mirror of
https://github.com/merlinhu1/codex-game-studio.git
synced 2026-08-25 07:54:34 +02:00
docs: design codex-native agent skill surfaces
This commit is contained in:
MerlinH
@@ -0,0 +1,468 @@
|
||||
---
|
||||
status: draft
|
||||
doc_type: implementation-design
|
||||
last_reviewed: 2026-06-29
|
||||
source_of_truth:
|
||||
- "https://developers.openai.com/codex/skills"
|
||||
- "https://developers.openai.com/codex/subagents"
|
||||
- "https://developers.openai.com/codex/guides/agents-md"
|
||||
- "https://developers.openai.com/codex/rules"
|
||||
- "https://developers.openai.com/codex/hooks"
|
||||
- ../architecture/product-boundary.md
|
||||
- ../../AGENTS.md
|
||||
---
|
||||
|
||||
# Codex-Native Agent and Skill Surfaces Implementation Design
|
||||
|
||||
> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Generate Codex-native project agents and workflow skills that become visible and usable after a plain `git clone`.
|
||||
|
||||
**Architecture:** Codex Game Studio keeps its TypeScript registries as package source of truth, but `init` materializes official Codex surfaces into each generated project: `.codex/agents/*.toml` for custom agents, `.agents/skills/*/SKILL.md` for reusable workflow and standards skills, and `AGENTS.md` for repository instructions. Existing `.codex/prompts/**` and `.codex/workflows/**` remain Codex Game Studio runtime artifacts until a later migration proves they can be removed.
|
||||
|
||||
**Tech Stack:** TypeScript, NodeNext, Codex CLI native project files, generated-surface provenance, Vitest, Truthmark.
|
||||
|
||||
---
|
||||
|
||||
## Online Codex documentation findings
|
||||
|
||||
The previous `.codex/agents/*.md` idea was wrong. Current Codex docs define different native surfaces:
|
||||
|
||||
1. **Custom agents are TOML files.** Project-scoped custom agents live under `.codex/agents/`. Each standalone agent file must define `name`, `description`, and `developer_instructions`. Optional fields include `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`. Source: <https://developers.openai.com/codex/subagents>.
|
||||
2. **Skills live under `.agents/skills`.** For repositories, Codex scans `.agents/skills` from the current working directory up to the repository root. A skill is a directory with `SKILL.md` plus optional `scripts/`, `references/`, `assets/`, and `agents/openai.yaml`. Codex initially sees each skill's name, description, and path, then loads full `SKILL.md` only when the skill is selected. Source: <https://developers.openai.com/codex/skills>.
|
||||
3. **`AGENTS.md` is the instruction surface.** Codex reads global and project `AGENTS.md` or `AGENTS.override.md` files before work. Project discovery starts at the repository root and walks down to the current working directory. Files closer to the working directory appear later and override broader guidance. Source: <https://developers.openai.com/codex/guides/agents-md>.
|
||||
4. **Codex rules are permission rules, not coding standards.** Project-local command permission rules live under `<repo>/.codex/rules/*.rules` and control whether commands can run outside the sandbox. They are experimental. They should not be used for gameplay/UI/test coding standards. Source: <https://developers.openai.com/codex/rules>.
|
||||
5. **Codex hooks are official but trusted lifecycle automation.** Project hooks can live in `<repo>/.codex/hooks.json` or `<repo>/.codex/config.toml`, but non-managed command hooks must be reviewed and trusted before they run. Matching hooks from multiple files all run. Source: <https://developers.openai.com/codex/hooks>.
|
||||
|
||||
## Correct target layout
|
||||
|
||||
A generated project should look like this after `init`:
|
||||
|
||||
```text
|
||||
projects/<slug>/
|
||||
AGENTS.md
|
||||
.codex/
|
||||
agents/
|
||||
producer.toml
|
||||
gameplay-programmer.toml
|
||||
qa-playtester.toml
|
||||
prompts/
|
||||
producer.md
|
||||
gameplay-programmer.md
|
||||
qa-playtester.md
|
||||
workflows/
|
||||
bugfix.md
|
||||
vertical-slice.md
|
||||
studio.json
|
||||
tasks.json
|
||||
context-manifest.json
|
||||
.agents/
|
||||
skills/
|
||||
cgs-bugfix/SKILL.md
|
||||
cgs-vertical-slice/SKILL.md
|
||||
cgs-ui-ux-review/SKILL.md
|
||||
cgs-standards-gameplay/SKILL.md
|
||||
cgs-standards-tests/SKILL.md
|
||||
```
|
||||
|
||||
Canonical meanings:
|
||||
|
||||
- `AGENTS.md`: Codex instruction surface loaded automatically.
|
||||
- `.codex/agents/*.toml`: official project-scoped Codex custom agents.
|
||||
- `.agents/skills/*/SKILL.md`: official repository skill packages.
|
||||
- `.codex/prompts/*.md`: Codex Game Studio runtime prompt artifacts used by `codex-game-studio run <role>` until the CLI is migrated to direct custom-agent orchestration.
|
||||
- `.codex/workflows/*.md`: Codex Game Studio workflow prompt artifacts, not Codex-native skills.
|
||||
- `.codex/rules/*.rules`: reserved for sandbox command permission rules only.
|
||||
- `.codex/hooks.json`: optional future surface for trust-reviewed lifecycle hooks; not part of the first implementation slice.
|
||||
|
||||
## Design decisions
|
||||
|
||||
1. Generate `.codex/agents/*.toml`, not `.codex/agents/*.md`.
|
||||
2. Generate workflow and standards skills under `.agents/skills/**`, not `.codex/skills/**`.
|
||||
3. Use `cgs-` prefixes for generated skill names to avoid collisions with user or global skills. Public docs say duplicate skill names are not merged and can both appear.
|
||||
4. Keep `AGENTS.md` concise. It should point to available agents and skills, not embed all role or workflow bodies.
|
||||
5. Keep `.codex/prompts/**` for current runtime compatibility. Do not pretend it is the Codex custom-agent format.
|
||||
6. Do not use Codex `rules` for coding standards. Encode standards as skills and selected prompt/context guidance. Use `.codex/rules/*.rules` only for permission-policy rules if a later design needs them.
|
||||
7. Do not generate hooks by default. Add `<project>/.codex/hooks.json` only in a later explicit design that handles Codex hook trust and user review.
|
||||
8. Validate all generated surfaces with source hashes and schema versions.
|
||||
|
||||
## Agent generation contract
|
||||
|
||||
Each generated role agent is a TOML file:
|
||||
|
||||
```toml
|
||||
# generated-by: codex-game-studio
|
||||
# surface: custom-agent
|
||||
# source-role-id: gameplay-programmer
|
||||
# source-sha256: <hash>
|
||||
# schema-version: 1
|
||||
|
||||
name = "gameplay_programmer"
|
||||
description = "Game development implementation agent for gameplay-programmer tasks in this project. Use for gameplay feature code, mechanics integration, and implementation verification."
|
||||
model_reasoning_effort = "medium"
|
||||
developer_instructions = """
|
||||
You are the gameplay-programmer role for this Codex Game Studio project.
|
||||
Follow AGENTS.md, .codex/studio.json, and selected task context.
|
||||
Keep changes bounded to the requested task.
|
||||
Report changed files and verification evidence.
|
||||
"""
|
||||
```
|
||||
|
||||
Mapping rules:
|
||||
|
||||
- Filename uses existing role ID: `.codex/agents/gameplay-programmer.toml`.
|
||||
- TOML `name` uses a safe Codex agent identifier derived from the role ID by replacing `-` with `_`.
|
||||
- `description` front-loads trigger words for when Codex should use the agent.
|
||||
- `developer_instructions` reuses the role package contract but is formatted for a custom Codex agent, not for a one-shot prompt.
|
||||
- Only active-engine roles are materialized. A Godot project gets `godot-specialist.toml` and must not get `unity-specialist.toml` or `unreal-specialist.toml`.
|
||||
- Optional `skills.config` is deferred until tested with relative project paths. The first pass relies on repository skill discovery from `.agents/skills`.
|
||||
|
||||
## Skill generation contract
|
||||
|
||||
Each generated workflow or standards skill is a directory with `SKILL.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: cgs-bugfix
|
||||
description: Use for Codex Game Studio bugfix workflow tasks: reproduce, repair, verify, and report a bounded defect.
|
||||
---
|
||||
|
||||
# Codex Game Studio Bugfix Workflow
|
||||
|
||||
Use this skill when the task is a bounded defect repair in this generated game project.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `AGENTS.md`
|
||||
- `.codex/studio.json`
|
||||
- `.codex/workflows/bugfix.md`
|
||||
- task-relevant files named by the user or task record
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Reproduce or characterize the defect.
|
||||
2. Identify the smallest relevant implementation surface.
|
||||
3. Make a bounded fix.
|
||||
4. Run focused verification.
|
||||
5. Report changed files, verification evidence, and remaining risks.
|
||||
```
|
||||
|
||||
Skill categories:
|
||||
|
||||
- Workflow skills: `cgs-bugfix`, `cgs-vertical-slice`, `cgs-ui-ux-review`, `cgs-release-checklist` in the first pass because these already have task recipes.
|
||||
- Standards skills: `cgs-standards-gameplay`, `cgs-standards-tests`, `cgs-standards-prototype`, `cgs-standards-ui` in the first pass.
|
||||
- Later workflow skills can be generated for all built-in workflows after prompt-budget and selector behavior is verified.
|
||||
|
||||
## AGENTS.md contract
|
||||
|
||||
Generated `AGENTS.md` remains the primary project guidance file. It should include:
|
||||
|
||||
- project identity;
|
||||
- engine and mode;
|
||||
- validation commands;
|
||||
- the active role-agent catalog path `.codex/agents/*.toml`;
|
||||
- the generated skill catalog path `.agents/skills/*/SKILL.md`;
|
||||
- the rule that coding standards are skills, not Codex permission rules;
|
||||
- current no-hidden-hooks boundary.
|
||||
|
||||
It should not embed every role prompt, workflow prompt, template, or standards body. Codex docs state `AGENTS.md` discovery has a default combined size cap, so `AGENTS.md` must stay a compact index and contract.
|
||||
|
||||
## Runtime behavior
|
||||
|
||||
### Current runtime path
|
||||
|
||||
`codex-game-studio run <role>` continues to prepare and execute a bounded Codex prompt from existing role packages and `.codex/prompts/<role>.md`.
|
||||
|
||||
Dry-run must show both runtime and native Codex surfaces:
|
||||
|
||||
```text
|
||||
Runtime role prompt: .codex/prompts/gameplay-programmer.md
|
||||
Codex custom agent: .codex/agents/gameplay-programmer.toml
|
||||
Relevant skills:
|
||||
- .agents/skills/cgs-standards-gameplay/SKILL.md
|
||||
- .agents/skills/cgs-bugfix/SKILL.md
|
||||
```
|
||||
|
||||
### Clone-injectable path
|
||||
|
||||
After a plain `git clone`, a user can launch Codex in the generated project and Codex can discover:
|
||||
|
||||
- project instructions from `AGENTS.md`;
|
||||
- custom agents from `.codex/agents/*.toml`;
|
||||
- skills from `.agents/skills/*/SKILL.md`.
|
||||
|
||||
This path does not require `codex-game-studio` to be installed, though validation and regeneration still require the CLI.
|
||||
|
||||
## Validation contract
|
||||
|
||||
Repository validation must check package assets and generators.
|
||||
|
||||
Project validation must check generated project surfaces:
|
||||
|
||||
- `AGENTS.md` exists and has fresh provenance;
|
||||
- active-engine `.codex/agents/*.toml` files exist;
|
||||
- wrong-engine `.codex/agents/*.toml` files are absent;
|
||||
- every generated agent TOML parses and contains `name`, `description`, and `developer_instructions`;
|
||||
- generated agent source hashes match current role package inputs;
|
||||
- `.agents/skills/<name>/SKILL.md` exists for required first-pass workflow and standards skills;
|
||||
- generated skill `SKILL.md` files include `name` and `description` metadata;
|
||||
- generated skill hashes match current workflow or standards source inputs;
|
||||
- `.codex/rules/**` is absent unless a permission-rules feature is explicitly enabled;
|
||||
- `.codex/hooks.json` is absent unless a hooks feature is explicitly enabled.
|
||||
|
||||
Optional Codex CLI smoke validation, when Codex is available:
|
||||
|
||||
```bash
|
||||
codex debug prompt-input "probe generated project skills" > /tmp/cgs-prompt-input.json
|
||||
```
|
||||
|
||||
The probe should confirm generated skill names appear in the skill list. A later test can inspect custom agent availability once the CLI exposes a stable debug shape for custom agents.
|
||||
|
||||
## Implementation tasks
|
||||
|
||||
### Task 1: Add generated custom-agent renderer
|
||||
|
||||
**Objective:** Convert existing role packages into Codex custom agent TOML.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `src/agents.ts`
|
||||
- Modify: `src/generated-surfaces.ts`
|
||||
- Test: `tests/agents-templates.test.ts`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Add `renderProjectCustomAgentToml(role, config, engines)`.
|
||||
2. Serialize TOML with required fields: `name`, `description`, `developer_instructions`.
|
||||
3. Add provenance comments with source role ID, schema version, and source hash.
|
||||
4. Use active-engine filtering through `projectRoleIdsForEngine`.
|
||||
5. Test that a Godot project renders `godot-specialist.toml` and does not render Unity or Unreal agents.
|
||||
|
||||
**Verification:**
|
||||
|
||||
```bash
|
||||
npm test -- tests/agents-templates.test.ts
|
||||
```
|
||||
|
||||
### Task 2: Materialize `.codex/agents/*.toml` during init
|
||||
|
||||
**Objective:** Write project-scoped custom agents into generated projects.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `src/agents.ts`
|
||||
- Modify: `src/projects.ts`
|
||||
- Test: `tests/project-workflow.test.ts`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Update `materializeAgents` to create `.codex/agents`.
|
||||
2. Write one TOML file per active project role.
|
||||
3. Keep existing `.codex/prompts/*.md` writes unchanged.
|
||||
4. Update generated `AGENTS.md` to reference `.codex/agents/*.toml`.
|
||||
5. Test generated file existence and wrong-engine omission.
|
||||
|
||||
**Verification:**
|
||||
|
||||
```bash
|
||||
npm test -- tests/project-workflow.test.ts
|
||||
```
|
||||
|
||||
### Task 3: Add workflow skill renderer
|
||||
|
||||
**Objective:** Convert first-pass built-in workflows into Codex skills.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Create: `src/skills.ts`
|
||||
- Modify: `src/workflows.ts` if helper exports are needed
|
||||
- Test: `tests/skills.test.ts`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Add `GeneratedSkillDefinition` with `name`, `description`, `sourceId`, `body`, and `sourceHash`.
|
||||
2. Render `SKILL.md` with frontmatter `name` and `description`.
|
||||
3. Generate first-pass workflow skills for `bugfix`, `vertical-slice`, `ui-ux-review`, and `release-checklist`.
|
||||
4. Include references to existing `.codex/workflows/<id>.md` files instead of duplicating the full workflow body when a pointer is enough.
|
||||
5. Test frontmatter, trigger descriptions, and provenance.
|
||||
|
||||
**Verification:**
|
||||
|
||||
```bash
|
||||
npm test -- tests/skills.test.ts
|
||||
```
|
||||
|
||||
### Task 4: Add standards skills, not Codex rules
|
||||
|
||||
**Objective:** Encode path/domain coding standards as skills rather than `.codex/rules`.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `src/skills.ts`
|
||||
- Create: `tests/standards-skills.test.ts`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Add standards skill definitions for gameplay, tests, prototype, and UI.
|
||||
2. Put path and domain trigger words in each skill description.
|
||||
3. Keep deterministic checks in validation, not in the subjective `SKILL.md` body.
|
||||
4. Do not create `.codex/rules/*.rules`.
|
||||
5. Test that generated skills have clear `description` triggers and valid frontmatter.
|
||||
|
||||
**Verification:**
|
||||
|
||||
```bash
|
||||
npm test -- tests/standards-skills.test.ts
|
||||
```
|
||||
|
||||
### Task 5: Materialize `.agents/skills/**` during init
|
||||
|
||||
**Objective:** Write generated skills into the project so Codex discovers them after clone.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `src/projects.ts`
|
||||
- Modify: `src/skills.ts`
|
||||
- Test: `tests/project-workflow.test.ts`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Create `.agents/skills/<skill-name>/`.
|
||||
2. Write `SKILL.md` for each first-pass workflow and standards skill.
|
||||
3. Keep skill names stable and `cgs-` prefixed.
|
||||
4. Update `AGENTS.md` to list `.agents/skills` as the workflow and standards skill catalog.
|
||||
5. Test generated skill paths after `init`.
|
||||
|
||||
**Verification:**
|
||||
|
||||
```bash
|
||||
npm test -- tests/project-workflow.test.ts tests/skills.test.ts
|
||||
```
|
||||
|
||||
### Task 6: Validate generated Codex-native surfaces
|
||||
|
||||
**Objective:** Add hard validation for generated agents and skills.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `src/validation.ts`
|
||||
- Test: `tests/validation.test.ts`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Validate `.codex/agents/*.toml` presence for active roles.
|
||||
2. Validate wrong-engine agent absence.
|
||||
3. Validate TOML required fields. If no TOML parser exists, add a narrow parser for generated scalar/string fields or use simple structural validation for generated files only.
|
||||
4. Validate skill directories and `SKILL.md` frontmatter.
|
||||
5. Validate provenance hashes for generated agent and skill files.
|
||||
6. Fail if `.codex/rules/**` or `.codex/hooks.json` appears without an explicit future feature flag.
|
||||
|
||||
**Verification:**
|
||||
|
||||
```bash
|
||||
npm test -- tests/validation.test.ts
|
||||
npm run validate
|
||||
```
|
||||
|
||||
### Task 7: Show native surfaces in dry-run and status output
|
||||
|
||||
**Objective:** Make the clone-injectable surfaces discoverable without reading source code.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `src/runner.ts`
|
||||
- Modify: `src/projects.ts`
|
||||
- Modify: `docs/user-guide.md`
|
||||
- Test: `tests/runner.test.ts`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Add `Codex custom agent: .codex/agents/<role>.toml` to `run --dry-run` output.
|
||||
2. Add selected generated skill paths to dry-run output when a workflow or standards skill is relevant.
|
||||
3. Add `status` output that points to `.codex/agents` and `.agents/skills`.
|
||||
4. Update user docs with official Codex path names.
|
||||
5. Test dry-run and status strings.
|
||||
|
||||
**Verification:**
|
||||
|
||||
```bash
|
||||
npm test -- tests/runner.test.ts tests/project-workflow.test.ts
|
||||
```
|
||||
|
||||
### Task 8: Add optional Codex debug smoke probe
|
||||
|
||||
**Objective:** Verify generated repository skills are visible to Codex when Codex CLI is available.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `src/validation.ts` or add a dev-only test helper
|
||||
- Test: focused integration test, skipped when `codex` is unavailable
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Create a temp project with generated `.agents/skills`.
|
||||
2. Run `codex debug prompt-input "probe generated project skills"` from the generated project root.
|
||||
3. Parse JSON or text for `cgs-bugfix` and one standards skill.
|
||||
4. Skip with an explicit diagnostic if Codex is not installed or authenticated.
|
||||
|
||||
**Verification:**
|
||||
|
||||
```bash
|
||||
npm test -- tests/codex-skill-discovery.test.ts
|
||||
```
|
||||
|
||||
### Task 9: Update truth and architecture docs
|
||||
|
||||
**Objective:** Record the corrected Codex-native surface contract.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `docs/architecture/product-boundary.md` only if product boundary wording needs clarification.
|
||||
- Modify: `docs/truthmark/engineering/projects/project-scaffolding.md`
|
||||
- Modify: `docs/truthmark/engineering/codex/roles-and-workflows.md`
|
||||
- Modify: `docs/truthmark/engineering/contracts/cli-and-validation.md`
|
||||
- Modify: `docs/project-anatomy.md`
|
||||
- Modify: `docs/user-guide.md`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Describe `.codex/agents/*.toml` as native custom-agent files.
|
||||
2. Describe `.agents/skills/**` as native Codex skill packages.
|
||||
3. Describe `.codex/prompts/**` and `.codex/workflows/**` as CGS runtime artifacts.
|
||||
4. State that coding standards are skills or AGENTS.md guidance, not Codex permission rules.
|
||||
5. State that hooks are not generated by default.
|
||||
6. Run Truthmark checks.
|
||||
|
||||
**Verification:**
|
||||
|
||||
```bash
|
||||
truthmark check --json
|
||||
truthmark index --json
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- Generated projects contain `.codex/agents/*.toml` for active roles.
|
||||
- Generated custom-agent TOML files include required Codex fields: `name`, `description`, and `developer_instructions`.
|
||||
- Generated projects contain `.agents/skills/<name>/SKILL.md` for first-pass workflow and standards skills.
|
||||
- Generated skills include `name` and `description` metadata.
|
||||
- Generated `AGENTS.md` points to native agents and skills without embedding all content.
|
||||
- Existing `run <role>` behavior still works through `.codex/prompts/**`.
|
||||
- Validation fails stale generated agent and skill files.
|
||||
- Validation fails wrong-engine generated agents.
|
||||
- No `.codex/agents/*.md` files are generated.
|
||||
- No `.codex/rules/*.rules` files are generated for coding standards.
|
||||
- No `.codex/hooks.json` is generated by default.
|
||||
- Optional Codex debug probe confirms repository skills are discoverable when Codex CLI is available.
|
||||
|
||||
## Deferred work
|
||||
|
||||
- Migrate `run <role>` to use Codex custom agents directly if the CLI exposes a stable noninteractive custom-agent selection contract.
|
||||
- Generate workflow skills for all built-in workflows after prompt-budget behavior is measured.
|
||||
- Add project-local Codex hooks only after a design covers trust review, hook disablement, and deterministic failure behavior.
|
||||
- Add `.codex/rules/*.rules` only for sandbox command permission policy, not coding standards.
|
||||
|
||||
## Rollback plan
|
||||
|
||||
If the generated native surfaces create confusion or Codex discovery changes, keep existing runtime behavior stable by leaving `.codex/prompts/**`, `.codex/workflows/**`, and `AGENTS.md` intact. Disable native surface materialization behind one generator flag, regenerate affected projects, and keep validation focused on the old runtime surfaces until the native surface contract is repaired.
|
||||
@@ -1,520 +1,22 @@
|
||||
---
|
||||
status: draft
|
||||
doc_type: design
|
||||
status: superseded
|
||||
doc_type: design-index
|
||||
last_reviewed: 2026-06-29
|
||||
source_of_truth:
|
||||
- ../architecture/product-boundary.md
|
||||
- ../../AGENTS.md
|
||||
superseded_by:
|
||||
- 2026-06-29-codex-native-agent-skill-surfaces.md
|
||||
---
|
||||
|
||||
# Scoped Standards Rule Packs Design
|
||||
|
||||
## Goal
|
||||
This draft is superseded by [Codex-Native Agent and Skill Surfaces Implementation Design](2026-06-29-codex-native-agent-skill-surfaces.md).
|
||||
|
||||
Add Codex-native, path-scoped standards guidance to Codex Game Studio without importing Claude Code hooks, `.claude/rules`, or hidden lifecycle automation.
|
||||
Reason: follow-up review of the online Codex documentation showed this draft used the wrong native structure for generated agents and rules.
|
||||
|
||||
The design keeps the current product boundary: explicit commands, reviewable project files, bounded selected context, and validation that runs through the CLI or test suite.
|
||||
Corrected decisions now live in the replacement design:
|
||||
|
||||
## Background
|
||||
|
||||
Claude Code Game Studios has useful path-scoped rules for gameplay code, UI code, tests, prototypes, design docs, data files, networking, AI, and engine hot paths. Those rules improve day-to-day agent guidance because a role editing `src/gameplay/**` sees gameplay standards instead of every standard in the repository.
|
||||
|
||||
Codex Game Studio should adapt that idea, not the Claude implementation. The CCGS hook and rule runtime depends on `.claude/settings.json` lifecycle events and host-specific automatic behavior. Codex Game Studio's architecture requires visible local files, deterministic CLI output, dry-run inspection, explicit validation, and selected context rather than hidden automation.
|
||||
|
||||
## Decisions
|
||||
|
||||
1. Rule packs are a Codex Game Studio surface, not a Claude compatibility surface.
|
||||
2. Built-in package rule packs are the canonical defaults.
|
||||
3. Generated project rule packs may be materialized under `.codex/studio/rules/**` when the project needs local reviewable copies or overrides.
|
||||
4. Generated project role agents should be visible as clone-injectable `.codex/agents/**` files in addition to the runtime `.codex/prompts/**` prompts.
|
||||
5. Workflow skills should be visible as clone-injectable `.agents/skills/**` packages when they are meant to behave like reusable agent workflows.
|
||||
6. Rule selection is explicit and deterministic. It is based on declared task context, not ambient editor hooks.
|
||||
7. Mechanically checkable rules become validation checks. Subjective guidance remains selected prompt context.
|
||||
8. No `.claude/hooks`, `.claude/rules`, Git hooks, background daemons, or hidden lifecycle triggers are introduced.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Do not add Claude Code hook compatibility.
|
||||
- Do not add a hidden session-start, pre-tool, post-write, compact, or stop hook runtime.
|
||||
- Do not load every rule pack into every prompt.
|
||||
- Do not make strict studio process mandatory for fast prototypes.
|
||||
- Do not turn Truthmark route files into user-facing game-studio product features.
|
||||
- Do not add CI, PR, release, or merge enforcement behavior.
|
||||
|
||||
## Product surface
|
||||
|
||||
### Built-in package registry
|
||||
|
||||
Codex Game Studio ships a rule-pack registry with package assets. The registry is read by CLI runtime code, not by a host-specific agent hook.
|
||||
|
||||
Proposed package asset layout:
|
||||
|
||||
```text
|
||||
rules/
|
||||
registry.json
|
||||
gameplay-code.md
|
||||
engine-core.md
|
||||
ui-code.md
|
||||
network-code.md
|
||||
ai-code.md
|
||||
test-standards.md
|
||||
prototype-code.md
|
||||
design-docs.md
|
||||
data-files.md
|
||||
shader-code.md
|
||||
```
|
||||
|
||||
`rules/registry.json` declares metadata for each pack:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"packs": [
|
||||
{
|
||||
"id": "gameplay-code",
|
||||
"title": "Gameplay Code Standards",
|
||||
"appliesTo": {
|
||||
"paths": ["source/**/gameplay/**", "src/gameplay/**"],
|
||||
"roles": ["gameplay-programmer", "senior-game-designer"],
|
||||
"stages": ["prototype", "development"],
|
||||
"strictness": ["guided-studio", "strict-studio"]
|
||||
},
|
||||
"checks": ["data-driven-gameplay-values"],
|
||||
"guidancePath": "rules/gameplay-code.md"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The registry is a package asset and must be included in package shipping checks. Installed-bin execution from a non-repository working directory must still resolve built-in rule packs from the package root.
|
||||
|
||||
### Project-local copies and overrides
|
||||
|
||||
Generated projects may materialize local rule packs when reviewability or customization is needed:
|
||||
|
||||
```text
|
||||
projects/<slug>/.codex/studio/rules/
|
||||
registry.json
|
||||
gameplay-code.md
|
||||
test-standards.md
|
||||
```
|
||||
|
||||
Local copies are optional. A project without local copies uses built-in package defaults. A project with local copies can override or disable selected built-in packs through a registry entry, but the override is explicit and validated.
|
||||
|
||||
Generated local rule packs must include provenance metadata so validation can detect stale or malformed generated surfaces:
|
||||
|
||||
```markdown
|
||||
<!-- generated-by: codex-game-studio -->
|
||||
<!-- rule-pack-id: gameplay-code -->
|
||||
<!-- source-registry-version: 1 -->
|
||||
<!-- source-sha256: <hash> -->
|
||||
```
|
||||
|
||||
### Clone-injectable agents and skills
|
||||
|
||||
Codex Game Studio should make generated projects self-describing after a plain `git clone`. The generated project should carry the role and workflow surfaces that a host can inject without requiring the original package checkout.
|
||||
|
||||
Proposed generated project layout:
|
||||
|
||||
```text
|
||||
projects/<slug>/
|
||||
AGENTS.md
|
||||
.codex/
|
||||
agents/
|
||||
producer.md
|
||||
gameplay-programmer.md
|
||||
qa-playtester.md
|
||||
prompts/
|
||||
producer.md
|
||||
gameplay-programmer.md
|
||||
qa-playtester.md
|
||||
workflows/
|
||||
bugfix.md
|
||||
vertical-slice.md
|
||||
studio.json
|
||||
.agents/
|
||||
skills/
|
||||
bugfix/SKILL.md
|
||||
vertical-slice/SKILL.md
|
||||
ui-ux-review/SKILL.md
|
||||
```
|
||||
|
||||
`AGENTS.md` remains the primary Codex instruction surface. `.codex/agents/**` is the browseable, clone-injectable agent catalog. `.codex/prompts/**` remains the runtime prompt surface used by `run <role>` and selected context contracts. The first implementation may make `.codex/agents/<role>.md` and `.codex/prompts/<role>.md` identical files or one may be a generated wrapper pointing to the other, but validation must keep both fresh if both are materialized.
|
||||
|
||||
`.agents/skills/**` is for reusable workflow packages, not for hidden hooks. A workflow skill package contains a `SKILL.md` with the workflow goal, required role, selected templates, validation expectations, and handoff format. It may include support files only when those files reduce prompt bloat or make the workflow auditable after clone.
|
||||
|
||||
Generated agent and skill files must include provenance metadata:
|
||||
|
||||
```markdown
|
||||
<!-- generated-by: codex-game-studio -->
|
||||
<!-- surface: role-agent | workflow-skill -->
|
||||
<!-- source-id: gameplay-programmer -->
|
||||
<!-- source-sha256: <hash> -->
|
||||
```
|
||||
|
||||
This gives the CCGS-style "clone the repo and see the studio" experience while preserving Codex Game Studio's explicit runtime. A host may inject `.codex/agents/**` or `.agents/skills/**` directly, but Codex Game Studio still executes through explicit CLI commands and validates generated surface freshness.
|
||||
|
||||
## Selection inputs
|
||||
|
||||
Rule selection uses the same explicit context model as prompt and task preparation. The selector receives a structured input instead of inspecting an editor event.
|
||||
|
||||
Required input fields:
|
||||
|
||||
```ts
|
||||
type RuleSelectionInput = {
|
||||
projectRoot: string;
|
||||
roleId: string;
|
||||
engine?: "godot" | "unity" | "unreal";
|
||||
projectStage?: "design" | "prototype" | "development";
|
||||
studioStrictness?: "fast-prototype" | "guided-studio" | "strict-studio";
|
||||
commandSurface: "run" | "task-dry-run" | "task-orchestrate" | "validate";
|
||||
declaredWriteFiles: string[];
|
||||
declaredReadFiles?: string[];
|
||||
workflowId?: string;
|
||||
};
|
||||
```
|
||||
|
||||
Selection factors:
|
||||
|
||||
- path patterns from `declaredWriteFiles` first;
|
||||
- role ID;
|
||||
- engine;
|
||||
- project stage;
|
||||
- studio strictness;
|
||||
- workflow recipe ID;
|
||||
- explicit project-local enables/disables.
|
||||
|
||||
`declaredWriteFiles` is the strongest signal because standards should match the files a task is allowed to change. Read-only context can add advisory packs, but it must not cause write-scope-only checks to fail.
|
||||
|
||||
## Selection algorithm
|
||||
|
||||
1. Load built-in registry from package assets.
|
||||
2. Load project-local registry if present.
|
||||
3. Validate local registry schema, IDs, provenance, and path containment.
|
||||
4. Build candidate packs from built-in defaults plus project-local overrides.
|
||||
5. Score each pack:
|
||||
- path match against declared write files;
|
||||
- role match;
|
||||
- engine match;
|
||||
- stage match;
|
||||
- strictness match;
|
||||
- workflow match.
|
||||
6. Select packs above the configured threshold.
|
||||
7. Apply hard caps for prompt budget:
|
||||
- maximum selected packs;
|
||||
- maximum total guidance characters;
|
||||
- deterministic priority tie-breaks.
|
||||
8. Return both selected and omitted packs with reasons.
|
||||
|
||||
The selector must never fall back to loading all packs when no match is found. If no pack matches, the result is an empty selected set plus diagnostics explaining why.
|
||||
|
||||
## Output surfaces
|
||||
|
||||
### `run --dry-run`
|
||||
|
||||
Dry-run output includes a `Selected standards` section:
|
||||
|
||||
```text
|
||||
Selected standards:
|
||||
- gameplay-code: matched writeFiles source/gameplay/combat.ts and role gameplay-programmer
|
||||
- test-standards: matched writeFiles tests/combat.test.ts
|
||||
|
||||
Omitted standards:
|
||||
- ui-code: no declared write file matched src/ui/**
|
||||
- prototype-code: project stage is development
|
||||
```
|
||||
|
||||
Dry-run remains non-mutating.
|
||||
|
||||
### Prompt packets
|
||||
|
||||
Prepared Codex prompts include selected subjective guidance as a bounded section:
|
||||
|
||||
```markdown
|
||||
## Selected Standards
|
||||
|
||||
### gameplay-code
|
||||
|
||||
<selected concise guidance>
|
||||
|
||||
### test-standards
|
||||
|
||||
<selected concise guidance>
|
||||
```
|
||||
|
||||
The prompt metadata records selected pack IDs, source type, source hash, and omitted-pack diagnostics. That metadata is part of reviewable run evidence under `.codex/**` when a run writes prompt caches or run metadata.
|
||||
|
||||
### Task orchestration diagnostics
|
||||
|
||||
`task orchestrate --dry-run` reports selected standards per task. It must show conflicts before execution, such as a task with no declared write files attempting a mutating role that normally requires path-scoped standards.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Task combat-implementation:
|
||||
selected standards: gameplay-code, test-standards
|
||||
omitted standards: ui-code, network-code
|
||||
diagnostics: all selected packs fit within 6,000 character budget
|
||||
```
|
||||
|
||||
### Validation advisory output
|
||||
|
||||
`validate` checks registry integrity and mechanically checkable standards. It also prints advisory diagnostics for subjective packs when selection data is available.
|
||||
|
||||
Validation must distinguish severity:
|
||||
|
||||
- `error`: malformed registry, stale generated rule pack, path traversal, package asset missing, mechanical rule failed;
|
||||
- `warning`: subjective rule matched but only advisory, local override disables a recommended pack, no standards matched a declared write set;
|
||||
- `info`: selected/omitted summary for inspection.
|
||||
|
||||
## Mechanical checks vs subjective guidance
|
||||
|
||||
Rule packs may contain two kinds of rules.
|
||||
|
||||
### Mechanical checks
|
||||
|
||||
Mechanical checks are deterministic and belong in validation. Examples:
|
||||
|
||||
- rule registry JSON schema is valid;
|
||||
- local rule pack paths stay under `.codex/studio/rules/**`;
|
||||
- generated local rule pack provenance hashes match the current registry;
|
||||
- TypeScript relative imports use emitted `.js` specifiers;
|
||||
- package assets include `rules/**` and installed-bin execution can load them;
|
||||
- JSON data files are syntactically valid;
|
||||
- generated project `AGENTS.md` provenance remains fresh;
|
||||
- no forbidden future-only CLI surface appears in help output.
|
||||
|
||||
Mechanical checks can fail validation.
|
||||
|
||||
### Subjective guidance
|
||||
|
||||
Subjective guidance belongs in selected prompt context and dry-run diagnostics. Examples:
|
||||
|
||||
- gameplay values should be data-driven unless a prototype task explicitly allows inline tuning;
|
||||
- UI code should not own authoritative game state;
|
||||
- prototype code may prefer speed over final architecture but must document the hypothesis;
|
||||
- design docs should include player fantasy, rules, edge cases, and acceptance criteria;
|
||||
- tests should be behavior-oriented rather than source-inspection assertions.
|
||||
|
||||
Subjective guidance must not be hidden enforcement. It can appear in prompts, dry-runs, and warnings, but it does not block unless a separate deterministic validation check exists.
|
||||
|
||||
## Strictness and stage behavior
|
||||
|
||||
Project stage and studio strictness stay separate.
|
||||
|
||||
- `design` stage selects design-doc, planning, and scope standards by default.
|
||||
- `prototype` stage selects prototype-friendly standards and may downgrade some production rules to advisory warnings.
|
||||
- `development` stage selects stricter implementation and test standards.
|
||||
- `fast-prototype` strictness keeps rule selection minimal and advisory.
|
||||
- `guided-studio` strictness selects relevant guidance and warns on missing standards.
|
||||
- `strict-studio` strictness enables more mechanical checks where deterministic checks exist.
|
||||
|
||||
This preserves lightweight prototype use while making deeper studio process available when explicitly chosen.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
### Task 1: Add rule-pack data model and registry loader
|
||||
|
||||
Files:
|
||||
|
||||
- Create: `src/rule-packs.ts`
|
||||
- Create: `tests/rule-packs.test.ts`
|
||||
- Create: `rules/registry.json`
|
||||
- Create: initial `rules/*.md` pack files
|
||||
|
||||
Behavior:
|
||||
|
||||
- load built-in package registry;
|
||||
- validate schema;
|
||||
- resolve guidance paths from the package root;
|
||||
- reject absolute paths and traversal;
|
||||
- return deterministic pack metadata.
|
||||
|
||||
Verification:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm test -- tests/rule-packs.test.ts
|
||||
```
|
||||
|
||||
### Task 2: Add rule selection
|
||||
|
||||
Files:
|
||||
|
||||
- Modify: `src/rule-packs.ts`
|
||||
- Create: `tests/rule-selection.test.ts`
|
||||
|
||||
Behavior:
|
||||
|
||||
- select packs from path, role, engine, stage, strictness, workflow, and write files;
|
||||
- never load all packs as fallback;
|
||||
- return selected and omitted diagnostics;
|
||||
- enforce prompt budget caps deterministically.
|
||||
|
||||
Verification:
|
||||
|
||||
```bash
|
||||
npm test -- tests/rule-selection.test.ts
|
||||
```
|
||||
|
||||
### Task 3: Materialize clone-injectable agent and skill surfaces
|
||||
|
||||
Files:
|
||||
|
||||
- Modify: `src/agents.ts`
|
||||
- Modify: `src/generated-surfaces.ts`
|
||||
- Modify: `src/projects.ts`
|
||||
- Modify: `src/workflows.ts`
|
||||
- Modify: `tests/project-workflow.test.ts`
|
||||
- Modify: `tests/agents-templates.test.ts`
|
||||
- Modify: `tests/validation.test.ts`
|
||||
|
||||
Behavior:
|
||||
|
||||
- materialize active-engine role agents under `.codex/agents/**` during `init`;
|
||||
- keep runtime role prompts under `.codex/prompts/**` until a later migration proves one surface can replace the other;
|
||||
- materialize workflow skill packages under `.agents/skills/<workflow-id>/SKILL.md` for reusable built-in workflows;
|
||||
- include provenance metadata for every generated agent and skill file;
|
||||
- validate freshness and reject wrong-engine generated agents just like wrong-engine prompts.
|
||||
|
||||
Verification:
|
||||
|
||||
```bash
|
||||
npm test -- tests/project-workflow.test.ts tests/agents-templates.test.ts tests/validation.test.ts
|
||||
```
|
||||
|
||||
### Task 4: Wire selection into run preparation
|
||||
|
||||
Files:
|
||||
|
||||
- Modify: `src/runner.ts`
|
||||
- Modify: `src/codex-prompts.ts`
|
||||
- Modify: `tests/runner.test.ts`
|
||||
- Modify: `tests/codex-prompts.test.ts`
|
||||
|
||||
Behavior:
|
||||
|
||||
- include selected standards in `--dry-run` output;
|
||||
- include selected standards in prompt packets;
|
||||
- record selected and omitted pack metadata in run metadata;
|
||||
- make selected `.codex/agents/**` and `.agents/skills/**` paths visible in dry-run diagnostics when those files are used as context;
|
||||
- preserve non-mutating behavior for `--dry-run` and `--print-prompt`.
|
||||
|
||||
Verification:
|
||||
|
||||
```bash
|
||||
npm test -- tests/runner.test.ts tests/codex-prompts.test.ts
|
||||
```
|
||||
|
||||
### Task 5: Wire selection into task orchestration diagnostics
|
||||
|
||||
Files:
|
||||
|
||||
- Modify: `src/orchestrator.ts`
|
||||
- Modify: `src/workflow-recipes.ts` if recipes need default write-scope hints
|
||||
- Modify: `tests/orchestrator.test.ts`
|
||||
- Modify: `tests/workflow-recipes.test.ts`
|
||||
|
||||
Behavior:
|
||||
|
||||
- show selected standards per task during `task orchestrate --dry-run`;
|
||||
- warn when mutating tasks have no declared write files;
|
||||
- keep orchestration bounded and foreground-only;
|
||||
- do not introduce background hooks or hidden scheduler behavior.
|
||||
|
||||
Verification:
|
||||
|
||||
```bash
|
||||
npm test -- tests/orchestrator.test.ts tests/workflow-recipes.test.ts
|
||||
```
|
||||
|
||||
### Task 6: Add validation checks and package shipping coverage
|
||||
|
||||
Files:
|
||||
|
||||
- Modify: `src/validation.ts`
|
||||
- Modify: `tests/validation.test.ts`
|
||||
- Modify: `package.json` if `files` needs `rules/**`
|
||||
- Modify: package smoke tests if present, or add a focused installed-bin asset-loading test
|
||||
|
||||
Behavior:
|
||||
|
||||
- validate built-in registry shape;
|
||||
- validate project-local rule-pack overrides;
|
||||
- validate generated local provenance when local packs are materialized;
|
||||
- validate generated `.codex/agents/**` and `.agents/skills/**` provenance and freshness;
|
||||
- fail on missing package assets;
|
||||
- keep subjective guidance as advisory output only.
|
||||
|
||||
Verification:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm test
|
||||
npm run validate
|
||||
```
|
||||
|
||||
### Task 7: Update truth and user docs
|
||||
|
||||
Files:
|
||||
|
||||
- Modify: `docs/architecture/product-boundary.md` only if the product boundary changes; this design should not require a boundary change.
|
||||
- Modify: `docs/truthmark/engineering/codex/roles-and-workflows.md`
|
||||
- Modify: `docs/truthmark/engineering/codex/runtime-and-tasks.md`
|
||||
- Modify: `docs/truthmark/engineering/contracts/cli-and-validation.md`
|
||||
- Modify: `docs/user-guide.md` if the feature becomes user-visible.
|
||||
|
||||
Behavior:
|
||||
|
||||
- document rule-pack selection as explicit selected context;
|
||||
- document clone-injectable `.codex/agents/**` and `.agents/skills/**` surfaces;
|
||||
- document validation severity split;
|
||||
- document project-local override behavior;
|
||||
- avoid describing Truthmark workflow mechanics as a product feature.
|
||||
|
||||
Verification:
|
||||
|
||||
```bash
|
||||
truthmark check --json
|
||||
truthmark index --json
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- Built-in rule packs are package assets and load from installed-bin execution.
|
||||
- A project can run without local rule packs and still receive built-in selected standards.
|
||||
- A project can materialize local `.codex/studio/rules/**` rule packs with provenance.
|
||||
- A generated project materializes clone-injectable `.codex/agents/**` files for active-engine roles.
|
||||
- A generated project materializes clone-injectable `.agents/skills/**` packages for reusable workflow skills.
|
||||
- Validation detects stale or wrong-engine generated agents and stale generated workflow skills.
|
||||
- Selection can use path, role, engine, project stage, studio strictness, workflow, and declared write files.
|
||||
- `run --dry-run` shows selected and omitted standards without writing state.
|
||||
- Prompt packets include only selected guidance within budget caps.
|
||||
- Task orchestration dry-runs show standards per task.
|
||||
- Validation fails deterministic mechanical issues and only warns for subjective guidance.
|
||||
- No `.claude/**`, Git hooks, background hooks, or hidden lifecycle automation are added.
|
||||
- Tests prove no unmatched task falls back to loading every rule pack.
|
||||
|
||||
## Open questions
|
||||
|
||||
1. Should local rule packs be materialized by default during `init`, or only when a project enables customization?
|
||||
2. Should `.codex/agents/**` duplicate `.codex/prompts/**` in the first pass, or should one surface become a lightweight wrapper pointing to the canonical body?
|
||||
3. Which workflows deserve `.agents/skills/**` packages in the first pass: all built-in workflows, only task-recipe workflows, or only high-value reusable workflows?
|
||||
4. Should built-in rules be engine-neutral first, with engine-specific overlays later, or should the first pass include Godot/Unity/Unreal overlays?
|
||||
5. Should `strict-studio` require declared write files for every mutating task, or should it allow a conservative project-wide write scope with a warning?
|
||||
|
||||
## Recommended first implementation slice
|
||||
|
||||
Build the visible generated-surface and read-only selection path first:
|
||||
|
||||
1. package registry;
|
||||
2. `.codex/agents/**` materialization for active-engine roles;
|
||||
3. `.agents/skills/**` materialization for a small workflow-skill set;
|
||||
4. generated-surface provenance validation;
|
||||
5. selector;
|
||||
6. `run --dry-run` selected/omitted diagnostics;
|
||||
7. prompt inclusion;
|
||||
8. registry validation.
|
||||
|
||||
Defer local rule-pack materialization, full workflow-skill coverage, and strict-studio hard failures until the built-in selector and generated agent/skill surfaces are proven with tests.
|
||||
- Codex custom agents are `.codex/agents/*.toml`, not `.codex/agents/*.md`.
|
||||
- Codex repository skills are `.agents/skills/<name>/SKILL.md`.
|
||||
- `AGENTS.md` is the automatic project instruction surface.
|
||||
- Codex `.codex/rules/*.rules` files are sandbox command permission rules, not coding standards.
|
||||
- Coding standards should be generated as skills and selected prompt guidance, not Codex permission rules.
|
||||
- Project hooks are official Codex surfaces but require trust review; they are not part of the first implementation slice.
|
||||
|
||||
Reference in New Issue
Block a user