sudocode-workflow

name: sudocode-workflow description: Use when starting implementation tasks, planning features, or managing multi-session work. Enforces spec-first development with proper issue tracking and feedback loops. Integrates sudocode specs/issues with Claude Code's native task system.

Sudocode Workflow

A comprehensive workflow for spec-driven development that balances persistent context (specs/issues) with runtime task tracking.

When to Activate

• Starting a new feature or significant change
• Planning implementation of requirements
• Managing work across multiple sessions
• Beginning a session (check ready for available work)
• Closing issues and documenting learnings

Core Principles

1. Specs BEFORE Issues

Capture user intent and requirements in specs before creating implementation issues. Specs are the "why" - issues are the "what to do about it."

2. Issues BEFORE Tasks

Plan persistent work items (issues) before creating session-scoped tasks. Issues survive sessions; tasks are runtime tracking.

3. Tasks for Runtime, Issues for Persistence

• Tasks (TaskCreate/TaskUpdate): Track progress within a single session
• Issues: Track work across sessions, with dependencies and feedback

4. Feedback ALWAYS on Completion

When closing an issue that implements a spec, provide feedback documenting what was done, decisions made, and learnings.

Workflow Phases

Phase 1: Capture (Spec)

Goal: Extract requirements, design decisions, and context into persistent specs.

When to create a spec:

• User describes a feature or requirement
• Making an architectural decision
• Researching a technical approach
• Documenting context that should persist

Actions:

1. Identify the core intent (what does the user want?)
2. Check for existing related specs: list_specs
3. Create or update spec: upsert_spec
4. Link to related specs using [[s-xxxx]] syntax
5. Use hierarchy (parent/child) for complex features

Spec structure:

# Feature/Decision Title

## Context
Why this is needed, background information

## Requirements
- Specific requirement 1
- Specific requirement 2

## Success Criteria
- [ ] Measurable outcome 1
- [ ] Measurable outcome 2

## Open Questions
- Unresolved decisions

Phase 2: Plan (Issue)

Goal: Break specs into implementable issues with proper dependency graphs.

When to create issues:

• Spec is ready for implementation
• Work can be broken into atomic units
• Need to track multi-session work

Actions:

1. Review spec content: show_spec <id>
2. Identify atomic work units (completable in one session)
3. Create issues: upsert_issue
4. Link to specs: link <issue-id> <spec-id> --type=implements
5. Add dependencies: link <issue-id> <blocker-id> --type=blocks
6. Verify graph: ready (shows unblocked work)

Issue structure:

• Clear, actionable title
• Description with acceptance criteria
• Links to spec via implements
• Dependencies via blocks

Dependency patterns:

Foundation Pattern:
  setup-db blocks api-endpoints
  api-endpoints blocks frontend-integration

Parallel Pattern:
  auth-spec spawns: login-issue, logout-issue, session-issue
  (all can run in parallel, none block each other)

Phase 3: Execute (Tasks)

Goal: Implement issues using runtime task tracking.

Session start protocol:

1. Run: ready (find unblocked work)
2. Run: list_issues status=in_progress (check current work)
3. Claim issue: upsert_issue <id> status=in_progress
4. Load context: show_issue <id>, show_spec <linked-spec-id>

During implementation:

1. Create session tasks: TaskCreate for immediate work
2. Update task status as you progress
3. Keep issue status current (in_progress, blocked if needed)
4. Document discoveries in issue description

Integration with other skills:

• Use tdd-workflow for test-driven implementation
• Use verification-loop before marking complete
• Use coding-standards for code quality

Task vs Issue decision tree:

Will this work span multiple sessions?
  YES → Create issue
  NO → Will it take more than a few steps?
    YES → Create tasks (TaskCreate)
    NO → Just do it directly

Phase 4: Close (Feedback)

Goal: Document implementation results and close the loop.

Before closing an issue:

1. Verify all acceptance criteria met
2. Run verification-loop (build, test, lint)
3. Prepare feedback for implemented specs

Providing feedback:

1. Identify linked spec: show_issue <id> → implements relationship
2. Add feedback: add_feedback
   - to_id: spec being implemented
   - type: comment | suggestion | request
   - content: structured feedback (see template below)
   - Anchor to specific line/section when relevant

Feedback template:

✅ **Requirements met:** [what was implemented per spec]

📝 **Design decisions:** [choices made during implementation]
- Chose X over Y because [reason]

⚠️ **Challenges:** [issues encountered, how resolved]
- [Challenge]: [Resolution]

✅ **Evidence:** [tests, observations, metrics]
- X tests passing
- Verified in [environment]

💡 **Suggestions:** [spec improvements, discovered work]
- Spec could clarify [X]
- Discovered need for [Y] → created [[i-xxxx]]

Closing the issue:

1. Provide feedback on spec: add_feedback
2. Close issue: upsert_issue <id> status=closed
3. Check for newly unblocked work: ready

Decision Trees

When to Create What?

User describes something...

Is it requirements/intent/context?
  YES → Create SPEC
  NO ↓

Is it actionable work?
  YES → Will it span sessions?
    YES → Create ISSUE (link to spec)
    NO → Create TASKS (TaskCreate)
  NO ↓

Is it a quick fix/clarification?
  YES → Just do it, no tracking needed

Spec vs Issue vs Task

Integration Points

With Existing Skills

With Claude Code Native Tools

Quick Reference

Session Start

ready                          # Find unblocked work
list_issues status=in_progress # Check current work
show_issue <id>                # Load context

During Work

TaskCreate                     # Track session progress
upsert_issue status=blocked    # If blocked
show_spec <id>                 # Reference requirements

Closing Out

add_feedback to_id=<spec-id>   # Document results
upsert_issue status=closed     # Close issue
ready                          # Find next work

Common Patterns

Pattern: New Feature

1. User describes feature
2. Create spec capturing requirements
3. Plan issues (break down work)
4. Add dependencies (blocks relationships)
5. Check ready → claim first issue
6. Implement with tasks
7. Provide feedback → close issue
8. Repeat until all issues closed

Pattern: Bug Discovery During Implementation

1. Discover bug while implementing issue
2. Create new issue for bug
3. Link: bug-issue discovered-from current-issue
4. If blocker: bug-issue blocks current-issue
5. Set current issue to blocked (if needed)
6. Fix bug first, then continue

Pattern: Spec Clarification Needed

1. Find ambiguity in spec during implementation
2. Add feedback type=request to spec
3. Continue with best interpretation
4. Document decision in issue
5. Flag for user review

Remember: The goal is to maintain context across sessions while staying productive within sessions. Specs capture intent, issues track work, tasks track progress, feedback closes the loop.