Workflow

Workflow Skill

Manage active multi-phase development workflows using native Claude Code tasks. This skill covers core behavior — routing, status display (including phase-specific guidance), phase transitions, spec doc sync, and acceptance criteria verification. For implementation details (sub-task creation, dependency analysis, pivot handling), see ${CLAUDE_PLUGIN_ROOT}/commands/workflow.md.

Routing

Route based on user intent:

| Input | Action | |-------|--------| | /workflow or "show my workflow" | Show current phase and progress | | /workflow next or "next phase" | Advance to next phase | | /workflow skip or "skip phase" | Skip current phase | | /workflow done or "workflow done" | Mark workflow complete | | /workflow switch or "switch workflow" | Switch between active workflows | | /workflow expand | Create sub-tasks from phase items | | Natural-language status queries (e.g., "where am I", "what should I do next") | Show current phase and progress (same as /workflow) |

Execution

1. Find Current Workflow

CALL TaskList to find tasks with [claude-evolve] prefix.

• One found: Use as current workflow
• Multiple found: List them and let user pick, or suggest /workflow switch
• None found: Show fallback (see Error Handling)

2. Show Status

CALL TaskGet(id) to read task details and metadata.

Read metadata fields: depth, phase, phases_done, phases_skipped, has_phase_tasks, spec_file.

If depth is execute (no phases):

[claude-evolve] Workflow: {subject}
Status: In progress (execute — no phases)
{Task description summary}
Commands: done

Otherwise (depths with phases — design, explore, plan, check):

[claude-evolve] Workflow: {subject}
Phase: {current} | Progress: requirements [OK] -> design [OK] -> implement  design -> implement -> testing |
| `explore` | research -> prototype -> evaluate -> decide |
| `plan` | action -> outcome |
| `check` | verify (single phase) |
| `execute` | No phases — just do it. No phase management needed. |

### 5. Spec Doc Sync

After phase transitions (`next`, `skip`, `done`), update the spec doc:

1. Check if `spec_file` exists in metadata — skip if missing or file not found
2. Read the file, find or append a `## Status` section
3. Update with phase completion info, e.g.:
   ```
   - Phase: implement
   - Completed: requirements, design
   - Next: testing
   ```

See `${CLAUDE_PLUGIN_ROOT}/commands/workflow.md` (Spec Doc Sync sections) for format details and edge cases.

### 6. Sub-Task Management

Sub-task creation is determined by **complexity scoring**, not a fixed item count. The algorithm assesses item count, dependencies, scope, and complexity signals (each Low/Medium/High) to decide whether to skip, suggest, or auto-create sub-tasks.

See `${CLAUDE_PLUGIN_ROOT}/references/complexity-scoring.md` for the scoring algorithm. See `${CLAUDE_PLUGIN_ROOT}/commands/workflow.md` (Intelligent Sub-Task Creation and Working with Sub-Tasks sections) for dependency analysis and sub-task workflows.

### 7. Switch Between Workflows

**CALL TaskList** to find all `[claude-evolve]` tasks. Display an indexed list with subjects and current phases. Let the user pick by number, then show the selected workflow's full status. See `${CLAUDE_PLUGIN_ROOT}/commands/workflow.md` (Switch section) for full output format.

### 8. Expand Phase into Sub-Tasks

Parse the current phase's items from the task description. Use complexity scoring to determine whether to create sub-tasks (see `${CLAUDE_PLUGIN_ROOT}/references/complexity-scoring.md`). See `${CLAUDE_PLUGIN_ROOT}/commands/workflow.md` (Intelligent Sub-Task Creation section) for dependency analysis.

### 9. Handling Pivots

If the user says "let's start over" or significantly changes direction, ask whether to update the existing workflow or create a new one. Updating resets the phase and clears progress; creating a new one marks the old task as "Superseded." See `${CLAUDE_PLUGIN_ROOT}/commands/workflow.md` (Handle Pivots section) for reset and supersede flows.

## Insufficient Context Detection

When showing status or starting work on a phase, check if the project directory has insufficient context. **Heuristic:** fewer than 3 source files (excluding config files like `package.json`, `.gitignore`) and the task requires implementing substantial functionality. If context is insufficient for the current phase:

[claude-evolve] This project doesn't have enough context for me to work effectively.

Recommendation: Do deep research first using Claude on the web (claude.ai) or another research tool, then drop the research report into a file in this project (e.g., research.md). I'll use that context to produce much better results.

This is especially relevant for `design`/`explore` depths where understanding the problem space is critical before implementation.

## Error Handling

| Error | Action |
|-------|--------|
| No `[claude-evolve]` tasks found | Show: "No active workflow. Use /build-project for guided setup or describe your project." |
| Task has no metadata.phase | Treat as freeform task, show status without phase progress |
| Multiple workflows, user doesn't pick | Default to most recently updated task |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hknc](https://github.com/hknc)
- **Source:** [hknc/claude-evolve](https://github.com/hknc/claude-evolve)
- **License:** MIT

Install and usage instructions live in the source repository linked above.