maestro-ralph-cli

Notation

Skill(name) / Skill(name, args) = load ~/.codex/skills/{name}/SKILL.md or .codex/skills/{name}/SKILL.md(project overrides global). Strictly forbidden to translate as Bash("maestro {name} {args}")—CLI does not accept bare intent.

Session: .workflow/.maestro/ralph-cli-{YYYYMMDD-HHmmss}/status.json

Shared with ralph: chain building (A_RESOLVE_PHASE → A_INFER_POSITION → A_BUILD_STEPS), session schema, decomposition (A_DECOMPOSE_TASKS). See Skill(maestro-ralph) for full specification.

Parse:

-y flag        → auto_confirm = true
--to <tool>    → cli_tool (claude|codex|opencode|agy); 默认 claude
--roadmap      → wants_roadmap = true
--amend / -a   → amend_mode = true
.md/.txt path  → input_doc
status|continue → route keyword
Remaining      → intent (amend_mode 时为 change_request)

CLI tool selection:

--to <tool> explicitly specified → use directly
not specified → default claude
validate cli-tools.json target tool in enabled: true
enabled: false → E012

State files:

.workflow/state.json — artifact registry
.workflow/.maestro/ralph-cli-*/status.json — session state

ralph-cli owns the loop — compose → delegate → analyze → decide all complete within this command; maestro-ralph-cli-execute is only the execution wrapper on the delegation side
Delegate via cli-execute — the first line of the delegate prompt is the cli-execute call, format determined by the target tool (see Invocation Notation)
Parse ---RESULT--- block — after delegate returns, parse the structured result block from the output
Decision evaluation inline — decision nodes do not handoff, evaluated directly within this loop
No inline skill execution — this command does not execute skill logic; execution is done by the delegation side cli-execute
Platform — session.platform = "codex"; skill discovery through maestro ralph skills --platform codex

<state_machine>

Ralph's chain-building states apply (S_PARSE_ROUTE through S_CREATE_SESSION). Execution loop states replace S_DISPATCH:

S_STEP_LOCATE — find next pending step PERSIST: — S_STEP_RESOLVE — resolve placeholders + enrich args PERSIST: step.args S_STEP_LOAD — load prior outputs + findings PERSIST: — S_STEP_COMPOSE — generate adapted prompt based on target skill PERSIST: — S_STEP_DELEGATE — call maestro delegate → STOP PERSIST: step.delegate_exec_id, step.status S_STEP_ANALYZE — parse ---RESULT--- block + analyze artifacts PERSIST: step.cli_output_summary, session.context S_POST_ANALYZE — artifact vs goal drift analysis PERSIST: step.drift_score, step.drift_correction S_STEP_COMPLETE — mark complete PERSIST: step.completion_* S_DECISION_EVAL — evaluate decision node PERSIST: — S_APPLY_VERDICT — apply verdict PERSIST: session.steps[] S_SESSION_DONE — all steps complete PERSIST: session.status S_HANDLE_FAIL — handle failure PERSIST: step.status S_AMEND_GOAL — modify running session goal PERSIST: session.task_decomposition, .boundary_contract, .goal_changelog, .steps[] S_FALLBACK — request user input PERSIST: —

S_PARSE_ROUTE: → S_STATUS WHEN: intent == "status" → S_CONTINUE WHEN: intent == "continue" → S_AMEND_GOAL WHEN: amend_mode == true AND running session exists → S_FALLBACK WHEN: amend_mode == true AND no running session → S_STEP_LOCATE WHEN: running session with decision step in "running" status → S_RESOLVE_PHASE WHEN: intent is non-empty → S_FALLBACK WHEN: no intent AND no running session

S_STATUS: → END DO: A_SHOW_STATUS

S_CONTINUE: → S_STEP_LOCATE WHEN: running session found → S_FALLBACK WHEN: no running session

S_AMEND_GOAL: → S_STEP_LOCATE WHEN: change applied + user confirmed DO: A_AMEND_GOAL → END WHEN: user cancels GUARD: RISK_LEVEL=high → auto_confirm invalid

S_CREATE_SESSION: → S_CONFIRM WHEN: not auto_confirm → S_STEP_LOCATE WHEN: auto_confirm

S_CONFIRM: → S_STEP_LOCATE WHEN: user confirms → S_BUILD_CHAIN WHEN: user edits → END WHEN: user cancels

S_STEP_LOCATE: → S_STEP_RESOLVE WHEN: pending execution step found → S_DECISION_EVAL WHEN: pending decision step found → S_SESSION_DONE WHEN: no pending steps → S_FALLBACK WHEN: no running session

S_STEP_RESOLVE → S_STEP_LOAD DO: A_RESOLVE_ARGS S_STEP_LOAD → S_STEP_COMPOSE DO: A_LOAD_STEP_CONTEXT S_STEP_COMPOSE → S_STEP_DELEGATE DO: A_COMPOSE_DELEGATION_PROMPT S_STEP_DELEGATE → END DO: A_DISPATCH_DELEGATE (STOP)

S_STEP_LOCATE (on re-entry, finds running step with delegate_exec_id): → S_STEP_ANALYZE WHEN: delegate completed → END WHEN: delegate still running (STOP)

S_STEP_ANALYZE: → S_POST_ANALYZE WHEN: STATUS == DONE|DONE_WITH_CONCERNS DO: A_PARSE_RESULT → S_HANDLE_FAIL WHEN: STATUS == NEEDS_RETRY|BLOCKED DO: A_PARSE_RESULT

S_POST_ANALYZE: → S_STEP_COMPLETE WHEN: drift_score == ALIGNED|MINOR_DRIFT DO: A_POST_ANALYZE_DRIFT → S_STEP_LOAD WHEN: drift_score == MAJOR_DRIFT + not retried DO: A_POST_ANALYZE_DRIFT (re-delegate with correction) → S_STEP_COMPLETE WHEN: drift_score == MAJOR_DRIFT + retried DO: A_POST_ANALYZE_DRIFT (proceed with caveats)

S_STEP_COMPLETE → S_STEP_LOCATE DO: A_MARK_COMPLETE

S_DECISION_EVAL: → S_APPLY_VERDICT WHEN: quality-gate DO: A_DELEGATE_EVALUATE → S_APPLY_VERDICT WHEN: goal-gate DO: A_GOAL_AUDIT_EVALUATE → S_APPLY_VERDICT WHEN: scope-gate DO: A_SCOPE_EVALUATE → S_APPLY_VERDICT WHEN: reground-gate DO: A_REGROUND_EVALUATE → S_APPLY_VERDICT WHEN: structural DO: A_STRUCTURAL_EVALUATE

S_APPLY_VERDICT: → S_STEP_LOCATE WHEN: proceed / fix / goal-fix / scope-verdict / milestone-advance → END WHEN: escalate / reground-halt / session complete / debug-escalate GUARD: retry_count >= max_retries → force escalate GUARD: confidence_score < 60 AND proceed → override to fix GUARD: post-reground + drifted + confidence >= 60 → A_REGROUND_HALT (auto_confirm does not skip)

S_HANDLE_FAIL: → S_STEP_LOCATE WHEN: auto + not retried DO: A_RETRY → END WHEN: auto + retried DO: A_PAUSE_SESSION

S_SESSION_DONE → END DO: A_COMPLETE_SESSION

A_CREATE_SESSION (override)

Same as ralph A_CREATE_SESSION with:

session_id format: ralph-cli-{YYYYMMDD-HHmmss}
execution_mode: "cli-delegate", cli_tool, platform: "codex"
Each step: delegate_exec_id: null, cli_output_summary: null, artifacts_produced: []
Step mode/role/rule assigned per stage (see Stage Mapping)

A_RESOLVE_ARGS

Same as Skill(maestro-ralph-execute) A_RESOLVE_ARGS:

Placeholder substitution, per-skill enrichment, --from auto-injection, goal context injection, --from blueprint:{BLP_ID} support

A_LOAD_STEP_CONTEXT

The main flow loads prior outputs and findings, preparing material for prompt generation.

Session base — Read status.json → intent, phase, milestone, boundary_contract
Previous step output — the previous step's cli_output_summary + completion_caveats + artifacts_produced → key findings + artifact paths
Artifacts — Read each artifact path one by one, extracting content relevant to the current step:
- conclusions.json → scope, key_findings, recommendations
- TASK-*.json → task descriptions, dependencies, wave assignments
- verification.json → pass/fail results, gap details
- review.json → findings, severity, fix suggestions
- completion_evidence → error traces, test failures
- grill-report.md → challenged assumptions, risks
Explore if needed — artifact points to a code location but lacks context → maestro explore supplement (only for execute/debug/test and when a file path reference exists)
Accumulated signals — iterate over ALL completed steps → aggregate caveats + deferred

Output:step_context structure, for consumption by A_COMPOSE_DELEGATION_PROMPT.

A_COMPOSE_DELEGATION_PROMPT

Based on step_context + Generate an adapted delegate prompt for the target skill.

Invocation Notation — Determined by session.cli_tool :

cli_tool	First-line format
claude	`/maestro-ralph-cli-execute {step.skill} {resolved_args} --session {session_id}`
codex	`$maestro-ralph-cli-execute {step.skill} {resolved_args} --session {session_id}`
opencode, agy	`/maestro-ralph-cli-execute {step.skill} {resolved_args} --session {session_id}`

Skill-adapted prompt — Selectively inject content from step_context based on the target skill type:

Target skill type	Injection focus
analyze	intent + scope + boundary
plan	analysis findings + scope_verdict + recommendations
execute	task list + dependencies + wave + caveats from plan
review	changed files + verification results + execution decisions
test	review findings + execution artifacts + coverage data
debug	error details + failing tests + execution trace
brainstorm/grill	challenged assumptions + risks + prior findings

Each section is added only when it has actual content; skip if there is no content.

A_DISPATCH_DELEGATE

maestro delegate "{prompt}" --to {cli_tool} --mode {delegate_mode} --id {prefix}-{HHmmss}-{rand4}
Write step.delegate_exec_id, step.status = "running"
Bash({ run_in_background: true })
STOP

A_PARSE_RESULT

maestro delegate status {exec_id} — still running → STOP
maestro delegate output {exec_id} — parse ---RESULT--- / ---END--- block
Extract: STATUS, SUMMARY, ARTIFACTS, DECISIONS, CAVEATS, DEFERRED, SIGNALS
Apply SIGNALS key=value pairs to session.context
No block found → fallback: STATUS=DONE_WITH_CONCERNS

A_MARK_COMPLETE

Bash("maestro ralph complete {index} --status {STATUS} --summary \"{SUMMARY}\" ...")

A_SHOW_STATUS

Same as ralph: find latest ralph-cli session, display steps + sub-goals progress.

A_POST_ANALYZE_DRIFT

Artifact vs. goal deviation analysis. Executed after A_PARSE_RESULT and before A_MARK_COMPLETE.

1. Collect comparison baselines:

Baseline source	Value
`step.goal_ref` → goal.done_when	Completion conditions of the sub-goal
`session.boundary_contract.definition_of_done`	Global acceptance criteria
`session.execution_criteria`	Execution guidelines
`session.intent`	Original intent

2. Read the artifact summary:

Build the artifact profile from the SUMMARY + DECISIONS + ARTIFACTS + CAVEATS already extracted by A_PARSE_RESULT.

3. Compare and score:

Dimension	Check
Coverage	Whether the artifact covers every condition of goal.done_when
Directionality	Whether DECISIONS are consistent with intent and boundary
Completeness	Whether all expected artifact types are present

drift_score: ALIGNED / MINOR_DRIFT / MAJOR_DRIFT

4. Corrective actions:

drift_score	Action
ALIGNED	Proceed normally to S_STEP_COMPLETE
MINOR_DRIFT	Append the deviation items to completion_caveats and complete normally
MAJOR_DRIFT + not retried	Write `step.drift_correction`, return to S_STEP_LOAD to recompose + delegate
MAJOR_DRIFT + already retried	Complete with DONE_WITH_CONCERNS, to be adjudicated by the subsequent decision node

5. Write: step.drift_score, step.drift_correction

A_DELEGATE_EVALUATE

Same as ralph: delegate --role analyze --mode analysis with quality gate verdict parsing. Inline (run_in_background, STOP, callback).

A_GOAL_AUDIT_EVALUATE / A_SCOPE_EVALUATE / A_REGROUND_EVALUATE

Same as ralph. All run inline via delegate.

A_STRUCTURAL_EVALUATE

post-milestone: next milestone? insert lifecycle steps / complete. Adhoc: always END. post-debug-escalate: always STOP → A_PAUSE_ESCALATE.

A_APPLY_PROCEED / A_APPLY_FIX / A_APPLY_ESCALATE / A_APPLY_SCOPE_VERDICT / A_APPLY_GOAL_FIX / A_APPLY_GOAL_DONE / A_ADVANCE_MILESTONE

Same as ralph. All chain mutations apply unchanged.

A_REGROUND_HALT

Same as ralph: session.status = "paused", display drift warning. auto_confirm does not skip.

A_PAUSE_ESCALATE

Set session paused, display "Please intervene manually", suggest Skill(maestro-ralph-cli, continue).

A_AMEND_GOAL

Same as ralph (deferred_reading: ralph-amend-goal.md): 5-step flow. auto_confirm is ineffective when RISK_LEVEL=high.

A_RETRY / A_PAUSE_SESSION / A_COMPLETE_SESSION

Same as ralph equivalents.

</state_machine>

Stage Mapping

Stage	delegate_mode	delegate_role	delegate_rule
analyze, analyze-macro	analysis	analyze	`analysis-analyze-code-patterns`
plan	write	plan	`planning-breakdown-task-steps`
execute	write	implement	`development-implement-feature`
review, business-test	analysis	review	`analysis-review-code-quality`
test, test-gen	write	implement	—
grill, brainstorm	write	brainstorm	—
debug	write	analyze	`analysis-diagnose-bug-root-cause`

Session Schema (extends ralph)

All fields of the Ralph session schema apply. New CLI fields:

{
  "execution_mode": "cli-delegate",
  "cli_tool": "claude",
  "platform": "codex",
  "steps": [{
    "delegate_exec_id": null,
    "delegate_mode": "write|analysis",
    "delegate_role": "analyze|plan|implement|review|brainstorm",
    "delegate_rule": null,
    "cli_output_summary": null,
    "artifacts_produced": []
  }]
}

Fix-Loop Templates

Same as ralph. All 6 fix-loop templates apply unchanged. Each inserted step is delegated through the same compose → delegate → analyze cycle.

Error Codes

Ralph E001–E006, W001–W004 all apply. CLI additions:

Code	Severity	Description	Recovery
E011	error	Delegate execution failed	Retry once, then BLOCKED
E012	error	CLI tool not enabled	Switch tool or enable
E013	error	---RESULT--- block not found	Fallback parse, LOW CONFIDENCE

Success Criteria

All ralph success criteria apply. Additionally:

ralph-cli owns full loop: compose → delegate → STOP → callback → parse → complete → next
The first line of the delegation prompt is a cli-execute call (format determined by cli_tool), followed by <execution_context>
A_PARSE_RESULT extracts ---RESULT--- block fields
Decision evaluation inline (no handoff)
S_AMEND_GOAL + A_AMEND_GOAL (5 steps, RISK_LEVEL=high is not skipped)
goal_changelog The write path exists
blueprint_id Supports --from blueprint:{BLP_ID}
A_STRUCTURAL_EVALUATE handles post-milestone + post-debug-escalate
A_ADVANCE_MILESTONE inserts the next milestone's lifecycle steps
A_REGROUND_HALT drift circuit breaker (auto_confirm does not skip)
Fix-loop templates (6 sets) are executed via the compose-delegate cycle
re-grounding 3-step insertion rule (build rule 5.5)
spec-setup pre-check (build rule 0.5)
platform: "codex", skill discovery via --platform codex