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:**

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

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

With relation