/sudocode

name: sudocode
description: ALWAYS use this skill for ALL sudocode spec and issue operations. Use when user mentions "spec", "issue", "ready", "blocked", "implement", "feature", "plan", or "feedback" with sudocode specs and issues. PROACTIVELY use at start of implementation tasks to check ready issues and understand work context. Operations include viewing (show_spec, show_issue, list_issues, list_specs), creating/modifying (upsert_spec, upsert_issue), planning features, breaking down work, creating dependency graphs, and providing implementation feedback.

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 circ