---
name: avizmarlon/agent-flywheel
source: https://app.decimal.ai/s/avizmarlon-agent-flywheel@1/SKILL.md
source_sha256: dfb54bd35d6e
---

# 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.