Skip to content
rig-cPublic

About

Projects for rig-c: the user's direction, an interview and a signed plan before any rigging

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

@rig-c/create — Project direction, an interview and a signed plan before rigging

npm version npm downloads license

@rig-c/create

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.

Install and start

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 --json

To 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 --json

Choose 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.

Why it exists

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:

  1. Base motion — the cut, the bones, what deforms, physics, the motions. Reviewed on a still frame, the rig alone.
  2. Direction — camera, depth and timing, applied after the rig is accepted. Reviewed as a take. Camera keys and timing are authored with rig-create direction in a hash-bound direction document; depth and turn remain in parts.
  3. 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.

What it provides

  • 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 invariants and 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.

Recording approvals

Agents route human picks, corrections, verdicts and signatures through Review. Start the first job open in the background and share the private URL once. Publish later asks with another job open using the matching selector, or through a bound writer. The open page updates in place. Until #698 lands, the owner has to tell the agent after submitting in Review. Then run 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 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 loop for recovery, close and the temporary package-only host transition pending #700.

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, follow next to record the owner's correction with amend direction-review. See the live Review flow and forward amendments.

The clock

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

  • 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 seethrough and assemble.
  • docs/LESSONS.md — the self-check every version passes before anyone looks, and the review lessons behind it.
  • templates/ — the empty project.json and collection.json skeletons, and a worked example (example-interview.md, example-project.json) on a made-up painting. Its sign-offs are synthetic fixture records. The remesh example records a request for a finer torso mesh as a forward amendment. Remesh record

Verify the installed examples

From a consumer project with @rig-c/create installed, run:

bun node_modules/@rig-c/create/scripts/verify-example-seals.ts

The shipped, dependency-free script verifies every files[] entry and project_sha256 in the six example-chain checkpoint manifests (currently 327 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.

Licence

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.

About

Projects for rig-c: the user's direction, an interview and a signed plan before any rigging

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages