// 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.
| 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. |
A comprehensive workflow for spec-driven development that balances persistent context (specs/issues) with runtime task tracking.
ready for available work)Capture user intent and requirements in specs before creating implementation issues. Specs are the "why" - issues are the "what to do about it."
Plan persistent work items (issues) before creating session-scoped tasks. Issues survive sessions; tasks are runtime tracking.
When closing an issue that implements a spec, provide feedback documenting what was done, decisions made, and learnings.
Goal: Extract requirements, design decisions, and context into persistent specs.
When to create a spec:
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
Goal: Break specs into implementable issues with proper dependency graphs.
When to create issues:
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:
implementsblocksDependency 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)
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:
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
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
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
| 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 |
| 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) |
| 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 |
ready # Find unblocked work
list_issues status=in_progress # Check current work
show_issue <id> # Load context
TaskCreate # Track session progress
upsert_issue status=blocked # If blocked
show_spec <id> # Reference requirements
add_feedback to_id=<spec-id> # Document results
upsert_issue status=closed # Close issue
ready # Find next work
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
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
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.
Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
Automatically extract reusable patterns from Claude Code sessions and save them as learned skills for future use.
Patterns for providing structured feedback that closes the loop between implementation and requirements. Use when closing issues, documenting implementation decisions, or updating specs with learnings.
Patterns for breaking specs into atomic issues with proper dependency graphs and execution ordering. Use when planning implementation of a spec or organizing complex work.
Patterns for writing effective specs that capture user intent, design decisions, and requirements clearly. Use when creating or updating specs to ensure quality and completeness.
Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests. Integrates with sudocode for issue tracking and feedback.