Skip to content

Commit 50857de

Browse files
striderZAstriderZA
authored
v0.3.2 — Hybrid workflow, init-template, Godot MCP, docs cleanup
Milestone v0.3.2
1 parent cb1f933 commit 50857de

7 files changed

Lines changed: 537 additions & 1 deletion

File tree

‎.opencode/docs/hybrid-workflow.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Hybrid Discovery-Production Workflow
2+
3+
## Overview
4+
5+
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.
6+
7+
**When to use this workflow**: Small teams, unknown designs, short timelines (weeks to a few months), prototypes that may be pivoted or killed.
8+
9+
**When to use the full OCGS workflow**: Large teams (5–15+), known designs, long timelines (6+ months), funded projects with publisher requirements.
10+
11+
---
12+
13+
## Two-Phase Model
14+
15+
The project lifecycle is split into two modes with **different rules**:
16+
17+
| Dimension | Discovery | Production |
18+
|-----------|-----------|------------|
19+
| **Goal** | Find the fun | Ship a polished game |
20+
| **Process overhead** | Low | High (full OCGS) |
21+
| **Time to playable** | 2–4 days | 2–4 weeks planning first |
22+
| **GDDs** | Quick-design / bullet points | Formal GDDs |
23+
| **Architecture** | None | ADRs required |
24+
| **Code location** | `prototypes/` | `src/` |
25+
| **Tests** | Manual playtest only | Unit + integration + QA |
26+
| **Sprint planning** | Weekly goals (informal) | Formal sprint plan |
27+
| **Agents** | 4 core roles | 10 core roles |
28+
29+
---
30+
31+
## Phase 1: Discovery (Pre-Production)
32+
33+
### Goal
34+
Answer one question per prototype: *Is this mechanic/system/fun?*
35+
36+
### Rules
37+
- **No formal GDDs.** Use `/quick-design` for lightweight specs, or bullet points in a markdown file.
38+
- **No architecture.** Build throwaway scenes in `prototypes/`.
39+
- **Minimal agents.** Only `creative-director`, `game-designer`, `prototyper`, and `godot-specialist` (or engine equivalent).
40+
- **Time-boxed.** 2–4 weeks maximum per prototype.
41+
- **Kill cheaply.** If it's not fun, pivot or scrap. No sunk-cost fallacy.
42+
43+
### What NOT to do in Discovery
44+
- Architecture Decision Records (ADRs)
45+
- Epic/story breakdowns
46+
- QA plans
47+
- Asset pipeline setup
48+
- Unit tests (prototypes are throwaway)
49+
- Formal sprint plans
50+
51+
### Deliverable
52+
A working prototype that answers one core design question.
53+
54+
---
55+
56+
## Phase 2: Production (Post-Prototype)
57+
58+
### Goal
59+
Build, polish, and ship the game with full quality gates.
60+
61+
### Rules
62+
- Use the existing OCGS framework, but with a **consolidated agent hierarchy** (see below).
63+
- All changes require design review, architecture review, and QA sign-off.
64+
- Code lives in `src/` with full coding standards.
65+
- Every system has an ADR in `docs/architecture/`.
66+
- Tests first for gameplay systems (TDD).
67+
68+
### Slimmed Agent Hierarchy (49 → 10)
69+
70+
| Tier | Role | Responsibilities |
71+
|------|------|------------------|
72+
| 1 | `creative-director` | Vision, final say on design |
73+
| 1 | `technical-director` | Architecture, tech choices, code quality |
74+
| 2 | `game-designer` | Core mechanics, balance, progression |
75+
| 2 | `art-director` | Visual identity, asset specs |
76+
| 2 | `lead-programmer` | Code review, task breakdown |
77+
| 3 | `gameplay-programmer` | Player systems, combat, UI |
78+
| 3 | `technical-artist` | Shaders, VFX, rendering pipeline |
79+
| 3 | `qa-lead` | Test strategy, bug triage |
80+
| 3 | `sound-designer` | Audio direction |
81+
| 3 | `writer` | Narrative, lore, dialogue |
82+
83+
> **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`.
84+
85+
### Merged / Deferred Roles
86+
The following roles from the full 49-agent roster are either merged into the 10 above, or deferred until late production:
87+
88+
- `engine-programmer`, `tools-programmer` → `lead-programmer`
89+
- `ai-programmer`, `network-programmer` → `gameplay-programmer` (until needed)
90+
- `level-designer`, `world-builder` → `game-designer`
91+
- `ui-programmer`, `ux-designer` → `gameplay-programmer`
92+
- `economy-designer`, `systems-designer` → `game-designer`
93+
- `performance-analyst` → `technical-artist` / `lead-programmer`
94+
- `security-engineer`, `accessibility-specialist`, `live-ops-designer` → deferred until late production
95+
- `community-manager`, `analytics-engineer`, `localization-lead` → post-launch only
96+
97+
---
98+
99+
## Decision Gates
100+
101+
| Gate | Trigger | Checks |
102+
|------|---------|--------|
103+
| **Prototype Gate** | 2–4 weeks or prototype complete | Is it fun? Is scope realistic? |
104+
| **Production Gate** | Prototype approved | Is there a GDD? Is architecture defined? Is team staffed? |
105+
| **Alpha Gate** | Core loop complete | Balance, performance, major bugs |
106+
| **Ship Gate** | Content complete | QA sign-off, no critical bugs |
107+
108+
**Removed gates** (vs. full OCGS):
109+
- Full architecture review (lightweight ADR is enough)
110+
- Complete epic/story breakdown before implementation
111+
- Pre-commit architecture for every feature
112+
113+
---
114+
115+
## The `/prototype` Fast Lane
116+
117+
A new skill/command that shortcuts the path to a playable prototype:
118+
119+
1. `creative-director` approves concept (informal/chat).
120+
2. `prototyper` + `godot-specialist` build it.
121+
3. Manual playtest.
122+
4. `creative-director` + `game-designer` decide: **iterate**, **pivot**, or **productionize**.
123+
124+
**Average time to playable**: 2–3 days instead of 2–3 weeks of planning.
125+
126+
---
127+
128+
## Artifact Comparison
129+
130+
| Artifact | Discovery | Production |
131+
|----------|-----------|------------|
132+
| Game concept doc | Informal (`design/concept.md`) | Formal GDDs |
133+
| Architecture | None | ADRs required |
134+
| Code | `prototypes/` | `src/` with standards |
135+
| Tests | Manual playtest only | Unit + integration |
136+
| Sprint plans | Weekly goals in chat | Formal sprint plan |
137+
| QA | "Does it crash?" | Full QA plan |
138+
139+
---
140+
141+
## When to Switch to Full OCGS
142+
143+
Switch back to the **full 49-agent framework** if any of these become true:
144+
- Team grows beyond 5 people
145+
- Project timeline exceeds 6 months
146+
- Multiple features need parallel development
147+
- You need live ops, analytics, or multiplayer
148+
- Funding/publisher requires formal process
149+
150+
---
151+
152+
## Comparison
153+
154+
| Aspect | Full OCGS | Hybrid |
155+
|--------|-----------|--------|
156+
| Time to first prototype | 2–4 weeks | 2–4 days |
157+
| Process overhead (early) | High | Low |
158+
| Coordination (late) | Excellent | Good |
159+
| Team size | 5–15 | 1–5 |
160+
| Best for | Known game, funded, long timeline | Unknown game, indie, iterating |
161+
162+
---
163+
164+
## Migration Path
165+
166+
If a project starts with the hybrid workflow and later needs the full OCGS framework:
167+
168+
1. **Archive prototypes** to `prototypes/archive/`.
169+
2. **Promote surviving designs** to formal GDDs in `design/`.
170+
3. **Write ADRs** for the architecture of systems proven in prototypes.
171+
4. **Recruit additional agents** from the full roster as needed.
172+
5. **Switch to `src/`** with full coding standards.
173+
6. **Enable all quality gates** from the full framework.
174+
175+
---
176+
177+
## Notes
178+
179+
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.

‎.opencode/docs/skills-reference.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,7 @@
109109
| Command | Purpose |
110110
|---------|---------|
111111
| `/prototype` | Rapid throwaway prototype to validate a mechanic (relaxed standards, isolated worktree) |
112+
| `/hybrid-prototype` | Fast-lane prototype for discovery phase — 2-3 day build, no formal gates, lightweight DECISION.md |
112113
| `/onboard` | Generate contextual onboarding document for a new contributor or agent |
113114
| `/localize` | Localization workflow: string extraction, validation, translation readiness |
114115

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

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
name: hybrid-prototype
3+
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."
4+
argument-hint: "[concept-description]"
5+
user-invocable: true
6+
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
7+
agent: prototyper
8+
isolation: worktree
9+
---
10+
11+
## Overview
12+
13+
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.
14+
15+
**Time budget**: 1-3 days.
16+
**Agents involved**: `creative-director`, `game-designer`, `prototyper`, `godot-specialist` (or engine equivalent).
17+
18+
---
19+
20+
## Phase 1: Concept & Question (5 minutes)
21+
22+
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.
23+
24+
Examples of good questions:
25+
- "Does the combat feel responsive with 200ms input lag?"
26+
- "Is resource scarcity actually fun, or just frustrating?"
27+
- "Does the movement mechanic support the intended platforming challenges?"
28+
29+
Bad question: "Is this game fun?" (Too broad. Narrow it down.)
30+
31+
**Ask the user**: "The core question for this prototype is: [question]. Proceed?"
32+
33+
---
34+
35+
## Phase 2: Plan (15 minutes)
36+
37+
Define the minimum viable prototype in 3-5 bullet points:
38+
39+
- What is the absolute minimum code to answer the question?
40+
- What can be hardcoded / placeholder / skipped?
41+
- What is the success criteria? (e.g., "Player can complete 3 jumps in a row without dying")
42+
43+
**Present the plan to the user and ask for confirmation.**
44+
45+
---
46+
47+
## Phase 3: Build (1-2 days)
48+
49+
**Ask**: "May I create the prototype directory at `prototypes/[concept-name]/` and begin implementation?"
50+
51+
If yes, create the directory. Every file must begin with:
52+
53+
```
54+
// PROTOTYPE - NOT FOR PRODUCTION
55+
// Question: [Core question being tested]
56+
// Date: [Current date]
57+
```
58+
59+
**Rules for prototype code**:
60+
- Hardcode values freely
61+
- Use placeholder assets (colored squares, simple shapes)
62+
- Skip error handling
63+
- Use the simplest approach that works
64+
- Copy code rather than importing from production
65+
- NEVER import from `src/` — prototypes are isolated
66+
67+
**Run the prototype** as you build. Test continuously. Fix blockers, but don't polish.
68+
69+
---
70+
71+
## Phase 4: Playtest (2-4 hours)
72+
73+
Play the prototype yourself. Then ask the user to play it. Collect observations:
74+
75+
- What worked?
76+
- What felt bad?
77+
- Did it answer the core question?
78+
- Any surprising discoveries?
79+
80+
**Document findings informally** — a bulleted list is fine.
81+
82+
---
83+
84+
## Phase 5: Decide (30 minutes)
85+
86+
Collaborate with `creative-director` and `game-designer` (via Task or conversation) to make a decision:
87+
88+
| Verdict | Meaning | Next Step |
89+
|---------|---------|-----------|
90+
| **ITERATE** | Core is promising, but needs adjustment | Run `/hybrid-prototype [revised-concept]` |
91+
| **PIVOT** | The concept doesn't work, but a related one might | Run `/brainstorm` or `/hybrid-prototype [new-direction]` |
92+
| **PRODUCTIONIZE** | It's fun and proven — move to production | Begin GDD in `/design-system`, architecture in `/create-architecture` |
93+
| **KILL** | It's not fun and no clear fix | Stop. The prototype report is the deliverable. |
94+
95+
**Update `prototypes/[concept-name]/DECISION.md`** with:
96+
97+
```markdown
98+
# Prototype Decision: [Concept Name]
99+
100+
## Question
101+
[Core question]
102+
103+
## Result
104+
[What happened]
105+
106+
## Verdict
107+
[ITERATE / PIVOT / PRODUCTIONIZE / KILL]
108+
109+
## Reasoning
110+
[Why]
111+
112+
## Next Steps
113+
[What to do next]
114+
```
115+
116+
**Ask**: "May I write the decision to `prototypes/[concept-name]/DECISION.md`?"
117+
118+
---
119+
120+
## Phase 6: Done
121+
122+
Output a summary to the user: the core question, the verdict, and the next step.
123+
124+
If **PRODUCTIONIZE**: remind them to switch to the Production phase workflow (`/design-system`, `/create-architecture`, etc.)
125+
126+
If **ITERATE / PIVOT / KILL**: no further action needed.
127+
128+
---
129+
130+
## Constraints
131+
132+
- Prototype code must NEVER import from production source files
133+
- Production code must NEVER import from prototype directories
134+
- If productionizing, rewrite from scratch — do not refactor prototype code
135+
- Timebox strictly: if it's not working after 3 days, kill or pivot
136+
- Keep the question narrow — one prototype, one question
137+
- **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.
138+
139+
---
140+
141+
## Differences from Full `/prototype` Skill
142+
143+
| Aspect | `/prototype` (Full OCGS) | `/hybrid-prototype` (Fast Lane) |
144+
|--------|--------------------------|----------------------------------|
145+
| Review mode gates | Solo / Lean / Full | None (always fast) |
146+
| Creative Director review | Formal gate spawn | Informal chat/Task |
147+
| Report format | Formal `REPORT.md` | Lightweight `DECISION.md` |
148+
| Agents involved | All tiers | 4 core roles only |
149+
| Time to verdict | 1-3 days + review overhead | 1-3 days total |
150+
| Next step on PROCEED | Formal GDD + ADR | Start GDD when ready |

‎AGENTS.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,24 +90,44 @@ after each significant milestone:
9090
The state file should contain: current task, progress checklist, key decisions
9191
made, files being worked on, and open questions.
9292

93+
## Workflow Modes
94+
95+
This project supports two workflow modes. Choose the one that fits your team size and project maturity:
96+
97+
### Hybrid Workflow (Recommended for Indie Teams)
98+
99+
- **Discovery Phase**: Rapid prototyping to find the fun. Low process overhead, minimal agents, throwaway code in `prototypes/`.
100+
- **Production Phase**: Full OCGS discipline once the design is proven. Formal GDDs, ADRs, tests, and quality gates.
101+
- **Best for**: Teams of 1–5, unknown designs, iterating to find the fun.
102+
- **See**: `docs/hybrid-workflow.md` for full details.
103+
104+
### Full OCGS Workflow
105+
106+
- **All phases formal**: Every feature goes through design → architecture → stories → code → tests → review.
107+
- **Best for**: Teams of 5–15, known designs, long timelines, publisher requirements.
108+
- **See**: Full documentation in `docs/` and `.opencode/skills/`.
109+
93110
## Getting Started
94111

95112
Run `/start` in OpenCode to begin the guided onboarding flow.
96113
Or jump directly to:
97114
- `/brainstorm` — explore game ideas from scratch
98115
- `/setup-engine godot 4.6` — configure your engine
99116
- `/project-stage-detect` — analyze an existing project
117+
- `/prototype` — rapid prototype a concept
118+
- `/hybrid-prototype` — fast-lane prototype for discovery phase
100119

101120
## Available Commands
102121

103-
Type `/` in OpenCode to see all 72 commands. Key categories:
122+
Type `/` in OpenCode to see all available commands. Key categories:
104123

105124
- **Onboarding**: `/start`, `/help`, `/project-stage-detect`, `/setup-engine`
106125
- **Design**: `/brainstorm`, `/map-systems`, `/design-system`, `/quick-design`
107126
- **Architecture**: `/create-architecture`, `/architecture-decision`, `/architecture-review`
108127
- **Stories**: `/create-epics`, `/create-stories`, `/dev-story`, `/sprint-plan`
109128
- **Reviews**: `/design-review`, `/code-review`, `/balance-check`, `/gate-check`
110129
- **QA**: `/qa-plan`, `/smoke-check`, `/soak-test`, `/regression-suite`
130+
- **Prototyping**: `/prototype`, `/hybrid-prototype`
111131
- **Team**: `/team-combat`, `/team-narrative`, `/team-ui`, `/team-release`
112132

113133
## Studio Hierarchy

0 commit comments

Comments
 (0)