# EvanFlow

> A TDD-driven iterative feedback loop for software development with Claude Code, walking ideas from brainstorm through implementation with human checkpoints throughout.

EvanFlow is a TDD-driven iterative feedback loop for software development built on top of Claude Code. It provides 16 cohesive skills and 2 custom subagents that walk an idea from brainstorm through planning, execution, and iteration, with real human checkpoints at every critical stage. The loop is designed as a conductor, not an autopilot — it never auto-commits, never auto-stages, and always stops to await your direction before any git operation.

- **Single entry point** — say *"let's evanflow this"* and the `evanflow-go` orchestrator fires and walks the entire loop automatically.
- **TDD as discipline, not a phase** — `evanflow-tdd` runs vertical-slice RED → GREEN → REFACTOR inside every code-writing task, with assertion-correctness warnings baked in.
- **Human checkpoints** — the loop stops at design approval, plan approval, and after iteration; you stay in control at every gate.
- **Parallel coder/overseer orchestration** — for plans with 3+ independent units, the loop forks into parallel coders (each with vertical-slice TDD) and read-only overseer subagents that can report findings but never modify code.
- **Five Failure Modes checklist** — every iterate phase runs a pass against hallucinated actions, scope creep, cascading errors, context loss, and tool misuse.
- **Git guardrails hook** — a bundled `block-dangerous-git.sh` PreToolUse hook blocks destructive git operations (`git push`, `git reset --hard`, `git clean -f`, etc.) and auto-activates with the plugin install path.
- **Context drift management** — `evanflow-compact` triggers at clean phase boundaries and on drift symptoms to keep long sessions coherent.
- **16 skills covering the full lifecycle** — brainstorming, planning, execution, TDD, iteration, debugging, architecture review, interface design, PRD synthesis, QA, code review, glossary extraction, and more.
- **Three install paths** — Claude Code plugin marketplace (recommended, auto-wires hook), `npx skills@latest add` CLI, or manual copy from the repository.
- **MIT licensed and fully customizable** — every skill has a clear structure and hard rules section designed to be edited and adapted to your project's conventions.

## Features
- TDD-driven iterative feedback loop
- 16 cohesive Claude Code skills
- 2 custom subagents (coder and overseer)
- Single entry point via evanflow-go
- Human checkpoints at design, plan, and iteration stages
- Parallel coder/overseer orchestration for independent tasks
- Vertical-slice TDD per task (RED → GREEN → REFACTOR)
- Five Failure Modes checklist in iterate phase
- Git guardrails hook blocking destructive operations
- Context drift management via evanflow-compact
- Brainstorming with embedded grill/stress-test
- File structure-first planning with deletion test
- Assertion-correctness warnings in TDD
- Visual UI verification via headless Chromium
- Hard cap of 5 iterations
- No auto-commit, no auto-stage, no auto-finish

## Integrations
Claude Code, Bash, jq, Chromium, Google Chrome

## Platforms
WINDOWS, MACOS, LINUX, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/evanklem/evanflow
- Documentation: https://github.com/evanklem/evanflow#readme
- Repository: https://github.com/evanklem/evanflow
- EveryDev.ai: https://www.everydev.ai/tools/evanflow