[codex] add prototype phase gates

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "ralph-specum",
       "description": "Spec-driven development with research, requirements, design, tasks, autonomous execution, and epic triage. Fresh context per task.",
-      "version": "4.9.1",
+      "version": "4.10.2",
       "author": {
         "name": "tzachbon"
       },

.gitignore

@@ -34,4 +34,7 @@ test-ac-*/
 
 # Claude
 .claude/worktrees/**
-.omc/**
+
+# Local tool artifacts
+.clawpatch/
+.omc/**

README.md

@@ -194,6 +194,7 @@ The helper skill package also includes `$ralph-specum-switch`, `$ralph-specum-ca
 Use `$ralph-specum-triage` first when the goal is large, cross-cutting, or likely to become multiple specs. Use `$ralph-specum-start` for a single spec or to resume an existing one.
 
 Codex Ralph is approval-gated by default. After each spec artifact, Ralph stops and asks you to approve the current artifact, request changes, or continue to the next step. Quick or autonomous flow happens only when you explicitly ask for it.
+Normal mode uses bundled grill-with-docs behavior before phase generation. Research, requirements, and design can also offer an optional prototype gate after the artifact walkthrough. Ralph ships these behaviors for Claude Code and documents inline fallbacks for Codex users without `$grill-with-docs` or `$prototype`.
 
 ### Claude Code
 

docs/superpowers/plans/2026-05-19-prototype-gates.md

@@ -0,0 +1,119 @@
+# Prototype Gates Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task by task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add optional prototype gates to Ralph Specum phase handoffs for Claude Code and Codex.
+
+**Architecture:** Keep the disk contract unchanged. Update phase command prompts and Codex skill guidance so normal mode uses `grill-with-docs`, shows walkthroughs, then asks a native choice: continue, run review, run prototype where useful, or request changes.
+
+**Tech Stack:** Markdown command prompts, Claude Code plugin metadata, Codex skill docs, Bats validation.
+
+---
+
+## File Structure
+
+- Modify `plugins/ralph-specum/commands/start.md`: use `grill-with-docs` during setup and align research handoff.
+- Modify `plugins/ralph-specum/commands/research.md`: use `grill-with-docs`, add prototype choice after walkthrough.
+- Modify `plugins/ralph-specum/commands/requirements.md`: use `grill-with-docs`, add prototype choice after PRD walkthrough.
+- Modify `plugins/ralph-specum/commands/design.md`: use `grill-with-docs`, add prototype choice after design walkthrough.
+- Modify `plugins/ralph-specum/commands/tasks.md`: use `grill-with-docs`, keep review and continue gate.
+- Modify `plugins/ralph-specum/skills/spec-workflow/SKILL.md`: document phase gate behavior.
+- Create `plugins/ralph-specum/skills/grill-with-docs/SKILL.md`: bundled Claude plugin grill fallback.
+- Create `plugins/ralph-specum/skills/prototype/SKILL.md`: bundled Claude plugin prototype fallback.
+- Modify `plugins/ralph-specum/.claude-plugin/plugin.json`: bump minor version.
+- Modify `.claude-plugin/marketplace.json`: match plugin version.
+- Modify `platforms/codex/skills/ralph-specum/references/workflow.md`: shared Codex phase flow.
+- Modify `platforms/codex/skills/ralph-specum/SKILL.md`: primary Codex contract.
+- Modify helper skills under `platforms/codex/skills/ralph-specum-*`: phase specific handoffs.
+- Modify Codex wording so `$grill-with-docs` and `$prototype` are optional, with inline behavior when missing.
+- Modify `platforms/codex/skills/ralph-specum/assets/bootstrap/AGENTS.md`: consumer repo guidance.
+- Modify `README.md` and `platforms/codex/README.md`: public flow docs.
+- Modify `tests/codex-platform.bats`: assert Codex docs expose prototype gate text.
+
+### Task 1: Claude Phase Prompts
+
+**Files:**
+- Modify: `plugins/ralph-specum/commands/start.md`
+- Modify: `plugins/ralph-specum/commands/research.md`
+- Modify: `plugins/ralph-specum/commands/requirements.md`
+- Modify: `plugins/ralph-specum/commands/design.md`
+- Modify: `plugins/ralph-specum/commands/tasks.md`
+- Modify: `plugins/ralph-specum/skills/spec-workflow/SKILL.md`
+
+- [ ] **Step 1: Patch interview instructions**
+
+Replace normal mode `interview-framework` references with `grill-with-docs` first, with fallback to existing interview framework if skill unavailable.
+
+- [ ] **Step 2: Patch approval gates**
+
+Research, requirements, and design AskUserQuestion options become:
+
+```text
+1. Continue to <next phase> (Recommended)
+2. Run review agent
+3. Run prototype
+4. Request changes
+```
+
+Tasks AskUserQuestion options become:
+
+```text
+1. Continue to implementation (Recommended)
+2. Run review agent
+3. Request changes
+```
+
+- [ ] **Step 3: Add prototype branch**
+
+Prototype branch invokes `Skill({ skill: "prototype" })`, runs throwaway prototype against current artifact and upstream context, captures result in `.progress.md`, then redisplays walkthrough and asks again.
+
+### Task 2: Codex Skill Contract
+
+**Files:**
+- Modify: `platforms/codex/skills/ralph-specum/references/workflow.md`
+- Modify: `platforms/codex/skills/ralph-specum/SKILL.md`
+- Modify: `platforms/codex/skills/ralph-specum-start/SKILL.md`
+- Modify: `platforms/codex/skills/ralph-specum-research/SKILL.md`
+- Modify: `platforms/codex/skills/ralph-specum-requirements/SKILL.md`
+- Modify: `platforms/codex/skills/ralph-specum-design/SKILL.md`
+- Modify: `platforms/codex/skills/ralph-specum-tasks/SKILL.md`
+- Modify: `platforms/codex/skills/ralph-specum/assets/bootstrap/AGENTS.md`
+- Modify: `platforms/codex/README.md`
+- Modify: `README.md`
+
+- [ ] **Step 1: Patch workflow reference**
+
+Normal flow documents `grill-with-docs` before phase generation and prototype gates after research, requirements, and design.
+
+- [ ] **Step 2: Patch helper handoffs**
+
+Each helper skill names the exact choice prompt. Prototype appears only on research, requirements, and design.
+
+- [ ] **Step 3: Patch docs**
+
+Root README and Codex README mention optional prototype gates after artifact walkthroughs.
+
+### Task 3: Version And Tests
+
+**Files:**
+- Modify: `plugins/ralph-specum/.claude-plugin/plugin.json`
+- Modify: `.claude-plugin/marketplace.json`
+- Modify: `tests/codex-platform.bats`
+
+- [ ] **Step 1: Bump version**
+
+Set Ralph Specum plugin version to `4.9.0` in both manifest files.
+
+- [ ] **Step 2: Add Codex assertions**
+
+Add Bats checks that primary and helper skill docs include `grill-with-docs` and prototype gate wording.
+
+- [ ] **Step 3: Verify**
+
+Run:
+
+```bash
+bats tests/codex-platform.bats
+```
+
+Expected: all tests pass.

plugins/ralph-specum-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-specum",
-  "version": "4.10.1",
+  "version": "4.10.2",
   "description": "Spec-driven development for OpenAI Codex. Research, requirements, design, tasks, autonomous implementation, and epic triage for multi-spec feature decomposition.",
   "author": {
     "name": "tzachbon"

plugins/ralph-specum-codex/README.md

@@ -19,6 +19,8 @@ $ralph-specum-start my-feature "Build a user authentication system"
 
 This starts the spec-driven workflow: research, requirements, design, tasks, then implementation.
 
+Normal mode uses bundled grill-with-docs behavior before phase generation. Research, requirements, and design can offer a prototype gate after the artifact walkthrough. If `$grill-with-docs` or `$prototype` is not installed, Ralph runs the documented behavior inline.
+
 ## Installation
 
 Pick one of the two methods below.

plugins/ralph-specum-codex/assets/bootstrap/AGENTS.md

@@ -23,15 +23,16 @@ Use Ralph Specum as the spec workflow for this repo.
 ## Flow
 
 1. Start or resume a spec
-2. Stop and ask whether to continue to research
-3. Research
-4. Approve the artifact, request changes, or continue to requirements
-5. Requirements
-6. Approve the artifact, request changes, or continue to design
-7. Design
-8. Approve the artifact, request changes, or continue to tasks
-9. Tasks
-10. Approve the artifact, request changes, or continue to implementation
-11. Implement
+2. When quick mode is off, use bundled grill-with-docs behavior before the next phase artifact
+3. Stop and ask whether to continue to research
+4. Research
+5. Walk through the artifact, then choose continue to requirements, run review agent, run prototype, or request changes. If `$prototype` is missing, run prototype behavior inline.
+6. Requirements
+7. Walk through the artifact, then choose continue to design, run review agent, run prototype, or request changes
+8. Design
+9. Walk through the artifact, then choose continue to tasks, run review agent, run prototype, or request changes
+10. Tasks
+11. Walk through the artifact, then choose continue to implementation, run review agent, or request changes
+12. Implement
 
 Quick mode may generate missing artifacts and continue straight into implementation in one run only when the user explicitly asks for quick or autonomous flow.

plugins/ralph-specum-codex/references/workflow.md

@@ -24,7 +24,7 @@
 Every phase skill acts as a coordinator. The coordinator:
 
 1. Gathers context (spec state, progress, prior artifacts)
-2. Runs the brainstorming interview (skip if `--quick`)
+2. Runs bundled grill-with-docs behavior (skip if `--quick`)
 3. Delegates artifact generation to the appropriate sub-agent type
 4. Validates the sub-agent output exists and is well-formed
 5. Presents the walkthrough summary
@@ -47,10 +47,10 @@ The coordinator MUST NOT write spec artifacts directly. If sub-agent delegation
 1. Resolve current repo state, branch, and spec roots.
 2. Start or resume a spec.
 3. STOP. Wait for explicit direction to continue to research unless `--quick`.
-4. Delegate `research.md` to `research-analyst` sub-agent. STOP and request approval unless `--quick`.
-5. Delegate `requirements.md` to `product-manager` sub-agent. STOP and request approval unless `--quick`.
-6. Delegate `design.md` to `architect-reviewer` sub-agent. STOP and request approval unless `--quick`.
-7. Delegate `tasks.md` to `task-planner` sub-agent. STOP and request approval unless `--quick`.
+4. Delegate `research.md` to `research-analyst` sub-agent. Walk through the artifact, then ask for `continue to requirements`, `run review agent`, `run prototype`, or `request changes` unless `--quick`.
+5. Delegate `requirements.md` to `product-manager` sub-agent. Walk through the artifact, then ask for `continue to design`, `run review agent`, `run prototype`, or `request changes` unless `--quick`.
+6. Delegate `design.md` to `architect-reviewer` sub-agent. Walk through the artifact, then ask for `continue to tasks`, `run review agent`, `run prototype`, or `request changes` unless `--quick`.
+7. Delegate `tasks.md` to `task-planner` sub-agent. Walk through the artifact, then ask for `continue to implementation`, `run review agent`, or `request changes` unless `--quick`.
 8. Delegate each task to `spec-executor` sub-agent until complete or blocked.
 9. Use `status`, `switch`, `cancel`, `index`, `refactor`, `feedback`, and `help` as needed.
 
@@ -124,12 +124,35 @@ When a phase writes `research.md`, `requirements.md`, `design.md`, `tasks.md`, o
 - name the file or files that changed
 - give a short summary
 - end with exactly one explicit choice prompt:
-  - `approve current artifact`
-  - `request changes`
   - `continue to <named next step>`
+  - `run review agent`
+  - `run prototype` when the artifact is `research.md`, `requirements.md`, or `design.md`
+  - `request changes`
 
 Treat `continue to <named next step>` as approval of the current artifact.
 
+## Bundled Grill With Docs Behavior
+
+Codex users may not have `$grill-with-docs` installed. If it is available, use it. Otherwise run the behavior inline:
+
+1. Inspect code and docs before asking.
+2. Check `CONTEXT.md`, `CONTEXT-MAP.md`, and `docs/adr/` when present.
+3. Ask one native question at a time only when the answer is not discoverable.
+4. Put the recommended answer first.
+5. Capture stable terminology in `CONTEXT.md` when useful.
+
+## Bundled Prototype Behavior
+
+Codex users may not have `$prototype` installed. If it is available, use it. Otherwise run the behavior inline:
+
+1. Name the question the prototype must answer.
+2. Choose a terminal prototype for logic or state questions.
+3. Choose route-level UI variants for UI questions.
+4. Mark prototype files as throwaway.
+5. Provide one command to run.
+6. Append the result to `.progress.md`.
+7. Redisplay the walkthrough and ask the gate question again.
+
 ## Hook-Driven Execution Path
 
 When the Codex Stop hook is enabled (`[features] codex_hooks = true` in Codex config), the execution loop runs without user re-invocation:

plugins/ralph-specum-codex/skills/ralph-specum-design/SKILL.md

@@ -22,8 +22,8 @@ You are a **coordinator, not an architect** -- delegate ALL work to an `architec
 1. Resolve the active spec. If none exists, stop.
 2. Require `requirements.md`. Read `research.md` when present, `.progress.md`, and current state.
 3. Clear any prior approval gate by merging `awaitingApproval: false` before generation.
-4. Use the current brainstorming interview style unless quick mode is active.
-5. **Delegate** design generation to an `architect-reviewer` sub-agent. Pass requirements, research, and interview context. The sub-agent writes `design.md`. Do NOT write design.md yourself.
+4. Use bundled grill-with-docs behavior unless quick mode is active. If `$grill-with-docs` exists, use it. Otherwise inspect code and docs inline, ask native questions one at a time, and capture stable terminology when useful.
+5. **Delegate** design generation to an `architect-reviewer` sub-agent. Pass requirements, research, grill-with-docs decisions, and interview context. The sub-agent writes `design.md`. Do NOT write design.md yourself.
 6. Read the sub-agent's output and validate it exists.
 7. Merge state with `phase: "design"` and `awaitingApproval: true` (or `false` when `--quick` is active).
 8. Update `.progress.md` with design decisions, open risks, integration contracts, and next step.
@@ -41,8 +41,10 @@ The result should cover architecture, interfaces, data flow, file changes, techn
 ## Response Handoff
 
 - After writing `design.md`, name `design.md` and summarize the design briefly.
+- If the user chooses `run prototype`, use `$prototype` when available. If unavailable, run a throwaway prototype inline, append the result to `.progress.md`, redisplay the walkthrough, and ask again.
 - End with exactly one explicit choice prompt:
-  - `approve current artifact`
-  - `request changes`
   - `continue to tasks`
+  - `run review agent`
+  - `run prototype`
+  - `request changes`
 - Treat `continue to tasks` as approval of `design.md`.

plugins/ralph-specum-codex/skills/ralph-specum-design/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Ralph Specum Design"
   short_description: "Generate technical design for an active spec"
-  default_prompt: "Use $ralph-specum-design to write design.md, then ask me to `approve current artifact`, `request changes`, or `continue to tasks`."
+  default_prompt: "Use $ralph-specum-design to run bundled grill-with-docs behavior, write design.md, then ask me to `continue to tasks`, `run review agent`, `run prototype`, or `request changes`."
 policy:
   allow_implicit_invocation: false

plugins/ralph-specum-codex/skills/ralph-specum-requirements/SKILL.md

@@ -22,8 +22,8 @@ You are a **coordinator, not a product manager** -- delegate ALL work to a `prod
 1. Resolve the active spec. If none exists, stop.
 2. Read `research.md` when present, `.progress.md`, and the current state.
 3. Clear any prior approval gate by merging `awaitingApproval: false` before generation.
-4. Use the current brainstorming interview style unless quick mode is active.
-5. **Delegate** requirements generation to a `product-manager` sub-agent. Pass research context, goal, and interview results. The sub-agent writes `requirements.md`. Do NOT write requirements.md yourself.
+4. Use bundled grill-with-docs behavior unless quick mode is active. If `$grill-with-docs` exists, use it. Otherwise inspect code and docs inline, ask native questions one at a time, and capture stable terminology when useful.
+5. **Delegate** requirements generation to a `product-manager` sub-agent. Pass research context, goal, grill-with-docs decisions, and interview results. The sub-agent writes `requirements.md`. Do NOT write requirements.md yourself.
 6. Read the sub-agent's output and validate it exists.
 7. Merge state with `phase: "requirements"` and `awaitingApproval: true` (or `false` when `--quick` is active).
 8. Update `.progress.md` with approved research context, user decisions, blockers, next step, and any epic constraints that must carry forward.
@@ -41,8 +41,10 @@ The result should include user stories, acceptance criteria, functional requirem
 ## Response Handoff
 
 - After writing `requirements.md`, name `requirements.md` and summarize the requirements briefly.
+- If the user chooses `run prototype`, use `$prototype` when available. If unavailable, run a throwaway prototype inline, append the result to `.progress.md`, redisplay the walkthrough, and ask again.
 - End with exactly one explicit choice prompt:
-  - `approve current artifact`
-  - `request changes`
   - `continue to design`
+  - `run review agent`
+  - `run prototype`
+  - `request changes`
 - Treat `continue to design` as approval of `requirements.md`.

plugins/ralph-specum-codex/skills/ralph-specum-requirements/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Ralph Specum Requirements"
   short_description: "Generate requirements for an active spec"
-  default_prompt: "Use $ralph-specum-requirements to write requirements.md, then ask me to `approve current artifact`, `request changes`, or `continue to design`."
+  default_prompt: "Use $ralph-specum-requirements to run bundled grill-with-docs behavior, write requirements.md, then ask me to `continue to design`, `run review agent`, `run prototype`, or `request changes`."
 policy:
   allow_implicit_invocation: false

plugins/ralph-specum-codex/skills/ralph-specum-research/SKILL.md

@@ -22,8 +22,8 @@ You are a **coordinator, not a researcher** -- delegate ALL work to a `research-
 
 1. Resolve the active spec. If none exists, stop and tell the user to start a spec first.
 2. Read the goal, `.progress.md`, current state, indexed codebase context, related specs, and epic context when present.
-3. Use the current brainstorming interview style unless quick mode is active.
-4. **Delegate** research generation to a `research-analyst` sub-agent. Pass the goal, existing context, and interview results. The sub-agent writes `research.md` in the spec directory. Do NOT write research.md yourself.
+3. Use bundled grill-with-docs behavior unless quick mode is active. If `$grill-with-docs` exists, use it. Otherwise inspect code and docs inline, ask native questions one at a time, and capture stable terminology when useful.
+4. **Delegate** research generation to a `research-analyst` sub-agent. Pass the goal, existing context, grill-with-docs decisions, and interview results. The sub-agent writes `research.md` in the spec directory. Do NOT write research.md yourself.
 5. Read the sub-agent's output and validate it exists.
 6. Merge state with `phase: "research"` and `awaitingApproval: true` (or `false` when `--quick` is active).
 7. Update `.progress.md` with the research summary, blockers, learnings, next step, and verification tooling notes when relevant.
@@ -41,8 +41,10 @@ The result should identify existing code patterns, external references, constrai
 ## Response Handoff
 
 - After writing `research.md`, name `research.md` and summarize the research briefly.
+- If the user chooses `run prototype`, use `$prototype` when available. If unavailable, run a throwaway prototype inline, append the result to `.progress.md`, redisplay the walkthrough, and ask again.
 - End with exactly one explicit choice prompt:
-  - `approve current artifact`
-  - `request changes`
   - `continue to requirements`
+  - `run review agent`
+  - `run prototype`
+  - `request changes`
 - Treat `continue to requirements` as approval of `research.md`.

plugins/ralph-specum-codex/skills/ralph-specum-research/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Ralph Specum Research"
   short_description: "Generate research for an active spec"
-  default_prompt: "Use $ralph-specum-research to write research.md, then ask me to `approve current artifact`, `request changes`, or `continue to requirements`."
+  default_prompt: "Use $ralph-specum-research to run bundled grill-with-docs behavior, write research.md, then ask me to `continue to requirements`, `run review agent`, `run prototype`, or `request changes`."
 policy:
   allow_implicit_invocation: false