iterate

What this skill does

# kenken Iterate Workflow

> **For Claude:** This skill orchestrates development through 4 stages. Follow each stage sequentially. Do not skip phases.

## When to Use

```dot
digraph when_to_use {
    "Task requires implementation?" [shape=diamond];
    "Has spec or requirements?" [shape=diamond];
    "Need structured workflow?" [shape=diamond];
    "Use kenken:iterate" [shape=box style=filled fillcolor=lightgreen];
    "Use superpowers:brainstorming first" [shape=box];
    "Manual implementation" [shape=box];

    "Task requires implementation?" -> "Has spec or requirements?" [label="yes"];
    "Task requires implementation?" -> "Manual implementation" [label="no - research only"];
    "Has spec or requirements?" -> "Need structured workflow?" [label="yes"];
    "Has spec or requirements?" -> "Use superpowers:brainstorming first" [label="no - explore first"];
    "Need structured workflow?" -> "Use kenken:iterate" [label="yes"];
    "Need structured workflow?" -> "Manual implementation" [label="no - simple task"];
}
```

## Overview

**Stages:** PLAN → IMPLEMENT → TEST (optional) → FINAL

```dot
digraph workflow {
    rankdir=LR;

    subgraph cluster_plan {
        label="PLAN";
        "1.1 Brainstorm" -> "1.2 Write Plan" -> "1.3 Plan Review";
    }

    subgraph cluster_implement {
        label="IMPLEMENT";
        "2.1 Implementation" -> "2.2 Code Simplify" -> "2.3 Implement Review";
    }

    subgraph cluster_test {
        label="TEST (optional)";
        "3.1 Test Plan" -> "3.2 Write Tests" -> "3.3 Coverage" -> "3.4 Run Tests" -> "3.5 Test Review";
    }

    subgraph cluster_final {
        label="FINAL";
        "4.1 Codex Final" -> "4.2 Suggest Extensions";
    }

    "1.3 Plan Review" -> "2.1 Implementation";
    "2.3 Implement Review" -> "3.1 Test Plan" [label="if enabled"];
    "2.3 Implement Review" -> "4.1 Codex Final" [label="if disabled"];
    "3.5 Test Review" -> "4.1 Codex Final";
    "4.2 Suggest Extensions" -> "1.1 Brainstorm" [label="user accepts" style=dashed];
}
```

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

**Config file:** `.claude/kenken-config.json`

## Initialization

1. Load configuration (see Configuration section)
2. Create or read state file
3. If resuming, continue from saved phase
4. If new, start at Phase 1.1

## Stage 1: PLAN

Complete all phases before advancing to IMPLEMENT.

### Phase 1.1: Brainstorm

**Goal:** Understand the problem and design a production-ready solution.

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

**Prompt:** See `prompts/brainstorm.md`

**Actions:**

1. Read existing code to understand context
2. Dispatch parallel agents to research:
   - Existing patterns in codebase
   - Requirements and constraints
   - Edge cases and failure modes
   - Security considerations
3. Ask clarifying questions (one at a time)
4. Propose 2-3 approaches with honest trade-offs, addressing:
   - Core functionality
   - Error handling strategy
   - Edge cases and boundary conditions
   - Security implications
   - Observability (logging, monitoring)
   - Maintainability
5. Get user agreement on approach
6. Save design to `docs/plans/{date}-{topic}-design.md`

**Exit criteria:** Design documented and approved.

### Phase 1.2: Write Plan

**Goal:** Create detailed implementation plan with tasks in Task API format.

**Skill:** `superpowers:writing-plans`

**Actions:**

1. Break design into tasks (each 2-5 minutes of work)
2. For each task, specify:
   - Files to create/modify
   - Exact code changes
   - How to verify it works
3. Include logging requirements (adopt repo conventions)
4. **Convert each task to Task API format:**

```yaml
tasks:
  - id: 1
    description: "Short description (3-5 words)"
    subagent_type: "general-purpose" # or Bash, Explore, etc.
    prompt: |
      Full prompt for the subagent including:
      - What to implement
      - Files to create/modify
      - Exact code to write
      - How to verify
    dependencies: [] # task IDs this depends on
```

5. Save plan to `docs/plans/{date}-{topic}-plan.md`

**Task API Format Reference:**

| Field               | Required | Description                                                             |
| ------------------- | -------- | ----------------------------------------------------------------------- |
| `id`                | Yes      | Unique task identifier (number)                                         |
| `description`       | Yes      | Short description for Task tool (3-5 words)                             |
| `subagent_type`     | Yes      | Agent type: `general-purpose`, `Bash`, `Explore`, etc.                  |
| `prompt`            | Yes      | Full prompt with all context needed                                     |
| `dependencies`      | No       | List of task IDs that must complete first                               |
| `model`             | No       | Override model: `sonnet`, `opus`, `haiku`, or versioned like `opus-4.5` |
| `run_in_background` | No       | Run async: `true`/`false`                                               |

**Exit criteria:** Plan saved with all tasks in Task API format.

### Phase 1.3: Plan Review

**Goal:** Validate plan quality before implementation.

**Tool:** Configured tool (default: `mcp__codex-high__codex`)

**Prompt:** See `prompts/plan-review.md`

**Actions:**

1. Submit plan for review
2. If issues found:
   - Fix the plan
   - Re-run review (increment retryCount)
3. If approved, advance to IMPLEMENT stage

**On failure:** Retry (max configured retries). After max, ask user.

## Stage 2: IMPLEMENT

Complete all phases before advancing to TEST or FINAL.

### Phase 2.1: Implementation

**Goal:** Execute the plan task by task.

**Implementer (from config `stages.implement.implementation.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

**Actions:**

1. Load plan from `docs/plans/{date}-{topic}-plan.md`
2. Parse the `tasks:` YAML block into task list
3. Check `stages.implement.implementation.implementer` config:

#### Claude Mode (default)

Create TodoWrite with all tasks. For each task (respecting `dependencies`):

- Mark task in_progress in TodoWrite
- **Dispatch using Task tool:**
  ```
  Task(
    description: task.description,
    prompt: task.prompt,
    subagent_type: task.subagent_type,
    model: task.model,  // optional
    run_in_background: task.run_in_background  // optional
  )
  ```
- Add logging (match repo conventions, include error context)
- Dispatch spec reviewer subagent
- Dispatch code quality reviewer subagent
- Mark task completed in TodoWrite

**Parallel execution:** Tasks with no unmet dependencies can run in parallel using `run_in_background: true`

Commit after each task or logical group.

#### Codex Mode (codex-high or codex-xhigh)

Invoke the configured Codex tool with implementation prompt:

```
Implement the following tasks from the plan at docs/plans/{date}-{topic}-plan.md

For each task:
1. Read the task requirements
2. Write the code following TDD:
   - Write failing test first (if applicable)
   - Implement minimal code to pass
   - Verify tests pass
3. Follow existing code patterns and conventions
4. Add appropriate logging and error handling

Run these commands after implementation:
1. make lint (if available)
2. make test (if available)

If tests fail, fix issues and re-run until passing.
```

Commit after implementation is complete.

**Logging requirements (both modes):**

- Detect repo's logging library (winston, pino, console, etc.)
- Add logs at: function entry, errors, warnings, state changes
- Error logs must include: message, stack, context

**Exit criteria:** All tasks completed and committed.

### Phase 2.2: Code Simplify

**Goal:** Reduce complexity while preserving functionality.

**Plugin:** `code-simplifier:code