evanflow-tdd-loop

What this skill does

```markdown
---
name: evanflow-tdd-loop
description: Use EvanFlow's 16-skill TDD-driven iterative feedback loop for Claude Code to walk ideas from brainstorm through implementation with checkpoints and guardrails.
triggers:
  - "let's evanflow this"
  - "set up evanflow for my project"
  - "use evanflow to build this feature"
  - "run the evanflow loop"
  - "install evanflow skills"
  - "evanflow brainstorm plan execute"
  - "tdd feedback loop with claude code"
  - "evanflow coder overseer parallel"
---

# EvanFlow TDD Loop

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

EvanFlow is a TDD-driven iterative feedback loop for software development with Claude Code. 16 cohesive skills + 2 custom subagents walk an idea from brainstorm → plan → execute → iterate, with real checkpoints where you stay in control. The agent never auto-commits, never auto-stages, never proposes a PR without your explicit direction.

```
brainstorm → plan → execute (vertical-slice TDD per task) → iterate → STOP
                    └─ sequential, or parallel coder/overseer
```

---

## Installation

### Path 1 — Plugin Marketplace (recommended)

Auto-wires all skills, subagents, and the guardrail hook:

```
/plugin marketplace add evanklem/evanflow
/plugin install evanflow@evanflow
```

Restart Claude Code (or `/reload-plugins`). Skills appear as `/evanflow:evanflow-go`, `/evanflow:evanflow-tdd`, etc.

To uninstall: `/plugin uninstall evanflow@evanflow`

### Path 2 — npx CLI (skills only)

```bash
# All 16 skills at once
npx skills@latest add evanklem/evanflow -s '*' -y

# Individual skills
npx skills@latest add evanklem/evanflow/evanflow-go
npx skills@latest add evanklem/evanflow/evanflow-tdd
npx skills@latest add evanklem/evanflow/evanflow-iterate
```

> ⚠️ This path does NOT install the guardrail hook or custom subagents. Add those manually if needed.

### Path 3 — Manual Copy

```bash
git clone https://github.com/evanklem/evanflow.git
cd evanflow

# Skills (project-level)
mkdir -p .claude/skills
cp -r skills/* .claude/skills/

# Custom subagents
mkdir -p .claude/agents
cp agents/*.md .claude/agents/

# Git guardrail hook
mkdir -p .claude/hooks
cp hooks/block-dangerous-git.sh .claude/hooks/
chmod +x .claude/hooks/block-dangerous-git.sh
```

Register the hook in `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}
```

### Requirements

- **Claude Code** (any recent version)
- **Bash** (Linux, macOS, or Windows + WSL)
- **`jq`** — used by the guardrail hook. Install via:
  ```bash
  # macOS
  brew install jq
  # Ubuntu/Debian
  apt install jq
  ```
  > ⚠️ If `jq` is missing, the hook fails silently and dangerous git ops are NOT blocked.
- **`chromium` or `google-chrome`** (optional) — for UI screenshot verification in `evanflow-iterate`. Falls back gracefully if missing.

### Verify Install

Restart Claude Code, then say:

> "Let's evanflow this — I want to add a small feature that does X."

`evanflow-go` should fire and walk you through the loop.

---

## The 16 Skills at a Glance

### Default Loop (invoke in order, or via `evanflow-go`)

| Skill | What it does |
|---|---|
| `evanflow-brainstorming` | Clarifies intent, proposes 2–3 approaches with embedded stress-test. Mockup quick-mode for visual-only requests. |
| `evanflow-writing-plans` | Maps file structure first, creates bite-sized tasks, offers parallel path if 3+ independent units. |
| `evanflow-executing-plans` | Runs tasks sequentially with inline verification. Surfaces blockers. Hands off to iterate, then STOPS. |
| `evanflow-tdd` | Vertical-slice TDD inside each code task: one failing test → minimal impl → refactor → next test. |
| `evanflow-iterate` | Self-review after implementation. Re-reads diff, runs quality checks, screenshots UI, Five Failure Modes checklist. Hard cap: 5 iterations. |

### Single Entry Point

```
evanflow-go   →   Say "let's evanflow this" — orchestrates the full loop.
```

### Special-Purpose Skills

| Skill | When to use it |
|---|---|
| `evanflow-glossary` | Extract canonical domain terms into `CONTEXT.md` |
| `evanflow-improve-architecture` | Surface refactor opportunities (deletion test + deep-modules) |
| `evanflow-design-interface` | "Design it twice" — 3+ parallel sub-agents with different constraints |
| `evanflow-debug` | Root-cause first, hypothesis stated explicitly, failing test before fix |
| `evanflow-review` | Both sides of code review; don't capitulate to feedback you can't justify |
| `evanflow-prd` | Synthesize a PRD from existing context |
| `evanflow-qa` | Conversational bug discovery → issue draft (asks before filing) |
| `evanflow-compact` | Long-session context management; triggers at clean phase boundaries |

### Custom Subagents (in `agents/`)

| Subagent | Tool access | Role |
|---|---|---|
| `evanflow-coder` | Read, Edit, Write, Glob, Grep, Bash, TodoWrite | Implementation — no git ops, no out-of-scope edits |
| `evanflow-overseer` | Read, Grep, Glob only | Read-only review — physically cannot modify code |

---

## Key Workflows

### 1. Full Loop via Single Entry Point

```
User: "Let's evanflow this — add rate limiting to our API"
```

`evanflow-go` fires and sequences:
1. **Brainstorm** — proposes 2–3 approaches, stress-tests each, awaits your design approval
2. **Plan** — maps files first, creates tasks, offers parallel path → awaits your plan approval
3. **Execute** — runs tasks with TDD inside each code task → surfaces any blockers → hands to iterate
4. **Iterate** — self-review loop (max 5), Five Failure Modes check, quality checks
5. **STOP** — reports outcome, awaits your direction. No commits.

### 2. TDD Discipline Inside Execute

`evanflow-tdd` is the discipline inside every code-writing task — not a separate phase:

```
Per task:
  RED:    Write one failing test that specifies behavior via public interface
  GREEN:  Write minimal implementation to pass it
  REFACTOR: Clean up while the test is still your safety net
  → next test
```

Assertion-correctness check: would a one-character bug in the impl still pass this assertion? If yes, the assertion is wrong.

### 3. Parallel Coder/Overseer (3+ independent units)

When `evanflow-writing-plans` detects 3+ truly independent units, it offers the parallel path:

```
Plan with 3 independent modules
→ fork: 3 evanflow-coder subagents (one per module)
       + 3 evanflow-overseer subagents (one per coder, read-only)
       + 1 integration overseer (runs named integration tests at every touchpoint)
```

Integration tests are the executable contract — interfaces can't drift if both sides must satisfy the same passing test.

### 4. Architecture Review

```
User: "evanflow improve architecture on the auth module"
```

`evanflow-improve-architecture` runs the **deletion test** (if you deleted this, what breaks?) and **deep-modules vocabulary** (wide interface, narrow implementation) to surface refactor opportunities.

### 5. Debug with Root-Cause Discipline

```
User: "evanflow debug — users are getting 500s on /api/checkout"
```

`evanflow-debug` sequence:
1. State explicit hypothesis before touching code
2. Embedded stress-test of the hypothesis
3. Write a failing test that reproduces the bug
4. Fix → verify test passes → run full suite

### 6. Context Management for Long Sessions

```
User: "evanflow compact — we've been going for a while"
```

`evanflow-compact` triggers proactive summarization. Drift symptoms it watches for:
- Re-asking questions that were already settled
- Contradicting earlier decisions
- Losing track of which tasks are done vs. pending

---

## Hard Rules (Every Skill Enforces These)

1. **Never auto-commit, never auto-stage, never auto-finish.** Every git write op requires your explicit ask in the current turn.
2. **Never invent