安装项目 AGENTS 指南

2026-05-18 19:21:55 -07:00
parent 8cd173889c
commit 0c4227cba6
7 changed files with 240 additions and 23 deletions
--- 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
--- a/project-template/AGENTS.md
+++ 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.
--- 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/<agent-name>.toml`. The plugin source copies for those agents live
-in `runtime/agents/`; run `python3 scripts/install_codex_runtime.py <target-project>`
-from the plugin root if the target project is missing them. Pass the context
+`.codex/agents/<agent-name>.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 <target-project>` 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.

--- 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

--- 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
--- 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/<agent-name>.toml` files installed. If they are missing, run
-   `python3 scripts/install_codex_runtime.py <target-project>` 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/<agent-name>.toml` files installed and a root `AGENTS.md`. If
+   they are missing, run `python3 scripts/install_codex_runtime.py <target-project>`
+   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)
--- 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 <target-project>` 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 <target-project>` 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