start

Orchestrate: Full Flywheel

Run the agent-flywheel for this project. $ARGUMENTS (optional: initial goal or --mode single-branch)

⚠️ UNIVERSAL RULE 1 — AskUserQuestion is the only way to ask the user anything

Every user decision in this skill — phase routing, plan refinement, bead approval, launch confirmation, wrap-up choices, recovery branches — MUST be presented via the AskUserQuestion tool with concrete labeled options (2–4 per question). Free-text "ask the user…" prompts, "wait for confirmation", "wait for the user's next message", or implicit decision points are bugs. The "Other" field absorbs custom answers when none of the prepared options fit.

If you find yourself about to write text like "surface this to the user", "propose this to the user", "check with the user", or "only do X if the user confirms" — STOP and write an AskUserQuestion call instead. No exceptions.

⚠️ UNIVERSAL RULE 2 — invoke specialist skills by name when they apply

This SKILL references many specialist skills by slash-name (/idea-wizard, /ubs-workflow, /caam, /ui-polish, /docs-de-slopify, testing-*, stack-specific skills, etc.). When a step names one, invoke it via the Skill tool rather than re-implementing its logic inline. Specialist skills carry project-tested prompts and conventions you don't have time to recreate.

Equally important: if a step does NOT name a skill but you notice one applies to the situation (e.g. a React component bead and /react-component-generator exists), invoke it anyway. Skills are hints-with-authority — use them by default, skip only when they clearly don't fit.

⚠️ UNIVERSAL RULE 3 — load phase instructions on demand (PRIMARY: flywheel_get_skill)

Steps 5–12 are stored in separate files to keep this prompt within token limits. When you reach a phase boundary, fetch the corresponding body via the bundled MCP tool — do not default to Read. Call: flywheel_get_skill({ cwd, name: "agent-flywheel:start_<phase>" }).

Phase	Skill name	Sub-file (fallback)	Steps
Planning	agent-flywheel:start_planning	_planning.md	5, 5.55, 5.6
Bead creation & approval	agent-flywheel:start_beads	_beads.md	5.5, 6
Implementation	agent-flywheel:start_implement	_implement.md	7
Review & loop	agent-flywheel:start_review	_review.md	8, 9 (verify + compliance), 9.25, 9.4
Wrap-up & post-flywheel	agent-flywheel:start_wrapup	_wrapup.md	9.5, 10, 11, 12
Reality check	agent-flywheel:start_reality_check	_reality_check.md	(referenced from _wrapup, _saturation)
Deslop pass	agent-flywheel:start_deslop	_deslop.md	(Step 9.5 routing)
Saturation suite	agent-flywheel:start_saturation	_saturation.md	(saturation-pipeline routing)
In-flight resume	agent-flywheel:start_inflight_prompt	_inflight_prompt.md	(auto-swarm)

Why MCP-first: one round-trip, served from the bundled body at mcp-server/dist/skills.bundle.json with srcSha256 integrity check + transparent disk fallback. Read is two-step (path resolution then file I/O) and burns more context on listing noise.

Skill-stub recovery. If invoking the Skill tool itself ever returns just the description / pointer text instead of the canonical body (the harness sometimes ack's instead of inlining for already-loaded skills), do NOT fall back to Read — call flywheel_get_skill({ name: "agent-flywheel:start" }) for the entry-point or the relevant start_<phase> for sub-phases. Single MCP round-trip, served from the same bundle, no path-resolution noise.

Fetch the body before executing that phase. Do NOT guess or improvise — the sub-files contain critical gates, edge-case handling, and AskUserQuestion templates.

Disk fallback. If flywheel_get_skill errors (e.g. FW_SKILL_BUNDLE=off, missing bundle, MCP transport down), then Read skills/start/_<phase>.md from disk. Existing Read references throughout this skill are valid fallbacks — but try MCP first.

Step 0: Opening Ceremony

0.banner — SHOW THIS FIRST, ALWAYS

Before any tool calls, before any other reads, print the banner. This is the first visible output of the skill. Use the version from mcp-server/package.json (resolve CLAUDE_PLUGIN_ROOT or use the find command in Step 0a; default to unknown if unreadable — never substitute a stale hardcoded version).

░▒▓ CLAUDE // AGENT-FLYWHEEL v<VERSION> ▓▒░

Output it as a plain code block so the user always sees the banner even if the rest of the skill fails. Then continue with 0.preflight.

0.preflight — Captured user input

If the user's prompt contains anything beyond /start <args> — a goal sentence, a pasted plan, a path to a plan file, a directive like "fix X then Y" — capture it as USER_INPUT and treat it as a candidate goal or plan. Do NOT act on it yet. Do NOT skip the welcome banner or Step 0b detection. Run the full Step 0a–0d flow silently so the user sees current state (existing session, open beads, AM status) before deciding.

Then route in Step 0e instead of showing the default main menu:

Classification heuristics:

• Plan-shaped USER_INPUT — multi-paragraph, contains ##/### headers, mentions specific files, OR is an existing path matching docs/plans/*.md → treat as plan.
• Goal-shaped USER_INPUT — ≤300 chars, no markdown headers, reads as one or two sentences → treat as goal.
• Ambiguous — long unstructured prose → treat as goal but route through the Goal framing mode menu (Light / Grill / Full brainstorm) before flywheel_select.

Routing override for Step 0e (only when USER_INPUT is non-empty):

• Plan-shaped:

  AskUserQuestion(questions: [{
    question: "I see a plan in your message ('<first 60 chars>…'). What should I do with it?",
    header: "Plan input",
    options: [
      { label: "Use as plan", description: "Register via flywheel_plan and jump to bead creation (Recommended)" },
      { label: "Treat as goal", description: "Use the plan content as the goal description and run the full flywheel from Step 4" },
      { label: "Discard", description: "Ignore the input and show the regular start menu" }
    ],
    multiSelect: false
  }])
  

  • "Use as plan" → if USER_INPUT was a file path, call flywheel_plan with planFile. If it was inline, write it to docs/plans/<date>-<goal-slug>.md first, then call flywheel_plan with planFile. Then jump to Step 5.5.
  • "Treat as goal" → call flywheel_select with the input as goal, jump to Step 5.
  • "Discard" → fall back to the default Step 0e menu.

• Goal-shaped:

  AskUserQuestion(questions: [{
    question: "I see a goal in your message: '<USER_INPUT>'. Run the flywheel on this?",
    header: "Goal input",
    options: [
      { label: "Yes, full flywheel", description: "Skip discovery, plan and implement this goal (Recommended)" },
      { label: "Refine first", description: "Pick a framing mode (Light / Grill with docs / Full brainstorm) before planning" },
      { label: "Plan only", description: "Generate a plan, stop before implementation" },
      { label: "Discard", description: "Ignore the input and show the regular start menu" }
    ],
    multiSelect: false
  }])
  

  • "Yes, full flywheel" → call flywheel_select with USER_INPUT as goal, proceed to Step 5 (Phase 0.5 still applies unless skipped).
  • "Refine first" → run Goal framing mode (below) with RAW_GOAL = USER_INPUT, then flywheel_select with the enriched goal and continue to Step 5.
  • "Plan only" → call flywheel_select, proceed through Step 5, stop after bead creation.
  • "Discard" → fall back to the default Step 0e menu.

• Ambiguous → always run Goal framing mode first (Recommended default: Grill with docs), then route as goal-shaped after refinement.

Hard rule: never act on USER_INPUT directly without first showing the banner and getting an explicit menu choice. The flywheel's gates exist for a reason — pre-prompt content does NOT bypass them.

Goal framing mode (shared by Set a goal / Refine first / Ambiguous)

Use this whenever a goal needs refinement before flywheel_select. Do not chain multiple framing paths (no brainstorm + grill + Phase 0.5 triple interview).

AskUserQuestion(questions: [{
  question: "How should we refine this goal before planning?\n\nGoal: '<RAW_GOAL>'",
  header: "Framing",
  options: [
    { label: "Light (Phase 0.5 only)", description: "Skip deep interview; three pressure-test questions at Step 4.5 (floor / 10x / adjacents)" },
    { label: "Grill with docs (Recommended)", description: "Relentless interview via skills/grill-with-docs — writes brainstorm + optional ADRs/glossary, then hands off" },
    { label: "Full brainstorm", description: "/brainstorming design dialogue — best for greenfield product specs / mockups" },
    { label: "Skip framing", description: "Goal is already concrete — call flywheel_select with the raw text" }
  ],
  multiSelect: false
}])

Default recommendation rules:

• Ambiguous USER_INPUT → mark Grill with docs as Recommended (already set above).
• Goal-shaped but operator picked Refine first → Grill with docs Recommended.
• Concrete ≤300 chars (caller already skipped this menu) → never show this menu.
• If the goal is clearly a full product design (UI-heavy, multi-surface, greenfield), the operator may still pick Full brainstorm.

Routing:

• Light (Phase 0.5 only) → set FRAMING_MODE = light, enrichedGoal = RAW_GOAL. Do not write brainstorm yet. Call flywheel_select({ goal: enrichedGoal }), then load _planning.md and run Step 4.5 normally.
• Grill with docs (Recommended) → set FRAMING_MODE = grill. Prefer flywheel_get_skill({ name: "agent-flywheel:grill-with-docs" }) (fallback: `Skill(skill: "agent-flywheel:grill-

Content truncated.