# Ralph Specum Status

Should be used only when the user explicitly asks to use `$ralph-specum-status`, or...

- Repository: https://github.com/tzachbon/smart-ralph (566 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add tzachbon/smart-ralph --skill ralph-specum-status -g -a claude-code -y`
Codex: `npx skills add tzachbon/smart-ralph --skill ralph-specum-status -g -a codex -y`
Cursor: `npx skills add tzachbon/smart-ralph --skill ralph-specum-status -g -a cursor -y`
Gemini CLI: `npx skills add tzachbon/smart-ralph --skill ralph-specum-status -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add tzachbon/smart-ralph`

## Description

This skill should be used only when the user explicitly asks to use `$ralph-specum-status`, or explicitly asks Ralph Specum in Codex for status or active spec progress.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Ralph Specum Status

Use this to report Ralph state across configured spec roots.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill by resolving two parent directories from the `SKILL.md` directory. Never derive it from the project working directory.

## Contract

- Read `.claude/ralph-specum.local.md` when present
- Default specs root is `./specs`
- `.current-spec` lives in the default specs root
- Hidden directories do not count as specs

## Action

1. Resolve configured roots.
2. Read `.current-spec` to identify the active spec.
   - If `.current-spec` is missing or empty, report that there is no active spec and continue listing specs across roots.
3. Read `specs/.current-epic` when present and summarize epic status.
4. For each spec directory, inspect:
   - `.ralph-state.json`
   - `research.md`
   - `requirements.md`
   - `design.md`
   - `tasks.md`
5. When state exists, use the resolved spec path as `basePath`, run `"$RALPH_CODEX_PLUGIN_ROOT/scripts/prototype_records.py" reconcile --base-path "$BASE_PATH" --state "$BASE_PATH/.ralph-state.json"`, then re-read state. Never construct `specs/<name>` after resolution.
6. Inventory prototype records in lexical order:
   - Read `activePrototypes`, treating a missing field as an empty map.
   - List `prototypes/.*.candidate.md`, immutable `prototypes/*.md` finals, and visible or dot-prefixed `*.quarantine.md` files.
   - Parse candidates and finals with `prototype_records.py parse`; use `select-downstream` with state to derive blockers and stale dependencies.
7. If `tasks.md` exists, count completed and incomplete tasks.
8. Group results by spec root.
9. Show the active spec, current phase, backlog state, approval state, granularity when present, and which artifacts exist.

## Output

The rest: https://github.com/tzachbon/smart-ralph/blob/HEAD/plugins/ralph-specum-codex/skills/ralph-specum-status/SKILL.md