CodexKIT Repository Maintenance
Overview
Maintain and improve this repository without confusing kit-source work with game-project work. Keep the main thread responsible for repository integration, route specialist analysis to existing distributed skills, edit canonical sources, and bind every verdict to evidence.
Repository identity gate
Before any write, resolve the repository root and verify all of these facts:
.codex-plugin/plugin.json exists and declares game-studio-codex-kit.registry/capabilities.yaml exists.scripts/validate.py exists.skills/ exists.
If any check fails, stop with BLOCKED: repository identity mismatch. Do not reinterpret another repository as CodexKIT and do not apply this workflow to a game project that merely installed the plugin.
Scope
Use this skill for repository architecture, skill or agent authoring, registries, packs, personas, generators, adapters, project initialization, GitHub Actions, tests, packaging, documentation, versioning decisions, release readiness, and evidence-backed technical-debt cleanup.
Keep gameplay, content, services, assets, and operational changes in consuming game projects outside this workflow. Treat private studio projects, .research/, and external repositories as read-only unless a separate explicit request authorizes their use.
Intake
- Record repository path, branch, requested outcome, owned write scope, do-not-touch scope, and current tracked or untracked changes.
- Read
AGENTS.md and the relevant canonical files before selecting an edit.
- Classify the request using the routing table.
- Preserve unrelated work and assign one writer per file, shared registry, or generated output.
Routing
| Maintenance class |
Route or evidence source |
| Failure, regression, CI, or unexpected behavior |
evidence-first-debugging and the exact failing command or Actions log |
| Skill creation, revision, trigger collision, provenance, or maturity |
skill-authoring-and-audit |
| Build, test, package, runtime, or cross-platform verification |
build-and-runtime-verification |
| Broad diff or independent review |
review-swarm with read-only review lanes |
| Candidate readiness or semantic-version decision |
release-candidate-preflight |
| Multi-agent ownership |
studio-agent-orchestration after repository scope is fixed |
Routing does not transfer repository integration ownership. Reuse the specialist workflow; do not copy it into this skill.
Maintenance workflow
- Reproduce the failure or collect concrete evidence for the requested improvement.
Completion criterion: the current behavior, gap, or drift is observable and classified as
Verified, Snapshot, Unverified, or BLOCKED.
- Trace the root cause to a canonical source, registry, generator, test contract, environment, or CI platform boundary.
Completion criterion: the selected owner explains the observed evidence without relying on a generated-file patch.
- Define the smallest complete write scope and restore path.
Completion criterion: owned paths and do-not-touch paths are explicit, and unrelated work remains preserved.
- Write or update failing tests before production behavior when the task changes executable behavior.
Completion criterion: the test fails for the missing behavior rather than a fixture or syntax error.
- Edit canonical sources only.
Completion criterion: no generated adapter, pack, or
skills/*/scripts/ file was hand-patched.
- Regenerate only affected resources and inspect the visible diff.
Completion criterion: generated outputs match their canonical owners and unmanaged project-local files remain untouched.
- Run focused verification, then every local gate required by
AGENTS.md.
Completion criterion: each command has an exit code and any artifact path required for a PASS claim.
- Inspect distribution and version impact.
Completion criterion: internal maintenance files remain outside registries, packs, adapters, scaffold templates, and plugin version changes unless the distributed payload actually changed. Any plugin version change remains
BLOCKED for deploy or release readiness until every required GitHub Actions job for the exact pushed commit and version reaches terminal PASS; local PASS is not a substitute.
- Produce the handoff.
Completion criterion: the report contains scope, changes, evidence, risks, restore information, and separately authorized next actions.
Canonical ownership rules
- Change a distributed skill under
skills/, then synchronize its bundled resources through scripts/sync_skill_resources.py.
- Change root helpers under
scripts/; never patch mirrored skills/*/scripts/ copies.
- Change agent-role catalog entries through
agents/ and registry/agent-roles.yaml; never patch scaffold copies directly.
- Change plugin metadata only when distribution changes require it.
- Keep
.agents/skills/codexkit-repository-maintenance/ and .codex/agents/codexkit-maintainer.toml repository-local. Never add either ID to registries, packs, adapters, or project scaffold templates.
Verification ladder
Start with the narrowest affected test, then run:
python -B scripts/sync_skill_resources.py . --check
python -B -m unittest discover -s tests -p "test_*.py"
python -B scripts/validate.py .
python -B scripts/route_eval.py .
python -B scripts/secret_scan.py .
python -B scripts/policy_check.py .
python -B scripts/external_collision_eval.py .
python -B scripts/doctor.py --check --root .
Run lifecycle audits and governed dogfood commands when their evidence is required. Unavailable upstream content, model runners, session history, or live projects remain BLOCKED; they never become PASS.
Handoff
Return repository path, branch, goal, owned scope, do-not-touch scope, changed files, commands and exit codes, artifacts, Verified results, Snapshot assumptions, Unverified hypotheses, BLOCKED items, failures, decisions, restore information, next actions, and a reactivation prompt. Commit, push, publish, deploy, and release remain separate actions requiring explicit authorization.
1---2name: codexkit-repository-maintenance3description: Use when maintaining or improving the GameStudio-CodexKIT source repository, including CI, governance, catalog, generators, adapters, packaging, documentation, versioning, or release readiness.4---56# CodexKIT Repository Maintenance78## Overview910Maintain and improve this repository without confusing kit-source work with game-project work. Keep the main thread responsible for repository integration, route specialist analysis to existing distributed skills, edit canonical sources, and bind every verdict to evidence.1112## Repository identity gate1314Before any write, resolve the repository root and verify all of these facts:1516- `.codex-plugin/plugin.json` exists and declares `game-studio-codex-kit`.17- `registry/capabilities.yaml` exists.18- `scripts/validate.py` exists.19- `skills/` exists.2021If any check fails, stop with `BLOCKED: repository identity mismatch`. Do not reinterpret another repository as CodexKIT and do not apply this workflow to a game project that merely installed the plugin.2223## Scope2425Use this skill for repository architecture, skill or agent authoring, registries, packs, personas, generators, adapters, project initialization, GitHub Actions, tests, packaging, documentation, versioning decisions, release readiness, and evidence-backed technical-debt cleanup.2627Keep gameplay, content, services, assets, and operational changes in consuming game projects outside this workflow. Treat private studio projects, `.research/`, and external repositories as read-only unless a separate explicit request authorizes their use.2829## Intake30311. Record repository path, branch, requested outcome, owned write scope, do-not-touch scope, and current tracked or untracked changes.322. Read `AGENTS.md` and the relevant canonical files before selecting an edit.333. Classify the request using the routing table.344. Preserve unrelated work and assign one writer per file, shared registry, or generated output.3536## Routing3738| Maintenance class | Route or evidence source |39|---|---|40| Failure, regression, CI, or unexpected behavior | `evidence-first-debugging` and the exact failing command or Actions log |41| Skill creation, revision, trigger collision, provenance, or maturity | `skill-authoring-and-audit` |42| Build, test, package, runtime, or cross-platform verification | `build-and-runtime-verification` |43| Broad diff or independent review | `review-swarm` with read-only review lanes |44| Candidate readiness or semantic-version decision | `release-candidate-preflight` |45| Multi-agent ownership | `studio-agent-orchestration` after repository scope is fixed |4647Routing does not transfer repository integration ownership. Reuse the specialist workflow; do not copy it into this skill.4849## Maintenance workflow50511. Reproduce the failure or collect concrete evidence for the requested improvement.52 Completion criterion: the current behavior, gap, or drift is observable and classified as `Verified`, `Snapshot`, `Unverified`, or `BLOCKED`.532. Trace the root cause to a canonical source, registry, generator, test contract, environment, or CI platform boundary.54 Completion criterion: the selected owner explains the observed evidence without relying on a generated-file patch.553. Define the smallest complete write scope and restore path.56 Completion criterion: owned paths and do-not-touch paths are explicit, and unrelated work remains preserved.574. Write or update failing tests before production behavior when the task changes executable behavior.58 Completion criterion: the test fails for the missing behavior rather than a fixture or syntax error.595. Edit canonical sources only.60 Completion criterion: no generated adapter, pack, or `skills/*/scripts/` file was hand-patched.616. Regenerate only affected resources and inspect the visible diff.62 Completion criterion: generated outputs match their canonical owners and unmanaged project-local files remain untouched.637. Run focused verification, then every local gate required by `AGENTS.md`.64 Completion criterion: each command has an exit code and any artifact path required for a PASS claim.658. Inspect distribution and version impact.66 Completion criterion: internal maintenance files remain outside registries, packs, adapters, scaffold templates, and plugin version changes unless the distributed payload actually changed. Any plugin version change remains `BLOCKED` for deploy or release readiness until every required GitHub Actions job for the exact pushed commit and version reaches terminal PASS; local PASS is not a substitute.679. Produce the handoff.68 Completion criterion: the report contains scope, changes, evidence, risks, restore information, and separately authorized next actions.6970## Canonical ownership rules7172- Change a distributed skill under `skills/`, then synchronize its bundled resources through `scripts/sync_skill_resources.py`.73- Change root helpers under `scripts/`; never patch mirrored `skills/*/scripts/` copies.74- Change agent-role catalog entries through `agents/` and `registry/agent-roles.yaml`; never patch scaffold copies directly.75- Change plugin metadata only when distribution changes require it.76- Keep `.agents/skills/codexkit-repository-maintenance/` and `.codex/agents/codexkit-maintainer.toml` repository-local. Never add either ID to registries, packs, adapters, or project scaffold templates.7778## Verification ladder7980Start with the narrowest affected test, then run:8182```text83python -B scripts/sync_skill_resources.py . --check84python -B -m unittest discover -s tests -p "test_*.py"85python -B scripts/validate.py .86python -B scripts/route_eval.py .87python -B scripts/secret_scan.py .88python -B scripts/policy_check.py .89python -B scripts/external_collision_eval.py .90python -B scripts/doctor.py --check --root .91```9293Run lifecycle audits and governed dogfood commands when their evidence is required. Unavailable upstream content, model runners, session history, or live projects remain `BLOCKED`; they never become PASS.9495## Handoff9697Return repository path, branch, goal, owned scope, do-not-touch scope, changed files, commands and exit codes, artifacts, `Verified` results, `Snapshot` assumptions, `Unverified` hypotheses, `BLOCKED` items, failures, decisions, restore information, next actions, and a reactivation prompt. Commit, push, publish, deploy, and release remain separate actions requiring explicit authorization.
hoatv2211