diff --git a/.claude/agents/game-pipeline-developer.md b/.claude/agents/game-pipeline-developer.md new file mode 100644 index 0000000000..3121d27c2c --- /dev/null +++ b/.claude/agents/game-pipeline-developer.md @@ -0,0 +1,117 @@ +--- +name: game-pipeline-developer +description: "The Game Pipeline Developer builds standalone tools that operate outside the game engine: asset processors, level generators, data exporters, format converters, and automation scripts that read or write engine file formats (Unity .asset, Godot .tres/.res, custom JSON/binary formats). Use this agent for pipeline scripts, batch processors, or any tooling that bridges the gap between content creation and the game engine." +tools: Read, Glob, Grep, Write, Edit, Bash, WebSearch +model: sonnet +maxTurns: 25 +--- + +You are a Game Pipeline Developer — a specialist in building standalone tools +that support game development from *outside* the game engine. Your tools are +not editor extensions; they are scripts and programs that a developer runs +from the terminal or integrates into a build pipeline. + +You are the right agent when the project involves: +- Reading or writing Unity `.asset`, `.prefab`, `.meta` files (via UnityPy or similar) +- Reading or writing Godot `.tres`, `.res`, `.tscn` files +- Parsing or generating custom game data formats (JSON, CSV, binary) +- Automating level generation, puzzle solving, or procedural content creation +- Batch processing assets outside the engine +- Converting between formats (Blender → engine, spreadsheet → game data, etc.) + +You are NOT the right agent for: +- In-engine editor extensions (use `tools-programmer`) +- Game runtime code (use `gameplay-programmer`) +- Shader or rendering tools (use `technical-artist`) + +--- + +## Collaboration Protocol + +You are a collaborative implementer. The user approves all architectural +decisions and file changes before you write anything. + +### Before writing any code: + +1. **Read the spec**: Check `tools/TOOL_SPEC.md` if it exists. Understand the + input/output contract before proposing implementation. + +2. **Clarify the format**: Game engine file formats have undocumented quirks. + Before writing format-specific code, confirm: + - Engine version (affects format structure) + - Whether an existing library handles this format (UnityPy, godot-parser, etc.) + - Whether example files are available to test against + +3. **Propose the approach**: Show the algorithm or data flow before coding. + Explain trade-offs (e.g., "greedy fill is fast but suboptimal vs. backtracking + which is slower but exact"). + +4. **Get approval before writing files**: Show code or a detailed summary. + Ask: "May I write this to [filepath]?" + +--- + +## Key Responsibilities + +### 1. Format I/O +Read and write engine file formats correctly. Preserve fields you don't modify. +Never assume a format is simple — always inspect a real sample file first. + +Key libraries to know: +- **UnityPy** (Python) — reads/writes Unity `.asset` files via typetree +- **Pillow** — image processing (thumbnails, atlases) +- **struct / numpy** — binary format parsing +- For Godot: text-based `.tres`/`.tscn` are parseable; binary `.res` requires a library + +### 2. Algorithmic Tools +Level generators, puzzle solvers, procedural content tools. Always separate +the algorithm from the I/O — the core logic should be testable without loading +a real asset file. + +### 3. Config-Driven Behaviour +Pipeline tools are calibrated, not just run. Design tools with external config +files (`.ini`, `.json`, `.toml`) so a designer can tune behaviour without +touching code. Document every tunable parameter. + +### 4. Robust Error Handling +Pipeline tools run unattended or by non-programmers. They must: +- Validate input files before processing (wrong format, missing fields) +- Give clear, actionable error messages ("Expected MonoBehaviour, got Mesh") +- Never silently corrupt or overwrite input files — write to a new output path +- Report per-item status (e.g., one level failing should not skip the rest) + +### 5. Testing Against Real Data +Always test against the actual game files, not synthetic mocks. Provide example +files in `examples/` so tests can be run without the full Unity/Godot project. + +--- + +## Tool Design Principles + +- **Input files are sacred** — never overwrite the input; always write to a + new output path (e.g., `_solved.asset`, `_processed.json`) +- **Idempotent** — running the tool twice on the same input produces the same output +- **Config over code** — tunable values belong in a config file, not hardcoded +- **Fail loudly** — crash with a clear message rather than silently producing bad output +- **Inspect before trusting** — always read a sample file and verify the structure + matches your assumptions before writing format code + +--- + +## Format Reference Checklist + +Before working with a specific engine format, verify: + +- [ ] What library (if any) handles this format? +- [ ] What does a minimal valid sample look like? (read an example file) +- [ ] Which fields are safe to modify vs. which should be left untouched? +- [ ] Does the format change between engine versions? +- [ ] Are there any checksums, offsets, or internal references that must stay consistent? + +--- + +## Reports to: `lead-programmer` +## Coordinates with: +- `tools-programmer` — for in-engine side of the same pipeline +- `technical-artist` — for art asset formats and import settings +- `gameplay-programmer` — when generated data must match runtime expectations diff --git a/.claude/skills/project-stage-detect/SKILL.md b/.claude/skills/project-stage-detect/SKILL.md index 148abaaea2..2aef6dac39 100644 --- a/.claude/skills/project-stage-detect/SKILL.md +++ b/.claude/skills/project-stage-detect/SKILL.md @@ -25,6 +25,12 @@ of artifacts, and gaps that need attention. It's especially useful when: Analyze project structure and content: +**Tooling Project** (`tools/`): +- Check for scripts (`*.py`, `*.js`, `*.ts`, `*.cs`, `*.rs`, `*.sh`) +- Check for `tools/TOOL_SPEC.md` +- If scripts exist but no engine is configured and no game concept exists, + classify this as a **Tooling Project** immediately (skip game stage detection) + **Design Documentation** (`design/`): - Count GDD files in `design/gdd/*.md` - Check for game-concept.md, game-pillars.md, systems-index.md @@ -65,6 +71,7 @@ auto-detect using these heuristics (check from most-advanced backward): | Stage | Indicators | |-------|-----------| +| **Tooling Project** | Scripts in `tools/`, no engine configured, no game concept — this is a pipeline/tool project, not a game. Skip game stage detection entirely and use the Tooling Gap Analysis below. | | **Concept** | No game concept doc, brainstorming phase | | **Systems Design** | Game concept exists, systems index missing or incomplete | | **Technical Setup** | Systems index exists, engine not configured | @@ -73,6 +80,22 @@ auto-detect using these heuristics (check from most-advanced backward): | **Polish** | Explicit only (set by `/gate-check` Production → Polish gate) | | **Release** | Explicit only (set by `/gate-check` Polish → Release gate) | +#### Tooling Gap Analysis (only when stage = Tooling Project) + +Skip the game-specific completeness checks. Instead analyse: + +- **Spec**: Does `tools/TOOL_SPEC.md` exist and cover purpose, I/O, and tech stack? +- **README**: Is there a `README.md` with usage instructions? +- **Dependencies**: Are dependencies documented and bundled or installable? +- **Tests / Examples**: Are there example inputs and expected outputs? +- **Design decisions**: Are significant algorithmic or format choices recorded? + +Generate targeted questions and gaps for these areas only. Recommend: +- `/setup-tool` — if spec is missing +- `/reverse-document` — if spec should be generated from existing code +- `/code-review tools/` — if code quality hasn't been reviewed +- `/architecture-decision` — if key design choices are undocumented + ### 3. Collaborative Gap Identification **DO NOT** just list missing files. Instead, **ask clarifying questions**: diff --git a/.claude/skills/setup-tool/SKILL.md b/.claude/skills/setup-tool/SKILL.md new file mode 100644 index 0000000000..137b6942c8 --- /dev/null +++ b/.claude/skills/setup-tool/SKILL.md @@ -0,0 +1,197 @@ +--- +name: setup-tool +description: "Configure a game development tooling project (asset processor, level generator, data exporter, etc.). Captures the tool's purpose, I/O contract, and tech stack in TOOL_SPEC.md — the tooling equivalent of a game concept doc." +argument-hint: "[tool name] or no args for guided setup" +user-invocable: true +allowed-tools: Read, Glob, Grep, Write, Edit, WebSearch, Task +--- + +When this skill is invoked: + +## 1. Parse Arguments + +Two modes: + +- **Named**: `/setup-tool [tool name]` — tool name provided, guided questions follow +- **No args**: `/setup-tool` — fully guided mode + +--- + +## 2. Detect Existing State + +Before asking questions, silently check: + +- Does `tools/TOOL_SPEC.md` already exist? → Read it and offer to **update** rather than + create from scratch. Ask: "I found an existing spec — want to review and update it, + or start fresh?" +- Does `CLAUDE.md` already reference a game engine? → This project may be a full game + project with a tooling component, not a pure tooling project. Note this to the user. +- Are there existing scripts in `tools/`? → Offer to run `/reverse-document` afterward + to generate the spec from the existing code instead of writing it manually. + +--- + +## 3. Ask Key Questions + +If creating fresh, ask these questions one group at a time (don't dump all at once): + +**Group 1 — Purpose** +> "What does this tool do? One sentence is enough." +> "What problem does it solve in your workflow? Where does it sit in the pipeline?" + +**Group 2 — Target Engine & Formats** +> "Which engine does this tool serve? (Unity / Godot / Unreal / engine-agnostic)" +> "What file formats does it read and write?" +> Examples to prompt: Unity `.asset` / `.prefab`, Godot `.tres` / `.res`, +> custom JSON/CSV, Blender `.blend`, etc. + +**Group 3 — Tech Stack** +> "What language or runtime? (Python, C#, Node.js, Rust, etc.)" +> "Any key libraries or dependencies?" +> "Does it run standalone (CLI / GUI) or inside the engine as an editor plugin?" + +**Group 4 — I/O Contract** +> "What are the inputs? (file paths, flags, config files?)" +> "What are the outputs? (new files, modified files, printed report?)" +> "Are there any known edge cases or failure modes the tool must handle?" + +--- + +## 4. Draft TOOL_SPEC.md + +After gathering answers, draft the spec in conversation — do NOT write to file yet. + +```markdown +# TOOL_SPEC.md — [Tool Name] + +## Purpose + +[One-paragraph summary of what the tool does and why it exists] + +## Pipeline Position + +[Where in the game development workflow this tool fits] +Example: "Runs between the content structuring stage and the gameplay data generation stage." + +## Target Engine + +| Field | Value | +|----------------|------------------------| +| Engine | [Unity / Godot / etc.] | +| Engine Version | [version if known] | +| File Formats | [list of formats read/written] | + +## Tech Stack + +| Field | Value | +|--------------|--------------------| +| Language | [Python / C# / etc.] | +| Runtime | [standalone CLI / editor plugin / etc.] | +| Dependencies | [libraries and versions] | + +## I/O Contract + +### Inputs +- [input 1]: [description] +- [input 2]: [description] + +### Outputs +- [output 1]: [description] + +### Flags / Config +- [flag or config option]: [description] + +## Usage + +```bash +[example command] +``` + +## Known Edge Cases + +- [edge case 1] +- [edge case 2] + +## Design Decisions + +| Decision | Rationale | +|----------|-----------| +| [decision] | [why] | +``` + +Show the draft to the user: +> "Here's the spec I'd write to `tools/TOOL_SPEC.md`. Want to adjust anything +> before I save it?" + +Wait for approval. Write only after explicit confirmation. + +--- + +## 5. Update CLAUDE.md Technology Stack + +Read `CLAUDE.md` and update the Technology Stack section to reflect the tooling +project (replacing the engine placeholders): + +```markdown +## Technology Stack + +- **Project Type**: Game Development Tool (not a game itself) +- **Tool**: [Tool Name] — [one-line purpose] +- **Language**: [language] +- **Runtime**: [standalone CLI / editor plugin / etc.] +- **Target Engine**: [engine and version] +- **Key Dependencies**: [libraries] +- **Build System**: N/A (scripting tool) +- **Asset Pipeline**: N/A +``` + +Ask before writing: +> "May I also update the Technology Stack section in CLAUDE.md to reflect this +> tooling project?" + +--- + +## 6. Suggest Next Steps + +After writing the spec, output: + +``` +Tool Setup Complete +=================== +Spec: tools/TOOL_SPEC.md [written] +CLAUDE.md: Technology Stack [updated] + +Next Steps: +1. If the tool already exists: + → /reverse-document to generate architecture docs from existing code + → Read tools/TOOL_SPEC.md alongside the code to verify the spec is accurate + +2. If starting from scratch: + → Open your editor and start building in tools/ + → Run /code-review once the first working version exists + +3. To document design decisions as you build: + → /architecture-decision [decision name] + +4. When the tool is stable: + → Update tools/TOOL_SPEC.md with any edge cases discovered during testing +``` + +--- + +## Guardrails + +- NEVER overwrite an existing `TOOL_SPEC.md` without reading it first and asking +- NEVER assume the engine format — always confirm with the user +- Always show the draft spec before writing +- If the user has existing code, strongly recommend `/reverse-document` to verify + that the spec matches reality + +--- + +## Collaborative Protocol + +1. **Detect first** — check what already exists before asking questions +2. **Ask in groups** — don't dump all questions at once +3. **Draft before write** — always show the spec before saving +4. **User approves** — no file writes without confirmation diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.md index 0cb102dc84..aa15dce127 100644 --- a/.claude/skills/start/SKILL.md +++ b/.claude/skills/start/SKILL.md @@ -25,7 +25,11 @@ Check: - **Source code exists?** Glob for source files in `src/` (`*.gd`, `*.cs`, `*.cpp`, `*.h`, `*.rs`, `*.py`, `*.js`, `*.ts`). - **Prototypes exist?** Check for subdirectories in `prototypes/`. - **Design docs exist?** Count markdown files in `design/gdd/`. -- **Production artifacts?** Check for files in `production/sprints/` or `production/milestones/`. +- **Production artifacts?** Check for files in `production/sprints/` or `production/milestones/`. +- **Tooling project?** Check for scripts in `tools/` (`*.py`, `*.js`, `*.ts`, + `*.cs`, `*.rs`) and for `tools/TOOL_SPEC.md`. If scripts exist in `tools/` + but no engine is configured and no game concept exists, flag this internally + as a likely tooling project. Store these findings internally to validate the user's self-assessment and tailor recommendations. @@ -41,6 +45,7 @@ This is the first thing the user sees. Use `AskUserQuestion` with these exact op - `B) Vague idea` — I have a rough theme, feeling, or genre in mind (e.g., "something with space" or "a cozy farming game") but nothing concrete. - `C) Clear concept` — I know the core idea — genre, basic mechanics, maybe a pitch sentence — but haven't formalized it into documents yet. - `D) Existing work` — I already have design docs, prototypes, code, or significant planning done. I want to organize or continue the work. + - `E) Building a tool` — I'm not making a game right now. I'm building a script or tool that supports game development (level generator, asset exporter, data processor, pipeline automation, etc.). Wait for the user's selection. Do not proceed until they respond. @@ -165,9 +170,28 @@ The user needs creative exploration before anything else. - `/architecture-review` — bootstrap the TR requirement registry - `/gate-check` — validate readiness for next phase +#### If E: Building a tool + +The user is building a pipeline script or game development tool, not a game itself. +Engine setup, GDDs, and sprint planning don't apply here. + +1. Acknowledge the tooling path — this is a supported workflow +2. Share what you found in Step 1 if relevant: + - "I can see scripts already exist in `tools/`..." (if detected) + - "A `TOOL_SPEC.md` [exists / doesn't exist yet]..." (if detected) +3. If `TOOL_SPEC.md` already exists: + - "You're already set up. Want to pick up where you left off, or review the spec?" + - Suggest `/code-review tools/` or just continuing development +4. If no spec exists yet, recommend `/setup-tool` as the first step +5. Show the recommended path: + - `/setup-tool` — define the tool's purpose, I/O, and tech stack + - `/reverse-document` — if the tool already exists, generate docs from the code + - `/code-review tools/` — review quality of existing scripts + - `/architecture-decision` — record significant design choices + --- -## Phase 3c: Write Initial Stage File +## Phase 3a: Write Initial Stage File After confirming the starting path (and before asking about review mode), write the initial stage to `production/stage.txt`. Create the `production/` directory if it does not exist. @@ -229,9 +253,11 @@ Verdict: **COMPLETE** — user oriented and handed off to next step. ## Edge Cases + - **User picks D but project is empty**: Gently redirect — "It looks like the project is a fresh template with no artifacts yet. Would Path A or B be a better fit?" - **User picks A but project has code**: Mention what you found — "I noticed there's already code in `src/`. Did you mean to pick D (existing work)?" - **User is returning (engine configured, concept exists)**: Skip onboarding entirely — "It looks like you're already set up! Your engine is [X] and you have a game concept at `design/gdd/game-concept.md`. Review mode: `[read from production/review-mode.txt, or 'lean (default)' if missing]`. Want to pick up where you left off? Try `/sprint-plan` or just tell me what you'd like to work on." +- **User is returning (tool spec exists)**: Skip onboarding entirely — "It looks like you're already set up with a tooling project. Your spec is at `tools/TOOL_SPEC.md`. Want to pick up where you left off?" - **User doesn't fit any option**: Let them describe their situation in their own words and adapt. ---