[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1054":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":15,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":16,"starSnapshotCount":16,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},1054,"evanflow","evanklem\u002Fevanflow","evanklem","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.","",null,"Shell",412,18,385,3,0,4,20,9,3.84,"Other",false,"main",true,[],"2026-06-12 02:00:22","# EvanFlow\n\n**A TDD-driven iterative feedback loop for software development with Claude Code.**\n\n16 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.\n\n```\nbrainstorm → plan → execute (vertical-slice TDD per task) → iterate → STOP\n                    └─ sequential, or parallel coder\u002Foverseer\n```\n\nTDD 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.\n\nThe 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.\n\n---\n\n## Quick Install\n\nThe **recommended** path — Claude Code's plugin marketplace:\n\n```\n\u002Fplugin marketplace add evanklem\u002Fevanflow\n\u002Fplugin install evanflow@evanflow\n```\n\nRestart, then try:\n\n> \"Let's evanflow this — I want to add a small feature that does X.\"\n\n`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., `\u002Fevanflow:evanflow-go`).\n\nSee [Installation](#installation) below for two alternative paths.\n\n---\n\n## What Makes It a Feedback Loop\n\nThe loop is built around **discipline that compounds across iterations**, not single-shot generation. Every step has a checkpoint that gates the next:\n\n- **Brainstorm** clarifies intent, proposes 2–3 approaches with embedded grill (stress-test) → you approve the design\n- **Plan** maps file structure first (deep modules, deletion test) → you approve the plan\n- **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).\n- **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\n- **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\n- **STOP.** Report. Await your direction. The agent never auto-commits, never auto-stages, never proposes a PR\n\nFor plans with 3+ truly independent units, the loop forks into a **parallel coder\u002Foverseer 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.\n\n## Hard Rules Baked Into the Loop\n\nEach 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.\n\n- **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\u002FColumbia \"9 Critical Failure Patterns of Coding Agents\"](https:\u002F\u002Fdaplab.cs.columbia.edu\u002Fgeneral\u002F2026\u002F01\u002F08\u002F9-critical-failure-patterns-of-coding-agents.html).*\n- **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:\u002F\u002Farxiv.org\u002Fpdf\u002F2402.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.\n- **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.*\n- **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:\u002F\u002Fdatalakehousehub.com\u002Fblog\u002F2026-03-context-management-opencode\u002F).*\n- **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.\n- **No skill tax** — opinion. Skills are tools, not a tollbooth.\n\n---\n\n## The Skill Set\n\n### Default Loop (5 skills)\n\n| Skill | Purpose |\n|---|---|\n| `evanflow-brainstorming` | Clarify intent, propose 2–3 approaches with embedded grill (stress-test). Mockup quick-mode for visual-only requests. |\n| `evanflow-writing-plans` | File structure first, bite-sized tasks, embedded grill. Step 2.5 offers `evanflow-coder-overseer` if the plan is parallelizable. |\n| `evanflow-executing-plans` | Task-by-task with inline verification. Step 0 re-offers parallel path. Hands off to iterate, then STOPS. |\n| `evanflow-tdd` | Vertical-slice TDD. One test → one impl → repeat. Behavior through public interface. Assertion-correctness warning. |\n| `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. |\n\n### Special-Purpose (8 skills)\n\n| Skill | Purpose |\n|---|---|\n| `evanflow-go` | **Single entry point.** Say \"let's evanflow this\" and it walks the whole loop. |\n| `evanflow-glossary` | Extract canonical domain terms into `CONTEXT.md`. Flag ambiguities and synonyms. |\n| `evanflow-improve-architecture` | Surface refactor opportunities via the deletion test + deep-modules vocabulary. |\n| `evanflow-design-interface` | \"Design it twice\" — spawn 3+ parallel sub-agents with radically different constraints, compare on depth\u002Fsimplicity\u002Fefficiency. |\n| `evanflow-debug` | Root-cause discipline. Hypothesis stated explicitly, embedded grill before fixing, failing test first. |\n| `evanflow-review` | Both halves of code review (giving + receiving). Don't capitulate to feedback you can't justify. |\n| `evanflow-prd` | Synthesize a PRD from existing context. For substantial new features. |\n| `evanflow-qa` | Conversational bug discovery → issue draft. Asks before filing. |\n\n### Cross-Cutting (1 skill)\n\n| Skill | Purpose |\n|---|---|\n| `evanflow-compact` | Long-session context management. Strategies for proactive summarization at clean boundaries. Drift symptoms checklist. |\n\n### Meta (1 skill)\n\n| Skill | Purpose |\n|---|---|\n| `evanflow` | The index. Shared vocabulary + when to invoke each `evanflow-*` skill. |\n\n### Custom Subagents (2)\n\nIn `agents\u002F` — invoked via `Agent` tool with `subagent_type:` parameter:\n\n| Subagent | Tool restrictions | Purpose |\n|---|---|---|\n| `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. |\n| `evanflow-overseer` | Read, Grep, Glob (no Edit\u002FWrite\u002FBash) | Read-only review subagent. Tools physically enforce \"report findings, never fix.\" |\n\n### Bundled Hook\n\n`hooks\u002Fblock-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.\n\n---\n\n## Hard Rules (apply to every skill)\n\n1. **Never auto-commit, never auto-stage, never auto-finish.** Every git write op requires you to explicitly ask in the current turn.\n2. **Never invent values.** File paths, env vars, IDs, function names, library APIs — if unsure, the agent stops and asks.\n3. **No skill tax.** Ad-hoc questions don't require a skill invocation. Skills are tools, not a tollbooth.\n4. **No forced spec\u002Fplan paths.** Files live where you want them.\n5. **Verify before claiming done.** Quality checks (typecheck, lint, test) run before any \"done\" report.\n\n---\n\n## Requirements\n\n- **[Claude Code](https:\u002F\u002Fclaude.com\u002Fclaude-code)** (any recent version)\n- **Bash** — for the bundled hook script (Linux, macOS, or Windows + WSL)\n- **`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.**\n\nOptional but recommended:\n\n- **`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.\n\n---\n\n## Installation\n\nThree paths, in priority order. All three end with the same skill set in your `.claude\u002Fskills\u002F`. The plugin path additionally auto-wires the guardrail hook.\n\n### Path 1 — Claude Code Plugin Marketplace (recommended)\n\nThis is the cleanest install. Skills, agents, AND the guardrail hook all activate automatically.\n\n```\n\u002Fplugin marketplace add evanklem\u002Fevanflow\n\u002Fplugin install evanflow@evanflow\n```\n\nRestart Claude Code (or `\u002Freload-plugins`). Skills appear namespaced as `\u002Fevanflow:evanflow-go`, `\u002Fevanflow:evanflow-tdd`, etc. Auto-invocation via \"let's evanflow this\" still works regardless of namespace.\n\nTo uninstall: `\u002Fplugin uninstall evanflow@evanflow`.\n\n### Path 2 — `npx skills@latest add` CLI\n\nWorks 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).\n\n```bash\n# Install all 16 skills at once\nnpx skills@latest add evanklem\u002Fevanflow -s '*' -y\n\n# Or install individual skills\nnpx skills@latest add evanklem\u002Fevanflow\u002Fevanflow-go\nnpx skills@latest add evanklem\u002Fevanflow\u002Fevanflow-tdd\n# ...\n```\n\nThis places skills under `~\u002F.claude\u002Fskills\u002F` (global) or `.claude\u002Fskills\u002F` (project, auto-detected).\n\n### Path 3 — Manual Copy\n\nFor users who want full control, no CLI dependencies.\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fevanklem\u002Fevanflow.git\ncd evanflow\n\n# Skills (project-level — adjust to ~\u002F.claude\u002Fskills\u002F for global)\nmkdir -p .claude\u002Fskills\ncp -r skills\u002F* .claude\u002Fskills\u002F\n\n# Agents (custom subagents used by evanflow-coder-overseer)\nmkdir -p .claude\u002Fagents\ncp agents\u002F*.md .claude\u002Fagents\u002F\n\n# Git guardrails hook (optional but recommended)\nmkdir -p .claude\u002Fhooks\ncp hooks\u002Fblock-dangerous-git.sh .claude\u002Fhooks\u002F\nchmod +x .claude\u002Fhooks\u002Fblock-dangerous-git.sh\n```\n\nThen register the hook in your `.claude\u002Fsettings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\\\"$CLAUDE_PROJECT_DIR\\\"\u002F.claude\u002Fhooks\u002Fblock-dangerous-git.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nOptionally, paste `examples\u002FCLAUDE.md.snippet` into your project's `CLAUDE.md` to brief Claude about EvanFlow's conventions.\n\n### Verify Any Install Path\n\nRestart Claude Code. Try saying:\n\n> \"Let's evanflow this — I want to add a small feature that does X.\"\n\n`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\".\n\n---\n\n## Customization\n\nEvery skill has a clear structure with a `## Hard Rules` section. To adapt to your project:\n\n- **Replace `\u003Cfrontend>` and `\u003Cbackend>` placeholders** in skills like `evanflow-writing-plans` with your actual paths if you find yourself answering the same question repeatedly.\n- **Document your project's quality checks** in your `CLAUDE.md` — exact `typecheck`, `lint`, and `test` commands. The skills reference these abstractly.\n- **Adapt the visual verification step** in `evanflow-iterate` if you don't have `chromium` available — substitute `google-chrome --headless` or another tool.\n- **Edit the cohesion contract template** in `evanflow-coder-overseer` to match your project's conventions (your authentication middleware name, your DB write helper, etc.).\n\nThe skills are designed to be edited. Treat them as starting points, not gospel.\n\nIf you fork to make a vendor-specific variant (your-name-flow), great — that's the spirit.\n\n---\n\n## How EvanFlow Works End-to-End\n\n```\nYou say: \"let's evanflow this — I want to add a feature that does X\"\n           │\n           ▼\n       evanflow-go (the conductor)\n           │\n           ├─ Phase 0: Restate idea, scope check\n           ├─ Phase 1: evanflow-brainstorming (CHECKPOINT: design approval)\n           ├─ Phase 2: evanflow-writing-plans (CHECKPOINT: plan approval)\n           │            └─ Step 2.5: parallelization check\n           ├─ Phase 3: evanflow-executing-plans (sequential)\n           │            OR\n           │            evanflow-coder-overseer (parallel)\n           │              ├─ contract with named tests + integration tests\n           │              ├─ RED checkpoint (all coders write failing tests, orchestrator verifies)\n           │              ├─ GREEN phase (vertical-slice TDD per coder)\n           │              ├─ per-coder overseers (review, never fix)\n           │              └─ integration overseer (runs touchpoint tests)\n           ├─ Phase 4: evanflow-iterate (5x cap, Five Failure Modes pass)\n           └─ Phase 5: STOP. Report what was done. Await your direction.\n```\n\nCross-cutting: `evanflow-compact` runs at clean boundaries when context gets heavy.\n\nSpecial-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.\n\n---\n\n## Repository Structure\n\n```\n.\n├── .claude-plugin\u002F\n│   ├── plugin.json          — plugin identity (name, description, version)\n│   └── marketplace.json     — marketplace manifest (lists EvanFlow as one bundled plugin)\n├── skills\u002F                  — 16 SKILL.md folders\n│   ├── evanflow\u002F\n│   ├── evanflow-go\u002F\n│   ├── evanflow-brainstorming\u002F\n│   ... (etc)\n├── agents\u002F                  — 2 custom subagent definitions\n│   ├── evanflow-coder.md\n│   └── evanflow-overseer.md\n├── hooks\u002F\n│   ├── hooks.json           — auto-activated when plugin installs\n│   └── block-dangerous-git.sh\n├── examples\u002F\n│   └── CLAUDE.md.snippet    — for the manual-copy install path\n├── docs\u002F\n│   └── skills-audit.md      — verdict on all 38 candidate skills considered\n├── README.md\n└── LICENSE                  — MIT\n```\n\n---\n\n## Credits\n\nEvanFlow synthesizes ideas from:\n\n- **[mattpocock\u002Fskills](https:\u002F\u002Fgithub.com\u002Fmattpocock\u002Fskills)** by Matt Pocock — vertical-slice TDD, deep modules, deletion test, design-it-twice, ubiquitous language, grill-me, caveman.\n- **[superpowers](https:\u002F\u002Fgithub.com\u002Fobra\u002Fsuperpowers)** by Jesse Vincent — verification-before-completion, code review patterns, parallel agent dispatch, finishing-a-development-branch (the 4-option presentation).\n- **[git-guardrails-claude-code](https:\u002F\u002Fgithub.com\u002Fmattpocock\u002Fskills\u002Ftree\u002Fmain\u002Fgit-guardrails-claude-code)** — bundled in `hooks\u002F` (script copied verbatim). Original by Matt Pocock.\n\nIndustry research informing the design:\n\n- Anthropic's [2026 Agentic Coding Trends Report](https:\u002F\u002Fresources.anthropic.com\u002Fhubfs\u002F2026%20Agentic%20Coding%20Trends%20Report.pdf?hsLang=en)\n- [9 Critical Failure Patterns of Coding Agents (DAPLab, Columbia)](https:\u002F\u002Fdaplab.cs.columbia.edu\u002Fgeneral\u002F2026\u002F01\u002F08\u002F9-critical-failure-patterns-of-coding-agents.html)\n- [Test-Driven Development for Code Generation](https:\u002F\u002Farxiv.org\u002Fpdf\u002F2402.13521) (arXiv 2402.13521) — assertion-correctness findings\n\n---\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n---\n\n## Contributing\n\nIssues 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.\n","EvanFlow 是一个基于测试驱动开发（TDD）的软件开发迭代反馈循环工具。它通过16个连贯技能和2个自定义子代理，引导项目从头脑风暴到计划、执行（每个任务采用垂直切片TDD）、迭代，并在每个阶段设置检查点，确保开发者始终掌控开发过程。该工具支持并行或顺序执行编码与监督任务，适用于希望在保持高质量标准的同时快速迭代的小型功能开发场景。EvanFlow强调在编写代码时融入TDD原则，而非将其作为独立阶段，从而提高代码质量和开发效率。此外，它提供了一种非自动化的流程控制方式，在关键节点如设计批准、计划确认及迭代后停止等待用户指令，避免了不必要的自动化操作。",2,"2026-06-11 02:41:22","CREATED_QUERY"]