git:20260408.1b33202 to git:20260828.cbfd12c

18 added, 10 removed. Audit A to A.

---

name: ralph-specum-start

description: This skill should be used only when the user explicitly asks to use `$ralph-specum-start`, or explicitly asks Ralph Specum in Codex to start or resume a spec.

metadata:

surface: helper

action: start

---

# Ralph Specum Start

Use this for the `start` and `new` entrypoints.

## Contract

- Read `.claude/ralph-specum.local.md` when present

- Default specs root is `./specs`

- Keep `.current-spec` in the default specs root

- Keep the standard Ralph files stable

- Merge `.ralph-state.json`. Do not replace the full object

## Action

- 1. Parse explicit name, goal, `--quick`, commit flags, optional specs root, and optional `--tasks-size fine|coarse`.

+ 1. Parse explicit name, goal, exact `--quick` or exact `--interactive`, commit flags, optional specs root, and optional `--tasks-size fine|coarse`. Reject both mode flags together, `-q`, variants, and natural-language substitutes.

2. Resolve the target by explicit path, exact name, or `.current-spec`.

3. If the same name exists in multiple configured roots, stop and require a full path.

4. Check active epic context from `specs/.current-epic` when no explicit spec was chosen.

5. For large or cross-cutting goals, route to triage instead of forcing a single spec.

6. `new` is an alias here. Create the spec directory if needed.

7. Initialize or merge state with:

- `source: "spec"`

- `name`

+ - exact `goal` text used by the context gate

- `basePath`

- `phase: "research"`

- `taskIndex: 0`

- `totalTasks: 0`

- `taskIteration: 1`

- `maxTaskIterations: settings default or 5`

- `globalIteration: 1`

- `maxGlobalIterations: 100`

- `commitSpec: settings auto_commit_spec or true`

- `relatedSpecs: []`

- - `awaitingApproval: true` when the run will stop after setup and wait for explicit direction

- - `awaitingApproval: false` when quick mode or explicit autonomy will continue without pausing

+ - `awaitingApproval: false` while the goal interview is active

- preserve or set `quickMode`

- preserve or set `granularity` when `--tasks-size` was supplied

- preserve or set `epicName` when starting from an epic suggestion

8. Update `.current-spec`.

- 9. Write `.progress.md` with goal, current phase, next step, blockers, learnings, and skill discovery results when used.

+ 9. Write `.progress.md` with goal, current phase, next step, blockers, learnings, and skill discovery results.

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.

+ 11. Run `scripts/phase_gate.py mode STATE` with the exact supplied mode flag. No flag normalizes invalid legacy quick state to interactive.

+ 12. Run skill discovery pass 1 against the goal. Collect plugin skills, project `.agents/skills`, project `.claude/skills`, and the current Codex harness catalog. Always select explicitly named skills and record shadowed duplicates.

+ 13. Load `skills/interview-framework-codex/SKILL.md`, its required algorithm and domain-modeling references, and every selected domain contract in both interactive and quick mode. In interactive mode, follow that algorithm for the start goal territory: outcome and observable success, material scope boundaries, critical constraints, and viable high-level approach. Ask no spec-path, branch, task-size, or discoverable question.

+ 14. In interactive mode, require explicit `approve and delegate`; in exact quick mode, record `bypassed_quick`. In both modes, run `phase_gate.py check-delegation` with the current loaded-manifest identity before creating a `research-analyst` child.

+ 15. Pass the absolute helper path, state path, identity tuple, a unique teammate dispatch identity, and the verbatim `phaseSkillLoad` manifest. The child must record its loads and pass `check-agent-write` with that unique identity before writing `research.md`.

+ 16. Validate `research.md`, merge `phase: "research"` and `awaitingApproval: true` in interactive mode or `false` in exact quick mode, update progress, and present artifact approval when interactive.

+ 17. In exact quick mode, record the quick bypass, generate missing artifacts in order, skip normal approval pauses, and continue into implementation in the same run.

## Branch Isolation

- If the user wants isolation, offer a feature branch in place or a worktree with a feature branch.

- If a worktree is created, stop after creation and ask the user to continue from that worktree.

## Response Handoff

- - After creating or resuming the spec, name the resolved spec path and summarize the current state briefly.

- - End with exactly one explicit choice prompt:

+ - After setup in normal mode, begin the goal grill in the same run.

+ - After final `approve and delegate`, dispatch research in the same turn.

+ - After `research.md` in interactive mode, name the file, summarize it, and end with exactly one artifact approval prompt:

+ - `approve current artifact`

- `request changes`

- - `continue to research`

- - Do not run research until the user explicitly asks to continue or explicitly asked for quick or autonomous flow.

+ - `continue to requirements`

+ - With exact `--quick`, do not show this prompt; continue directly through the remaining phases after the gates succeed.

+ - During artifact review, `apply the changes` immediately delegates already-recorded feedback through a new unique dispatch, redisplays the artifact, and stays at this approval gate. Ask one focused change question only when no feedback is pending. Control-only `continue`, `proceed`, and `go ahead` approve nothing.