Using STAGE With Codex

This is the owner-facing operating guide for the STAGE Codex plugin. It explains which workflow to invoke, what it may change, and where human authority remains required.

The plugin is optional. The Safety Kernel and delivery method can be followed without installing anything.

Install Or Refresh

From the STAGE repository root:

codex plugin marketplace add .
codex plugin add stage-game-engineering@stage-local
codex plugin list --marketplace stage-local

Codex caches installed plugin releases. After the package version changes, repeat the plugin add command and open a new task. An already-open task keeps the skill snapshot with which it started.

Choose One Workflow

You want to...	Invoke	Mutation boundary
Implement, fix, tune, refactor, diagnose, or polish one game change	Describe the change normally; stage-deliver-change is the implicit primary route	May mutate only the authorized outcome
Start a fresh task safely, recover from a handoff, switch repositories, or understand a dirty tree	$stage-game-engineering:stage-orient	Read-only
Check whether an existing delta, revision, build, or behavior claim is actually supported	$stage-game-engineering:stage-verify	Check-only; never fixes findings
Deliberately adopt, refresh, or externally audit a STAGE project map	$stage-game-engineering:stage-map-project	Explicit map scope only

Use the full plugin-qualified name for explicit workflows. A bare skill name is not resolved consistently by every Codex surface.

Begin A Fresh Task

Open the task in the Codex project rooted at the game repository. Then invoke:

$stage-game-engineering:stage-orient

The workflow snapshots repository coordinates and protected paths, follows the smallest relevant Context Spine, reconciles any handoff, and reports the safe next action. You do not need to paste the orientation questionnaire into every task.

Orientation stops before mutation. Once the report is correct, give one concrete outcome:

Fix the Stage Door so it always appears after the Headliner is defeated.

The ordinary delivery workflow then takes over. A clean idle repository is allowed to report needs-direction; STAGE does not invent a work item merely to keep an agent busy.

Verify Without Fixing

Invoke:

$stage-game-engineering:stage-verify

Name the claim and scope when they are not obvious:

$stage-game-engineering:stage-verify
Verify the current dirty delta fixes controller navigation on the performer
selection screen without changing mouse navigation.

Verification inventories the delta, identifies the production consumer, and selects material Source, Model, Engine, Consumer, Distribution, and Director lanes. It reports passed, failed, unavailable, not run, or not material per lane.

The workflow does not repair failures, regenerate baselines, or weaken checks. Start a separate delivery request after reviewing the result.

Human Decisions Stay Human

Codex may inspect, research, challenge assumptions, implement, instrument, and run project operations. The owner still decides:

• what game should be made;
• which experience hypothesis is worth testing;
• whether visuals, audio, feel, balance, pacing, comprehension, and fun are acceptable;
• whether destructive or externally visible actions are authorized; and
• whether a checkpoint or release should be accepted.

Automated verification can establish mechanical and integration claims. It cannot certify that a game is enjoyable.

Project Knowledge And Task Memory

Keep durable project knowledge in the repository's Context Spine:

1. AGENTS.md for mandatory operating rules;
2. STAGE.md or another concise project map when the project has earned one;
3. a documentation index linking canonical detail; and
4. an active work item only while a coherent outcome is unfinished.

Use a revision-bound Task Handoff only when unfinished work crosses a task boundary. Conversation history is useful working context, not the project archive. See Task Continuity And Context Recovery.

What Not To Add By Default

• Do not require a project map before ordinary game work.
• Do not paste the full handbook into agent instructions.
• Do not create a detached visual evidence product when the engine or game already owns the relevant view.
• Do not use Linear, another tracker, or sprint ceremony as STAGE's source of truth. A tracker may later mirror Ready work when its recurring coordination value exceeds its maintenance cost.
• Do not treat the human documentation site as a second canonical knowledge base.

For one developer using agents in spare time, the repository, short Codex tasks, the optional Stage Director's Flow, and coherent Git checkpoints are the default operating system.