diff --git a/.opencode/docs/CLAUDE-local-template.md b/.opencode/docs/CLAUDE-local-template.md deleted file mode 100644 index 5c858f3..0000000 --- a/.opencode/docs/CLAUDE-local-template.md +++ /dev/null @@ -1,37 +0,0 @@ -# CLAUDE.local.md Template - -Copy this file to the project root as `CLAUDE.local.md` for personal overrides. -This file is gitignored and will not be committed. - -```markdown -# Personal Preferences - -## Model Preferences -- Prefer Opus for complex design tasks -- Use Haiku for quick lookups and simple edits - -## Workflow Preferences -- Always run tests after code changes -- Compact context proactively at 60% usage -- Use /clear between unrelated tasks - -## Local Environment -- Python command: python (or py / python3) -- Shell: Git Bash on Windows -- IDE: VS Code with Claude Code extension - -## Communication Style -- Keep responses concise -- Show file paths in all code references -- Explain architectural decisions briefly - -## Personal Shortcuts -- When I say "review", run /code-review on the last changed files -- When I say "status", show git status + sprint progress -``` - -## Setup - -1. Copy this template to your project root: `cp .opencode/docs/CLAUDE-local-template.md CLAUDE.local.md` -2. Edit to match your preferences -3. Verify `CLAUDE.local.md` is in `.gitignore` (Claude Code reads it from the project root) diff --git a/.opencode/docs/context-management.md b/.opencode/docs/context-management.md index 2734f3b..c23998a 100644 --- a/.opencode/docs/context-management.md +++ b/.opencode/docs/context-management.md @@ -1,6 +1,6 @@ # Context Management -Context is the most critical resource in a Claude Code session. Manage it actively. +Context is the most critical resource in an OpenCode session. Manage it actively. ## File-Backed State (Primary Strategy) diff --git a/.opencode/docs/coordination-rules.md b/.opencode/docs/coordination-rules.md index e9f2a41..9525da1 100644 --- a/.opencode/docs/coordination-rules.md +++ b/.opencode/docs/coordination-rules.md @@ -36,7 +36,7 @@ high-stakes output; otherwise leave unset (Sonnet). This project uses two distinct multi-agent patterns: ### Subagents (current, always active) -Spawned via `Task` within a single Claude Code session. Used by all `team-*` skills +Spawned via `Task` within a single OpenCode session. Used by all `team-*` skills and orchestration skills. Subagents share the session's permission context, run sequentially or in parallel within the session, and return results to the parent. @@ -45,23 +45,13 @@ needs the other's output to begin), spawn both Task calls simultaneously rather than waiting. Example: `/review-all-gdds` Phase 1 (consistency) and Phase 2 (design theory) are independent — spawn both at the same time. -### Agent Teams (experimental — opt-in) -Multiple independent Claude Code *sessions* running simultaneously, coordinated +### Agent Teams (future) +Multiple independent OpenCode *sessions* running simultaneously, coordinated via a shared task list. Each session has its own context window and token budget. -Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable. +OpenCode does not currently support this pattern. -**Use agent teams when**: -- Work spans multiple subsystems that will not touch the same files -- Each workstream would take >30 minutes and benefits from true parallelism -- A senior agent (technical-director, producer) needs to coordinate 3+ specialist - sessions working on different epics simultaneously - -**Do not use agent teams when**: -- One session's output is required as input for another (use sequential subagents) -- The task fits in a single session's context (use subagents instead) -- Cost is a concern — each team member burns tokens independently - -**Current status**: Not yet used in this project. Document usage here when first adopted. +**Use subagents instead** — the `Task` tool spawns agents within a single session +and supports both sequential and parallel execution. See the Subagents section above. ## Parallel Task Protocol diff --git a/.opencode/docs/director-gates.md b/.opencode/docs/director-gates.md index 21e04eb..f643a12 100644 --- a/.opencode/docs/director-gates.md +++ b/.opencode/docs/director-gates.md @@ -101,7 +101,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 `AskUserQuestion` — options: `Revise flagged items` / `Accept and proceed` / `Discuss further` | +| **CONCERNS [list]** | Issues present but not blocking. | Surface to user via `question` — options: `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 diff --git a/.opencode/docs/hooks-reference.md b/.opencode/docs/hooks-reference.md index fd169d5..05bfc7a 100644 --- a/.opencode/docs/hooks-reference.md +++ b/.opencode/docs/hooks-reference.md @@ -1,21 +1,36 @@ # Active Hooks -Hooks are configured in `.opencode/settings.json` and fire automatically: - -| Hook | Event | Trigger | Action | -| ---- | ----- | ------- | ------ | -| `validate-commit.sh` | PreToolUse (Bash) | `git commit` commands | Validates design doc sections, JSON data files, hardcoded values, TODO format | -| `validate-push.sh` | PreToolUse (Bash) | `git push` commands | Warns on pushes to protected branches (develop/main) | -| `validate-assets.sh` | PostToolUse (Write/Edit) | Asset file changes | Checks naming conventions and JSON validity for files in `assets/` | -| `session-start.sh` | SessionStart | Session begins | Loads sprint context, milestone, git activity; detects and previews active session state file for recovery | -| `detect-gaps.sh` | SessionStart | Session begins | Detects fresh projects (suggests /start) and missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect | -| `pre-compact.sh` | PreCompact | Context compression | Dumps session state (active.md, modified files, WIP design docs) into conversation before compaction so it survives summarization | -| `post-compact.sh` | PostCompact | After compaction | Reminds Claude to restore session state from `active.md` checkpoint | -| `notify.sh` | Notification | Notification event | Shows Windows toast notification via PowerShell | -| `session-stop.sh` | Stop | Session ends | Summarizes accomplishments and updates session log | -| `log-agent.sh` | SubagentStart | Agent spawned | Audit trail start — logs subagent invocation with timestamp | -| `log-agent-stop.sh` | SubagentStop | Agent stops | Audit trail stop — completes subagent record | -| `validate-skill-change.sh` | PostToolUse (Write/Edit) | Skill file changes | Advises running `/skill-test` after any `.opencode/skills/` file is written or edited | - -Hook reference documentation: `.opencode/docs/hooks-reference/` -Hook input schema documentation: `.opencode/docs/hooks-reference/hook-input-schemas.md` +All 12 bash hooks from CCGS are ported to a single TypeScript plugin +at **`.opencode/plugins/ccgs-hooks.ts`**. Hooks fire automatically +via OpenCode's plugin event system: + +| # | Original Hook | 🔌 OpenCode Event | 🧪 Tests | +|---|-----------|-------------------|:--------:| +| 1 | `session-start.sh` | `session.created` | **18** | +| 2 | `session-stop.sh` | `session.idle` / `server.instance.disposed` | **10** | +| 3 | `detect-gaps.sh` | `session.created` | **15** | +| 4 | `log-agent.sh` | `tool.execute.before` (task) | **5** | +| 5 | `log-agent-stop.sh` | `tool.execute.after` (task) | **4** | +| 6 | `validate-assets.sh` | `tool.execute.after` | **16** | +| 7 | `validate-commit.sh` | `tool.execute.before` (git commit) | **17** | +| 8 | `validate-push.sh` | `tool.execute.before` (git push) | **13** | +| 9 | `validate-skill-change.sh` | `tool.execute.after` | **12** | +| 10 | `pre-compact.sh` | `experimental.session.compacting` | **14** | +| 11 | `post-compact.sh` | `experimental.compaction.autocontinue` | **5** | +| 12 | `notify.sh` | Utility (`showNotification`) | — | + +## Running Tests + +Run a test suite against the hooks plugin: + +```bash +node .opencode/plugins/tests/test-.mjs +``` + +For example, to run the commit validation tests: + +```bash +node .opencode/plugins/tests/test-validate-commit.mjs +``` + +For a complete list of test suites, see the [README](/README.md#-hooks-plugin) Hooks Plugin section. diff --git a/.opencode/docs/hybrid-workflow.md b/.opencode/docs/hybrid-workflow.md new file mode 100644 index 0000000..9f005a4 --- /dev/null +++ b/.opencode/docs/hybrid-workflow.md @@ -0,0 +1,179 @@ +# Hybrid Discovery-Production Workflow + +## Overview + +This document defines a pragmatic hybrid workflow that balances **creative agility** during pre-production with **production discipline** once the game's direction is proven. It is designed for indie teams (1–5 people) who need to iterate quickly to find the fun, but still want professional-grade coordination when building the real thing. + +**When to use this workflow**: Small teams, unknown designs, short timelines (weeks to a few months), prototypes that may be pivoted or killed. + +**When to use the full OCGS workflow**: Large teams (5–15+), known designs, long timelines (6+ months), funded projects with publisher requirements. + +--- + +## Two-Phase Model + +The project lifecycle is split into two modes with **different rules**: + +| Dimension | Discovery | Production | +|-----------|-----------|------------| +| **Goal** | Find the fun | Ship a polished game | +| **Process overhead** | Low | High (full OCGS) | +| **Time to playable** | 2–4 days | 2–4 weeks planning first | +| **GDDs** | Quick-design / bullet points | Formal GDDs | +| **Architecture** | None | ADRs required | +| **Code location** | `prototypes/` | `src/` | +| **Tests** | Manual playtest only | Unit + integration + QA | +| **Sprint planning** | Weekly goals (informal) | Formal sprint plan | +| **Agents** | 4 core roles | 10 core roles | + +--- + +## Phase 1: Discovery (Pre-Production) + +### Goal +Answer one question per prototype: *Is this mechanic/system/fun?* + +### Rules +- **No formal GDDs.** Use `/quick-design` for lightweight specs, or bullet points in a markdown file. +- **No architecture.** Build throwaway scenes in `prototypes/`. +- **Minimal agents.** Only `creative-director`, `game-designer`, `prototyper`, and `godot-specialist` (or engine equivalent). +- **Time-boxed.** 2–4 weeks maximum per prototype. +- **Kill cheaply.** If it's not fun, pivot or scrap. No sunk-cost fallacy. + +### What NOT to do in Discovery +- Architecture Decision Records (ADRs) +- Epic/story breakdowns +- QA plans +- Asset pipeline setup +- Unit tests (prototypes are throwaway) +- Formal sprint plans + +### Deliverable +A working prototype that answers one core design question. + +--- + +## Phase 2: Production (Post-Prototype) + +### Goal +Build, polish, and ship the game with full quality gates. + +### Rules +- Use the existing OCGS framework, but with a **consolidated agent hierarchy** (see below). +- All changes require design review, architecture review, and QA sign-off. +- Code lives in `src/` with full coding standards. +- Every system has an ADR in `docs/architecture/`. +- Tests first for gameplay systems (TDD). + +### Slimmed Agent Hierarchy (49 → 10) + +| Tier | Role | Responsibilities | +|------|------|------------------| +| 1 | `creative-director` | Vision, final say on design | +| 1 | `technical-director` | Architecture, tech choices, code quality | +| 2 | `game-designer` | Core mechanics, balance, progression | +| 2 | `art-director` | Visual identity, asset specs | +| 2 | `lead-programmer` | Code review, task breakdown | +| 3 | `gameplay-programmer` | Player systems, combat, UI | +| 3 | `technical-artist` | Shaders, VFX, rendering pipeline | +| 3 | `qa-lead` | Test strategy, bug triage | +| 3 | `sound-designer` | Audio direction | +| 3 | `writer` | Narrative, lore, dialogue | + +> **Note**: The `producer` role is merged into `technical-director`. Cross-domain coordination falls to `technical-director` (sprint planning, milestone reviews, scope management). Gate checks and release coordination are shared with `creative-director`. Design conflicts escalate to `creative-director`. + +### Merged / Deferred Roles +The following roles from the full 49-agent roster are either merged into the 10 above, or deferred until late production: + +- `engine-programmer`, `tools-programmer` → `lead-programmer` +- `ai-programmer`, `network-programmer` → `gameplay-programmer` (until needed) +- `level-designer`, `world-builder` → `game-designer` +- `ui-programmer`, `ux-designer` → `gameplay-programmer` +- `economy-designer`, `systems-designer` → `game-designer` +- `performance-analyst` → `technical-artist` / `lead-programmer` +- `security-engineer`, `accessibility-specialist`, `live-ops-designer` → deferred until late production +- `community-manager`, `analytics-engineer`, `localization-lead` → post-launch only + +--- + +## Decision Gates + +| Gate | Trigger | Checks | +|------|---------|--------| +| **Prototype Gate** | 2–4 weeks or prototype complete | Is it fun? Is scope realistic? | +| **Production Gate** | Prototype approved | Is there a GDD? Is architecture defined? Is team staffed? | +| **Alpha Gate** | Core loop complete | Balance, performance, major bugs | +| **Ship Gate** | Content complete | QA sign-off, no critical bugs | + +**Removed gates** (vs. full OCGS): +- Full architecture review (lightweight ADR is enough) +- Complete epic/story breakdown before implementation +- Pre-commit architecture for every feature + +--- + +## The `/prototype` Fast Lane + +A new skill/command that shortcuts the path to a playable prototype: + +1. `creative-director` approves concept (informal/chat). +2. `prototyper` + `godot-specialist` build it. +3. Manual playtest. +4. `creative-director` + `game-designer` decide: **iterate**, **pivot**, or **productionize**. + +**Average time to playable**: 2–3 days instead of 2–3 weeks of planning. + +--- + +## Artifact Comparison + +| Artifact | Discovery | Production | +|----------|-----------|------------| +| Game concept doc | Informal (`design/concept.md`) | Formal GDDs | +| Architecture | None | ADRs required | +| Code | `prototypes/` | `src/` with standards | +| Tests | Manual playtest only | Unit + integration | +| Sprint plans | Weekly goals in chat | Formal sprint plan | +| QA | "Does it crash?" | Full QA plan | + +--- + +## When to Switch to Full OCGS + +Switch back to the **full 49-agent framework** if any of these become true: +- Team grows beyond 5 people +- Project timeline exceeds 6 months +- Multiple features need parallel development +- You need live ops, analytics, or multiplayer +- Funding/publisher requires formal process + +--- + +## Comparison + +| Aspect | Full OCGS | Hybrid | +|--------|-----------|--------| +| Time to first prototype | 2–4 weeks | 2–4 days | +| Process overhead (early) | High | Low | +| Coordination (late) | Excellent | Good | +| Team size | 5–15 | 1–5 | +| Best for | Known game, funded, long timeline | Unknown game, indie, iterating | + +--- + +## Migration Path + +If a project starts with the hybrid workflow and later needs the full OCGS framework: + +1. **Archive prototypes** to `prototypes/archive/`. +2. **Promote surviving designs** to formal GDDs in `design/`. +3. **Write ADRs** for the architecture of systems proven in prototypes. +4. **Recruit additional agents** from the full roster as needed. +5. **Switch to `src/`** with full coding standards. +6. **Enable all quality gates** from the full framework. + +--- + +## Notes + +This workflow is a **first-class citizen** of the OCGS framework, not a hack. All existing OCGS skills, gates, and documentation remain valid and are simply deferred to the Production phase. The `/prototype` skill is designed to integrate cleanly with the existing command structure. diff --git a/.opencode/docs/quick-start.md b/.opencode/docs/quick-start.md index 05381ea..56d3950 100644 --- a/.opencode/docs/quick-start.md +++ b/.opencode/docs/quick-start.md @@ -2,7 +2,7 @@ ## What Is This? -This is a complete Claude Code agent architecture for game development. It +This is a complete OpenCode agent architecture for game development. It organizes 48 specialized AI agents into a studio hierarchy that mirrors real game development teams, with defined responsibilities, delegation rules, and coordination protocols. It includes engine-specialist agents @@ -75,6 +75,7 @@ Ask yourself: "What department would handle this in a real studio?" | Command | What it does | |---------|-------------| +| `/init-template` | First-time repo setup — customizes the cloned template with your game identity, engine, and team preferences | | `/start` | First-time onboarding — asks where you are, guides you to the right workflow | | `/help` | Context-aware "what do I do next?" — reads your current phase and artifacts | | `/project-stage-detect` | Analyze project state, detect stage, identify gaps | @@ -210,27 +211,28 @@ If you already know what you need, jump directly to the relevant path: what excites you, what you've played, your constraints - Generates 3 concepts, helps you pick one, defines core loop and pillars - Produces a game concept document and recommends an engine -2. **Set up the engine** — Run `/setup-engine` (uses the brainstorm recommendation) +2. **Initialize your project** — Run `/init-template` to customize the template with your game name, engine, and clean out example files. +3. **Set up the engine** — Run `/setup-engine` (uses the brainstorm recommendation) - Configures CLAUDE.md, detects knowledge gaps, populates reference docs - Creates `.opencode/docs/technical-preferences.md` with naming conventions, performance budgets, and engine-specific defaults - If the engine version is newer than the LLM's training data, it fetches current docs from the web so agents suggest correct APIs -3. **Enhance with godot-mcp (Godot only)** — Install the optional MCP server +4. **Enhance with godot-mcp (Godot only)** — Install the optional MCP server for automated editor control and smoke testing: ```bash npx @coding-solo/godot-mcp ``` Once configured, run `/automated-smoke-test` to verify the project launches without errors. -4. **Validate the concept** — Run `/design-review design/gdd/game-concept.md` -5. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies -6. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`) +5. **Validate the concept** — Run `/design-review design/gdd/game-concept.md` +6. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies +7. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`) to write GDDs in dependency order -7. **Test the core loop** — Run `/prototype [core-mechanic]` -8. **Playtest it** — Run `/playtest-report` to validate the hypothesis -9. **Plan the first sprint** — Run `/sprint-plan new` -10. Start building +8. **Test the core loop** — Run `/prototype [core-mechanic]` +9. **Playtest it** — Run `/playtest-report` to validate the hypothesis +10. **Plan the first sprint** — Run `/sprint-plan new` +11. Start building ### Path B: "I know what I want to build" @@ -273,10 +275,10 @@ If you have design docs, prototypes, or code already: ``` AGENTS.md -- Master config (read this first) .opencode/ - config.json -- OpenCode settings and plugin configuration + (opencode.json at root) -- OpenCode settings and plugin configuration agents/ -- Agent definitions (YAML frontmatter) skills/ -- Skill definitions (YAML frontmatter) - hooks/ -- Hook scripts wired by config + plugins/ -- TypeScript hooks plugin (ccgs-hooks.ts) rules/ -- Path-specific rule files docs/ quick-start.md -- This file @@ -286,8 +288,6 @@ AGENTS.md -- Master config (read this first) context-management.md -- Context budgets and compaction instructions directory-structure.md -- Project directory layout workflow-catalog.yaml -- 7-phase pipeline definition (read by /help) - setup-requirements.md -- System prerequisites (Git Bash, jq, Python) - settings-local-template.md -- Personal settings.local.json guide + setup-requirements.md -- System prerequisites (Git, Node.js, OpenCode CLI) templates/ -- 37 document templates ``` - diff --git a/.opencode/docs/settings-local-template.md b/.opencode/docs/settings-local-template.md deleted file mode 100644 index 05f9f89..0000000 --- a/.opencode/docs/settings-local-template.md +++ /dev/null @@ -1,63 +0,0 @@ -# settings.local.json Template - -Create `.opencode/settings.local.json` for personal overrides that should NOT -be committed to version control. Add it to `.gitignore`. - -## Example settings.local.json - -```json -{ - "permissions": { - "allow": [ - "Bash(git *)", - "Bash(npm *)", - "Read", - "Glob", - "Grep" - ], - "deny": [ - "Bash(rm -rf *)", - "Bash(git push --force *)" - ] - } -} -``` - -## Permission Modes - -Claude Code supports different permission modes. Recommended for game dev: - -### During Development (Default) -Use **normal mode** — Claude asks before running most commands. This is safest -for production code. - -### During Prototyping -Use **auto-accept mode** with limited scope — faster iteration on throwaway code. -Only use this when working in `prototypes/` directory. - -### During Code Review -Use **read-only** permissions — Claude can read and search but not modify files. - -## Customizing Hooks Locally - -You can add personal hooks in `settings.local.json` that extend (not override) -the project hooks. For example, adding a notification when builds complete: - -```json -{ - "hooks": { - "Stop": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "bash -c 'echo Session ended at $(date)'", - "timeout": 5 - } - ] - } - ] - } -} -``` diff --git a/.opencode/docs/setup-requirements.md b/.opencode/docs/setup-requirements.md index af26058..ef3a3ee 100644 --- a/.opencode/docs/setup-requirements.md +++ b/.opencode/docs/setup-requirements.md @@ -4,54 +4,52 @@ This template requires a few tools to be installed for full functionality. All hooks fail gracefully if tools are missing — nothing will break, but you'll lose validation features. +> **New projects:** After cloning this template, run `/init-template` before anything else. It customizes the template with your game name, engine choice, and team preferences, and cleans out example files. + ## Required | Tool | Purpose | Install | | ---- | ---- | ---- | | **Git** | Version control, branch management | [git-scm.com](https://git-scm.com/) | -| **Claude Code** | AI agent CLI | `npm install -g @anthropic-ai/claude-code` | +| **OpenCode** | AI agent CLI | `npm install -g opencode` | ## Recommended | Tool | Used By | Purpose | Install | | ---- | ---- | ---- | ---- | -| **jq** | Hooks (4 of 8) | JSON parsing in commit/push/asset/agent hooks | See below | -| **Python 3** | Hooks (2 of 8) | JSON validation for data files | [python.org](https://www.python.org/) | -| **Bash** | All hooks | Shell script execution | Included with Git for Windows | +| **Node.js 18+** | Hooks plugin | Runtime for the CCGS TypeScript hooks plugin | [nodejs.org](https://nodejs.org/) | -### Installing jq +### Installing Node.js **Windows** (any of these): ``` -winget install jqlang.jq -choco install jq -scoop install jq +winget install OpenJS.NodeJS.LTS +choco install nodejs-lts +scoop install nodejs ``` **macOS**: ``` -brew install jq +brew install node ``` **Linux**: ``` -sudo apt install jq # Debian/Ubuntu -sudo dnf install jq # Fedora -sudo pacman -S jq # Arch +sudo apt install nodejs npm # Debian/Ubuntu +sudo dnf install nodejs # Fedora +sudo pacman -S nodejs npm # Arch ``` ## Platform Notes ### Windows -- Git for Windows includes **Git Bash**, which provides the `bash` command - used by all hooks in `settings.json` +- Git for Windows includes **Git Bash**, which provides `bash` - Ensure Git Bash is on your PATH (default if installed via the Git installer) -- Hooks use `bash .opencode/hooks/[name].sh` — this works on Windows because - Claude Code invokes commands through a shell that can find `bash.exe` +- OpenCode runs natively in PowerShell, CMD, Git Bash, and Windows Terminal ### macOS / Linux -- Bash is available natively -- Install `jq` via your package manager for full hook support +- Node.js and npm are available via your package manager +- OpenCode works in any standard terminal ## Verifying Your Setup @@ -59,25 +57,23 @@ Run these commands to check prerequisites: ```bash git --version # Should show git version -bash --version # Should show bash version -jq --version # Should show jq version (optional) -python3 --version # Should show python version (optional) +node --version # Should show Node.js 18+ +npx opencode --version # Should show OpenCode version ``` ## What Happens Without Optional Tools | Missing Tool | Effect | | ---- | ---- | -| **jq** | Commit validation, push protection, asset validation, and agent audit hooks silently skip their checks. Commits and pushes still work. | -| **Python 3** | JSON data file validation in commit and asset hooks is skipped. Invalid JSON can be committed without warning. | -| **Both** | All hooks still execute without error (exit 0) but provide no validation. You're flying without safety nets. | +| **Node.js** | The hooks plugin (`ccgs-hooks.ts`) cannot execute. All hook events silently pass through. Commits, pushes, and all other operations still work. | ## Recommended IDE -Claude Code works with any editor, but the template is optimized for: -- **VS Code** with the Claude Code extension -- **Cursor** (Claude Code compatible) -- Terminal-based Claude Code CLI +OpenCode works with any editor: +- **VS Code** with the OpenCode CLI +- **Cursor** (OpenCode compatible) +- **Terminal** — `opencode` CLI directly in any shell +- **JetBrains IDEs** — via the terminal ## Optional Engine Dependencies diff --git a/.opencode/docs/skills-reference.md b/.opencode/docs/skills-reference.md index 8b54526..0a8c8db 100644 --- a/.opencode/docs/skills-reference.md +++ b/.opencode/docs/skills-reference.md @@ -6,6 +6,7 @@ | Command | Purpose | |---------|---------| +| `/init-template` | First-time repo setup. Customizes the cloned template with your game identity, engine, and team preferences. | | `/start` | First-time onboarding — asks where you are, then guides you to the right workflow | | `/help` | Context-aware "what do I do next?" — reads current stage and surfaces the required next step | | `/project-stage-detect` | Full project audit — detect phase, identify existence gaps, recommend next steps | @@ -108,6 +109,7 @@ | Command | Purpose | |---------|---------| | `/prototype` | Rapid throwaway prototype to validate a mechanic (relaxed standards, isolated worktree) | +| `/hybrid-prototype` | Fast-lane prototype for discovery phase — 2-3 day build, no formal gates, lightweight DECISION.md | | `/onboard` | Generate contextual onboarding document for a new contributor or agent | | `/localize` | Localization workflow: string extraction, validation, translation readiness | diff --git a/.opencode/docs/templates/collaborative-protocols/design-agent-protocol.md b/.opencode/docs/templates/collaborative-protocols/design-agent-protocol.md index c9d7460..6ac2d4c 100644 --- a/.opencode/docs/templates/collaborative-protocols/design-agent-protocol.md +++ b/.opencode/docs/templates/collaborative-protocols/design-agent-protocol.md @@ -16,14 +16,14 @@ Before proposing any design: - What are the constraints (scope, complexity, existing systems)? - Any reference games or mechanics the user loves/hates? - How does this connect to the game's pillars? - - *Use `AskUserQuestion` to batch up to 4 constrained questions at once* + - *Use `question` to batch up to 4 constrained questions at once* 2. **Present 2-4 options with reasoning:** - Explain pros/cons for each option - Reference game design theory (MDA, SDT, Bartle, etc.) - Align each option with the user's stated goals - Make a recommendation, but explicitly defer the final decision to the user - - *After the full explanation, use `AskUserQuestion` to capture the decision* + - *After the full explanation, use `question` to capture the decision* 3. **Draft based on user's choice:** - Create sections iteratively (show one section, get feedback, refine) @@ -33,7 +33,7 @@ Before proposing any design: 4. **Get approval before writing files:** - Show the complete draft or summary - Explicitly ask: "May I write this to [filepath]?" - - Wait for "yes" before using Write/Edit tools + - Wait for "yes" before using write and edit tools - If user says "no" or "change X", iterate and return to step 3 #### Example Interaction Pattern @@ -107,27 +107,27 @@ You: [uses Write tool] #### Structured Decision UI -Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of +Use the `question` tool to present decisions as a selectable UI instead of plain text. Follow the **Explain → Capture** pattern: 1. **Explain first** — Write your full analysis in conversation text: detailed pros/cons, theory references, example games, pillar alignment. This is where the expert reasoning lives — don't try to fit it into the tool. -2. **Capture the decision** — Call `AskUserQuestion` with concise option labels +2. **Capture the decision** — Call `question` with concise option labels and short descriptions. The user picks from the UI or types a custom answer. **When to use it:** - Every decision point where you present 2-4 options (step 2) - Initial clarifying questions that have constrained answers (step 1) -- Batch up to 4 independent questions in a single `AskUserQuestion` call +- Batch up to 4 independent questions in a single `question` call - Next-step choices ("Draft formulas section or refine rules first?") **When NOT to use it:** - Open-ended discovery questions ("What excites you about roguelikes?") - Single yes/no confirmations ("May I write to file?") - When running as a Task subagent (tool may not be available) — structure your - text output so the orchestrator can present options via AskUserQuestion + text output so the orchestrator can present options via question **Format guidelines:** - Labels: 1-5 words (e.g., "Hybrid Discovery", "Full Randomized") @@ -137,7 +137,7 @@ plain text. Follow the **Explain → Capture** pattern: **Example — multi-question batch for clarifying questions:** - AskUserQuestion with questions: + question with questions: 1. question: "Should crafting recipes be discovered or learned?" header: "Discovery" options: "Experimentation", "NPC/Book Learning", "Tiered Hybrid" @@ -147,7 +147,7 @@ plain text. Follow the **Explain → Capture** pattern: **Example — capturing a design decision (after full analysis in conversation):** - AskUserQuestion with questions: + question with questions: 1. question: "Which crafting approach fits your vision?" header: "Approach" options: diff --git a/.opencode/docs/templates/collaborative-protocols/implementation-agent-protocol.md b/.opencode/docs/templates/collaborative-protocols/implementation-agent-protocol.md index 3ea80e7..e3bebad 100644 --- a/.opencode/docs/templates/collaborative-protocols/implementation-agent-protocol.md +++ b/.opencode/docs/templates/collaborative-protocols/implementation-agent-protocol.md @@ -21,7 +21,7 @@ Before writing any code: - "Where should [data] live? (CharacterStats? Equipment class? Config file?)" - "The design doc doesn't specify [edge case]. What should happen when...?" - "This will require changes to [other system]. Should I coordinate with that first?" - - *Use `AskUserQuestion` to batch constrained architecture questions* + - *Use `question` to batch constrained architecture questions* 3. **Propose architecture before implementing:** - Show class structure, file organization, data flow @@ -38,7 +38,7 @@ Before writing any code: - Show the code or a detailed summary - Explicitly ask: "May I write this to [filepath(s)]?" - For multi-file changes, list all affected files - - Wait for "yes" before using Write/Edit tools + - Wait for "yes" before using write and edit tools 6. **Complete the story with `/story-done`:** - When implementation (and tests, if written) is complete, invoke `/story-done [story-file-path]` @@ -129,12 +129,12 @@ You: [creates tests/combat/test_damage_calculator.gd] #### Structured Decision UI -Use the `AskUserQuestion` tool for architecture decisions and next-step choices. +Use the `question` tool for architecture decisions and next-step choices. Follow the **Explain → Capture** pattern: 1. **Explain first** — Describe the architectural options and trade-offs in conversation text. -2. **Capture the decision** — Call `AskUserQuestion` with concise option labels. +2. **Capture the decision** — Call `question` with concise option labels. **When to use it:** - Architecture questions with constrained answers (step 2) @@ -148,7 +148,7 @@ Follow the **Explain → Capture** pattern: **Example — architecture questions (batch):** - AskUserQuestion with questions: + question with questions: 1. question: "Where should DamageCalculator live?" header: "Architecture" options: "Static Utility (Recommended)", "Autoload Singleton", "Scene Node" diff --git a/.opencode/docs/templates/collaborative-protocols/leadership-agent-protocol.md b/.opencode/docs/templates/collaborative-protocols/leadership-agent-protocol.md index 72e36c8..3b7b6e0 100644 --- a/.opencode/docs/templates/collaborative-protocols/leadership-agent-protocol.md +++ b/.opencode/docs/templates/collaborative-protocols/leadership-agent-protocol.md @@ -15,7 +15,7 @@ When the user asks you to make a decision or resolve a conflict: - Ask questions to understand all perspectives - Review relevant docs (pillars, constraints, prior decisions) - Identify what's truly at stake (often deeper than the surface question) - - *Use `AskUserQuestion` to batch up to 4 constrained questions at once* + - *Use `question` to batch up to 4 constrained questions at once* 2. **Frame the decision:** - State the core question clearly @@ -29,7 +29,7 @@ When the user asks you to make a decision or resolve a conflict: - Downstream consequences (technical, creative, schedule, scope) - Risks and mitigation strategies - Real-world examples (how other games handled similar decisions) - - *After the full analysis, use `AskUserQuestion` to capture the decision* + - *After the full analysis, use `question` to capture the decision* 4. **Make a clear recommendation:** - "I recommend Option [X] because..." @@ -146,13 +146,13 @@ You: [Creates ADR, updates docs, notifies relevant agents] #### Structured Decision UI -Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI. +Use the `question` tool to present strategic decisions as a selectable UI. Follow the **Explain → Capture** pattern: 1. **Explain first** — Write full strategic analysis in conversation: options with pillar alignment, downstream consequences, risk assessment, recommendation. -2. **Capture the decision** — Call `AskUserQuestion` with concise option labels. +2. **Capture the decision** — Call `question` with concise option labels. **When to use it:** - Every strategic decision point (options in step 3, context questions in step 1) @@ -171,7 +171,7 @@ Follow the **Explain → Capture** pattern: **Example — strategic decision (after full analysis in conversation):** - AskUserQuestion with questions: + question with questions: 1. question: "How should we handle crafting scope for Alpha?" header: "Scope" options: diff --git a/.opencode/skills/hybrid-prototype/SKILL.md b/.opencode/skills/hybrid-prototype/SKILL.md new file mode 100644 index 0000000..83f8ad0 --- /dev/null +++ b/.opencode/skills/hybrid-prototype/SKILL.md @@ -0,0 +1,150 @@ +--- +name: hybrid-prototype +description: "Fast-lane prototype skill for the hybrid workflow. Builds a playable prototype in 2-3 days with minimal process overhead. Designed for discovery phase." +argument-hint: "[concept-description]" +user-invocable: true +allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task +agent: prototyper +isolation: worktree +--- + +## Overview + +This skill implements the **Discovery Phase fast lane** as described in `.opencode/docs/hybrid-workflow.md`. It is intentionally lightweight: no formal GDD, no architecture, no epic breakdown. Just build it, play it, decide. + +**Time budget**: 1-3 days. +**Agents involved**: `creative-director`, `game-designer`, `prototyper`, `godot-specialist` (or engine equivalent). + +--- + +## Phase 1: Concept & Question (5 minutes) + +Read the concept description from the argument. State the **one core question** this prototype must answer. If the concept is vague, ask the user to clarify before proceeding. + +Examples of good questions: +- "Does the combat feel responsive with 200ms input lag?" +- "Is resource scarcity actually fun, or just frustrating?" +- "Does the movement mechanic support the intended platforming challenges?" + +Bad question: "Is this game fun?" (Too broad. Narrow it down.) + +**Ask the user**: "The core question for this prototype is: [question]. Proceed?" + +--- + +## Phase 2: Plan (15 minutes) + +Define the minimum viable prototype in 3-5 bullet points: + +- What is the absolute minimum code to answer the question? +- What can be hardcoded / placeholder / skipped? +- What is the success criteria? (e.g., "Player can complete 3 jumps in a row without dying") + +**Present the plan to the user and ask for confirmation.** + +--- + +## Phase 3: Build (1-2 days) + +**Ask**: "May I create the prototype directory at `prototypes/[concept-name]/` and begin implementation?" + +If yes, create the directory. Every file must begin with: + +``` +// PROTOTYPE - NOT FOR PRODUCTION +// Question: [Core question being tested] +// Date: [Current date] +``` + +**Rules for prototype code**: +- Hardcode values freely +- Use placeholder assets (colored squares, simple shapes) +- Skip error handling +- Use the simplest approach that works +- Copy code rather than importing from production +- NEVER import from `src/` — prototypes are isolated + +**Run the prototype** as you build. Test continuously. Fix blockers, but don't polish. + +--- + +## Phase 4: Playtest (2-4 hours) + +Play the prototype yourself. Then ask the user to play it. Collect observations: + +- What worked? +- What felt bad? +- Did it answer the core question? +- Any surprising discoveries? + +**Document findings informally** — a bulleted list is fine. + +--- + +## Phase 5: Decide (30 minutes) + +Collaborate with `creative-director` and `game-designer` (via Task or conversation) to make a decision: + +| Verdict | Meaning | Next Step | +|---------|---------|-----------| +| **ITERATE** | Core is promising, but needs adjustment | Run `/hybrid-prototype [revised-concept]` | +| **PIVOT** | The concept doesn't work, but a related one might | Run `/brainstorm` or `/hybrid-prototype [new-direction]` | +| **PRODUCTIONIZE** | It's fun and proven — move to production | Begin GDD in `/design-system`, architecture in `/create-architecture` | +| **KILL** | It's not fun and no clear fix | Stop. The prototype report is the deliverable. | + +**Update `prototypes/[concept-name]/DECISION.md`** with: + +```markdown +# Prototype Decision: [Concept Name] + +## Question +[Core question] + +## Result +[What happened] + +## Verdict +[ITERATE / PIVOT / PRODUCTIONIZE / KILL] + +## Reasoning +[Why] + +## Next Steps +[What to do next] +``` + +**Ask**: "May I write the decision to `prototypes/[concept-name]/DECISION.md`?" + +--- + +## Phase 6: Done + +Output a summary to the user: the core question, the verdict, and the next step. + +If **PRODUCTIONIZE**: remind them to switch to the Production phase workflow (`/design-system`, `/create-architecture`, etc.) + +If **ITERATE / PIVOT / KILL**: no further action needed. + +--- + +## Constraints + +- Prototype code must NEVER import from production source files +- Production code must NEVER import from prototype directories +- If productionizing, rewrite from scratch — do not refactor prototype code +- Timebox strictly: if it's not working after 3 days, kill or pivot +- Keep the question narrow — one prototype, one question +- **Workflow isolation**: This skill explicitly bypasses `production/review-mode.txt`. Any stale review-mode state from a previous full OCGS session is ignored — the hybrid fast lane always runs without formal gates. + +--- + +## Differences from Full `/prototype` Skill + +| Aspect | `/prototype` (Full OCGS) | `/hybrid-prototype` (Fast Lane) | +|--------|--------------------------|----------------------------------| +| Review mode gates | Solo / Lean / Full | None (always fast) | +| Creative Director review | Formal gate spawn | Informal chat/Task | +| Report format | Formal `REPORT.md` | Lightweight `DECISION.md` | +| Agents involved | All tiers | 4 core roles only | +| Time to verdict | 1-3 days + review overhead | 1-3 days total | +| Next step on PROCEED | Formal GDD + ADR | Start GDD when ready | diff --git a/.opencode/skills/init-template/SKILL.md b/.opencode/skills/init-template/SKILL.md new file mode 100644 index 0000000..3b5e0ed --- /dev/null +++ b/.opencode/skills/init-template/SKILL.md @@ -0,0 +1,123 @@ +--- +name: init-template +description: "First-time repo setup for new projects. Transforms the cloned OCGS template into a clean, ready-to-use game project with your own identity." +argument-hint: "[--reset-git] [--name \"My Game\"] [--engine godot|unity|unreal]" +user-invocable: true +allowed-tools: Read, Glob, Grep, Write, Edit, Bash, question, Task +--- + +When this skill is invoked: + +## Phase 1: Parse Arguments + +Check if CLI arguments were passed (from `argument-hint`): + +- `--name "My Game"` → sets game name (skips the name question below) +- `--engine godot|unity|unreal` → sets engine (skips engine question) +- `--reset-git` → automatically offers git reset (skips the prompt) + +If `--name` and `--engine` are both provided, skip the interactive prompt entirely and proceed to Phase 2 using the provided values. + +Otherwise, use `question` to gather missing details: + +### Tab 1: Project Identity +- **What is your game's name?** (e.g., "My Game") +- **What is your game's one-line description?** (e.g., "A 2D platformer about a cat in space") + +### Tab 2: Engine & Genre +- **Which engine are you using?** (godot / unity / unreal) +- **What genre best describes your game?** (e.g., platformer, RPG, puzzle, FPS, strategy) + +### Tab 3: Team +- **Team size** (solo / small 2-5 / medium 6-15 / large 16+) +- **Preferred model tier** (default / workhorse / lightweight) — refer to the README's Model Mapping section for options + +## Phase 2: Replace README.md + +Write a fresh README.md to the project root. Use a template structure like: + +```markdown +# [Game Name] + +> [One-line description] + +Built with [Engine] using [OpenCode Game Studios](https://github.com/striderZA/OpenCodeGameStudios). + +## Quick Start + +```bash +opencode +``` + +Type `/start` for onboarding, or browse all skills with `/`. + +## Project Structure + +``` +/ +├── src/ # Game source code +├── assets/ # Game assets (art, audio, vfx) +├── design/ # Game design documents +├── docs/ # Technical documentation +└── production/ # Sprint plans, session logs +``` + +## License + +[Choose a license] +``` + +Replace `[Game Name]`, `[One-line description]`, and `[Engine]` with the user's answers from Phase 1. + +## Phase 3: Update AGENTS.md + +Read AGENTS.md and update: +- Set the engine to the user's choice by changing the `## Technology Stack` section +- Update the model assignment: replace the model table with the user's preference (default/workhorse/lightweight), mapping to their engine's specialist agents +- Remove or update any project-specific settings +- If AGENTS.md is missing or malformed, warn and skip this phase + +## Phase 4: Update opencode.json + +Read opencode.json and clean it up: +- Remove any internal-only plugin paths +- Set project name appropriately +- Keep the ccgs-hooks.ts plugin reference only if the file actually exists: `if [ -f .opencode/plugins/ccgs-hooks.ts ]; then ...` +- If opencode.json is missing or malformed, warn and skip this phase + +## Phase 5: Remove Internal Files + +For each file/directory below, check existence first before deleting. If the directory already has user-created content, warn and skip rather than destroying it: + +- `rm -f UPGRADING.md CONTRIBUTING.md SECURITY.md CODE_OF_CONDUCT.md` +- Clear `design/` contents only if empty of user files: `if ls design/*.md >/dev/null 2>&1; then echo "WARNING: design/ has content, skipping"; else rm -rf design/*; fi` +- Clear `src/` contents only if empty of user files: `if ls src/*.gd src/*.cs src/*.cpp src/*.ts >/dev/null 2>&1; then echo "WARNING: src/ has code files, skipping"; else rm -rf src/* && touch src/.gitkeep; fi` +- Clear `production/` contents only if empty of user files: similar guard +- On any error (file locked, permission denied), warn and continue to next item + +## Phase 6: Optional Git Reset + +If the user selected `--reset-git` or agrees when prompted: +- Offer to reset git history to a single commit +- `git checkout --orphan fresh-root` +- `git add -A` +- `git commit -m "Initial commit: scaffolded from OpenCode Game Studios template"` +- Delete all old tags (optional) — warn: if tags were previously pushed to remote, deletion requires `git push origin --delete ` for each one +- Force push if needed (warn: this rewrites remote history for anyone who has cloned this repo) + +## Phase 7: Summary + +Print a completion summary: + +``` +✅ Template initialized + + Project: [Game Name] + Engine: [Engine] + Team: [Size] + + What's next: + - Run /setup-engine [engine] to configure your engine docs + - Run /brainstorm to start designing your game concept + - Run /start for guided onboarding +``` diff --git a/AGENTS.md b/AGENTS.md index e033c38..6dc3faa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,6 +90,23 @@ after each significant milestone: The state file should contain: current task, progress checklist, key decisions made, files being worked on, and open questions. +## Workflow Modes + +This project supports two workflow modes. Choose the one that fits your team size and project maturity: + +### Hybrid Workflow (Recommended for Indie Teams) + +- **Discovery Phase**: Rapid prototyping to find the fun. Low process overhead, minimal agents, throwaway code in `prototypes/`. +- **Production Phase**: Full OCGS discipline once the design is proven. Formal GDDs, ADRs, tests, and quality gates. +- **Best for**: Teams of 1–5, unknown designs, iterating to find the fun. +- **See**: `docs/hybrid-workflow.md` for full details. + +### Full OCGS Workflow + +- **All phases formal**: Every feature goes through design → architecture → stories → code → tests → review. +- **Best for**: Teams of 5–15, known designs, long timelines, publisher requirements. +- **See**: Full documentation in `docs/` and `.opencode/skills/`. + ## Getting Started Run `/start` in OpenCode to begin the guided onboarding flow. @@ -97,10 +114,12 @@ Or jump directly to: - `/brainstorm` — explore game ideas from scratch - `/setup-engine godot 4.6` — configure your engine - `/project-stage-detect` — analyze an existing project +- `/prototype` — rapid prototype a concept +- `/hybrid-prototype` — fast-lane prototype for discovery phase ## Available Commands -Type `/` in OpenCode to see all 72 commands. Key categories: +Type `/` in OpenCode to see all available commands. Key categories: - **Onboarding**: `/start`, `/help`, `/project-stage-detect`, `/setup-engine` - **Design**: `/brainstorm`, `/map-systems`, `/design-system`, `/quick-design` @@ -108,6 +127,7 @@ Type `/` in OpenCode to see all 72 commands. Key categories: - **Stories**: `/create-epics`, `/create-stories`, `/dev-story`, `/sprint-plan` - **Reviews**: `/design-review`, `/code-review`, `/balance-check`, `/gate-check` - **QA**: `/qa-plan`, `/smoke-check`, `/soak-test`, `/regression-suite` +- **Prototyping**: `/prototype`, `/hybrid-prototype` - **Team**: `/team-combat`, `/team-narrative`, `/team-ui`, `/team-release` ## Studio Hierarchy diff --git a/docs/hybrid-workflow.md b/docs/hybrid-workflow.md new file mode 100644 index 0000000..cd08497 --- /dev/null +++ b/docs/hybrid-workflow.md @@ -0,0 +1,179 @@ +# Hybrid Discovery-Production Workflow + +## Overview + +This document defines a pragmatic hybrid workflow that balances **creative agility** during pre-production with **production discipline** once the game's direction is proven. It is designed for indie teams (1–5 people) who need to iterate quickly to find the fun, but still want professional-grade coordination when building the real thing. + +**When to use this workflow**: Small teams, unknown designs, short timelines (weeks to a few months), prototypes that may be pivoted or killed. + +**When to use the full OCGS workflow**: Large teams (5–15+), known designs, long timelines (6+ months), funded projects with publisher requirements. + +--- + +## Two-Phase Model + +The project lifecycle is split into two modes with **different rules**: + +| Dimension | Discovery | Production | +|-----------|-----------|------------| +| **Goal** | Find the fun | Ship a polished game | +| **Process overhead** | Low | High (full OCGS) | +| **Time to playable** | 2–4 days | 2–4 weeks planning first | +| **GDDs** | Quick-design / bullet points | Formal GDDs | +| **Architecture** | None | ADRs required | +| **Code location** | `prototypes/` | `src/` | +| **Tests** | Manual playtest only | Unit + integration + QA | +| **Sprint planning** | Weekly goals (informal) | Formal sprint plan | +| **Agents** | 4 core roles | 10 core roles | + +--- + +## Phase 1: Discovery (Pre-Production) + +### Goal +Answer one question per prototype: *Is this mechanic/system/fun?* + +### Rules +- **No formal GDDs.** Use `/quick-design` for lightweight specs, or bullet points in a markdown file. +- **No architecture.** Build throwaway scenes in `prototypes/`. +- **Minimal agents.** Only `creative-director`, `game-designer`, `prototyper`, and `godot-specialist` (or engine equivalent). +- **Time-boxed.** 2–4 weeks maximum per prototype. +- **Kill cheaply.** If it's not fun, pivot or scrap. No sunk-cost fallacy. + +### What NOT to do in Discovery +- Architecture Decision Records (ADRs) +- Epic/story breakdowns +- QA plans +- Asset pipeline setup +- Unit tests (prototypes are throwaway) +- Formal sprint plans + +### Deliverable +A working prototype that answers one core design question. + +--- + +## Phase 2: Production (Post-Prototype) + +### Goal +Build, polish, and ship the game with full quality gates. + +### Rules +- Use the existing OCGS framework, but with a **consolidated agent hierarchy** (see below). +- All changes require design review, architecture review, and QA sign-off. +- Code lives in `src/` with full coding standards. +- Every system has an ADR in `docs/architecture/`. +- Tests first for gameplay systems (TDD). + +### Slimmed Agent Hierarchy (49 → 10) + +| Tier | Role | Responsibilities | +|------|------|------------------| +| 1 | `creative-director` | Vision, final say on design | +| 1 | `technical-director` | Architecture, tech choices, code quality | +| 2 | `game-designer` | Core mechanics, balance, progression | +| 2 | `art-director` | Visual identity, asset specs | +| 2 | `lead-programmer` | Code review, task breakdown | +| 3 | `gameplay-programmer` | Player systems, combat, UI | +| 3 | `technical-artist` | Shaders, VFX, rendering pipeline | +| 3 | `qa-lead` | Test strategy, bug triage | +| 3 | `sound-designer` | Audio direction | +| 3 | `writer` | Narrative, lore, dialogue | + +> **Note**: The `producer` role is merged into `technical-director`. Cross-domain coordination falls to `technical-director` (sprint planning, milestone reviews, scope management). Gate checks and release coordination are shared with `creative-director`. Design conflicts escalate to `creative-director`. + +### Merged / Deferred Roles +The following roles from the full 49-agent roster are either merged into the 10 above, or deferred until late production: + +- `engine-programmer`, `tools-programmer` → `lead-programmer` +- `ai-programmer`, `network-programmer` → `gameplay-programmer` (until needed) +- `level-designer`, `world-builder` → `game-designer` +- `ui-programmer`, `ux-designer` → `gameplay-programmer` +- `economy-designer`, `systems-designer` → `game-designer` +- `performance-analyst` → `technical-artist` / `lead-programmer` +- `security-engineer`, `accessibility-specialist`, `live-ops-designer` → deferred until late production +- `community-manager`, `analytics-engineer`, `localization-lead` → post-launch only + +--- + +## Decision Gates + +| Gate | Trigger | Checks | +|------|---------|--------| +| **Prototype Gate** | 2–4 weeks or prototype complete | Is it fun? Is scope realistic? | +| **Production Gate** | Prototype approved | Is there a GDD? Is architecture defined? Is team staffed? | +| **Alpha Gate** | Core loop complete | Balance, performance, major bugs | +| **Ship Gate** | Content complete | QA sign-off, no critical bugs | + +**Removed gates** (vs. full OCGS): +- Full architecture review (lightweight ADR is enough) +- Complete epic/story breakdown before implementation +- Pre-commit architecture for every feature + +--- + +## The `/hybrid-prototype` Fast Lane + +A new skill/command that shortcuts the path to a playable prototype: + +1. `creative-director` approves concept (informal/chat). +2. `prototyper` + `godot-specialist` build it. +3. Manual playtest. +4. `creative-director` + `game-designer` decide: **iterate**, **pivot**, or **productionize**. + +**Average time to playable**: 2–3 days instead of 2–3 weeks of planning. + +--- + +## Artifact Comparison + +| Artifact | Discovery | Production | +|----------|-----------|------------| +| Game concept doc | Informal (`design/concept.md`) | Formal GDDs | +| Architecture | None | ADRs required | +| Code | `prototypes/` | `src/` with standards | +| Tests | Manual playtest only | Unit + integration | +| Sprint plans | Weekly goals in chat | Formal sprint plan | +| QA | "Does it crash?" | Full QA plan | + +--- + +## When to Switch to Full OCGS + +Switch back to the **full 49-agent framework** if any of these become true: +- Team grows beyond 5 people +- Project timeline exceeds 6 months +- Multiple features need parallel development +- You need live ops, analytics, or multiplayer +- Funding/publisher requires formal process + +--- + +## Comparison + +| Aspect | Full OCGS | Hybrid | +|--------|-----------|--------| +| Time to first prototype | 2–4 weeks | 2–4 days | +| Process overhead (early) | High | Low | +| Coordination (late) | Excellent | Good | +| Team size | 5–15 | 1–5 | +| Best for | Known game, funded, long timeline | Unknown game, indie, iterating | + +--- + +## Migration Path + +If a project starts with the hybrid workflow and later needs the full OCGS framework: + +1. **Archive prototypes** to `prototypes/archive/`. +2. **Promote surviving designs** to formal GDDs in `design/`. +3. **Write ADRs** for the architecture of systems proven in prototypes. +4. **Recruit additional agents** from the full roster as needed. +5. **Switch to `src/`** with full coding standards. +6. **Enable all quality gates** from the full framework. + +--- + +## Notes + +This workflow is a **first-class citizen** of the OCGS framework, not a hack. All existing OCGS skills, gates, and documentation remain valid and are simply deferred to the Production phase. The `/hybrid-prototype` skill is designed to integrate cleanly with the existing command structure. diff --git a/opencode.json b/opencode.json index 5dad018..d10ae6a 100644 --- a/opencode.json +++ b/opencode.json @@ -1,6 +1,13 @@ { "$schema": "https://opencode.ai/config.json", "plugin": ["./.opencode/plugins/ccgs-hooks.ts"], + "command": { + "hybrid-prototype": { + "template": "Run the hybrid-prototype skill: load .opencode/skills/hybrid-prototype/SKILL.md and follow the fast-lane prototype workflow. Concept: $ARGUMENTS", + "description": "Fast-lane prototype for discovery phase — build a playable prototype in 2-3 days with minimal process overhead.", + "agent": "prototyper" + } + }, "permission": { "bash": { "git status*": "allow", diff --git a/prototypes/.gitkeep b/prototypes/.gitkeep new file mode 100644 index 0000000..e69de29