wxm/codex-game-studios
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Align brainstorm workflow with Codex input schema

Browse Source
This commit is contained in:
wxm
2026-05-18 19:42:51 -07:00
parent 0c4227cba6
commit 445d86c300
11 changed files with 1192 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
skills/brainstorm/DETAILS.md
View File

@@ -11,21 +11,6 @@ When this skill is invoked:
See `../../references/studio-docs/director-gates.md` for the full check pattern.
Review mode controls **director / lead review gates only**. It is not a
blanket rule for all custom-agent or subagent usage. For `/brainstorm`, the
current agent calls are review gates, so `lean` skips CD-PILLARS,
AD-CONCEPT-VISUAL, TD-FEASIBILITY, and PR-SCOPE; `full` runs them; `solo`
skips all director review gates.
Director agent source files live in `../../runtime/agents/`, and the project
guidance template lives at `../../project-template/AGENTS.md`. Before running
any `full` review-mode gate, verify the target project has the matching
`.codex/agents/<agent-name>.toml` files installed and a root `AGENTS.md`. If
they are missing, run `python3 scripts/install_codex_runtime.py <target-project>`
from the plugin root first. When a gate is active, spawn the named Codex
custom agent; do not recreate the director role by pasting profile text into
a generic default agent.
2. **Check for existing concept work**:
- Read `design/gdd/game-concept.md` if it exists (resume, don't restart)
- Read `design/gdd/game-pillars.md` if it exists (build on established pillars)
@@ -35,17 +20,27 @@ When this skill is invoked:
exploration** where the AI acts as a creative facilitator, not a replacement
for the human's vision.
**Use a structured decision prompt when available** at key decision points
throughout brainstorming. In Codex, use the current user-input mechanism if
it is available in the active mode; otherwise ask the same question directly
in chat and wait for the user's reply.
**Use Codex `request_user_input`** at key decision points throughout brainstorming:
- Constrained taste questions (genre preferences, scope, team size)
- Concept selection ("Which 2-3 concepts resonate?") after presenting options
- Direction choices ("Develop further, explore more, or prototype?")
- Pillar ranking after concepts are refined
Write full creative analysis in conversation text first, then use
the structured prompt or chat question to capture the decision with concise
labels.
Write full creative analysis in conversation text first, then call
`request_user_input` to capture the decision with concise labels.
Codex structured input requirements:
- Ask 1-3 short questions per `request_user_input` call.
- Each question must include `header` (12 or fewer characters), `id` (snake_case),
`question` (one sentence), and 2-3 mutually exclusive `options`.
- Each option must include `label` (1-5 words) and `description` (one short sentence).
- Put the recommended option first and suffix its label with `(Recommended)` when
there is a recommendation.
- Do not add an explicit `Other` option in Codex app runs; the client supplies the
free-form Other path. For app-server integrations, the equivalent free-form
option is represented by `isOther`.
- If a Claude reference choice list has more than 3 options, split it into a
first 2-3 option category question plus a follow-up `request_user_input` call,
or rely on the Codex free-form Other path for uncommon cases.
Professional studio brainstorming principles to follow:
- Withhold judgment — no idea is bad during exploration
@@ -70,19 +65,53 @@ conversationally (not as a checklist):
**Taste profile**:
- What 3 games have you spent the most time with? What kept you coming back?
*(Ask this as plain text — the user must be able to type specific game names freely.
Do NOT put this in a structured prompt with preset options.)*
Do NOT put this in `request_user_input` with preset options.)*
- Are there genres you love? Genres you avoid? Why?
- Do you prefer games that challenge you, relax you, tell you stories,
or let you express yourself? *(Use a structured prompt for this when available — constrained choice.)*
or let you express yourself? *(Use `request_user_input` for this — constrained choice.
Use 2-3 grouped options plus Codex's free-form Other path.)*
**Practical constraints** (shape the sandbox before brainstorming).
Bundle these into a single multi-field structured prompt when available:
- Tab "Experience" — "What kind of experience do you most want players to have?" (Challenge & Mastery / Story & Discovery / Expression & Creativity / Relaxation & Flow)
- Tab "Timeline" — "What's your realistic development timeline?" (Weeks / Months / 1-2 years / Multi-year)
- Tab "Dev level" — "Where are you in your dev journey?" (First game / Shipped before / Professional background)
Bundle these into one Codex `request_user_input` call with three questions:
If the UI supports grouping fields, use exactly these group names. If not,
ask the three questions one at a time.
```json
{
"questions": [
{
"header": "Experience",
"id": "target_experience",
"question": "What kind of experience do you most want players to have?",
"options": [
{"label": "Challenge", "description": "Players seek mastery, pressure, and earned wins."},
{"label": "Story", "description": "Players seek discovery, drama, and authored moments."},
{"label": "Expression", "description": "Players seek creativity, agency, or relaxed flow."}
]
},
{
"header": "Timeline",
"id": "timeline",
"question": "What's your realistic development timeline?",
"options": [
{"label": "Weeks", "description": "A jam-scale prototype or tiny polished game."},
{"label": "Months", "description": "A focused indie scope with selective polish."},
{"label": "1+ years", "description": "A larger project that needs strong scope control."}
]
},
{
"header": "Dev level",
"id": "dev_level",
"question": "Where are you in your dev journey?",
"options": [
{"label": "First game", "description": "Keep systems simple and learning-friendly."},
{"label": "Shipped before", "description": "Use moderate scope and proven patterns."},
{"label": "Professional", "description": "Assume stronger production and technical context."}
]
}
]
}
```
Do not use tabs or more than three options per question in Codex.
**Synthesize** the answers into a **Creative Brief** — a 3-5 sentence
summary of the person's emotional goals, taste profile, and constraints.
@@ -120,25 +149,40 @@ For each concept, present:
- **Why It Could Work** (1 sentence on market/audience fit)
- **Biggest Risk** (1 sentence on the hardest unanswered question)
Present all three. Then use a structured prompt or direct chat question to
capture the selection.
Present all three. Then use Codex `request_user_input` to capture the selection.
**CRITICAL**: This MUST be a plain list choice, not a multi-field form. Use this structure:
**CRITICAL**: Codex `request_user_input` only supports 1-3 short questions and
2-3 options per question. Do not use tabs, form fields, or a 5-option list.
Use exactly this shape:
```
structured decision prompt(
prompt: "Which concept resonates with you? You can pick one, combine elements, or ask for fresh directions.",
options: [
"Concept 1 — [Title]",
"Concept 2 — [Title]",
"Concept 3 — [Title]",
"Combine elements across concepts",
"Generate fresh directions"
```json
{
"questions": [
{
"header": "Concept",
"id": "concept_choice",
"question": "Which concept is the strongest starting point?",
"options": [
{"label": "Concept 1", "description": "[Title] — [one-line reason it fits]."},
{"label": "Concept 2", "description": "[Title] — [one-line reason it fits]."},
{"label": "Concept 3", "description": "[Title] — [one-line reason it fits]."}
]
},
{
"header": "Next move",
"id": "concept_next_move",
"question": "How should we proceed with that direction?",
"options": [
{"label": "Develop it", "description": "Use the selected concept as the foundation."},
{"label": "Combine", "description": "Blend the selected concept with elements from another."},
{"label": "Fresh set", "description": "Generate three new directions from the brief."}
]
}
]
)
}
```
Do NOT use a multi-field form here. This is a plain prompt plus options.
If the user wants a custom blend, use the Codex free-form Other path.
Never pressure toward a choice — let them sit with it.
@@ -152,11 +196,12 @@ isolation, no amount of content or polish will save the game.
**30-Second Loop** (moment-to-moment):
Ask these as structured prompts when available — derive the options from the chosen concept, don't hardcode them:
Ask these with Codex `request_user_input` — derive the options from the chosen
concept, don't hardcode them:
1. **Core action feel** — prompt: "What's the primary feel of the core action?" Generate 3-4 options that fit the concept's genre and tone, plus a free-text escape (`I'll describe it`).
1. **Core action feel** — prompt: "What's the primary feel of the core action?" Generate exactly 2-3 options that fit the concept's genre and tone. Use the Codex free-form Other path for custom answers.
2. **Key design dimension** — identify the most important design variable for this specific concept (e.g., world reactivity, pacing, player agency) and ask about it. Generate options that match the concept. Always include a free-text escape.
2. **Key design dimension** — identify the most important design variable for this specific concept (e.g., world reactivity, pacing, player agency) and ask about it. Generate exactly 2-3 options that match the concept. Use the Codex free-form Other path for custom answers.
After capturing answers, analyze: Is this action intrinsically satisfying? What makes it feel good? (Audio feedback, visual juice, timing satisfaction, tactical depth?)
@@ -201,53 +246,34 @@ Then define **3+ anti-pillars** (what this game is NOT):
be cool if..." features that don't serve the core vision
- Frame as: "We will NOT do [thing] because it would compromise [pillar]"
**Pillar confirmation**: After presenting the full pillar set, use a structured prompt:
**Pillar confirmation**: After presenting the full pillar set, use Codex `request_user_input`:
- Prompt: "Do these pillars feel right for your game?"
- Options: `[A] Lock these in` / `[B] Rename or reframe one` / `[C] Swap a pillar out` / `[D] Something else`
- Options: `[A] Lock these in` / `[B] Revise one` / `[C] Discuss further`
If the user selects B, C, or D, make the revision, then use a structured prompt again:
If the user selects B or C, make the revision or discuss the concern, then use
Codex `request_user_input` again:
- Prompt: "Pillars updated. Ready to lock these in?"
- Options: `[A] Lock these in` / `[B] Revise another pillar` / `[C] Something else`
- Options: `[A] Lock these in` / `[B] Revise another` / `[C] Discuss further`
Repeat until the user selects [A] Lock these in.
Treat `[A] Lock these in` as approval to create or update
`design/gdd/game-pillars.md` during this `/brainstorm` run. The file is a
brainstorm-stage artifact: start it lightweight now, then let later workflows
deepen it as the project matures.
**Pillar conflict priority**: After pillars are locked, ask one short follow-up:
"If two pillars conflict, which one wins first?" Present the locked pillar names
as ordered options and let the user rank them or describe a custom priority.
Record this as the initial conflict-resolution order in
`design/gdd/game-pillars.md`.
**Review mode check** — apply before spawning CD-PILLARS and AD-CONCEPT-VISUAL:
- `solo` → skip both. Note: "CD-PILLARS skipped — Solo mode. AD-CONCEPT-VISUAL skipped — Solo mode." Create or update the initial `design/gdd/game-pillars.md` directly from the locked pillars, then proceed to Phase 5.
- `lean` → skip both (not PHASE-GATEs). Note: "CD-PILLARS skipped — Lean mode. AD-CONCEPT-VISUAL skipped — Lean mode." Create or update the initial `design/gdd/game-pillars.md` directly from the locked pillars, then proceed to Phase 5.
- `solo` → skip both. Note: "CD-PILLARS skipped — Solo mode. AD-CONCEPT-VISUAL skipped — Solo mode." Proceed to Phase 5.
- `lean` → skip both (not PHASE-GATEs). Note: "CD-PILLARS skipped — Lean mode. AD-CONCEPT-VISUAL skipped — Lean mode." Proceed to Phase 5.
- `full` → spawn as normal.
**After pillars and anti-pillars are agreed, spawn BOTH `creative-director` AND `art-director` via Codex custom-agent delegation in parallel before moving to Phase 5. Issue both subagent requests simultaneously — do not wait for one before starting the other.**
**After pillars and anti-pillars are agreed, spawn BOTH `creative-director` AND `art-director` via Codex custom-agent delegation in parallel before moving to Phase 5. Issue both custom-agent requests simultaneously — do not wait for one before starting the other.**
- **`creative-director`** — gate **CD-PILLARS** (`../../references/studio-docs/director-gates.md`)
Pass: full pillar set with design tests, anti-pillars, pillar conflict priority,
core fantasy, unique hook.
Also pass whether `design/gdd/game-pillars.md` already exists and whether its
contents match the locked pillar set. This file is required for `/brainstorm`:
if it already exists and still matches the locked pillars, the subagent reviews
it in place and avoids rewriting for churn; if the file is missing, stale, or
incomplete, the subagent creates or updates it from
`../../references/studio-docs/templates/game-pillars.md`. The initial version
only needs the brainstorm-level material: core fantasy, unique hook, target
MDA aesthetics, 3-5 pillars, design tests, anti-pillars, conflict priority,
and a validation checklist.
Pass: full pillar set with design tests, anti-pillars, core fantasy, unique hook.
- **`art-director`** — gate **AD-CONCEPT-VISUAL** (`../../references/studio-docs/director-gates.md`)
Pass: game concept elevator pitch, full pillar set with design tests, target platform (if known), any reference games or visual touchstones the user mentioned.
Collect both verdicts, then present them together using a structured prompt:
- Tab **"Pillars"**: present creative-director feedback. Options mirror the standard CD-PILLARS handling — `Lock in as-is` / `Revise [specific pillar]` / `Discuss further`.
- Tab **"Visual anchor"**: present the art-director's 2-3 named visual direction options. Options: each named direction (one per option) + `Combine elements across directions` + `Describe my own direction`.
Collect both verdicts, then present them together using one Codex
`request_user_input` call with up to two questions:
- Question **"Pillars"**: present creative-director feedback. Options mirror the standard CD-PILLARS handling — `Lock in` / `Revise one` / `Discuss`.
- Question **"Visual"**: present the art-director's 2-3 named visual direction options. If there are three named directions, use those three options and rely on the Codex free-form Other path for combine/custom answers. If there are only two named directions, use those two plus `Combine`.
The user's selected visual anchor (the named direction or their custom description) is stored as the **Visual Identity Anchor** — it will be written into the game-concept document and becomes the foundation of the art bible.
@@ -274,13 +300,13 @@ who this game is actually for:
Ground the concept in reality:
- **Target platform**: Use a structured prompt when available — "What platforms are you targeting for this game?"
Options: `PC (Steam / Epic)` / `Mobile (iOS / Android)` / `Console` / `Web / Browser` / `Multiple platforms`
- **Target platform**: Use Codex `request_user_input` — "What platforms are you targeting for this game?"
Options: `PC` / `Mobile` / `Console/Web`. Use the Codex free-form Other path for multiple platforms or a specific store target.
Record the answer — it directly shapes the engine recommendation and will be passed to `/setup-engine`.
Note platform implications if relevant (e.g., mobile means Unity is strongly preferred; console means Godot has limitations; web means Godot exports cleanly).
- **Engine experience**: Use a structured prompt when available — "Do you already have an engine you work in?"
Options: `Godot` / `Unity` / `Unreal Engine 5` / `No preference — help me decide`
- **Engine experience**: Use Codex `request_user_input` — "Do you already have an engine you work in?"
Options: `Godot` / `Unity` / `Unreal`. Use the Codex free-form Other path for "No preference" or another engine.
- If they pick an engine → record it as their preference and move on. Do NOT second-guess it.
- If "No preference" → tell them: "Run `/setup-engine` after this session — it will walk you through the full decision based on your concept and platform target." Do not make a recommendation here.
- **Art pipeline**: What's the art style and how labor-intensive is it?
@@ -314,20 +340,10 @@ Present the assessment to the user. If UNREALISTIC, offer to adjust the MVP defi
---
4. **Generate the brainstorm documents**:
- Generate or update `design/gdd/game-pillars.md` using
`../../references/studio-docs/templates/game-pillars.md`. This file is
created during `/brainstorm`, even if it starts lightweight. If review mode
is `full`, the `creative-director` subagent owns this write during
CD-PILLARS. If review mode is `lean` or `solo`, the main brainstorm workflow
writes the initial version directly after pillars are locked.
- Generate `design/gdd/game-concept.md` using
`../../references/studio-docs/templates/game-concept.md`. Fill in ALL
sections from the brainstorm conversation, including the MDA analysis,
player motivation profile, and flow state design sections.
- In `design/gdd/game-concept.md`, summarize the locked pillars and link to
`design/gdd/game-pillars.md` as the detailed pillar source of truth.
4. **Generate the game concept document** using the template at
`../../references/studio-docs/templates/game-concept.md`. Fill in ALL sections from the
brainstorm conversation, including the MDA analysis, player motivation
profile, and flow state design sections.
**Include a Visual Identity Anchor section** in the game concept document with:
- The selected visual direction name
@@ -338,21 +354,20 @@ Present the assessment to the user. If UNREALISTIC, offer to adjust the MVP defi
This section is the seed of the art bible — it captures the "everything must
move" decision before it can be forgotten between sessions.
5. Use a structured prompt or direct chat question for write approval:
- Prompt: "Brainstorm documents are ready. May I write them to `design/gdd/game-concept.md` and `design/gdd/game-pillars.md`?"
- Options: `[A] Yes — write them` / `[B] Not yet — revise a section first`
5. Use Codex `request_user_input` for write approval:
- Prompt: "Game concept is ready. May I write it to `design/gdd/game-concept.md`?"
- Options: `[A] Yes — write it` / `[B] Not yet — revise a section first`
If [B]: ask which section to revise using a structured prompt with options: `Elevator Pitch` / `Core Fantasy & Unique Hook` / `Pillars` / `Core Loop` / `MVP Definition` / `Scope Tiers` / `Risks` / `Something else — I'll describe`
If [B]: ask which area to revise using Codex `request_user_input` with 2-3
category options such as `Identity`, `Loop`, and `Scope/Risks`, then ask a
follow-up question if the category needs narrowing. Use the Codex free-form
Other path for a custom section.
After revising, show the updated section as a diff or clear before/after, then ask — "Ready to write the updated brainstorm documents?"
Options: `[A] Yes — write them` / `[B] Revise another section`
After revising, show the updated section as a diff or clear before/after, then use Codex `request_user_input` — "Ready to write the updated concept document?"
Options: `[A] Yes — write it` / `[B] Revise another section`
Repeat until the user selects [A].
If yes, generate `design/gdd/game-pillars.md` using
`../../references/studio-docs/templates/game-pillars.md` and
`design/gdd/game-concept.md` using
`../../references/studio-docs/templates/game-concept.md`, fill both from the
brainstorm conversation, and write the files, creating directories as needed.
If yes, generate the document using the template at `../../references/studio-docs/templates/game-concept.md`, fill in ALL sections from the brainstorm conversation, and write the file, creating directories as needed.
**Scope consistency rule**: The "Estimated Scope" field in the Core Identity table must match the full-vision timeline from the Scope Tiers section — not just say "Large (9+ months)". Write it as "Large (X–Y months, solo)" or "Large (X–Y months, team of N)" so the summary table is accurate.
@@ -379,7 +394,7 @@ brainstorm conversation, and write the files, creating directories as needed.
5. "After full design and architecture, build the `/vertical-slice` to validate production readiness before committing to sprints"
7. **Output a summary** with the chosen concept's elevator pitch, pillars,
primary player type, engine recommendation, biggest risk, and file paths.
primary player type, engine recommendation, biggest risk, and file path.
Verdict: **COMPLETE** — game concept created and handed off for next steps.