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

Aspect	Spec	Issue	Task
Purpose	Capture intent	Track work	Runtime progress
Lifespan	Persistent	Until closed	Session only
Created by	User intent	Planning phase	Execution phase
Contains	Requirements, decisions	Acceptance criteria	Immediate steps
Links	To other specs	To specs (implements)	None

---

Integration Points

With Existing Skills

Skill	Integration
tdd-workflow	Use after claiming issue, before implementation
verification-loop	Run before closing issue
coding-standards	Apply during implementation
continuous-learning	Patterns extracted become spec suggestions
strategic-compact	Compact between phases (after planning, before executing)

With Claude Code Native Tools

Tool	Usage in Workflow
TaskCreate	Phase 3 - runtime tracking
TaskUpdate	Phase 3 - progress updates
TaskList	Phase 3 - check session progress
EnterPlanMode	Phase 2 - complex planning

---

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.