kapi-ralplan

name	kapi-ralplan
description	Ralph planning workflow for Kapi. Use when a Ralph workspace needs interview-driven planning, specs, AGENTS.md, IMPLEMENTATION_PLAN.md, state.json, handoff.json, and critic/architect consensus before /kapi-ralph execution.

kapi-ralplan

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

Purpose

Ralplan is the planning driver for a shared Ralph workspace. It interviews when context is insufficient, produces or revises specs and implementation planning artifacts, and stops only when the plan is ready for /kapi-ralph or the loop is blocked.

Do not implement code. Do not commit code. Planning output is the product.

Workspace

Use the active Kapi artifact root:

.ilchul/workflows/ralph/<slug>/

Ralplan and Ralph share this same workspace and the same state.json.

Expected files:

state.json                 # Kapi WorkflowState plus nested ralphState; source of truth
AGENTS.md                  # repo-specific operating rules, protection, validation/backpressure
IMPLEMENTATION_PLAN.md     # prioritized Ralph task plan
specs/                     # topic-of-concern specs; skill-managed nested files
handoff.json               # ready-for-/kapi-ralph handoff after consensus
verify.md                  # evidence ledger for planner, critic, architect, verifier

specs/* are workspace files, not Kapi tracked artifacts yet, because the current artifact API rejects path separators.

Context Sufficiency Check

Before planning, decide whether the available context is sufficient. It is insufficient if any of these are unclear:

• JTBD / desired outcome
• target repo or work area
• bounded scope and non-goals
• topic(s) of concern
• acceptance criteria
• protection boundary / blast radius
• validation/backpressure commands or candidate checks
• relevant existing implementation patterns

If context is insufficient, run a deep-interview-style clarification first: ask one decision-critical question at a time, prefer questions that unlock multiple downstream choices, and do not write the final plan until the missing fields are clear enough.

Requirements Shape

Plan from product intent toward implementation, not from random tasks:

1. Identify the JTBD: the user outcome the project slice should satisfy.
2. Split the JTBD into topics of concern.
3. Use the topic scope test: each topic should be explainable in one sentence without joining unrelated capabilities with "and".
4. Write or update one specs/<topic>.md per topic of concern.
5. Keep specs behavioral: observable outcomes, constraints, edge cases, and acceptance/backpressure expectations.

Do not turn specs into task lists. Tasks belong in IMPLEMENTATION_PLAN.md after comparing specs against the existing code.

File Roles

• specs/* are the source of truth for what should be true.
• IMPLEMENTATION_PLAN.md is the prioritized task list produced by specs-vs-code gap analysis. It is disposable: if it becomes stale, confusing, or wrong, regenerate it rather than preserving clutter.
• AGENTS.md is operational only: build/run/test commands, protection boundaries, repo patterns, and durable loop learnings. Do not use it for status updates, progress notes, or changelog entries.
• verify.md is evidence only.
• handoff.json is a phase-transition contract, not the primary plan.

Shared State: state.json

Always read state.json first if it exists. Never reset attempts or history unless the user explicitly restarts the Ralph workspace.

state.json is the normal Kapi WorkflowState. Ralplan/Ralph loop state lives under ralphState:

{
  "ralphState": {
    "workspaceId": "<slug>",
    "stage": "planning",
    "mode": "ralplan",
    "phase": "interview|planning|reviewing|revising|approved|blocked",
    "attempt": 1,
    "maxAttempts": 5,
    "contextSufficiency": { "status": "unknown|sufficient|insufficient", "missing": [] },
    "currentIteration": { "plannerAction": "create|revise", "summary": "", "filesChanged": [] },
    "reviews": {
      "critic": { "verdict": "pending|approve|revise|reject", "summary": "", "blockingFindings": [] },
      "architect": { "verdict": "pending|approve|revise|reject", "summary": "", "blockingFindings": [] }
    },
    "consensus": { "reached": false, "reason": "" },
    "nextStep": "...",
    "blocker": null,
    "history": [],
    "updatedAt": "..."
  }
}

Update state.json at every phase transition. Increment attempt only when the planner submits a plan for critic/architect review. maxAttempts is 5.

Planning Loop

Run up to maximum 5 planning-review attempts:

1. Interview / orient

   • Fill missing context with deep-interview-style questions.
   • Study existing specs, AGENTS.md, IMPLEMENTATION_PLAN.md, and relevant source before asserting gaps.

2. Planner creates or revises

   • Write/update specs/* for each topic of concern.
   • Write/update AGENTS.md with protection boundaries, validation commands, and backpressure. Keep it concise and operational.
   • Study existing source and tests before claiming a gap; do not assume not implemented.
   • Write/update IMPLEMENTATION_PLAN.md with prioritized bullet tasks derived from specs-vs-code gap analysis.
   • Include acceptance-driven backpressure in the plan when possible: the check, test, review, or evidence that will prove each task.
   • Update state.json.ralphState and append planner evidence to verify.md.
   • Do not implement.

3. Critic and architect review in parallel

   • Critic reviews ambiguity, acceptance criteria, missing specs, risk, and testability.
   • Architect reviews technical coherence, boundaries, dependency order, repo fit, and maintainability.
   • Record both verdicts in state.json.ralphState.reviews and verify.md.

4. Consensus gate

   • Consensus requires both critic and architect verdicts to be approve or pass, with no blocking findings.
   • If either role returns revise, reject, or fail, planner must revise and loop.
   • If consensus is not reached after 5 attempts, set phase/status to blocked, record blocker and next step, and ask the user to narrow scope or decide.

5. Handoff

   • Only after consensus, write handoff.json with ready_for: "kapi-ralph", slug, workspace, source files, approvals, and next step.
   • Set ralphState.stage = "planning", mode = "ralplan", phase = "approved", and consensus.reached = true.

Required Review Evidence

verify.md must show:

• planner attempt summary and files changed;
• critic verdict and blocking findings;
• architect verdict and blocking findings;
• final consensus record or blocked reason.

Use structured evidence when available:

kind=review
role=critic|architect|verifier
verdict=approve|pass|revise|reject|fail
ref=subagent:<role>

Stop Conditions

Stop as blocked when:

• context remains insufficient after focused interview;
• critic/architect consensus fails after maximum 5 attempts;
• the plan requires a human scope/protection decision;
• repo facts contradict the requested scope;
• validation/backpressure cannot be identified.

Completion

Complete Ralplan only when:

• AGENTS.md, IMPLEMENTATION_PLAN.md, handoff.json, verify.md, and relevant specs/* are current;
• state.json.ralphState records attempts, review verdicts, consensus, and next step;
• critic and architect both approve/pass;
• the handoff clearly says /kapi-ralph can continue from the same slug.