# Incremental Implementation > Use when .forge/tasks.yaml exists and implementation is starting, when executing a planned task list one task at a time, when a feature must ship in independently-verifiable slices, or when contracts in .forge/contracts/ need to be implemented against acceptance criteria. - Skill: `aneja5/incremental-implementation` (Agent Skill) - Install (CLI): `npx skillmds@latest add aneja5/incremental-implementation` - Raw SKILL.md: https://api.skillmd.com/api/skills/aneja5/incremental-implementation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: aneja5 (https://skillmd.com/u/aneja5) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/aneja5/incremental-implementation --- # Incremental Implementation ## Overview Pick the next ready task from `.forge/tasks.yaml`, load its contracts from `.forge/contracts/`, implement using `tdd` discipline (red-green-refactor), verify against acceptance criteria, commit, and mark done. Repeat until all tasks are complete. ## When to Use - `.forge/tasks.yaml` exists with at least one unstarted task - Dependencies for the next task are complete - Ready to write code (not planning, not designing) ## When NOT to Use - No task plan exists — run `planning-and-task-breakdown` first - Architecture is unclear — run `architecture-and-contracts` first - Task is XL and not decomposed — spike first, then plan ## Common Rationalizations | Thought | Reality | |---------|---------| | "I'll implement a few tasks together to go faster" | Mixing tasks blurs acceptance criteria and commit history | | "I don't need to read the contract — I know the interface" | Contracts encode invariants and error types you'll miss | | "I'll write tests after the implementation is working" | Then you're testing implementation, not behavior | | "This small extra thing is obviously correct to add" | Scope creep is always "obviously correct" in the moment | | "I'll commit everything at the end" | Atomic commits per task make revert and review tractable | ## Red Flags - Implementing a task that has unsatisfied dependencies in `tasks.yaml` - Writing code that touches modules not listed in the task's `files_likely_affected` - Skipping the contract read — implementing to an assumed interface - Committing with a message that doesn't reference the task ID - Acceptance criteria not verifiable after implementation - Task marked done before verification step passes - `.forge/tasks.yaml` not updated mid-flight when a task is split or blocked (the plan diverges silently) - Editing `.forge/contracts/.md` inline when build reveals the contract is wrong (file `/feedback` instead) - Skipping `skills:` tag reads — implementing UI without loading `design-system`, writing migrations without loading `database-design` ## Core Process ### Step 1: Select the next task Read `.forge/tasks.yaml`. Find all tasks where `status: pending` (or unset) AND every task in `depends_on` has `status: done`. Pick the highest-priority unblocked task (or ask the user if multiple are ready). Immediately mark the selected task in place: - `status: in_progress` - `started_at: ` Write the file back. The mutation is per-task — do not rewrite the whole `tasks.yaml`. Re-emit only the `forge:meta` `generated_at`/`content_hash` if the file as a whole was touched (status flips count); the `depends_on` set does not change. ### Step 2: Load context Read the task's acceptance criteria and verification steps. Read each contract listed in the task's `contracts` field from `.forge/contracts/`. Load only the `files_likely_affected` — don't read the whole codebase. **Skill-tagged context load (#41):** if the task has a `skills:` field (e.g., `[design-system, accessibility, api-design]`), read `skills//SKILL.md` BEFORE writing the first test. These tags exist precisely because the task touches a domain whose rules are encoded in another skill. Skipping them means the implementation will recreate problems those skills exist to prevent. If `.forge/testing-strategy.md` exists, also read it — per-module coverage decisions there override TDD defaults. ### Step 3: Implement with TDD Follow the `tdd` skill. For this task's acceptance criteria: ``` RED: Write a failing test for the first acceptance criterion GREEN: Write minimum code to make it pass REPEAT for each acceptance criterion REFACTOR: Clean up while keeping all tests green ``` Stay within the task's scope. Do not add features not in the acceptance criteria. Do not touch files outside `files_likely_affected` without explicit reason. ### Step 4: Verify Run the verification steps listed in the task. All must pass: - Unit tests green - Integration tests green (if listed) - Manual verification step confirmed (if listed) ### Step 5: Commit ``` git add git commit -m "[T001] - Implements: - Implements: - Tests: " ``` ### Step 6: Mark done Update `.forge/tasks.yaml` in place: - `status: done` - `completed_at: ` - `commit: ` Check if any tasks whose `depends_on` is now fully satisfied. Report progress to user. ### Step 7: Mid-task discoveries — split, block, or feedback If during Steps 2-4 you discovered the task can't complete as-scoped, do NOT silently continue. Update `.forge/tasks.yaml` and (if upstream is wrong) file a feedback entry: - **Scope creep discovered** → split the task. Mark the original `status: split`. Append new task IDs into the `notes` array describing the split. Add new task entries for the carved-out work. Do not implement the carved-out work in this run. - **Unmet dependency surfaced** → set `status: blocked`. Append the blocker to `notes`. Stop work on this task. Pick the next ready task. - **The CONTRACT is wrong** (refund endpoint missing, wrong type, missing error case) → run `/feedback` to file `.forge/feedback/-build.md` targeting the broken contract. Do NOT edit the contract inline. Mark the task `status: blocked` with `notes` referencing the feedback entry path. The contract update happens via `/architect` re-run. - **The TEST STRATEGY contradicts what you need to write** → file `/feedback` targeting `.forge/testing-strategy.md`. Continue per the strategy's current text for now. After ≥3 such events in a sprint, `forge-sync` will flag `TASKS_DIVERGED` — at that point, run `/plan` to re-baseline before picking the next task. ## Verification Before marking any task done: - [ ] Task started: `status: in_progress` + `started_at` set when work began - [ ] All `skills:` tags read (if any listed) BEFORE first test was written - [ ] `.forge/testing-strategy.md` consulted if it exists - [ ] All acceptance criteria in tasks.yaml satisfied - [ ] All verification steps in tasks.yaml passed - [ ] No files touched outside the task's scope (or explicitly justified) - [ ] Contract invariants not violated (check against `.forge/contracts/`) - [ ] Tests verify behavior through public interface, not implementation details - [ ] Commit message references task ID - [ ] `.forge/tasks.yaml` updated: `status: done`, `completed_at`, `commit` (short sha) - [ ] If mid-flight discoveries occurred: split tasks were added, OR a feedback entry was filed, OR the task was marked blocked with a reason — never silently absorbed