sudocode: Spec & Issue Management

Spec-driven development and issue management system. Work persists across sessions, specs guide implementation, dependency graphs ensure correct execution order, feedback loops close requirements gaps.

Core Concepts

Specs: Requirements/design documents (markdown in .sudocode/specs/) - user-initiated, capture intent
Issues: Work items with status tracking (markdown in .sudocode/issues/) - agent work, actionable tasks
Feedback: Anchored comments on specs documenting what happened during implementation
Relationships: Dependency graphs between issues and specs (blocks, implements, parent-child, discovered-from)

Create issues when: Concrete actionable work, can be completed and closed, implements a spec, is a bug/task Create specs when: Documenting user intent and requirements, architecture decisions, API designs, feature specifications

Working with the System

Two Ways to Modify Specs/Issues

Option 1: Direct Markdown Editing (For content-heavy edits)

Edit markdown files in .sudocode/specs/ or .sudocode/issues/
Frontmatter contains metadata (id, title, status, relationships, tags)
Content after frontmatter is the body
System syncs bidirectionally
Use direct markdown editing when possible to maintain file structure and reduce content churn

Option 2: MCP Tools (Recommended for structured operations)

Use upsert_issue, upsert_spec, link, add_feedback tools
Automatically syncs to markdown/sqlite/jsonl
Validates relationships and IDs

When to use each:

MCP tools: Status changes, creating entities, adding relationships, adding feedback
Direct editing: Writing detailed content, refactoring descriptions, bulk editing

Obsidian-Style Mentions

Link specs and issues inline using [[ID]] syntax:

Basic reference:
Implement OAuth per [[s-8h2k]]

With display text:
See [[s-8h2k|authentication spec]] for details

With relationship type:
Must complete [[i-7x9m]]{ blocks } first

Formats supported:
- [[s-14sh]] - basic reference (creates "references" relationship)
- [[i-x7k9]] or [[@i-x7k9]] - with @ prefix
- [[s-3s542|Custom Text]] - with display text
- [[s-x4d6df]]{ blocks } - declares relationship type
- [[s-24gfs3|Text]]{ blocks } - both display and relationship

Relationship types in mentions: blocks, implements, depends-on, discovered-from

Why use inline mentions:

Bidirectionally links entities without separate link tool call
Colocate with informational context
Automatically creates relationships during sync
Makes content more readable

Quick Reference

Session Start (Always Do This)

- [ ] Use ready tool to find unblocked work
- [ ] Use list_issues with status=in_progress to see current work
- [ ] Ask user which work to pursue (if not specified)

If you were assigned an issue, work ONLY on implementing the requirements of the issue.

Essential Tools

ready                → Find unblocked work
show_issue/show_spec → Get details with relationships
upsert_issue/spec    → Create/update (status, priority, parent)
link                 → Create relationships (blocks, implements, parent-child)
add_feedback         → Document implementation results on specs

Relationship Types

Type	Purpose	Effect on ready
`implements`	Issue → Spec connection	None (documentation)
`blocks`	Execution ordering	Blocked issue not ready until blocker closes
`parent-child`	Hierarchical organization	None (hierarchy only)
`discovered-from`	Provenance tracking	None (documentation)

Status Flow

Standard flow:

open → in_progress  → closed
  ↓         ↓            ↑
  └─────────┴────────────┘
    blocked (when waiting on dependencies)

When requirements are not fully met or unforeseen issues arise during execution:

in_progress → needs_review → closed

When to Use Hierarchies

Hierarchical specs: Multiple subsystems, multiple layers, natural abstraction levels Hierarchical issues: Epic with subtasks, clear dependencies, progress tracking at different granularity

Pattern: Hierarchical Feature with Dependencies

Example: "Implement authentication system"

Create hierarchy:

s-2a7c: Auth System (parent)
├── s-8h2k: OAuth (child)
├── s-9j3m: Sessions (child)
└── s-4k8p: Permissions (child)

i-5n7q: Implement auth (parent epic, implements s-2a7c)
├── i-7x9m: OAuth flow (child, implements s-8h2k)
├── i-3p6k: Session storage (child, implements s-9j3m)
└── i-8w2n: Permissions (child, implements s-4k8p)

Add execution order:

link: i-7x9m blocks i-3p6k (OAuth before sessions)
link: i-3p6k blocks i-8w2n (sessions before permissions)

Result: ready shows i-7x9m → close it → ready shows i-3p6k → etc.

Dependency Graphs

Use blocks for: Execution ordering (A must finish before B starts) Use parent-child for: Hierarchical organization (tracking progress at multiple levels) Use both: Parent-child for hierarchy + blocks for ordering

Building Dependency Graphs

- [ ] Identify foundation work (must happen first)
- [ ] Identify parallel work (no dependencies)
- [ ] Create all issues first (don't worry about order)
- [ ] Add parent-child for hierarchy
- [ ] Add blocks for execution order
- [ ] Verify no circular dependencies
- [ ] Use ready to verify graph correct

Pattern: Foundation blocks everything else → parallel work in middle → validation at end

Feedback Loop

Always provide feedback when implementing specs.

When to Provide Feedback

Complete implementing an issue that references a spec
Discover requirements were unclear/incomplete
Encounter implementation challenges not in spec
Make design decisions that deviate from spec
Have evidence requirements were met (tests, observations)

Feedback Checklist

- [ ] Update issue status
- [ ] Use add_feedback on spec with requirements met, design decisions, challenges, evidence
- [ ] Choose type: comment (informational), suggestion (spec update), request (clarification)
- [ ] Anchor feedback to relevant spec sections

Feedback Pattern Example

Good feedback:

✅ Requirements met: OAuth flow working per spec
📝 Design decisions: Used Redis for tokens (horizontal scaling), added rate limiting
⚠️ Challenges: PKCE needed for mobile (not in spec), token refresh race condition solved with 10s buffer
✅ Evidence: 47 tests passing, 3 OAuth providers tested, security scan clean
💡 Suggestions: Add mobile requirements, document token refresh edge case

Bad feedback: "Implemented the feature. It works."

Status Transitions

closed vs request_review

Close (status=closed) when:

All requirements met
Tests passing with good coverage
Confident in approach
No blocking questions

Set needs_review when:

Uncertain about approach (multiple valid options)
Partial completion (need priority guidance)
Quality concerns
Spec ambiguities found
Trade-offs need approval

Self-check: "Could another developer deploy this to production as-is?"

Yes confidently → Close
Yes with caveats → Close + flag concerns in feedback
Need guidance → Set needs_review + request clarification
Incomplete → Set needs_review + explain gaps

Closing Checklist

- [ ] All requirements met
- [ ] Tests passing
- [ ] No blocking questions
- [ ] Implementation sound or uncertainties flagged
- [ ] Evidence provided
- [ ] Feedback on spec documenting what was done

If any item is ✗, set needs_review with feedback explaining gaps/questions

Common Workflows

Spec-driven feature: Create spec → Create issues that implement spec → Add blocks dependencies to establish execution order → Use ready to find next work → Provide feedback on spec when done

Bug discovery: Create issue for discovered work → Link with discovered-from → If blocker: add blocks relationship + set original to blocked

Complex hierarchical feature: Create parent spec + child specs → Create parent issue + child issues → Link issues to specs with implements → Add parent-child + blocks relationships → Use ready to execute in order → Provide feedback on each spec

Integration with TodoWrite

Use TodoWrite for: Session-scoped checklists, immediate execution tracking Use Issues for: Multi-session work, dependencies, spec implementation

Pattern: Start session with ready → Create TodoWrite for immediate tasks → Update issue status as you work → Close issue when complete