Agent skill

ralph-specum

Use only when the user explicitly invokes `$ralph-specum`, requests Ralph Specum in Codex, asks Ralph Specum to handle a named phase, or explicitly requests autonomous or quick mode or continuation without pauses.

View SKILL.md on GitHub Repository
Stars 278
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/tzachbon/smart-ralph/tree/main/plugins/ralph-specum-codex/skills/ralph-specum

Metadata

Additional technical details for this skill

surface
primary

SKILL.md

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.

Read These References

  • references/workflow.md for the phase flow, branch and worktree behavior, quick mode, and command routing
  • references/state-contract.md for .ralph-state.json, .progress.md, commit rules, and resume semantics
  • references/path-resolution.md for specs_dirs, .current-spec, ambiguity handling, and default directory behavior
  • references/parity-matrix.md for Claude-to-Codex feature translation and command mapping

Use These Helpers

  • scripts/resolve_spec_paths.py for spec roots, current spec, and unique or ambiguous name resolution
  • scripts/merge_state.py for safe top-level state merges
  • scripts/count_tasks.py for task counts and next incomplete task
  • assets/templates/ for the canonical Ralph markdown file shapes
  • 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
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

  1. You are a coordinator, not a doer. For every phase (research, requirements, design, tasks, implement, triage, refactor), delegate the actual generation work to the appropriate sub-agent. Never write spec artifacts (research.md, requirements.md, design.md, tasks.md) yourself. Your job is to gather context, run the interview, delegate, validate the output, and present results for approval.
  2. Keep the Ralph disk contract stable.
  3. Treat .claude/ralph-specum.local.md as the settings source when present.
  4. Default to ./specs when no valid config exists.
  5. Keep .current-spec in the default specs root.
  6. Merge state fields. Do not replace the whole state object.
  7. Preserve source, name, basePath, phase, taskIndex, totalTasks, taskIteration, maxTaskIterations, globalIteration, maxGlobalIterations, commitSpec, and relatedSpecs.
  8. Also preserve newer state fields when present, especially awaitingApproval, quickMode, granularity, epicName, discoveredSkills, and native task sync metadata.
  9. Write .progress.md after every phase and after every implementation attempt.
  10. Honor approval checkpoints between phases unless quick mode is active.
  11. Honor the Commit line in tasks during implementation unless the user explicitly disables task commits.
  12. Use branch creation or worktree creation when the user asks for branch isolation or the repo policy requires it.
  13. Enter quick mode only when the user explicitly asks Ralph to be autonomous, do it quickly, or continue without pauses.
  14. In quick mode, generate missing artifacts, default task granularity to fine when unset, and continue into implementation in the same session.

Stop Enforcement

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)
  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.

Response Handoff

  • After writing research.md, requirements.md, design.md, tasks.md, or refactored spec files outside quick mode:
    • 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>
  • Treat continue to <named next step> 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.
  • 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/<epic-name>/.
  • 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.
  • 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.

Bootstrap

Bootstrap project-local files only when the user wants them.

Suggested bootstrap files:

  • assets/bootstrap/AGENTS.md to give a consumer repo local Ralph guidance
  • assets/bootstrap/ralph-specum.local.md to seed local settings

Do not bootstrap by default. Installation into $CODEX_HOME/skills is enough.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

tzachbon/smart-ralph

MCP Integration

This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.

278 15
Explore
tzachbon/smart-ralph

Command Development

This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.

278 15
Explore
tzachbon/smart-ralph

Plugin Settings

This skill should be used when the user asks about "plugin settings", "store plugin configuration", "user-configurable plugin", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.

278 15
Explore
tzachbon/smart-ralph

Plugin Structure

This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.

278 15
Explore
tzachbon/smart-ralph

Hook Development

This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.

278 15
Explore
tzachbon/smart-ralph

Skill Development

This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.

278 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results