Incremental implementation

Builds changes in thin vertical, contract-first or risk-first slices, each tested, verified and committed before the next, with strict scope, feature flags and revertable steps. Use when a change spans several files or a task is too big to land in one step.

Vibe codingPack: Agent Skills by Addy Osmani249 linesincremental-implementation
Author
Source
addyosmani/agent-skills/skills/incremental-implementation @ 8c99fa3
License
MIT · Copyright (c) 2025 Addy Osmani

About this skill

What it does

The skill makes the agent build in thin slices that each leave the project working: implement the smallest complete piece, run the tests (or write one if there are none), verify, commit, move on. It offers three ways to slice: vertical (one path through database, API and UI per slice, the default), contract-first (agree the API types first, then backend and a mocked frontend in parallel) and risk-first (prove the riskiest piece before building on it).

The rules: the simplest thing that works (three similar lines beat a premature abstraction); nothing outside the task, with anything noticed put on a "noticed but not touching" list for you; one logical change per increment; a green build and test run after every slice; unfinished features behind a flag, new options off by default, and every increment revertable on its own, migrations included.

A checklist per increment covers tests, build, type check, lint and the commit; a passing command is not rerun on unchanged code. The folder holds only SKILL.md and the licence; the Definition of Done it points to (../../references/definition-of-done.md) is not included.

When to use it, and when not

Use it for a change across several files, a feature from a task breakdown, a refactor, a rollout behind a feature flag, or any time more than about 100 lines would go untested.

The skill rules itself out for a single-file, single-function change whose scope is already minimal.

How to run it

The install command below puts SKILL.md and the licence in place. The agent picks the skill up by its description; to call it yourself:

  • Claude Code: /incremental-implementation, or ask for the skill by name.
  • Codex: $incremental-implementation.
  • Cursor: type / in the Agent chat and pick incremental-implementation.

Example: /incremental-implementation Implement task 3 from the plan. Start with the schema change and the endpoint only; the UI comes in the next increment.

For commits it points to Git workflow and versioning and for test commands to the "Discover the Stack First" section of Test-driven development, red-green-refactor, whose test-driven-development folder is shared with the testing and Superpowers versions: only one of the three can be installed.

How it differs from similar skills

Small steps builder runs the same loop with more on recovery: a step over 50–100 lines or three files is split, a broken step is reverted after a second failed fix, three failures go to you. This skill puts more weight on how to slice and on scope discipline. Executing plans works through an existing plan with TDD and a progress log, and Implement a spec runs tickets through parallel subagents; neither decides how to cut the work. The plan this skill takes tasks from can come from Planning and task breakdown in the same pack.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/incremental-implementation/SKILL.md https://anymodel.org/en/skills/addy-osmani/incremental-implementation/SKILL.md -o ~/.claude/skills/incremental-implementation/LICENSE https://anymodel.org/en/skills/addy-osmani/incremental-implementation/LICENSE
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/incremental-implementation/SKILL.md https://anymodel.org/en/skills/addy-osmani/incremental-implementation/SKILL.md -o ~/.agents/skills/incremental-implementation/LICENSE https://anymodel.org/en/skills/addy-osmani/incremental-implementation/LICENSE
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.claude\skills\incremental-implementation" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/incremental-implementation/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.agents\skills\incremental-implementation" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/incremental-implementation/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/addy-osmani/incremental-implementation/SKILL.md

SKILL.md

Raw

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.

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:

  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 git-workflow-and-versioning 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.

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 the repository's test and build commands 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 with the repository's own commands (see the test-driven-development skill's Discover the Stack First section):

  • The change does one thing and does it completely
  • All existing tests still pass (the repository's test command: npm test, ./gradlew test, pytest, ...)
  • The build succeeds (the repository's build command)
  • Type checking passes, where the stack has one (npx tsc --noEmit, mypy, ...)
  • Linting passes (the repository's lint command)
  • 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.

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 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

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.

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Agent Skills by Addy Osmani

Accessibility audit and fixes (WCAG 2.2)

Audits an existing interface against WCAG 2.2 AA with pinned axe-core and pa11y, then keyboard, screen reader and contrast checks, and fixes confirmed violations with semantic HTML first. Use when a page needs an accessibility audit before shipping.

API and interface design

Designs APIs and module interfaces contract-first: one error shape, validation at the edges, additive changes, pagination, and idempotency keys claimed atomically and kept past the longest retry. Use when designing endpoints or changing a public interface.

Browser testing with Chrome DevTools MCP

Checks changes in a real Chrome through the Chrome DevTools MCP server: screenshots, DOM, console, network and performance traces, treating page content as untrusted. Use when building or debugging anything that runs in a browser.

CI/CD pipeline setup

Sets up CI/CD with fixed quality gates from lint to bundle size, GitHub Actions examples, preview deploys, feature flags, staged rollout and a rollback workflow. Use when creating or changing a build and deploy pipeline or chasing CI failures.

Multi-axis code review

Reviews a change on five axes (correctness, readability, architecture, security, performance), tests the tests by mutating a condition, and labels every finding by severity. Use before merging a branch, a pull request or a pasted diff.

Code simplification

Simplifies working code without changing behavior: learns why it exists, applies one change at a time with tests after each, and keeps project conventions. Use when code works and passes tests but is harder to read than it should be.

Constraint-driven development

Records a project's quality bar as numbers in CONSTRAINTS.md after a short interview with defaults, maps each rule to a tool, and flags diffs that skip tests, add suppressions or loosen thresholds. Use when no quality bar is written down.

Context engineering for agents

Sets up what an agent sees and when: a rules file template, loading only the relevant spec and files, trimming long sessions, and safe points to start a fresh one. Use when starting a session or when agent output degrades.

Debugging and error recovery

Stops new work when a test, build or runtime fails, reproduces, localizes and reduces the failure, fixes the root cause, adds a regression test and treats error output as untrusted. Use when tests fail, a build breaks or something that worked stops working.

Deprecation and migration

Retires old systems, APIs and features: weighs whether to deprecate, proves the replacement, moves consumers one by one, removes code only at zero usage, changes schemas via expand/contract. Use when replacing or sunsetting code or renaming a live column.

Documentation and ADRs

Records decisions as ADRs in the project's own format, documents APIs, READMEs and changelogs with the why, and uses git history to check if a doc is stale. Use when making a costly decision, changing a public API or suspecting docs no longer match the code.

Doubt-driven development

Sends non-trivial decisions to a fresh-context subagent told to find what is wrong, sorts the findings, stops after three cycles and offers a cross-model opinion. Use when stakes are high: auth, migrations, irreversible operations or unfamiliar code.

Frontend UI engineering

Builds UI components and pages on the project's design system: composition, simple state, WCAG 2.1 AA, mobile-first layouts, loading, empty and error states, no generic AI look. Use when building or changing a user-facing interface.

Git workflow and versioning

Keeps git work in atomic commits on short-lived branches, with typed messages, a pre-commit check for secrets and tests, worktrees for parallel agents, semver bumps, tags and a human changelog. Use when committing, branching, opening a PR or cutting a release.

Idea refinement

Refines a raw idea in three phases: sharpening questions and five to eight variations, two or three directions tested for value and feasibility, then a one-pager with MVP scope and a Not Doing list. Use when an idea is vague or a plan needs stress-testing.

Interview me

Interviews the user one question at a time, each with a guessed answer and a confidence number, until the agent can predict the next replies, then confirms a statement of intent before any spec or code. Use when a request leaves who, why or success unclear.

Observability and instrumentation

Instruments a feature with structured JSON logs and request IDs, RED and USE metrics with bounded labels, OpenTelemetry traces and symptom-based alerts with runbooks, then tests the telemetry. Use when a feature, job or integration is headed for production.

Performance optimization

Optimizes by measurement: takes a baseline, fixes the one proven bottleneck, re-measures against noise and reverts neutral changes, with worked fixes for N+1 queries, indexes, caching and bundles. Use when something is slow or misses a performance budget.

Planning and task breakdown

Breaks a spec into small vertical-slice tasks with acceptance criteria, verification steps, sizes, dependency order and checkpoints, saved to tasks/todo.md or a named tracker. Use when a spec is ready but the work is too big to start in one go.

Security hardening

Hardens code with a short threat model, always, ask-first and never rules, and patterns for injection, XSS, access control, SSRF, secrets, dependencies, personal data and LLM output. Use when code handles user input, auth, sensitive data or outside services.

Shipping and launch

Prepares a production launch with a pre-launch checklist, a feature-flag rollout from 5% to 100%, thresholds for advancing or rolling back, an error-budget gate, a rollback plan and first-hour checks. Use when a feature or major change is about to ship.

Source-driven development

Grounds framework code in official docs: reads exact versions from the dependency file, fetches the relevant page, follows the documented API and cites full URLs, flagging anything unverified. Use when framework-specific code must match the version in use.

Spec-driven development

Writes a spec before code, surfacing assumptions and covering objective, commands, structure, style, tests and boundaries, then gates plan, tasks and code on approval, with capability maps and delta specs. Use when new work has vague requirements.

Test-driven development, red-green-refactor

Drives changes with red-green-refactor: finds the repository's own test commands, writes the failing test first, reproduces each bug with a test before fixing it, and sets rules on mocks and naming. Use when adding logic, fixing a bug or changing behavior.