workflow

# Workflow: Structured AI Development Addresses three AI limitations: no memory, shortcut-taking, black-box code. > Concepts and mental models: see [CONCEPTS.md](./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) ```json { "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: ```json { "step": 1, "topic": "Authentication approach", "choice": "JWT with refresh tokens", "rationale": "Stateless, simpler horizontal scaling", "timestamp": "2026-02-27T10:45:00Z" } ``` | Field | Type | Description | |-------|------|-------------| | `step` | number | Step in which the decision was made (1-5) | | `topic` | string | What was being decided | | `choice` | string | The selected option | | `rationale` | string | Why this choice was made | | `timestamp` | string | ISO 8601 timestamp | **Status values**: `"pending"` | `"in_progress"` | `"completed"` | `"skipped"` **Workflow status**: `"in_progress"` | `"paused"` | `"aborted"` | `"completed"` ### Prerequisite Table | Step | Prerequisites | |------|--------------| | 1 | None | | 2 | Step 1 `completed` or `skipped` | | 3 | Step 2 (`completed` or `skipped`) AND `approved: true` | | 4 | Step 3 `completed` | | 5 | Step 4 `completed` | ### 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**: ```markdown ## 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**: | Type | Action | |------|--------| | Test failure (simple) | Fix code, stay in Step 4 | | Test failure (complex, cause unclear) | Invoke `superpowers:systematic-debugging`, stay in Step 4 | | Criteria not met | Supplement implementation, stay in Step 4 | | Plan deficiency | Roll back to Step 2 | | New requirement discovered | Log it, finish current workflow, open new one | --- ## 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