OpenSkillIndex← back to search
claude-codeautomation

Smart-ralph smart-ralph

Core Smart Ralph skill defining common arguments, execution modes, and shared behaviors across all Ralph plugins.

install
source · Clone the upstream repo
git clone https://github.com/tzachbon/smart-ralph
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/tzachbon/smart-ralph "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/ralph-speckit/skills/smart-ralph" ~/.claude/skills/tzachbon-smart-ralph-smart-ralph && rm -rf "$T"
manifest: plugins/ralph-speckit/skills/smart-ralph/SKILL.md
tags
#automation#command-line#state-management#plugin-architecture#workflow-management
source content

Smart Ralph

Core skill for all Ralph plugins. Defines common arguments, execution modes, and shared behaviors.

Common Arguments

All Ralph commands support these standard arguments:

ArgumentShortDescriptionDefault
--quick
-q
Skip interactive phases, auto-generate artifacts, start execution immediatelyfalse
--commit
-c
Commit and push spec/feature files after generationtrue (normal), false (quick)
--no-commit
Explicitly disable committing files-
--max-task-iterations
-m
Max retries per failed task before stopping5
--fresh
-f
Force new spec/feature, overwrite if existsfalse

Argument Parsing Rules

Priority Order (highest to lowest):
1. --no-commit (explicit disable)
2. --commit (explicit enable)
3. --quick mode default (false)
4. Normal mode default (true)

Parsing Logic

commitSpec = true  // default

if "--no-commit" in args:
  commitSpec = false
else if "--commit" in args:
  commitSpec = true
else if "--quick" in args:
  commitSpec = false  // quick mode defaults to no commit
// else keep default (true)

Execution Modes

Normal Mode (Interactive)

  • User reviews artifacts between phases
  • Phase transitions require explicit commands
  • Each phase sets 
    awaitingApproval: true
  • Commits spec files by default

Quick Mode (
--quick
)

  • Skips all interactive prompts and interviews
  • Auto-generates all artifacts in sequence
  • Immediately starts execution after generation
  • Does NOT commit by default (use 
    --commit
    to override)
  • Still delegates to subagents (delegation is mandatory)

State File Structure

All Ralph plugins use a state file with common fields:

{
  "phase": "research|requirements|design|tasks|execution",
  "taskIndex": 0,
  "totalTasks": 0,
  "taskIteration": 1,
  "maxTaskIterations": 5,
  "awaitingApproval": false
}

Plugins may extend with additional fields.

Commit Behavior

When 

commitSpec
is true:

  1. Stage spec/feature files after generation
  2. Commit with message: 
    chore(<plugin>): commit spec files before implementation
  3. Push to current branch

When 

commitSpec
is false:

  • Files remain uncommitted
  • User can manually commit later

Execution Loop (Self-Contained)

The execution loop is self-contained via the built-in stop-hook. No external plugins are required.

1. Coordinator outputs task delegation prompt
2. Stop-hook detects task completion signals
3. Stop-hook outputs continuation prompt for next task
4. Loop ends when coordinator outputs ALL_TASKS_COMPLETE

Coordinator Prompt

The implement command includes the coordinator prompt inline. The stop-hook (

hooks/scripts/stop-watcher.sh
) reads 
.speckit-state.json
to determine continuation behavior.

Task Completion Protocol

Executor Signals

SignalMeaning
TASK_COMPLETE
Task finished successfully
VERIFICATION_PASS
Verification task passed
VERIFICATION_FAIL
Verification failed, needs retry

Coordinator Signals

SignalMeaning
ALL_TASKS_COMPLETE
All tasks done, end loop

Error Handling

Max Retries

When 

taskIteration
exceeds 
maxTaskIterations
:

  1. Output error with task index and attempt count
  2. Include last failure reason
  3. Suggest manual intervention
  4. Do NOT output ALL_TASKS_COMPLETE
  5. Do NOT continue execution

State Corruption

If state file missing or invalid:

  1. Output error with state file path
  2. Suggest re-running the implement command
  3. Do NOT continue execution

Branch Management

All Ralph plugins follow consistent branch strategy:

  1. Check current branch before starting
  2. If on default branch (main/master): prompt for branch strategy
  3. If on feature branch: offer to continue or create new
  4. Quick mode: auto-create branch, no prompts