Every rig starts as a project, and every project starts with the user's direction.
This repository is where the rig-c project layer is built: the folder a rig is made in, the interview that comes before any rigging, the plan the user signs, and the guide an agent reads before it touches anything. It does not cut parts (rig-c/parts does) and it does not compile or gate rigs (rig-c/core does). It decides what and why; those packages do how.
Requires Bun 1.4.0 or newer and Git. Run the published CLI without a global install:
bunx rig-create --help
bunx rig-create init p1
bunx rig-create interview --check p1 --json
bunx rig-create next p1 --jsonTo pin the canonical scoped name, use bunx --package @rig-c/create rig-create ….
Or install it globally:
bun add -g @rig-c/create
rig-create --help
rig-create init p1
rig-create interview --check p1 --json
rig-create next p1 --jsonChoose one route and a new or empty p1 folder. init creates the project,
installs its pinned rig-c dependencies, and makes its first Git commit. If the
install fails, the project is still created; run bun install inside p1 to
recover. Use init p1 --no-install only to defer dependency installation.
A fresh project's interview check reports the work still needed and exits
nonzero until its stage requirements are met. next reports the available
next actions; follow those through the review tool rather than editing records
by hand.
An agent rigging a painting passes through the same places every time: the layer split, the cut of each part, the bones, what deforms and what stays rigid, what gets physics or wind, which motions it plays. Left alone at each of those places, it guesses — and a guessed direction is only found out when a person watches the result and sends it back. A precise direction, given before the work, is done in one pass.
So the user gives direction at those places, in their own sentences, before the work starts:
- Base motion — the cut, the bones, what deforms, physics, the motions. Reviewed on a still frame, the rig alone.
- Direction — camera, depth and timing, applied after the rig is accepted.
Reviewed as a take. Camera keys and timing are authored with
rig-create directionin a hash-bound direction document; depth and turn remain in parts. - Polish — what the user says after seeing a result, kept word for word and tied to the place it is about.
Choosing "auto" at any place is allowed. It is recorded as the user handing that decision to the agent, never left blank for the agent to fill.
- A project scaffold: one folder per rig, one record of its direction, sign-offs and versions, and data split by lifetime (inputs and evidence kept; derived data, outputs and scratch rebuilt or discarded).
- The interview, organised by the places the rig work always passes through.
- Translation of the user's sentences into checks the rig must keep, enforced by
rig-c's
invariantsand named failures. - Collections: several rigs that belong together, sharing direction and pinned to exact member builds.
- The guide an agent starts from, pointing at the installed packages' own documentation rather than copying it.
Release preparation and the owner-operated publication steps are in RELEASING.md.
Agents route human picks, corrections, verdicts and signatures through Review.
Open the relevant question, draft, rig/post version or plan, let the person act
in the tool, then use job acts and ingest its printed writer command:
rig-create job open <project dir> --reviewer <id> --role owner --plan
rig-create job acts <project dir>
rig-create signoff plan-approved --from-review <actId> <project dir>
rig-create parts-review <project dir> --from-review <actId>
rig-create review <version> --from-review <actId> <project dir>The owner is asked for a parts verdict only at parts-review. As soon as the
first draft has the agent's check-parts report, structure snapshot,
diff-components report and diff-classes classifications, advance to
parts-review. Draft registration publishes inventory before the verdict ask;
publish the prepared draft with job open --draft <id> and ask for one
parts-verdict.
Stay at parts-review throughout retouch rounds. Changes-requested leaves the
stage unsigned: the agent makes an edited_parts correction, registers a new
draft and prepares fresh reports, snapshot and classifications for that draft.
Open the new draft and ask for one new verdict. This correction loop requires
no owner reopen, separate signoff or move back to parts. Ingesting an approved
UI verdict atomically records its receipt and the parts-review signature.
Finish each draft's record changes before publishing: a stale projectHash
refuses ingestion. See the live Review flow for the order.
Only a midflight approved verdict already ingested unsigned uses the separate
signoff parts-review --from-review <actId> --draft <id> --structure-file <path>
route. Other stages keep their existing acts. Publish the matching subject before each
human act. Keep the Review host up across bound writes. If it stops, job open
again with reviewer/role, then job reconcile before more writes. --rig <n>
selects either a rig or a post version.
At rig-review, a fresh job asks for one rig verdict. Ingesting its approval
also records the rig-review signature atomically; pending or changes-requested
stays unsigned. Existing verdict-only receipts and old two-subject publications
retain their separate-signoff recovery. See live review.
signoff records without moving the stage. advance uses its authority. Record
verdicts in Review. To relay an owner's eligible interview answer or stage
sign-off, use --by with the owner's identity and supply
--owner-chat <words file> --said-at <ISO> --relayed-by <operator>. For a
verdict-bearing stage, ingest the current accepted live verdict first. After
an accepted post is bounced, host job open --plan and choose the
direction-review reopen. Plan publications offer a reopen for each eligible
stage. List the act with job acts --json, then ingest
reopen direction-review --from-review <actId> and job close.
The exported act supplies the reviewer, timestamp and unchanged
words. To record an owner's reopen instruction from chat, supply the owner's
--by and the owner-chat flags to reopen. See the live Review flow
and the record contract.
Every command, writer and check takes the instant it runs at as an explicit
now (milliseconds since the epoch). That one value dates what a writer records
and bounds every "not in the future" refusal. The process entry in src/cli.ts
is the only place create reads the wall clock; it passes Date.now() to main.
Tests and generators never read or replace the global clock. Generators pass
their declared example instants. Tests call create through
tests/clock.ts, which passes the suite's instant, by default
twelve hours after the latest *_SINCE date; testClock.set moves it for the
next call. A test that needs a real process spawns
tests/cli-at.ts with that instant. The only test that reads
the real clock is tests/contract-dates.test.ts:
it fails, naming the constant, when a *_SINCE date is still in the future.
- docs/PROJECT.md — the project folder, data by lifetime, stages and sign-offs, the plan, versions.
- docs/INTERVIEW.md — the three user steps, answer states and shape, waypoints, post-production, provenance, polish feedback.
- docs/CHECKS.md —
rig-create interview --check: every refusal code, what fires it, how to clear it. - docs/COLLECTIONS.md — several rigs that belong together: inherited answers, the reference member, composition, pins.
- docs/CRAFT.md — craft notes: the default proposed at each waypoint, and execution defects handed to rig-c/parts gates.
- docs/SOURCE.md — the layer split and the cut: what to do, in
what order and why, read before
seethroughandassemble. - docs/LESSONS.md — the self-check every version passes before anyone looks, and the review lessons behind it.
- templates/ — the empty
project.jsonandcollection.jsonskeletons, and a worked example (example-interview.md, example-project.json) on a made-up painting. Its sign-offs and the reopened variant's reopen are synthetic fixture records, not a person's approval (why).
From a consumer project with @rig-c/create installed, run:
bun node_modules/@rig-c/create/scripts/verify-example-seals.tsThe shipped, dependency-free script verifies every files[] entry and
project_sha256 in the six example-chain checkpoint manifests (currently
319 checks). It names missing files and hash mismatches and exits nonzero.
It reads installed bytes only; it does not regenerate examples or run producers.
The CLI creates projects from empty templates; it does not copy worked examples.
See release candidate verification.
MIT.
New projects ask a separate multiple-choice question for each applicable ask,
with a reasoned agent recommendation, Other and explicit delegation. The shown
option file is retained by raw sha256. Record it with interview-options, then
open the question in Review and ingest its finalized act with interview-answer --from-review <actId>;
interview-decision records only the explicitly delegated asks. See
the choice contract and the
generated consumer fixture.
Existing @1 projects keep their sentence history; adopt choices explicitly
with interview-options --adopt, without re-dating old answers.