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