| name | ralphx-swe |
| description | RalphX autonomous agent playbook. Teaches external agents pipeline navigation: ideation → execution → review → merge. Covers 24-state machine, decision trees for edge cases, event-driven patterns, failure recovery playbooks. Use when connecting to RalphX via External MCP API or managing pipeline tasks.
|
| argument-hint | [section: quick-start | state-machine | decisions | events | recovery | dos-donts | cross-project] |
RalphX SWE Skill — Autonomous Pipeline Playbook
Skill vs Guide: Call v1_get_agent_guide for tool schemas and sequencing rules. This skill
teaches judgment: when to act vs observe, how to handle edge cases, what events mean for
decision-making. Zero overlap with the guide's API reference content.
1. Bootstrap — Start Here Every Session
Two steps before taking any pipeline action:
Canonical tool naming (read this before any tool call):
Examples in this skill use canonical RalphX method names: v1_*
Host mappings:
- RalphX external MCP methods: v1_*
- Claude/Codex MCP wrappers in some environments: mcp__ralphx__v1_*
- ReefBot integration: ralphx__v1_*
Never invent a namespace from this skill name.
Never call mcp__ralphx-swe__*.
Step 1 — Check attention items (find what needs action right now):
v1_get_attention_items(project_id)
→ Returns escalated_reviews, failed_tasks, merge_conflicts.
→ Address these before doing anything else.
Step 2 — Load tool reference (for argument schemas and preconditions):
v1_get_agent_guide() → or v1_get_agent_guide(section: "pipeline") for supervision tools
2. Core Principles
Observe before act. Most pipeline states are agent-active (executing, reviewing, merging). Your
role in those states is to watch, not interrupt. Only take action in waiting states
(review_passed, escalated, qa_failed, merge_conflict, merge_incomplete).
Annotate before you intervene. Before calling any action tool, call v1_create_task_note with
your reasoning. This creates an audit trail for humans reviewing your decisions.
Always pair UUIDs with titles. Any task ID you surface in a log, message, or annotation must
include the human-readable title. Use v1_get_task_detail or v1_batch_task_status to resolve
titles. Format: task-{id} ({Title}).
Webhook chat updates should stay human-first. Machine IDs from RalphX webhook events are
stored separately in message/session metadata. In normal user-facing chat updates, prefer human
titles and project labels; do not dump raw UUID footers unless the user explicitly asks for them.
Separate review approval from merge progression. review_passed is the approval-decision
point. merge:ready / pending_merge are merge-pipeline observation states. Do NOT ask for a
second "merge approval" unless your integration explicitly defines one.
Approval authority is integration-specific. On review_passed, either:
- act if your current policy/delegation allows
v1_approve_review / v1_request_changes
- or report that a decision is pending
Never assume approval is always human-only. Never assume approval is always autonomous.
Accepted-plan follow-ups use append, not a new ideation, while the plan is still open.
When the user asks for a small one-off addition after v1_accept_plan_and_schedule, call
v1_append_task_to_plan if the plan branch is still active. Open PR / waiting-on-PR plans are still
open and can receive appended tasks. Once the PR/plan is closed, merged, terminal, or actively
merging/repairing, start a new ideation continuation instead.
Conservative intervention. When uncertain, annotate and wait. A wrong auto-action (retrying a
non-transient failure, sending a message to a generating agent) causes more damage than a brief
delay. Escalate to human attention when in doubt.
Escalations are exception states. review:escalated, merge_conflict, and
merge_incomplete should be surfaced immediately. Only resolve review:escalated if your current
policy/delegation explicitly allows it.
Report for chat surfaces, not operator consoles. Telegram, Slack, and WhatsApp updates should
be short:
- line 1: what changed
- line 2: next automatic step or blocker
- line 3 only if user action is truly required
- in shared/multi-project webhook topics, start line 1 with the project label
- stay silent for no-op duplicate redeliveries; users should not see "No response requested" or duplicate-event chatter
- avoid markdown tables in webhook updates; use prose or at most 2-4 compact bullets
Do not ask "shall I approve?" unless approval is genuinely blocked on the user.
3. Do's and Don'ts
| Situation | ✅ Do | ❌ Don't |
|---|
Task in review_passed | Check current authority/policy. If allowed: v1_approve_review or v1_request_changes. If not: report pending decision. | Assume a human must always approve, or assume you may always auto-approve |
Task in escalated | Annotate + alert human/owner; call v1_resolve_escalation ONLY if delegation/policy explicitly allows | Auto-resolve escalation by default |
review:escalated event arrives | v1_get_task_detail → v1_create_task_note → surface blocker clearly | Treat it like an ordinary review_passed case |
Task in merge_conflict | Annotate with conflict files + alert human | Call v1_retry_task (resets branch context) |
Task in blocked | Call v1_get_task_detail to inspect blocker; notify human if human-input block | Cancel the blocked task |
| MCP/webhook delivery failure | Observe. If RalphX emits system:webhook_unhealthy, treat it as informational; system health tracker handles recovery automatically | Synthesize your own webhook-health events or claim transport repair — infrastructure issues, not agent-resolvable |
v1_accept_plan_and_schedule fails | Call v1_resume_scheduling(session_id) to resume idempotently | Re-call v1_accept_plan_and_schedule (may double-create tasks) |
Agent agent_status: generating | Wait briefly, then check status again | Send a message (it will be queued and may confuse agent state) |
| Rate limit 429 received | Exponential backoff: 1s → 2s → 4s → 8s with ±200ms jitter | Retry immediately or in a tight loop |
Task in transient state (pending_review, approved, pending_merge) | Check status again shortly for settled state | Take any action — these states last milliseconds |
Task in paused | Annotate + alert human; do NOT call v1_retry_task | Call v1_retry_task (resets to ready, loses pre-pause context) |
Task iterating reviewing → re_executing | Log the cycle count; only intervene after ~5 cycles | Interrupt the loop — normal iteration is 2-3 cycles |
Freshness conflict (executing → merging) | Observe; this is automatic rebasing, not a failure | Panic or annotate — it resolves to ready or pending_review automatically |
QA fails (qa_failed) | Call v1_get_task_detail + surface to human; human decides: v1_request_changes or manually skips QA via app UI | Auto-retry QA without human review |
merge:ready or pending_merge | Treat as merge-pipeline progress; monitor for merge:completed or merge:conflict | Ask the user for a second generic merge approval |
Session delivery_status = delivered | Report "all tasks merged to main" / "plan delivered" | Continue talking as if approval is still pending |
| Small follow-up after accepted plan while plan is still open | v1_append_task_to_plan(session_id, title, steps, acceptance_criteria) | Start a whole new ideation for a one-off task while the existing plan branch/PR is still open |
| Follow-up after plan is closed, terminal, or actively merging/repairing | Start a new ideation continuation | Append to a closed, merged, terminal, conflicting, or actively merging plan |
4. Quick Decision Guide
The 11 most common decision points:
1. Event arrives: task:status_changed → escalated
→ v1_get_task_detail(task_id) → v1_create_task_note(task_id, "Escalated: <reason>") → Alert human
2. Event arrives: review_passed
→ Check current authority/policy
→ If allowed: inspect v1_get_review_summary + v1_get_task_diff → call v1_approve_review or v1_request_changes
→ If not allowed: report decision pending with task title and key finding summary
3. Event arrives: merge:conflict
→ v1_get_task_detail(task_id) for conflict files → v1_create_task_note(task_id, "Merge conflict in: <files>") → Alert human
4. v1_get_attention_items returns failed tasks
→ v1_get_task_detail(task_id) for failure reason → Transient failure + count < 3 → v1_retry_task
→ Non-transient or count ≥ 3 → Annotate + alert human
5. v1_get_ideation_status shows agent_status: idle unexpectedly
→ v1_send_ideation_message(session_id, "Please continue drafting the plan and finalize proposals.")
6. Plan verification not converging after 10 minutes
→ v1_get_plan(session_id) for gap details → Alert human with gaps list → Await human guidance
7. v1_get_execution_capacity returns available: 0
→ Wait for task:status_changed events indicating terminal states (merged/failed/cancelled/stopped) — capacity recalculates automatically
→ Do NOT call v1_resume_scheduling (not a capacity tool)
8. Task stuck in blocked for extended period
→ v1_get_task_detail → check blocked_by list → v1_batch_task_status([blocker_ids])
→ Blocker failed/stopped → annotate + consider v1_retry_task on blocker; blocker active → wait
9. Ideation plan ready — should I accept?
→ Only if: plan exists AND v1_get_plan_verification returns Verified status
→ Then: v1_accept_plan_and_schedule(session_id) → note returned task IDs
10. Session delivery reaches delivered
→ Report concise completion: "All tasks merged to main. Plan delivered."
→ Include task count or key titles only if useful
11. User asks for a small follow-up after plan acceptance
→ v1_get_session_tasks(session_id) to inspect delivery/task state
→ If the plan is still open, including open PR / waiting-on-PR: v1_append_task_to_plan(session_id, title, steps, acceptance_criteria)
→ If the PR/plan is closed, merged, terminal, or actively merging/repairing: start a new ideation continuation
5. Reference Navigation
Five reference files live alongside this skill. Load them when you need depth on a specific topic.
All paths are relative to this skill file's directory (skills/ralphx-swe/):
| File | Contents | When to Load |
|---|
reference/state-machine.md | All 24 pipeline states, transition table, happy paths, behavioral patterns | Confused by a state transition; need precise state semantics |
reference/decision-trees.md | 6 ASCII decision trees for common scenarios | Handling escalation, merge conflict, blocked task, failed task, capacity |
reference/event-catalog.md | All 20 event types, fields, and recommended reactions | Unsure how to react to a specific event; need event field names |
reference/failure-playbooks.md | 5 step-by-step recovery procedures with real v1_ tool calls | Recovering from accept failure, blocked task, rate limits, idle agent, webhook delivery failure |
reference/cross-project.md | Cross-project orchestration — what it is and what it means for your agent | Understanding tasks appearing across multiple projects from a single ideation session |
These files are fully self-contained. No external dependencies. No internet required.
6. Section Dispatch
When this skill is invoked with an argument, load the corresponding content:
If $ARGUMENTS contains state-machine: Read the file reference/state-machine.md in the same
directory as this skill file and present its full content to the user.
If $ARGUMENTS contains decisions: Read the file reference/decision-trees.md in the same
directory as this skill file and present its full content to the user.
If $ARGUMENTS contains events: Read the file reference/event-catalog.md in the same
directory as this skill file and present its full content to the user.
If $ARGUMENTS contains recovery: Read the file reference/failure-playbooks.md in the same
directory as this skill file and present its full content to the user.
If $ARGUMENTS contains dos-donts: Present Section 3 (Do's and Don'ts) of this skill file in
full, with the complete table of situations and recommended actions.
If $ARGUMENTS contains quick-start: Present Sections 1 (Bootstrap) and 4 (Quick Decision
Guide) of this skill file in full, as a fast onboarding reference.
If $ARGUMENTS contains cross-project: Read the file reference/cross-project.md in the same
directory as this skill file and present its full content to the user.
If $ARGUMENTS is empty or not recognized: Present the full skill content above (Sections 1–5),
then remind the user that /ralphx-shared-plugin:ralphx-swe [section] can be used to load a
specific reference file.
