Agent Skills › tzachbon/smart-ralph › smart-ralph

smart-ralph

GitHub

定义Ralph插件的核心通用参数、执行模式（正常/快速）及共享行为。支持自动提交、重试控制、状态管理及自包含的任务执行循环，为各插件提供统一的基础框架与交互规范。

plugins/ralph-speckit/skills/smart-ralph/SKILL.md tzachbon/smart-ralph

Trigger Scenarios

需要配置或运行Ralph系列插件时涉及Spec文件生成与提交逻辑时处理多阶段交互式开发流程时

Install

npx skills add tzachbon/smart-ralph --skill smart-ralph -g -y

More Options

Non-standard path

npx skills add https://github.com/tzachbon/smart-ralph/tree/main/plugins/ralph-speckit/skills/smart-ralph -g -y

Use without installing

npx skills use tzachbon/smart-ralph@smart-ralph

指定 Agent (Claude Code)

npx skills add tzachbon/smart-ralph --skill smart-ralph -a claude-code -g -y

安装 repo 全部 skill

npx skills add tzachbon/smart-ralph --all -g -y

预览 repo 内 skill

npx skills add tzachbon/smart-ralph --list

SKILL.md

Frontmatter

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

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.