diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 420d4385..5bef9c0f 100644 --- a/.claude-plugin/marketplace.json +++ b/.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" }, diff --git a/.gitignore b/.gitignore index 4426cb97..98a2598c 100644 --- a/.gitignore +++ b/.gitignore @@ -34,4 +34,7 @@ test-ac-*/ # Claude .claude/worktrees/** -.omc/** \ No newline at end of file + +# Local tool artifacts +.clawpatch/ +.omc/** diff --git a/README.md b/README.md index ee05e8d8..9b0b1e65 100644 --- a/README.md +++ b/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 diff --git a/docs/superpowers/plans/2026-05-19-prototype-gates.md b/docs/superpowers/plans/2026-05-19-prototype-gates.md new file mode 100644 index 00000000..824c5992 --- /dev/null +++ b/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 (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. diff --git a/plugins/ralph-specum-codex/.codex-plugin/plugin.json b/plugins/ralph-specum-codex/.codex-plugin/plugin.json index 0fcd3011..73751a24 100644 --- a/plugins/ralph-specum-codex/.codex-plugin/plugin.json +++ b/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" diff --git a/plugins/ralph-specum-codex/README.md b/plugins/ralph-specum-codex/README.md index 1bb4fc25..87abcc61 100644 --- a/plugins/ralph-specum-codex/README.md +++ b/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. diff --git a/plugins/ralph-specum-codex/assets/bootstrap/AGENTS.md b/plugins/ralph-specum-codex/assets/bootstrap/AGENTS.md index 42a9007b..33d955ad 100644 --- a/plugins/ralph-specum-codex/assets/bootstrap/AGENTS.md +++ b/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. diff --git a/plugins/ralph-specum-codex/references/workflow.md b/plugins/ralph-specum-codex/references/workflow.md index 168fe82c..3b2a5df6 100644 --- a/plugins/ralph-specum-codex/references/workflow.md +++ b/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 ` + - `run review agent` + - `run prototype` when the artifact is `research.md`, `requirements.md`, or `design.md` + - `request changes` Treat `continue to ` 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: diff --git a/plugins/ralph-specum-codex/skills/ralph-specum-design/SKILL.md b/plugins/ralph-specum-codex/skills/ralph-specum-design/SKILL.md index 9ec1431b..3954a3b3 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum-design/SKILL.md +++ b/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`. diff --git a/plugins/ralph-specum-codex/skills/ralph-specum-design/agents/openai.yaml b/plugins/ralph-specum-codex/skills/ralph-specum-design/agents/openai.yaml index 6b9da3e7..93677dc1 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum-design/agents/openai.yaml +++ b/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 diff --git a/plugins/ralph-specum-codex/skills/ralph-specum-requirements/SKILL.md b/plugins/ralph-specum-codex/skills/ralph-specum-requirements/SKILL.md index 06b608ba..9cf1db37 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum-requirements/SKILL.md +++ b/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`. diff --git a/plugins/ralph-specum-codex/skills/ralph-specum-requirements/agents/openai.yaml b/plugins/ralph-specum-codex/skills/ralph-specum-requirements/agents/openai.yaml index 962ecd1a..46ebf5a1 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum-requirements/agents/openai.yaml +++ b/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 diff --git a/plugins/ralph-specum-codex/skills/ralph-specum-research/SKILL.md b/plugins/ralph-specum-codex/skills/ralph-specum-research/SKILL.md index bffe0bd5..46af27f5 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum-research/SKILL.md +++ b/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`. diff --git a/plugins/ralph-specum-codex/skills/ralph-specum-research/agents/openai.yaml b/plugins/ralph-specum-codex/skills/ralph-specum-research/agents/openai.yaml index e9f7504b..f9abc3c0 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum-research/agents/openai.yaml +++ b/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 diff --git a/plugins/ralph-specum-codex/skills/ralph-specum-start/SKILL.md b/plugins/ralph-specum-codex/skills/ralph-specum-start/SKILL.md index 292577ae..b6880d1b 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum-start/SKILL.md +++ b/plugins/ralph-specum-codex/skills/ralph-specum-start/SKILL.md @@ -48,7 +48,8 @@ Use this for the `start` and `new` entrypoints. 9. Write `.progress.md` with goal, current phase, next step, blockers, learnings, and skill discovery results when used. 10. On resume, prefer `tasks.md` and present files over stale state when they disagree. 11. In quick mode, generate missing artifacts in order, skip normal approval pauses, and continue into implementation in the same run. -12. **Without quick mode or explicit autonomy: STOP HERE after setup. Do NOT proceed to research. Wait for the user to explicitly ask to continue.** This is non-negotiable. +12. Before the next phase artifact in normal mode, use bundled grill-with-docs behavior. 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. +13. **Without quick mode or explicit autonomy: STOP HERE after setup. Do NOT proceed to research. Wait for the user to explicitly ask to continue.** This is non-negotiable. ## Branch Isolation @@ -58,6 +59,7 @@ Use this for the `start` and `new` entrypoints. ## Response Handoff - After creating or resuming the spec, name the resolved spec path and summarize the current state briefly. +- If quick mode is not active, the next phase uses bundled grill-with-docs behavior before artifact generation. - End with exactly one explicit choice prompt: - `request changes` - `continue to research` diff --git a/plugins/ralph-specum-codex/skills/ralph-specum-tasks/SKILL.md b/plugins/ralph-specum-codex/skills/ralph-specum-tasks/SKILL.md index 25d8868d..bc734958 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum-tasks/SKILL.md +++ b/plugins/ralph-specum-codex/skills/ralph-specum-tasks/SKILL.md @@ -23,8 +23,8 @@ You are a **coordinator, not a task planner** -- delegate ALL work to a `task-pl 2. Require `requirements.md` and `design.md`. Read `research.md` when present, `.progress.md`, and current state. 3. Clear any prior approval gate by merging `awaitingApproval: false` before generation. 4. Respect `granularity` from state. Allow `--tasks-size fine|coarse` to override it. In quick mode, default unset granularity to `fine`. -5. Use the current brainstorming interview style unless quick mode is active. -6. **Delegate** task planning to a `task-planner` sub-agent. Pass requirements, design, research, and interview context. The sub-agent writes `tasks.md`. Do NOT write tasks.md yourself. +5. 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. +6. **Delegate** task planning to a `task-planner` sub-agent. Pass requirements, design, research, grill-with-docs decisions, and interview context. The sub-agent writes `tasks.md`. Do NOT write tasks.md yourself. 7. Read the sub-agent's output and validate it exists. 8. Count tasks and merge state with: - `phase: "tasks"` @@ -47,7 +47,7 @@ Use atomic tasks with exact file targets, explicit success criteria, verificatio - After writing `tasks.md`, name `tasks.md` and summarize the task plan briefly. - End with exactly one explicit choice prompt: - - `approve current artifact` - - `request changes` - `continue to implementation` + - `run review agent` + - `request changes` - Treat `continue to implementation` as approval of `tasks.md`. diff --git a/plugins/ralph-specum-codex/skills/ralph-specum-tasks/agents/openai.yaml b/plugins/ralph-specum-codex/skills/ralph-specum-tasks/agents/openai.yaml index 3970df88..c6a9bd83 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum-tasks/agents/openai.yaml +++ b/plugins/ralph-specum-codex/skills/ralph-specum-tasks/agents/openai.yaml @@ -1,6 +1,6 @@ interface: display_name: "Ralph Specum Tasks" short_description: "Generate implementation tasks for an active spec" - default_prompt: "Use $ralph-specum-tasks to write tasks.md, then ask me to `approve current artifact`, `request changes`, or `continue to implementation`." + default_prompt: "Use $ralph-specum-tasks to run bundled grill-with-docs behavior, write tasks.md, then ask me to `continue to implementation`, `run review agent`, or `request changes`." policy: allow_implicit_invocation: false diff --git a/plugins/ralph-specum-codex/skills/ralph-specum/SKILL.md b/plugins/ralph-specum-codex/skills/ralph-specum/SKILL.md index afecdf54..b1c62c80 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum/SKILL.md +++ b/plugins/ralph-specum-codex/skills/ralph-specum/SKILL.md @@ -69,7 +69,7 @@ If the corresponding helper skill is installed and the user invoked it explicitl After completing any phase artifact (research, requirements, design, tasks), you MUST: 1. Display the walkthrough summary -2. Present the approval prompt (approve / request changes / continue to next) +2. Present the gate prompt 3. **STOP and wait for user response** The ONLY exception is `--quick` mode. Without `--quick`, you MUST NOT auto-continue to the next phase. This is non-negotiable. @@ -80,19 +80,21 @@ The ONLY exception is `--quick` mode. Without `--quick`, you MUST NOT auto-conti - 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 ` + - `run review agent` + - `run prototype` when the artifact is `research.md`, `requirements.md`, or `design.md` + - `request changes` - Treat `continue to ` as approval of the current artifact and permission to proceed. - After `start` or `new`, summarize the resolved spec and stop unless the user explicitly asked for quick or autonomous flow. The next choice should point to `continue to research`. ## Current Workflow Expectations -- Use brainstorming-style interviews for research, requirements, design, and tasks when quick mode is not active. +- Use bundled grill-with-docs behavior for research, requirements, design, and tasks when quick mode is not 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. - Route obviously large or cross-cutting efforts to triage before normal spec generation. - Support active epic state via `specs/.current-epic` and per-epic state in `specs/_epics//`. - Treat task planning as POC-first with `[P]` markers for safe parallel work and `[VERIFY]` checkpoints for explicit quality validation. - Support VE tasks when the plan needs autonomous end-to-end verification. +- After research, requirements, and design walkthroughs, allow an optional prototype gate before the next phase choice. If `$prototype` exists, use it. Otherwise run the bundled prototype behavior inline and record the result in `.progress.md`. - During implementation, recompute task counts from disk, resume from the first incomplete task, and prefer task file truth over stale state. - Native task sync is part of the current Ralph execution model. Keep Codex wording aligned with that behavior without promising Claude-only hook mechanics. diff --git a/plugins/ralph-specum-codex/skills/ralph-specum/agents/openai.yaml b/plugins/ralph-specum-codex/skills/ralph-specum/agents/openai.yaml index 60d71cb6..2d4dc5fb 100644 --- a/plugins/ralph-specum-codex/skills/ralph-specum/agents/openai.yaml +++ b/plugins/ralph-specum-codex/skills/ralph-specum/agents/openai.yaml @@ -1,6 +1,6 @@ interface: display_name: "Ralph Specum" short_description: "Run Ralph Specum workflows in Codex" - default_prompt: "Use $ralph-specum to run Ralph step by step in this repo and ask me to `approve current artifact`, `request changes`, or `continue to `." + default_prompt: "Use $ralph-specum to run Ralph step by step in this repo. In normal mode, use bundled grill-with-docs behavior, then offer continue, `run review agent`, `run prototype` when available, or `request changes`." policy: allow_implicit_invocation: false diff --git a/plugins/ralph-specum/.claude-plugin/plugin.json b/plugins/ralph-specum/.claude-plugin/plugin.json index 9affe412..81a320ea 100644 --- a/plugins/ralph-specum/.claude-plugin/plugin.json +++ b/plugins/ralph-specum/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "ralph-specum", - "version": "4.9.1", + "version": "4.10.2", "description": "Spec-driven development with task-by-task execution. Research, requirements, design, tasks, autonomous implementation, and epic triage for multi-spec feature decomposition.", "author": { "name": "tzachbon" diff --git a/plugins/ralph-specum/commands/design.md b/plugins/ralph-specum/commands/design.md index 3d415908..d768ee6d 100644 --- a/plugins/ralph-specum/commands/design.md +++ b/plugins/ralph-specum/commands/design.md @@ -41,7 +41,7 @@ Parse Intent Classification and all prior interview responses to skip already-an ### Brainstorming Dialogue -Apply adaptive dialogue from `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md`. Ask context-driven questions one at a time. +Invoke `Skill({ skill: "ralph-specum:grill-with-docs" })` first. If it cannot be loaded, fall back to `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md`. Ask context-driven questions one at a time. **Design Exploration Territory** (hints, not a script): - **Architecture fit** -- extend existing architecture, create isolated module, or require refactor? @@ -139,16 +139,18 @@ Output: $PWD/specs/$spec/design.md If `--quick`, skip to Step 6. Ask ONE question: "How do you want to proceed?" with these options via AskUserQuestion: -1. **Approve** (Recommended) -- Accept artifact as-is, advance to next phase -2. **Run review** -- Spawn spec-reviewer to validate against rubrics, show findings, then loop back to this choice -3. **Request changes** -- Provide specific feedback to revise the artifact - -**If "Approve"**: proceed to Step 6. -**If "Run review"**: Invoke spec-reviewer via Task tool with full design.md content (upstream: research.md + requirements.md). Display findings table. If REVIEW_PASS, note it. If REVIEW_FAIL, show feedback. Then loop back to this same 3-choice question (user decides next action). +1. Continue to tasks (Recommended) +2. Run review agent +3. Run prototype +4. Request changes + +**If "Continue to tasks"**: proceed to Step 6. +**If "Run review agent"**: invoke `spec-reviewer` with full `design.md` content and upstream `research.md` plus `requirements.md`. Display findings, then loop back to this same question. +**If "Run prototype"**: invoke `Skill({ skill: "ralph-specum:prototype" })`, run a throwaway prototype using `design.md` and upstream context, write the result to `.progress.md`, re-display the walkthrough, then ask again. **If "Request changes" or "Other"**: 1. Ask what to change -2. Re-invoke architect-reviewer using **cleanup-and-recreate** team pattern (TeamDelete old -> TeamCreate new -> spawn with feedback -> wait -> shutdown -> TeamDelete) -3. Re-display walkthrough, ask again with same 3 choices. Loop until approved. +2. Re-invoke architect-reviewer using **cleanup-and-recreate** team pattern +3. Re-display walkthrough, ask again with the same 4 choices. Loop until approved. ## Step 6: Finalize diff --git a/plugins/ralph-specum/commands/requirements.md b/plugins/ralph-specum/commands/requirements.md index 5d573829..a8974c73 100644 --- a/plugins/ralph-specum/commands/requirements.md +++ b/plugins/ralph-specum/commands/requirements.md @@ -40,7 +40,7 @@ Parse Intent Classification and prior interview responses to skip already-answer ### Brainstorming Dialogue -Apply adaptive dialogue from `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md`. Ask context-driven questions one at a time. +Invoke `Skill({ skill: "ralph-specum:grill-with-docs" })` first. If it cannot be loaded, fall back to `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md`. Ask context-driven questions one at a time. **Requirements Exploration Territory** (hints, not a script): - **Primary users** -- who will use this feature? Developers, end users, specific roles? @@ -136,16 +136,18 @@ Output: $PWD/specs/$spec/requirements.md If `--quick`, skip to Step 6. Ask ONE question: "How do you want to proceed?" with these options via AskUserQuestion: -1. **Approve** (Recommended) -- Accept artifact as-is, advance to next phase -2. **Run review** -- Spawn spec-reviewer to validate against rubrics, show findings, then loop back to this choice -3. **Request changes** -- Provide specific feedback to revise the artifact - -**If "Approve"**: proceed to Step 6. -**If "Run review"**: Invoke spec-reviewer via Task tool with full requirements.md content (upstream: research.md). Display findings table. If REVIEW_PASS, note it. If REVIEW_FAIL, show feedback. Then loop back to this same 3-choice question (user decides next action). +1. Continue to design (Recommended) +2. Run review agent +3. Run prototype +4. Request changes + +**If "Continue to design"**: proceed to Step 6. +**If "Run review agent"**: invoke `spec-reviewer` with full `requirements.md` content and upstream `research.md`. Display findings, then loop back to this same question. +**If "Run prototype"**: invoke `Skill({ skill: "ralph-specum:prototype" })`, run a throwaway prototype using `requirements.md` and upstream context, write the result to `.progress.md`, re-display the walkthrough, then ask again. **If "Request changes" or "Other"**: 1. Ask what to change -2. Re-invoke product-manager using **cleanup-and-recreate** team pattern (TeamDelete old -> TeamCreate new -> spawn with feedback -> wait -> shutdown -> TeamDelete) -3. Re-display walkthrough, ask again with same 3 choices. Loop until approved. +2. Re-invoke product-manager using **cleanup-and-recreate** team pattern +3. Re-display walkthrough, ask again with the same 4 choices. Loop until approved. ## Step 6: Finalize diff --git a/plugins/ralph-specum/commands/research.md b/plugins/ralph-specum/commands/research.md index 8249b571..fbf5bc20 100644 --- a/plugins/ralph-specum/commands/research.md +++ b/plugins/ralph-specum/commands/research.md @@ -43,7 +43,7 @@ Read `.progress.md` and parse: ### Brainstorming Dialogue -Apply adaptive dialogue from `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md`. Ask context-driven questions one at a time, adapting to prior answers. +Invoke `Skill({ skill: "ralph-specum:grill-with-docs" })` first. If it cannot be loaded, fall back to `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md`. Ask context-driven questions one at a time, adapting to prior answers. **Research Exploration Territory** (hints, not a script): - **Technical approach preference** -- follow existing patterns or introduce new ones? @@ -153,13 +153,15 @@ Output: $PWD/specs/$spec/research.md If `--quick`, skip to Step 7. Ask ONE question: "How do you want to proceed?" with these options via AskUserQuestion: -1. **Approve** (Recommended) -- Accept artifact as-is, advance to next phase -2. **Run review** -- Spawn spec-reviewer to validate against rubrics, show findings, then loop back to this choice -3. **Request changes** -- Provide specific feedback to revise the artifact - -**If "Approve"**: proceed to Step 7. -**If "Run review"**: Invoke spec-reviewer via Task tool with full research.md content (upstream: none). Display findings table. If REVIEW_PASS, note it. If REVIEW_FAIL, show feedback. Then loop back to this same 3-choice question (user decides next action). -**If "Request changes" or "Other"**: Ask what to change, invoke subagents with feedback, re-merge, re-display walkthrough, ask again with same 3 choices. Loop until approved. +1. Continue to requirements (Recommended) +2. Run review agent +3. Run prototype +4. Request changes + +**If "Continue to requirements"**: proceed to Step 7. +**If "Run review agent"**: invoke `spec-reviewer` with full `research.md` content and goal context. Display findings, then loop back to this same question. +**If "Run prototype"**: invoke `Skill({ skill: "ralph-specum:prototype" })`, run a throwaway prototype using `research.md` and goal context, write the result to `.progress.md`, re-display the walkthrough, then ask again. +**If "Request changes" or "Other"**: ask what to change, invoke subagents with feedback, re-merge, re-display the walkthrough, ask again. ## Step 7: Finalize diff --git a/plugins/ralph-specum/commands/start.md b/plugins/ralph-specum/commands/start.md index 2edef4c7..c3d05b9a 100644 --- a/plugins/ralph-specum/commands/start.md +++ b/plugins/ralph-specum/commands/start.md @@ -182,7 +182,7 @@ Continuing... ``` If no skills match: `- No skills matched` 10. Update Spec Index: `./plugins/ralph-specum/hooks/scripts/update-spec-index.sh --quiet` -11. **Goal Interview** -- Read `${CLAUDE_PLUGIN_ROOT}/references/goal-interview.md` and follow brainstorming dialogue +11. **Goal Interview** -- Invoke `Skill({ skill: "ralph-specum:grill-with-docs" })` first. If it cannot be loaded, use `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md` 12. **Team Research Phase** -- Read `${CLAUDE_PLUGIN_ROOT}/references/parallel-research.md` and follow the dispatch pattern 13. **Skill Discovery Pass 2 (Post-Research Retry)** -- Re-scan skills with enriched context after research completes: @@ -246,8 +246,16 @@ Output: $basePath/research.md **Feasibility**: [High/Medium/Low] | **Risk**: [High/Medium/Low] | **Effort**: [S/M/L/XL] ``` -Then STOP. Output: `-> Next: Run /ralph-specum:requirements` -End response immediately. +Then ask ONE question: "How do you want to proceed?" with these options via AskUserQuestion: +1. Continue to requirements (Recommended) +2. Run review agent +3. Run prototype +4. Request changes + +If Continue to requirements, display `-> Next: Run /ralph-specum:requirements` and stop. +If Run review agent, invoke `spec-reviewer` with full `research.md` and goal context. Show findings, then ask again. +If Run prototype, invoke `Skill({ skill: "ralph-specum:prototype" })`, run a throwaway prototype using `research.md` and goal context, write the result to `.progress.md`, redisplay the walkthrough, and ask again. +If Request changes, ask what to change, update `research.md`, redisplay the walkthrough, and ask again. ## Step 5: Quick Mode Flow diff --git a/plugins/ralph-specum/commands/tasks.md b/plugins/ralph-specum/commands/tasks.md index 82b8dc5c..8db69fb1 100644 --- a/plugins/ralph-specum/commands/tasks.md +++ b/plugins/ralph-specum/commands/tasks.md @@ -47,7 +47,7 @@ Parse Intent Classification and all prior interview responses to skip already-an ### Brainstorming Dialogue -Apply adaptive dialogue from `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md`. Ask context-driven questions one at a time. +Invoke `Skill({ skill: "ralph-specum:grill-with-docs" })` first. If it cannot be loaded, fall back to `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md`. Ask context-driven questions one at a time. **Tasks Exploration Territory** (hints, not a script): - **Testing thoroughness** -- minimal POC-only tests, standard unit + integration, or comprehensive E2E? @@ -174,16 +174,16 @@ Output: $PWD/specs/$spec/tasks.md If `--quick`, skip to Step 6. Ask ONE question: "How do you want to proceed?" with these options via AskUserQuestion: -1. **Approve** (Recommended) -- Accept artifact as-is, advance to next phase -2. **Run review** -- Spawn spec-reviewer to validate against rubrics, show findings, then loop back to this choice -3. **Request changes** -- Provide specific feedback to revise the artifact +1. Continue to implementation (Recommended) +2. Run review agent +3. Request changes -**If "Approve"**: proceed to Step 6. -**If "Run review"**: Invoke spec-reviewer via Task tool with full tasks.md content (upstream: design.md + requirements.md). Display findings table. If REVIEW_PASS, note it. If REVIEW_FAIL, show feedback. Then loop back to this same 3-choice question (user decides next action). +**If "Continue to implementation"**: proceed to Step 6. +**If "Run review agent"**: invoke `spec-reviewer` with full `tasks.md` content and upstream `design.md` plus `requirements.md`. Display findings, then loop back to this same question. **If "Request changes" or "Other"**: 1. Ask what to change -2. Re-invoke task-planner using **cleanup-and-recreate** team pattern (TeamDelete old -> TeamCreate new -> spawn with feedback + current tasks.md -> wait -> shutdown -> TeamDelete) -3. Re-display walkthrough, ask again with same 3 choices. Loop until approved. +2. Re-invoke task-planner using **cleanup-and-recreate** team pattern +3. Re-display walkthrough, ask again with the same 3 choices. Loop until approved. ## Step 6: Finalize diff --git a/plugins/ralph-specum/skills/grill-with-docs/SKILL.md b/plugins/ralph-specum/skills/grill-with-docs/SKILL.md new file mode 100644 index 00000000..6467d21c --- /dev/null +++ b/plugins/ralph-specum/skills/grill-with-docs/SKILL.md @@ -0,0 +1,60 @@ +--- +name: grill-with-docs +description: This skill should be used when Ralph Specum needs to question a phase plan against project docs, code terminology, CONTEXT.md, or ADR decisions before generating research, requirements, design, or tasks. +version: 0.1.0 +--- + +# Grill With Docs + +Stress-test the active Ralph phase against the repo language and existing decisions before artifact generation. + +## Workflow + +1. Inspect existing docs first: + - `CONTEXT-MAP.md` + - `CONTEXT.md` + - `docs/adr/` + - phase artifacts in the active spec + - nearby code when the answer may already exist +2. If the code or docs answer the question, use that evidence and do not ask. +3. If ambiguity remains, ask one native question at a time. +4. Give the recommended answer first. +5. Resolve dependencies between decisions before moving to the next question. +6. Capture stable terminology in `CONTEXT.md` as decisions settle. +7. Create ADRs only when the decision is hard to reverse, surprising without context, and based on a real tradeoff. + +## Question Rules + +- Ask one question at a time. +- Use native question UI when available. +- Provide 2 to 3 choices. +- Put the recommended choice first. +- Add a short impact note for each choice. +- Do not ask if codebase inspection can answer. +- Stop when the phase has enough context to proceed. + +## CONTEXT.md Rules + +Use `CONTEXT.md` only as a glossary. + +Include: +- terms +- role names +- domain relationships +- boundary definitions + +Do not include: +- implementation details +- task plans +- architecture choices +- scratch notes + +## ADR Rules + +Create an ADR only when all are true: + +1. Cost to change later is meaningful. +2. Future reader would wonder why. +3. Alternatives existed and one was chosen for a reason. + +If any condition is false, skip ADR. diff --git a/plugins/ralph-specum/skills/prototype/SKILL.md b/plugins/ralph-specum/skills/prototype/SKILL.md new file mode 100644 index 00000000..390ff067 --- /dev/null +++ b/plugins/ralph-specum/skills/prototype/SKILL.md @@ -0,0 +1,43 @@ +--- +name: prototype +description: This skill should be used when Ralph Specum needs a throwaway prototype to validate research, requirements, or design before continuing to the next spec phase. +version: 0.1.0 +--- + +# Prototype + +Build throwaway proof code to answer one question before committing to the next phase. + +## Pick The Question + +Identify the question from the current artifact and upstream context: + +- Logic or state model question: build a small terminal prototype. +- UI or interaction question: build several small UI variants in the app's existing routing style. +- Ambiguous question: inspect nearby code. Default to logic for backend modules and UI for pages or components. + +State the prototype question at the top of the artifact. + +## Rules + +1. Mark prototype files as throwaway. +2. Put prototype code close to the related module or route. +3. Use one command to run it. +4. Keep state in memory unless the question is about persistence. +5. Skip tests and polish. +6. Show the relevant state after each action or variant switch. +7. Do not leave prototype code as production code. + +## Result Capture + +After prototype work, append to `.progress.md`: + +```markdown +## Prototype Result +- Question: +- Artifact: +- Result: +- Decision: +``` + +Then redisplay the current phase walkthrough and ask the phase gate question again. diff --git a/plugins/ralph-specum/skills/spec-workflow/SKILL.md b/plugins/ralph-specum/skills/spec-workflow/SKILL.md index 43951c78..5dbd48e7 100644 --- a/plugins/ralph-specum/skills/spec-workflow/SKILL.md +++ b/plugins/ralph-specum/skills/spec-workflow/SKILL.md @@ -26,6 +26,23 @@ start/new -> research -> requirements -> design -> tasks -> implement Each phase produces a markdown artifact in `./specs//`. Normal mode pauses for approval between phases. Quick mode runs all phases then auto-starts execution. +### Gate Rules + +Invoke `ralph-specum:grill-with-docs` first for normal mode interviews. If it cannot be loaded, fall back to `interview-framework`. + +Research, requirements, and design use these walkthrough choices: +- Continue to next phase +- Run review agent +- Run prototype +- Request changes + +Tasks use these walkthrough choices: +- Continue to implementation +- Run review agent +- Request changes + +Prototype mode uses `Skill({ skill: "ralph-specum:prototype" })`, runs a throwaway prototype against the current artifact plus upstream context, writes the result to `.progress.md`, then redisplays the walkthrough and asks again. + ### Phase Commands | Command | Agent | Output | Purpose | diff --git a/tests/codex-platform.bats b/tests/codex-platform.bats index 7e0ee1eb..4f61d4c7 100644 --- a/tests/codex-platform.bats +++ b/tests/codex-platform.bats @@ -151,6 +151,61 @@ for skill in (ROOT / "plugins/ralph-specum-codex/skills").glob("ralph-specum*"): [[ "$package_text" == *"Installation"* ]] } +@test "codex platform: docs expose grill-with-docs and prototype gates" { + local root + root="$(repo_root)" + + assert_python ' +files = { + "README.md": ["grill-with-docs", "prototype"], + "plugins/ralph-specum-codex/README.md": ["grill-with-docs", "prototype"], + "plugins/ralph-specum-codex/skills/ralph-specum/SKILL.md": ["grill-with-docs"], + "plugins/ralph-specum-codex/skills/ralph-specum-start/SKILL.md": ["grill-with-docs"], + "plugins/ralph-specum-codex/skills/ralph-specum-research/SKILL.md": ["grill-with-docs", "run review agent", "run prototype", "request changes", "continue to requirements"], + "plugins/ralph-specum-codex/skills/ralph-specum-requirements/SKILL.md": ["grill-with-docs", "run review agent", "run prototype", "request changes", "continue to design"], + "plugins/ralph-specum-codex/skills/ralph-specum-design/SKILL.md": ["grill-with-docs", "run review agent", "run prototype", "request changes", "continue to tasks"], + "plugins/ralph-specum-codex/skills/ralph-specum-tasks/SKILL.md": ["grill-with-docs", "run review agent", "request changes", "continue to implementation"], + "plugins/ralph-specum-codex/assets/bootstrap/AGENTS.md": ["grill-with-docs", "prototype"], +} + +for relpath, tokens in files.items(): + text = (ROOT / relpath).read_text() + for token in tokens: + assert token in text, {"path": relpath, "token": token} +' "$root" +} + +@test "ralph plugin: ships grill and prototype gate skills" { + local root + root="$(repo_root)" + + [ -f "$root/plugins/ralph-specum/skills/grill-with-docs/SKILL.md" ] + [ -f "$root/plugins/ralph-specum/skills/prototype/SKILL.md" ] + + assert_python ' +required = { + "plugins/ralph-specum/commands/research.md": ["ralph-specum:grill-with-docs", "ralph-specum:prototype"], + "plugins/ralph-specum/commands/requirements.md": ["ralph-specum:grill-with-docs", "ralph-specum:prototype"], + "plugins/ralph-specum/commands/design.md": ["ralph-specum:grill-with-docs", "ralph-specum:prototype"], + "plugins/ralph-specum/commands/tasks.md": ["ralph-specum:grill-with-docs"], + "plugins/ralph-specum/commands/start.md": ["ralph-specum:grill-with-docs", "ralph-specum:prototype"], +} + +for relpath, tokens in required.items(): + text = (ROOT / relpath).read_text() + for token in tokens: + assert token in text, {"path": relpath, "token": token} + +for relpath in [ + "plugins/ralph-specum/skills/grill-with-docs/SKILL.md", + "plugins/ralph-specum/skills/prototype/SKILL.md", +]: + text = (ROOT / relpath).read_text() + assert "name:" in text + assert "description:" in text +' "$root" +} + @test "codex platform: copied install layout remains usable" { local proot temp_codex_home skill proot="$(plugin_root)" @@ -175,6 +230,10 @@ for skill in (ROOT / "plugins/ralph-specum-codex/skills").glob("ralph-specum*"): validator="/mnt/c/Users/ADMIN/.codex/skills/.system/skill-creator/scripts/quick_validate.py" [ -f "$validator" ] || skip + run python3 - <<'PY' +import yaml +PY + [ "$status" -eq 0 ] || skip while IFS= read -r skill; do run python3 "$validator" "$proot/skills/$skill" @@ -255,12 +314,12 @@ for command, token in required_tokens.items(): assert_python ' expected = { - "ralph-specum": ["approve current artifact", "request changes", "continue to "], + "ralph-specum": ["grill-with-docs", "run review agent", "run prototype", "request changes"], "ralph-specum-start": ["wait for explicit direction", "research"], - "ralph-specum-research": ["approve current artifact", "continue to requirements"], - "ralph-specum-requirements": ["approve current artifact", "continue to design"], - "ralph-specum-design": ["approve current artifact", "continue to tasks"], - "ralph-specum-tasks": ["approve current artifact", "continue to implementation"], + "ralph-specum-research": ["grill-with-docs", "continue to requirements", "run review agent", "run prototype", "request changes"], + "ralph-specum-requirements": ["grill-with-docs", "continue to design", "run review agent", "run prototype", "request changes"], + "ralph-specum-design": ["grill-with-docs", "continue to tasks", "run review agent", "run prototype", "request changes"], + "ralph-specum-tasks": ["grill-with-docs", "continue to implementation", "run review agent", "request changes"], "ralph-specum-cancel": ["whether anything was removed", "exactly what if so"], "ralph-specum-triage": ["approve current artifact", "continue to the next spec"], "ralph-specum-refactor": ["approve current artifact", "continue to implementation"], @@ -281,9 +340,9 @@ for skill, tokens in expected.items(): pairs = { "start": ["quick mode", "granularity", ".current-epic", "awaitingApproval"], "triage": ["specs/_epics", ".current-epic", ".epic-state.json", "dependencies"], - "research": ["brainstorming", "research.md", "verification tooling"], - "requirements": ["brainstorming", "requirements.md", "awaitingApproval"], - "design": ["brainstorming", "design.md", "awaitingApproval"], + "research": ["grill-with-docs", "research.md", "verification tooling"], + "requirements": ["grill-with-docs", "requirements.md", "awaitingApproval"], + "design": ["grill-with-docs", "design.md", "awaitingApproval"], "tasks": ["granularity", "[P]", "[VERIFY]", "VE tasks", "taskIndex: first incomplete or totalTasks"], "implement": ["[P]", "[VERIFY]", "VE tasks", "tasks.md", "approval", "quick mode", "explicit user direction", "file sets do not overlap", "Marker syntax must be explicitly present"], "status": [".current-epic", "approval state", "granularity", "there is no active spec"], @@ -308,10 +367,10 @@ for name, tokens in pairs.items(): assert_python ' expected = { - "research": ["approve current artifact", "request changes", "continue to requirements"], - "requirements": ["approve current artifact", "request changes", "continue to design"], - "design": ["approve current artifact", "request changes", "continue to tasks"], - "tasks": ["approve current artifact", "request changes", "continue to implementation"], + "research": ["run review agent", "run prototype", "request changes", "continue to requirements"], + "requirements": ["run review agent", "run prototype", "request changes", "continue to design"], + "design": ["run review agent", "run prototype", "request changes", "continue to tasks"], + "tasks": ["run review agent", "request changes", "continue to implementation"], "triage": ["approve current artifact", "request changes", "continue to the next spec"], "refactor": ["approve current artifact", "request changes", "continue to implementation"], } @@ -342,7 +401,13 @@ assert "Use only when the user explicitly invokes `$ralph-specum`" in primary assert "## Response Handoff" in primary assert "epic.md" not in primary.split("## Current Workflow Expectations")[0] assert "epic.md" not in workflow.split("Treat `continue to ` as approval of the current artifact.")[0] -assert "Wait for explicit direction to continue to research" in workflow +assert "grill-with-docs" in bootstrap +assert "run review agent" in bootstrap +assert "run prototype" in bootstrap +assert "grill-with-docs" in workflow +assert "run review agent" in workflow +assert "run prototype" in workflow +assert "prototype gate" in primary assert "quick_mode_default" in path_resolution assert "Approval Prompt Shape" in state_contract ' "$root" diff --git a/tests/interview-framework.bats b/tests/interview-framework.bats index d07db162..7d005c1d 100644 --- a/tests/interview-framework.bats +++ b/tests/interview-framework.bats @@ -61,11 +61,11 @@ GOAL_INTERVIEW="plugins/ralph-specum/references/goal-interview.md" grep -q "skills/interview-framework/SKILL.md" "$GOAL_INTERVIEW" } -@test "plugin.json version is 4.9.1" { - grep -q '"version": "4.9.1"' "plugins/ralph-specum/.claude-plugin/plugin.json" +@test "plugin.json version is 4.10.2" { + grep -q '"version": "4.10.2"' "plugins/ralph-specum/.claude-plugin/plugin.json" } -@test "marketplace.json ralph-specum version is 4.9.1" { +@test "marketplace.json ralph-specum version is 4.10.2" { version=$(jq -r '.plugins[] | select(.name == "ralph-specum") | .version' ".claude-plugin/marketplace.json") - [ "$version" = "4.9.1" ] + [ "$version" = "4.10.2" ] }