smart-ralph

name	smart-ralph
description	Core Smart Ralph skill defining common arguments, execution modes, and shared behaviors across all Ralph plugins.
version	0.1.0

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

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

Coordinator Signals

Signal	Meaning
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