Incremental Implementation

Incremental Implementation

Purpose

Stage: Implement (agent — per slice, inside a worktree). THE implementer workhorse. It applies test-driven-development as its rigid core loop and source-driven-development as a referenced discipline; the worktree isolation mechanism is owned by the orchestrator — implement runs in the worktree it is handed, it does not make its own.

Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable.

When to use / when to skip

• Implementing any multi-file change
• Building a new feature from a task breakdown
• Refactoring existing code
• Any time you're tempted to write more than ~100 lines before testing

When NOT to use: Single-file, single-function changes where the scope is already minimal.

Inputs

Implement runs per slice, inside the worktree the orchestrator hands it (it does not create its own isolation; that is worktree, owned upstream). It consumes the Plan-stage contract cold and refuses to run if a load-bearing input is missing.

| Input | Source (skill) | Stable sections it reads | Refuse-to-run if absent | |---|---|---|---| | plan.md + slices | plan-breakdown | the assigned slice's row keyed by Slice id — its Story-ref · Files (owned) · Regression surface · Checkpoint · Blocked-by columns — plus the line-level steps and exact tests in the plan body | no plan.md, or no concrete steps for the assigned slice | | assigned slice id | STATE.md (orchestrator) | the PRD-namespaced slice row in state impl, gate agent | no slice assigned, or it is not in impl/agent | | acceptance.md | acceptance-criteria (Spec, signed) | the behavioral Given/When/Then scenario ids (e.g. PWR-A2) this slice realizes — the frozen oracle test-driven-development turns RED | the slice references an acceptance id that does not exist | | clean worktree | worktree (orchestrator) | a provisioned, preflight-green baseline branch for this slice | not running inside the handed worktree |

Disciplines it applies (consulted, not stages it consumes): test-driven-development (RED-GREEN-REFACTOR; test-first order is hook-enforced), source-driven-development (ground any framework/library decision in fetched official docs, as needed), debugging-and-error-recovery (five-step triage when a slice's tests break). It does not re-derive the plan, re-open the spec, or re-slice — the plan handed to it is already vertical.

The Increment Cycle

┌──────────────────────────────────────┐
│                                      │
│   Implement ──→ Test ──→ Verify ──┐  │
│       ▲                           │  │
│       └───── Commit ◄─────────────┘  │
│              │                       │
│              ▼                       │
│          Next slice                  │
│                                      │
└──────────────────────────────────────┘

For each slice:

1. Implement the smallest complete piece of functionality
2. Test — run the test suite (or write a test if none exists)
3. Verify — confirm the slice works as expected (tests pass, build succeeds, manual check)
4. Commit -- save your progress with a descriptive message (see the git-workflow skill for atomic commit guidance)
5. Move to the next slice — carry forward, don't restart

Slicing Strategies

Vertical Slices (Preferred)

Build one complete path through the stack:

Slice 1: Create a task (DB + API + basic UI)
    → Tests pass, user can create a task via the UI

Slice 2: List tasks (query + API + UI)
    → Tests pass, user can see their tasks

Slice 3: Edit a task (update + API + UI)
    → Tests pass, user can modify tasks

Slice 4: Delete a task (delete + API + UI + confirmation)
    → Tests pass, full CRUD complete

Each slice delivers working end-to-end functionality.

Skeleton-First (stub → mock → wire → fill)

Within a vertical slice, build the skeleton end-to-end first, then fill it in — absorbed from cr-structure's build-order. Each step is independently observable:

• Stub — every layer the slice touches returns a hardcoded value; the end-to-end path already runs.
• Mock — swap stubs for mocks at the real boundaries; the shape of the data flows through.
• Wire — replace mocks with the real calls, one boundary at a time.
• Fill — handle the edge cases and error paths.

This is the antidote to horizontal building (all DB, then all API, then all UI), which yields code that does not work end-to-end until the last step and gives you nothing to debug from in between. The plan you were handed is already sliced vertically; skeleton-first is how you build each slice without silently re-horizontalizing it. The Increment Cycle's "Verify" step is the slice's checkpoint — a specific observable fact ("submitting the form shows the inline error"), never "it compiles".

Contract-First Slicing

When backend and frontend need to develop in parallel:

Slice 0: Define the API contract (types, interfaces, OpenAPI spec)
Slice 1a: Implement backend against the contract + API tests
Slice 1b: Implement frontend against mock data matching the contract
Slice 2: Integrate and test end-to-end

Risk-First Slicing

Tackle the riskiest or most uncertain piece first:

Slice 1: Prove the WebSocket connection works (highest risk)
Slice 2: Build real-time task updates on the proven connection
Slice 3: Add offline support and reconnection

If Slice 1 fails, you discover it before investing in Slices 2 and 3.

Implementation Rules

Rule 0: Simplicity First

Before writing any code, ask: "What is the simplest thing that could work?"

After writing code, review it against these checks:

• Can this be done in fewer lines?
• Are these abstractions earning their complexity?
• Would a staff engineer look at this and say "why didn't you just..."?
• Am I building for hypothetical future requirements, or the current task?

SIMPLICITY CHECK:
✗ Generic EventBus with middleware pipeline for one notification
✓ Simple function call

✗ Abstract factory pattern for two similar components
✓ Two straightforward components with shared utilities

✗ Config-driven form builder for three forms
✓ Three form components

Three similar lines of code is better than a premature abstraction. Implement the naive, obviously-correct version first. Optimize only after correctness is proven with tests.

Rule 0.5: Scope Discipline

Touch only what the task requires.

Do NOT:

• "Clean up" code adjacent to your change
• Refactor imports in files you're not modifying
• Remove comments you don't fully understand
• Add features not in the spec because they "seem useful"
• Modernize syntax in files you're only reading

If you notice something worth improving outside your task scope, note it — don't fix it:

NOTICED BUT NOT TOUCHING:
- src/utils/format.ts has an unused import (unrelated to this task)
- The auth middleware could use better error messages (separate task)
→ Want me to create tasks for these?

Rule 1: One Thing at a Time

Each increment changes one logical thing. Don't mix concerns:

Bad: One commit that adds a new component, refactors an existing one, and updates the build config.

Good: Three separate commits — one for each change.

Rule 2: Keep It Compilable

After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices.

Rule 3: Feature Flags for Incomplete Features

If a feature isn't ready for users but you need to merge increments:

// Feature flag for work-in-progress
const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';

if (ENABLE_TASK_SHARING) {
  // New sharing UI
}

This lets you merge small increments to the main branch without exposing incomplete work.

Rule 4: Safe Defaults

New code should default to safe, conservative behavior:

// Safe: disabled by default, opt-in
export function createTask(data: TaskInput, options?: { notify?: boolean }) {
  const shouldNotify = options?.notify ?? false;
  // ...
}

Rule 5: Rollback-Friendly

Each increment should be independently revertable:

• Additive changes (new files, new functions) are easy to revert
• Modifications to existing code should be minimal and focused
• Database migrations should have corresponding rollback migrations
• Avoid deleting something in one commit and replacing it in the same commit — separate them

Working with Agents

When directing an agent to implement incrementally:

"Let's implement Task 3 from the plan.

Start with just the database schema change and the API endpoint.
Don't touch the UI yet — we'll do that in the next increment.

After implementing, run `npm test` and `npm run build` to verify
nothing is broken."

Be explicit about what's in scope and what's NOT in scope for each increment.

Increment Checklist

After each increment, verify:

• [ ] The change does one thing and does it completely
• [ ] All existing tests still pass (npm test)
• [ ] The build succeeds (npm run build)
• [ ] Type checking passes (npx tsc --noEmit)
• [ ] Linting passes (npm run lint)
• [ ] The new functionality works as expected
• [ ] The change is committed with a descriptive message

Note: Run each verification command after a change that could affect it. After a successful run, don't repeat the same command unless the code has changed since — re-running on unchanged code adds no information.

Rationalizations

| Rationalization | Reality | |---|---| | "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. | | "It's faster to do it all at once" | It feels faster until something breaks and you can't find which of 500 changed lines caused it. | | "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. | | "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. | | "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. | | "Let me run the build command again just to be sure" | After a successful run, repeating the same command adds nothing unless the code has changed since. Run it again after subsequent edits, not as reassurance. |

Red flags

• More than 100 lines of code written without running tests
• Multiple unrelated changes in a single increment
• "Let me just quickly add this too" scope expansion
• Skipping the test/verify step to move faster
• Build or tests broken between increments
• Large uncommitted changes accumulating
• Building abstractions before the third use case demands it
• Touching files outside the task scope "while I'm here"
• Creating new utility files for one-time operations
• Running the same build/test command twice in a row without any intervening code change

Verification (ending criteria)

After completing all increments for a task:

• [ ] Each increment was individually tested and committed
• [ ] The full test suite passes
• [ ] The build is clean
• [ ] The feature works end-to-end as specified
• [ ] No uncommitted changes remain

See Also

Per-increment verification is the local check. Before declaring a task done, apply the project-wide Definition of Done as the final gate, the standing bar every increment clears regardless of the task. See ../../references/definition-of-done.md.

Outputs & handoff contract

• Emits: a diff on the slice's worktree branch — the implemented slice as a sequence of atomic,

individually-tested commits (code + the tests that prove it). This is the artifact quality-verification (Verify) consumes cold, alongside the running app and acceptance.md.

• Stable guarantees the consumer depends on:
• The diff stays inside the slice's declared Regression surface (from plan.md). Narrowing or

widening that surface to pass is a gate-erosion HALT, not a fix.

• Tests land test-first (the test-driven-development order hook enforces it) and assert observable behavior, never

mock calls (testing-strategy AP1).

• The worktree is compilable and green at every increment checkpoint — never left broken between slices.
• The slice diff stays within the ≤400 LOC cluster cap; if it cannot, the

slice was mis-sliced — stop and surface, do not stretch the cap.

• Frozen-under-retry (silent-false-green defense — non-negotiable): during this slice's bounded retry

rounds, acceptance.md, the RED tests, and the declared Regression surface are immutable. A retry diff that weakens an assertion, deletes a test, or narrows the surface = HALT (gate-erosion + reward-hack tripwire: the failure signature must not move only because a test/acceptance was edited while impl is materially unchanged). The way to green is to fix the impl (via debugging-and-error-recovery), never to move the goalposts. No --no-verify, no hook edits, no SKIP_HOOKS (security.md / CLAUDE.md).

• STATE.md update: on a green slice checkpoint, flip the slice impl → verify (gate stays agent)

and hand off to quality-verification. If the slice cannot pass after the bounded rounds (3 implement→verify→review cycles), flip it impl → halted and flip its gate agent → you — the failure-escalation path is the only place a human gate survives the autonomous run.

• Consumer: quality-verification (Verify). Change the shape of what you emit → update quality-verification in the same commit.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: celestialdust
• Source: celestialdust/achilles-skills
• License: MIT

Install and usage instructions live in the source repository linked above.