Ralph Specum

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

.claude/skills/Command Development

.claude/skills/Hook Development

.claude/skills/MCP Integration

.claude/skills/Plugin Settings

.claude/skills/Plugin Structure

Audit 0.4.1 · source sha a73b124937d9 · 18 Oct 2026Report an issue or request a re-scan

• Publishertzachbon GitHub userOwner of the repository this skill is read from
• Source foldertzachbon/smart-ralph/plugins/ralph-specum-codex/skills/ralph-specumThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdicta73b124937d9A new audit runs when the source changes
• Repository statusNot archivedLast push 32 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use only when the user explicitly invokes `$ralph-specum`, requests Ralph Specum in Codex, or asks Ralph Specum to handle a named phase or optional prototype.

---
name: ralph-specum
description: Use only when the user explicitly invokes `$ralph-specum`, requests Ralph Specum in Codex, or asks Ralph Specum to handle a named phase or optional prototype.
metadata:
  surface: primary
---

# Ralph Specum

Use this as the primary Codex surface for Ralph Specum. It carries the full reusable workflow and can handle the entire command surface directly when helper skills are not installed.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill: take the directory containing `SKILL.md`, then its parent `skills` directory, then the next parent. Never derive the plugin root from the project working directory.

## Read These References

- `"$RALPH_CODEX_PLUGIN_ROOT/references/workflow.md"` for the phase flow, branch and worktree behavior, quick mode, and command routing
- `"$RALPH_CODEX_PLUGIN_ROOT/references/state-contract.md"` for `.ralph-state.json`, `.progress.md`, commit rules, and resume semantics
- `"$RALPH_CODEX_PLUGIN_ROOT/references/path-resolution.md"` for `specs_dirs`, `.current-spec`, ambiguity handling, and default directory behavior
- `"$RALPH_CODEX_PLUGIN_ROOT/references/parity-matrix.md"` for Claude-to-Codex feature translation and command mapping
- `"$RALPH_CODEX_PLUGIN_ROOT/references/prototype-coordinator.md"` for direct, suggested, resume, quick, cancel, and prototype handoff behavior
- `"$RALPH_CODEX_PLUGIN_ROOT/skills/interview-framework-codex/SKILL.md"` and its required algorithm and domain-modeling references for every normal-mode phase interview

## Use These Helpers

- `"$RALPH_CODEX_PLUGIN_ROOT/scripts/resolve_spec_paths.py"` for spec roots, current spec, and unique or ambiguous name resolution
- `"$RALPH_CODEX_PLUGIN_ROOT/scripts/merge_state.py"` for safe top-level state merges
- `"$RALPH_CODEX_PLUGIN_ROOT/scripts/count_tasks.py"` for task counts and next incomplete task
- `"$RALPH_CODEX_PLUGIN_ROOT/scripts/phase_gate.py"` for mode, skill-load, interview, parent-delegation, and artifact-write gates
- `"$RALPH_CODEX_PLUGIN_ROOT/scripts/locked_state.py"` for locked state and `activePrototypes` mutations
- `"$RALPH_CODEX_PLUGIN_ROOT/scripts/prototype_records.py"` for reviewed immutable prototype records and downstream selection
- `"$RALPH_CODEX_PLUGIN_ROOT/scripts/prototype_harness.py"` for bounded builder control outcomes and retry metadata
- `"$RALPH_CODEX_PLUGIN_ROOT/templates/"` for the canonical Ralph markdown file shapes
- `"$RALPH_CODEX_PLUGIN_ROOT/assets/bootstrap/"` when the user wants optional project-local Codex guidance

## Primary Routing

Handle these intents directly:

| Intent | Action |
|--------|--------|
| Start, new, resume, quick mode | Follow the start flow in `../../references/workflow.md` |
| Triage | Delegate to `triage-analyst` sub-agent to decompose into epic and specs |
| Research | Delegate to `research-analyst` sub-agent to write `research.md` |
| Requirements | Delegate to `product-manager` sub-agent to write `requirements.md` |
| Prototype | Follow `../../references/prototype-coordinator.md`, or route an explicit helper request to `$ralph-specum-prototype` |
| Design | Delegate to `architect-reviewer` sub-agent to write `design.md` |
| Tasks | Delegate to `task-planner` sub-agent to write `tasks.md` |
| Implement | Delegate each task to `spec-executor` sub-agent until complete or blocked |
| Status | Show active spec, backlog state, and per-root listing |
| Switch | Update `.current-spec` only |
| Cancel | Stop execution and clean up state, confirm before destructive delete |
| Index | Generate `specs/.index/` component and external specs |
| Refactor | Delegate to `refactor-specialist` sub-agent to update spec files |
| Feedback | Open or draft GitHub feedback |
| Help | Summarize the surface and next commands |

If the corresponding helper skill is installed and the user invoked it explicitly, keep behavior aligned with that helper. If not, perform the action here.

## Core Rules

0. **You are a coordinator, not a doer.** Delegate each phase to the appropriate sub-agent and never write spec artifacts (`research.md`, `requirements.md`, `design.md`, or `tasks.md`) yourself. Apply the shared hard-transition invariant to only `start`, `triage`, `research`, `requirements`, `design`, and `tasks`. For only `start`, `triage`, `research`, `requirements`, `design`, and `tasks`, enforce that invariant. For those phases, gather context, discover and preload contracts, run the interview, obtain final approval, pass the gate, delegate, validate the output, and present results for artifact approval. Keep the existing delegation flows for `implement` and `refactor` unchanged; the new phase gates do not apply to them.
1. Keep the Ralph disk contract stable.
2. Treat `.claude/ralph-specum.local.md` as the settings source when present.
3. Default to `./specs` when no valid config exists.
4. Keep `.current-spec` in the default specs root.
5. Merge state fields. Do not replace the whole state object.
6. Preserve `source`, `name`, `goal`, `basePath`, `phase`, `taskIndex`, `totalTasks`, `taskIteration`, `maxTaskIterations`, `globalIteration`, `maxGlobalIterations`, `commitSpec`, and `relatedSpecs`.
7. Also preserve newer state fields when present, especially `awaitingApproval`, `quickMode`, `granularity`, `epicName`, `discoveredSkills`, and native task sync metadata.
8. Write `.progress.md` after every phase and after every implementation attempt.
9. Keep pre-delegation interview approval separate from post-generation artifact approval.
10. Honor the `Commit` line in tasks during implementation unless the user explicitly disables task commits.
11. Use branch creation or worktree creation when the user asks for branch isolation or the repo policy requires it.
12. Run `phase_gate.py mode` at entry to every affected phase. Only exact `--quick` enables quick mode; exact `--interactive` clears it. Reject both together, `-q`, variants, and natural-language substitutes. No flags normalize invalid legacy quick state to interac

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-18
   !CAUTION B 89 / 100

   first audit · source a73b124937d9

Questions about Ralph Specum

• github.com/tzachbon/smart-ralph/tree/main/plugins/ralph-specum-c — the audited source at commit a73b124937d9 and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology