diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index d0e6407..f006250 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "codex-game-studios", - "version": "0.1.1", - "description": "A Codex plugin for building game-production workflows step by step, starting with guided game concept brainstorming.", + "version": "0.2.0", + "description": "A Codex plugin for game-production workflows, project runtime setup, and guided game concept brainstorming.", "author": { "name": "wxm", "email": "18854896936@163.com", @@ -14,6 +14,7 @@ "games", "game-development", "studio-workflow", + "runtime-setup", "brainstorm", "gdd" ], @@ -21,7 +22,7 @@ "interface": { "displayName": "Codex Game Studios", "shortDescription": "Game-production workflows for Codex", - "longDescription": "Build a Codex game-production plugin step by step. The current workflow starts with /brainstorm, a guided concept ideation process that turns a rough idea into a structured game concept document.", + "longDescription": "Codex Game Studios exposes plugin-native skills for initializing game projects, installing bundled director agents, and guiding concept ideation into structured game design documentation.", "developerName": "wxm", "category": "Coding", "capabilities": [ @@ -33,7 +34,9 @@ "privacyPolicyURL": "https://gitea.wuxianming.ac.cn/wxm/codex-game-studios", "termsOfServiceURL": "https://gitea.wuxianming.ac.cn/wxm/codex-game-studios", "defaultPrompt": [ - "Run /brainstorm for my game project." + "Use $setup-runtime to initialize this game project.", + "Use $brainstorm to shape my game concept.", + "Use $using-codex-game-studios to explain the workflow." ], "brandColor": "#0F766E", "composerIcon": "./assets/codex-game-studio.svg", diff --git a/.gitignore b/.gitignore index b8b2a20..fea4e3a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,6 @@ .env +.env.* .DS_Store __pycache__/ *.pyc +plan.md diff --git a/README.md b/README.md index 8442a5c..e2f426c 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,47 @@ # Codex Game Studios -This repository is the minimal starting framework for a Codex plugin. +Codex Game Studios is a Codex plugin for game-production workflows. It follows +the normal plugin layout: `.codex-plugin/plugin.json` points to `./skills/`, and +skills expose the runtime workflows directly. Do not use a global +`~/.codex/skills/codex-game-studio` bridge as the plugin entry point. -Current state: +## Current State -- Skills: `/brainstorm` -- Codex custom agents: `creative-director`, `art-director`, `technical-director`, `producer` -- Assets: `codex-game-studio.svg` -- References: `director-gates.md`, `templates/game-concept.md` -- Standards: `design-docs.md` -- Commands: `/brainstorm` wrapper document -- Scripts: `scripts/install_codex_runtime.py` installs bundled custom agents into a target project +- Skills: + - `$using-codex-game-studios` explains the plugin workflow and entry points. + - `$setup-runtime` installs bundled director agents into a target game project. + - `$brainstorm` guides game concept ideation into `design/gdd/game-concept.md`. +- Runtime agents: `creative-director`, `art-director`, `technical-director`, `producer` +- Runtime source: `runtime/agents/` +- References: `references/studio-docs/director-gates.md`, `references/studio-docs/templates/game-concept.md` +- Standards: `standards/design-docs.md` - Marketplace: `.agents/plugins/marketplace.json` -- No hooks -- No rules -- No MCP servers -- No app integrations +- No hooks, rules, MCP servers, or app integrations yet -The director agents are pre-defined Codex custom agents stored in: +## Runtime Setup -```text -.codex/agents/ -``` - -Each custom agent is a standalone TOML file with `name`, `description`, and -`developer_instructions`, matching the Codex subagents documentation. - -To install the bundled custom agents into a game project: +To install the bundled custom agents into a game project, invoke `$setup-runtime` +or run the installer directly: ```bash -python3 scripts/install_codex_runtime.py /path/to/game-project +python3 skills/setup-runtime/scripts/install_codex_runtime.py /path/to/game-project ``` -The current installer only writes custom agents to: +The installer writes custom agents to: ```text /path/to/game-project/.codex/agents/ ``` -The only required plugin manifest is: +Each runtime agent is a standalone TOML file with `name`, `description`, and +`developer_instructions`, matching Codex custom-agent conventions. -```text -.codex-plugin/plugin.json +## Packaging Hygiene + +Only plugin source files should be packaged. `.git/`, `.env`, `.DS_Store`, local +caches, and generated artifacts are not part of the plugin runtime. Run the +validation script before publishing or refreshing an installed cache: + +```bash +python3 scripts/validate_plugin.py ``` - -Add plugin components one at a time so each addition can be reviewed, explained, and adjusted before the next component is introduced. diff --git a/commands/brainstorm.md b/commands/brainstorm.md deleted file mode 100644 index 56a6d15..0000000 --- a/commands/brainstorm.md +++ /dev/null @@ -1,15 +0,0 @@ -# /brainstorm - -Run the Brainstorm Codex Game Studio skill workflow. - -## Arguments - -Pass any text after `/brainstorm` as workflow input. - -## Workflow - -1. Use `../skills/brainstorm/SKILL.md` as the workflow entry point. -2. Read `../skills/brainstorm/DETAILS.md` when present for the full procedure. -3. Apply project guidance from `AGENTS.md` and relevant files in `../standards/` before changing project files. -4. Use the pre-defined Codex custom agents in `../.codex/agents/.toml` when the skill delegates to a subagent. -5. Return decisions, changes, blockers, verification, and next steps. diff --git a/references/studio-docs/director-gates.md b/references/studio-docs/director-gates.md index 0a92239..5b6f0f0 100644 --- a/references/studio-docs/director-gates.md +++ b/references/studio-docs/director-gates.md @@ -19,10 +19,11 @@ Spawn `creative-director` via Codex custom-agent delegation using gate **CD-PILLARS** from `references/studio-docs/director-gates.md`. ``` -The matching custom agent must already be defined at -`.codex/agents/.toml`. Pass the context listed under that gate's -**Context to pass** field, then handle the verdict using the **Verdict -handling** rules below. +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 `$setup-runtime` if the target project is missing +them. Pass the context listed under that gate's **Context to pass** field, then +handle the verdict using the **Verdict handling** rules below. Director names are Codex custom agent names. Do not recreate them by pasting profile text into a generic default agent. @@ -86,7 +87,7 @@ Apply the resolved mode: # Apply mode check, then: Spawn `[agent-name]` via Codex custom-agent delegation: - Gate: [GATE-ID] (see references/studio-docs/director-gates.md) -- Custom agent file: .codex/agents/[agent-name].toml +- Custom agent file: .codex/agents/[agent-name].toml in the target project - Context: [fields listed under that gate] - Codex fork_context: false unless full thread context is required - Await the verdict before proceeding. @@ -110,7 +111,7 @@ All gates return one of three verdicts. Skills must handle all three: | Verdict | Meaning | Default action | |---------|---------|----------------| | **APPROVE / READY** | No issues. Proceed. | Continue the workflow | -| **CONCERNS [list]** | Issues present but not blocking. | Surface to user via `ask the user in chat` — options: `Revise flagged items` / `Accept and proceed` / `Discuss further` | +| **CONCERNS [list]** | Issues present but not blocking. | Surface to user via a structured prompt when available, or ask directly in chat: `Revise flagged items` / `Accept and proceed` / `Discuss further` | | **REJECT / NOT READY [blockers]** | Blocking issues. Do not proceed. | Surface blockers to user. Do not write files or advance stage until resolved. | **Escalation rule**: When multiple directors are spawned in parallel, apply the @@ -133,7 +134,7 @@ For phase gates, record in `docs/architecture/architecture.md` or ## Tier 1 — Creative Director Gates -Agent: `creative-director` | Custom agent file: `.codex/agents/creative-director.toml` | Domain: Vision, pillars, player experience +Agent: `creative-director` | Target custom agent file: `.codex/agents/creative-director.toml` | Domain: Vision, pillars, player experience --- @@ -275,7 +276,7 @@ any session that produces player feedback ## Tier 1 — Technical Director Gates -Agent: `technical-director` | Custom agent file: `.codex/agents/technical-director.toml` | Domain: Architecture, engine risk, performance +Agent: `technical-director` | Target custom agent file: `.codex/agents/technical-director.toml` | Domain: Architecture, engine risk, performance --- @@ -421,7 +422,7 @@ or before finalizing any engine-specific implementation approach ## Tier 1 — Producer Gates -Agent: `producer` | Custom agent file: `.codex/agents/producer.toml` | Domain: Scope, timeline, dependencies, production risk +Agent: `producer` | Target custom agent file: `.codex/agents/producer.toml` | Domain: Scope, timeline, dependencies, production risk --- @@ -547,7 +548,7 @@ is invoked ## Tier 1 — Art Director Gates -Agent: `art-director` | Custom agent file: `.codex/agents/art-director.toml` | Domain: Visual identity, art bible, visual production readiness +Agent: `art-director` | Target custom agent file: `.codex/agents/art-director.toml` | Domain: Visual identity, art bible, visual production readiness --- diff --git a/.codex/agents/art-director.toml b/runtime/agents/art-director.toml similarity index 100% rename from .codex/agents/art-director.toml rename to runtime/agents/art-director.toml diff --git a/.codex/agents/creative-director.toml b/runtime/agents/creative-director.toml similarity index 100% rename from .codex/agents/creative-director.toml rename to runtime/agents/creative-director.toml diff --git a/.codex/agents/producer.toml b/runtime/agents/producer.toml similarity index 100% rename from .codex/agents/producer.toml rename to runtime/agents/producer.toml diff --git a/.codex/agents/technical-director.toml b/runtime/agents/technical-director.toml similarity index 100% rename from .codex/agents/technical-director.toml rename to runtime/agents/technical-director.toml diff --git a/scripts/validate_plugin.py b/scripts/validate_plugin.py new file mode 100755 index 0000000..444cd67 --- /dev/null +++ b/scripts/validate_plugin.py @@ -0,0 +1,125 @@ +#!/usr/bin/env python3 +"""Validate Codex Game Studios plugin structure and package hygiene.""" + +from __future__ import annotations + +import json +import subprocess +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +FORBIDDEN_NAMES = {".DS_Store", ".env", "plan.md"} +FORBIDDEN_PARTS = {".git", "__pycache__"} +REQUIRED_SKILLS = { + "brainstorm", + "setup-runtime", + "using-codex-game-studios", +} +REQUIRED_RUNTIME_AGENTS = { + "art-director.toml", + "creative-director.toml", + "producer.toml", + "technical-director.toml", +} + + +def fail(message: str) -> None: + print(f"ERROR: {message}", file=sys.stderr) + raise SystemExit(1) + + +def run_git(args: list[str]) -> list[str]: + result = subprocess.run( + ["git", *args], + cwd=ROOT, + text=True, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + ) + if result.returncode != 0: + raise RuntimeError(result.stderr.strip() or "git command failed") + return [line for line in result.stdout.splitlines() if line] + + +def assert_manifest() -> None: + manifest_path = ROOT / ".codex-plugin" / "plugin.json" + if not manifest_path.is_file(): + fail("Missing .codex-plugin/plugin.json") + + manifest = json.loads(manifest_path.read_text(encoding="utf-8")) + if manifest.get("name") != "codex-game-studios": + fail("plugin.json name must be codex-game-studios") + if manifest.get("skills") != "./skills/": + fail('plugin.json must expose skills via "./skills/"') + + for prompt in manifest.get("interface", {}).get("defaultPrompt", []): + if len(prompt) > 128: + fail(f"defaultPrompt exceeds 128 chars: {prompt}") + + +def assert_skill(skill_name: str) -> None: + skill_dir = ROOT / "skills" / skill_name + skill_path = skill_dir / "SKILL.md" + agent_path = skill_dir / "agents" / "openai.yaml" + + if not skill_path.is_file(): + fail(f"Missing skill file: {skill_path.relative_to(ROOT)}") + if not agent_path.is_file(): + fail(f"Missing skill UI metadata: {agent_path.relative_to(ROOT)}") + + text = skill_path.read_text(encoding="utf-8") + if not text.startswith("---\n"): + fail(f"Missing YAML frontmatter: {skill_path.relative_to(ROOT)}") + if f"name: {skill_name}" not in text: + fail(f"Skill name mismatch in {skill_path.relative_to(ROOT)}") + if "description:" not in text.split("---", 2)[1]: + fail(f"Missing skill description in {skill_path.relative_to(ROOT)}") + + +def assert_runtime_agents() -> None: + agent_dir = ROOT / "runtime" / "agents" + if not agent_dir.is_dir(): + fail("Missing runtime/agents directory") + + present = {path.name for path in agent_dir.glob("*.toml")} + missing = sorted(REQUIRED_RUNTIME_AGENTS - present) + if missing: + fail(f"Missing runtime agents: {', '.join(missing)}") + + +def assert_package_hygiene() -> None: + try: + tracked = run_git(["ls-files"]) + untracked = run_git(["ls-files", "--others", "--exclude-standard"]) + candidates = tracked + untracked + except RuntimeError: + candidates = [ + str(path.relative_to(ROOT)) + for path in ROOT.rglob("*") + if path.is_file() or path.is_dir() + ] + + bad: list[str] = [] + for rel_path in candidates: + path = Path(rel_path) + if path.name in FORBIDDEN_NAMES or FORBIDDEN_PARTS.intersection(path.parts): + bad.append(rel_path) + + if bad: + fail("Forbidden package candidates:\n- " + "\n- ".join(sorted(bad))) + + +def main() -> int: + assert_manifest() + for skill_name in sorted(REQUIRED_SKILLS): + assert_skill(skill_name) + assert_runtime_agents() + assert_package_hygiene() + print("Codex Game Studios plugin validation passed.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skills/brainstorm/DETAILS.md b/skills/brainstorm/DETAILS.md index fe1aac6..00c0b2e 100644 --- a/skills/brainstorm/DETAILS.md +++ b/skills/brainstorm/DETAILS.md @@ -11,9 +11,12 @@ When this skill is invoked: See `../../references/studio-docs/director-gates.md` for the full check pattern. - When a gate is active, spawn the named Codex custom agent that is already - defined in `../../.codex/agents/.toml`. Do not recreate the - director role by pasting profile text into a generic default agent. + Director agent source files live in `../../runtime/agents/`. Before running + any `full` review-mode gate, verify the target project has the matching + `.codex/agents/.toml` files installed. If they are missing, run + `$setup-runtime` for the project 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) @@ -24,13 +27,17 @@ When this skill is invoked: exploration** where the AI acts as a creative facilitator, not a replacement for the human's vision. - **Use `ask the user in chat`** at key decision points throughout brainstorming: + **Use a structured decision prompt when available** at key decision points + throughout brainstorming. In Codex, use the current user-input mechanism if + it is available in the active mode; otherwise ask the same question directly + in chat and wait for the user's reply. - Constrained taste questions (genre preferences, scope, team size) - Concept selection ("Which 2-3 concepts resonate?") after presenting options - Direction choices ("Develop further, explore more, or prototype?") - Pillar ranking after concepts are refined Write full creative analysis in conversation text first, then use - `ask the user in chat` to capture the decision with concise labels. + the structured prompt or chat question to capture the decision with concise + labels. Professional studio brainstorming principles to follow: - Withhold judgment — no idea is bad during exploration @@ -55,18 +62,19 @@ conversationally (not as a checklist): **Taste profile**: - What 3 games have you spent the most time with? What kept you coming back? *(Ask this as plain text — the user must be able to type specific game names freely. - Do NOT put this in an ask the user in chat with preset options.)* + Do NOT put this in a structured prompt with preset options.)* - Are there genres you love? Genres you avoid? Why? - Do you prefer games that challenge you, relax you, tell you stories, - or let you express yourself? *(Use `ask the user in chat` for this — constrained choice.)* + or let you express yourself? *(Use a structured prompt for this when available — constrained choice.)* **Practical constraints** (shape the sandbox before brainstorming). -Bundle these into a single multi-tab `ask the user in chat` with these exact tab labels: +Bundle these into a single multi-field structured prompt when available: - Tab "Experience" — "What kind of experience do you most want players to have?" (Challenge & Mastery / Story & Discovery / Expression & Creativity / Relaxation & Flow) - Tab "Timeline" — "What's your realistic development timeline?" (Weeks / Months / 1-2 years / Multi-year) - Tab "Dev level" — "Where are you in your dev journey?" (First game / Shipped before / Professional background) -Use exactly these tab names — do not rename or duplicate them. +If the UI supports grouping fields, use exactly these group names. If not, +ask the three questions one at a time. **Synthesize** the answers into a **Creative Brief** — a 3-5 sentence summary of the person's emotional goals, taste profile, and constraints. @@ -104,12 +112,13 @@ For each concept, present: - **Why It Could Work** (1 sentence on market/audience fit) - **Biggest Risk** (1 sentence on the hardest unanswered question) -Present all three. Then use `ask the user in chat` to capture the selection. +Present all three. Then use a structured prompt or direct chat question to +capture the selection. -**CRITICAL**: This MUST be a plain list call — no tabs, no form fields. Use exactly this structure: +**CRITICAL**: This MUST be a plain list choice, not a multi-field form. Use this structure: ``` -ask the user in chat( +structured decision prompt( prompt: "Which concept resonates with you? You can pick one, combine elements, or ask for fresh directions.", options: [ "Concept 1 — [Title]", @@ -121,7 +130,7 @@ ask the user in chat( ) ``` -Do NOT use a `tabs` field here. The `tabs` form is for multi-field input only — using it here causes an "Invalid tool parameters" error. This is a plain `prompt` + `options` call. +Do NOT use a multi-field form here. This is a plain prompt plus options. Never pressure toward a choice — let them sit with it. @@ -135,7 +144,7 @@ isolation, no amount of content or polish will save the game. **30-Second Loop** (moment-to-moment): -Ask these as `ask the user in chat` calls — derive the options from the chosen concept, don't hardcode them: +Ask these as structured prompts when available — derive the options from the chosen concept, don't hardcode them: 1. **Core action feel** — prompt: "What's the primary feel of the core action?" Generate 3-4 options that fit the concept's genre and tone, plus a free-text escape (`I'll describe it`). @@ -184,11 +193,11 @@ Then define **3+ anti-pillars** (what this game is NOT): be cool if..." features that don't serve the core vision - Frame as: "We will NOT do [thing] because it would compromise [pillar]" -**Pillar confirmation**: After presenting the full pillar set, use `ask the user in chat`: +**Pillar confirmation**: After presenting the full pillar set, use a structured prompt: - Prompt: "Do these pillars feel right for your game?" - Options: `[A] Lock these in` / `[B] Rename or reframe one` / `[C] Swap a pillar out` / `[D] Something else` -If the user selects B, C, or D, make the revision, then use `ask the user in chat` again: +If the user selects B, C, or D, make the revision, then use a structured prompt again: - Prompt: "Pillars updated. Ready to lock these in?" - Options: `[A] Lock these in` / `[B] Revise another pillar` / `[C] Something else` @@ -207,7 +216,7 @@ Repeat until the user selects [A] Lock these in. - **`art-director`** — gate **AD-CONCEPT-VISUAL** (`../../references/studio-docs/director-gates.md`) Pass: game concept elevator pitch, full pillar set with design tests, target platform (if known), any reference games or visual touchstones the user mentioned. -Collect both verdicts, then present them together using a two-tab `ask the user in chat`: +Collect both verdicts, then present them together using a structured prompt: - Tab **"Pillars"**: present creative-director feedback. Options mirror the standard CD-PILLARS handling — `Lock in as-is` / `Revise [specific pillar]` / `Discuss further`. - Tab **"Visual anchor"**: present the art-director's 2-3 named visual direction options. Options: each named direction (one per option) + `Combine elements across directions` + `Describe my own direction`. @@ -236,12 +245,12 @@ who this game is actually for: Ground the concept in reality: -- **Target platform**: Use `ask the user in chat` — "What platforms are you targeting for this game?" +- **Target platform**: Use a structured prompt when available — "What platforms are you targeting for this game?" Options: `PC (Steam / Epic)` / `Mobile (iOS / Android)` / `Console` / `Web / Browser` / `Multiple platforms` Record the answer — it directly shapes the engine recommendation and will be passed to `/setup-engine`. Note platform implications if relevant (e.g., mobile means Unity is strongly preferred; console means Godot has limitations; web means Godot exports cleanly). -- **Engine experience**: Use `ask the user in chat` — "Do you already have an engine you work in?" +- **Engine experience**: Use a structured prompt when available — "Do you already have an engine you work in?" Options: `Godot` / `Unity` / `Unreal Engine 5` / `No preference — help me decide` - If they pick an engine → record it as their preference and move on. Do NOT second-guess it. - If "No preference" → tell them: "Run `/setup-engine` after this session — it will walk you through the full decision based on your concept and platform target." Do not make a recommendation here. @@ -290,13 +299,13 @@ Present the assessment to the user. If UNREALISTIC, offer to adjust the MVP defi This section is the seed of the art bible — it captures the "everything must move" decision before it can be forgotten between sessions. -5. Use `ask the user in chat` for write approval: +5. Use a structured prompt or direct chat question for write approval: - Prompt: "Game concept is ready. May I write it to `design/gdd/game-concept.md`?" - Options: `[A] Yes — write it` / `[B] Not yet — revise a section first` -If [B]: ask which section to revise using `ask the user in chat` with options: `Elevator Pitch` / `Core Fantasy & Unique Hook` / `Pillars` / `Core Loop` / `MVP Definition` / `Scope Tiers` / `Risks` / `Something else — I'll describe` +If [B]: ask which section to revise using a structured prompt with options: `Elevator Pitch` / `Core Fantasy & Unique Hook` / `Pillars` / `Core Loop` / `MVP Definition` / `Scope Tiers` / `Risks` / `Something else — I'll describe` -After revising, show the updated section as a diff or clear before/after, then use `ask the user in chat` — "Ready to write the updated concept document?" +After revising, show the updated section as a diff or clear before/after, then ask — "Ready to write the updated concept document?" Options: `[A] Yes — write it` / `[B] Revise another section` Repeat until the user selects [A]. diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index 031c905..8865244 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -5,6 +5,8 @@ description: "Use when you need the /brainstorm game-production workflow. Guided # Brainstorm -Run the `/brainstorm` Codex Game Studio workflow. +Run the Codex Game Studios brainstorm workflow. -Before acting, read `DETAILS.md` for the full workflow. Apply project guidance from `AGENTS.md`, use `../../standards/` for path-specific standards, and use the pre-defined Codex custom agents in `../../.codex/agents/.toml` when the workflow delegates to a subagent. +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 `$setup-runtime` first. diff --git a/skills/brainstorm/agents/openai.yaml b/skills/brainstorm/agents/openai.yaml index 21a45b1..979d1be 100644 --- a/skills/brainstorm/agents/openai.yaml +++ b/skills/brainstorm/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Brainstorm" - short_description: "Use when you need the /brainstorm game-production workflow. Guided game concept ideation — from zero idea to a structure" - default_prompt: "Run /brainstorm for my game project." + short_description: "Shape a game idea into a concept doc" + default_prompt: "Use $brainstorm to shape my game concept." diff --git a/skills/setup-runtime/SKILL.md b/skills/setup-runtime/SKILL.md new file mode 100644 index 0000000..99e2e7e --- /dev/null +++ b/skills/setup-runtime/SKILL.md @@ -0,0 +1,23 @@ +--- +name: setup-runtime +description: "Use when a user asks to initialize, install, or refresh the Codex Game Studios runtime in a game project. Installs bundled director custom agents into the target project's .codex/agents directory." +--- + +# Setup Runtime + +Install the Codex Game Studios runtime assets into the current game project. + +## Workflow + +1. Treat the current working directory as the target project unless the user names another path. +2. Run `scripts/install_codex_runtime.py `. +3. Report installed, unchanged, and conflicting agent files. +4. If conflicts are reported, do not overwrite them unless the user explicitly asks for `--force`. + +The installer copies runtime agents from the plugin's `runtime/agents/` directory to: + +```text +/.codex/agents/ +``` + +The runtime currently contains only Codex custom-agent TOML files. It does not install hooks, rules, MCP servers, apps, or project templates. diff --git a/skills/setup-runtime/agents/openai.yaml b/skills/setup-runtime/agents/openai.yaml new file mode 100644 index 0000000..8171611 --- /dev/null +++ b/skills/setup-runtime/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Setup Runtime" + short_description: "Install game-studio agents into a project" + default_prompt: "Use $setup-runtime to initialize this game project." diff --git a/scripts/install_codex_runtime.py b/skills/setup-runtime/scripts/install_codex_runtime.py similarity index 88% rename from scripts/install_codex_runtime.py rename to skills/setup-runtime/scripts/install_codex_runtime.py index b2faa5b..e27d203 100755 --- a/scripts/install_codex_runtime.py +++ b/skills/setup-runtime/scripts/install_codex_runtime.py @@ -2,7 +2,7 @@ """Install Codex Game Studios runtime files into a game project. Current runtime scope: -- Copy bundled Codex custom agents from this plugin's `.codex/agents/` +- Copy bundled Codex custom agents from this plugin's `runtime/agents/` directory into the target project's `.codex/agents/` directory. This installer intentionally does not install hooks, rules, MCP servers, apps, @@ -19,8 +19,18 @@ from dataclasses import dataclass from pathlib import Path -PLUGIN_ROOT = Path(__file__).resolve().parents[1] -SOURCE_AGENTS_DIR = PLUGIN_ROOT / ".codex" / "agents" +def find_plugin_root(start: Path) -> Path: + """Walk upward until the Codex plugin manifest is found.""" + for candidate in [start, *start.parents]: + if (candidate / ".codex-plugin" / "plugin.json").is_file(): + return candidate + raise FileNotFoundError( + f"Could not find .codex-plugin/plugin.json above: {start}" + ) + + +PLUGIN_ROOT = find_plugin_root(Path(__file__).resolve()) +SOURCE_AGENTS_DIR = PLUGIN_ROOT / "runtime" / "agents" @dataclass(frozen=True) diff --git a/skills/using-codex-game-studios/SKILL.md b/skills/using-codex-game-studios/SKILL.md new file mode 100644 index 0000000..988cd5d --- /dev/null +++ b/skills/using-codex-game-studios/SKILL.md @@ -0,0 +1,19 @@ +--- +name: using-codex-game-studios +description: "Use when a user asks how the Codex Game Studios plugin is structured, what workflow to run next, how to initialize it, or how it differs from generic development workflow plugins." +--- + +# Using Codex Game Studios + +Codex Game Studios is a game-production plugin built around plugin-discovered skills, not global `~/.codex/skills` bridge folders. + +## Entry Points + +- Use `$setup-runtime` when a project needs the bundled director agents installed into `.codex/agents/`. +- Use `$brainstorm` to turn a rough game idea into `design/gdd/game-concept.md`. +- Use `runtime/agents/` as the plugin source of bundled custom agents. +- Use `references/` and `standards/` only when the active workflow points to them. + +## Design Rule + +Do not rely on a global `~/.codex/skills/codex-game-studio` bridge. The installed plugin exposes its skills through `.codex-plugin/plugin.json` with `"skills": "./skills/"`, matching the normal Codex plugin layout. diff --git a/skills/using-codex-game-studios/agents/openai.yaml b/skills/using-codex-game-studios/agents/openai.yaml new file mode 100644 index 0000000..8eac1ac --- /dev/null +++ b/skills/using-codex-game-studios/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Using Codex Game Studios" + short_description: "Understand the game-studio plugin workflow" + default_prompt: "Use $using-codex-game-studios to explain this plugin workflow."