Theworkshop

The Workshop

The Workshop is a thin contract layer over native Codex. Its only durable project artifact is WORKSHOP.md.

Use it when a task is long-running, high-stakes, easy to derail, or likely to cross context boundaries. Do not activate it for a simple answer, a small edit, or work that already has an adequate checked-in contract.

Product boundary

The Workshop owns:

• the intended outcome;
• objective completion criteria;
• constraints and mutation boundaries;
• the checks that prove completion;
• durable decisions that future turns must preserve.

Native Codex owns:

• conversational planning and plan updates;
• goals and long-running continuation;
• subagent spawning, steering, waiting, and lifecycle state;
• browser, computer-use, plugins, apps, skills, hooks, and other tools;
• approvals, permissions, notifications, and thread state.

Do not create project/workstream/job trees, dashboards, reward scores, custom subagent logs, memory curators, spend ledgers, UAT artifacts, or loop runners. Use an existing specialized skill when the task is really data analysis, security, browser QA, autoresearch, release work, or another owned workflow.

Workflow

1. Read the repository instructions, current files, git state, and relevant live state before proposing a contract.
2. Reuse an existing WORKSHOP.md when present. Treat it as a contract, not a status dump.
3. Create WORKSHOP.md only when the task benefits from durable scope. Use the CLI initializer or the template in assets/WORKSHOP.md.
4. Ask the user only for decisions that materially change the outcome, authority, risk, or irreversible scope. Record the answer under ## Decisions.
5. Use the native plan surface for the changing execution plan. Create a native goal only when the user explicitly requests long-running goal behavior and the runtime exposes it.
6. At the delegation checkpoint, use native subagents only when the user or higher-priority instructions authorize delegation and the work is independent and bounded. Do not mirror native agent state into custom files.
7. Execute the work with the relevant repo and domain tools. Preserve unrelated changes and obey the declared mutation boundary.
8. Run every applicable check from ## Checks. A command listed there is evidence only after its current run succeeds.
9. Mark completion boxes only when their claims are objectively true. Set state: done only when all completion criteria are checked and all applicable checks pass.
10. Close with the outcome, verification, residual risk, and exact remaining blocker if incomplete.

CLI

The dependency-free helper lives at {baseDir}/scripts/theworkshop.py, where {baseDir} is the installed skill root.

Initialize a contract only after you know the goal, at least one completion criterion, and at least one verification command:

python3 {baseDir}/scripts/theworkshop.py init \
  --root /path/to/repo \
  --title "Outcome title" \
  --goal "Concrete end state" \
  --done "Objective completion criterion" \
  --check "repo-owned verification command"

Validate or summarize an existing contract:

python3 {baseDir}/scripts/theworkshop.py check --root /path/to/repo
python3 {baseDir}/scripts/theworkshop.py status --root /path/to/repo

The helper never runs the declared checks. Codex must inspect and run them through the normal tool and approval boundary.

Contract rules

Read references/contract.md before creating or materially changing a contract.

Keep WORKSHOP.md short enough to reread at every important transition. It is not a transcript, backlog, dashboard, or memory store.

A valid contract has:

• frontmatter with version, state, risk, and updated;
• ## Outcome, ## Done when, ## Constraints, ## Checks, and ## Decisions;
• at least one unchecked or checked completion criterion;
• at least one concrete verification command;
• a ## Blocker section when state: blocked.

Never weaken a completion criterion merely to obtain a clean closeout. Change the contract only when the user changes the intended outcome or current evidence proves the original criterion is invalid.