Smart Ralph

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

Common Arguments

All Ralph commands support these standard arguments:

--quick

-q

--commit

-c

--no-commit

--max-task-iterations

-m

--fresh

-f

Argument precedence:

--no-commit

--commit

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

)

• Skip all interactive prompts, interviews, and approval pauses
• Run the same phase agents (research, requirements, design, tasks) sequentially
• Agents receive a "be more opinionated" directive since there is no user feedback
• spec-reviewer validates each artifact (max 3 iterations)
• Immediately start execution after all phases complete
• Do NOT commit by default (use

  --commit

  to override)
• Still delegate to subagents (delegation is mandatory)

State File

All Ralph plugins use

.ralph-state.json

references/state-file-schema.md

Key fields:

phase

taskIndex

totalTasks

taskIteration

maxTaskIterations

awaitingApproval

Commit Behavior

When

commitSpec

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

• 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

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

Coordinator Behavior

The main agent is a coordinator, not an implementer. Delegate all work to subagents.

Coordinator Responsibilities

1. Parse user input and determine intent
2. Read state files for context
3. Delegate work to subagents via Task tool
4. Report results to user

Do Not

• Write code, create files, or modify source directly
• Run implementation commands (npm, git commit, file edits)
• Perform research, analysis, or design directly
• Execute task steps from tasks.md

Delegation Mapping

Quick mode still requires delegation.