| name | incremental-implementation |
| description | Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use when you're about to write a large amount of code at once, or when a task feels too big to land in one step. |
Incremental Implementation
Overview
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.
Development Discipline
- Think before coding: state assumptions, ambiguity, tradeoffs, and stop points
before editing.
- Keep it simple: retain only rules, abstractions, and artifacts that change the
execution result; reduce duplicated wording and speculative structure.
- Edit precisely: change the canonical source for the behavior; do not
hand-edit generated adapters or copied outputs unless that source owns them.
- Make goals verifiable: turn instructions into success criteria, gates, proof
commands, or explicit blocker records.
When to Use
- 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.
The Increment Cycle
┌──────────────────────────────────────┐
│ │
│ Implement ──→ Test ──→ Verify ──┐ │
│ ▲ │ │
│ └───── Commit ◄─────────────┘ │
│ │ │
│ ▼ │
│ Next slice │
│ │
└──────────────────────────────────────┘
For each slice:
- Implement the smallest complete piece of functionality
- Test — run the test suite (or write a test if none exists)
- Verify — confirm the slice works as expected (tests pass, build succeeds, manual check)
- Commit or checkpoint -- when inside a git repo and the user/workspace has authorized commits, save progress with a descriptive commit. Otherwise, record a checkpoint in
<project-name>/.dev-agent/tasks/status.md with changed files and verification evidence.
- Record evidence -- update
.dev-agent/tasks/status.md and
.dev-agent/reviews/VERIFICATION.md or .dev-agent/reviews/BLOCKED_BUILD.md
with changed areas, commands, and blockers.
- Move to the next slice — carry forward, don't restart
Use the project-local workspace layout for all implementation work:
- Read tasks from
<project-name>/.dev-agent/tasks/
- Edit app/source files under the project root, such as
<project-name>/src/,
<project-name>/app/, <project-name>/apps/, or <project-name>/packages/
- Run commands from the project root or stack-local source directory, for
example
<project-name> or <project-name>/apps/mobile
- Do not create project-specific source directories outside the project folder
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.
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 -2: Build Micro-Plan
Before coding, write a compact slice note in the working response,
.dev-agent/tasks/status.md, or .dev-agent/tasks/PLAN.md only when the slice
is too large to hold in the spec/status. Include the goal, target files, source
boundary, proof command, and blocker/escalation path. This replaces a separate
planning phase.
For behavior changes, prefer a failing test or executable proof first. If that
is not practical, record why and use the smallest manual or smoke proof that
can catch the intended behavior.
Rule -1: Escalate Instead Of Forcing
Before coding, check whether the requirement, spec, design resources,
environment, and risk boundary are clear enough for the current slice.
Return the issue to its owner instead of hard-working around it:
- unclear user value or acceptance criteria -> idea/spec
- missing or weak UI design input -> design
- unavailable SDK/permission/service -> host requirements or user decision
- reproduced failure with unknown cause -> debugging-and-error-recovery
- security/payment/permission/data deletion risk -> security-and-hardening or user decision
If no flow can resolve it, record the blocker in
.dev-agent/reviews/BLOCKED_BUILD.md and ask the user for the decision.
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.
If commits are not appropriate in the current environment, use the same atomicity for checkpoints: one status entry per logical change, with files touched and verification output.
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:
const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';
if (ENABLE_TASK_SHARING) {
}
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:
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:
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.
Common 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 or checkpoint separately" | Small commits/checkpoints are cheap. Large untracked batches 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
- No checkpoint record in a non-git or no-commit environment
- 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
After completing all increments for a task:
