Documentation Index
Fetch the complete documentation index at: https://mintlify.com/jorgeferrando/sdd-skills/llms.txt
Use this file to discover all available pages before exploring further.
/sdd-agent is the fully autonomous orchestrator for SDD. You hand it a task — as a plain description, a GitHub issue number, or a Jira ticket — and it works through the entire cycle: exploring the codebase, writing the proposal, spec, design, and tasks, implementing each task, verifying quality, creating a structured pull request, and then monitoring and responding to PR review comments until the PR is approved. It asks questions only when it genuinely needs a decision it cannot make itself. For everything covered by your conventions.md, project-rules.md, or existing code patterns, it proceeds silently and reports progress.
/sdd-agent is designed for supervised autonomy — it is not headless by default. It reports progress, surfaces decisions, and waits for approval at key gates (notably after proposing, before implementation begins). If running without a chat channel, it treats all MEDIUM-confidence situations as HIGH and skips questions.Usage
Prerequisites
openspec/initialized. If it does not exist, the agent runssdd-init --quickautomatically to bootstrap with sensible defaults — no need to ask.- A Git repository with a clean working tree before the agent starts.
Confidence Model
Before each phase the agent assesses its confidence and decides whether to proceed or ask:| Level | Criteria | Action |
|---|---|---|
| HIGH | Scope < 5 files, existing pattern to follow, clear requirements | Proceed silently |
| MEDIUM | Scope 5–10 files, some ambiguity but reasonable defaults exist | Proceed, flag in PR description as “needs review” |
| LOW | Scope > 10 files, ambiguous requirements, no similar pattern, conflicting conventions | Stop and ask via chat |
What It Does
--issue N) — fetches title, body, and comments via gh issue view N--ticket ID) — reads from the Jira APIExtracts the goal, constraints, and acceptance criteria. If the input is too vague to determine scope (e.g., “improve performance” with no further detail), the agent asks targeted clarifying questions before proceeding.
Checks for
openspec/steering/conventions.md. If openspec/ is missing entirely, runs sdd-init --quick automatically. Reads all steering files — conventions.md, project-rules.md, tech.md, and relevant specialists — once here and passes them as a shared prefix to all subsequent subagents. This ensures prompt-cache hits across the sequential phases.openspec/changes/{change-name}/notes.mdIf recall finds a previous spec that explicitly excluded something the current task appears to include, the agent flags it and asks whether to respect the prior boundary.
Generates
proposal.md following the full /sdd-propose skill. Shows a summary in chat and waits for explicit approval before continuing. This is the primary human checkpoint in the autonomous flow.Writes the behavior specification. Asks about business logic edge cases only; technical decisions that follow from
conventions.md or existing patterns are decided automatically without asking.Runs
/sdd-design as a subagent (non-interactive, keeps context clean), then generates tasks.md inline. If the design scope exceeds 10 files, asks whether to proceed, split the change, or hand off.Implements each task from
tasks.md using /sdd-apply --auto. Reports progress after each task. If a task fails after one retry, stops and asks with full context before attempting again.Runs
/sdd-verify as a subagent (non-interactive). Does not create the PR — the orchestrator handles that in the next step.## Task
{Original task description or issue link}
## What this PR does
{1-3 sentences from proposal.md}
## Spec
{Key behaviors from spec.md — Given/When/Then summary}
## Design decisions
{Decision table from design.md}
## Changes
{File list from tasks.md with one-line descriptions}
## Acceptance criteria
{From proposal.md}
---
Generated by SDD Agent | [View full artifacts](openspec/changes/{change}/)
✅ PR created: {repo}#{number}
{title}
{N} commits, {N} files changed
Tests: all passing
Waiting for review.
Escalation Protocol
The agent asks when it needs to — and only then.| Situation | Does the agent ask? |
|---|---|
| Business logic is ambiguous | ✅ Yes |
| Scope changes beyond the original proposal | ✅ Yes |
| Tests fail after 2 attempts | ✅ Yes |
| Review requests an architectural change | ✅ Yes |
| Confidence is LOW | ✅ Yes |
Decision is covered by conventions.md | ❌ No — proceeds silently |
Code style follows project-rules.md | ❌ No — proceeds silently |
| Pattern exists in the codebase | ❌ No — proceeds silently |
Phase and Model Reference
Each phase uses the model hint from the underlying skill’s frontmatter:| Phase | Skill | Mode | Model hint |
|---|---|---|---|
| Propose | sdd-propose | Inline | opus |
| Spec | sdd-spec | Inline | sonnet |
| Design | sdd-design | Agent | opus |
| Tasks | sdd-tasks | Inline | haiku |
| Apply | sdd-apply --auto | Inline (manages own agents) | haiku (orchestrator), sonnet (subagents) |
| Verify | sdd-verify | Agent | sonnet |
Skill Metadata
| Field | Value |
|---|---|
model_hint | sonnet |
requires | openspec/config.yaml |
produces | proposal.md, specs/*/spec.md, design.md, tasks.md, code commits, pull request |
When to Use
/sdd-agent is best suited for tasks that are:
- Well-scoped with clear requirements (or at least a clear GitHub issue / Jira ticket)
- Operating in a codebase where
openspec/steering/files are up to date - Intended for review at the PR level rather than at each intermediate phase
/sdd-new → /sdd-continue → /sdd-continue → … or run the planning-only shortcut /sdd-ff followed by /sdd-apply and /sdd-verify.
Next Steps
Once/sdd-agent creates the PR, the human’s job is to review it. The agent handles follow-up comments automatically. When the PR is approved and merged, run /sdd-archive to close the cycle and merge the delta specs into the canonical specs.