workflow

name: workflow description: Use when starting any non-trivial coding task, implementing features, or fixing complex bugs. Orchestrates Brainstorm → Plan → Execute → Verify → Close with plan-first discipline.

Workflow: Structured AI Development

Addresses three AI limitations: no memory, shortcut-taking, black-box code.

Concepts and mental models: see CONCEPTS.md

Core Principle

Plan first, code later. The first deliverable is always a plan, never code.

Workflow State Management

State File

• Location: .claude/workflow-state/{slug}.json
• Slug: from task description — lowercase, hyphens, max 60 chars

Schema (v2)

{
  "version": 2,
  "slug": "implement-feature-x",
  "task_description": "Implement feature X",
  "created_at": "2026-02-27T10:30:00Z",
  "updated_at": "2026-02-27T11:45:00Z",
  "ttl_days": 30,
  "current_step": 2,
  "status": "in_progress",
  "steps": {
    "1": { "status": "completed", "started_at": "...", "completed_at": "...", "notes": "..." },
    "2": { "status": "in_progress", "started_at": "...", "approved": false, "notes": "" },
    "3": { "status": "pending" },
    "4": { "status": "pending" },
    "5": { "status": "pending" }
  },
  "decisions": [],
  "artifacts": { "plan_file": null, "branch": null, "pr_url": null }
}

Decision Entry Schema

Each entry in the decisions array:

{
  "step": 1,
  "topic": "Authentication approach",
  "choice": "JWT with refresh tokens",
  "rationale": "Stateless, simpler horizontal scaling",
  "timestamp": "2026-02-27T10:45:00Z"
}

Status values: "pending" | "in_progress" | "completed" | "skipped" Workflow status: "in_progress" | "paused" | "aborted" | "completed"

Prerequisite Table

Gate Check Protocol

Before entering any step:

1. Read .claude/workflow-state/{slug}.json
2. Check prerequisites from the table above
3. If NOT met → STOP, tell user: "Cannot enter Step {N}: Step {X} is {actual_status}."
4. If met → update state: steps.{N}.status = "in_progress", current_step = N

On step completion: set status = "completed", completed_at, update notes.

Starting a New Workflow

1. Generate slug from task description
2. Scan .claude/workflow-state/*.json for existing workflows:
   • Found in_progress → ask: Resume / Pause old + start new / Abort old + start new
   • Found expired (created_at + ttl_days < now) → auto-mark aborted, notify user
   • Max 1 in_progress workflow at a time
3. mkdir -p .claude/workflow-state and write initial state file
4. Run Session Hook, then enter Step 1

Session Hook: Context Recovery

Not a step. Runs automatically when /workflow is invoked.

1. Read CLAUDE.md + memory files
2. git log --oneline -20
3. Scan workflow state files:
   • in_progress → offer resume
   • Expired → auto-abort
4. Output 1-3 sentence context summary
5. Clean up stale state files:
   • completed + older than ttl_days → delete file
   • aborted + older than ttl_days → delete file
   • Log: "Cleaned up N expired workflow state files."

Step 1: Brainstorm

Goal: Human-AI alignment before any code.

Invoke superpowers:brainstorming if available.

Skip conditions (hard rules, not AI judgment):

• User explicitly says "skip brainstorm" or "just plan"
• Task comes from a detailed spec/design doc (user provides path)

Process:

1. Read relevant code files, understand current state
2. Identify constraints and non-negotiables
3. List ambiguities as a structured list — ASK user one at a time
4. Propose 2-3 approaches with trade-offs and recommendation
5. Wait for user decision

Delegate UP (never guess):

• Design decisions with multiple valid options
• Domain-specific correctness requirements
• Trade-offs between competing goals
• Naming and API design choices

On completion: record decisions in decisions array.

Step 2: Plan

Goal: Concrete, reviewable plan. The plan IS the first deliverable.

Invoke superpowers:writing-plans if available.

Gate: Step 1 completed or skipped.

Plan template:

## Plan: [Task Title]

### Sub-tasks
1. [ ] [action] — `path/to/file`
2. [ ] [action] — `path/to/file`

### Acceptance Criteria
- [ ] All existing tests pass
- [ ] New tests cover changes
- [ ] [domain-specific criteria]

### Risks
- [known risks or edge cases]

### Context Strategy
- [ ] Single context / Sub-agent decomposition needed

### Rollback Strategy
- If rollback needed: [specific git operations]

Approval flow:

• User approves → steps.2.approved = true, status = "completed"
• User requests changes → revise, stay in_progress
• User cancels → workflow.status = "aborted"

→ Set artifacts.plan_file to the path of the written plan file.

Step 3: Execute

Goal: Implement the approved plan. Nothing more, nothing less.

Invoke superpowers:executing-plans if available.

Gate: Step 2 completed AND approved: true.

→ Set artifacts.branch to the feature branch name upon creation.

Process:

for sub_task in plan:
    1. Mark sub_task in_progress (TodoWrite)
    2. Implement code + write tests alongside
    3. Run relevant tests
    4. Mark sub_task completed
    5. If plan deviation detected:
       Level 1 (cosmetic, <5 lines) → log in context_notes, continue
       Level 2 (new/delete file, interface change) → STOP, ask user
       Level 3 (plan infeasible) → STOP, roll back to Step 2

Sub-agent strategy:

• Use when: sub-tasks are independent, no shared mutable state, context > 60% full
• Protocol: main agent writes scope → sub-agent executes in worktree → main agent reviews diff

May invoke: workflow:add-model, workflow:add-rule for structured additions.

Step 4: Verify

Goal: Prove implementation is correct, complete, and explainable.

Invoke superpowers:verification-before-completion if available. Auto-invoke: workflow:review-implementation.

Gate: Step 3 completed.

Mandatory checklist (not skippable):

□ 1. Full test suite passes
     Run project test command. If fails: fix code, not tests.

□ 2. Diff traceable to plan
     git diff base...HEAD — every change maps to a plan sub-task.
     Untraceable changes → delete or explain.

□ 3. Acceptance criteria check
     Each criterion from plan: PASS / FAIL.
     Any FAIL → cannot complete Step 4.

□ 4. Explainability
     Every non-trivial change: can explain WHY in one sentence.
     Cannot explain → investigate before proceeding.

Failure handling:

Step 5: Close

Goal: Feedback + persist knowledge + archive. Three phases, one step.

Invoke superpowers:finishing-a-development-branch if available.

Gate: Step 4 completed.

Phase A — Feedback:

1. Show: completed sub-tasks, test results, deviations
2. Ask user for feedback:
   • "No issues" → Phase B
   • Minor fix (< 10 lines) → fix, re-test, Phase B
   • Major change → roll back to Step 2

Phase B — Persist Knowledge: Check if any apply (if none, skip):

• New code pattern or convention established?
• Non-obvious debugging insight discovered?
• New build/test command added?
• Architecture decision made?
• User preference expressed?

If yes → update CLAUDE.md or memory files.

Phase C — Archive:

1. Update state: steps.5.status = "completed", status = "completed"
2. → Set artifacts.pr_url (if a PR was created)
3. Notify user: "Workflow '{task_description}' complete."

Fast-Track

For trivial tasks only. Two conditions (not AI judgment):

1. User explicitly says "simple/trivial, just do it"
2. Pure mechanical change: 1 file, < 5 lines, no behavior change

State updates:

1. Create state file with all steps "pending"
2. Mark steps 1-2 as "skipped" (set steps.2.approved = true to satisfy gate)
3. Execute change (treat as Step 3: mark "in_progress" → "completed")
4. Enter Step 4 (Verify) — gate check passes because Step 3 is completed
5. Enter Step 5 (Close)

Step 4 is never skippable, even on fast-track.

Abort Protocol

Triggered when: user cancels (Step 2), TTL expires, or user explicitly aborts.

1. If code changes exist on a feature branch:
   • Ask user: "Keep branch {branch} for later, or delete it?"
   • Keep → leave branch, note in state
   • Delete → git branch -D {branch}
2. If running in a worktree → clean up worktree
3. Update state: status = "aborted", updated_at, add abort_reason to notes
4. Notify user: "Workflow '{task_description}' aborted. Reason: {reason}"

Skill Composition

Skills call skills to build complex workflows:

workflow:issue-to-pr
  ├─→ superpowers:brainstorming (if ambiguous)
  ├─→ workflow:add-model or workflow:add-rule
  │     └─→ workflow:review-implementation
  ├─→ superpowers:writing-plans
  └─→ Create PR (plan only, then code after review)

Key Principles

1. Human is AI's superpower — delegate UP for creative decisions
2. Plan first — code after approval, never before
3. Context is finite — use sub-agents to manage pressure
4. Tattoos survive resets — update CLAUDE.md to persist knowledge
5. Verify, don't trust — run tests, check diff, review against plan
6. Explainable, not black-box — if you can't explain it, don't commit it
7. State survives sessions — workflow state files prevent step-skipping