inception

Files (8)

• SKILL.md
• README.md · evals/
• evals.json · evals/
• frontier-machinery-tasks.md · evals/files/
• frontier-stalled-tasks.md · evals/files/
• gate-status-record.md · evals/files/
• returned-annotations.md · evals/files/
• session-batch-outcomes.md · evals/files/

SKILL.md (first lines)

# Flywheel inception — the design loop

One intent = one OpenSpec change bound to the `flywheel-intent` schema
(shipped in this plugin's `schemas/`), plus one tracker milestone
(`intent/<slug>`) holding its work items. The change holds the durable
prose — `intent.md`, `decisions/`, `questions/`,
`sessions/` — and the tracker holds every mutable fact: item state,
dependencies, the queue, the narrative in comments. Nothing is recorded
in both places; a file keeps only terminal facts.

Two roles load this skill: **dispatch** and **design sessions** under
either session profile. The **intent loop** — `bin/flywheel-intent-loop`,
one process per milestone — is a program rather than a reader; what it
does is written down here so the actors around it can count on it.

## The tracker

GitHub Issues on the org's tracker repo — the `tracker:` line in the
org's `fleet.yaml`. Every machinery write runs as the app:
`GH_TOKEN=$("${CLAUDE_PLUGIN_ROOT}"/bin/flywheel-token --org <org>) gh …`
— the plugin's `bin/` is not on `PATH`; `${CLAUDE_PLUGIN_ROOT}` is
substituted into this skill at load and is the `<plugin-root>` the
references speak of. The invocations, label
set, and batch queries are in the plugin's `skills/_reference/herdr.md`;
the object-graph rules and two worked examples are the shared copy at
`skills/_reference/tracker.md` — when a situation is not covered there
or by a work order, queue a question rather than inventing structure.

- **An item** is an issue: title imperative, body one to three sentences
  plus pointers to the record it serves, milestone from birth, labels
  `type:*` and exactly one `state:*`. The type is the session type that
  works it — a question borrows the type of the session that will answer
  it. A bolt's work items are the exception: born by expansion with no
  type label, their construction stages living in their comments, never
  as items of their own.
- **The lifecycle** is `state:queued → state:ready → state:in-progress`,
  ending closed with a `closed:*` reason — done, declined, superseded,
  parked. Anyone queues; only the operator's word makes an item ready —
  their approval on the board, or the approval of a dispatch plan,
  which the actor that ran the round applies
  (`skills/_reference/dispatch-plan.md`); an item's progress is its
  comment history.
- **A batch** is a parent issue whose sub-issues are the batch,
  composed with `flywheel-batch`, sitting in the Project at Status
  **Backlog**. Its kind is what approving it authorizes: a **unit**
  releases construction work — AI-DLC's unit of work; an
  **elaboration** authorizes design sessions. The operator approves by
  moving the batch to **Ready** on the board — one move per batch,
  never per item. Batches group by **thread**, not by type: a
  prototype, the questions it answers, and the writeback of its findings
  are one approval; the loop partitions the types into sessions at
  work time.
- **Milestones** are the change-sized containers, exactly two forms:
  `intent/<slug>` and `bolt/<slug>`. Everything an intent owns —
  questions, prototypes, writebacks — sits on its one
  milestone, distinguished by `type:*`. Dependencies are the items'
  native blocked-by relations, declared best-effort by whoever files an
  item; the loop computes readiness from the field and never reasons
  about it.

**Routing is creating the item where it belongs.** A finding for another
change is queued on that change's milestone, and the open item is the
obligation — nothing needs a second ledger to avoid being lost.

## Running agents

Supervised sessions run on herdr; names are the addressing scheme. The
loop launches, waits on, collects and closes them through the session
runner (`bin/_flywheel_sessions.py`), which reuses any agent already
running under the name — so a restarted loop process never puts two
sessions on the same work. Check `test "${HERDR_ENV:-}" = 1` before
starting anything yourself — if it fails you cannot address standing
agents; say so and stop rather than reaching for the `Agent` tool, whose
subagents are invisible to the operator.

The herdr and worktrunk invocations — starting an agent, the
rename-then-confirm protocol, cutting worktrees, merging through the
gate, teardown — are in `skills/_reference/herdr.md`, the one shared
copy. Read it before doing any of them.

## What lives where

- **A design session** writes the change's records: its own
  `sessions/<date>-<slug>/` directory, the decision and question
  records its work order charged it to close, and the books and
  map for writeback batches — all inside its own worktree.
- **The intent loop** writes no records. Its merge of a session's branch
  is what admits that session's file writes to main.
- **Anyone** writes the tracker: items, comments, queued discoveries.
- Construction — every other file edit, in any repo, the loop's own
  machinery included — reaches a repo through a released bolt.

## Sessions

A work order is the change id, the session type, the item numbers, and
one or two plain sentences of goal. Worktree, session directory, and
model are launch mechanics the loop sets, not work order content.

- **Batch generously, partition by judgment.** Type is the hard
  boundary — a session loads one type skill. Within a type: related
  topics share a session, unrelated ones split even at the same type,
  and prototypes ride alone by default — each is its own experiment. A
  session costs a pane, a worktree, and its reading — spend it on a
  real batch, and never split just to make sessions smaller.
- **A session that edits no files gets no worktree.** Most research
  reads, comments its answer, and reports — no branch, no merge, no
  teardown.
- **Sessions run with their own judgment.** A small fix inside the
  batch's ready scope is work, not a finding. Discoveries beyond the
  batch are queued items, filed in a minute. Escalation is for being
  blocked, not for noticing things.
- **A report is comment-sized**: what happened, evidence as pointers,
  what it asks the operator to decide. A report that is genuinely a
  document is a file in the session directory the comment points at. It
  goes on the item and into the pane; there is nobody to prompt.
- The five design types and their skills: `flywheel:planning`,
  `flywheel:interactive`, `flywheel:prototype`, `flywheel:research`,
  `flywheel:writeback`. An item's `type:*` label
  picks the type and the loop batches by it. Interactive runs under

From agentplot/flywheel, MIT.

More from agentplot/flywheel