v0.3.1 — init-template skill + 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/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
 ```
-

.opencode/docs/setup-requirements.md

@@ -4,80 +4,76 @@ 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
 
 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