sdd-agent-setup

Set up a spec-driven development (SDD) workflow for coding agents in any repository — one command, no global install required.

This tool scans your repo, writes a shared AGENTS.md, and adds lightweight adapter files for the agents you use (Codex, Claude Code, Cursor, GitHub Copilot, Windsurf/Devin). Managed sections stay behind markers so you can run update later without overwriting your own notes.

Quick start (Mac)

0. Prerequisites

You need Node.js 20 or newer. Check with:

node -v

If that fails or shows a version below 20, install Node from nodejs.org or with Homebrew:

brew install node

You do not need to install this package globally. npx downloads and runs it for you.

1. Run setup in your repo

Open Terminal, go to the repository you want to configure, and run:

cd /path/to/your-project
npx sdd-agent-setup init

The CLI will:

1. Scan your repo — languages, frameworks, package manager, scripts, CI, and existing agent files.
2. Ask which agents you use — nothing is selected by default. Use Space to toggle each agent you use (Codex, Claude Code, Cursor, GitHub Copilot, and/or Windsurf/Devin), then Enter to continue. You must select at least one.
3. Show a plan — which files will be created or updated.
4. Ask for confirmation — nothing is written until you approve.

When it finishes, your repo has the SDD workflow files in place. Commit them like any other project config:

git add AGENTS.md CLAUDE.md .cursor .github .devin .sdd
git commit -m "Add spec-driven development agent setup"

(Adjust the paths to match what was actually created — see What it writes below.)

2. Confirm everything looks good

npx sdd-agent-setup doctor

doctor reports missing, stale, or conflicting setup files. Fix issues by re-running init, or refresh managed content with update.

3. Start using the workflow

After setup, your agents read from AGENTS.md. The SDD flow lives in .sdd/:

| Step | Where | |------|--------| | Write a spec | .sdd/templates/spec.md | | Turn it into a plan | .sdd/templates/plan.md | | Break into tasks | .sdd/templates/tasks.md | | Full workflow reference | .sdd/workflow.md |

Open your coding agent in the repo and ask it to follow the SDD workflow — e.g. "Draft a spec for adding user authentication using the template in .sdd/templates/spec.md."

Non-interactive setup

Useful for scripts or CI:

npx sdd-agent-setup init --yes --no-interactive --agents cursor,codex,claude

Preview changes without writing anything:

npx sdd-agent-setup preview

What it writes

Core (always):

• AGENTS.md — canonical instructions for all agents
• .sdd/workflow.md — SDD process overview
• .sdd/templates/spec.md, plan.md, tasks.md — templates to copy or fill in
• .sdd/setup-manifest.json — metadata used by update and doctor

Adapters (based on your selection):

| Agent | File | |-------|------| | Codex | Uses AGENTS.md directly (no extra file) | | Claude Code | CLAUDE.md | | Cursor | .cursor/rules/sdd.mdc | | GitHub Copilot | .github/copilot-instructions.md | | Windsurf / Devin | .devin/rules/sdd.md |

Generated regions are wrapped in managed markers. Keep custom notes outside those markers — update only refreshes what's inside.

Commands

npx sdd-agent-setup init [path]      # First-time setup (default path: current directory)
npx sdd-agent-setup update [path]    # Refresh managed sections after repo or tool changes
npx sdd-agent-setup preview [path]   # Show planned changes without writing
npx sdd-agent-setup doctor [path]    # Check setup health

Useful flags:

--agents codex,claude,cursor,copilot,windsurf   # Limit which adapters to configure
--all-agents                                    # Enable every adapter
--dry-run                                       # Plan only, no writes (init/update)
--yes                                           # Apply without confirmation
--no-interactive                                # Skip prompts
--format text|json                              # Machine-readable output

Keeping setup in sync

Re-run when your repo changes in ways agents should know about — new scripts, frameworks, CI, or agent tools:

npx sdd-agent-setup update

Your hand-written content outside managed markers is preserved.

Developing this package locally

If you're working on sdd-agent-setup itself (not just using it in another repo):

git clone <this-repo-url>
cd sdd-agent-setup
npm install
npm run build
node dist/cli.js init /path/to/test-repo

Or during development:

npm run dev -- init /path/to/test-repo