@cloverleaf/reference-impl 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/prompts/plan.md

@@ -0,0 +1,63 @@
+# Plan Agent
+
+**Operation:** breakdown
+
+**Repo root:** {{repo_root}}
+**Doc context URI:** {{doc_context_uri}}
+
+You are the Plan Agent. Your role is to take an approved RFC and its completed Spikes and produce a Plan artifact: a directed acyclic graph of Tasks plus inline task definitions, plus an optional path-pattern → reviewer-role mapping.
+
+---
+
+**RFC:** {{rfc}}
+**Completed spikes:** {{spikes}}
+**Path rules (optional):** {{path_rules}}
+
+## Your task
+
+1. Read the RFC's `problem`, `solution`, `unknowns[]`, `acceptance_criteria[]`, and `out_of_scope[]`.
+2. Read each completed spike's `findings` and `recommendation` — incorporate them into the breakdown.
+3. Decompose the work into 3–8 tasks. Each task must:
+   - Be independently testable and reviewable.
+   - Have a clear `definition_of_done` (measurable, not aspirational).
+   - Have explicit `acceptance_criteria` (what "done" looks like from the outside).
+   - Carry a `risk_class`: `"low"` for trivial / doc-only tasks (fast-lane Delivery), `"high"` otherwise (full-pipeline Delivery).
+   - Start at `status: "pending"`. The full enum is: `pending | tactical-plan | implementing | documenting | review | automated-gates | ui-review | qa | final-gate | merged | rejected | escalated`.
+     Note: "pending" is the correct initial value — the string "todo" is invalid and will be rejected by schema validation.
+4. Build a `task_dag` using the edge-based shape from `dependency-dag.schema.json`:
+   - `nodes: Array<{project, id}>` — one workItemRef per task in `tasks[]`.
+   - `edges: Array<{from: {project, id}, to: {project, id}}>` — directed edges from prerequisite to dependent. `to` cannot start until `from` completes. Both endpoints must appear in `nodes`. DAG roots are nodes that appear in no edge's `to` field.
+5. If `path_rules` is non-empty, emit `path_reviewer_map: Array<{pattern, role}>` by mapping the rules' path globs to reviewer roles.
+
+## Emit a Plan JSON conforming to `plan.schema.json`
+
+Required top-level fields:
+- `type: "plan"`
+- `id` — supplied by orchestrator (the next available ID in the project's work-item namespace)
+- `project` — supplied by orchestrator
+- `status: "drafting"`
+- `owner` — `{ "kind": "agent", "id": "plan" }`
+- `parent_rfc: { project: <rfc.project>, id: <rfc.id> }`
+- `task_dag` — as described above
+- `tasks` — array of full Task docs conforming to `task.schema.json`
+
+### Critical runtime invariants
+- The set of `tasks[].id` MUST equal the set of workItemRefs in `task_dag.nodes`. No task without a DAG node; no DAG node without a task.
+- `task_dag.edges` MUST form an acyclic graph. Cycles will be rejected by the orchestrator at materialisation time.
+- `additionalProperties: false` on Plan and on each Task — emit ONLY schema-defined fields.
+
+### Important: the Plan has NO `title` field
+Unlike RFC / Spike / Task, the Plan schema does not define a `title` field. Do not add one.
+
+## Task IDs
+- Each task's `id` must follow the project's ID convention (typically `<PROJECT>-<N>`).
+- Task IDs must not collide with any existing `.cloverleaf/{rfcs,spikes,plans,tasks}/` work item. The orchestrator supplies a `next_id_base` hint in its invocation context; allocate task IDs sequentially starting from that base.
+- Example: if `next_id_base` is `CLV-13` and you're emitting 3 tasks, use `CLV-13`, `CLV-14`, `CLV-15` in `tasks[]` and in `task_dag.nodes`.
+
+## Output format
+Write the Plan JSON to stdout, nothing else. No prose, no markdown fences. The orchestrator captures stdout and validates against `plan.schema.json` (and each task via `task.schema.json`). Budget: 3 bounces per invocation.
+
+## General rules
+- **Schema compliance is mandatory.** Each task in `tasks[]` must independently pass `task.schema.json` validation.
+- **No file writes.** Orchestrator persists your output.
+- Gate for Plan approval: `task_batch_gate` (approved by human after `gate-pending`).

package/prompts/researcher.md

@@ -0,0 +1,74 @@
+# Researcher Agent
+
+**Operation:** {{operation}} (`draftRfc` or `runSpike`)
+
+**Repo root:** {{repo_root}}
+**Doc context URI:** {{doc_context_uri}}
+
+You are the Researcher Agent. Your role is to ground ideas in the project's existing AI-facing documentation, then emit either an RFC (when drafting) or Spike findings (when investigating). You do not execute production code changes; you read docs and emit structured JSON.
+
+---
+
+## If operation = draftRfc
+
+**Brief:** {{brief}}
+
+**Prior RFC (if this is a re-draft after spikes):** {{prior_rfc}}
+**Completed spikes (if any):** {{completed_spikes}}
+
+### Your task
+1. Read the docs under `{{repo_root}}/{{doc_context_uri}}` that are relevant to the brief.
+2. If `prior_rfc` is non-empty, read it and the `completed_spikes` — your output may be identical to the prior RFC if no revision is needed, or a revised body if findings warrant change.
+3. Emit a single JSON document conforming to `rfc.schema.json` (from `@cloverleaf/standard`). Required top-level fields:
+   - `type: "rfc"`
+   - `id` — supplied by orchestrator via `{{repo_root}}` context; preserve the existing ID if prior_rfc is given, else use the orchestrator's allocated ID
+   - `project` — supplied by orchestrator
+   - `status: "drafting"`
+   - `owner` — object `{ kind: "agent"|"human"|"system", id: string }`; use `{ "kind": "agent", "id": "researcher" }`
+   - `title` — short name
+   - `problem` — paragraph describing what's wrong or missing
+   - `solution` — paragraph describing the proposed approach
+   - `unknowns` — **array of strings**, each entry is one uncertainty that should become a Spike (e.g. "What is the webkit install size?"). Empty array if no uncertainties.
+   - `acceptance_criteria` — array of strings (minItems: 1), each a measurable condition for RFC approval
+   - `out_of_scope` — array of strings; can be empty
+
+### Important schema notes
+- **The RFC does NOT contain a `spikes` field.** Spikes are separate work items created by the orchestrator after reading your `unknowns[]`. Each `unknowns[]` entry becomes a Spike's `question`.
+- `additionalProperties: false` — do not emit extra fields. Optional schema fields: `parent`, `relationships`, `extensions`.
+
+### Output format
+Write the JSON to stdout, nothing else. No prose, no markdown fences, no explanation. The orchestrator captures stdout and validates against the schema. Budget: 3 bounces per invocation.
+
+---
+
+## If operation = runSpike
+
+**Spike input:** {{spike}}
+
+### Your task
+1. Read the spike's `question` and `method` fields.
+2. `method` is one of:
+   - `research` — read documentation, synthesise an answer
+   - `prototype` — describe a minimal prototype (you don't build it — the Implementer does in Delivery; spike output describes what to prototype)
+   - `benchmark` — describe what to measure and expected comparison axes
+3. Investigate using `{{repo_root}}/{{doc_context_uri}}` docs plus any read-only code inspection necessary. Do NOT modify files.
+4. Emit the input spike object with these additions/changes:
+   - `status: "completed"`
+   - `findings: string` — **a single string** summarising evidence-backed observations. Multi-sentence paragraphs are fine; do NOT emit an array.
+   - `recommendation: string` — **a single string** summarising the implication for the RFC / Plan.
+
+### Schema compliance
+- Preserve all existing spike fields (`id, type, owner, project, title, parent_rfc, question, method`).
+- Add `findings` and `recommendation`.
+- Output must conform to `spike.schema.json` (from `@cloverleaf/standard`).
+- `additionalProperties: false` — no extra fields.
+
+### Output format
+Write the updated spike JSON to stdout, nothing else. Budget: 3 bounces per invocation.
+
+---
+
+## General rules
+- **Schema compliance is mandatory.** If your output fails AJV validation, you bounce and try again. Budget: 3 bounces per invocation.
+- **No side-effects on the filesystem.** Don't write files. The orchestrator persists your output.
+- **No tool use beyond reading.** v0.5 limits Researcher to doc-reading; web search and external tools are future work.

package/skills/cloverleaf-breakdown/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: cloverleaf-breakdown
+description: Invoke the Plan agent (operation=breakdown) to decompose an approved RFC + completed spikes into a Plan with task_dag + inline tasks. Transitions Plan drafting → gate-pending (task_batch_gate). Usage — /cloverleaf-breakdown <RFC-ID>.
+---
+
+# Cloverleaf — Plan breakdown
+
+The user has invoked this skill with an RFC-ID (e.g., `CLV-009`).
+
+## Steps
+
+1. Capture `<RFC-ID>` as `$RFC_ID`. If missing, report usage and stop.
+
+2. Load and verify the RFC is in status `approved`:
+   ```
+   cloverleaf-cli load-rfc <repo_root> <RFC-ID>
+   ```
+   If `status !== "approved"`, report "RFC must be approved before breakdown" and stop.
+
+3. Collect all completed Spikes for this RFC. For each `.cloverleaf/spikes/*.json`:
+   - Parse the JSON.
+   - If `parent_rfc.id === $RFC_ID` AND `parent_rfc.project === <rfc.project>` AND `status === "completed"`: include in the SPIKES array.
+   - If zero matches, SPIKES is `[]`.
+
+4. Load discovery config:
+   ```bash
+   CFG=$(cloverleaf-cli discovery-config --repo-root <repo_root>)
+   DOC_CTX=$(echo "$CFG" | jq -r .docContextUri)
+   PROJECT_ID=$(echo "$CFG" | jq -r .projectId)
+   ```
+
+5. Compute the next work-item ID (this is the Plan's ID):
+   ```
+   PLAN_ID=$(cloverleaf-cli next-work-item-id <repo_root> $PROJECT_ID)
+   ```
+
+6. Dispatch the Plan subagent via the Task tool:
+   - `subagent_type`: `general-purpose`
+   - `model`: `sonnet`
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/plan.md`, with placeholders:
+     - `{{rfc}}` → the full RFC JSON
+     - `{{spikes}}` → the SPIKES JSON array
+     - `{{doc_context_uri}}` → `$DOC_CTX`
+     - `{{repo_root}}` → absolute path to the current repo
+     - `{{path_rules}}` → `null` (v0.5 does not auto-populate path_rules; defer to v0.6)
+
+   In the subagent context, also supply a hint that `next_id_base === $PLAN_ID`, so task IDs in `tasks[]` start at `PLAN_ID + 1`. The Plan agent allocates its own ID as `next_id_base` and task IDs sequentially after.
+
+7. Parse subagent response — expected JSON conforming to `plan.schema.json`. Required fields: `id, type: "plan", status: "drafting", owner, project, parent_rfc, task_dag (edge-based), tasks (inline Task docs, status=pending)`. 3-bounce budget per invocation.
+
+8. Ensure output `plan.id === $PLAN_ID`, `project === $PROJECT_ID`, `parent_rfc === { project: <rfc.project>, id: $RFC_ID }`. If the subagent drifted, override these before save.
+
+9. Save the Plan:
+   ```
+   cloverleaf-cli save-plan <repo_root> /tmp/plan-$PLAN_ID.json
+   ```
+
+10. Transition drafting → gate-pending:
+    ```
+    cloverleaf-cli advance-plan <repo_root> $PLAN_ID gate-pending agent task_batch_gate
+    ```
+
+11. Commit:
+    ```bash
+    git add .cloverleaf/plans/ .cloverleaf/events/
+    git commit -m "cloverleaf: plan $PLAN_ID for RFC $RFC_ID → gate-pending"
+    ```
+
+12. Print the Plan ID.
+
+## Notes
+
+- Tasks from `plan.tasks[]` are NOT yet materialised on disk. Materialisation happens only after a human approves via `/cloverleaf-gate $PLAN_ID approve`, which transitions the Plan to `approved`, at which point the orchestrator runs `cloverleaf-cli materialise-tasks`.
+- If the RFC has no completed spikes (`unknowns[]` was empty), SPIKES is `[]` and the Plan agent works from the RFC alone.

package/skills/cloverleaf-discover/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: cloverleaf-discover
+description: End-to-end Discovery orchestrator. Drives RFC → (Spikes) → Plan → gates → task materialisation. Blocks on human gate decisions (rfc_strategy_gate, task_batch_gate). On Plan approval, materialises tasks and asks whether to kick off /cloverleaf-run on the first DAG root. Usage — /cloverleaf-discover <brief-file>.
+---
+
+# Cloverleaf — discover (Discovery orchestrator)
+
+The user has invoked this skill with a brief file path (e.g., `docs/briefs/cross-browser-ui-review.md`).
+
+## Branch discipline
+
+Each sub-skill runs from `main`. Between steps, confirm branch is `main` before proceeding. All sub-skills return the user to `main`.
+
+## Per-agent bounce budget (in-session)
+
+- **Researcher and Plan agent bounces are budgeted inside the sub-skills** (`/cloverleaf-draft-rfc`, `/cloverleaf-spike`, `/cloverleaf-breakdown`), each with a 3-bounce per-invocation budget. The orchestrator invokes each sub-skill once per step — if a sub-skill exhausts its budget, it halts, and the orchestrator treats that as a hard halt and dumps state.
+- **Revise loops are budgeted in the orchestrator:**
+  ```
+  MAX_REVISE_LOOPS = 3
+  ```
+  Resets on each `/cloverleaf-discover` invocation.
+
+## Steps
+
+1. Capture `<brief-file>` as `$BRIEF_FILE`. Verify file exists:
+   ```bash
+   [ -f "$BRIEF_FILE" ] || { echo "Brief file not found: $BRIEF_FILE" >&2; exit 1; }
+   ```
+
+2. Verify branch is `main`:
+   ```bash
+   [ "$(git rev-parse --abbrev-ref HEAD)" = "main" ] || { echo "Run /cloverleaf-discover from main" >&2; exit 1; }
+   ```
+
+3. **Create the RFC** — invoke `/cloverleaf-new-rfc $BRIEF_FILE`. Capture the printed RFC ID as `$RFC_ID`.
+
+   Initialise revise loop counter:
+   ```
+   revise_loops = 0
+   ```
+
+4. **Draft RFC (Researcher draftRfc)** — invoke `/cloverleaf-draft-rfc $RFC_ID`. Researcher runs with a per-invocation bounce budget (3 bounces inside draft-rfc).
+   - On bounce exhaustion (draft-rfc exits non-zero): dump state to `.cloverleaf/runs/$RFC_ID/discover-crash.json` and halt.
+   - Reload the RFC. Its new status is either `spike-in-flight` (unknowns non-empty) or `planning` (unknowns empty).
+
+5. **Conditional on RFC status after step 4:**
+   - If `planning`: skip the spike loop below; proceed to step 6.
+   - If `spike-in-flight`: run every pending spike linked to this RFC:
+     ```bash
+     for each spike in .cloverleaf/spikes/*.json where parent_rfc.id === $RFC_ID AND status === "pending":
+       invoke /cloverleaf-spike <SPIKE_ID>.
+     ```
+
+     If `/cloverleaf-spike` exits non-zero or leaves the spike in a non-`completed` status after returning, treat that as bounce exhaustion: dump state to `.cloverleaf/runs/$RFC_ID/discover-crash.json` (including the spike ID) and halt. The orchestrator does NOT resume partially-run spike trees — if any spike is unresolved, the whole Discovery halts.
+
+     After all spikes complete:
+
+     1. Transition RFC spike-in-flight → drafting:
+        ```
+        cloverleaf-cli advance-rfc <repo_root> $RFC_ID drafting agent
+        ```
+     2. Re-invoke `/cloverleaf-draft-rfc $RFC_ID` — Researcher sees the completed spikes and may revise the RFC body. draft-rfc itself re-transitions the RFC to `spike-in-flight` (if new unknowns emerge — should not happen the second time since spikes were answered) or `planning` (expected path).
+
+     Rationale: redundant redraft is cheap; avoids introducing an off-contract "rfc_revision_required" boolean. The human gate at step 6 catches any missed revisions.
+
+6. **Gate: rfc_strategy_gate** — transition RFC to gate-pending:
+   ```
+   cloverleaf-cli advance-rfc <repo_root> $RFC_ID gate-pending agent rfc_strategy_gate
+   ```
+
+   Prompt human (blocking readline):
+   ```
+   RFC $RFC_ID at rfc_strategy_gate: approve / reject / revise [reason]? > _
+   ```
+
+   Parse input. On:
+   - `approve` → invoke `/cloverleaf-gate $RFC_ID approve`. Continue to step 7.
+   - `reject [reason]` → invoke `/cloverleaf-gate $RFC_ID reject [reason]`. Exit with summary.
+   - `revise [reason]` → invoke `/cloverleaf-gate $RFC_ID revise [reason]`. `revise_loops += 1`. If `revise_loops >= MAX_REVISE_LOOPS`, dump state and halt. Else loop back to step 4.
+
+7. **Plan breakdown** — invoke `/cloverleaf-breakdown $RFC_ID`. Per-invocation bounce budget (3 bounces inside breakdown). Capture `$PLAN_ID`. On bounce exhaustion: dump state and halt.
+
+8. **Gate: task_batch_gate** — Plan is already in `gate-pending` (set by breakdown). Prompt:
+   ```
+   PLN $PLAN_ID at task_batch_gate: approve / reject [reason]? > _
+   ```
+
+   On:
+   - `approve` → invoke `/cloverleaf-gate $PLAN_ID approve`. Continue.
+   - `reject [reason]` → invoke `/cloverleaf-gate $PLAN_ID reject [reason]`. Exit with summary.
+
+9. **Materialise tasks**:
+   ```bash
+   OUT=$(cloverleaf-cli materialise-tasks <repo_root> $PLAN_ID)
+   TASK_IDS=$(echo "$OUT" | jq -r '.task_ids[]')
+   ```
+
+   On materialise-tasks failure (cycle detected, or AJV validation error):
+   - The error message from `cloverleaf-cli` identifies the failing task.
+   - `materialiseTasksFromPlan` is atomic: the cycle-check and AJV pre-validation run BEFORE any file write, so no task files were created.
+   - The Plan remains in `approved` status (the gate was legitimately approved; the materialisation issue is with the Plan's own task DAG, not the gate decision).
+   - Dump state to `.cloverleaf/runs/$PLAN_ID/materialise-crash.json` and halt.
+   - Operator investigation typically leads to a new `/cloverleaf-breakdown` run to produce a corrected Plan (the rejected path is via the ORIGINAL gate, not a post-approval state correction).
+
+10. **Compute DAG roots**:
+    ```bash
+    PLAN_JSON=$(cloverleaf-cli load-plan <repo_root> $PLAN_ID)
+
+    # DAG roots = nodes whose id never appears as `to.id` in any edge.
+    # v0.5 picks the FIRST root only; multi-root concurrent Delivery is v0.6.
+    FIRST_ROOT=$(echo "$PLAN_JSON" | jq -r '
+      (.task_dag.edges | map(.to.id)) as $targets
+      | [.task_dag.nodes[] | select(.id as $n | ($targets | index($n)) | not) | .id][0]
+    ')
+    ```
+
+    v0.5 simplified rule: pick the FIRST root only (first `nodes[]` entry whose `id` does not appear in any `edges[].to.id`). Defer multi-root walk to v0.6.
+
+11. **Prompt to kick off first root** (blocking readline):
+    ```
+    N tasks materialised: $TASK_IDS.
+    DAG roots: $FIRST_ROOT.
+    Run first root via /cloverleaf-run now? [y/N] > _
+    ```
+
+    On `y` or `yes` (case-insensitive): invoke `/cloverleaf-run <FIRST_ROOT>`. On anything else: exit with summary.
+
+12. **Exit summary**:
+    - RFC ID + final status
+    - Spike IDs + findings summary (if any)
+    - Plan ID + task count
+    - Materialised task IDs
+    - Whether first root was invoked (and its outcome if so)
+
+## Notes
+
+- v0.5 prompts only for the FIRST DAG root. Multi-root concurrent Delivery is v0.6 scope.
+- All bounces and revise loops halt cleanly with a state dump at `.cloverleaf/runs/<RFC_ID>/discover-crash.json`. No partial work is left in an inconsistent state — the gate_decision events and work-item status are always coherent.
+- The readline prompts are compatible with the user's session-bridging tool for automated dogfooding.
+- "Invoke `/cloverleaf-X`" means spawn the sub-skill via the Skill tool — do NOT re-enter `/cloverleaf-discover` recursively. Sub-skills run in-process (same session) and return control to this orchestrator.

package/skills/cloverleaf-draft-rfc/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: cloverleaf-draft-rfc
+description: Invoke the Researcher agent (operation=draftRfc) to populate an RFC body from its brief. Emits zero or more Spike work items from the RFC's unknowns[]. Transitions the RFC drafting → spike-in-flight (if unknowns exist) or drafting → planning (if no unknowns). Usage — /cloverleaf-draft-rfc <RFC-ID>.
+---
+
+# Cloverleaf — draft RFC
+
+The user has invoked this skill with an RFC-ID (e.g., `CLV-009`).
+
+## Steps
+
+1. Capture `<RFC-ID>` as `$RFC_ID`. If missing, report usage and stop.
+
+2. Load the RFC:
+   ```
+   cloverleaf-cli load-rfc <repo_root> <RFC-ID>
+   ```
+   Parse the JSON. Verify `status === "drafting"`. If not, report and stop.
+
+3. Load the discovery config:
+   ```bash
+   CFG=$(cloverleaf-cli discovery-config --repo-root <repo_root>)
+   DOC_CTX=$(echo "$CFG" | jq -r .docContextUri)
+   ```
+
+4. Gather re-draft context (optional — used when re-invoked after spikes):
+   - `PRIOR_RFC`: the current RFC JSON (for a re-draft, same content)
+   - `COMPLETED_SPIKES`: for each spike ref linked to this RFC (via spike's `parent_rfc` field), if `status === "completed"`, include its findings/recommendation. Build a JSON array. If none, use `[]`.
+
+   Find all spikes for this RFC by scanning `.cloverleaf/spikes/*.json` for files whose `parent_rfc.id === $RFC_ID`. Use jq. If none, the array is empty.
+
+5. Dispatch the Researcher subagent via the Task tool:
+   - `subagent_type`: `general-purpose`
+   - `model`: `sonnet`
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/researcher.md`, with placeholders substituted:
+     - `{{operation}}` → `draftRfc`
+     - `{{brief}}` → the RFC's `problem` field (seeded by `/cloverleaf-new-rfc`)
+     - `{{doc_context_uri}}` → `$DOC_CTX`
+     - `{{repo_root}}` → absolute path to the current repo
+     - `{{prior_rfc}}` → `PRIOR_RFC` JSON (or the literal string `null` for first draft)
+     - `{{completed_spikes}}` → `COMPLETED_SPIKES` JSON array (or `[]`)
+     - `{{spike}}` → (unused for draftRfc; substitute `null`)
+
+6. Parse subagent's response: expected JSON conforming to `rfc.schema.json`. Required fields: `id`, `type: "rfc"`, `status: "drafting"`, `owner`, `project`, `title`, `problem`, `solution`, `unknowns` (array of strings), `acceptance_criteria`, `out_of_scope`.
+
+   If output fails schema validation: bounce. Budget: 3 bounces per invocation. On budget exhaustion: report and stop without advancing state.
+
+7. Ensure output `id === $RFC_ID` and `project === <original>`. If the subagent changed them, override back.
+
+8. Save the populated RFC:
+   ```bash
+   cloverleaf-cli save-rfc <repo_root> /tmp/rfc-draft-$RFC_ID.json
+   ```
+
+9. Inspect `rfc.unknowns[]`:
+
+   **If `unknowns.length > 0`:** create one Spike per unknown:
+   ```bash
+   for unknown in rfc.unknowns:
+     SPIKE_ID=$(cloverleaf-cli next-work-item-id <repo_root> <project>)
+     cat > /tmp/spike-$SPIKE_ID.json <<EOF
+     {
+       "type": "spike",
+       "project": "<project>",
+       "id": "$SPIKE_ID",
+       "status": "pending",
+       "owner": { "kind": "agent", "id": "researcher" },
+       "title": "<first 80 chars of unknown>",
+       "parent_rfc": { "project": "<project>", "id": "$RFC_ID" },
+       "question": "<unknown>",
+       "method": "research"
+     }
+     EOF
+     cloverleaf-cli save-spike <repo_root> /tmp/spike-$SPIKE_ID.json
+   ```
+
+   Then transition RFC:
+   ```
+   cloverleaf-cli advance-rfc <repo_root> <RFC-ID> spike-in-flight agent
+   ```
+
+   **If `unknowns.length === 0`:** transition RFC directly to planning:
+   ```
+   cloverleaf-cli advance-rfc <repo_root> <RFC-ID> planning agent
+   ```
+
+10. Clean up temp files. Commit state files under `.cloverleaf/`:
+    ```bash
+    git add .cloverleaf/rfcs/ .cloverleaf/spikes/ .cloverleaf/events/
+    git commit -m "cloverleaf: draft RFC $RFC_ID + spike emission"
+    ```
+
+11. Report: RFC body populated; N spikes created (list IDs); RFC status now `spike-in-flight` or `planning`.
+
+## Notes
+
+- This skill does NOT prompt for human input. It's a pure agent step.
+- The orchestrator (`/cloverleaf-discover`) invokes this plus manages bounces and gates.
+- For a re-draft after spikes complete, invoke this skill again with the same RFC-ID — it will pick up completed spikes and may revise the RFC body.

package/skills/cloverleaf-gate/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: cloverleaf-gate
+description: Human gate action on an RFC (rfc_strategy_gate) or Plan (task_batch_gate) in status gate-pending. Usage — /cloverleaf-gate <item-id> <approve|reject|revise> [reason]. `revise` is valid only at rfc_strategy_gate (RFC only).
+---
+
+# Cloverleaf — human gate
+
+The user has invoked this skill with `<item-id> <action> [reason]`.
+
+## Steps
+
+1. Capture arguments:
+   - `$ITEM_ID` = first positional arg
+   - `$ACTION` = second positional arg (must be `approve`, `reject`, or `revise`)
+   - `$REASON` = remaining args joined with spaces (optional)
+
+   If `ITEM_ID` or `ACTION` is missing, report usage and stop.
+
+2. Validate action:
+   ```bash
+   case "$ACTION" in
+     approve|reject|revise) ;;
+     *) echo "Invalid action: $ACTION. Use approve, reject, or revise." >&2; exit 1 ;;
+   esac
+   ```
+
+3. Detect work-item type by checking which directory has the JSON file:
+   ```bash
+   if [ -f "<repo_root>/.cloverleaf/rfcs/$ITEM_ID.json" ]; then
+     TYPE=rfc
+     GATE=rfc_strategy_gate
+   elif [ -f "<repo_root>/.cloverleaf/plans/$ITEM_ID.json" ]; then
+     TYPE=plan
+     GATE=task_batch_gate
+   else
+     echo "No RFC or Plan found with ID $ITEM_ID" >&2
+     exit 1
+   fi
+   ```
+
+4. Validate that `revise` is only valid at `rfc_strategy_gate` (i.e., on RFCs — revise is only exclusive to rfc_strategy_gate):
+   ```bash
+   if [ "$ACTION" = "revise" ] && [ "$TYPE" != "rfc" ]; then
+     echo "revise is only valid at rfc_strategy_gate (RFCs). Use reject on Plans." >&2
+     exit 2
+   fi
+   ```
+
+5. Verify the item is in `gate-pending` status:
+   ```bash
+   STATUS=$(cloverleaf-cli load-$TYPE <repo_root> $ITEM_ID | jq -r .status)
+   if [ "$STATUS" != "gate-pending" ]; then
+     echo "$TYPE $ITEM_ID is in status '$STATUS', not gate-pending" >&2
+     exit 3
+   fi
+   ```
+
+6. Emit the gate-decision event:
+   ```bash
+   if [ -n "$REASON" ]; then
+     cloverleaf-cli emit-gate-decision <repo_root> $ITEM_ID $GATE $ACTION human --comment="$REASON"
+   else
+     cloverleaf-cli emit-gate-decision <repo_root> $ITEM_ID $GATE $ACTION human
+   fi
+   ```
+
+7. Advance the work-item state:
+   ```bash
+   case "$ACTION" in
+     approve)
+       cloverleaf-cli advance-$TYPE <repo_root> $ITEM_ID approved human $GATE
+       ;;
+     reject)
+       cloverleaf-cli advance-$TYPE <repo_root> $ITEM_ID rejected human $GATE
+       ;;
+     revise)
+       # RFC-only — validated in step 4
+       cloverleaf-cli advance-rfc <repo_root> $ITEM_ID drafting human $GATE
+       # Persisting the revise reason as a feedback finding is deferred to v0.6.
+       # For now, the reason is surfaced on stdout so the caller can capture it
+       # and pass it back via the next /cloverleaf-draft-rfc invocation context.
+       if [ -n "$REASON" ]; then
+         echo "revise reason: $REASON"
+       fi
+       ;;
+   esac
+   ```
+
+8. Commit state files:
+   ```bash
+   git add .cloverleaf/rfcs/ .cloverleaf/plans/ .cloverleaf/events/
+   git commit -m "cloverleaf: gate $ITEM_ID $ACTION ($GATE)"
+   ```
+
+9. Print the new status:
+   ```bash
+   NEW=$(cloverleaf-cli load-$TYPE <repo_root> $ITEM_ID | jq -r .status)
+   echo "$ITEM_ID: $STATUS → $NEW"
+   ```
+
+## Notes
+
+- `revise` (RFC only) returns the RFC to `drafting`. The orchestrator loops back to `/cloverleaf-draft-rfc`.
+- On `reject` of an RFC: terminal (enters rejected state; orchestrator halts).
+- On `reject` of a Plan: plan enters rejected state; it can be re-decomposed via a new `/cloverleaf-breakdown` run (rejected → drafting via agent is a legal transition).
+- `[reason]` text is persisted in the gate_decision event's `comment` field. For `revise`, it's also echoed to stdout so the calling orchestrator can feed it back to the Researcher on re-draft.

package/skills/cloverleaf-new-rfc/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: cloverleaf-new-rfc
+description: Scaffold a new RFC work item from a brief file. Usage — /cloverleaf-new-rfc <brief-file>. Writes `.cloverleaf/rfcs/<ID>.json` with status=drafting and empty body fields (populated by /cloverleaf-draft-rfc). Returns the new RFC ID.
+---
+
+# Cloverleaf — new RFC
+
+## Steps
+
+1. Capture `<brief-file>` (first positional arg). Verify file exists:
+
+```bash
+BRIEF_FILE="$1"
+[ -f "$BRIEF_FILE" ] || { echo "Brief file not found: $BRIEF_FILE" >&2; exit 1; }
+```
+
+2. Load the discovery config to get `projectId`:
+
+```bash
+CFG=$(cloverleaf-cli discovery-config --repo-root $(pwd))
+PROJECT_ID=$(echo "$CFG" | jq -r .projectId)
+[ -z "$PROJECT_ID" ] && { echo "set projectId in .cloverleaf/config/discovery.json" >&2; exit 2; }
+```
+
+3. Compute next work-item ID:
+
+```bash
+RFC_ID=$(cloverleaf-cli next-work-item-id $(pwd) "$PROJECT_ID")
+```
+
+4. Read brief content:
+
+```bash
+BRIEF_CONTENT=$(cat "$BRIEF_FILE")
+```
+
+5. Build the RFC skeleton JSON. Derive a short title from the brief's first non-empty line (truncate if long). Problem = brief content. All other body fields are seeded with schema-conformant placeholders that `/cloverleaf-draft-rfc` will overwrite.
+
+```bash
+FIRST_LINE=$(head -n 1 "$BRIEF_FILE" | sed 's/^# *//' | cut -c1-120)
+TMPFILE=$(mktemp --suffix=.json)
+
+cat > "$TMPFILE" <<EOF
+{
+  "type": "rfc",
+  "project": "$PROJECT_ID",
+  "id": "$RFC_ID",
+  "status": "drafting",
+  "owner": { "kind": "agent", "id": "researcher" },
+  "title": $(printf '%s' "$FIRST_LINE" | jq -Rs .),
+  "problem": $(printf '%s' "$BRIEF_CONTENT" | jq -Rs .),
+  "solution": "TBD — to be populated by /cloverleaf-draft-rfc.",
+  "unknowns": [],
+  "acceptance_criteria": ["RFC body populated by researcher agent"],
+  "out_of_scope": []
+}
+EOF
+```
+
+6. Save via CLI (validates against rfc.schema.json):
+
+```bash
+cloverleaf-cli save-rfc $(pwd) "$TMPFILE"
+rm "$TMPFILE"
+```
+
+7. Print the new RFC ID to stdout:
+
+```bash
+echo "$RFC_ID"
+```
+
+## Notes
+
+- This skill does NOT invoke the Researcher agent. Use `/cloverleaf-draft-rfc <RFC_ID>` to populate body from the brief + doc grounding.
+- To drive the whole Discovery flow end-to-end, use `/cloverleaf-discover <brief-file>` instead.