v0.3.2 — Hybrid workflow, init-template, Godot MCP, docs cleanup

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

.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
 

.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

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

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