Instruction file imported from madebyaris/spec-kit-command-cursor (.cursor/rules/sdd-system.mdc). Copyright stays with the author.

SDD (Spec-Driven Development) System v6.0

Requires Cursor 3.8+ for async subagents, nested subagent trees, skills, plugins, cloud subagents (/in-cloud, /babysit), native review (/review), Memories, agent multitasking, worktrees, and multi-root sessions.

Core Philosophy

Create specifications before code. Plan-approve-execute for all operations.

Architecture

User Request → Main Agent → Subagents (parallel/async) → Skills (auto-invoked)
                    ↓                    ↓
              Verification ←── Subagent Tree (nested spawning)

Subagents (.cursor/agents/)

Foreground vs Background

• Foreground blocks the parent until complete. Use when results are needed immediately (exploration, planning, verification).
• Background (is_background: true) returns immediately. The parent continues working. Use for long-running implementations and orchestration.

Subagent Tree

Subagents can spawn their own subagents to any depth:

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

Delegation Guidelines

Delegate when: deep exploration, long implementation, parallel tasks, verification. Keep in main context when: simple operations, user interaction needed, sequential dependent steps.

Skills (.cursor/skills/)

Skills use progressive loading — keep SKILL.md focused, put details in references/, scripts in scripts/, templates in assets/.

Workflows

Quick Planning (80% of features)

• /brief → feature-brief.md (30-minute planning)
• /evolve → Update specs with discoveries
• /refine → Iterate on existing specs

Full Planning (complex features)

/research → /specify → /plan → /tasks → /implement

Parallel Execution with DAG

• /sdd-full-plan → Create roadmap with DAG structure
• /execute-task → Sequential task execution
• /execute-parallel → Parallel via async subagents

Cursor 3.8 Agent Runtime

• Use /multitask for ad hoc independent work that does not need a roadmap, checkpoint, or dependency graph.
• Use /execute-parallel for SDD roadmap execution because it handles dependencies, file-conflict batching, checkpoints, and verifier handoffs.
• Use Agents Window worktrees for risky, parallel, or best-of-N implementation work. .cursor/worktrees.json prepares the isolated checkout.
• Offload long-running, risky, or environment-heavy tasks to cloud subagents with /in-cloud (own VM + branch); use /babysit to drive a PR to merge-ready remotely. .cursor/environment.json makes cloud agents start faster.
• In multi-root workspaces, resolve paths from the active project root and avoid assuming a single repository owns every file.

Memory (.sdd/config.json → memory)

SDD long-term memory is optional and pluggable. The active backend is set in .sdd/config.json:

The sdd-memory skill performs recall before planning/implementation and persist after discoveries. Configure with /sdd-memory. Never store secrets in memory. When standard, memory is a no-op.

Native Review (Cursor 3.8+)

Prefer Cursor's first-party reviewers for mechanical checks, then let SDD agents own spec compliance:

• /review (choose Bugbot + Security Review), or /review-bugbot / /review-security directly. Bugbot runs in ~90s and syncs with GitHub/GitLab to avoid duplicate PR reviews.
• /audit and sdd-reviewer fold native findings into a single consolidated report.

DAG-Based Execution

Tasks as Directed Acyclic Graph with automatic parallelization:

{
  "dag": {
    "roots": ["task-001", "task-003"],
    "parallelGroups": [["task-001", "task-003"], ["task-002", "task-004"]]
  }
}

Pattern: Identify ready tasks → spawn background subagents in parallel → collect results → verify with sdd-verifier → continue.

Automated Verification

Every implementation triggers verification:

sdd-implementer → [code] → sdd-verifier → [validation report]

Background implementers spawn foreground verifiers as child subagents.

Sandbox (.cursor/sandbox.json)

Network access controls for sandboxed commands. Configure allowed domains for package registries and APIs. See .cursor/sandbox.json for project defaults.

File Organization

specs/
├── active/[task-id]/          # Tasks in development
├── todo-roadmap/[project]/    # Project roadmaps with DAG
└── completed/                 # Delivered features

.cursor/
├── agents/                    # Subagents (foreground + background)
├── skills/                    # Agent Skills (progressive loading)
├── commands/                  # Slash commands
├── environment.json           # Cloud agent environment setup (3.7+)
├── worktrees.json             # Worktree setup
└── sandbox.json               # Network access controls

Command Reference

Todo Execution Rules

1. Read entire list before starting
2. Execute in order — respect dependencies
3. Mark completion: - [ ] → - [x]
4. Document blockers — never skip silently
5. Verify after implementation — use sdd-verifier

Plugin Distribution

This system can be packaged as a Cursor Marketplace plugin. See .cursor-plugin/plugin.json for manifest.

References

• Agent Manual: .cursor/commands/_shared/agent-manual.md
• Subagents: .cursor/agents/
• Skills: .cursor/skills/
• Memory: .cursor/skills/sdd-memory/ + .sdd/config.json memory
• Cloud env: .cursor/environment.json
• Sandbox: .cursor/sandbox.json