kapi-workflow

name	kapi-workflow
description	Use when an active Kapi workflow is in context or the user explicitly asks for /kapi-* workflow structure. Preserve thin-by-default behavior and follow the active workflow contract, artifacts, evidence, and worker guidance.

Kapi Workflow

Use the active Kapi workflow contract as the source of workflow behavior.

Rules:

• Do not start Kapi workflow state unless the user explicitly asks for a /kapi-* workflow or a Kapi tool has already activated one.
• When a workflow is active, keep status, phase, artifact root, evidence requirements, and worker constraints visible in the final answer.
• Prefer the lightest Kapi workflow that satisfies the task.
• Record evidence before completion claims.
• For governed workflows, do not claim completion without verifier evidence and required handoff approvals.

Artifact-Backed Workflow Reminders

Use these reminders when the active workflow is artifact-backed. Keep the artifacts short, current, and useful for the next workflow; do not turn artifact-backed workflows into governed execution.

Artifacts are durable checkpoints, not conversational scratchpads. Prefer reading at workflow start and writing at meaningful checkpoints, phase boundaries, blockers, verification results, or completion gates instead of after every turn. Use kapi_write_artifacts when a checkpoint updates multiple files.

• /kapi-deep-interview: use the bundled kapi-deep-interview skill as maintained behavioral guidance; the main agent conducts the interview directly, so do not spawn an interviewer subagent or call named interviewer agents.
• /kapi-deep-interview: update context.md, interview.md, run-contract-draft.md, and decision-report.md directly at question-batch or decision checkpoints; use kapi_update_workflow and kapi_record_evidence for protected generated artifacts such as state.json, events.jsonl, snapshot.json, and verify.md; overwrite authored artifacts with consolidated current content rather than appending duplicate headers or stale pending answers; keep run-contract-draft.md as a Markdown draft with GoalSpec, ConstraintSpec, EvidenceStandard, DoneCriteria, and recommendedPreset sections, not as a durable contract.json source of truth; do not require a root spec.md because downstream Ralph/Autoresearch own implementation-specific planning.
• /kapi-autoresearch: update contract.md, benchmark.sh, ledger.jsonl, ideas.md, checks.sh, decision-report.md, and verify.md inside the explicit experiment boundary.
• /kapi-ralph: update AGENTS.md, IMPLEMENTATION_PLAN.md, handoff.json, decision-report.md, and verify.md after planning/build milestones and verifier evidence.
• /kapi-integrate: update merge-plan.md, conflict-matrix.md, integration-report.md, decision-report.md, and verify.md; merge only toward dev after approval and verification.

Governed Workflow Reminders

Use these reminders only when the active workflow is governed; do not impose them on ordinary Pi turns or lightweight workflows.

• /kapi-ralph: keep IMPLEMENTATION_PLAN.md, handoff.json, decision-report.md, and verify.md synchronized at planning, build, verification, blocker, and closeout boundaries rather than every turn.
• /kapi-ralph: use the kapi-ralph skill; if context is insufficient, interview first, then run planner -> critic/architect consensus loops (max 5 attempts) and prepare AGENTS.md, IMPLEMENTATION_PLAN.md, handoff, verify, specs, and shared state.json.ralphState under .ilchul/workflows/ralph/<slug>/; do not implement.
• /kapi-ralph: use the kapi-ralph skill; reuse the shared Ralph workspace, read state.json, AGENTS.md, IMPLEMENTATION_PLAN.md, specs, handoff, and verify first, pick exactly one task, validate it, and update state.json.ralphState, IMPLEMENTATION_PLAN.md, and verify.md after meaningful steps, blockers, and fresh evidence.
• /kapi-autoresearch: keep contract.md, benchmark.sh, ledger.jsonl, ideas.md, checks.sh, and verify.md attached to the loop contract; do not mutate the fixed comparison boundary silently.
• /kapi-integrate: operate only on Kapi-owned branches/worktrees, keep merge-plan.md, conflict-matrix.md, integration-report.md, and verify.md current, and never merge directly to main.

Governed Approval Evidence

When a governed workflow uses handoff.json, keep architect and verifier approvals structured enough for Kapi validation instead of relying on prose:

• architect evidence should use kind: review, role: architect, and verdict: approve when the plan or handoff is accepted;
• verifier evidence should use kind: review, role: verifier, and verdict: pass or approve when completion evidence is accepted;
• evidence refs should point to a stable command, artifact anchor, or review note, such as cmd:npm run verify or verify.md#verifier-pass.

Completion Output

When closing or reporting progress in an active workflow, include:

• status and phase;
• artifacts created or updated;
• evidence refs, including commands when available;
• worker status or handoff notes when workers were used;
• remaining risks or the next workflow recommendation.