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:

Argument	Short	Description	Default
--quick	-q	Skip interactive phases, auto-generate artifacts, start execution immediately	false
--commit	-c	Commit and push spec/feature files after generation	true (normal), false (quick)
--no-commit		Explicitly disable committing files	-
--max-task-iterations	-m	Max retries per failed task before stopping	5
--fresh	-f	Force new spec/feature, overwrite if exists	false

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, interviews, and approval pauses
• Runs the same phase agents (research, requirements, design, tasks) sequentially
• Agents receive a "be more opinionated" directive since there's no user feedback
• spec-reviewer validates each artifact (max 3 iterations)
• Immediately starts execution after all phases complete
• Does NOT commit by default (use --commit to override)
• Still delegates to subagents (delegation is mandatory)

State File

All Ralph plugins use .ralph-state.json for execution state. See references/state-file-schema.md for full schema.

Key fields: phase, taskIndex, totalTasks, taskIteration, maxTaskIterations, awaitingApproval.

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

Task Execution Loop

Ralph Specum v3.0.0+ has a self-contained execution loop via the stop-hook. No external dependencies required.

Key signals:

• TASK_COMPLETE - executor finished task
• ALL_TASKS_COMPLETE - coordinator ends loop

Error Handling

When taskIteration > maxTaskIterations: block task, suggest manual intervention.

If state file missing/invalid: output error, suggest re-running implement command.

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