SDD Cursor Commands v5.1

What's New in v5.1

• Async Subagents — Background subagents (is_background: true) let the parent agent continue working while long tasks run
• Subagent Tree — Subagents spawn their own subagents: orchestrator → implementers → verifiers
• Deep Research — Multi-pass external investigation with web search, documentation deep-dives, real-world validation, and confidence scoring (/research --deep)
• File Conflict Detection — Tasks declare touchedFiles so the orchestrator can prevent parallel edits to the same files
• Progressive Context Loading — Heavy roadmaps (40+ tasks) load only the current batch, not the full task list
• Checkpoints & Resume — execution-checkpoint.json enables /execute-parallel --resume after interruption
• Downstream Propagation — /evolve marks stale downstream docs when a spec changes
• Deadlock Detection — Orchestrator detects circular dependency deadlocks and per-task timeouts
• Hooks — Workflow automation via .cursor/hooks.json (subagentStop, stop events)
• Cursor 3.2 Agent Runtime — Guidance for /multitask, Agents Window worktrees, and multi-root sessions
• Sandbox Controls — Granular network access via .cursor/sandbox.json
• Plugin Packaging — Distributable as a Cursor Marketplace plugin (.cursor-plugin/)

Quick Start

git clone https://github.com/madebyaris/spec-kit-command-cursor.git
cd spec-kit-command-cursor

Most common flow (copy into Cursor chat):

/brief user-auth JWT authentication with login/logout

Full planning:

/sdd-full-plan blog-platform Full-featured blog with CMS
/execute-parallel blog-platform --until-finish

Deep research before planning:

/research database-engine Best database for our use case --deep

Cursor 3.2 parallel work:

• Use Cursor's built-in /multitask for quick independent prompts with no SDD roadmap state.
• Use /execute-parallel for roadmap-backed SDD work that needs dependency checks, checkpoints, and verifier handoffs.
• Use Agents Window worktrees for risky or competing implementations; .cursor/worktrees.json prepares the isolated checkout.

Commands

Planning

Execution

Maintenance

Subagents & Skills

Subagents (.cursor/agents/)

Specialized agents with isolated context. Background agents run asynchronously — the parent continues working.

Reviewer vs Verifier: The reviewer is a pre-merge quality gate (security, performance, style). The verifier is a post-implementation completeness check (does the code match the spec?). Verifier answers "is it done?", Reviewer answers "is it good?"

Subagent Tree (Cursor 3.2+)

Subagents can spawn their own subagents, enabling true parallel DAG execution:

sdd-orchestrator (background)
├── sdd-implementer (task 1) → sdd-verifier
├── sdd-implementer (task 2) → sdd-verifier
└── sdd-implementer (task 3) → sdd-verifier

Skills (.cursor/skills/)

Auto-invoked domain knowledge packages with progressive loading:

Each skill folder contains:

sdd-[name]/
├── SKILL.md          # Core instructions
├── references/       # Loaded on demand
├── scripts/          # Executable helpers
└── assets/           # Templates

Workflows

flowchart LR
    subgraph quick [Quick Planning]
        A["/brief"] --> B["/evolve"]
        B --> C["/refine"]
    end
    subgraph full [Full Planning]
        D["/research"] --> E["/specify"] --> F["/plan"] --> G["/tasks"] --> H["/implement"]
    end
    subgraph parallel [Parallel Execution]
        I["/sdd-full-plan"] --> J["/execute-parallel"]
    end

Heavy App Path

For new apps with 20+ tasks or enterprise complexity:

1. /sdd-full-plan [project-id] [description] — create roadmap with DAG
2. For 40+ tasks: choose Option C: Phased Creation to create epics incrementally
3. /execute-parallel [project-id] --until-finish — run all tasks with conflict detection
4. /execute-parallel [project-id] --resume — resume after interruption via checkpoint

Deep Research

For high-stakes technical decisions (database engines, auth providers, cloud platforms):

/research auth-provider Compare Auth0 vs Clerk vs Supabase Auth --deep

Deep research performs 4 passes: landscape scan → documentation deep-dive → real-world validation → integration feasibility. Results include source URLs, reliability ratings, and a confidence assessment.

Automated Execution

# Execute until complete
/execute-task epic-001 --until-finish

# Create and execute entire project
/sdd-full-plan my-project --until-finish

Architecture

graph TD
    User["User Request"] --> MainAgent["Main Agent"]
    MainAgent -->|foreground| Explorer["sdd-explorer"]
    MainAgent -->|foreground| Planner["sdd-planner"]
    MainAgent -->|background| Orchestrator["sdd-orchestrator"]
    MainAgent -->|background| Implementer["sdd-implementer"]
    MainAgent -->|foreground| Reviewer["sdd-reviewer"]

    Orchestrator -->|"conflict check"| BatchSelector["Batch Selector"]
    BatchSelector -->|spawns| Impl1["implementer (task 1)"]
    BatchSelector -->|spawns| Impl2["implementer (task 2)"]
    BatchSelector -->|spawns| Impl3["implementer (task 3)"]

    Orchestrator -->|checkpoint| Checkpoint["execution-checkpoint.json"]

    Implementer -->|spawns| Verifier["sdd-verifier"]
    Impl1 -->|spawns| V1["verifier"]
    Impl2 -->|spawns| V2["verifier"]
    Impl3 -->|spawns| V3["verifier"]

Project Structure

.cursor/
├── agents/           # 6 subagents (foreground + background)
├── skills/           # 5 skills with progressive loading
├── commands/         # Slash commands
├── rules/            # Always-applied rules
├── hooks.json        # Workflow automation hooks
└── sandbox.json      # Network access controls

.cursor-plugin/
└── plugin.json       # Cursor Marketplace manifest

.sdd/
├── config.json       # Project configuration
├── guidelines.md     # Methodology guide
├── ROADMAP_FORMAT_SPEC.md  # Roadmap JSON schema (with DAG)
├── FULL_PLAN_EXAMPLES.md   # Worked examples at 3 complexity levels
├── templates/        # Document templates (compact + specialized)
└── archive/          # Historical implementation docs

specs/
├── active/           # Features in development
├── backlog/          # Future features
├── todo-roadmap/     # Project roadmaps with DAG
└── completed/        # Delivered features

Hooks & Sandbox

Hooks (.cursor/hooks.json)

Workflow automation triggered by agent events:

Sandbox (.cursor/sandbox.json)

Granular network access controls for sandboxed commands. Defaults allow common package registries (npm, pypi, GitHub, Docker, Deno) while denying private networks. Customize by editing .cursor/sandbox.json.

Templates

Available in .sdd/templates/:

Plugin Distribution

SDD is packaged as a Cursor Marketplace plugin. Install via /add-plugin or clone the repo directly. See .cursor-plugin/plugin.json for the manifest.

Contributing

• Contributing guide - How to add commands, subagents, skills, and templates
• Report bugs
• Suggest features

Acknowledgments

Thanks to ClavixDev for valuable ideas and suggestions!

License

MIT License - see LICENSE