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:

1. Generate independent plans from 2+ models or agents, fresh context each. Different backgrounds yield different angles.
2. Synthesize convergence. Identify where plans agree and where they diverge. Adjudicate disagreements with verified facts (search-first on external claims).
3. 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.
4. 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

1. State your scope (project size, team size, timeline, constraints, what "done" looks like).
2. Activate step 1 — I'll help you pick the right mode (A/B/C/D).
3. Activate step 2 — I'll generate or synthesize a multi-perspective plan, attack it, verify external facts.
4. Activate step 3 — I'll help you produce the gateway artifacts (spec, ADRs, metrics, plan, ship policy).
5. 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.