kapi-ralph

name	kapi-ralph
description	Ralph build workflow for Kapi. Use when /kapi-ralph is active or when implementing from a prepared Ralph workspace with AGENTS.md, IMPLEMENTATION_PLAN.md, specs, shared state.json, handoff.json, verify.md, one-task iterations, validation backpressure, and reviewer closeout.

kapi-ralph

Use this skill as Kapi's embedded equivalent of Ralph PROMPT_build.md.

Purpose

Ralph is the build driver for the shared Ralph workspace prepared by /kapi-ralph. It owns a context sufficiency check before build work: when product intent, JTBD, constraints, acceptance criteria, or topic scope are unclear, use a deep-interview-style planning pass before selecting implementation tasks. Treat that pass as a topic scope test and route planner, critic, and architect consensus into state.json, IMPLEMENTATION_PLAN.md, AGENTS.md, handoff.json, specs/*, and verify.md; keep AGENTS.mdis operational only and keep the implementation plan disposable. If consensus cannot converge after maximum 5 planning attempts, stop blocked. It must continue from approved durable Ralph state instate.json.ralphState; if that state is absent or not approved, run /kapi-ralphfirst. When/kapi-ralphis started without a slug and exactly one approved, unstarted Ralplan slug exists, Kapi should continue that slug; if several are ready, Kapi lists indexed choices and the user should choose with/kapi-ralph or--slug `. Ralph implements exactly one highest-priority unfinished task per iteration, validates it, records evidence, updates the plan/state, and exits cleanly so the next iteration starts from fresh context.

Workspace

Use the active Kapi artifact root:

.ilchul/workflows/ralph/<slug>/

Read these before acting:

state.json                 # Kapi WorkflowState plus nested ralphState; source of truth
AGENTS.md                  # operating rules, protection, validation/backpressure
IMPLEMENTATION_PLAN.md     # prioritized tasks and completion markers
specs/                     # topic-of-concern requirements when present
handoff.json               # planning approvals and readiness
verify.md                  # evidence ledger

Ralplan and Ralph share the same state.json. Do not create a separate progress file for Ralph state.

Shared State: state.json

Always read state.json first if it exists. Keep existing ralphState.planning/history information intact and update the build fields in the same nested state object.

When building, ralphState should indicate:

{
  "ralphState": {
    "workspaceId": "<slug>",
    "stage": "building",
    "mode": "ralph",
    "phase": "build|verify|validate|blocked|completed",
    "currentTask": "...",
    "iteration": 1,
    "lastValidation": { "command": "...", "status": "pass|fail", "evidenceRef": "..." },
    "nextStep": "...",
    "blocker": null,
    "history": []
  }
}

Update state.json at orientation, task selection, validation, blocker, and closeout boundaries.

File Roles

• specs/* define behavioral requirements and acceptance/backpressure expectations.
• IMPLEMENTATION_PLAN.md is the prioritized work queue. Treat it as disposable working state: keep it current, remove completed clutter when it grows, and recommend /kapi-ralph if it is stale or wrong.
• AGENTS.md is operational only: commands, protection boundaries, repo patterns, and durable build/test learnings. Do not write progress notes or status updates there.
• state.json.ralphState is the workflow machine state.
• verify.md is the evidence ledger.

Build Iteration

Perform one bounded Ralph iteration:

1. Orient

   • Read state.json first and confirm ralphState.consensus.reached = true with critic and architect approve/pass verdicts.
   • If approved durable Ralph state is missing, stop before building and start /kapi-ralph with the same slug; the Ralplan skill will deep-interview if planning information is insufficient.
   • Read AGENTS.md, IMPLEMENTATION_PLAN.md, specs/*, handoff.json, and verify.md.
   • Confirm handoff/plan are not stale. If planning consensus is stale, stop and recommend /kapi-ralph.

2. Select exactly one task

   • Pick the highest-priority unfinished in-scope task from IMPLEMENTATION_PLAN.md.
   • If no in-scope unfinished task remains, validate closeout instead of inventing work.

3. Investigate before assuming

   • Search the repo and tests before claiming functionality is missing.
   • Do not assume not implemented. Prefer reusing existing code and patterns over duplicating behavior.

4. Implement

   • Make the smallest correct diff for the selected task only.
   • Implement completely; placeholders and stubs waste future loop iterations.
   • Do not opportunistically refactor unrelated code.
   • Prefer shared utilities and existing project patterns over ad-hoc copies.
   • Update AGENTS.md only for durable operational learnings that future iterations must know.

5. Validate with backpressure

   • Run the smallest relevant checks from AGENTS.md and acceptance criteria.
   • Prefer tests/typecheck/lint/build or LLM-as-judge checks when subjective acceptance requires it.
   • Do not claim completion without the check that proves the selected task.
   • If unrelated tests fail, document or resolve them before the iteration exits; do not silently ignore backpressure.
   • If validation fails and the fix is still within the selected task, fix and rerun. Otherwise stop blocked.

6. Update durable files

   • Mark the task done or revise it in IMPLEMENTATION_PLAN.md; capture the why, validation result, and any discovered follow-up.
   • If the plan is now stale, confusing, or too cluttered, clean it or recommend /kapi-ralph regeneration.
   • Update state.json.ralphState with currentTask, iteration, validation result, nextStep, blocker/history.
   • Append validation evidence to verify.md.
   • Update handoff.json if status, blocker, or next step changed.

7. Review closeout

   • Before completing /kapi-ralph, obtain reviewer/subagent approval evidence.
   • Completion evidence should be structured: kind=review, ref=subagent:reviewer, role reviewer/verifier where appropriate, and verdict approve or pass.

Stop Conditions

Stop rather than continue when:

• no prepared or approved plan exists;
• the selected task is ambiguous or out of scope;
• repo search shows the task is already implemented and the plan needs revision;
• validation/backpressure fails outside the selected task;
• human protection/scope decision is required;
• implementation would touch unrelated tasks.

Completion

Complete Ralph only when:

• IMPLEMENTATION_PLAN.md has no in-scope unfinished tasks, or the current iteration is intentionally handing off to the next loop;
• state.json.ralphState records building mode, current/last task, validation, blocker or next step;
• verify.md contains fresh validation evidence;
• reviewer/subagent approval evidence is recorded before terminal closeout.