Workflow Plugin

1# Workflow Plugin
2 
3Structured development workflow for systematic task completion - explore, plan, implement, and deliver.
4 
5## Overview
6 
7The Workflow plugin provides a proven 4-phase development methodology for Claude Code. It guides you from initial requirements exploration through systematic planning, task execution, and final delivery. This workflow ensures thorough analysis, organized implementation, and quality delivery.
8 
9### Relationship to Claude's Built-in Plan Mode
10 
11Claude Code includes a built-in `EnterPlanMode` that provides enhanced reasoning for planning. **Our workflow complements it**:
12 
13| Feature | Built-in Plan Mode | Our Workflow |
14|---------|-------------------|--------------|
15| **Storage** | Global `~/.claude/plans/` | Project-local `.claude/work/` |
16| **Naming** | Auto-generated (`zany-cooking-wombat`) | Date-based (`2025-11-27_01_feature`) |
17| **Execution** | Implements entire plan at once | Incremental via `/next` |
18| **State tracking** | None | `state.json` with task progress |
19| **Session resume** | Cannot resume mid-plan | Work units persist across handoffs |
20| **Parallel execution** | No | `/next --parallel 3` |
21 
22**Best practice**: Use Claude's built-in plan mode *during* `/explore` or `/plan` for enhanced reasoning, while our workflow handles project-local storage and incremental execution. The two work together—you get better planning *and* better organization.
23 
24## The 4-Phase Workflow
25 
26```
27/explore → /plan → /next (repeat) → /ship
28   ↓         ↓          ↓             ↓
29Analyze   Design   Implement      Deliver
30```
31 
32### Phase 1: Explore
33Understand requirements, analyze codebase, identify constraints and opportunities.
34 
35### Phase 2: Plan
36Create detailed implementation plan with ordered tasks, dependencies, and acceptance criteria.
37 
38### Phase 3: Execute
39Implement tasks one at a time with /next, completing the plan systematically.
40 
41### Phase 4: Deliver
42Ship completed work with validation, documentation, and quality assurance.
43 
44## Commands
45 
46### `/explore [source] [--work-unit ID]`
47Explore requirements and codebase with systematic analysis before planning. This is Anthropic's recommended first step for any significant task.
48 
49**What it does**:
50- Analyzes requirements from multiple sources (@file, #issue, description, or interactive)
51- Explores relevant codebase areas to understand context
52- Identifies constraints, dependencies, and risks
53- Documents findings for planning phase
54- Creates work unit for tracking
55 
56**Usage**:
57```bash
58/explore                                    # Interactive exploration
59/explore "Add user authentication"          # From description
60/explore @requirements.md                   # From requirements doc
61/explore #123                               # From GitHub issue
62/explore --work-unit 001                    # Use existing work unit
63```
64 
65**Thoroughness Levels**:
66- `quick`: Basic search and analysis (5-10 minutes)
67- `medium`: Moderate exploration with multiple angles (15-25 minutes)
68- `very thorough`: Comprehensive analysis across codebase (30-45 minutes)
69 
70**Output**:
71- `exploration.md`: Detailed findings and analysis
72- `metadata.json`: Work unit tracking information
73 
74**When to use**:
75- ✅ Starting any non-trivial feature or bug fix
76- ✅ Unclear requirements that need investigation
77- ✅ Unfamiliar codebase areas
78- ✅ Complex changes with many dependencies
79 
80**When to skip**:
81- ❌ Trivial changes (typo fixes, simple updates)
82- ❌ Very clear requirements in familiar code
83- ❌ Quick experiments or spikes
84 
85### `/plan [--from-requirements | --from-issue #123 | description]`
86Create detailed implementation plan with ordered tasks and dependencies using structured reasoning.
87 
88**What it does**:
89- Reviews exploration findings (or analyzes requirements directly)
90- Breaks work into ordered, manageable tasks
91- Identifies dependencies and sequencing
92- Defines acceptance criteria for each task
93- Creates task tracking state file
94 
95**Usage**:
96```bash
97/plan                                       # From latest /explore
98/plan --from-requirements @specs.md         # From requirements doc
99/plan --from-issue #123                     # From GitHub issue
100/plan "Implement OAuth login"               # From description
101```
102 
103**Plan Structure**:
104- **Tasks**: Ordered list with IDs, descriptions, dependencies
105- **Dependencies**: Task relationships and sequencing
106- **Acceptance Criteria**: How to verify completion
107- **Risks**: Potential issues and mitigation strategies
108- **Estimates**: Rough time/complexity estimates
109 
110**Output**:
111- `implementation-plan.md`: Complete task breakdown
112- `state.json`: Task tracking state (pending, in_progress, completed)
113 
114**When to use**:
115- ✅ After /explore for complex work
116- ✅ Multi-step features requiring coordination
117- ✅ Changes affecting multiple files/systems
118- ✅ Work that will span multiple sessions
119 
120**When to skip**:
121- ❌ Single-file, single-function changes
122- ❌ Immediate fixes that are obvious
123- ❌ Exploratory work without clear endpoint
124 
125### `/next [--task TASK-ID | --preview | --status]`
126Execute the next available task from the implementation plan.
127 
128**What it does**:
129- Loads implementation plan and current state
130- Identifies next task based on dependencies
131- Executes the task completely
132- Updates state.json automatically
133- Moves to next task when ready
134 
135**Usage**:
136```bash
137/next                                       # Execute next available task
138/next --preview                             # Show what's next without executing
139/next --status                              # Show plan progress
140/next --task TASK-005                       # Execute specific task
141```
142 
143**Task Execution Flow**:
1441. Load plan and check dependencies
1452. Display current task details
1463. Execute implementation
1474. Verify completion against acceptance criteria
1485. Update state.json (pending → in_progress → completed)
1496. Show progress and next task
150 
151**States**:
152- `pending`: Not yet started
153- `in_progress`: Currently working on
154- `completed`: Finished and verified
155- `blocked`: Waiting on dependencies
156 
157**When to use**:
158- ✅ Systematic implementation of planned work
159- ✅ Multiple tasks that should be done in order
160- ✅ Work that needs tracking across sessions
161- ✅ Complex features with many steps
162 
163**Tips**:
164- Run `/next --status` frequently to see progress
165- Use `/next --preview` before starting if unsure
166- Tasks complete in dependency order automatically
167 
168### `/ship [--preview | --pr | --commit | --deploy]`
169Deliver completed work with validation and comprehensive documentation.
170 
171**What it does**:
172- Reviews completed implementation plan
173- Validates all acceptance criteria met
174- Runs tests and quality checks
175- Creates comprehensive documentation
176- Generates git commits or pull requests
177- Produces delivery summary
178 
179**Usage**:
180```bash
181/ship                                       # Full delivery workflow
182/ship --preview                             # Preview what will be delivered
183/ship --commit                              # Create git commit only
184/ship --pr                                  # Create pull request
185/ship --deploy                              # Prepare for deployment
186```
187 
188**Delivery Checklist**:
189- ✅ All planned tasks completed
190- ✅ Tests passing
191- ✅ Code reviewed (self or automated)
192- ✅ Documentation updated
193- ✅ Breaking changes documented
194- ✅ Migration guides (if needed)
195 
196**Output**:
197- `COMPLETION_SUMMARY.md`: What was delivered and how to use it
198- Git commit or pull request (if requested)
199- Test results and quality metrics
200- Deployment instructions (if applicable)
201 
202**When to use**:
203- ✅ Implementation plan complete
204- ✅ Feature ready for review/merge
205- ✅ All acceptance criteria met
206- ✅ Quality checks passed
207 
208**Options**:
209- `--preview`: See what will be shipped without doing it
210- `--commit`: Create git commit with generated message
211- `--pr`: Create GitHub pull request with summary
212- `--deploy`: Include deployment checklist and instructions
213 
214### `/work [subcommand] [args]`
215Unified work management - list units, continue work, save checkpoints, and switch contexts.
216 
217**What it does**:
218- Lists active, paused, and completed work units
219- Continues work from previous sessions
220- Creates checkpoints for context switching
221- Switches between parallel work streams
222 
223**Usage**:
224```bash
225/work                                      # List all work units
226/work continue                             # Resume last active work unit
227/work checkpoint "Switching to bug fix"    # Save checkpoint before context switch
228/work switch 002                           # Switch to work unit 002
229/work active                               # Show only active work units
230/work completed                            # Show completed work units
231```
232 
233**When to use**:
234- ✅ Managing multiple parallel work streams
235- ✅ Context switching between tasks
236- ✅ Resuming work after interruptions
237- ✅ Tracking work unit status
238 
239### `/spike [topic] [timebox]`
240Time-boxed exploration in isolated branch for investigating uncertain approaches.
241 
242**What it does**:
243- Creates isolated git branch for experimentation
244- Time-boxes exploration (default: 2 hours)
245- Documents findings and recommendations
246- Easy to merge or discard results
247 
248**Usage**:
249```bash
250/spike "GraphQL vs REST API" 2h            # 2-hour spike
251/spike "Redis caching strategy" 1h         # 1-hour spike
252/spike "New authentication library"        # Default 2-hour spike
253```
254 
255**Output**:
256- Isolated git branch (`spike/topic-name`)
257- Findings document with recommendations
258- Code examples (if applicable)
259- Decision: proceed, modify, or abandon
260 
261**When to use**:
262- ✅ High uncertainty in approach
263- ✅ Need to compare multiple solutions
264- ✅ Investigating new libraries or patterns
265- ✅ Risk mitigation before committing to design
266 
267**Benefits**:
268- Isolated from main work (git branch)
269- Time-boxed to prevent rabbit holes
270- Documented findings for future reference
271- Easy to discard if approach doesn't work
272 
273## Complete Workflow Example
274 
275### Example: Adding User Authentication
276 
277```bash
278# Phase 1: Explore
279/explore "Add JWT-based authentication to API"
280 
281# Output: exploration.md with findings:
282# - Existing auth middleware
283# - JWT library already in dependencies
284# - 3 endpoints need protection
285# - User model needs password hashing
286 
287# Phase 2: Plan
288/plan
289 
290# Output: implementation-plan.md with 6 tasks:
291# TASK-001: Add password hashing to User model
292# TASK-002: Create JWT token generation utilities
293# TASK-003: Implement login endpoint
294# TASK-004: Create auth middleware
295# TASK-005: Protect existing endpoints
296# TASK-006: Add integration tests
297 
298# Phase 3: Execute
299/next --status
300# Shows: TASK-001 ready, others pending
301 
302/next
303# Implements TASK-001, updates state.json
304 
305/next
306# Implements TASK-002 (dependency of TASK-001 complete)
307 
308/next
309# ... continues through all tasks
310 
311# Phase 4: Deliver
312/ship --pr
313# Creates pull request with:
314# - Summary of 6 completed tasks
315# - Test results (all passing)
316# - Breaking changes documentation
317# - Migration guide for existing users
318```
319 
320## Integration with Other Plugins
321 
322### System Plugin
323- Uses `/status` to show plan progress
324- Uses `/setup` for project initialization
325- Uses `/audit` for framework compliance
326 
327### Agents Plugin
328- Uses `/agent` for specialized exploration and analysis
329- Uses `/serena` for semantic code understanding
330 
331### Development Plugin
332- `/test` runs during /ship validation
333- `/review` provides code quality feedback
334- `/fix` helps resolve issues found during execution
335 
336### Memory Plugin
337- Auto-loads memory context via @imports
338- Preserves decisions in `decisions.md`
339- Documents lessons in `lessons_learned.md`
340 
341### Git Plugin
342- `/ship --commit` uses `/git commit`
343- `/ship --pr` uses `/git pr`
344- Automatic commit message generation
345 
346## Work Unit Structure
347 
348The workflow creates and maintains this structure:
349 
350```
351.claude/work/current/[work-unit]/
352├── metadata.json              # Work unit metadata
353├── exploration.md             # /explore findings
354├── implementation-plan.md     # /plan task breakdown
355├── state.json                # /next task tracking
356└── COMPLETION_SUMMARY.md     # /ship delivery summary
357```
358 
359## Configuration
360 
361### Exploration Defaults (`.claude/config.json`)
362```json
363{
364  "workflow": {
365    "explore": {
366      "defaultThoroughness": "medium",
367      "autoCreateWorkUnit": true,
368      "explorationAgent": "Explore"
369    }
370  }
371}
372```
373 
374### Planning Defaults
375```json
376{
377  "workflow": {
378    "plan": {
379      "useSequentialThinking": true,
380      "includeTestTasks": true,
381      "includeDocTasks": true
382    }
383  }
384}
385```
386 
387### Delivery Defaults
388```json
389{
390  "workflow": {
391    "ship": {
392      "requireTests": true,
393      "requireDocs": true,
394      "autoCommit": false,
395      "autoPR": false
396    }
397  }
398}
399```
400 
401## Dependencies
402 
403### Required Plugins
404- **claude-code-system** (^1.0.0): System status and configuration
405- **claude-code-memory** (^1.0.0): Memory context loading
406 
407### Optional MCP Tools
408- **Sequential Thinking**: Enhanced planning and exploration analysis
409- **Serena**: Semantic code understanding for exploration
410- **Firecrawl**: Web research for requirements gathering
411 
412**Graceful Degradation**: All commands work without MCP tools.
413 
414## Best Practices
415 
416### When to Use Full Workflow
417 
418✅ **Use /explore → /plan → /next → /ship for**:
419- Multi-file features
420- Unfamiliar codebase areas
421- Complex business logic
422- Work spanning multiple sessions
423- Team collaboration (plan serves as spec)
424 
425### When to Skip Workflow
426 
427❌ **Skip workflow for**:
428- Single-line fixes
429- Documentation updates
430- Typo corrections
431- Configuration tweaks
432- Quick experiments
433 
434### Workflow Variations
435 
436**Quick Mode** (skip /explore):
437```bash
438/plan "Simple, clear task"
439/next
440/ship --commit
441```
442 
443**Investigation Mode** (explore only):
444```bash
445/explore "Complex problem"
446# Review findings, decide approach
447# May not lead to implementation
448```
449 
450**Iterative Mode** (re-plan as you learn):
451```bash
452/explore
453/plan
454/next
455# Discover new requirements
456/plan --update  # Adjust plan
457/next
458/ship
459```
460 
461## Troubleshooting
462 
463### /explore finds nothing
464- Broaden search terms
465- Use `very thorough` mode
466- Manually specify file patterns to search
467- Check if you're in correct directory
468 
469### /plan creates too many tasks
470- Tasks should be 30min - 2hr each
471- Merge small tasks
472- Use subtasks in descriptions
473 
474### /next shows "no tasks available"
475- Run `/next --status` to check dependencies
476- Tasks may be blocked waiting on others
477- Check `state.json` for task states
478 
479### /ship validation fails
480- Review acceptance criteria in plan
481- Run tests manually: `/test`
482- Check code quality: `/review`
483- Fix issues: `/fix`
484 
485## Metrics and Success
486 
487The workflow tracks:
488- **Exploration time**: How long /explore takes
489- **Task completion rate**: Completed vs. total tasks
490- **Plan accuracy**: How often plan matches reality
491- **Quality metrics**: Test coverage, review feedback
492 
493View with:
494```bash
495/status verbose
496/performance
497```
498 
499## Examples
500 
501See `examples/` directory for complete workflow examples:
502- `examples/feature-development/` - Full feature workflow
503- `examples/bug-fix/` - Systematic bug resolution
504- `examples/refactoring/` - Code improvement workflow
505 
506## Support
507 
508- **Documentation**: [Workflow Guide](../../docs/guides/workflow.md)
509- **Issues**: [GitHub Issues](https://github.com/applied-artificial-intelligence/claude-code-toolkit/issues)
510- **Discussions**: [GitHub Discussions](https://github.com/applied-artificial-intelligence/claude-code-toolkit/discussions)
511 
512## License
513 
514MIT License - see [LICENSE](../../LICENSE) for details.
515 
516---
517 
518**Version**: 1.0.0
519**Category**: Workflow
520**Dependencies**: core (^1.0.0), memory (^1.0.0)
521**MCP Tools**: Optional (sequential-thinking, serena, firecrawl)
522