STAGE Project Map
Last reviewed: 2026-07-30
Map profile: extended
Project Direction
STAGE is a human-directed method and Codex plugin for agent-assisted game engineering. The current method release is 0.6 and separates:
- a small universal Safety Kernel;
- recommended project-native delivery guidance; and
- optional interoperability contracts for maps, operations, ownership, evidence, studies, and artifact compatibility.
Project-map schemas remain at 0.3 with 0.1 compatibility. Case-study
schemas use 0.4 for new records while retaining 0.1 and 0.3
compatibility. Those schema versions are independent from the method release.
The owner workflow is operational and the method has been exercised across several engine and architecture shapes. STAGE is optimized first for the owner's personal spare-time Unity work; recruiting independent maintainers is not a current product goal. No longitudinal comparison establishes a productivity improvement, so STAGE remains an evidence-bounded practitioner proposal rather than a proven method or universal target architecture.
The primary operation is delivery of one accepted project-native change. A game does not need a STAGE map, custom operation, evidence package, gallery, or runtime framework. Persistent infrastructure must solve an observed recurring cost, material ownership risk, or named consumer need.
Ubiquitous Language
| Term | Meaning |
|---|---|
| STAGE | Systems-oriented, Tool-mediated, Agent-operable, Governed, Evidence-backed game engineering. |
| Safety Kernel | Eight universal rules protecting human authority, project state, canonical sources, truthful evidence, and reversibility. |
| Delivery loop | Frame -> Inspect -> Plan -> Build -> Rehearse -> Judge -> Checkpoint; recommended rather than mandatory ceremony. |
| Stage Director's Flow | Optional Cue -> Dialogue -> Ready -> Active -> Rehearsal -> Director's Call -> Checkpointed control loop for solo human-agent attention and product decisions. |
| Director's Call | Human accept, revise, reject, or defer disposition after a fair rehearsal; separate from mechanical check status. |
| Quality gate | One claim-matched Source, Model, Engine, Consumer, Distribution, or Director boundary; not a universal score. |
| Project Context Spine | Smallest versioned source chain a fresh agent follows for project rules, direction, canonical detail, and active work. |
| Task Handoff | Disposable revision-bound bridge for unfinished coherent work crossing a task boundary; never the project archive. |
| Orientation Check | Read-only fresh-task reconciliation of repository, authority, protected state, next action, and gates before mutation. |
| Orientation workflow | Explicit stage-orient route that performs an Orientation Check and stops before mutation. |
| Verification workflow | Explicit stage-verify route that checks an existing change or claim and never repairs findings. |
| Work-item branch | Short-lived branch and isolated worktree for one Ready item, with declared path ownership and integration order. |
| Build identity | Exact source and environment coordinates for one binary; separate from its product release version and data contract versions. |
| Gameplay Design Dialogue | Human-led intent formation before substantial implementation of a new or materially changed gameplay premise. |
| Player Experience Gate | Human accepted, blocked, or not tested decision controlling broad expansion of a new or materially changed player-facing loop. |
| Optional contract | A normative artifact interface that applies only after deliberate adoption. |
| Production consumer | The real caller, engine path, middleware, authoring tool, platform, or player route that consumes changed behavior. |
| Consumer-complete verification | The smallest truthful evidence route containing the production consumer and every boundary material to the claim. |
| Project map | Optional human entry point for direction, architecture, operations, ownership, and evidence. |
| Project manifest | Machine-readable companion to an adopted project map. |
| Maintainer Laboratory | This repository's optional schemas, profiles, trials, migrations, probes, and release machinery. |
| Earned Infrastructure | Persistent tooling or structure retained because an observed recurring job or risk justifies its cost. |
| Decision-bearing artifact consumer | A concrete decision or operation that needs durable output the live project cannot provide. |
Do not call STAGE an engine, AI-first architecture, autonomous development, empirically proven method, conformance score, or maturity ladder.
Repository Domains
The documentation map is the canonical navigation surface for practitioner guidance, maintainer procedures, evidence, decisions, and release history.
| Domain | Responsibility | Entry points |
|---|---|---|
| Safety and method | Define the Safety Kernel, recommended delivery, attention, task-continuity, change-integration, release, gameplay-design, and quality-gate guidance, vocabulary, and decisions | SPEC.md, docs/method.md, docs/directors-flow.md, docs/task-continuity.md, docs/change-and-release-workflow.md, docs/quality-and-ci.md, docs/gameplay-design-dialogue.md, docs/glossary.md, docs/adr/ |
| Artifact contracts | Maintain optional project/study schemas, templates, compatibility, and migration | schemas/, templates/, docs/compatibility.md |
| Agent package | Package implicit delivery plus explicit orientation, verification, and mapping procedures without the Maintainer Laboratory, and expose the package through the repository-local marketplace | .agents/plugins/marketplace.json, plugin/.codex-plugin/plugin.json, plugin/skills/ |
| Human documentation | Render selected canonical sources through a removable Docusaurus reading interface without creating another source of truth | website/, docs/documentation-surfaces.md |
| Maintainer operations | Validate source quality, contracts, packages, links, snapshots, migrations, profiles, and release state | pyproject.toml, .github/workflows/quality.yml, scripts/, tests/, docs/maintaining-stage.md |
| Evaluation | Preserve origin history, external studies, failed experiments, synthesis, and evidence limits | docs/evaluation.md, docs/case-study-synthesis.md, trials/ |
| Optional Solo Unity profile | Record one personal Unity dependency and operation baseline as a question set, not a required stack | profiles/solo-unity/ |
Visual implementation, inspection, and polish are ordinary delivery guidance, not another STAGE domain or plugin route. See Visual Work. A persistent almanac, gallery, bestiary, model viewer, or world previewer belongs to the game or authoring tool when it has an independent user and value.
Composition And Lifecycle
SPEC.md is authoritative for the Safety Kernel and explicitly adopted
contracts. Guidance and skills explain or operationalize it without adding
hidden requirements. Historical ADRs preserve why earlier interfaces were
introduced, corrected, or retired.
The installable plugin/ package contains only:
stage-deliver-change, the primary implicit delivery route;stage-orient, an explicit read-only context-recovery route;stage-verify, an explicit check-only claim-verification route; andstage-map-project, an explicit-only adoption, onboarding, audit, or map maintenance route.
The remaining repository is the Maintainer Laboratory. A method change moves through research or observed failure, an ADR when the public shape changes, specification and guidance edits, structural and behavioral validation, checkpointing, and a compatibility-meaningful release.
The 1.0 readiness review is the current owner-facing decision record for the proposed stable contract, support boundary, and release gates. It does not itself declare a release.
Artifact validators select the schema version declared by each map or study. They do not silently migrate older supported artifacts.
Authoring Surfaces
| Surface | Canonical source | Authority |
|---|---|---|
| Safety rules and optional contracts | SPEC.md | Human |
| Vocabulary and rationale | docs/glossary.md, docs/adr/, explanatory docs/ | Human |
| Packaged agent behavior and local marketplace | .agents/plugins/marketplace.json, plugin/.codex-plugin/plugin.json, plugin/skills/ | Human, structurally validated |
| Human documentation interface | canonical Markdown plus website/ navigation and presentation | Human; generated site output is disposable |
| Schemas and migration | versioned schemas/, templates/, compatibility docs and tests | Human, compatibility reviewed |
| Visual-work guidance | docs/visual-work.md, packaged conditional reference, engine profiles | Human guidance; product acceptance remains project-owned |
| Solo attention, task-continuity, change-integration, release, and quality-gate guidance | docs/directors-flow.md, docs/task-continuity.md, docs/change-and-release-workflow.md, docs/quality-and-ci.md, packaged conditional references | Human guidance; prioritization, project context, asset ownership, release authority, quality policy, and product acceptance remain human-owned |
| Evaluation record | trials/, docs/evaluation.md, synthesis | Human research record |
Maintainer Operations
| Operation | State | Claim boundary |
|---|---|---|
| Change gate | Available | Ruff lint/format checks, core tests, structured artifacts, studies, maps, links, and diff hygiene |
| Release gate | Available | Change gate plus optional Solo Unity profile contracts |
| Hosted quality gate | Available | Pinned, read-only clean-checkout execution of the release gate; no engine or product-acceptance claim |
| Conventional Commit policy | Available | Root commitlint and Husky tooling plus hosted push and pull-request checks; release approval remains human-owned |
| Draft release proposal | Available | Release Please proposes synchronized versions and changelog after successful main quality; it cannot tag, create a GitHub Release, refresh the plugin, or publish source |
| Project-map validation | Available | Schema, declared target paths, evidence classes, and optional provenance |
| Case-study validation | Available | Exact declared study schema plus 0.4 product-experience gate semantics |
| Repository snapshot | Available | Pre/post source state for read-only claims |
| Semantic artifact hash | Available | Timestamp-insensitive comparison of supported artifact bundles |
| Manifest migration | Available, approval-sensitive | Separate conservative 0.1 to 0.3 candidate |
| Skill/plugin validation | Available | Codex package structure, not semantic behavior |
| Behavior probe | Optional | Model- and toolchain-bound routing or stopping observation; human interpretation required |
| Human documentation build | Available | Docusaurus renders selected canonical Markdown and screens the public artifact; it does not validate method truth |
| Human documentation publication | Available | A successful main quality run publishes its exact screened site to the dedicated public mirror; Cloudflare Pages serves that mirror at stage.zoshachi.com without private-source access |
| Release | Human-only | Commit, tag, push, package refresh, and explicit evidence boundary |
Operation definitions remain available in this durable map. Fresh outcomes,
counts, revisions, and tool versions belong in release notes or study records,
not here.
Ownership Boundaries
| Pattern | Authority | Rule |
|---|---|---|
SPEC.md, docs/**, templates/** | Human | Edit intentionally; do not convert one case preference into a universal requirement. |
frozen schemas/*-v0.1.schema.json | Legacy compatibility | Validate but do not modify in place. |
| current schemas and aliases | Human | Keep exact schemas, aliases, validators, templates, and compatibility guidance synchronized. |
scripts/**, tests/** | Human | Test executable contracts and structural boundaries, not preferred paragraph wording. |
pyproject.toml, requirements-dev.txt, .github/** | Human | Quality policy and hosted gates are check-only; do not weaken, suppress, or mutate merely to obtain green status. |
package.json, package-lock.json, .commitlintrc.cjs, .husky/** | Human | Keep repository commit policy deterministic; do not infer release authority from a commit type. |
plugin/** | Human | Keep the installed package concise and independent of maintainer-only files. |
.agents/plugins/** | Human | Keep the repository-local marketplace pointed at the packaged plugin/ subtree. |
website/** | Human | Keep configuration and presentation derived from canonical sources; never edit generated build output as documentation. |
.github/workflows/docs-mirror.yml | Human | Keep mirror publication downstream of successful main quality evidence; do not broaden source or release authority through the deploy key or hosting integration. |
.github/workflows/release-proposal.yml | Human | Keep proposals draft-only and downstream of successful main quality; never add tag, GitHub Release, package refresh, or publication steps. |
profiles/** | Human, non-normative | Treat as personal or engine question sets, not universal dependencies. |
trials/** | Human research record | Preserve failures, corrections, independence, and absent maintainer acceptance. |
| caches and local environments | Runtime | Never commit as project intent. |
Verification Boundary
Deterministic local and hosted repository checks establish source-format, lint, schema, validator, link, package, migration, and compatibility claims. Behavior probes can observe a specific model/toolchain invocation but are not deterministic release gates. External maps establish legibility, not adoption or improved maintenance.
Agents can verify rules, state, encoded policies, distributions, and bounded presentation mechanics. Gameplay theory and automated play produce hypotheses, not product acceptance. Visual, audio, interaction, balance, pacing, lived accessibility, and fun claims require the real project and accountable human judgment; broader audience claims require representative target players. The Circussy detached visual-rehearsal trial is retained as negative evidence: package validity did not create useful review, while one native production-content motion preview answered a concrete question.
Known Risks And Gaps
- Independent transferability and longitudinal productivity remain unestablished claim boundaries, not current personal-workflow release gates.
- The specification and plugin are still pre-1.0 and may simplify further.
- The proposed 1.x contract, compatibility policy, and support boundary still require explicit owner acceptance.
- Optional schemas permit project extensions, so ecosystem interoperability is bounded rather than universal.
- Behavior probes are expensive and model-bound; phrase-lock tests can create specification theater rather than reliable behavior.
- Same-director case studies can reveal failures but cannot establish external transferability or human acceptance for another project.
Decision Rights
- Human-only: gameplay intent and product acceptance, normative method changes, compatibility removal, publishing, release, and research interpretation.
- Delegated: bounded inspection, implementation within authorized scope, deterministic validation, snapshots, migration candidates, and mechanical documentation checks.
- Shared: terminology, architecture interpretation, evidence planning, risk assessment, and proposed method revisions.