iteration-workflow

What this skill does

# 8-Phase Iteration Workflow Skill

## When to Use

This skill activates when:

- User invokes `/iterate <task>`
- User asks to "follow the iteration workflow"
- User mentions "superpowers iteration" or "8-phase workflow"

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

## The 8 Phases

```
Phase 1: Brainstorm  -> superpowers:brainstorming + N parallel subagents
Phase 2: Plan        -> superpowers:writing-plans + N parallel subagents
Phase 3: Implement   -> superpowers:subagent-driven-development + N subagents
Phase 4: Review      -> superpowers:requesting-code-review (3 rounds)
Phase 5: Test        -> make lint && make test
Phase 6: Simplify    -> code-simplifier agent
Phase 7: Final Review -> @codex-high MCP review (3 rounds)
Phase 8: Codex       -> @codex-xhigh MCP final validation
```

## State Management

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

Initialize at start:

```json
{
  "version": 1,
  "task": "<task description>",
  "startedAt": "<ISO timestamp>",
  "currentPhase": 1,
  "phases": {
    "1": { "status": "in_progress", "startedAt": "<timestamp>" },
    "2": { "status": "pending" },
    "3": { "status": "pending" },
    "4": { "status": "pending" },
    "5": { "status": "pending" },
    "6": { "status": "pending" },
    "7": { "status": "pending" },
    "8": { "status": "pending" }
  }
}
```

Update state after each phase transition.

## 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 as many parallel sonnet subagents as needed** using `superpowers:dispatching-parallel-agents`:
   - 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 as many parallel sonnet subagents as needed** 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: Implement

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

**Required Skill:** `superpowers:subagent-driven-development` + `superpowers:test-driven-development`

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

**Actions:**

1. Mark Phase 3 as `in_progress`
2. Follow `superpowers:subagent-driven-development` process:
   - 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 text AND LSP context:
        ```
        You have access to LSP (Language Server Protocol) tools:
        - mcp__lsp__get_diagnostics: Get errors/warnings for a file
        - mcp__lsp__get_hover: Get type info and documentation at position
        - mcp__lsp__goto_definition: Jump to symbol definition
        - mcp__lsp__find_references: Find all references to a symbol
        - mcp__lsp__get_completions: Get code completions at position

        Use LSP tools to:
        - Check for errors before committing
        - Understand existing code via hover/go-to-definition
        - Find all usages before refactoring
        ```
     b. Answer any questions from subagent
     c. Subagent follows `superpowers:test-driven-development`:
        - Write failing test first
        - Run to verify it fails
        - Write minimal code to pass
        - Run to verify it passes
        - Use `mcp__lsp__get_diagnostics` to check for errors
        - Self-review and commit
     d. Dispatch spec reviewer subagent
     e. Dispatch code quality reviewer subagent (can use LSP diagnostics)
     f. Mark task complete in TodoWrite
3. Run `make lint && make test` to verify all tests pass
4. Commit after tests pass

**Note:** Implementation subagents run sequentially (to avoid file conflicts), but reviewer subagents can run in parallel.

**Exit criteria:**

- All tasks from plan implemented
- Tests written for new functionality (TDD)
- `make lint && make test` pass
- Code committed

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

## Phase 4: Review (3 Rounds)

**Purpose:** Code review with 3 mandatory rounds

**Required Skill:** `superpowers:requesting-code-review`

**Actions:**

1. Mark Phase 4 as `in_progress`
2. Get git SHAs for the changes:
   ```bash
   BASE_SHA=$(git merge-base HEAD main)
   HEAD_SHA=$(git rev-parse HEAD)
   ```
3. For round in [1, 2, 3]:
   a. Dispatch code-reviewer subagent per `superpowers:requesting-code-review`
   b. Provide:
   - WHAT_WAS_IMPLEMENTED: Description of changes
   - PLAN_OR_REQUIREMENTS: Reference to plan file
   - BASE_SHA and HEAD_SHA
     c. Categorize issues:
   - **Critical:** Must fix immediately
   - **Important:** Fix before next round
   - **Minor:** Note for later
     d. Fix Critical and Important issues
     e. Re-run tests after fixes
4. Document findings in state

**Exit criteria:**

- 3 review rounds completed
- No Critical issues remaining
- Important issues addressed

**Transition:** Mark Pha