diff --git a/.opencode/docs/skills-reference.md b/.opencode/docs/skills-reference.md index 8d8bf99..2d3ab60 100644 --- a/.opencode/docs/skills-reference.md +++ b/.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 | diff --git a/.opencode/skills/hybrid-prototype/SKILL.md b/.opencode/skills/hybrid-prototype/SKILL.md new file mode 100644 index 0000000..53c5dd5 --- /dev/null +++ b/.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 | 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