sddguard

Spec-Driven Development for AI-assisted projects.

sddguard installs a local protocol that guides AI agents through clarify → plan → execute → verify → review, stopping at explicit gates where a human approves before the agent continues. The CLI is intentionally small: it copies Markdown command definitions into your repo, then you work inside your agent chat with commands like /spec-plan, /spec-tasks, /verify, and /finish.

npx sddguard init

Works with any stack (Next.js, Python, Go, Rails, …) and ships provider templates for Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Windsurf, Cursor, and Zed.

After install, the workflow happens inside your AI agent:

/spec-new auth-refresh
/spec-plan auth-refresh      # stops for your approval before any code
/spec-tasks auth-refresh     # executes one task at a time
/verify auth-refresh         # mechanical audit — writes verify-report.md
/review auth-refresh         # qualitative final pass — writes review-report.md
/finish                      # requires verify + review, then proposes a commit

Mental model

There is no daemon, server, database, or task runner. sddguard is an installer for plain-Markdown protocol files your repo owns and you can edit.

Two command surfaces:

CLI commands run in your terminal — install, status, updates: npx sddguard init, sddguard status, sddguard update.
Agent commands run inside your AI tool — the actual workflow: /spec-plan, /spec-tasks, /verify, /finish.

The agent reads .sdd/workflow.md before every task. That file defines the commands, per-phase permissions, and non-negotiable stop points. .sdd/autonomy.md defines which approvals, if any, are delegated to the agent. Each feature lives in specs/<feature>/ as Markdown you can read and diff.

Why this exists

Left unsupervised, AI agents implement before validating assumptions, refactor more than asked, add dependencies silently, and have no model of when to stop and ask.

This protocol gives the agent explicit stop points: plan before code, ask before guessing, verify before finish, and amend approved specs through a visible Change Request instead of editing them silently.

Quick start

New project:

# 1. Install the protocol (prompts for which agents to set up)
npx sddguard init

# 2. Populate project context — run inside your AI agent
/bootstrap

# 3. Build a feature, using a real feature name
/spec-new auth-refresh
/spec-clarify auth-refresh  # resolve blockers, then mark requirements ready
/spec-plan auth-refresh     # STOPS for your approval before any code
/spec-tasks auth-refresh    # executes task by task
/verify auth-refresh        # mechanical audit — writes verify-report.md
/review auth-refresh        # qualitative final pass — writes review-report.md
/finish                     # requires verify + review, then proposes a commit

Existing codebase:

npx sddguard init --existing

# Then have the agent discover the code before writing context files:
/scan                       # discovery only — writes scan-report.md
/bootstrap --scan           # proposes project-overview.md + conventions.md for approval

Which flow should I use?

Situation	Use
Small confirmed bug (≤ ~50 lines, 1 file)	`/bugfix` → `/finish`
Behavior-preserving cleanup	`/refactor` → `/finish`
New feature	`/spec-new <name>` → `/spec-clarify <name>` → `/spec-plan <name>` → `/spec-tasks <name>` → `/verify` → `/review` → `/finish`
Unsure how the code works	`/ask`
Comparing libraries or approaches	`/research <feature> <topic>`
Requirements ambiguous before planning	`/spec-clarify <feature>`
Implementation blocked mid-task	`/impl-gap <feature>`
Approved requirements or plan must change	`/spec-amend <feature> <change-summary>`
Work done, needs audit	`/verify <feature>` → `/review <feature>`

Agent commands

20 slash commands, installed for every agent you select. Full contract lives in .sdd/workflow.md.

Project setup

Command	Purpose
`/bootstrap`	Populate project context — interview (new) or `--scan` (existing codebase)
`/scan`	Discovery-only pass — writes `scan-report.md`, no `.sdd/` changes
`/conventions-sync`	Refresh `.sdd/conventions.md`, preserving `<!-- manual -->` sections

Exploration and research artifacts

Command	Purpose
`/ask`	Research and explanation — never modifies files
`/research`	Compare libraries/patterns — writes only non-binding `research-<topic>.md`, never code
`/assume`	Surface every assumption and stop until they're confirmed

Feature flow

Command	Purpose
`/spec-new`	Scaffold `specs/<feature>/` from the template
`/spec-clarify`	Ask blocking/non-blocking questions, record answers, and get requirements ready
`/spec-plan`	Generate the technical plan from requirements marked ready — stops for approval before any code
`/spec-tasks`	Execute the plan one atomic task at a time, test-first
`/impl-gap`	Stop and log a blocking ambiguity/contradiction — no improvising
`/spec-amend`	Documented Change Request to edit an already-approved spec
`/spec-analyze`	Cross-consistency check: goals↔tasks, plan↔tasks, scope creep
`/verify`	Strict mechanical audit — read-only `verify-report.md`
`/review`	Lighter qualitative pass — writes `review-report.md`
`/finish`	Requires passing verify + non-escalated review, then stages files + drafts a commit message

Multi-spec awareness

Command	Purpose
`/spec-status`	State of every active spec (phase, progress, open CRs/gaps)
`/spec-conflicts`	Detect specs that touch the same files before they collide

Quick changes

Command	Purpose
`/bugfix`	Reproduce → diagnose → fix → validate
`/refactor`	Restructure with a green-test invariant, no behavior change

/verify vs /review: /verify is the deterministic audit (tasks complete, goals covered, suite green, no out-of-scope edits, no open gaps/CRs) and must record evidence for every check, not just a Result: PASS line. /review is the qualitative human-touch pass, recorded in review-report.md. Both avoid code/spec edits except for their report outputs.

CLI reference

npx sddguard init                  # install protocol (prompts for agents)
npx sddguard init --provider codex # install only one provider integration
npx sddguard init --provider codex,gemini
npx sddguard init --profile agent  # install a delegated autonomy policy
npx sddguard init --profile autonomous
npx sddguard init --all            # install every provider integration
npx sddguard init --existing       # brownfield: next steps start with /scan
npx sddguard init --force          # refresh protocol files, preserving project context

npx sddguard add domain auth       # add a built-in domain template
                                        # built-in: auth, payments, storage, email
                                        # for custom domains, create .sdd/domains/<name>.md manually

npx sddguard status                # bootstrap state + open specs progress
npx sddguard commands              # list protocol command catalog
npx sddguard update                # refresh protocol files
npx sddguard update --dry-run      # preview installed files that would change
npx sddguard update --check        # CI-friendly outdated check
npx sddguard doctor                # validate install health + stale files

Non-TTY default: When stdout is not a TTY (CI, piped scripts), init without flags installs every provider - equivalent to --all. Pass --provider explicitly to limit.

Autonomy profiles

init also installs .sdd/autonomy.md, a project-owned policy that tells agents whether stop-point approval is human-only or delegated. Each policy includes an Operating Mode section that defines the agent's default behavior for that profile.

Profile	Use when	Behavior
`guided`	You want the original workflow	Default. The agent asks before approving SDD stop points.
`agent`	You want low-risk agent work to continue	The agent continues only for low-risk, bounded, test-backed work.
`autonomous`	You want routine SDD work to run with minimal interruption	The agent continues through routine SDD phases unless a hard stop applies.

Examples:

npx sddguard init --profile guided
npx sddguard init --profile agent
npx sddguard init --profile autonomous

This is not an agent runner. There is still no daemon, scheduler, background process, or automatic execution of AI tool commands. The profile only changes the written policy that an obedient agent reads before deciding whether a stop point has delegated self-approval.

Everything is copied locally — your repo owns the files, no runtime dependency, edit freely.

Updating an existing install

sddguard update refreshes managed workflow and command files that already exist in your project. It preserves project context and provider entrypoints/rules, and it does not silently create newly introduced provider commands in older installs.

Need	Command
Refresh managed files you already have	`sddguard update`
List protocol command catalog	`sddguard commands`
Preview template updates	`sddguard update --dry-run`
Fail CI when templates are outdated	`sddguard update --check`
Pull in commands added by a newer version	`sddguard init --force`
Add a built-in domain template	`sddguard add domain auth`
Check installation health	`sddguard doctor`

update and init --force never touch project-overview.md, conventions.md, .sdd/autonomy.md, domains/, or provider entrypoints/rules such as AGENTS.md, CLAUDE.md, GEMINI.md, Copilot instructions, Cursor/Windsurf rules, and .rules. Before init --force, review local changes to provider command files.

Generated structure

.sdd/
  workflow.md            # commands, permissions, stop points
  project-overview.md    # what this app is — populated by /bootstrap
  conventions.md         # stack & patterns — populated by /bootstrap
  domains/               # optional domain rules (auth, payments, …)
specs/
  _template/             # source templates copied by /spec-new
    1-requirements.md    #   problem, goals (G1…), BDD acceptance criteria
    2-plan.md            #   approach, tradeoffs, components, abort criteria
    3-tasks.md           #   atomic task checklist with a TDD gate
    2a-data-model.md     #   optional: non-trivial persistence
    2b-api-contracts.md  #   optional: new external contracts
    2c-research.md       #   optional: research that belongs in the plan
    amendments.md        #   Change Requests (/spec-amend)
    impl-gaps.md         #   blocking gaps logged during execution (/impl-gap)
    analysis.md          #   /spec-analyze output
    verify-report.md     #   /verify output
    review-report.md     #   /review output
  _done/                 # shipped specs, moved here after verify + review close
CLAUDE.md                # agent entry point — points at .sdd/

You edit: project-overview.md, conventions.md, and per-feature 1-requirements.md / 2-plan.md / 3-tasks.md.
The agent generates as history/reports: amendments.md, impl-gaps.md, analysis.md, verify-report.md, and review-report.md.

Per selected agent, command files are also installed (see Provider support).

How approval works

The agent may draft plans and reports. By default, structural decisions stay with the human. If .sdd/autonomy.md delegates a specific approval, the agent may self-approve that stop point and must record the decision in the same artifact a human would approve.

/spec-plan stops before code. You approve the plan before /spec-tasks.
/spec-tasks can edit code and tests, but not approved requirements or plan files.
/impl-gap records a blocker and waits for direction — no improvising.
/spec-amend records a Change Request and waits for approval before changing 1-requirements.md or 2-plan.md.
/verify and /review are read-only, except for verify-report.md and review-report.md.
/finish may proceed only after verify-report.md is complete with Result: PASS and review-report.md is non-blocking (Result: PASS or Result: FOLLOW_UPS).

Delegated self-approval never overrides hard stops. Ambiguity, unresolved gaps, pending CRs, failing tests, unlisted scope, destructive changes, high-risk domains, and release/publish actions still follow .sdd/workflow.md and .sdd/autonomy.md.

Spec structure

Each feature lives in specs/<name>/. Three core files gate progress:

1-requirements.md — problem, measurable goals (G1, G2…), BDD acceptance criteria, constraints, blocking vs. non-blocking open questions, and a Clarifications section populated by /spec-clarify. Its Status checklist must mark Ready for /spec-plan before planning can start.
2-plan.md — goals coverage, assumptions confirmed via /assume, approach + tradeoffs, components affected, abort criteria. Requires explicit approval before any code is written.
3-tasks.md — one atomic task at a time; each names the test to write first (red → green), files to change, and the goal ID it serves.

Once approved, 1-requirements.md and 2-plan.md are read-only — changes go through /spec-amend. After /verify passes and /review is PASS or FOLLOW_UPS, the spec moves to specs/_done/.

Provider support

Provider	Installed files
Claude Code	`.claude/commands/*.md`, `CLAUDE.md`
OpenAI Codex	`.agents/skills/*/SKILL.md`, `AGENTS.md`
GitHub Copilot	`.github/prompts/*.prompt.md`, `.github/copilot-instructions.md`
Gemini CLI	`.gemini/commands/*.toml`, `GEMINI.md`
Windsurf	`.windsurf/workflows/*.md`, `.windsurf/rules/sddguard.md`
Cursor	`.cursor/rules/sddguard.mdc`
Zed	`.rules`

Providers with native slash-command or workflow support get per-command files. Rule-only providers get the protocol as always-on project context.

Execution principles

Enforced by every command:

Surface assumptions — list them before acting, not mid-execution.
Minimum code — only what was asked; no "while I'm here" changes.
Surgical changes — touch only what the task requires.
Verify before moving on — define "done" before starting, not after.
Use the right channel for changes — /impl-gap for blocked tasks, /spec-amend for approved spec edits. Never edit approved specs silently.

Design principles

Zero runtime dependency — files copied locally, no server, daemon, or watcher.
npx-first — one command, no Python/uv/pipx.
Delegation is explicit — structural decisions are human-approved unless .sdd/autonomy.md clearly delegates them.
Files you can read — pure Markdown, no databases, no binary formats.

Development

git clone https://github.com/MarcosCamara01/sddguard.git
cd sddguard
npm install
npm run dev      # watch mode
npm run build    # production build → dist/cli.js

Publishing

npm version patch   # bug fix:     0.1.0 → 0.1.1
npm version minor   # new feature: 0.1.0 → 0.2.0
npm publish

Users running npx sddguard init always get the latest version.

License

MIT

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.claude/commands		.claude/commands
.github/workflows		.github/workflows
.sdd		.sdd
smoke		smoke
specs		specs
src		src
templates		templates
test		test
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
RELEASE_CHECKLIST.md		RELEASE_CHECKLIST.md
biome.json		biome.json
package-lock.json		package-lock.json
package.json		package.json
skills-lock.json		skills-lock.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Navigation Menu

Repository files navigation

sddguard

Mental model

Why this exists

Quick start

Which flow should I use?

Agent commands

Project setup

Exploration and research artifacts

Feature flow

Multi-spec awareness

Quick changes

CLI reference

Autonomy profiles

Updating an existing install

Generated structure

How approval works

Spec structure

Provider support

Execution principles

Design principles

Development

Publishing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

sddguard

Mental model

Why this exists

Quick start

Which flow should I use?

Agent commands

Project setup

Exploration and research artifacts

Feature flow

Multi-spec awareness

Quick changes

CLI reference

Autonomy profiles

Updating an existing install

Generated structure

How approval works

Spec structure

Provider support

Execution principles

Design principles

Development

Publishing

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages