The Spec-Driven AI-Assisted Development Starter Kit

A Starting Point, Not Another Framework

The previous articles built the method one problem at a time.

This starter kit turns that method into files and commands that can live inside a real project.

It includes templates for requirements.md, design.md, and tasks.md, a project instruction file for agent behavior, and three workflow commands:

/add-spec
/update-spec
/implement-spec

The goal is not to introduce another framework. The goal is to provide a practical starting point that readers can copy, inspect, and change.

The files are intentionally small. They define where decisions belong, how one slice moves into implementation, which checks control completion, and what must be written back when the work changes.

They will not fit every team without modification.

A useful starter kit should make its assumptions visible enough to adapt, not hide them behind automation.

The Kit Structure

I would keep the starter kit close to the code and separate each feature into its own spec folder.

project/
├── AGENTS.md
├── CLAUDE.md
├── specs/
│   └── training-request/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
└── commands/
    ├── add-spec.md
    ├── update-spec.md
    └── implement-spec.md

AGENTS.md defines the project behavior for agents that support it. Claude Code users can place the same contract in CLAUDE.md.

A project does not need to maintain both files unless it uses both instruction systems. If both are present, their shared rules should stay aligned instead of becoming two different workflows.

Each folder under specs/ holds the decisions and progress for one feature or implementation slice. This prevents one large specification from becoming the context for every change.

The files under commands/ define the three workflow contracts. Their installation path will depend on the agent tool, but their responsibilities should stay the same.

The directory names can change. The separation between project behavior, feature decisions, and workflow commands is the important part.

For the examples that follow, I will use the same training-request slice from the previous articles.

requirements.md: Define the Expected Behavior

requirements.md describes what the slice should achieve and which product boundaries it must respect.

# <Feature or Slice Name>

## Status

Draft | Approved | Implementing | Verified

## Outcome

<What should be true for the user or business when this slice is complete?>

## Users

- <User or role involved>
- <Another user or role, if needed>

## In Scope

- <Behavior included in this slice>
- <Another included behavior>

## Out of Scope

- <Related behavior intentionally postponed>
- <Shortcut or limitation accepted for this slice>

## Business Rules

- <Rule the implementation must enforce>
- <Permission, state, ownership, or validation rule>

## Acceptance Criteria

- Given <starting condition>, when <action happens>, then <observable result>.
- Given <another condition>, when <action happens>, then <observable result>.

## Open Questions

- <Decision that must be resolved before implementation>

The outcome should describe a result, not a component to build.

The scope keeps related work from entering the slice silently. Business rules capture behavior the agent must not infer from the UI or existing code.

Acceptance criteria define the proof expected before the slice can close. If an open question can change the implementation, it should be resolved before the status moves to Approved.

Implementation can begin when the expected behavior is clear enough to challenge the code.

design.md: Record the Technical Decisions

design.md explains how the slice fits the existing system and which technical consequences the engineer has accepted.

# <Feature or Slice Name> Design

## Context

<Relevant existing behavior, architecture, or constraint>

## Proposed Approach

<How the slice will be implemented at a high level>

## Components Affected

- <Service, module, page, API, or integration>
- <Another affected component>

## Data and Access Boundaries

- <Who can read or change the data?>
- <Ownership, permission, validation, or storage boundary>

## Interfaces

- <API, event, command, or external contract that changes>
- <Compatibility requirement that must remain true>

## Decisions and Tradeoffs

### <Decision>

- Choice: <What was selected?>
- Reason: <Why does it fit this slice?>
- Consequence: <What limitation or future cost was accepted?>

## Risks

- <Technical or operational risk>
- <How the risk will be reduced or detected>

## Open Questions

- <Technical decision that must be resolved before implementation>

This file should not repeat the expected behavior from requirements.md.

Its job is to expose the technical choices that would otherwise appear silently in the implementation.

A decision is incomplete if it records only what was chosen. The reason and consequence make the tradeoff reviewable later.

The design does not need to predict every implementation detail. It needs to make the decisions with lasting consequences visible.

tasks.md: Control the Active Slice

tasks.md turns the approved requirements and design into a small implementation path.

# <Feature or Slice Name> Tasks

## Status

Not Started | In Progress | Blocked | Verified

## Active Slice

<The working behavior this task file is expected to deliver>

## Implementation Boundary

Included:

- <Work allowed in this slice>
- <Another allowed change>

Excluded:

- <Related work that must remain separate>

## Tasks

- [ ] <First implementation step>
  - Purpose: <Why this step is needed>
  - Proof: <Check that shows this step works>

- [ ] <Next implementation step>
  - Purpose: <Why this step is needed>
  - Proof: <Check that shows this step works>

## Verification Gate

- [ ] Acceptance criteria pass
- [ ] Relevant automated tests pass
- [ ] Build and type checks pass
- [ ] Required manual scenario passes
- [ ] New decisions are written back
- [ ] Deferred work is recorded

## Blocked Decisions

- <Decision that must be resolved before work continues>

## Progress Log

### <Date or session>

- Completed: <What changed>
- Remaining: <What is still open>
- Failed checks: <Failure that still blocks completion>
- Spec updates: <Requirements or design decisions written back>

This is not the backlog for the whole feature.

It records the active slice, the proof attached to its steps, and the state needed to resume the work safely.

The verification gate prevents completed code from being confused with completed behavior. A blocked decision stays visible instead of being replaced by an assumption.

The task file should tell the next agent what it can continue, what it must verify, and what is not allowed to move yet.

AGENTS.md or CLAUDE.md: Define the Project Contract

The project instruction file tells the agent how to use the spec files while it works.

The same core contract can be placed in AGENTS.md, CLAUDE.md, or adapted to the instruction file supported by another tool.

# Project Instructions

## Source of Truth

Before implementation, read the relevant files under `specs/<feature>/`:

- `requirements.md` defines expected behavior and product boundaries.
- `design.md` defines technical decisions and tradeoffs.
- `tasks.md` defines the active implementation slice and verification state.

Do not replace an explicit project decision with an assumption.

## Implementation Workflow

1. Confirm that the requirements and design have no blocking open questions.
2. Work only from the active slice in `tasks.md`.
3. Keep changes inside its implementation boundary.
4. Run the proof attached to each task before marking it complete.
5. Run the full verification gate before calling the slice complete.
6. Write progress and new decisions back to the spec files.

## Stop Conditions

Stop implementation and report the issue when:

- The requested change expands the approved scope.
- A missing business rule or design decision affects the implementation.
- The code, acceptance criteria, and existing system disagree.
- A required check fails and cannot be fixed inside the approved slice.
- Another task or agent is changing the same ownership area.

Do not continue by silently choosing a new product or architecture decision.

## Write-Back Rules

Update:

- `requirements.md` when expected behavior, scope, or a business rule changes.
- `design.md` when a technical decision or tradeoff changes.
- `tasks.md` when progress, verification state, or deferred work changes.

Keep decisions in the project files, not only in the conversation.

## Project Checks

Use the commands defined by this project:

- Tests: `<test command>`
- Build: `<build command>`
- Type check: `<type-check command>`
- Lint: `<lint command>`
- Manual or browser verification: `<verification instructions>`

Do not mark the slice `Verified` while a required check is failing.

This contract does not tell the agent how to write every line of code.

It defines the conditions around implementation: what to read, where it can work, when it must stop, which checks control completion, and what must survive the conversation.

If a project keeps both AGENTS.md and CLAUDE.md, I would generate them from the same shared contract or review them together when the workflow changes.

Tool-specific instructions can differ. The engineering rules should not.

/add-spec: Create the First Version of a Spec

/add-spec turns a feature request into the three spec files without starting implementation.

# /add-spec

## Purpose

Create an initial spec for one feature or implementation slice.

## Input

- Feature description: `$ARGUMENTS`
- Relevant existing code, documentation, and project instructions

## Plan Mode

For complex, ambiguous, or cross-cutting changes:

1. Enter Plan mode before running this command.
2. Inspect the existing system and produce a proposed spec.
3. Resolve blocking questions without creating or editing files.
4. Ask the engineer to approve the proposed scope and design.
5. Return to Default mode.
6. Run `/add-spec` with the approved plan as input.

Do not claim that spec files were created while still in Plan mode.

## Workflow

1. Read the project instruction file and related existing specs.
2. Inspect the current system where the feature will connect.
3. Identify the intended outcome, users, boundaries, business rules, and expected proof.
4. Identify technical constraints, affected components, interfaces, and tradeoffs.
5. Ask for decisions when missing information would materially change the product or design.
6. Create:

   - `specs/<feature>/requirements.md`
   - `specs/<feature>/design.md`
   - `specs/<feature>/tasks.md`

7. Keep the first task file limited to one executable slice.
8. Report unresolved questions and the files created.

## Restrictions

- Do not implement application code.
- Do not create migrations, tests, API behavior, or UI changes.
- Do not resolve consequential product or architecture decisions silently.
- Do not mark the spec `Approved` while blocking questions remain.

## Completion

The command is complete when the initial spec files exist, their assumptions are visible, and the next required decision is clear.

The command should inspect the existing project before proposing a design. A reusable template does not make the surrounding architecture optional.

Plan mode is useful when the feature needs investigation or important decisions. It prepares the proposal, but the files are created only after returning to Default mode.

The boundary is important: /add-spec prepares the work. It does not reward itself by starting the implementation early.

A spec command is useful when it makes missing decisions visible before they become code.

/update-spec: Change the Decision Before the Code

/update-spec updates an existing spec when implementation or review reveals new information.

# /update-spec

## Purpose

Update an existing spec while preserving the decisions that are still valid.

## Input

- Spec path or feature name: `$ARGUMENTS`
- New requirement, discovery, constraint, or decision
- Relevant current code and verification results

## Plan Mode

For updates with unclear product or technical consequences:

1. Enter Plan mode.
2. Read the current spec and inspect the affected system.
3. Identify which requirements, design decisions, tasks, and checks would change.
4. Compare the available options and their consequences.
5. Resolve blocking decisions with the engineer.
6. Produce an approved update proposal without editing files.
7. Return to Default mode.
8. Run `/update-spec` with the approved proposal as input.

Do not edit the spec or implementation while still in Plan mode.

## Workflow

1. Read the current `requirements.md`, `design.md`, and `tasks.md`.
2. Inspect the code or failed check that triggered the update.
3. Identify whether the change affects:

   - Expected behavior or scope
   - A business rule
   - A technical decision or tradeoff
   - The active implementation boundary
   - Acceptance criteria or verification

4. Explain the impact before editing the files.
5. Update only the sections affected by the decision.
6. Keep related requirements, design choices, tasks, and checks aligned.
7. Record deferred or invalidated work in `tasks.md`.
8. Report what changed and whether implementation can continue.

## Status Rules

Move the spec back to `Draft` or `Blocked` when the update introduces an unresolved decision.

Keep or restore `Approved` only when the changed behavior and design are clear enough to implement.

A slice cannot remain `Verified` if the update changes behavior its existing checks do not prove.

## Restrictions

- Do not implement the change.
- Do not rewrite unrelated parts of the spec.
- Do not remove a tradeoff or limitation without recording what replaced it.
- Do not change acceptance criteria only to make a failing implementation pass.
- Do not continue implementation when the updated spec contains a blocking question.

## Completion

The command is complete when the changed decision is visible, affected files agree, and the implementation state is accurate.

A spec update should be smaller than a spec rewrite.

Plan mode is useful when the update changes approved behavior, crosses several components, or invalidates an existing design decision. A factual correction or progress update does not need that extra stage.

The separation stays clear: Plan mode decides what the updated spec should say, /update-spec writes that decision into the files, and /implement-spec changes the code later.

Updating the spec is not correcting history. It is making the current decision explicit before more work depends on it.

/implement-spec: Execute One Approved Slice

/implement-spec changes the code only after the requirements, design, and active task are ready.

# /implement-spec

## Purpose

Implement and verify one approved slice from an existing spec.

## Input

- Spec path or feature name: `$ARGUMENTS`
- Approved `requirements.md`
- Approved `design.md`
- Active slice in `tasks.md`

## Preconditions

Before changing code, confirm that:

- The expected behavior and acceptance criteria are clear.
- No blocking product or technical questions remain.
- The active slice has an explicit implementation boundary.
- Each task has a defined proof.
- The required project checks are known.

If a precondition is missing, stop and route the work through `/update-spec`.

## Workflow

1. Read the project instruction file and all three spec files.
2. Inspect the relevant existing code before editing it.
3. Confirm the files and responsibilities owned by the active slice.
4. Mark the task status as `In Progress`.
5. Implement one task at a time.
6. Run its attached proof before marking it complete.
7. Record progress, failed checks, discoveries, and deferred work in `tasks.md`.
8. Use `/update-spec` when a discovery changes expected behavior, design, or scope.
9. Run the full verification gate.
10. Mark the slice `Verified` only when every required check passes.

## Stop Conditions

Stop implementation when:

- The work needs to expand beyond the approved boundary.
- A missing decision affects expected behavior or architecture.
- The implementation conflicts with the acceptance criteria or existing system.
- A required check fails for a reason outside the approved slice.
- Another task or agent owns the same files or responsibility.
- Continuing would require silently changing the spec.

## Parallel Work

Use sub-agents only when tasks can be separated by ownership, files, and proof.

The coordinating agent remains responsible for reconciling the results, running the complete verification gate, and writing back the final state.

## Restrictions

- Do not implement unapproved scope.
- Do not change acceptance criteria to fit the implementation.
- Do not hide failing checks or unresolved decisions.
- Do not mark a task complete without running its proof.
- Do not mark the slice `Verified` while required checks are failing.

## Completion

The command is complete when the approved behavior works, all required checks pass, and the spec files reflect the final state.

A separate Plan mode stage should not be the default here. The planning work already belongs in the approved spec and its active task.

If implementation exposes a decision that requires planning, the command should stop. The decision goes through /update-spec, then implementation resumes from the updated files.

/implement-spec is allowed to change the code. It is not allowed to change the agreement silently.

The Commands Form One Loop

The three commands are not independent shortcuts.

They control different transitions in the same workflow.

flowchart TD
    request["Feature request"] --> add["/add-spec"]
    add --> draft["Draft spec"]
    draft --> approval{"Spec approved?"}

    approval -->|"No: questions remain"| update["/update-spec"]
    approval -->|"Yes"| implement["/implement-spec"]

    implement --> discovery{"Decision missing or changed?"}
    discovery -->|"Yes"| update
    discovery -->|"No"| checks{"Verification gate passes?"}

    update --> draft

    checks -->|"No: implementation issue"| implement
    checks -->|"No: spec issue"| update
    checks -->|"Yes"| verified["Verified slice"]

    classDef input fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e,stroke-width:2px
    classDef command fill:#dbeafe,stroke:#2563eb,color:#1e3a8a,stroke-width:2px
    classDef state fill:#f8fafc,stroke:#64748b,color:#1e293b,stroke-width:2px
    classDef decision fill:#ffedd5,stroke:#f97316,color:#7c2d12,stroke-width:2px
    classDef success fill:#dcfce7,stroke:#16a34a,color:#14532d,stroke-width:2px

    class request input
    class add,update,implement command
    class draft state
    class approval,discovery,checks decision
    class verified success

/add-spec creates the first agreement.

/implement-spec works inside that agreement.

/update-spec changes it when new information makes the current version incomplete or wrong.

The important transition is not between commands. It is between states.

A draft spec cannot move into implementation while blocking questions remain. An implementation cannot move to verified while required checks fail. A changed decision cannot return to implementation until it is visible and approved.

The workflow moves forward only when the current state has earned the next one.

This keeps the commands small. Each one has a clear authority, and none of them needs to control the entire development process.

Adapt the Kit to the Project

The templates should not be copied without reading them.

Before using the kit, replace the generic parts with the rules the project already depends on:

• Add the real build, test, type-check, lint, and browser-verification commands.
• Match the spec location and command installation path to the tools in use.
• Define who can approve requirements, design changes, and expanded scope.
• Remove sections that do not support a real decision or verification step.

The project may also need stronger rules for database migrations, API compatibility, security review, deployment, or regulated data. Those belong in the project contract when they affect how the agent is allowed to work.

Start with one feature instead of moving every existing document into the structure.

Run the complete loop, notice where the agent still makes assumptions, and change the contract at that point.

The best version of this kit is not the most detailed one. It is the smallest version that makes the project's real boundaries enforceable.

Start With One Real Slice

The starter kit is ready when it can guide a real change, not when every template looks complete.

Choose one slice with a visible outcome, a few important boundaries, and checks that can prove the behavior.

Use /add-spec to create the first agreement. Let /implement-spec work inside it. When the existing system pushes back, use /update-spec instead of allowing the decision to disappear into the code or conversation.

Then inspect what happened.

Did the agent know when to stop? Did the checks control completion? Could another session resume from the project files without reconstructing the chat?

If the workflow preserves the decisions and exposes the failures, the kit is doing its job.

The complete starter kit is available in the Spec-Driven Development Skills and Templates repository. It contains the project templates, workflow commands, Codex skills, Claude Code adapters, and the training-request example used in this series.

This closes the foundation series.

The next problem is keeping Spec-Driven AI-Assisted Development useful when specs grow, projects change, and more people work inside the same system.