TheWorkshop

TheWorkshop is a lean execution-contract skill for Codex. It keeps one durable answer to five questions:

1. What outcome are we trying to produce?
2. What observable facts make it done?
3. What constraints must survive the work?
4. Which commands verify the result?
5. Which decisions are worth preserving?

Everything else belongs to Codex or to a specialized skill. Native plans track the current steps. Native goals handle explicitly requested long-running work. Native subagents handle independent bounded tasks when authorized. Hooks, apps, browser tools, security workflows, and memory keep their own contracts.

TheWorkshop does not build a second agent runtime.

Why v1 is smaller

The v0.x line grew into a project/workstream/job hierarchy with dashboards, reward scores, telemetry, spend estimation, workflow runners, custom subagent profiles, memory curators, and optional provider adapters. Those surfaces duplicated capabilities now owned by Codex and made a small skill expensive to understand and maintain.

Version 1 removes that machinery. The entire active product is:

• WORKSHOP.md: one human-readable execution contract in the target repository
• skills/theworkshop/SKILL.md: concise agent guidance
• skills/theworkshop/scripts/theworkshop.py: dependency-free init, check, and status commands
• .codex-plugin/plugin.json: current Codex plugin packaging

Historical v0.x releases remain available from Git tags and GitHub Releases. Version 1 does not migrate, rewrite, or delete existing v0.x project data.

The contract

---
version: 1
state: active
risk: normal
updated: 2026-07-14
---

# Ship the release

## Outcome

Users can install the release from the public package.

## Done when

- [ ] The package installs in a clean environment.
- [ ] The documented smoke test passes.

## Constraints

- Preserve the public API.
- Do not publish without maintainer approval.

## Checks

- `python3 -m unittest discover -s tests -v`
- `python3 -m build`

## Decisions

- Keep the package dependency-free.

States are proposed, active, blocked, and done. Risk is low, normal, high, or critical. A done contract cannot contain unchecked completion criteria. A blocked contract must include a concrete ## Blocker section.

The checker validates the declaration; it deliberately never executes commands from the file.

Quick start

From this repository:

python3 skills/theworkshop/scripts/theworkshop.py init \
  --root /path/to/repo \
  --title "Ship the release" \
  --goal "Users can install the release from the public package." \
  --done "The package installs in a clean environment." \
  --done "The documented smoke test passes." \
  --check "python3 -m unittest discover -s tests -v"

python3 skills/theworkshop/scripts/theworkshop.py check --root /path/to/repo
python3 skills/theworkshop/scripts/theworkshop.py status --root /path/to/repo --json

init refuses to overwrite an existing contract. check and status find the nearest WORKSHOP.md from the supplied path upward.

Install

The repository is packaged as a Codex plugin and can also be installed as a standalone skill.

• Plugin: install TheWorkshop from a configured Codex plugin marketplace after the v1 package is published.
• Standalone skill: install skills/theworkshop with the Codex skill installer or copy that directory into your Codex skills directory.
• Development: clone the repository and invoke the CLI directly as shown above.

The skill has no runtime dependencies beyond Python 3.11+ for the optional checker.

Upgrading a standalone v0 install

Version 0 documented cloning the whole repository directly at $CODEX_HOME/skills/theworkshop. Version 1 moves the installable skill to skills/theworkshop, so an in-place git pull leaves the old destination without a root SKILL.md.

Move the v0 install aside, then install only the v1 skill directory. The move is intentionally reversible until the new skill is verified:

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mv "$CODEX_HOME/skills/theworkshop" "$CODEX_HOME/theworkshop-v0-backup"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo CongressionalInsights/theworkshop \
  --path skills/theworkshop \
  --ref v1.0.0

The backup is deliberately outside skills/, so Codex cannot discover the legacy skill alongside v1. Restart Codex, invoke $theworkshop, and remove the backup only after the v1 skill is visible. Existing v0 project data is not modified by this migration.

What belongs here

Use TheWorkshop when work is substantial enough that the definition of done or governing constraints could drift during execution. Skip it for simple questions, tiny edits, or tasks whose contract is already precise and local.

TheWorkshop may preserve:

• the outcome
• observable completion criteria
• non-negotiable constraints and approvals
• commands that verify the result
• durable scope decisions
• a concrete blocker while work is blocked

TheWorkshop must not create:

• project/workstream/job directory trees
• dashboards or task trackers
• reward, score, spend, or token ledgers
• custom subagent telemetry
• memory or lesson-curation systems
• UAT artifact frameworks
• background loop runners
• provider-specific planning councils

If the task needs security analysis, browser QA, data analysis, autoresearch, release management, image generation, or another specialized workflow, use the skill that owns that domain. TheWorkshop can hold the shared outcome and boundary without reimplementing the domain tool.

Development

python3 -m compileall -q skills/theworkshop/scripts tests
python3 -m unittest discover -s tests -v
git diff --check

The CI suite uses only the Python standard library. Maintainers should also run the current Codex skill and plugin validators before release.

See CONTRIBUTING.md, RELEASE_CHECKLIST.md, and CHANGELOG.md.

License

MIT. See LICENSE.