autonomous-workshop

# Autonomous Workshop agent instructions

`AGENTS.md` is directory-scoped guidance, not a role selector. This root file
applies to any coding-agent session operating in the source repository. Shared
architecture rules come first. The section **Coding agents building this
repository** is specifically for agents modifying, reviewing, testing, or
documenting Workshop; it is not the product-run workflow.

A normal product run is launched in a separate persistent toy project. The host
materializes the complete `.agents/product-run/` template there, including its
root `AGENTS.md` and nested `.agents/skills/autonomous-workshop/SKILL.md`.

## Shared runtime architecture

Autonomous Workshop is a thin, trustworthy workflow harness around a native
coding-agent runtime. Codex is the implemented Manager runtime; Claude Code and
Grok Build are planned adapters to the same boundary. One product run gives the
selected runtime the cognitive and tool-using work. The Workshop host retains
lifecycle order, durable state, deterministic gates, budgets, and authorized
external effects.

The root native Codex session is the Workshop Manager. It may use Codex-native
subagents for bounded parallel or specialist work, including matching and
working as the selected Inventor. Those agents remain children of the one
product-run session; they are not Python workers or separately launched Codex
processes.

All implementation and product-run work must preserve these boundaries:

- `workshop wish` persists the exact Wish and frozen effort, creates a private
  run workspace, and launches one native coding-agent session for the first
  enabled creative stage.
- `workshop resume` resumes that exact session id. Stages are durable lifecycle
  checkpoints, not separate one-shot model sessions or personas.
- Native Codex performs Inventor selection, research, concept exploration,
  creation, inspection, and repair with its own tools and applicable skills.
- New runs freeze one selectable lifecycle: Spark is `Wish -> Make -> Release`,
  Forge is `Wish -> Invent -> Make -> Release`, and Quest is
  `Wish -> Invent -> Make -> Playtest -> Release`. Passed-through stages create
  no turn, artifact, gate, or evidence. Spark/Forge Release explicitly records
  Playtest `not-run`; Quest requires passing Playtest evidence. Frozen older
  runs retain their materialized protocol when resumed.
- New marked Spark runs select the Inventor in Workshop setup before Make.
  An explicit `--inventor` binds immediately; otherwise the native Manager
  chooses once, and the same root session continues into Make. Setup is not
  a separate Match Goal or product gate. Older runs retain their frozen
  selection protocol and accepted inventor.
- Codex runs freeze their selected model, reasoning effort, and total token
  allowance across stages, descendants, and resumes. Token-budget runs have
  no Workshop wall-clock, native-turn, proposal-retry, or lifecycle-round spending cap.
  Make retains its own frozen engineering checks and review allowance.
  Pending usage is not subject to a first-report timer; completed usage must
  still be accounted for. Other runtime adapters retain their frozen policy.
- Spark accepts Make's output as-is: no duplicate host CAD rebuild, geometry
  acceptance pass, or new manual review. Host-only Release publishes existing
  Make assets with deterministic site metadata; it creates no native Release
  turn or new PDF. A run created with `--no-publish` freezes one restriction:
  Release still seals and projects the toy locally with `unreleased`
  publication status, but performs no Factory effect, credential read or ledger
  write, and no resume can add or drop that restriction. Identity, exact bytes, credential isolation, and authenticated
  effect reconciliation remain host responsibilities. Forge/Quest keep their
  existing verification. See ADR 0061 for migration and live-acceptance status.
- A capable Forge or Quest Make attempt may return directly to Invent only when
  exact preserved evidence proves that the sealed concept prevents any
  conforming build. Quest Playtest returns directly to Make for implementation
  defects or to Invent for concept defects. Every backward edge records a
  failed host gate, invalidates the named downstream artifacts, and consumes
  the shared revision history (and the frozen revision allowance only for
  non-token-budget runs). Spark has no separate Invent stage
  to return to, and frozen runs gain no capability they did not materialize.
- Every active creative Invent, Make, Playtest, or PDF-first Release attempt uses
  one native Codex Goal with one objective, proof artifacts, and a verifiable
  stopping condition: the current stage finalizer succeeds. New Spark selection
  is Workshop setup; Spark Publish is a host effect, not another creative Goal.
  Older selection protocols remain folded into their first active stage.
  Only one Goal is active at a time. Codex works toward it by observing,
  acting, evaluating exact output,
  and improving. That loop is native-agent behavior, not a Python program.
  Wish is a host boundary rather than an agent Goal. Authenticated publication
  is the host-owned effect portion of Release; physical Operations begin only
  after Workshop completes.
- An Inventor is a declared specialist bundle. `TASTE.md` governs creative
  judgment; `inventor.json` identifies the specialist and binds its exact
  extension trees; the required `<id>-inventor` skill defines its
  primary method, while optional additional Inventor-prefixed skill trees may
  contain scripts, references, assets, and tested deterministic tools for
  specialist craft. Custom code may not become an agent scheduler,
  prompt loop, lifecycle engine, or effect path.
- The host materializes every eligible Inventor as an official project-scoped
  Codex custom agent under `.codex/agents/`, bound to its exact identity, Taste,
  and skill bytes. That directory is the sole Inventor roster in a run. Codex
  owns native spawning, routing, and synthesis. The root session alone receives
  host stage authority and submits a stage proposal; child agents cannot
  advance gates or perform external effects.
- Python is narrow trusted substrate: typed contracts, deterministic tools and
  gates, artifact hashing, checkpoints, exclusive run-mutation locks, budgets, sandbox/session
  boundaries, authorization, idempotency, receipts, and reconciliation.
- External-effect credentials never enter the native agent subprocess. The
  host alone performs authorized Factory, payment, manufacture, postage,
  carrier, or other authenticated effects.
- Model prose and self-scores are proposals. Only host-verified exact bytes,
  deterministic checks, and reconciled receipts advance a gate.

## Coding agents building this repository

This section is for agents building the Workshop itself. It does not tell the
per-Wish product-run agent how to Invent, Make, or Playtest a product.

Do not add a second Python agent framework. Python stage agents, structured
model calls, profile subprocesses, and Python-owned scoring or reward loops are
not extension points. Never add Python prompt chains, browsing strategy,
candidate fan-out, model judges, stage-role views, or repair reasoning.

Read `docs/NATIVE_AGENT_RUNTIME.md`,
`docs/adr/0012-codex-orchestrated-runtime.md`, and
`docs/adr/0013-manual-first-release.md`, and
`docs/adr/0014-terminal-published-release.md`, and
`docs/adr/0015-defer-playtest.md`, and
`docs/adr/0016-selectable-effort-routes.md`, and
`docs/adr/0019-frozen-spark-economics-profile.md`, and
`docs/adr/0020-signature-experience-evidence.md`, and
`docs/adr/0021-compacted-spark-and-signature-review.md`, and
`docs/adr/0022-blind-review-before-final-verification.md`, and
`docs/adr/0023-bounded-spark-turn-and-semantic-review.md`, and
`docs/adr/0050-structured-terminal-failure-diagnostics.md`, and
`docs/adr/0049-product-wide-token-budget.md`, and
`docs/adr/0060-make-round-visual-feedback-and-three-repairs.md`, and
`docs/adr/0061-spark-make-owned-verification.md`, and
`docs/adr/0062-step-only-cad-toolchain.md`, and
`docs/adr/0063-spark-component-first-make.md`, and
`docs/adr/0063-print-gates-on-source.md`, and
`docs/adr/0064-operator-selected-turn-boundary.md`, and
`docs/adr/0074-every-component-scored-against-its-own-image.md` before changing the CLI, runtime,
workflow, product-run instructions, or lifecycle orchestration. ADR 0013
supersedes ADR 0012's page-first Release details; ADR 0014 supersedes their
optional-publication and executable-Deliver details. ADR 0015 supersedes the
active Playtest stage while preserving truthful omission and frozen-run
compatibility. ADR 0016 supersedes ADR 0015's fixed topology for new runs while
preserving its truthful omission contract for Spark and Forge. The
native-session path is the production architecture. ADR 0019 freezes a
lower-cost Codex profile only for new marked Spark runs without changing their
gates or upgrading older sessions. ADR 0020 adds exact signature-experience
evidence and batched manual review without adding a host-side judge. ADR 0021
adds a frozen Spark compaction ceiling, final signature-review evidence, and a
bounded simple-manual path without splitting the Wish-wide session. ADR 0022
makes the review blind, places it before one final integrated verifier, rejects
duplicate final render families, and distinguishes core creative ownership from
carrier mechanics.
ADR 0023 adds a frozen 20-minute Spark native-turn boundary, requires the blind
critic to agree separately on subjects, action, and relationship, bounds that
critic to two rounds, and makes the integrated final CAD verifier refuse to run
before the hash-bound review exists.
ADR 0024 treats “10x quality at 0.1x cost” as a comparative North Star rather
than a literal lifecycle threshold. ADR 0025 extends the blind review to exact
form and the concept's anti-generic signature, binds it to the canonical concept
hash, and requires the final verification report inside the declared
self-contained CAD project.
ADR 0050 retains a bounded structured diagnosis for terminal provider failures
while continuing to discard unsafe free-form provider text.
ADR 0049 supersedes earlier Workshop time/turn/retry/round spending caps for
token-budget products, not Make's internal engineering or review policy.
ADR 0061 supersedes duplicate host verification and native manual
authoring for Spark only; it leaves Make's own implementation intact. Do not
reintroduce these removed boundaries from an older ADR or frozen-run fixture.
ADR 0063 makes new Spark Make work component-first: every distinct component
has its own source and isolated make-round repair loop before assembly review.
It changes native Make work and its deterministic round tool, not Workshop's
host-owned Spark acceptance boundary.
ADR 0060 requires native Manager visual feedback within Make rounds and expands
final blind review to an initial review plus three repair-and-rereview cycles
for new runs. Frozen older runs retain their original allowance and tool bytes.
ADR 0062 makes STEP the only geometry format Workshop writes, seals or ships:
the mesh export, cadgen's STL/3MF writers and the Workshop-local
print-preflight path are gone. Do not reintroduce a mesh deliverable from an
older ADR or a frozen-run fixture.
ADR 0063 supersedes ADR 0062's gate half and keeps its export half. The
`check_mesh`, `check_overhang` and `check_thickness` gates are back, reading
the B-rep directly instead of an exported mesh, so the CAD gate has two tiers
again. A product is print-ready only behind a passing `verify_project
--print-gates` run at the nozzle the print will use, declared twice — root
product status `full-with-thickness` **and** `print_ready_claim: true` — and
reproduced by the host's own rerun. A half-declared claim is refused, not
downgraded, and the legacy `--exports` full-tier replay path stays retired.
ADR 0064 adds one opt-in `--turn-minutes` override above the frozen turn
boundaries of ADR 0019, ADR 0023 and the deep-economics profiles, and supersedes
none of them: a run that does not ask keeps the exact boundary it froze. It
bounds a wall clock only; no gate, review, round or token allowance moves.
ADR 0074 scores every Contract Mode Component against its own sealed
`geometry:<id>` image at the 0.90 floor, never against the whole object, and
makes the final verifier account for every sealed image. Below the floor the
Workshop Manager may accept an image only after it stalls out, with a reason
the run reports when it ends; it is never recorded as the person's decision.
Preserve useful deterministic contracts and tests; do not reintroduce removed
cognitive orchestration as a compatibility layer.

## Repository ownership

- `src/cli/`: argument parsing, output formatting, and exit codes only.
- `src/workshop/runtime/`: native engine adapters and trusted state/effect
  boundaries.
- `src/workshop/workflow/`: lifecycle protocol, checkpoints, invalidation,
  frozen-run repair budgets, and the trusted whole-run host composition.
- `src/workshop/<stage>/`: stage-owned public contracts and deterministic tools.
- `src/workshop/make/skills/`: reusable domain skills owned by Make.
- `.agents/product-run/`: complete template materialized only into a toy
  project; its nested `.agents/skills/autonomous-workshop/` is intentionally
  invisible to repo-builder sessions.
- `.agents/product-run/.agents/skills/autonomous-workshop/scripts/stage_proposal.py`:
  run-local deterministic finalizer for exact stage contracts and outcome
  proposals; it does not reason or advance gates.
- `tests/<component>/`: tests mirroring the component that owns the behavior.

Keep the `src/` layout and the single `workshop` library namespace. The `cli`
package is its installed sibling under `src/`; CLI tests remain under
top-level `tests/`.

### Working rules

- Preserve unrelated user and agent changes in the shared worktree.
- Add contract and failure-path tests with every runtime or workflow change.
- Use deterministic fakes for CI; never weaken production gates to make a test
  pass.
- Never commit credentials, `.env` files, transcripts, run workspaces, build
  outputs, or private customer artifacts.
- Do not claim physical manufacture, delivery, publication, or live readiness
  from mocked or model-generated evidence.
- Keep documentation explicit about implemented behavior versus an accepted
  target that is still migrating.
- Make small coherent commits so other builder agents can pull frequently.

Builder agents may inspect the product-run skill when implementing or testing
its protocol. They must not treat that skill as authority to manufacture a
product, bypass a host gate, publish, or access effect credentials during
ordinary repository work.

## Product-run agents

A product-run agent follows the materialized product-run `AGENTS.md` and the
`autonomous-workshop` skill in its isolated run root. It performs one Wish's
cognitive work, reads the current immutable `STAGE.json`, and uses the
run-local proposal finalizer to propose compact outcomes to the host. It does
not use the builder-only section above as a product workflow, modify the
Workshop source as part of making a toy, or bypass host-owned gates and effect
authority.

## Agent skills

### Issue tracker

Issues live in GitHub Issues for `autonomous-ai/autonomous-workshop`, via the
`gh` CLI. See `docs/agents/issue-tracker.md`.

### Triage labels

The five canonical triage roles, each label string equal to its name. See
`docs/agents/triage-labels.md`.

### Domain docs

Single-context: `CONTEXT.md` and `docs/adr/` at the repo root. See
`docs/agents/domain.md`.