diff --git a/README.md b/README.md index bce815b..010acef 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ skills expose the runtime workflows directly. Do not use a global and `design/gdd/game-pillars.md`. - Runtime agents: `creative-director`, `art-director`, `technical-director`, `producer` - Runtime source: `runtime/agents/` +- Project guide template: `project-template/AGENTS.md` - References: `references/studio-docs/director-gates.md`, `references/studio-docs/templates/game-concept.md`, `references/studio-docs/templates/game-pillars.md` - Standards: `standards/design-docs.md` - Marketplace: `.agents/plugins/marketplace.json` @@ -38,15 +39,20 @@ directly: python3 scripts/install_codex_runtime.py /path/to/game-project ``` -The installer writes custom agents to: +The installer writes custom agents and the project guide to: ```text /path/to/game-project/.codex/agents/ +/path/to/game-project/AGENTS.md ``` Each runtime agent is a standalone TOML file with `name`, `description`, and `developer_instructions`, matching Codex custom-agent conventions. +If the target project already has a different `AGENTS.md`, the installer reports +a conflict and leaves it unchanged. Use `--force-agents-md` only when you intend +to overwrite it. + ## Packaging Hygiene Only plugin source files should be packaged. `.git/`, `.env`, `.DS_Store`, local diff --git a/project-template/AGENTS.md b/project-template/AGENTS.md new file mode 100644 index 0000000..b370a85 --- /dev/null +++ b/project-template/AGENTS.md @@ -0,0 +1,119 @@ +# Codex Game Studios Project Guide + +This file is the root project guide for Codex. It is installed at the game +project root so Codex and bundled subagents have shared context before running +game-production workflows. + +## Technology Stack + +- **Engine**: [CHOOSE: Godot 4 / Unity / Unreal Engine 5] +- **Language**: [CHOOSE: GDScript / C# / C++ / Blueprint] +- **Version Control**: Git with trunk-based development +- **Build System**: [SPECIFY after choosing engine] +- **Asset Pipeline**: [SPECIFY after choosing engine] + +> Engine-specialist agents will be added later. For now, use the four bundled +> director agents only when a workflow explicitly asks for them. + +## Runtime Agents + +Bundled custom agents are installed into: + +```text +.codex/agents/ +``` + +Current bundled agents: + +- `creative-director` +- `art-director` +- `technical-director` +- `producer` + +These agents are primarily used by director / lead review gates. They are not a +replacement for user decisions. + +## Review Intensity + +Review intensity is configured by: + +```text +production/review-mode.txt +``` + +Allowed values: + +- `full` — all key director / lead review gates call their custom agents. +- `lean` — only PHASE-GATE review gates such as `/gate-check` call directors; + ordinary per-skill review gates are skipped. +- `solo` — all director review gates are skipped. + +Default when the file is missing: `lean`. + +This is not a global switch for all custom-agent usage. Future team workflows +may still call specialist subagents as part of their core work. + +## Collaboration Protocol + +User-driven collaboration, not autonomous execution. Every workflow follows: + +```text +Question -> Options -> Decision -> Draft -> Approval +``` + +- Ask clarifying questions when the user's intent or constraints are unclear. +- Present options with trade-offs before major creative or technical decisions. +- The user makes final strategic decisions. +- Show drafts or summaries before writing important project files. +- Do not commit changes unless the user asks. +- Do not overwrite existing project guidance or design documents without + explicit approval. + +## Current Workflow Surface + +The current plugin build exposes only the migrated `/brainstorm` workflow. + +`/brainstorm` produces: + +```text +design/gdd/game-concept.md +design/gdd/game-pillars.md +``` + +In default `lean` mode, `/brainstorm` writes the initial pillar document itself. +In `full` mode, the `creative-director` review gate participates in creating or +updating the pillar document. + +## Design Documents + +Use these project paths: + +```text +design/gdd/ +design/ux/ +docs/architecture/ +production/ +``` + +`design/gdd/game-concept.md`, `design/gdd/game-pillars.md`, and +`design/gdd/systems-index.md` are top-level design documents. They are not +per-system GDDs. + +Per-system GDDs under `design/gdd/` should include: + +1. Overview +2. Player Fantasy +3. Detailed Rules +4. Formulas +5. Edge Cases +6. Dependencies +7. Tuning Knobs +8. Acceptance Criteria + +## Context Management + +- If a workflow becomes long, persist decisions into the relevant project file + instead of relying only on chat context. +- When resuming, read existing project documents before restarting a workflow. +- Preserve user-authored content and update only the sections needed for the + active task. diff --git a/references/studio-docs/director-gates.md b/references/studio-docs/director-gates.md index f1635da..52fb4f5 100644 --- a/references/studio-docs/director-gates.md +++ b/references/studio-docs/director-gates.md @@ -20,9 +20,12 @@ Spawn `creative-director` via Codex custom-agent delegation using gate ``` The matching custom agent must already be installed in the target project at -`.codex/agents/.toml`. The plugin source copies for those agents live -in `runtime/agents/`; run `python3 scripts/install_codex_runtime.py ` -from the plugin root if the target project is missing them. Pass the context +`.codex/agents/.toml`. The target project should also have a root +`AGENTS.md` installed from `project-template/AGENTS.md`; this is the shared +project guide used by Codex and bundled custom agents. The plugin source copies +for agents live in `runtime/agents/`; run +`python3 scripts/install_codex_runtime.py ` from the plugin root +if the target project is missing the agents or root guide. Pass the context listed under that gate's **Context to pass** field, then handle the verdict using the **Verdict handling** rules below. diff --git a/scripts/install_codex_runtime.py b/scripts/install_codex_runtime.py index e27d203..8a2ed48 100755 --- a/scripts/install_codex_runtime.py +++ b/scripts/install_codex_runtime.py @@ -4,9 +4,11 @@ Current runtime scope: - Copy bundled Codex custom agents from this plugin's `runtime/agents/` directory into the target project's `.codex/agents/` directory. +- Copy the Codex project guide template from `project-template/AGENTS.md` + into the target project's root `AGENTS.md`. -This installer intentionally does not install hooks, rules, MCP servers, apps, -or AGENTS.md templates yet. +This installer intentionally does not install hooks, rules, MCP servers, or apps +yet. """ from __future__ import annotations @@ -31,6 +33,7 @@ def find_plugin_root(start: Path) -> Path: PLUGIN_ROOT = find_plugin_root(Path(__file__).resolve()) SOURCE_AGENTS_DIR = PLUGIN_ROOT / "runtime" / "agents" +PROJECT_AGENTS_TEMPLATE = PLUGIN_ROOT / "project-template" / "AGENTS.md" @dataclass(frozen=True) @@ -96,6 +99,26 @@ def install_agents(target: Path, *, force: bool, dry_run: bool) -> InstallResult return InstallResult(installed=installed, unchanged=unchanged, conflicts=conflicts) +def install_project_guide( + target: Path, *, force: bool, dry_run: bool +) -> InstallResult: + if not PROJECT_AGENTS_TEMPLATE.is_file(): + raise FileNotFoundError(f"Missing project guide template: {PROJECT_AGENTS_TEMPLATE}") + + destination = target / "AGENTS.md" + + if destination.exists(): + if filecmp.cmp(PROJECT_AGENTS_TEMPLATE, destination, shallow=False): + return InstallResult(installed=[], unchanged=[destination], conflicts=[]) + if not force: + return InstallResult(installed=[], unchanged=[], conflicts=[destination]) + + if not dry_run: + shutil.copy2(PROJECT_AGENTS_TEMPLATE, destination) + + return InstallResult(installed=[destination], unchanged=[], conflicts=[]) + + def print_path_list(label: str, paths: list[Path], target: Path) -> None: if not paths: return @@ -117,6 +140,11 @@ def parse_args() -> argparse.Namespace: action="store_true", help="Overwrite existing agent files when their content differs.", ) + parser.add_argument( + "--force-agents-md", + action="store_true", + help="Overwrite an existing target AGENTS.md when its content differs.", + ) parser.add_argument( "--dry-run", action="store_true", @@ -132,25 +160,44 @@ def main() -> int: print("Codex Game Studios runtime installer") print(f"Plugin root: {PLUGIN_ROOT}") print(f"Target project: {target}") - print("Runtime scope: custom agents only") + print("Runtime scope: custom agents plus project AGENTS.md") try: - result = install_agents(target, force=args.force, dry_run=args.dry_run) + agent_result = install_agents(target, force=args.force, dry_run=True) + guide_result = install_project_guide( + target, force=args.force_agents_md, dry_run=True + ) except FileNotFoundError as error: print(f"ERROR: {error}", file=sys.stderr) return 1 - print_path_list("Installed" if not args.dry_run else "Would install", result.installed, target) - print_path_list("Unchanged", result.unchanged, target) - print_path_list("Conflicts", result.conflicts, target) + print_path_list("Agent conflicts", agent_result.conflicts, target) + print_path_list("Project guide conflicts", guide_result.conflicts, target) - if result.conflicts: - print( - "ERROR: Existing agent files differ. Re-run with --force to overwrite them.", - file=sys.stderr, - ) + if agent_result.conflicts or guide_result.conflicts: + if agent_result.conflicts: + print( + "ERROR: Existing agent files differ. Re-run with --force to overwrite them.", + file=sys.stderr, + ) + if guide_result.conflicts: + print( + "ERROR: Target AGENTS.md differs. Re-run with --force-agents-md to overwrite it.", + file=sys.stderr, + ) return 2 + if not args.dry_run: + agent_result = install_agents(target, force=args.force, dry_run=False) + guide_result = install_project_guide( + target, force=args.force_agents_md, dry_run=False + ) + + print_path_list("Installed agents" if not args.dry_run else "Would install agents", agent_result.installed, target) + print_path_list("Unchanged agents", agent_result.unchanged, target) + print_path_list("Installed project guide" if not args.dry_run else "Would install project guide", guide_result.installed, target) + print_path_list("Unchanged project guide", guide_result.unchanged, target) + print("Done.") return 0 diff --git a/scripts/validate_plugin.py b/scripts/validate_plugin.py index 212b57c..8662fc2 100755 --- a/scripts/validate_plugin.py +++ b/scripts/validate_plugin.py @@ -101,6 +101,41 @@ def assert_runtime_agents() -> None: fail(f"Missing runtime agents: {', '.join(missing)}") +def assert_project_template() -> None: + template_path = ROOT / "project-template" / "AGENTS.md" + if not template_path.is_file(): + fail("Missing project-template/AGENTS.md") + + text = template_path.read_text(encoding="utf-8") + required_fragments = [ + "Codex Game Studios Project Guide", + "production/review-mode.txt", + ".codex/agents/", + "design/gdd/game-concept.md", + "design/gdd/game-pillars.md", + ] + for fragment in required_fragments: + if fragment not in text: + fail(f"project-template/AGENTS.md missing required content: {fragment}") + + +def assert_runtime_installer() -> None: + installer_path = ROOT / "scripts" / "install_codex_runtime.py" + if not installer_path.is_file(): + fail("Missing scripts/install_codex_runtime.py") + + text = installer_path.read_text(encoding="utf-8") + required_fragments = [ + "PROJECT_AGENTS_TEMPLATE", + "project-template", + "AGENTS.md", + "--force-agents-md", + ] + for fragment in required_fragments: + if fragment not in text: + fail(f"install_codex_runtime.py missing required content: {fragment}") + + def assert_package_hygiene() -> None: try: tracked = run_git(["ls-files"]) @@ -129,6 +164,8 @@ def main() -> int: for skill_name in sorted(EXPECTED_SKILLS): assert_skill(skill_name) assert_runtime_agents() + assert_project_template() + assert_runtime_installer() assert_package_hygiene() print("Codex Game Studios plugin validation passed.") return 0 diff --git a/skills/brainstorm/DETAILS.md b/skills/brainstorm/DETAILS.md index b719e73..bce5392 100644 --- a/skills/brainstorm/DETAILS.md +++ b/skills/brainstorm/DETAILS.md @@ -17,13 +17,14 @@ When this skill is invoked: AD-CONCEPT-VISUAL, TD-FEASIBILITY, and PR-SCOPE; `full` runs them; `solo` skips all director review gates. - Director agent source files live in `../../runtime/agents/`. Before running + Director agent source files live in `../../runtime/agents/`, and the project + guidance template lives at `../../project-template/AGENTS.md`. Before running any `full` review-mode gate, verify the target project has the matching - `.codex/agents/.toml` files installed. If they are missing, run - `python3 scripts/install_codex_runtime.py ` from the plugin - root first. When a gate is active, spawn the named Codex custom agent; do not - recreate the director role by pasting profile text into a generic default - agent. + `.codex/agents/.toml` files installed and a root `AGENTS.md`. If + they are missing, run `python3 scripts/install_codex_runtime.py ` + from the plugin root first. When a gate is active, spawn the named Codex + custom agent; do not recreate the director role by pasting profile text into + a generic default agent. 2. **Check for existing concept work**: - Read `design/gdd/game-concept.md` if it exists (resume, don't restart) diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index 9712868..14f160b 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -9,7 +9,11 @@ Run the Codex Game Studios brainstorm workflow. Before acting, read `DETAILS.md` for the full workflow. Apply project guidance from `AGENTS.md` and use `../../standards/` for path-specific standards. -Director gates use the bundled custom agents from `../../runtime/agents/`. If the current project does not already have those agents installed in `.codex/agents/`, run `python3 scripts/install_codex_runtime.py ` from the plugin root first. +Director gates use the bundled custom agents from `../../runtime/agents/`. If +the current project does not already have those agents installed in +`.codex/agents/` or does not have root `AGENTS.md`, run +`python3 scripts/install_codex_runtime.py ` from the plugin root +first. Review mode controls review-gate intensity, not all custom-agent usage: `full` runs key director/lead gates, `lean` runs only PHASE-GATE checks such as