PT

Spec-DrivenGuide

The governance framework for developers and agents

Build with prefixes
$ npx spec-driven-guide

Run it in your terminal, inside your project folder. The agent reads the rules and follows them.

Start with a prefix

Start with a prefix

Instruct the agent the way you would write a commit message.

A loose ask

fix the login

The agent guesses the scope and starts typing. You find out what it decided by reviewing everything afterwards.

A hand-written spec

## Contract - Input, output, error codes - Acceptance criteria - Edge cases + 34 more lines

It works well. Detail helps, and the agent can write that detail with you.

A prefix

fix: login accepts an empty password

The agent writes the spec, stops for your approval, then plans, codes and tests inside the same cycle.

The agent proposes the SPEC from the context it already holds about the project. You align it together before any code. Where there is risk, spell out as much detail as you can.

5 Steps

5 Steps

What the agent runs for you after a single prefixed line.

1

1. SPEC

THE CONTRACT

Write down what you're building and why. No code until you reach an agreement.

2

2. PLAN

THE STRATEGY

Order the tasks and split the large ones into numbered subtasks anyone can follow.

3

3. CODE

THE EXECUTION

Follow the plan. Write what was agreed, nothing more.

4

4. TEST

THE VERIFICATION

Check that what was built matches what was agreed. Catch problems before they ship.

5

5. END

THE DELIVERY

Close the cycle: update the changelog, sync the backlog, and move on.

Agent Execution

Agent Execution

What your agent does, step by step, on each phase.

SPEC

THE CONTRACTMode: Planning
5 steps

PLAN

THE STRATEGYMode: Planning
8 steps

CODE

THE EXECUTIONMode: Fast
4 steps

TEST

THE VERIFICATIONMode: Fast
6 steps

END

THE DELIVERYMode: Planning
8 steps
Agent Commands

Agent Commands

Start the right workflow with a simple text prefix.

First contact

land: <your vision here>

Define your project's vision and scope before writing the first line.

Feature

feat: <describe the feature>

Walk through SPEC → PLAN → CODE → TEST → END for any new feature.

Bug fix

fix: <describe the problem>

Diagnose the root cause, fix it, and confirm nothing else broke.

Close the cycle

end: <optional instruction>

Summarize what was done, update the changelog, and commit.

Documentation

docs: <what to document>

Write ADRs, changelogs, and technical specs with the right template.

Audit

audit: <scope to audit>

Check whether the governance rules are applied to the project and get back a correction plan.

No agent in your editor yet?Browse the prompts

Harness Memory

Harness Memory

The files your agent reads before every cycle.

Core Context

Architecture & Decisions

Context, technology, and tactical decisions.

Learned Lessons

Accumulated Experience

What went wrong before, and the rule that came out of it.

Pending Actions

Next Steps

Current state, pending tasks, and delivery.

Resilience Log

Technical History

Root Cause Analysis (RCA) and failure history.

Impact Map

Blast-Radius Filter

Changed files, blast-radius imports, and tests at risk.

Common Questions

Common Questions

What developers ask before the first cycle.

Do I need to write a long specification to use the Spec-Driven Guide?

Not usually. One line is enough: a prefix (feat:, fix:, docs:, audit: or land:) plus what you want. The agent proposes the full SPEC and stops at the approval gate, where the two of you align it before any code. Write more up front where the risk is real.

How do I install the Spec-Driven Guide in a project?

Run npx spec-driven-guide inside the project. The CLI writes an AGENTS.md router at the repository root plus an .ai/ instruction set. Any agent that reads AGENTS.md picks the governance up from there.

Which AI agents does it work with?

Any agent that reads AGENTS.md at the repository root: Claude Code, Cursor, GitHub Copilot, Codex, Gemini, Windsurf and Roo Code. Claude Code also auto-loads a CLAUDE.md pointer to the same file.

What are the five phases of the SDG cycle?

SPEC defines what and why. PLAN turns it into an ordered task list. CODE follows the plan and nothing more. TEST verifies the build against the agreement. END closes the cycle with a changelog and a commit proposal. The agent stops for explicit approval at SPEC and at PLAN.

What does the audit: prefix do?

It runs a drift check: the agent compares the codebase against the governance rules installed under .ai/ and returns a correction plan with tasks you can act on, instead of silently rewriting code.

Context Builder

Context Builder

Generate your agent's starting instructions in a few clicks.

Context Builder

Step 1/4: Architecture

Architecture Flavor

Architecture Flavor

SDG Icon

Spec-DrivenGuide

v2.1.5
The governance framework for developers and agents © 2026