| 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:
- Stage spec/feature files after generation
- Commit with message:
chore(<plugin>): commit spec files before implementation
- 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:
- Output error with task index and attempt count
- Include last failure reason
- Suggest manual intervention
- Do NOT output ALL_TASKS_COMPLETE
- Do NOT continue execution
State Corruption
If state file missing or invalid:
- Output error with state file path
- Suggest re-running the implement command
- Do NOT continue execution
Branch Management
All Ralph plugins follow consistent branch strategy:
- Check current branch before starting
- If on default branch (main/master): prompt for branch strategy
- If on feature branch: offer to continue or create new
- Quick mode: auto-create branch, no prompts
