construction

Files (8)

• SKILL.md
• README.md · evals/
• evals.json · evals/
• bolt-widget-gateway-proposals.md · evals/files/
• bounced-twice-registry.md · evals/files/
• idle-registry-proposals.md · evals/files/
• inbox-one-line-fix.md · evals/files/
• specced-batch-registry.md · evals/files/

SKILL.md (first lines)

# Flywheel construction — the bolt loop

One bolt = one construction iteration = one OpenSpec change bound to a
bolt schema member — `bolt-direct`, `bolt-default`, `bolt-quick`,
`bolt-adversarial`, `bolt-plan`,
where **the member picked at creation IS the bolt type**, setting the
review steps the loop schedules and the stages it runs (`bolt-direct`
declares spec, build, merge, land — no verify; `bolt-plan` runs the
plan path) — and a unit card naming a type runs its batch under that
type. The tracker
milestone `bolt/<slug>` holds its items, born by the approved plan's
expansion; **the item body is the proposal**,
and every spec derives from the item and the sources it
cites, never from a restatement. A bolt exists only past the operator's
release, so the server starts its loop the moment the milestone has a
job, and the release that created a bolt covers every wave of agents
inside it.

The tracker practice — labels, lifecycle, batches, comments as narrative,
routing as item creation — is stated once in `flywheel:inception` and
reads the same here. The invocations are in the plugin's
`skills/_reference/herdr.md`; the object-graph rules and the quick-bolt
worked example are `skills/_reference/tracker.md` — when a situation is
not covered there or by a work order, queue a question rather than
inventing structure.

## Running agents

Construction runs on herdr; names are the addressing scheme. Check
`test "${HERDR_ENV:-}" = 1` before starting anything — if it fails, say
so and stop rather than reaching for the `Agent` tool, whose subagents
are invisible to the operator. The loop itself launches through the
session runner — `launch`/`wait`/`collect`/`close` — which gives a pane
to anything the operator might watch or answer and runs only
unsupervised stages headless.

Before first construction in a repo, audit its readiness: `.config/wt.toml`
gates, named verification commands, reset path, OpenSpec root. Queue
gaps as items rather than improvising around them.

## What lives where

- **The bolt loop** — `bin/flywheel-bolt-loop`, one stateless process
  per bolt milestone, started and stopped by `flywheel server` — drives
  the items: it scaffolds the bolt change's artifacts (`bolt.md`), and
  it merges every construction branch and lands every landing. It reads
  state and enforces contracts; every judgment it needs is asked of a
  session or of the operator.
- **Sessions** write the built repo inside their own worktrees, and their
  own spec-driven changes there. Book chapters and the context map are
  the design loop's; a design-level finding — the design is wrong, not
  the build — is queued on the source intent's milestone, never fixed
  from here.
- **Nothing edits without an item**, however small: a repo's CLAUDE.md,
  an architecture decision record (into the built repo's log4brains
  layout — the bolt is where the material for one exists), a tweak to
  the loop's own machinery. Each is a GitHub issue like all other work,
  and everything the bolt lands is carried by an item.

## Topology

One bolt branch + worktree per involved built repo (`bolt/<slug>`),
alive for the bolt's lifetime, cut lazily as units resolve to repos: a
unit card's `System:` line names the fleet binding, and
`fleet.yaml` `books.<name>.repo` is where that unit's construction
runs. The bolt's RECORDS — `bolt.md`, `units/*.md`, under
`openspec/changes/bolt-<slug>/` — live in the records repo on its main
branch, never on a construction branch. Sessions build on nested
worktrees off the bolt branch — concurrent when items are independent,
serial when they share contracts. Building directly on the bolt branch is legal only
for a bolt with a single small item. Batch acceptance after 2–3
merge-backs by default; a batch of one for high-risk changes.

Agents sharing a worktree share a git index: every session commits its
own artifacts by pathspec — never `-a`, never `add -A` — so a sibling's
staged work is never swept into a commit that did not mean it.

## The item flow

A work item is the one tracked object for its whole construction: the
stages below create no items of their own — the bolt loop decides
those moves, and the item's comments record them. Each item's progress is its comment
history — spec landed, review verdict, build done, merge SHA — plus the
one `stage:*` label naming its leading edge. Its
label stays `state:in-progress` from first spec work until the
merge-back, where the loop closes it `closed:merged` with the merge SHA
so the unit parent's native bar advances there; the landing then
upgrades that reason to `closed:done` with the landing SHA in the
closing comment. A closed item carries exactly one `closed:*` reason at
every moment. Only
discoveries become new items: findings, readiness gaps, design-level
faults queued to the source intent.

**WHICH STAGES EXIST IS THE BOLT TYPE'S FACT, NOT THIS SKILL'S.** The
loop — its stages, their order, whether any review runs — is defined
solely by the change's schema (`openspec instructions` shows it), and
run by the plugin's own process, `flywheel-bolt-loop --slug <slug>`,
which implements that instruction. This skill never adds a stage the loop
did not schedule: no review, no re-review, no bounce round exists
unless the bolt type's own instruction names it. What this skill holds
is the practice shared by every stage the loop does run:

- **One spec-driven change per work item** (`/opsx:ff` each); the
  item binds one change id and one landing ref. `openspec validate --strict` green before a spec
  counts; cite by anchor or quoted phrase, never line number; re-read
  every neighbour a spec claims something about from disk at build
  time.
- **The plan path — `bolt-plan` only**: on a `bolt-plan` batch the
  build session starts in plan mode
  (`--permission-mode plan`); approval is a judgment, so an approver
  session checks the plan against the item's claim and the loop drives
  the plan dialog on the verdict it answers with, pausing the batch
  after two returns rather than bouncing again. On every other type
  every item is
  specced — the type is the scrutiny the operator chose at
  approval, and an unknown type pauses the batch rather than running
  a downgraded loop.
- **Merging**: session branch to bolt branch through the gate, run
  from the build worktree so the feature is what gets rebased and the

From agentplot/flywheel, MIT.

More from agentplot/flywheel