iteration-workflow

What this skill does

# 9-Phase Iteration Workflow Skill

## When to Use

This skill activates when:

- User invokes `/superpowers-iterate:iterate <task>`
- User asks to "follow the iteration workflow"

**Announce:** "I'm using the iteration-workflow skill to orchestrate this task through all 9 mandatory phases."

## Overview

**Phases:** Brainstorm -> Plan -> Plan Review -> Implement -> Review -> Test -> Simplify -> Final Review -> Codex Final

**Iteration Loop:** Phases 1-8 repeat until Phase 8 finds zero issues or max iterations reached. Phase 9 runs once at the end (full mode only).

**Modes:**

- **Full (default):** Defaults to `mcp__codex-high__codex` for Phases 3, 8 and `mcp__codex-xhigh__codex` for Phase 9 (configurable via `/configure`)
- **Lite (`--lite`):** Uses Claude reviews, skips Phase 9

See AGENTS.md for model configuration and state schema details.

## State Management

**State file:** `.agents/iteration-state.json`

Initialize at start with version 3 schema. Update state after each phase transition. See AGENTS.md for full schema.

## Configuration Loading

**IMPORTANT:** Configuration MUST be loaded fresh each time the workflow is invoked. Always read both global and project config files at the start.

Load configuration using the `configuration` skill. The skill handles:

- Default values
- Merging global config (`~/.claude/iterate-config.json`)
- Merging project config (`.claude/iterate-config.local.json`)

**On each invocation:**

1. Read global config file (if exists)
2. Read project config file (if exists)
3. Merge: defaults → global → project
4. Use merged config for all phases in this run

Run `/superpowers-iterate:configure --show` to see current config.

## Phase 1: Brainstorm

**Purpose:** Explore problem space, generate ideas, clarify requirements

**Required Skill:** `superpowers:brainstorming` + `superpowers:dispatching-parallel-agents`

**Actions:**

1. Mark Phase 1 as `in_progress` in state file
2. Use TodoWrite to track brainstorming tasks
3. **Launch parallel subagents as needed** using `superpowers:dispatching-parallel-agents` (if config allows):
   - Identify independent research areas for the task
   - Dispatch one subagent per independent domain (no limit)
   - Example domains:
     - Research existing code patterns and architecture
     - Explore problem domain and requirements
     - Investigate test strategy and coverage requirements
     - Analyze similar implementations in codebase
     - Research external libraries/APIs needed
     - Explore edge cases and error scenarios
4. Follow `superpowers:brainstorming` process:
   - Ask questions one at a time to refine the idea
   - Propose 2-3 different approaches with trade-offs
   - Present design in 200-300 word sections, validating each
5. Document test strategy requirements during brainstorming:
   - What test frameworks/tools are available?
   - What testing patterns does the codebase use?
   - What edge cases need coverage?
6. Save design to `docs/plans/YYYY-MM-DD-<topic>-design.md`

**Exit criteria:**

- Problem is well understood
- Approach is agreed upon
- Design decisions documented
- Test strategy requirements identified

**Transition:** Mark Phase 1 complete, advance to Phase 2

## Phase 2: Plan

**Purpose:** Create detailed implementation plan with bite-sized tasks including tests

**Required Skill:** `superpowers:writing-plans` + `superpowers:dispatching-parallel-agents`

**Actions:**

1. Mark Phase 2 as `in_progress`
2. **Launch parallel subagents** (if `phases.2.parallel` is true) to create plan components:
   - Identify independent planning areas based on brainstorm output
   - Dispatch one subagent per independent component (no limit)
   - Example planning areas:
     - Plan core implementation tasks
     - Plan test coverage (TDD approach)
     - Plan integration points and edge cases
     - Plan documentation updates
     - Plan migration/upgrade paths
     - Plan performance considerations
3. Follow `superpowers:writing-plans` format:
   - Each task is 2-5 minutes of work
   - Include exact file paths
   - Include complete code in plan
   - Follow DRY, YAGNI, TDD principles
4. **Each task MUST include test steps:**
   - Step 1: Write failing test
   - Step 2: Run test to verify it fails
   - Step 3: Write minimal implementation
   - Step 4: Run test to verify it passes
   - Step 5: Commit
5. Save plan to `docs/plans/YYYY-MM-DD-<feature-name>.md`
6. Document the plan using TodoWrite

**Plan header must include:**

```markdown
# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Test Strategy:** [Testing approach and frameworks]

---
```

**Exit criteria:**

- Implementation plan created with TDD steps
- All tasks have clear acceptance criteria
- Test strategy defined for each task
- Plan follows superpowers:writing-plans format

**Transition:** Mark Phase 2 complete, advance to Phase 3

## Phase 3: Plan Review

**Purpose:** Validate plan quality before implementation begins

**Required Tool (from config `phases.3.tool`):**

- `mcp__codex-high__codex` (default): Codex with medium reasoning
- `mcp__codex-xhigh__codex`: Codex with high reasoning
- `claude-review`: Use `superpowers:requesting-code-review`
- Lite mode always uses `superpowers:requesting-code-review`

**Actions:**

1. Mark Phase 3 as `in_progress` in state file
2. Run review based on configured tool:

### Codex Mode (mcp\_\_codex\_\_codex or mcp\_\_codex-high\_\_codex)

Invoke `mcp__codex-high__codex` with plan review prompt:

```
Review the implementation plan at docs/plans/YYYY-MM-DD-<feature-name>.md

Validate:
- Task granularity (each task should be 2-5 minutes of work)
- TDD steps included for each task
- File paths are specific and accurate
- Plan follows DRY, YAGNI principles
- Test strategy is comprehensive
- Dependencies and task order are correct
- Edge cases are covered

Report findings with severity (HIGH/MEDIUM/LOW) and file:line references.
If you find NO issues, explicitly state: "Plan looks good to proceed."
```

### Claude Review Mode (claude-review or lite mode)

Dispatch code-reviewer subagent via `superpowers:requesting-code-review` to review the plan document.

3. **Evaluate review results:**

   **If ZERO issues found:**
   - Announce: "Plan review passed. Proceeding to implementation."
   - Proceed to Phase 4

   **If HIGH/MEDIUM issues found:**
   - Fix plan issues
   - Re-run plan review
   - Do not proceed until plan is clean

   **If only LOW issues found:**
   - Note them for awareness
   - Proceed to Phase 4

**Exit criteria:**

- Plan review completed
- No HIGH or MEDIUM severity issues in plan
- Plan ready for implementation

**Transition:** Mark Phase 3 complete, advance to Phase 4

## Phase 4: Implement

**Purpose:** TDD-style implementation following the plan

**Implementer (from config `phases.4.implementer`):**

- `claude` (default): Use Claude subagents via `superpowers:subagent-driven-development`
- `codex-high`: Use `mcp__codex-high__codex` for implementation
- `codex-xhigh`: Use `mcp__codex-xhigh__codex` for implementation

**Required Skill (claude mode):** `superpowers:subagent-driven-development` + `superpowers:test-driven-development`

**Required Plugins:** LSP plugins for code intelligence

**Actions:**

1. Mark Phase 4 as `in_progress`
2. Check `phases.4.implementer` config to determine implementation mode:

### Claude Mode (default)

Follow `superpowers:subagent-driven-development` process (model from `phases.4.model`):

- Read plan, extract all tasks, create TodoWrite
- **Launch as many subagents as needed** for implementation:
  - One implementer subagent per task (sequential to avoid conflicts)
  - Multiple reviewer subagents can run in parallel
- For each task:
  a. Dispatch implementer subagent with full task