Agent Flywheel
Overview
A reusable, systematic method for planning and executing software projects with AI agents. Core principle: invest heavily in plan-space before code — that's where errors are cheapest to fix. Inspired by Jeffrey Emanuel's Agent Flywheel framework (agent-flywheel.com).
The "flywheel" metaphor: each iteration upgrades plan quality, artifact reusability, and execution speed. Rework caught in planning costs ~1× effort; in task definition ~5×; in code ~25×. This heuristic shapes where to push reasoning (upstream, to the plan).
When to activate / anti-triggers
Use this skill when:
- Starting a new project or significant feature
- Converting ideas, specs, or requirements into executable plans
- Planning architecture or major technical decisions
- Establishing roadmaps or multi-phase programs
- Coordinating work across multiple agents or sessions
- Explicitly asked to "plan this", "make it a task graph", or "design the build"
Do NOT use when:
- Fixing routine bugs (non-architectural)
- Responding to urgent incidents or ops crises
- Executing an already-approved, locked plan
- Handling customer support or one-off requests
- Re-planning is explicitly out of scope
Step 1: Pick the execution mode (match scope to complexity)
Don't default to heavy machinery. Choose the lightest mode that fits the scope.
| Mode |
When to use |
Substrate |
Complexity |
| A: Plan-only |
Small/sequential projects; solo or tight-knit teams; coherent slice |
Markdown plan + test-driven development + standard PR workflow |
Minimal |
| B: Plan + task graph |
Multiple interconnected tasks; multi-session risk; dependency chains |
Markdown plan + structured task graph (JSONL format) + single-agent execution |
Medium |
| C: Task-graph + routable beads |
Plan B + need resumability across context loss; durable task store |
Structured beads + dependency routing + PR-per-cluster |
Medium–High |
| D: Full multi-agent swarm |
Large, highly parallel work; amortized coordination cost |
Only after passing swarm-readiness.md — full coordination layer |
High |
Default to Mode A. Escalate only when conditions in beads-escalation.md are genuinely met. Most projects do not justify modes B–D.
Step 2: Execute the planning loop (mandatory for all modes)
Quality planning requires multiple independent perspectives. This loop applies to any mode:
- Generate independent plans from 2+ models or agents, fresh context each. Different backgrounds yield different angles.
- Synthesize convergence. Identify where plans agree and where they diverge. Adjudicate disagreements with verified facts (search-first on external claims).
- Attack adversarially — use adversarial red-team review (e.g.,
mad-debate if available) to stress-test the plan. Identify MUST-FIX gaps and bake them into the plan as executable tests or tasks.
- Verify external facts that the plan depends on. Don't assume; search, verify, cite sources.
Output: one unified plan, with contention points resolved and external facts verified inline.
Step 3: Produce the gateway artifacts
The flywheel validates that a plan is real by checking for the artifacts that prove each discipline was applied. The skill used is a means; the artifact is the contract.
| Discipline |
Artifact that proves it |
Typical source |
| Scope & goals locked |
docs/SPEC.md — what, why, scope, non-goals, constraints |
Spec-writing discipline |
| Decisions recorded |
docs/adr/ADR-*.md — architecture decision records |
ADR discipline |
| Success measurable |
Impact metric + testable acceptance criteria |
Impact metrics discipline |
| Build plan executable |
Task-by-task plan with dependencies & test obligations |
Planning discipline |
| Risks identified |
Competition check, market fit, feasibility review |
Business/strategy discipline |
| Ship policy declared |
PR-only, CI gates, branch protection, code-review rules |
Engineering discipline |
If your tooling doesn't have a dedicated skill for a discipline, produce the same artifact manually — the contract (artifact existence) is what matters, not how you produced it.
Step 4: Quality gates (make them real, not performative)
- Fresh-eyes review: independent context (new session, different agent, no prior exposure), provided only the diff/artifact and the spec. Output: a concrete issue list or approval, not "looks good."
- De-slop owner/user-facing docs: Remove LLM writing artifacts (pseudo-profound openers, formulaic constructions, emdash overuse) from docs that humans actually read (READMEs, posts, guides). Use concrete criteria, not taste.
See fresh-eyes-review.md for detailed procedures.
Common failure modes & red flags
- Over-engineering (mode escalation mistake): jumping to beads/swarm for a 10-task project. Default to A; most builds fit in A.
- Hardcoded skill sequences: meta-skills that prescribe "run skill X then Y" become brittle. Check the artifact, not the tool invocation.
- "Fresh eyes" from same context: looking at your own code again isn't fresh. Use a separate agent/session.
- Confusing heuristic for law: "rework escalation (~1×/5×/25×)" is a bias, not proof. It informs where to invest, not a universal law.
- Adopting original Flywheel's commit-to-main model: the original assumes direct-to-main to avoid conflicts. Modern practice uses PR-only workflows — mode B/C include
pr-safe-beads.md for that.
References (load as needed)
beads-escalation.md — What beads are, exact conditions to escalate from mode A→B/C, portfolio substrate option.pr-safe-beads.md — Bead lifecycle (states, branching, PR-per-cluster) compatible with PR-only workflows.swarm-readiness.md — When/whether to adopt full multi-agent swarm; tooling trust caveats; prerequisites.fresh-eyes-review.md — Code review + de-slop procedures with acceptance criteria.
Quick-reference triggers (forward-test)
These prompts should activate this skill:
- "Build a new app"
- "Turn this idea into a plan"
- "Plan Phase 2"
- "Make this architecture executable"
- "Coordinate work across three developers"
These should NOT:
- "Fix this typo"
- "Urgent: production is down"
- "Execute the approved plan" (unless re-planning)
- "Quick bugfix"
How to use this skill
- State your scope (project size, team size, timeline, constraints, what "done" looks like).
- Activate step 1 — I'll help you pick the right mode (A/B/C/D).
- Activate step 2 — I'll generate or synthesize a multi-perspective plan, attack it, verify external facts.
- Activate step 3 — I'll help you produce the gateway artifacts (spec, ADRs, metrics, plan, ship policy).
- Activate step 4 — I'll coordinate fresh-eyes review and de-slop before handoff.
At each step, you decide whether to proceed, revise, or stop. The goal is a plan solid enough that execution becomes straightforward.
1---2name: agent-flywheel3description: Use when planning a new project or feature, turning an idea or specification into an executable plan, designing architecture, establishing a roadmap or phase, or coordinating multi-session or multi-agent builds. Activate on "plan this build", "turn this into tasks", "make it a plan", or when tasking/swarm coordination is mentioned. Skip routine bugfixes, urgent ops/incidents, or executing pre-approved plans unless re-planning is requested.4---56# Agent Flywheel78## Overview910A reusable, systematic method for planning and executing software projects with AI agents. Core principle: **invest heavily in plan-space before code — that's where errors are cheapest to fix.** Inspired by Jeffrey Emanuel's Agent Flywheel framework (agent-flywheel.com).1112The "flywheel" metaphor: each iteration upgrades plan quality, artifact reusability, and execution speed. Rework caught in planning costs ~1× effort; in task definition ~5×; in code ~25×. This heuristic shapes where to push reasoning (upstream, to the plan).1314## When to activate / anti-triggers1516**Use this skill when:**17- Starting a new project or significant feature18- Converting ideas, specs, or requirements into executable plans19- Planning architecture or major technical decisions20- Establishing roadmaps or multi-phase programs21- Coordinating work across multiple agents or sessions22- Explicitly asked to "plan this", "make it a task graph", or "design the build"2324**Do NOT use when:**25- Fixing routine bugs (non-architectural)26- Responding to urgent incidents or ops crises27- Executing an already-approved, locked plan28- Handling customer support or one-off requests29- Re-planning is explicitly out of scope3031## Step 1: Pick the execution mode (match scope to complexity)3233Don't default to heavy machinery. Choose the lightest mode that fits the scope.3435| Mode | When to use | Substrate | Complexity |36|---|---|---|---|37| **A: Plan-only** | Small/sequential projects; solo or tight-knit teams; coherent slice | Markdown plan + test-driven development + standard PR workflow | Minimal |38| **B: Plan + task graph** | Multiple interconnected tasks; multi-session risk; dependency chains | Markdown plan + structured task graph (JSONL format) + single-agent execution | Medium |39| **C: Task-graph + routable beads** | Plan B + need resumability across context loss; durable task store | Structured beads + dependency routing + PR-per-cluster | Medium–High |40| **D: Full multi-agent swarm** | Large, highly parallel work; amortized coordination cost | Only after passing `swarm-readiness.md` — full coordination layer | High |4142**Default to Mode A.** Escalate only when conditions in `beads-escalation.md` are genuinely met. Most projects do not justify modes B–D.4344## Step 2: Execute the planning loop (mandatory for all modes)4546Quality planning requires multiple independent perspectives. This loop applies to any mode:47481. **Generate** independent plans from 2+ models or agents, fresh context each. Different backgrounds yield different angles.492. **Synthesize** convergence. Identify where plans agree and where they diverge. Adjudicate disagreements with verified facts (search-first on external claims).503. **Attack adversarially** — use adversarial red-team review (e.g., `mad-debate` if available) to stress-test the plan. Identify MUST-FIX gaps and bake them into the plan as executable tests or tasks.514. **Verify external facts** that the plan depends on. Don't assume; search, verify, cite sources.5253Output: one unified plan, with contention points resolved and external facts verified inline.5455## Step 3: Produce the gateway artifacts5657The flywheel validates that a plan is real by checking for the **artifacts** that prove each discipline was applied. The skill used is a **means**; the artifact is the **contract**.5859| Discipline | Artifact that proves it | Typical source |60|---|---|---|61| Scope & goals locked | `docs/SPEC.md` — what, why, scope, non-goals, constraints | Spec-writing discipline |62| Decisions recorded | `docs/adr/ADR-*.md` — architecture decision records | ADR discipline |63| Success measurable | Impact metric + testable acceptance criteria | Impact metrics discipline |64| Build plan executable | Task-by-task plan with dependencies & test obligations | Planning discipline |65| Risks identified | Competition check, market fit, feasibility review | Business/strategy discipline |66| Ship policy declared | PR-only, CI gates, branch protection, code-review rules | Engineering discipline |6768If your tooling doesn't have a dedicated skill for a discipline, **produce the same artifact manually** — the contract (artifact existence) is what matters, not how you produced it.6970## Step 4: Quality gates (make them real, not performative)7172- **Fresh-eyes review:** independent context (new session, different agent, no prior exposure), provided only the diff/artifact and the spec. Output: a concrete issue list or approval, not "looks good."73- **De-slop owner/user-facing docs:** Remove LLM writing artifacts (pseudo-profound openers, formulaic constructions, emdash overuse) from docs that humans actually read (READMEs, posts, guides). Use concrete criteria, not taste.7475See `fresh-eyes-review.md` for detailed procedures.7677## Common failure modes & red flags7879- **Over-engineering (mode escalation mistake):** jumping to beads/swarm for a 10-task project. Default to A; most builds fit in A.80- **Hardcoded skill sequences:** meta-skills that prescribe "run skill X then Y" become brittle. Check the **artifact**, not the tool invocation.81- **"Fresh eyes" from same context:** looking at your own code again isn't fresh. Use a separate agent/session.82- **Confusing heuristic for law:** "rework escalation (~1×/5×/25×)" is a bias, not proof. It informs where to invest, not a universal law.83- **Adopting original Flywheel's commit-to-main model:** the original assumes direct-to-main to avoid conflicts. Modern practice uses PR-only workflows — mode B/C include `pr-safe-beads.md` for that.8485## References (load as needed)8687- **`beads-escalation.md`** — What beads are, exact conditions to escalate from mode A→B/C, portfolio substrate option.88- **`pr-safe-beads.md`** — Bead lifecycle (states, branching, PR-per-cluster) compatible with PR-only workflows.89- **`swarm-readiness.md`** — When/whether to adopt full multi-agent swarm; tooling trust caveats; prerequisites.90- **`fresh-eyes-review.md`** — Code review + de-slop procedures with acceptance criteria.9192## Quick-reference triggers (forward-test)9394**These prompts should activate this skill:**95- "Build a new app"96- "Turn this idea into a plan"97- "Plan Phase 2"98- "Make this architecture executable"99- "Coordinate work across three developers"100101**These should NOT:**102- "Fix this typo"103- "Urgent: production is down"104- "Execute the approved plan" (unless re-planning)105- "Quick bugfix"106107---108109## How to use this skill1101111. **State your scope** (project size, team size, timeline, constraints, what "done" looks like).1122. **Activate step 1** — I'll help you pick the right mode (A/B/C/D).1133. **Activate step 2** — I'll generate or synthesize a multi-perspective plan, attack it, verify external facts.1144. **Activate step 3** — I'll help you produce the gateway artifacts (spec, ADRs, metrics, plan, ship policy).1155. **Activate step 4** — I'll coordinate fresh-eyes review and de-slop before handoff.116117At each step, you decide whether to proceed, revise, or stop. The goal is a plan solid enough that execution becomes straightforward.
avizmarlon