/evanflow

name: evanflow
description: Meta skill for the EvanFlow system. Loads the shared vocabulary (deep modules, deletion test, vertical slice, grill, mockup quick-mode, no-auto-commit) and describes when to invoke each evanflow-* skill. Use when starting a new task and unsure which evanflow skill applies, or when you need to ground reasoning in the shared vocabulary.

EvanFlow

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 → tdd → iterate, with checkpoints throughout. Vertical-slice TDD, parallel coder/overseer review, executable cohesion contracts, context compaction. Never auto-commits — the user controls every git op.

Single Entry Point: `evanflow-go`

When the user says "let's evanflow this", "use evanflow", "evanflow this idea", "run this through evanflow", or anything similar — invoke `evanflow-go`. It's the orchestrator that walks the entire loop end-to-end (brainstorm → plan → execute → tdd → iterate → STOP), announces each step, respects checkpoints (design approval, plan approval), and hands off to the right sub-skill at each phase. The user gets the full EvanFlow workflow without having to remember which sub-skill applies when.

`evanflow-go` is conductor, not autopilot — every checkpoint is real and the user can interrupt or switch paths anytime.

Shared Vocabulary

Every `evanflow-*` skill speaks this. Cross-reference here, don't redefine.

• **Module** — any unit with interface + implementation (function, class, package). Scale-agnostic.
• **Interface** — complete caller knowledge: type signature, invariants, ordering constraints, error modes, performance characteristics.
• **Depth** — large behavior behind a small interface = deep (good). Large interface, thin behavior = shallow (avoid).
• **Seam** — where an interface lives; a place behavior can shift without editing in place.
• **Adapter** — concrete implementation satisfying an interface at a seam.
• **Deletion test** — does removing this module concentrate complexity across N callers, or does complexity vanish? The first is a real module; the second is bloat.
• **Vertical slice** — one test → one impl → repeat. Never write all tests first then all code (horizontal slicing produces tests of imagined behavior).
• **Behavior through public interface** — tests describe *what*, not *how*. They survive refactors. If a rename breaks a test but behavior didn't change, the test was wrong.
• **Grill** — opt-in interview pattern, embedded as a labeled section inside planning skills. Stress-test before committing to a path. Not a separate skill invocation in EvanFlow.
• **Ubiquitous language** — canonical domain terms in `CONTEXT.md`. New terms added as discovered.
• **Mockup quick-mode** — when user just wants visual concepts, skip spec/plan ceremony. Produce mockups directly in whatever form the project uses (HTML files, Figma frames, ASCII layouts, etc.) — no full design loop required.

Hard Rules (apply to every evanflow skill)

• **Never auto-commit, never auto-stage, never auto-finish.** Every git write op (`commit`, `push`, `merge`, `rebase`, `tag`, `branch -d/-D`) requires the user to explicitly ask for it in the current turn. Even `git add` should not happen on the agent's initiative — leave files unstaged until the user signals they're about to commit.
• **No "finish/integrate" workflow on the agent's initiative.** After implementation + iterate, the agent reports what was done and **stops**. The user decides whether to commit, merge, open a PR, keep iterating, or change direction.
• **Never invent values you don't authoritatively have.** This includes: file paths, env var values, API keys, secret values, IDs (UUIDs, foreign keys, third-party object IDs), URLs, port numbers, hostnames, version numbers, third-party service names, function names you haven't verified exist. **If unsure, STOP and ask** — don't guess. Action-hallucination (an agent confidently doing the wrong thing) is the most dangerous failure mode in agentic coding (industry research, 2026). The cost of asking is one round-trip; the cost of acting on a hallucinated value is potentially catastrophic.
• **Watch for context drift.** If you find yourself re-asking established questions, contradicting earlier decisions, or losing track of constraints set earlier in the session, invoke `evanflow-compact` to preserve anchors and propose a `/clear`. ~65% of agent failures trace to context drift, not raw token exhaustion.
• **No skill tax.** Ad-hoc questions don't require a skill invocation. Skills are tools, not a tollbooth.
• **No forced spec/plan paths.** Specs and plans live wherever the user wants. Default to `docs/` only if no preference is stated.
• **No forced sub-skill chains.** Each evanflow skill stands alone. Hand-offs are suggestions, not mandates.
• **Verify before claiming done.** Run the project's quality checks (typecheck, lint, test) and confirm output before reporting completion.

The Default Loop

1. (optional)  evanflow-brainstorming   — clarify intent, propose 2-3 approaches, embedded grill.
                                          Mockup-only requests use mockup quick-mode.
                                          (Hands off to evanflow-prd for substantial features.)
2. (if non-trivial) evanflow-writing-plans — file structure, bite-sized tasks, embedded grill.
                                          Step 2.5: parallelization check — offers
                                          coder-overseer if 3+ independent units exist.
3. EXECUTE     evanflow-executing-plans  — task harness: critical review, TaskCreate, inline
                                          verification, blockers, quality checks. Step 0:
                                          parallelization check (offers coder-overseer).
        OR     evanflow-coder-overseer   — same harness role, parallel: contract → RED checkpoint →