Spec-Driven Development

What is Spec-Driven Development?

Spec-driven development (SDD) is a workflow where specifications serve as the foundation for all implementation work. Instead of requirements living in disconnected documents, specs become version-controlled, queryable artifacts that evolve alongside your code through bidirectional feedback between humans and AI agents.

Spec-driven development treats specifications as first-class citizens in your codebase, creating a continuous feedback loop between design intent and implementation reality.

Traditional development:

Write requirements (Google Docs, Notion, Jira)
Implementation begins
Requirements drift from reality
Documentation becomes stale
Context is lost

Spec-driven development:

Write spec as version-controlled markdown
AI agents create implementation plan from spec
Agents execute work, providing feedback on ambiguities
Human updates spec based on learnings
Spec remains synchronized with implementation
Context is durable and queryable

Core Principles

Durable Context

Specs persist alongside code

Version controlled in git
Queryable through CLI/MCP
Evolve through feedback
Never drift from reality

Bidirectional Feedback

Continuous learning loop

Agents discover ambiguities
Feedback anchored to specific lines
Humans refine specs
Knowledge compounds

Graph-Based Planning

Work modeled as dependency graph

Issues implement specs
Dependencies explicit
Topological execution
Parallel work enabled

Agent Autonomy

AI-driven execution

Agents claim ready work
Self-directed implementation
Multi-agent coordination
Human-in-the-loop for decisions

How sudocode Implements SDD

sudocode provides the infrastructure for spec-driven development through:

1. Specs as First-Class Entities

Specs are structured markdown files with:

Unique IDs (SPEC-001, SPEC-002, etc.)
Metadata (priority, status, tags)
Version-controlled content
Hierarchical organization (parent-child)

Example spec structure:

---
id: SPEC-005
title: OAuth 2.0 Authentication System
priority: 0
status: approved
tags: [auth, security, api]
---

# OAuth 2.0 Authentication System

## Overview
Implement OAuth 2.0 authentication for the API...

## Requirements
1. Support Google and GitHub providers
2. Secure token storage
...

2. Issues Implement Specs

Issues are work items that implement specifications:

Created from specs (manually or by agents)
Linked via implements relationship
Track implementation progress
Close when complete

Relationship: ISSUE-042 implements SPEC-005

3. Anchored Feedback System

Agents provide feedback on specs during implementation:

Anchored to lines - Feedback tied to specific spec locations
Auto-relocating - Anchors update when specs change
Typed feedback - Comments, suggestions, requests
Bidirectional - Agents to humans, humans to agents

Example:

Agent working on ISSUE-042 discovers:
"Line 23 doesn't specify token expiration time"
→ Adds feedback anchored to line 23
→ Human sees feedback, updates spec
→ Agent continues with clarity

4. Dependency Graph

All work is modeled as a directed acyclic graph:

Issues can block other issues
Dependencies explicit via blocks relationships
ready() query finds unblocked work
Topological ordering enables parallel execution

Example graph:

SPEC-005 (OAuth System)
  ├─ ISSUE-050: Configure providers
  ├─ ISSUE-051: Token exchange (blocked by 050)
  ├─ ISSUE-052: User flow (blocked by 051)
  └─ ISSUE-053: Token refresh (blocked by 051)

5. Multi-Agent Coordination

Multiple agents can work simultaneously:

Each agent queries ready() for available work
Status updates prevent work conflicts
Agents discover and create blockers
Completion automatically unblocks dependent work

The Spec-Driven Development Workflow

1. Create Spec (Human)

Define what you want to buildHumans write specifications capturing intent, requirements, and design:

sudocode spec create "User Authentication System" \
  --type feature \
  --priority 0 \
  --tags auth,security

Edit the spec markdown to add:

Requirements and constraints
Architecture decisions
API designs
Success criteria
Open questions

Example spec content:

# User Authentication System

## Overview
Build a secure authentication system supporting OAuth 2.0

## Requirements
- Support Google and GitHub providers
- Secure token storage (httpOnly cookies)
- Token expiration: 15min access, 7d refresh
- PKCE for all OAuth flows

## Architecture
- OAuth middleware for Express
- Redis for session storage
- JWT for access tokens

## Open Questions
- Should we support email/password fallback?
- Rate limiting strategy?

Tips for writing effective specs

Start high-level: Capture intent before details
Be explicit: State constraints and assumptions
Ask questions: Document unknowns
Link references: Include RFCs, documentation
Define success: What does done look like?

2. Break Down (Optional)

Organize complex specs hierarchicallyFor large features, create sub-specs:

# Create parent spec
sudocode spec create "Authentication System" --priority 0

# Create child specs
sudocode spec create "OAuth 2.0 Integration" \
  --parent SPEC-001 \
  --priority 1

sudocode spec create "Session Management" \
  --parent SPEC-001 \
  --priority 1

sudocode spec create "Security Hardening" \
  --parent SPEC-001 \
  --priority 2

Hierarchy example:

SPEC-001: Authentication System
  ├─ SPEC-002: OAuth 2.0 Integration
  ├─ SPEC-003: Session Management
  └─ SPEC-004: Security Hardening

This allows:

Parallel work on independent sub-specs
Focused reviews
Incremental delivery

3. Plan Implementation (Human + Agent)

Collaborate with AI to create implementation planOption A: Agent-driven planningAsk your AI agent via MCP:

User: "Create an implementation plan for SPEC-001"

Agent (via MCP):
Calls show_spec("SPEC-001") to read spec
Analyzes requirements
Creates issues via upsert_issue()
Links to spec via link(implements)
Models dependencies via link(blocks)

Option B: Manual planningCreate issues yourself:

# Foundation work
sudocode issue create "Configure OAuth providers" \
  --priority 0 \
  --tags auth,setup

# Link to spec
sudocode link ISSUE-001 SPEC-001 --type implements

# Create dependent work
sudocode issue create "Implement token exchange" \
  --priority 1 \
  --tags auth,oauth

sudocode link ISSUE-002 SPEC-001 --type implements

# Model dependency
sudocode link ISSUE-001 ISSUE-002 --type blocks

Example: Agent creates implementation plan

User: "Break down SPEC-005 (OAuth System) into implementation issues"

Agent analyzes spec and creates:

ISSUE-050: "Configure OAuth providers (Google, GitHub)"
  - Priority: 0 (foundation)
  - Tags: oauth, setup, p0
  - Link: implements SPEC-005

ISSUE-051: "Implement OAuth token exchange"
  - Priority: 1
  - Tags: oauth, tokens
  - Link: implements SPEC-005
  - Link: blocked by ISSUE-050

ISSUE-052: "Build OAuth callback handler and user flow"
  - Priority: 1
  - Tags: oauth, flow
  - Link: implements SPEC-005
  - Link: blocked by ISSUE-051

ISSUE-053: "Implement token refresh logic"
  - Priority: 2
  - Tags: oauth, tokens
  - Link: implements SPEC-005
  - Link: blocked by ISSUE-051

ISSUE-054: "Add PKCE security for OAuth flows"
  - Priority: 1
  - Tags: oauth, security
  - Link: implements SPEC-005
  - Link: blocked by ISSUE-052

Agent: "Created 5 issues implementing SPEC-005.
ISSUE-050 is ready to start. Others are blocked by dependencies."

4. Execute Issues (Agent)

Agents claim and complete workAgent workflow:

Find ready work

Agent calls: ready()
Returns: [ISSUE-050] (unblocked, highest priority)

Claim the issue

Agent calls: upsert_issue("ISSUE-050", status: "in_progress")

Review requirements

Agent calls: show_issue("ISSUE-050")
Agent calls: show_spec("SPEC-005")
Agent reads full context

Implement

Agent writes code, tests, documentation
Agent commits changes to git

Complete

Agent calls: upsert_issue("ISSUE-050",
  status: "closed",
  description: "Completed OAuth provider setup.

  Implemented:
  - Google OAuth client configured
  - GitHub OAuth client configured
  - Environment variables documented
  - Provider selection UI added

  Tested with both providers."
)

Next work becomes available

ISSUE-051 is now unblocked (ISSUE-050 closed)
ready() now returns: [ISSUE-051]

CLI equivalent (human-driven):

# Find work
sudocode ready

# Claim it
sudocode issue update ISSUE-050 --status in_progress

# ... implement ...

# Complete
sudocode issue close ISSUE-050 \
  --comment "OAuth providers configured and tested"

5. Provide Feedback (Agent → Human)

Agents surface ambiguities during implementationWhile implementing ISSUE-051 (token exchange), agent discovers:Spec ambiguity on line 23:

23: - Token expiration: reasonable defaults

Agent adds feedback:

Agent calls: add_feedback(
  issue_id: "ISSUE-051",
  spec_id: "SPEC-005",
  content: "Token expiration not specified. Industry standards:
  - Access tokens: 15 minutes
  - Refresh tokens: 7 days

  Recommend specifying explicit values. Using 15min/7d for now.",
  type: "request",
  line: 23
)

Feedback is anchored:

Tied to line 23 of SPEC-005
Visible when viewing spec
Survives spec edits (auto-relocates)

Human reviews feedback:

sudocode feedback list --spec SPEC-005

# Output:
# FEEDBACK-001 (request) on SPEC-005:23
#   From: ISSUE-051
#   Token expiration not specified...

Types of feedback:

request - Need clarification or decision
suggestion - Improvement ideas
comment - Observations or context

6. Iterate (Human)

Update specs based on learningsHuman reviews feedback and updates spec:Before (line 23):

- Token expiration: reasonable defaults

After (updated):

- Token expiration:
  - Access tokens: 15 minutes (short-lived for security)
  - Refresh tokens: 7 days (balance security and UX)
  - Session tokens: 24 hours

Dismiss feedback:

sudocode feedback dismiss FEEDBACK-001 \
  --comment "Spec updated with explicit expiration times"

Smart anchors: If you add/remove lines above the feedback, anchors automatically relocate:

Before: Line 23
After adding 5 lines above: Line 28
Feedback automatically moves to line 28

Create new issues if needed:

# Agent feedback reveals missing work
sudocode issue create "Add token expiration monitoring" \
  --tags monitoring,auth
sudocode link ISSUE-055 SPEC-005 --type discovered-from

7. Track Progress

Monitor project health and identify bottlenecksQuick status:

sudocode status

Output:

Project Status

Specs: 5 total
Issues: 12 total
  - 3 open
  - 4 in_progress
  - 1 blocked
  - 4 closed

Ready: 2 issues
Blocked: 1 issue

Find blockers:

sudocode blocked

Output:

Blocked Issues

ISSUE-054: Add PKCE security
  Blocked by: ISSUE-052 (in_progress)
  Reason: PKCE requires callback handler from ISSUE-052

Detailed statistics:

sudocode stats

Output:

Project Statistics

Specs: 5 total
Issues: 12 total
  By status: 3 open, 4 in_progress, 1 blocked, 4 closed
  Ready: 2
  Blocked: 1

Relationships: 23 total
  8 implements, 6 blocks, 4 depends-on, 5 references

Recent activity (7 days):
  3 specs updated
  8 issues updated
  4 issues closed

Complete Example Walkthrough

Let’s walk through building an OAuth authentication system from start to finish.

Phase 1: Specification

Human creates initial spec:

sudocode spec create "OAuth 2.0 Authentication System" \
  --type feature \
  --priority 0 \
  --tags auth,oauth,security

Returns: SPEC-005 Human edits SPEC-005 markdown:

---
id: SPEC-005
title: OAuth 2.0 Authentication System
type: feature
status: draft
priority: 0
tags: [auth, oauth, security]
---

# OAuth 2.0 Authentication System

## Overview
Implement OAuth 2.0 authentication to allow users to sign in with
Google and GitHub accounts.

## Requirements

### Functional
- Support Google OAuth 2.0
- Support GitHub OAuth 2.0
- Secure token storage
- Token refresh capability
- User profile sync

### Non-Functional
- PKCE for all flows (security)
- Token expiration: reasonable defaults
- Rate limiting on auth endpoints
- Audit logging for auth events

## Architecture

### Components
- OAuth middleware (Express)
- Token storage (Redis)
- Session management
- User profile service

### Data Flow
1. User clicks "Sign in with Google"
2. Redirect to Google OAuth
3. User authorizes
4. Callback receives auth code
5. Exchange code for tokens
6. Store tokens securely
7. Create user session
8. Redirect to dashboard

## Success Criteria
- [ ] Users can sign in with Google
- [ ] Users can sign in with GitHub
- [ ] Tokens refresh automatically
- [ ] No security vulnerabilities (OWASP)
- [ ] Auth flow completes in < 3 seconds

## Open Questions
- Should we support email/password fallback?
- How to handle first-time vs returning users?
- Token storage encryption method?

Update status:

sudocode spec update SPEC-005 --status approved

Phase 2: Planning

Human asks AI agent to create plan:

User: "Create an implementation plan for SPEC-005 with proper dependencies"

Agent (via MCP) creates issues:

// Agent's internal process

// 1. Read the spec
const spec = await show_spec("SPEC-005");

// 2. Analyze and create foundation issue
const issue1 = await upsert_issue({
  title: "Set up OAuth provider configuration",
  description: `Configure OAuth 2.0 providers (Google, GitHub).

## Tasks
- Register OAuth apps with Google and GitHub
- Configure client IDs and secrets
- Set up redirect URIs
- Document environment variables

Implements [[SPEC-005]] section "Components"`,
  priority: 0,
  tags: ["auth", "oauth", "setup", "p0"]
});
// Returns: ISSUE-050

await link("ISSUE-050", "SPEC-005", "implements");

// 3. Create token exchange issue (depends on 050)
const issue2 = await upsert_issue({
  title: "Implement OAuth token exchange and storage",
  description: `Exchange authorization codes for access/refresh tokens.

## Tasks
- Implement token exchange endpoint
- Set up Redis token storage
- Encrypt tokens at rest
- Handle token expiration

Implements [[SPEC-005]] section "Data Flow" steps 4-6`,
  priority: 1,
  tags: ["auth", "oauth", "tokens"]
});
// Returns: ISSUE-051

await link("ISSUE-051", "SPEC-005", "implements");
await link("ISSUE-050", "ISSUE-051", "blocks");

// 4. Create user flow issue (depends on 051)
const issue3 = await upsert_issue({
  title: "Build OAuth callback handler and user flow",
  description: `Implement complete OAuth authentication flow.

## Tasks
- OAuth callback endpoint
- User session creation
- Profile sync from provider
- Login/logout handlers
- Redirect handling

Implements [[SPEC-005]] section "Data Flow" complete flow`,
  priority: 1,
  tags: ["auth", "oauth", "flow"]
});
// Returns: ISSUE-052

await link("ISSUE-052", "SPEC-005", "implements");
await link("ISSUE-051", "ISSUE-052", "blocks");

// 5. Create token refresh issue (depends on 051)
const issue4 = await upsert_issue({
  title: "Implement automatic token refresh",
  description: `Refresh expired access tokens using refresh tokens.

## Tasks
- Token refresh middleware
- Automatic refresh on expiration
- Refresh token rotation
- Error handling

Implements [[SPEC-005]] requirement "Token refresh capability"`,
  priority: 2,
  tags: ["auth", "oauth", "tokens"]
});
// Returns: ISSUE-053

await link("ISSUE-053", "SPEC-005", "implements");
await link("ISSUE-051", "ISSUE-053", "blocks");

// 6. Create security hardening issue (depends on 052)
const issue5 = await upsert_issue({
  title: "Add OAuth security hardening (PKCE, CSRF)",
  description: `Implement security best practices for OAuth.

## Tasks
- PKCE implementation
- CSRF protection (state parameter)
- Rate limiting on auth endpoints
- Security audit logging

Implements [[SPEC-005]] requirement "PKCE for all flows"`,
  priority: 1,
  tags: ["auth", "oauth", "security", "pkce"]
});
// Returns: ISSUE-054

await link("ISSUE-054", "SPEC-005", "implements");
await link("ISSUE-052", "ISSUE-054", "blocks");

Agent responds: “Created implementation plan for SPEC-005: Ready to start:

ISSUE-050: Set up OAuth provider configuration (P0)

Blocked (will become ready as work completes):

ISSUE-051: Token exchange (blocked by 050)
ISSUE-052: User flow (blocked by 051)
ISSUE-053: Token refresh (blocked by 051)
ISSUE-054: Security hardening (blocked by 052)

The work is organized in dependency order. Start with ISSUE-050.”

Phase 3: Execution

Agent 1 claims foundation work:

Agent 1: ready()
→ Returns: [ISSUE-050]

Agent 1: upsert_issue("ISSUE-050", {status: "in_progress"})
Agent 1: "Working on OAuth provider setup..."

Agent 1 implements:
- Creates .env.example with OAuth vars
- Registers apps with Google and GitHub
- Documents setup in README
- Commits changes

Agent 1: upsert_issue("ISSUE-050", {
  status: "closed",
  description: "... [updated with completion summary]"
})

Agent 1: "Completed ISSUE-050. ISSUE-051 and ISSUE-053 are now unblocked."

Agent 2 claims next work:

Agent 2: ready()
→ Returns: [ISSUE-051] (unblocked by 050 closing)

Agent 2: upsert_issue("ISSUE-051", {status: "in_progress"})
Agent 2: show_spec("SPEC-005")

Agent 2 reads spec line 23:
"Token expiration: reasonable defaults"

Agent 2: "This is ambiguous. Let me provide feedback..."

Agent 2: add_feedback({
  issue_id: "ISSUE-051",
  spec_id: "SPEC-005",
  content: `Token expiration policy not specified. Industry standards:
  - Access tokens: 15 minutes
  - Refresh tokens: 7 days

  Recommend adding explicit expiration times to spec.
  I'll use 15min/7d for now.`,
  type: "request",
  line: 23
})

Agent 2: "Provided feedback on SPEC-005. Continuing with 15min/7d defaults..."

Agent 2 implements token exchange with 15min/7d expiration
Agent 2: upsert_issue("ISSUE-051", {status: "closed", ...})

Meanwhile, Agent 3 works on parallel issue:

Agent 3: ready()
→ Returns: [ISSUE-053] (unblocked by 051 closing, independent of 052)

Agent 3: upsert_issue("ISSUE-053", {status: "in_progress"})
Agent 3 implements token refresh...
Agent 3: upsert_issue("ISSUE-053", {status: "closed", ...})

Phase 4: Feedback Integration

Human reviews feedback:

sudocode feedback list --spec SPEC-005 --status open

Output:

Open Feedback on SPEC-005

FEEDBACK-001 (request) - Line 23
  From: ISSUE-051
  Author: Agent 2

  Token expiration policy not specified. Industry standards:
  - Access tokens: 15 minutes
  - Refresh tokens: 7 days

  Recommend adding explicit expiration times to spec.

Human updates spec: Edit SPEC-005, line 23: Before:

- Token expiration: reasonable defaults

After:

- Token expiration:
  - Access tokens: 15 minutes (short-lived for security)
  - Refresh tokens: 7 days (balance security and UX)
  - Session cookies: 24 hours
  - Reasoning: Follows OAuth 2.0 security best practices (RFC 6749)

Dismiss feedback:

sudocode feedback dismiss FEEDBACK-001 \
  --comment "Spec updated with explicit expiration times based on agent recommendation"

Phase 5: Completion

Final issues complete:

Agent 2: ready()
→ Returns: [ISSUE-052] (unblocked by 051 closing)

Agent 2 completes user flow...

Agent 4: ready()
→ Returns: [ISSUE-054] (unblocked by 052 closing)

Agent 4 completes security hardening...

Check status:

sudocode status

Output:

Project Status

Specs: 1 total
  SPEC-005: OAuth 2.0 Authentication System (approved)

Issues: 5 total
  - 0 open
  - 0 in_progress
  - 0 blocked
  - 5 closed ✓

All work complete!

Verify implementation against spec:

sudocode spec show SPEC-005

Check off success criteria:

Users can sign in with Google
Users can sign in with GitHub
Tokens refresh automatically
No security vulnerabilities (OWASP)
Auth flow completes in < 3 seconds

Update spec status:

sudocode spec update SPEC-005 --status completed

Best Practices

For Humans

Start high-level, refine iteratively

Don’t try to specify everything upfront. Start with:

Core requirements
Key constraints
Open questions

Let implementation reality inform refinements.Example:

Draft: "Build user authentication"
v1: "OAuth 2.0 with Google/GitHub"
v2: Add token expiration details from agent feedback
v3: Add security requirements from implementation learnings

Keep issues small and focused

Issues should be agent-scoped: completable in one session.Too large:

❌ "Build complete authentication system"

Right size:

✅ "Configure OAuth providers"
✅ "Implement token exchange"
✅ "Add PKCE security"

Benefits:

Parallel work possible
Clear completion criteria
Easy to track progress
Reduces blocking

Use relationships to model dependencies

Make dependencies explicit with blocks relationships.Example:

# Token exchange needs providers configured first
sudocode link ISSUE-050 ISSUE-051 --type blocks

# Security needs user flow implemented first
sudocode link ISSUE-052 ISSUE-054 --type blocks

This enables:

Automatic ready() filtering
Parallel work discovery
Bottleneck identification

Encourage feedback early and often

Train agents to provide feedback immediately on ambiguities.Agent prompt guidance:

"When you discover ambiguities, unclear requirements, or
decisions that need human input, use add_feedback()
immediately. Don't block on questions - provide feedback
and continue with reasonable assumptions."

Benefits:

Specs improve continuously
Reduces back-and-forth
Agents stay unblocked
Knowledge compounds

Commit context with code

Commit sudocode changes alongside implementation:

git add .sudocode/ src/
git commit -m "Implement OAuth token exchange (ISSUE-051)

- Added token exchange endpoint
- Configured Redis storage
- Updated SPEC-005 with expiration details from agent feedback
"

Benefits:

Context travels with code
Reviews include design decisions
History is complete

For AI Agents

Always check ready() before claiming

Don’t assume work is available. Query first:

// Wrong
await upsert_issue("ISSUE-042", {status: "in_progress"});
// Might be blocked or already in progress!

// Right
const ready = await ready();
if (ready.issues.includes("ISSUE-042")) {
  await upsert_issue("ISSUE-042", {status: "in_progress"});
}

Read specs before implementing

Always review the spec before starting work:

// 1. Claim work
await upsert_issue("ISSUE-051", {status: "in_progress"});

// 2. Read issue for immediate context
const issue = await show_issue("ISSUE-051");

// 3. Read spec for full requirements
const spec = await show_spec("SPEC-005");

// 4. Now implement with full context

Provide feedback on ambiguities

Don’t block on unclear requirements. Provide feedback and continue:

// Discovered ambiguity on line 23
await add_feedback({
  issue_id: "ISSUE-051",
  spec_id: "SPEC-005",
  content: "Token expiration not specified. Using 15min/7d (industry standard).",
  type: "request",
  line: 23
});

// Continue with reasonable assumption
const ACCESS_TOKEN_TTL = 15 * 60; // 15 minutes

Update issue descriptions on close

When closing, document what was done:

await upsert_issue("ISSUE-051", {
  status: "closed",
  description: issue.description + `\n\n## Completed\n
- Implemented token exchange endpoint
- Set up Redis storage with encryption
- Added token expiration (15min access, 7d refresh)
- Wrote integration tests

## Notes
- Used industry-standard expiration times
- Provided feedback on SPEC-005 for clarification
`
});

Comparison to Traditional Workflows

Aspect	Traditional	Spec-Driven
Requirements	Google Docs, Notion	Version-controlled markdown
Drift	Requirements diverge from code	Continuous sync via feedback
Context	Lost over time	Durable and queryable
Agent autonomy	Limited (unclear requirements)	High (clear specs, ready work)
Feedback loop	Slow (meetings, async comments)	Fast (anchored feedback)
Dependencies	Implicit (tribal knowledge)	Explicit (graph relationships)
Parallelization	Manual coordination	Automatic (graph-based)
Progress tracking	Manual updates	Automatic (status queries)

Common Patterns

Pattern: Spec-First Feature Development

# 1. Human creates spec
sudocode spec create "New Feature" --priority 0

# 2. Human or agent breaks down into issues
# (via MCP or CLI)

# 3. Agents execute in dependency order
# (automated via ready() queries)

# 4. Agents provide feedback during implementation
# (via add_feedback())

# 5. Human refines spec based on feedback
# (edit spec markdown)

# 6. New issues created if needed
# (discovered during implementation)

# 7. Spec marked complete when all issues closed
sudocode spec update SPEC-001 --status completed

Pattern: Multi-Agent Parallel Development

Agent 1: ready() → ISSUE-001 (OAuth setup)
Agent 2: ready() → ISSUE-003 (Database schema)
Agent 3: ready() → ISSUE-005 (API design)

All work independently (no dependencies)

Agent 1 completes → ISSUE-002 unblocked
Agent 2: ready() → ISSUE-002 (OAuth integration)

Iteration 1:
  Spec: "Build search feature"
  Agent: Implements basic search
  Feedback: "Ranking algorithm not specified"

Iteration 2:
  Spec updated: "Use TF-IDF for ranking"
  Agent: Implements TF-IDF
  Feedback: "Performance on large datasets?"

Iteration 3:
  Spec updated: "Target: <100ms for 10M documents"
  Agent: Optimizes with caching
  Complete!

Pattern: Hierarchical Spec Organization

SPEC-001: E-commerce Platform (epic)
  ├─ SPEC-002: Product Catalog
  │    ├─ ISSUE-010: Product model
  │    ├─ ISSUE-011: Search API
  │    └─ ISSUE-012: Product images
  ├─ SPEC-003: Shopping Cart
  │    ├─ ISSUE-020: Cart model
  │    ├─ ISSUE-021: Add to cart
  │    └─ ISSUE-022: Checkout flow
  └─ SPEC-004: Payment Integration
       ├─ ISSUE-030: Stripe setup
       └─ ISSUE-031: Payment flow

Troubleshooting

No issues are ready (everything blocked)

Cause: Circular dependencies or all work depends on blocked itemsSolution:

# Find what's blocking work
sudocode blocked

# Output shows:
# ISSUE-010 blocked by ISSUE-009
# ISSUE-009 blocked by ISSUE-008
# ISSUE-008 blocked by external dependency

# Create issue for external dependency
sudocode issue create "External API integration" --priority 0

# Link properly
sudocode link ISSUE-100 ISSUE-008 --type blocks

# Now ISSUE-100 is ready

Specs drift from implementation

Cause: Agents not providing feedback, or humans ignoring feedbackSolution:

Train agents to use add_feedback() liberally
Review feedback regularly: sudocode feedback list --status open
Make spec updates part of PR review process
Dismiss feedback only after spec updated

Too many issues created upfront

Cause: Over-planning before implementation learningsSolution:

Create only foundation issues initially
Use discovered-from relationship for issues found during work
Allow specs to evolve based on implementation reality
Embrace iterative planning

Feedback anchors become stale

Cause: Large spec refactorings move contentSolution:

# Find stale feedback
sudocode feedback stale

# Output:
# FEEDBACK-001 on SPEC-005:23 (stale - line moved)

# Relocate manually if needed
sudocode feedback relocate FEEDBACK-001 --line 45

# Or dismiss if no longer relevant
sudocode feedback dismiss FEEDBACK-001 --comment "Spec restructured, no longer applicable"

Specs Concept

Deep dive into specifications

Feedback System

Anchored feedback mechanics

Agent Workflows

MCP workflow examples

CLI Reference

Command-line tools

Graph Planning

Dependency graph concepts

MCP Tools

AI agent integration

Next Steps

Create your first spec

sudocode spec create "Your Feature Name" --priority 0

Break it down into issues

Manually or ask an AI agent to create implementation plan

Let agents execute

Agents query ready(), claim work, provide feedback

Review and iterate

Update specs based on feedback, create new issues as needed

Track progress

sudocode status
sudocode blocked

Complete Example Project

See a full feature built with spec-driven development

Getting Started

Core Concepts

Examples & Tutorials

​What is Spec-Driven Development?

​Core Principles

Durable Context

Bidirectional Feedback

Graph-Based Planning

Agent Autonomy

​How sudocode Implements SDD

​1. Specs as First-Class Entities

​2. Issues Implement Specs

​3. Anchored Feedback System

​4. Dependency Graph

​5. Multi-Agent Coordination

​The Spec-Driven Development Workflow

​Complete Example Walkthrough

​Phase 1: Specification

​Phase 2: Planning

​Phase 3: Execution

​Phase 4: Feedback Integration

​Phase 5: Completion

​Best Practices

​For Humans

​For AI Agents

​Comparison to Traditional Workflows

​Common Patterns

​Pattern: Spec-First Feature Development

​Pattern: Multi-Agent Parallel Development

​Pattern: Feedback-Driven Spec Refinement

​Pattern: Hierarchical Spec Organization

​Troubleshooting

​Related Documentation

Specs Concept

Feedback System

Agent Workflows

CLI Reference

Graph Planning

MCP Tools

​Next Steps

Complete Example Project

What is Spec-Driven Development?

Core Principles

How sudocode Implements SDD

1. Specs as First-Class Entities

2. Issues Implement Specs

3. Anchored Feedback System

4. Dependency Graph

5. Multi-Agent Coordination

The Spec-Driven Development Workflow

Complete Example Walkthrough

Phase 1: Specification

Phase 2: Planning

Phase 3: Execution

Phase 4: Feedback Integration

Phase 5: Completion

Best Practices

For Humans

For AI Agents

Comparison to Traditional Workflows

Common Patterns

Pattern: Spec-First Feature Development

Pattern: Multi-Agent Parallel Development

Pattern: Feedback-Driven Spec Refinement

Pattern: Hierarchical Spec Organization

Troubleshooting

Related Documentation

Next Steps