Skip to content
Back to search

evanflow

MarketplaceWorks with Claude CodeGitHub

A TDD-driven iterative feedback loop for software development. 16 cohesive Claude Code skills walk an idea from brainstorm → plan → execute → iterate, with checkpoints throughout.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/evanklem-evanflow/badge.svg)](/listings/evanklem-evanflow)

HTML

<a href="/listings/evanklem-evanflow"><img src="/api/listings/evanklem-evanflow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The **recommended** path — Claude Code's plugin marketplace:

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

Restart, then try:

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

`evanflow-go` fires and walks the loop. The git-guardrails hook auto-activates with the plugin (no settings.json edit needed). Skills appear under the `evanflow:` namespace (e.g., `/evanflow:evanflow-go`).

See [Installation](#installation) below for two alternative paths.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 36 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "evanflow",
  3. "owner": {
  4. "name": "Evan Klem"
  5. },
  6. "metadata": {
  7. "description": "EvanFlow — a TDD-driven iterative feedback loop for software development with Claude Code. Vertical-slice TDD, parallel coder/overseer review, executable cohesion contracts, context compaction, no auto-commits.",
  8. "version": "1.0.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "evanflow",
  13. "description": "16 skills (default loop + special-purpose + meta) + 2 custom subagents (evanflow-coder, evanflow-overseer) + git-guardrails PreToolUse hook. Single entry point: say 'let's evanflow this' to walk the whole loop end-to-end.",
  14. "source": "./",
  15. "strict": false,
  16. "skills": [
  17. "./skills/evanflow",
  18. "./skills/evanflow-go",
  19. "./skills/evanflow-brainstorming",
  20. "./skills/evanflow-writing-plans",
  21. "./skills/evanflow-executing-plans",
  22. "./skills/evanflow-tdd",
  23. "./skills/evanflow-iterate",
  24. "./skills/evanflow-coder-overseer",
  25. "./skills/evanflow-compact",
  26. "./skills/evanflow-glossary",
  27. "./skills/evanflow-improve-architecture",
  28. "./skills/evanflow-design-interface",
  29. "./skills/evanflow-debug",
  30. "./skills/evanflow-review",
  31. "./skills/evanflow-prd",
  32. "./skills/evanflow-qa"
  33. ]
  34. }
  35. ]
  36. }
README.md · README · 322 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # EvanFlow
  2. **A TDD-driven iterative feedback loop for software development with Claude Code.**
  3. 16 cohesive skills + 2 custom subagents walk an idea from brainstorm through implementation, with checkpoints throughout where you stay in control. One entry point: say *"let's evanflow this"* and the orchestrator runs the loop.
  4. ```
  5. brainstorm → plan → execute (vertical-slice TDD per task) → iterate → STOP
  6. └─ sequential, or parallel coder/overseer
  7. ```
  8. TDD is not a separate phase after execute — it's the discipline *inside* each code-writing task. Execute is the harness (task tracking, blockers, quality checks); `evanflow-tdd` is what runs inside any task that produces production code.
  9. The loop is **conductor, not autopilot**: real checkpoints at design approval, plan approval, and after iteration. The agent stops short of every git operation and waits for your direction. No auto-commits. No forced ceremony. No "must invoke a skill" tax.
  10. ---
  11. ## Quick Install
  12. The **recommended** path — Claude Code's plugin marketplace:
  13. ```
  14. /plugin marketplace add evanklem/evanflow
  15. /plugin install evanflow@evanflow
  16. ```
  17. Restart, then try:
  18. > "Let's evanflow this — I want to add a small feature that does X."
  19. `evanflow-go` fires and walks the loop. The git-guardrails hook auto-activates with the plugin (no settings.json edit needed). Skills appear under the `evanflow:` namespace (e.g., `/evanflow:evanflow-go`).
  20. See [Installation](#installation) below for two alternative paths.
  21. ---
  22. ## What Makes It a Feedback Loop
  23. The loop is built around **discipline that compounds across iterations**, not single-shot generation. Every step has a checkpoint that gates the next:
  24. - **Brainstorm** clarifies intent, proposes 2–3 approaches with embedded grill (stress-test) → you approve the design
  25. - **Plan** maps file structure first (deep modules, deletion test) → you approve the plan
  26. - **Execute** runs task-by-task with inline verification → blockers stop the loop and surface to you. Inside each code-writing task, **TDD** is the discipline (not a separate phase that comes after).
  27. - **TDD** is vertical-slice only and **per-cycle full RED → GREEN → REFACTOR**: one failing test → minimal impl → refactor *while the test you just wrote is still fresh as your safety net* → next test. Refactor is not deferred to the end. Tests verify behavior through public interfaces, so they survive refactors
  28. - **Iterate** re-reads the diff with fresh eyes, runs quality checks, screenshots UI changes, and runs against a Five Failure Modes checklist (hallucinated actions, scope creep, cascading errors, context loss, tool misuse). Hard cap of 5 iterations
  29. - **STOP.** Report. Await your direction. The agent never auto-commits, never auto-stages, never proposes a PR
  30. For plans with 3+ truly independent units, the loop forks into a **parallel coder/overseer orchestration**: one coder per unit (using vertical-slice TDD with a RED checkpoint), one overseer per coder (read-only review subagent that can't modify code), plus an integration overseer that runs named integration tests at every touchpoint. The integration tests *are* the executable contract — interfaces can't drift if both sides have to satisfy the same passing test.
  31. ## Hard Rules Baked Into the Loop
  32. Each rule below cites the source it came from. If a citation is missing, the rule is opinion from running the loop on real projects, not research — labeled as such.
  33. - **Never invent values** — file paths, env vars, IDs, function names, library APIs. If unsure, the agent stops and asks. *Source: action-hallucination is the top failure mode in [DAPLab/Columbia "9 Critical Failure Patterns of Coding Agents"](https://daplab.cs.columbia.edu/general/2026/01/08/9-critical-failure-patterns-of-coding-agents.html).*
  34. - **Assertion-correctness warning** — over 62% of LLM-generated test assertions were incorrect across HumanEval evaluation of four LLMs. *Source: ["Test-Driven Development for Code Generation" (arXiv 2402.13521)](https://arxiv.org/pdf/2402.13521), §3.2.* Both `evanflow-tdd` and the overseer review explicitly check whether a one-character bug in the implementation would still let the assertion pass.
  35. - **Five Failure Modes pass** in iterate + overseer review — hallucinated actions, scope creep, cascading errors, context loss, tool misuse. *Source: synthesized from the DAPLab failure patterns paper above.*
  36. - **Context drift watch** — `evanflow-compact` triggers at clean phase boundaries and on drift symptoms (re-asking settled questions, contradicting earlier decisions). *Source: nearly 65% of enterprise AI failures in 2025 were attributed to context drift or memory loss during multi-step reasoning, not raw context exhaustion — see [Alex Merced, "Context Management Strategies for OpenCode" (March 2026)](https://datalakehousehub.com/blog/2026-03-context-management-opencode/).*
  37. - **Never auto-commit, never auto-stage** — opinion, not research. Came from running the loop on real projects: every time the agent decided to integrate, it integrated wrong.
  38. - **No skill tax** — opinion. Skills are tools, not a tollbooth.
  39. ---
  40. ## The Skill Set
  41. ### Default Loop (5 skills)
  42. | Skill | Purpose |
  43. |---|---|
  44. | `evanflow-brainstorming` | Clarify intent, propose 2–3 approaches with embedded grill (stress-test). Mockup quick-mode for visual-only requests. |
  45. | `evanflow-writing-plans` | File structure first, bite-sized tasks, embedded grill. Step 2.5 offers `evanflow-coder-overseer` if the plan is parallelizable. |
  46. | `evanflow-executing-plans` | Task-by-task with inline verification. Step 0 re-offers parallel path. Hands off to iterate, then STOPS. |
  47. | `evanflow-tdd` | Vertical-slice TDD. One test → one impl → repeat. Behavior through public interface. Assertion-correctness warning. |
  48. | `evanflow-iterate` | Self-review loop after implementation. Re-read diff, fix issues, run quality checks, screenshot UI (via headless Chromium). Five Failure Modes checklist. Hard cap of 5 iterations. |
  49. ### Special-Purpose (9 skills)
  50. | Skill | Purpose |
  51. |---|---|
  52. | `evanflow-go` | **Single entry point.** Say "let's evanflow this" and it walks the whole loop. |
  53. | `evanflow-coder-overseer` | Parallel implementation: coder/overseer pairs + integration overseer + executable cohesion contract. For plans with 3+ independent tasks. |
  54. | `evanflow-glossary` | Extract canonical domain terms into `CONTEXT.md`. Flag ambiguities and synonyms. |
  55. | `evanflow-improve-architecture` | Surface refactor opportunities via the deletion test + deep-modules vocabulary. |
  56. | `evanflow-design-interface` | "Design it twice" — spawn 3+ parallel sub-agents with radically different constraints, compare on depth/simplicity/efficiency. |
  57. | `evanflow-debug` | Root-cause discipline. Hypothesis stated explicitly, embedded grill before fixing, failing test first. |
  58. | `evanflow-review` | Both halves of code review (giving + receiving). Don't capitulate to feedback you can't justify. |
  59. | `evanflow-prd` | Synthesize a PRD from existing context. For substantial new features. |
  60. | `evanflow-qa` | Conversational bug discovery → issue draft. Asks before filing. |
  61. ### Cross-Cutting (1 skill)
  62. | Skill | Purpose |
  63. |---|---|
  64. | `evanflow-compact` | Long-session context management. Strategies for proactive summarization at clean boundaries. Drift symptoms checklist. |
  65. ### Meta (1 skill)
  66. | Skill | Purpose |
  67. |---|---|
  68. | `evanflow` | The index. Shared vocabulary + when to invoke each `evanflow-*` skill. |
  69. ### Custom Subagents (2)
  70. In `agents/` — invoked via `Agent` tool with `subagent_type:` parameter:
  71. | Subagent | Tool restrictions | Purpose |
  72. |---|---|---|
  73. | `evanflow-coder` | Read, Edit, Write, Glob, Grep, Bash, TodoWrite | Implementation subagent for `evanflow-coder-overseer`. Tools + system prompt prevent git ops, out-of-scope edits, value hallucination. |
  74. | `evanflow-overseer` | Read, Grep, Glob (no Edit/Write/Bash) | Read-only review subagent. Tools physically enforce "report findings, never fix." |
  75. ### Bundled Hook
  76. `hooks/block-dangerous-git.sh` — PreToolUse hook that blocks destructive git ops (`git push`, `git reset --hard`, `git clean -f`, `git branch -D`, `git checkout .`, `git restore .`). Auto-activates with the plugin install path.
  77. ---
  78. ## Hard Rules (apply to every skill)
  79. 1. **Never auto-commit, never auto-stage, never auto-finish.** Every git write op requires you to explicitly ask in the current turn.
  80. 2. **Never invent values.** File paths, env vars, IDs, function names, library APIs — if unsure, the agent stops and asks.
  81. 3. **No skill tax.** Ad-hoc questions don't require a skill invocation. Skills are tools, not a tollbooth.
  82. 4. **No forced spec/plan paths.** Files live where you want them.
  83. 5. **Verify before claiming done.** Quality checks (typecheck, lint, test) run before any "done" report.
  84. ---
  85. ## Requirements
  86. - **[Claude Code](https://claude.com/claude-code)** (any recent version)
  87. - **Bash** — for the bundled hook script (Linux, macOS, or Windows + WSL)
  88. - **`jq`** — used by the hook script to parse Claude's JSON tool input. Install via `apt install jq`, `brew install jq`, or your platform's package manager. **If `jq` is missing, the guardrail hook fails silently and dangerous git ops are NOT blocked.**
  89. Optional but recommended:
  90. - **`chromium`** or `google-chrome` — for `evanflow-iterate`'s visual verification of UI changes (`chromium --headless --screenshot=...`). Falls back gracefully if missing — the skill flags it and asks you to verify visually.
  91. ---
  92. ## Installation
  93. Three paths, in priority order. All three end with the same skill set in your `.claude/skills/`. The plugin path additionally auto-wires the guardrail hook.
  94. ### Path 1 — Claude Code Plugin Marketplace (recommended)
  95. This is the cleanest install. Skills, agents, AND the guardrail hook all activate automatically.
  96. ```
  97. /plugin marketplace add evanklem/evanflow
  98. /plugin install evanflow@evanflow
  99. ```
  100. Restart Claude Code (or `/reload-plugins`). Skills appear namespaced as `/evanflow:evanflow-go`, `/evanflow:evanflow-tdd`, etc. Auto-invocation via "let's evanflow this" still works regardless of namespace.
  101. To uninstall: `/plugin uninstall evanflow@evanflow`.
  102. ### Path 2 — `npx skills@latest add` CLI
  103. Works against any GitHub repo with `SKILL.md`-shaped folders. Installs skills only — **does not install the guardrail hook or custom subagents** (you'd add those manually if you want them).
  104. ```bash
  105. # Install all 16 skills at once
  106. npx skills@latest add evanklem/evanflow -s '*' -y
  107. # Or install individual skills
  108. npx skills@latest add evanklem/evanflow/evanflow-go
  109. npx skills@latest add evanklem/evanflow/evanflow-tdd
  110. # ...
  111. ```
  112. This places skills under `~/.claude/skills/` (global) or `.claude/skills/` (project, auto-detected).
  113. ### Path 3 — Manual Copy
  114. For users who want full control, no CLI dependencies.
  115. ```bash
  116. git clone https://github.com/evanklem/evanflow.git
  117. cd evanflow
  118. # Skills (project-level — adjust to ~/.claude/skills/ for global)
  119. mkdir -p .claude/skills
  120. cp -r skills/* .claude/skills/
  121. # Agents (custom subagents used by evanflow-coder-overseer)
  122. mkdir -p .claude/agents
  123. cp agents/*.md .claude/agents/
  124. # Git guardrails hook (optional but recommended)
  125. mkdir -p .claude/hooks
  126. cp hooks/block-dangerous-git.sh .claude/hooks/
  127. chmod +x .claude/hooks/block-dangerous-git.sh
  128. ```
  129. Then register the hook in your `.claude/settings.json`:
  130. ```json
  131. {
  132. "hooks": {
  133. "PreToolUse": [
  134. {
  135. "matcher": "Bash",
  136. "hooks": [
  137. {
  138. "type": "command",
  139. "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
  140. }
  141. ]
  142. }
  143. ]
  144. }
  145. }
  146. ```
  147. Optionally, paste `examples/CLAUDE.md.snippet` into your project's `CLAUDE.md` to brief Claude about EvanFlow's conventions.
  148. ### Verify Any Install Path
  149. Restart Claude Code. Try saying:
  150. > "Let's evanflow this — I want to add a small feature that does X."
  151. `evanflow-go` should fire and walk you through the loop. To verify the guardrail hook (paths 1 and 3 only): try `git reset --hard HEAD` from the Bash tool — it should be blocked with "BLOCKED: ... matches dangerous pattern".
  152. ---
  153. ## Customization
  154. Every skill has a clear structure with a `## Hard Rules` section. To adapt to your project:
  155. - **Replace `<frontend>` and `<backend>` placeholders** in skills like `evanflow-writing-plans` with your actual paths if you find yourself answering the same question repeatedly.
  156. - **Document your project's quality checks** in your `CLAUDE.md` — exact `typecheck`, `lint`, and `test` commands. The skills reference these abstractly.
  157. - **Adapt the visual verification step** in `evanflow-iterate` if you don't have `chromium` available — substitute `google-chrome --headless` or another tool.
  158. - **Edit the cohesion contract template** in `evanflow-coder-overseer` to match your project's conventions (your authentication middleware name, your DB write helper, etc.).
  159. The skills are designed to be edited. Treat them as starting points, not gospel.
  160. If you fork to make a vendor-specific variant (your-name-flow), great — that's the spirit.
  161. ---
  162. ## How EvanFlow Works End-to-End
  163. ```
  164. You say: "let's evanflow this — I want to add a feature that does X"
  165. │
  166. ▼
  167. evanflow-go (the conductor)
  168. │
  169. ├─ Phase 0: Restate idea, scope check
  170. ├─ Phase 1: evanflow-brainstorming (CHECKPOINT: design approval)
  171. ├─ Phase 2: evanflow-writing-plans (CHECKPOINT: plan approval)
  172. │ └─ Step 2.5: parallelization check
  173. ├─ Phase 3: evanflow-executing-plans (sequential)
  174. │ OR
  175. │ evanflow-coder-overseer (parallel)
  176. │ ├─ contract with named tests + integration tests
  177. │ ├─ RED checkpoint (all coders write failing tests, orchestrator verifies)
  178. │ ├─ GREEN phase (vertical-slice TDD per coder)
  179. │ ├─ per-coder overseers (review, never fix)
  180. │ └─ integration overseer (runs touchpoint tests)
  181. ├─ Phase 4: evanflow-iterate (5x cap, Five Failure Modes pass)
  182. └─ Phase 5: STOP. Report what was done. Await your direction.
  183. ```
  184. Cross-cutting: `evanflow-compact` runs at clean boundaries when context gets heavy.
  185. Special-purpose skills (`evanflow-debug`, `evanflow-improve-architecture`, `evanflow-design-interface`, `evanflow-glossary`, `evanflow-prd`, `evanflow-qa`, `evanflow-review`) are pulled in mid-flow when relevant.
  186. ---
  187. ## Repository Structure
  188. ```
  189. .
  190. ├── .claude-plugin/
  191. │ ├── plugin.json — plugin identity (name, description, version)
  192. │ └── marketplace.json — marketplace manifest (lists EvanFlow as one bundled plugin)
  193. ├── skills/ — 16 SKILL.md folders
  194. │ ├── evanflow/
  195. │ ├── evanflow-go/
  196. │ ├── evanflow-brainstorming/
  197. │ ... (etc)
  198. ├── agents/ — 2 custom subagent definitions
  199. │ ├── evanflow-coder.md
  200. │ └── evanflow-overseer.md
  201. ├── hooks/
  202. │ ├── hooks.json — auto-activated when plugin installs
  203. │ └── block-dangerous-git.sh
  204. ├── examples/
  205. │ └── CLAUDE.md.snippet — for the manual-copy install path
  206. ├── docs/
  207. │ └── skills-audit.md — verdict on all 38 candidate skills considered
  208. ├── README.md
  209. └── LICENSE — MIT
  210. ```
  211. ---
  212. ## Credits
  213. EvanFlow synthesizes ideas from:
  214. - **[mattpocock/skills](https://github.com/mattpocock/skills)** by Matt Pocock — vertical-slice TDD, deep modules, deletion test, design-it-twice, ubiquitous language, grill-me, caveman.
  215. - **[superpowers](https://github.com/obra/superpowers)** by Jesse Vincent — verification-before-completion, code review patterns, parallel agent dispatch, finishing-a-development-branch (the 4-option presentation).
  216. - **[git-guardrails-claude-code](https://github.com/mattpocock/skills/tree/main/git-guardrails-claude-code)** — bundled in `hooks/` (script copied verbatim). Original by Matt Pocock.
  217. Industry research informing the design:
  218. - Anthropic's [2026 Agentic Coding Trends Report](https://resources.anthropic.com/hubfs/2026%20Agentic%20Coding%20Trends%20Report.pdf?hsLang=en)
  219. - [9 Critical Failure Patterns of Coding Agents (DAPLab, Columbia)](https://daplab.cs.columbia.edu/general/2026/01/08/9-critical-failure-patterns-of-coding-agents.html)
  220. - [Test-Driven Development for Code Generation](https://arxiv.org/pdf/2402.13521) (arXiv 2402.13521) — assertion-correctness findings
  221. ---
  222. ## License
  223. MIT. See [LICENSE](LICENSE).
  224. ---
  225. ## Contributing
  226. Issues and pull requests welcome. EvanFlow is opinionated by design — proposals to add ceremony or auto-actions will be politely declined. Proposals to **further reduce** ceremony, sharpen rules, or add evidence-backed improvements are very welcome.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.