autonomous-workshop: Instructions file for Claude Code

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. The one exception is the fixed Component Reviewer role of new runs, which runs at low (ADR 0077). 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; in new runs it also holds the fixed Make role agents, component-worker and component-reviewer (ADR 0077) and contract-reviewer (ADR 0085), which are not Inventors. 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.