fix: Complete hybrid workflow documentation gaps (#30)

.opencode/docs/skills-reference.md

@@ -21,6 +21,7 @@
 | `/map-systems` | Decompose game concept into systems, map dependencies, prioritize design order |
 | `/design-system` | Guided, section-by-section GDD authoring for a single game system |
 | `/quick-design` | Lightweight design spec for small changes — tuning, tweaks, minor additions |
+| `/hybrid-prototype` | Fast-lane prototype for hybrid workflow — build, playtest, and decide in 2-3 days |
 | `/review-all-gdds` | Cross-GDD consistency and game design holism review across all design docs |
 | `/propagate-design-change` | When a GDD is revised, find affected ADRs and produce an impact report |
 

.opencode/skills/hybrid-prototype/SKILL.md

@@ -0,0 +1,148 @@
+---
+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** from `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`. If the session previously ran the full OCGS workflow, any stale review-mode state 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 |

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.

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