| name | flywheel |
| description | scry outer-loop shipping orchestrator. Picks the next backlog item,
composes /shape, /implement, /yeet, /settle, /ship, and /monitor,
then loops. Closure (backlog archive, trailers, /reflect, and harness
routing) lives in /ship; flywheel does not invoke /reflect directly.
Use when: "flywheel", "run the outer loop", "next N items",
"overnight queue", "cycle".
Trigger: /flywheel.
|
| argument-hint | [--max-cycles N] |
/flywheel
You are scry's outer loop. Preserve the mandatory composition exactly:
pick -> /shape -> /implement -> /yeet -> /settle -> /ship ->
/monitor -> loop.
Do not substitute /deliver for the explicit phases here. The point of
this skill is orchestration discipline around scry's backlog, not a
shortcut around the leaf skills.
Source Of Truth
Read .spellbook/repo-brief.md and backlog.d/*.md before the first
pick in a run. If they disagree, prefer the repo brief for repo-wide
invariants and the specific backlog file for ticket-local acceptance
criteria. If either conflicts with live package.json, .github/workflows/**,
or lefthook.yml, stop and let /shape reconcile the conflict before
implementation.
Every gate-adjacent phase cites this repo-brief statement verbatim:
The ship gate is GitHub Actions Quality Checks merge-gate: pnpm lint, pnpm typecheck, pnpm audit --audit-level=critical, no focused tests via the .only grep, and pnpm test:ci must pass; local parity is pnpm lint && pnpm tsc --noEmit && pnpm test:ci, with pnpm test:contract for convex/**, pnpm build for build/config/workflow/dependency surfaces, and pnpm audit --audit-level=critical for dependency or lockfile changes.
Never run forbidden deploy/build commands as part of the loop without
explicit operator approval: pnpm build:local, pnpm build:prod,
pnpm convex:deploy, ./scripts/deploy-production.sh, production
migration scripts, or anything that changes non-local Convex/Vercel
state.
Pick Order
Pick from backlog.d/, not vibes. Continue an in-progress item before
starting a new ready item unless ownership or git state says another
worker owns it. Skip done items unless the backlog file is stale; stale
entries are fixed through the normal /ship closure path, not by
flywheel archiving them.
Current scry priority shape:
- High-priority eval and content-type work comes first: phrasing
generation evals, content-type eval suite, hard quality gates, then
cloze and short-answer completeness. Respect declared dependencies:
003 -> 004 -> 005 -> 006.
- Agent-ready architecture follows once gates are hard. It is extraction,
not rewrite: split
convex/concepts.ts, convex/aiGeneration.ts,
convex/iqc.ts, and components/agent/review-chat.tsx into focused
modules without public API changes.
- Generative UI foundation follows content types and review-chat
decomposition. Prefer scry's thin Zod-validated
renderSpec registry
over a general-purpose LLM-generated UI framework.
- Product-surface cleanup remains important, but do not trample another
worker's
in-progress ownership. If the item is open and unowned,
finish it before starting a new high-priority chain.
When the next item is ambiguous, ask /shape to ratify the pick with the
backlog dependency graph and current git state. Flywheel does not invent
new scoring systems, locks, queues, or ticket state machines.
Scry Guardrails
Every cycle protects the product doctrine:
- Pure FSRS is non-negotiable. Do not pick or accept work that adds daily
caps, artificial review limits, comfort-mode shortcuts, or "ease"
affordances that change the scheduling curve.
- Convex backend precedes UI. Schema, query, mutation, generated API
readiness, and contract tests come before React wiring.
- Convex bandwidth is a ship concern. Runtime paths need indexes and
bounded
.take() or pagination; unbounded .collect() is not accepted
without a bounded diagnostic/offline justification.
- Destructive mutations need reverses:
archive/unarchive,
softDelete/restore; hard delete requires explicit confirmation UX.
- Keep
/ as the review home and Willow's review chat as the product
center. /tasks and /action-inbox may exist, but they are not primary
navigation unless a shaped ticket explicitly changes that.
Phase Contract
For each cycle:
- Pick. Select one backlog item and verify it is not already shipped
in git or owned by another worker. Record only the selected item in the
handoff to
/shape.
/shape. Ensure the ticket has a concrete oracle, dependency
order, test plan, FSRS/Convex implications, and the exact ship gate
statement above./implement. Build only the shaped ticket. For Convex work,
backend-first sequencing is mandatory. For architecture work, extract
without changing public APIs./yeet. Run adversarial review against behavior, tests, FSRS
purity, Convex bandwidth, and ticket oracle. Fix findings through the
normal implementation loop./settle. Stabilize the diff, receipts, and git state. No new
scope is added here./ship. Owns closure: final gate evidence, squash/merge flow,
backlog archive, trailers, /reflect, and harness routing. Flywheel
never invokes /reflect directly and never archives tickets itself./monitor. Check post-ship signals appropriate to the item. For
deploy-no-op work, monitor still records that there was nothing to
observe beyond CI/repo state.- Loop. Re-read the backlog summary before the next pick; do not
rely on stale memory from the prior cycle.
Collision Rules
- One worktree runs one flywheel. Parallel flywheels need separate
worktrees and disjoint backlog ownership.
- If a worker edits another skill, harness bridge, setting, marker,
AGENTS.md, or app code outside the selected ticket, stop and route
through the owning workflow. Flywheel does not clean up foreign edits.
- If
/ship produces reflect/harness changes, they route according to
/ship policy and never land on the product branch by flywheel action.
Non-Goals
- No direct implementation inside flywheel.
- No direct
/reflect invocation.
- No backlog archive, trailer editing, squash-merge, or harness routing
inside flywheel;
/ship owns closure.
- No custom cycle state machine, event enum, lock service, pick scorer,
or semantic orchestration layer.
