Sudocode

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

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