@cloverleaf/reference-impl 0.1.1

package/README.md

@@ -0,0 +1,88 @@
+# @cloverleaf/reference-impl
+
+Reference implementation of the Cloverleaf methodology as a set of Claude Code skills. This package implements the **Tight Loop** — Implementer + Reviewer — letting a user drive a Task from `pending` to `merged` with state, events, and feedback recorded in the repo under `.cloverleaf/`.
+
+Implements [Cloverleaf Standard](../standard/) v0.3.0 at L2 (Exchange) conformance.
+
+## Install
+
+From this directory:
+
+```bash
+npm install            # pulls @cloverleaf/standard + deps
+./install.sh           # symlinks skills into ~/.claude/plugins/cloverleaf/
+# or:
+./install.sh --project # local install into ./.claude/plugins/cloverleaf/
+```
+
+## Skills provided
+
+| Slash command | Role |
+|---|---|
+| `/cloverleaf-new-task "<brief>"` | Scaffold a new Task JSON from a prose brief. |
+| `/cloverleaf-implement <TASK-ID>` | Dispatch Implementer subagent; advances pending → review. |
+| `/cloverleaf-review <TASK-ID>` | Dispatch Reviewer subagent; pass → automated-gates, bounce → implementing. |
+| `/cloverleaf-merge <TASK-ID>` | Human gate; confirm and transition automated-gates → merged. |
+| `/cloverleaf-run <TASK-ID>` | Orchestrator: loops implement → review with up to 3 bounces, pauses at the human merge gate. |
+
+## Quick start — toy repo
+
+```bash
+cd examples/toy-repo
+npm install
+../../install.sh --project
+```
+
+In a Claude Code session in that directory:
+
+```
+/cloverleaf-run DEMO-001
+```
+
+Watch it walk the state machine, produce a branch `cloverleaf/DEMO-001` with a `multiply` function + tests, and pause at the merge gate.
+
+## What's in v0.1.0
+
+- Implementer + Reviewer agents (wired as subagents).
+- Full state machine transitions from `pending` to `merged` (fast-lane path), with stub transitions through `documenting` and `automated-gates`.
+- Per-project committed audit trail under `.cloverleaf/`.
+- Max 3 bounces before `escalated`.
+
+## What's NOT in v0.1.0
+
+- Researcher, Plan, Documenter, UI Reviewer, QA agents (stub transitions only).
+- HTTP endpoints for the agent OpenAPI contracts — skills are markdown-driven, not servers. L3 conformance deferred.
+- `git push` / PR creation — branch stays local; user handles remote.
+- Path-rules or risk-classifier-rules enforcement — fast-lane is hardcoded.
+
+See [upcoming releases](../CHANGELOG.md) for the roadmap.
+
+## Branch topology
+
+State commits (`.cloverleaf/**`) always land on `main`. Code commits land on a per-task feature branch named `cloverleaf/<task-id>`.
+
+- `main`: canonical audit trail. Every status-transition event, gate decision, and feedback envelope is committed here, in order.
+- `cloverleaf/<task-id>`: code for one task. Branched from main; the Implementer agent lives here.
+
+The skills handle the branch switching for you. After `/cloverleaf-implement <TASK-ID>` runs, you are back on main with the state updates committed; the `cloverleaf/<task-id>` branch holds the code ready for review. After `/cloverleaf-merge`, the audit trail reflects the merged state, and you push the code branch manually.
+
+The Reviewer never switches branches. It reads files via `git show` and runs tests in a `git worktree add` sidecar to avoid clobbering main's `.cloverleaf/`.
+
+## Package layout
+
+- `lib/` — TypeScript library used by the CLI. State, events, feedback, IDs, paths.
+- `skills/` — Claude Code skill markdown files.
+- `prompts/` — Implementer/Reviewer subagent system prompts.
+- `examples/toy-repo/` — standalone demo repo.
+- `tests/` — Vitest suite.
+
+## Development
+
+```bash
+npm test        # run the Vitest suite
+npm run test:watch
+```
+
+## License
+
+MIT — see [../LICENSE](../LICENSE).

package/VERSION

@@ -0,0 +1 @@
+0.1.1

package/install.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Cloverleaf Reference Impl installer.
+# Default: installs skills + CLI shim into ~/.claude/plugins/cloverleaf/.
+# --project: installs locally into ./.claude/plugins/cloverleaf/.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MODE="user"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --project) MODE="project"; shift ;;
+    --help|-h)
+      echo "Usage: ./install.sh [--project]"
+      echo "  --project: install locally in .claude/plugins/cloverleaf/"
+      echo "  (default): install at ~/.claude/plugins/cloverleaf/"
+      exit 0 ;;
+    *) echo "Unknown arg: $1"; exit 2 ;;
+  esac
+done
+
+if [[ "$MODE" == "user" ]]; then
+  INSTALL_ROOT="${HOME}/.claude/plugins/cloverleaf"
+else
+  INSTALL_ROOT="$(pwd)/.claude/plugins/cloverleaf"
+fi
+
+mkdir -p "${INSTALL_ROOT}/skills" "${INSTALL_ROOT}/prompts" "${INSTALL_ROOT}/bin"
+
+# Symlink skills
+for f in "${SCRIPT_DIR}/skills/"*.md; do
+  name="$(basename "$f")"
+  ln -sf "$f" "${INSTALL_ROOT}/skills/${name}"
+done
+
+# Symlink prompts
+for f in "${SCRIPT_DIR}/prompts/"*.md; do
+  name="$(basename "$f")"
+  ln -sf "$f" "${INSTALL_ROOT}/prompts/${name}"
+done
+
+# Write the CLI shim
+cat > "${INSTALL_ROOT}/bin/cloverleaf-cli" <<EOF
+#!/usr/bin/env bash
+exec npx --yes tsx "${SCRIPT_DIR}/lib/cli.ts" "\$@"
+EOF
+chmod +x "${INSTALL_ROOT}/bin/cloverleaf-cli"
+
+echo "Cloverleaf reference impl installed at: ${INSTALL_ROOT}"
+echo "Skills available: $(ls "${INSTALL_ROOT}/skills" | wc -l | tr -d ' ')"
+echo ""
+echo "Add ${INSTALL_ROOT}/bin to your PATH if you want to invoke cloverleaf-cli directly,"
+echo "or reference it by absolute path from your skill calls."

package/lib/cli.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Cloverleaf CLI dispatcher.
+ *
+ * Usage: cli.ts <command> [args...]
+ *
+ * Commands:
+ *   load-task <repoRoot> <taskId>
+ *   infer-project <repoRoot>
+ *   next-task-id <repoRoot> [--project=<p>]
+ *   advance-status <repoRoot> <taskId> <toStatus> <actor> [gate] [path]
+ *   write-feedback <repoRoot> <taskId> <envelopeJsonPath>
+ *   latest-feedback <repoRoot> <taskId>
+ *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
+ */
+
+import { readFileSync } from 'node:fs';
+import { loadTask } from './state.js';
+import { advanceStatus } from './state.js';
+import { emitGateDecision } from './events.js';
+import { writeFeedback, latestFeedback } from './feedback.js';
+import { nextTaskId, inferProject } from './ids.js';
+import type { FeedbackEnvelope } from './feedback.js';
+
+function die(msg: string, code = 1): never {
+  process.stderr.write(msg + '\n');
+  process.exit(code);
+}
+
+function usage(msg?: string): never {
+  if (msg) process.stderr.write(msg + '\n');
+  process.stderr.write(
+    'Usage: cli.ts <command> [args...]\n' +
+      'Commands:\n' +
+      '  load-task <repoRoot> <taskId>\n' +
+      '  infer-project <repoRoot>\n' +
+      '  next-task-id <repoRoot> [--project=<p>]\n' +
+      '  advance-status <repoRoot> <taskId> <toStatus> <actor> [gate] [path]\n' +
+      '  write-feedback <repoRoot> <taskId> <envelopeJsonPath>\n' +
+      '  latest-feedback <repoRoot> <taskId>\n' +
+      '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n'
+  );
+  process.exit(2);
+}
+
+const [, , command, ...rest] = process.argv;
+
+if (!command) {
+  usage('Error: no command given');
+}
+
+try {
+  switch (command) {
+    case 'load-task': {
+      const [repoRoot, taskId] = rest;
+      if (!repoRoot || !taskId) usage('load-task requires <repoRoot> <taskId>');
+      const task = loadTask(repoRoot, taskId);
+      process.stdout.write(JSON.stringify(task, null, 2) + '\n');
+      break;
+    }
+
+    case 'infer-project': {
+      const [repoRoot] = rest;
+      if (!repoRoot) usage('infer-project requires <repoRoot>');
+      const project = inferProject(repoRoot);
+      process.stdout.write(project + '\n');
+      break;
+    }
+
+    case 'next-task-id': {
+      // rest may contain --project=<p> flag among positional args
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const flags = rest.filter((a) => a.startsWith('--'));
+      const [repoRoot] = positional;
+      if (!repoRoot) usage('next-task-id requires <repoRoot>');
+      const projectFlag = flags.find((f) => f.startsWith('--project='));
+      const explicitProject = projectFlag ? projectFlag.replace('--project=', '') : undefined;
+      const project = inferProject(repoRoot, explicitProject);
+      const id = nextTaskId(repoRoot, project);
+      process.stdout.write(id + '\n');
+      break;
+    }
+
+    case 'advance-status': {
+      const [repoRoot, taskId, toStatus, actorArg, gate, path] = rest;
+      if (!repoRoot || !taskId || !toStatus || !actorArg)
+        usage('advance-status requires <repoRoot> <taskId> <toStatus> <actor> [gate] [path]');
+      if (actorArg !== 'agent' && actorArg !== 'human') {
+        die(`actor must be 'agent' or 'human' (got '${actorArg}')`, 2);
+      }
+      const actor: 'agent' | 'human' = actorArg;
+      const opts: { gate?: string; path?: 'fast_lane' | 'full_pipeline' } = {};
+      if (gate) opts.gate = gate;
+      if (path === 'fast_lane' || path === 'full_pipeline') opts.path = path;
+      const updated = advanceStatus(repoRoot, taskId, toStatus, actor, opts);
+      process.stdout.write(updated.status + '\n');
+      break;
+    }
+
+    case 'write-feedback': {
+      const [repoRoot, taskId, envelopeJsonPath] = rest;
+      if (!repoRoot || !taskId || !envelopeJsonPath)
+        usage('write-feedback requires <repoRoot> <taskId> <envelopeJsonPath>');
+      const envelope = JSON.parse(readFileSync(envelopeJsonPath, 'utf-8')) as FeedbackEnvelope;
+      const match = taskId.match(/^(.+)-\d+$/);
+      if (!match) die(`Invalid taskId format: ${taskId}`);
+      const project = match[1];
+      const writtenPath = writeFeedback(repoRoot, { project, taskId, envelope });
+      process.stdout.write(writtenPath + '\n');
+      break;
+    }
+
+    case 'latest-feedback': {
+      const [repoRoot, taskId] = rest;
+      if (!repoRoot || !taskId) usage('latest-feedback requires <repoRoot> <taskId>');
+      const envelope = latestFeedback(repoRoot, taskId);
+      if (envelope === null) {
+        process.stdout.write('');
+      } else {
+        process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+      }
+      break;
+    }
+
+    case 'emit-gate-decision': {
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const flags = rest.filter((a) => a.startsWith('--'));
+      const [repoRoot, workItemId, gate, decision, actorArg] = positional;
+      if (!repoRoot || !workItemId || !gate || !decision || !actorArg)
+        usage(
+          'emit-gate-decision requires <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]'
+        );
+      const validDecisions = ['approve', 'reject', 'revise', 'split', 'abandon', 'escalate'];
+      if (!validDecisions.includes(decision)) {
+        die(`decision must be one of: ${validDecisions.join(', ')}, got: ${decision}`);
+      }
+      if (actorArg !== 'agent' && actorArg !== 'human' && actorArg !== 'system') {
+        die(`actor must be "agent", "human", or "system", got: ${actorArg}`);
+      }
+      const commentFlag = flags.find((f) => f.startsWith('--comment='));
+      const comment = commentFlag ? commentFlag.replace('--comment=', '') : undefined;
+
+      // Derive project from workItemId (e.g. "DEMO-001" → "DEMO")
+      const wiMatch = workItemId.match(/^(.+)-\d+$/);
+      if (!wiMatch) die(`Cannot derive project from workItemId: ${workItemId}`);
+      const project = wiMatch[1];
+
+      const writtenPath = emitGateDecision(repoRoot, {
+        project,
+        workItemType: 'task',
+        workItemId,
+        gate,
+        decision: decision as 'approve' | 'reject' | 'revise' | 'split' | 'abandon' | 'escalate',
+        actor: actorArg as 'agent' | 'human' | 'system',
+        reasoning: comment,
+      });
+      process.stdout.write(writtenPath + '\n');
+      break;
+    }
+
+    default:
+      usage(`Unknown command: ${command}`);
+  }
+} catch (err: unknown) {
+  const msg = err instanceof Error ? err.message : String(err);
+  // Surface "illegal transition" errors with the right language
+  const lower = msg.toLowerCase();
+  if (lower.includes('illegal') || lower.includes('not allowed')) {
+    die(`Illegal transition: ${msg}`);
+  }
+  die(`Error: ${msg}`);
+}

package/lib/events.ts

@@ -0,0 +1,108 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { eventsDir } from './paths.js';
+import { nextEventId } from './ids.js';
+import { validateOrThrow } from './validate.js';
+
+export interface StatusTransitionParams {
+  project: string;
+  workItemType: 'task' | 'rfc' | 'spike' | 'plan';
+  workItemId: string;
+  from: string;
+  to: string;
+  actor: 'agent' | 'human' | 'system';
+  gate?: string;
+  path?: 'fast_lane' | 'full_pipeline';
+}
+
+export interface GateDecisionParams {
+  project: string;
+  workItemType: 'task' | 'rfc' | 'spike' | 'plan';
+  workItemId: string;
+  gate: string;
+  decision: 'approve' | 'reject' | 'revise' | 'split' | 'abandon' | 'escalate';
+  actor: 'agent' | 'human' | 'system';
+  reasoning?: string;
+}
+
+function actorObject(kind: 'agent' | 'human' | 'system'): { kind: string; id: string } {
+  const id = kind === 'agent' ? 'implementer' : kind === 'human' ? 'local-user' : 'system';
+  return { kind, id };
+}
+
+export function formatReason(opts: { gate?: string; path?: string }): string | undefined {
+  const parts: string[] = [];
+  if (opts.gate) parts.push(`gate=${opts.gate}`);
+  if (opts.path) parts.push(`path=${opts.path}`);
+  return parts.length > 0 ? parts.join('; ') : undefined;
+}
+
+/**
+ * Emits a status-transition event to `.cloverleaf/events/`.
+ * File name: `<PROJECT>-<NNN>-status.json` where NNN is the next per-project
+ * sequential number derived from existing event files.
+ *
+ * Returns the absolute path of the written file.
+ */
+export function emitStatusTransition(repoRoot: string, params: StatusTransitionParams): string {
+  const { project, workItemType, workItemId, from, to, actor } = params;
+  const seq = nextEventId(repoRoot, project);
+  const seqStr = String(seq).padStart(3, '0');
+  const filename = `${project}-${seqStr}-status.json`;
+  const filePath = join(eventsDir(repoRoot), filename);
+
+  // Build reason from gate and/or path if provided (schema only allows reason, not gate/path at top level).
+  const reason = formatReason({ gate: params.gate, path: params.path });
+
+  const doc: Record<string, unknown> = {
+    event_id: randomUUID(),
+    event_type: 'status_transition',
+    occurred_at: new Date().toISOString(),
+    work_item_id: { project, id: workItemId },
+    work_item_type: workItemType,
+    from_status: from,
+    to_status: to,
+    actor: actorObject(actor),
+  };
+  if (reason !== undefined) {
+    doc.reason = reason;
+  }
+
+  mkdirSync(eventsDir(repoRoot), { recursive: true });
+  validateOrThrow('https://cloverleaf.example/schemas/status-transition-event.schema.json', doc);
+  writeFileSync(filePath, JSON.stringify(doc, null, 2) + '\n');
+  return filePath;
+}
+
+/**
+ * Emits a gate-decision event to `.cloverleaf/events/`.
+ * File name: `<PROJECT>-<NNN>-gate.json`.
+ *
+ * Returns the absolute path of the written file.
+ */
+export function emitGateDecision(repoRoot: string, params: GateDecisionParams): string {
+  const { project, workItemId, gate, decision, actor, reasoning } = params;
+  const seq = nextEventId(repoRoot, project);
+  const seqStr = String(seq).padStart(3, '0');
+  const filename = `${project}-${seqStr}-gate.json`;
+  const filePath = join(eventsDir(repoRoot), filename);
+
+  const doc: Record<string, unknown> = {
+    event_id: randomUUID(),
+    event_type: 'gate_decision',
+    occurred_at: new Date().toISOString(),
+    gate,
+    work_item_id: { project, id: workItemId },
+    decision,
+    approver: actorObject(actor),
+  };
+  if (reasoning !== undefined) {
+    doc.comment = reasoning;
+  }
+
+  mkdirSync(eventsDir(repoRoot), { recursive: true });
+  validateOrThrow('https://cloverleaf.example/schemas/gate-decision-event.schema.json', doc);
+  writeFileSync(filePath, JSON.stringify(doc, null, 2) + '\n');
+  return filePath;
+}

package/lib/feedback.ts

@@ -0,0 +1,74 @@
+import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { feedbackDir } from './paths.js';
+import { nextFeedbackIteration } from './ids.js';
+import { validateOrThrow } from './validate.js';
+
+export type Verdict = 'pass' | 'bounce' | 'escalate';
+export type FindingSeverity = 'info' | 'warning' | 'error' | 'blocker';
+
+export interface FindingLocation {
+  file?: string;
+  line?: number;
+  work_item_id?: { project: string; id: string };
+}
+
+export interface Finding {
+  severity: FindingSeverity;
+  message: string;
+  location?: FindingLocation;
+  suggestion?: string;
+  rule?: string;
+}
+
+export interface FeedbackEnvelope {
+  verdict: Verdict;
+  summary?: string;
+  findings?: Finding[];
+  [key: string]: unknown;
+}
+
+export interface WriteFeedbackParams {
+  project: string;
+  taskId: string; // e.g. "ACME-001"
+  envelope: FeedbackEnvelope;
+}
+
+export function writeFeedback(repoRoot: string, params: WriteFeedbackParams): string {
+  const match = params.taskId.match(/^(.+)-(\d+)$/);
+  if (!match) throw new Error(`Invalid taskId: ${params.taskId}`);
+  const project = match[1];
+  const taskNum = parseInt(match[2], 10);
+  if (project !== params.project) {
+    throw new Error(`project mismatch: taskId=${params.taskId} vs project=${params.project}`);
+  }
+  const iteration = nextFeedbackIteration(repoRoot, project, taskNum);
+  const filename = `${params.taskId}-r${iteration}.json`;
+  const path = join(feedbackDir(repoRoot), filename);
+  mkdirSync(feedbackDir(repoRoot), { recursive: true });
+  validateOrThrow('https://cloverleaf.example/schemas/feedback.schema.json', params.envelope);
+  writeFileSync(path, JSON.stringify(params.envelope, null, 2) + '\n');
+  return path;
+}
+
+export function latestFeedback(repoRoot: string, taskId: string): FeedbackEnvelope | null {
+  const items = allFeedback(repoRoot, taskId);
+  return items.length === 0 ? null : items[items.length - 1];
+}
+
+export function allFeedback(repoRoot: string, taskId: string): FeedbackEnvelope[] {
+  const dir = feedbackDir(repoRoot);
+  if (!existsSync(dir)) return [];
+  const re = new RegExp(`^${escapeRegex(taskId)}-r(\\d+)\\.json$`);
+  const entries = readdirSync(dir)
+    .map((f) => ({ f, m: f.match(re) }))
+    .filter((x): x is { f: string; m: RegExpMatchArray } => !!x.m)
+    .sort((a, b) => parseInt(a.m[1], 10) - parseInt(b.m[1], 10));
+  return entries.map(({ f }) =>
+    JSON.parse(readFileSync(join(dir, f), 'utf-8')) as FeedbackEnvelope
+  );
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/lib/ids.ts

@@ -0,0 +1,59 @@
+import { readdirSync, existsSync } from 'node:fs';
+import { tasksDir, eventsDir, feedbackDir, projectsDir } from './paths.js';
+
+export function nextTaskId(repoRoot: string, project: string): string {
+  const dir = tasksDir(repoRoot);
+  if (!existsSync(dir)) return `${project}-001`;
+  const re = new RegExp(`^${escapeRegex(project)}-(\\d+)\\.json$`);
+  const nums = readdirSync(dir)
+    .map((f) => f.match(re))
+    .filter((m): m is RegExpMatchArray => !!m)
+    .map((m) => parseInt(m[1], 10));
+  const next = nums.length === 0 ? 1 : Math.max(...nums) + 1;
+  return `${project}-${String(next).padStart(3, '0')}`;
+}
+
+export function nextEventId(repoRoot: string, project: string): number {
+  const dir = eventsDir(repoRoot);
+  if (!existsSync(dir)) return 1;
+  const re = new RegExp(`^${escapeRegex(project)}-(\\d+)-(status|gate)\\.json$`);
+  const nums = readdirSync(dir)
+    .map((f) => f.match(re))
+    .filter((m): m is RegExpMatchArray => !!m)
+    .map((m) => parseInt(m[1], 10));
+  return nums.length === 0 ? 1 : Math.max(...nums) + 1;
+}
+
+export function nextFeedbackIteration(repoRoot: string, project: string, taskNum: number): number {
+  const dir = feedbackDir(repoRoot);
+  if (!existsSync(dir)) return 1;
+  const suffix = String(taskNum).padStart(3, '0');
+  const re = new RegExp(`^${escapeRegex(project)}-${suffix}-r(\\d+)\\.json$`);
+  const nums = readdirSync(dir)
+    .map((f) => f.match(re))
+    .filter((m): m is RegExpMatchArray => !!m)
+    .map((m) => parseInt(m[1], 10));
+  return nums.length === 0 ? 1 : Math.max(...nums) + 1;
+}
+
+export function listProjects(repoRoot: string): string[] {
+  const dir = projectsDir(repoRoot);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json') && !f.endsWith('.meta.json'))
+    .map((f) => f.replace(/\.json$/, ''));
+}
+
+export function inferProject(repoRoot: string, explicit?: string): string {
+  if (explicit) return explicit;
+  const projects = listProjects(repoRoot);
+  if (projects.length === 0) throw new Error('No projects found under .cloverleaf/projects/');
+  if (projects.length > 1) {
+    throw new Error(`Multiple projects found (${projects.join(', ')}); specify one explicitly.`);
+  }
+  return projects[0];
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/lib/index.ts

@@ -0,0 +1,6 @@
+export * from './paths.js';
+export * from './ids.js';
+export * from './state.js';
+export * from './events.js';
+export * from './feedback.js';
+export * from './validate.js';

package/lib/paths.ts

@@ -0,0 +1,35 @@
+import { resolve } from 'node:path';
+
+const CLOVERLEAF = '.cloverleaf';
+
+export function cloverleafDir(repoRoot: string): string {
+  return resolve(repoRoot, CLOVERLEAF);
+}
+
+export function projectsDir(repoRoot: string): string {
+  return resolve(cloverleafDir(repoRoot), 'projects');
+}
+
+export function tasksDir(repoRoot: string): string {
+  return resolve(cloverleafDir(repoRoot), 'tasks');
+}
+
+export function eventsDir(repoRoot: string): string {
+  return resolve(cloverleafDir(repoRoot), 'events');
+}
+
+export function feedbackDir(repoRoot: string): string {
+  return resolve(cloverleafDir(repoRoot), 'feedback');
+}
+
+export function rfcsDir(repoRoot: string): string {
+  return resolve(cloverleafDir(repoRoot), 'rfcs');
+}
+
+export function spikesDir(repoRoot: string): string {
+  return resolve(cloverleafDir(repoRoot), 'spikes');
+}
+
+export function plansDir(repoRoot: string): string {
+  return resolve(cloverleafDir(repoRoot), 'plans');
+}

package/lib/state.ts

@@ -0,0 +1,137 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { tasksDir, projectsDir } from './paths.js';
+import { emitStatusTransition, formatReason } from './events.js';
+
+// Import validator from @cloverleaf/standard.
+// The standard package ships TypeScript source only with no exports map.
+// Vitest (via vite-node) resolves .js → .ts for workspace symlinked packages,
+// so the .js convention works here. If it ever fails with "module not found",
+// switch the specifier to '@cloverleaf/standard/validators/index.ts'.
+import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
+import type { StatusTransitions, Task as SMTask } from '@cloverleaf/standard/validators/index.js';
+import { validateOrThrow } from './validate.js';
+
+const req = createRequire(import.meta.url);
+
+export interface TaskDoc {
+  type: 'task';
+  project: string;
+  id: string;
+  title: string;
+  status: string;
+  risk_class: 'low' | 'high';
+  owner: { kind: 'agent' | 'human' | 'system'; id: string };
+  acceptance_criteria: string[];
+  definition_of_done: string[];
+  context: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ProjectDoc {
+  key: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+export function loadTask(repoRoot: string, taskId: string): TaskDoc {
+  const path = join(tasksDir(repoRoot), `${taskId}.json`);
+  if (!existsSync(path)) throw new Error(`Task ${taskId} not found at ${path}`);
+  return JSON.parse(readFileSync(path, 'utf-8')) as TaskDoc;
+}
+
+export function saveTask(repoRoot: string, task: TaskDoc): void {
+  validateOrThrow('https://cloverleaf.example/schemas/task.schema.json', task);
+  const path = join(tasksDir(repoRoot), `${task.id}.json`);
+  writeFileSync(path, JSON.stringify(task, null, 2) + '\n');
+}
+
+export function loadProject(repoRoot: string, projectId: string): ProjectDoc {
+  const path = join(projectsDir(repoRoot), `${projectId}.json`);
+  if (!existsSync(path)) throw new Error(`Project ${projectId} not found at ${path}`);
+  return JSON.parse(readFileSync(path, 'utf-8')) as ProjectDoc;
+}
+
+function loadTaskStateMachine(): StatusTransitions {
+  // state-machines/task.json is a static JSON asset. Navigate from standard's
+  // package.json — no exports map support needed.
+  const pkgPath = req.resolve('@cloverleaf/standard/package.json');
+  const pkgDir = pkgPath.replace(/\/package\.json$/, '');
+  return JSON.parse(readFileSync(`${pkgDir}/state-machines/task.json`, 'utf-8')) as StatusTransitions;
+}
+
+export function advanceStatus(
+  repoRoot: string,
+  taskId: string,
+  toStatus: string,
+  actor: 'agent' | 'human',
+  options: { gate?: string; path?: 'fast_lane' | 'full_pipeline' } = {}
+): TaskDoc {
+  const task = loadTask(repoRoot, taskId);
+  const from = task.status;
+  const sm = loadTaskStateMachine();
+
+  // Read risk_class directly from the task (defaulting to 'low' if absent).
+  // The validator derives itemPath from workItem.risk_class: low → fast_lane, else full_pipeline.
+  // If caller passed options.path, translate it back to risk_class for the validator.
+  const riskClass: 'low' | 'high' =
+    options.path === 'fast_lane' ? 'low'
+    : options.path === 'full_pipeline' ? 'high'
+    : (task.risk_class ?? 'low');
+
+  // Build a minimal Task-shaped object so the validator can resolve path-tagged transitions.
+  const workItemForValidator: SMTask = {
+    type: 'task',
+    id: task.id,
+    project: task.project,
+    status: task.status,
+    risk_class: riskClass,
+    context: { rfc: { project: task.project, id: task.id } },
+    definition_of_done: task.definition_of_done,
+    acceptance_criteria: task.acceptance_criteria,
+  };
+
+  const reason = formatReason({ gate: options.gate, path: options.path });
+  const event = {
+    event_id: randomUUID(),
+    event_type: 'status_transition' as const,
+    occurred_at: new Date().toISOString(),
+    work_item_id: { project: task.project, id: task.id },
+    work_item_type: 'task' as const,
+    from_status: from,
+    to_status: toStatus,
+    actor: { kind: actor, id: actor },
+    ...(reason ? { reason } : {}),
+  };
+
+  const result = validateStatusTransitionLegality(event, sm, workItemForValidator);
+  if (!result.ok) {
+    const msgs = result.violations.map((v) => v.message).join('; ');
+    throw new Error(`Illegal transition ${from} → ${toStatus}: ${msgs}`);
+  }
+
+  // NEW: emit first, save second. validateStatusTransitionLegality stays above.
+  const emittedPath = emitStatusTransition(repoRoot, {
+    project: task.project,
+    workItemType: 'task',
+    workItemId: task.id,
+    from,
+    to: toStatus,
+    actor,
+    gate: options.gate,
+    path: options.path,
+  });
+
+  const proposed = { ...task, status: toStatus };
+  try {
+    saveTask(repoRoot, proposed);
+  } catch (err) {
+    const inner = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `orphan event written to ${emittedPath} but task save failed: ${inner}`
+    );
+  }
+  return proposed;
+}

package/lib/validate.ts

@@ -0,0 +1,61 @@
+import Ajv, { type ValidateFunction } from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const req = createRequire(import.meta.url);
+const pkgDir = req.resolve('@cloverleaf/standard/package.json').replace(/\/package\.json$/, '');
+
+const SCHEMA_FILES = [
+  'work-item.schema.json',
+  'project.schema.json',
+  'task.schema.json',
+  'rfc.schema.json',
+  'spike.schema.json',
+  'plan.schema.json',
+  'feedback.schema.json',
+  'problem.schema.json',
+  'status-transition-event.schema.json',
+  'gate-decision-event.schema.json',
+  'status-transitions.schema.json',
+  'dependency-dag.schema.json',
+  'extensions.schema.json',
+  'path-rules.schema.json',
+  'risk-classifier-rules.schema.json',
+];
+
+let ajvInstance: Ajv | null = null;
+const compiledCache = new Map<string, ValidateFunction>();
+
+function getAjv(): Ajv {
+  if (ajvInstance) return ajvInstance;
+  const ajv = new Ajv({ strict: false, validateFormats: true, allErrors: true });
+  addFormats(ajv);
+  for (const file of SCHEMA_FILES) {
+    const schema = JSON.parse(readFileSync(`${pkgDir}/schemas/${file}`, 'utf-8'));
+    ajv.addSchema(schema);
+  }
+  ajvInstance = ajv;
+  return ajv;
+}
+
+function getValidator(schemaId: string): ValidateFunction {
+  const cached = compiledCache.get(schemaId);
+  if (cached) return cached;
+  const ajv = getAjv();
+  const validator = ajv.getSchema(schemaId);
+  if (!validator) throw new Error(`Schema not registered: ${schemaId}`);
+  compiledCache.set(schemaId, validator);
+  return validator;
+}
+
+export function validateOrThrow(schemaId: string, doc: unknown): void {
+  const validate = getValidator(schemaId);
+  if (!validate(doc)) {
+    const violations = (validate.errors ?? []).length;
+    const detail = JSON.stringify(validate.errors, null, 2);
+    throw new Error(
+      `Schema validation failed: ${violations} violation(s) against ${schemaId}\n${detail}`
+    );
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@cloverleaf/reference-impl",
+  "version": "0.1.1",
+  "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Renato D'Arrigo <renato.darrigo@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloverleaf-org/cloverleaf.git",
+    "directory": "reference-impl"
+  },
+  "homepage": "https://github.com/cloverleaf-org/cloverleaf#readme",
+  "bugs": {
+    "url": "https://github.com/cloverleaf-org/cloverleaf/issues"
+  },
+  "keywords": [
+    "cloverleaf",
+    "methodology",
+    "ai-first",
+    "claude-code",
+    "agent",
+    "reference-implementation"
+  ],
+  "files": [
+    "skills",
+    "lib",
+    "prompts",
+    "install.sh",
+    "README.md",
+    "VERSION"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "cloverleaf-cli": "./lib/cli.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@cloverleaf/standard": "^0.3.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/prompts/implementer.md

@@ -0,0 +1,47 @@
+# Implementer Subagent
+
+You are the Cloverleaf Implementer agent. Your job: take a Task and produce working code that satisfies its Definition of Done and Acceptance Criteria.
+
+## Inputs
+
+- `task`: a Cloverleaf Task document (JSON).
+- `feedback`: optional — the most recent feedback envelope from a prior Reviewer bounce. If present, address every finding before re-submitting.
+- `repo_root`: absolute path to the consumer repo.
+- `base_branch`: the branch to branch off (default: `main`).
+
+## Your process
+
+1. Read the task's `title`, `acceptance_criteria`, `definition_of_done`, and `context`. Read any referenced files.
+2. If `feedback` is present, re-read each finding; plan how to address them.
+3. Create a new branch named `cloverleaf/<task.id>` from `base_branch` using `git checkout -b cloverleaf/<task.id>`.
+4. Implement the code + tests needed to satisfy every acceptance criterion.
+5. Run the project's test command (typically `npm test` — check package.json `scripts.test`). All tests must pass.
+6. Stage and commit your changes with message `feat: <task.title> [<task.id>]`.
+7. Return a structured JSON result to stdout:
+
+```json
+{
+  "status": "done",
+  "branch": "cloverleaf/<task.id>",
+  "files_changed": ["path/to/file1.ts", "tests/path/to/file1.test.ts"],
+  "summary": "One-sentence summary of the implementation."
+}
+```
+
+If you cannot complete the task:
+
+```json
+{
+  "status": "blocked",
+  "reason": "Concise description of what's blocking you."
+}
+```
+
+## Rules
+
+- Do NOT push the branch to a remote. The human will handle that post-merge.
+- Do NOT open a PR.
+- Do NOT modify `.cloverleaf/` — state transitions are the skill's job.
+- Do NOT skip tests or write placeholder tests. Every acceptance criterion must be covered by a real, meaningful test.
+- Work within the existing project patterns. If the repo has a tsconfig, package.json scripts, or test conventions, follow them.
+- Small, focused commits are preferred but a single well-scoped commit is acceptable for this task.

package/prompts/reviewer.md

@@ -0,0 +1,56 @@
+# Reviewer Subagent
+
+You are the Cloverleaf Reviewer agent. Your job: perform a fresh-eyes review of an Implementer's branch against the task's Acceptance Criteria and emit a structured feedback envelope.
+
+## Inputs
+
+- `task`: the Cloverleaf Task document (JSON).
+- `branch`: the branch name the Implementer produced (e.g., `cloverleaf/DEMO-001`).
+- `base_branch`: the branch to diff against (default: `main`).
+- `repo_root`: absolute path to the consumer repo.
+
+## Your process
+
+1. Read the task's `acceptance_criteria` and `definition_of_done`.
+2. Run `git diff <base_branch>..<branch> --stat` and `git diff <base_branch>..<branch>` to see the change.
+3. For each acceptance criterion, determine whether the diff satisfies it. Note any unsatisfied criteria as findings.
+4. Check for defects: missing tests, obvious logic errors, security issues, hygiene problems.
+5. Decide verdict:
+   - `pass` if every acceptance criterion is satisfied and no blocking defects exist.
+   - `bounce` otherwise.
+6. Return a feedback envelope (per `feedback.schema.json`) to stdout as JSON:
+
+```json
+{
+  "verdict": "pass" | "bounce",
+  "summary": "One or two sentences.",
+  "findings": [
+    {
+      "severity": "blocker" | "error" | "warning" | "info",
+      "message": "Concise description of the issue.",
+      "location": { "file": "path/to/file.ts", "line": 42 }
+    }
+  ]
+}
+```
+
+A `pass` verdict MAY have an empty `findings` array or omit it. A `bounce` verdict MUST have at least one finding AND a `summary`.
+
+## Rules
+
+- You are a fresh pair of eyes. Do not rubber-stamp. If you have substantive doubts, bounce.
+- Check that tests actually cover the AC; a passing test suite with no AC coverage is a bounce.
+- Do NOT modify any files. You are read-only.
+- Do NOT use `git checkout` or `git switch`. Read files via `git show <branch>:<path>`. If you need a live checkout to run tests, use a worktree:
+
+  ```bash
+  git worktree add /tmp/cl-review-<task-id> cloverleaf/<task-id>
+  cd /tmp/cl-review-<task-id>
+  npm install && npm test
+  cd -
+  git worktree remove /tmp/cl-review-<task-id>
+  ```
+
+  This keeps `.cloverleaf/` on main intact.
+- Severities (per the Cloverleaf feedback schema): `blocker` = wrong behavior / missing AC / broken tests; `error` = notable defect that should be fixed but doesn't break AC; `warning` = should fix; `info` = nit / style. Use `blocker` and `error` for bounces.
+- If a criterion is subjective, lean toward pass — the task author chose those words deliberately.

package/skills/cloverleaf-implement.md

@@ -0,0 +1,81 @@
+---
+name: cloverleaf-implement
+description: Run the Implementer agent on a task. Dispatches a subagent to produce code + tests on a new branch, then advances state pending → tactical-plan → implementing → documenting → review. Usage — /cloverleaf-implement <TASK-ID>.
+---
+
+# Cloverleaf — implement
+
+The user has invoked this skill with a TASK-ID (e.g., `DEMO-001`).
+
+## Steps
+
+1. Capture the argument. If no TASK-ID was provided, report usage and stop.
+
+2. Load the task:
+   ```
+   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli load-task <repo_root> <TASK-ID>
+   ```
+   Parse the JSON. Verify `status === "pending"` OR `status === "implementing"` (the second case is a re-run after a Reviewer bounce). If neither, report the current status and ask the user to use the correct command for that state.
+
+3. Load any outstanding feedback:
+   ```
+   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli latest-feedback <repo_root> <TASK-ID>
+   ```
+   Capture the output. If present and the latest verdict is `bounce`, pass it into the subagent.
+
+4. Dispatch the Implementer subagent via the Task tool:
+   - `subagent_type`: `general-purpose`
+   - `model`: `sonnet`
+   - Prompt: the contents of `~/.claude/plugins/cloverleaf/prompts/implementer.md`, with placeholders substituted:
+     - `{{task}}` → the full task JSON (pretty-printed)
+     - `{{feedback}}` → the feedback JSON if present, else the literal string `null`
+     - `{{repo_root}}` → absolute path to the current repo
+     - `{{base_branch}}` → `main` (or the current default branch)
+
+5. Parse the subagent's response. Expect JSON of the form `{"status": "done", "branch": "...", "files_changed": [...], "summary": "..."}` or `{"status": "blocked", "reason": "..."}`.
+
+6. On `blocked`: report the reason and stop. Do NOT advance status.
+
+7. On `done`: walk the state machine. First, switch back to main:
+
+   ```bash
+   cd <repo_root>
+   git checkout main
+   ```
+
+   If this fails (uncommitted changes on main, detached HEAD, etc.), report the error and stop without advancing state.
+
+8. Run each of these CLI calls in sequence:
+
+   If the current task status is `pending`:
+   ```
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> tactical-plan agent
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> documenting agent
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> review agent
+   ```
+
+   If the current task status was `implementing` (loop-back after bounce):
+   ```
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> documenting agent
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> review agent
+   ```
+
+9. Commit the state changes:
+   ```
+   cd <repo_root>
+   git add .cloverleaf/
+   git commit -m "cloverleaf: <TASK-ID> → review"
+   ```
+
+10. Report:
+    - "✓ Implementer done. Branch `<branch>`. State → review."
+    - "Files changed: <comma-separated>."
+    - "Currently on: `main`."
+    - "Next: `/cloverleaf-review <TASK-ID>`."
+
+## Rules
+
+- Never push the branch or modify remote state.
+- If any `advance-status` call fails (illegal transition), stop and report.
+- The skill's working directory is the consumer's repo root.

package/skills/cloverleaf-merge.md

@@ -0,0 +1,42 @@
+---
+name: cloverleaf-merge
+description: Human gate for merging a Cloverleaf task. Advances automated-gates → merged via the human_merge gate, requires explicit user confirmation. Usage — /cloverleaf-merge <TASK-ID>.
+---
+
+# Cloverleaf — merge
+
+## Steps
+
+0. Ensure you are on `main`. State is authoritative on main. Run:
+
+   ```bash
+   cd <repo_root>
+   current=$(git rev-parse --abbrev-ref HEAD)
+   if [ "$current" != "main" ]; then git checkout main; fi
+   ```
+
+   If main has uncommitted changes, stop and report — the user must clean up first.
+
+1. Capture the TASK-ID.
+
+2. Load the task: `cloverleaf-cli load-task <repo_root> <TASK-ID>`. Verify `status === "automated-gates"`. If not, report and stop.
+
+3. Confirm with the user. Print:
+   > "About to merge `<TASK-ID>`. Branch `cloverleaf/<TASK-ID>` has been reviewed and passed. Confirm merge? (y/N)"
+
+   Wait for the user's reply. Only proceed on explicit `y`, `Y`, `yes`, or `YES`. Anything else: abort without state change.
+
+4. On confirmation:
+   - Emit the gate decision: `cloverleaf-cli emit-gate-decision <repo_root> <TASK-ID> human_merge approve human`. Note: decision is `approve` (not `approved` — per the gate-decision schema's enum).
+   - Advance: `cloverleaf-cli advance-status <repo_root> <TASK-ID> merged human human_merge fast_lane`.
+   - Commit state: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> merged"`.
+
+5. Report:
+   - "✓ Merged `<TASK-ID>`. Branch `cloverleaf/<TASK-ID>` is ready for you to push and open a PR."
+   - "Suggested: `git push origin cloverleaf/<TASK-ID>` then open a PR against `main`."
+
+## Rules
+
+- The skill does NOT push the branch or open a PR. That remains explicit to the user.
+- The `merged` status in `.cloverleaf/` is the Cloverleaf-level record; the actual GitHub merge is the user's responsibility.
+- If the user declines, no state change and no commit.

package/skills/cloverleaf-new-task.md

@@ -0,0 +1,56 @@
+---
+name: cloverleaf-new-task
+description: Scaffold a new Cloverleaf Task from a prose brief. Allocates next task ID, writes .cloverleaf/tasks/<PROJECT>-<NNN>.json. Usage — /cloverleaf-new-task "<brief>".
+---
+
+# Cloverleaf — new task
+
+The user has invoked this skill with a brief. Your job: turn the brief into a structured Cloverleaf Task and write it to `.cloverleaf/tasks/`.
+
+## Steps
+
+1. Determine the active project. Run:
+   ```
+   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli infer-project <repo_root>
+   ```
+   where `<repo_root>` is the current working directory. On failure (no projects, or multiple projects), report the error and ask the user to specify `--project=<id>` or to create a project config first.
+
+2. Allocate the next task ID:
+   ```
+   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli next-task-id <repo_root> --project=<project>
+   ```
+   Capture the output (e.g., `DEMO-002`).
+
+3. Read the user's brief (the text passed as the skill argument).
+
+4. Construct a Task JSON document with this shape (matches task.schema.json):
+   ```json
+   {
+     "id": "<allocated-id>",
+     "type": "task",
+     "status": "pending",
+     "owner": { "kind": "agent", "id": "implementer" },
+     "project": "<project>",
+     "title": "<concise title derived from brief>",
+     "context": {},
+     "acceptance_criteria": ["<criterion 1>", "<criterion 2>", "..."],
+     "definition_of_done": ["<terminal statement of completion>"],
+     "risk_class": "low"
+   }
+   ```
+
+   Derive 2-5 acceptance criteria from the brief. Each must be verifiable. Derive one or more Definition of Done strings as an array.
+
+5. Write the file to `<repo_root>/.cloverleaf/tasks/<allocated-id>.json`.
+
+6. Commit: `git add .cloverleaf/tasks/<allocated-id>.json && git commit -m "cloverleaf: task <allocated-id>"`.
+
+7. Report:
+   - "Created `<allocated-id>` at `.cloverleaf/tasks/<allocated-id>.json`."
+   - Show the generated acceptance criteria.
+   - Suggest: "Review and edit the task if needed, then run `/cloverleaf-run <allocated-id>`."
+
+## Rules
+
+- Do not guess at acceptance criteria. If the brief is too vague (e.g., "make it faster" with no target), ask the user a clarifying question before writing the file.
+- If the user's brief hints at complex/risky work (UI changes, breaking API, cross-project), set `risk_class: "high"` and mention it. Default is `"low"` for simple tasks.

package/skills/cloverleaf-review.md

@@ -0,0 +1,63 @@
+---
+name: cloverleaf-review
+description: Run the Reviewer agent on a task in the `review` state. Emits a feedback envelope; advances to `automated-gates` on pass or loops back to `implementing` on bounce. Usage — /cloverleaf-review <TASK-ID>.
+---
+
+# Cloverleaf — review
+
+## Steps
+
+0. Ensure you are on `main`. State is authoritative on main. Run:
+
+   ```bash
+   cd <repo_root>
+   current=$(git rev-parse --abbrev-ref HEAD)
+   if [ "$current" != "main" ]; then git checkout main; fi
+   ```
+
+   If main has uncommitted changes, stop and report — the user must clean up first.
+
+1. Capture the TASK-ID argument.
+
+2. Load the task:
+   ```
+   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli load-task <repo_root> <TASK-ID>
+   ```
+   Verify `status === "review"`. If not, report the current status and stop.
+
+3. The Implementer's branch is `cloverleaf/<TASK-ID>`. Confirm it exists: `git rev-parse --verify cloverleaf/<TASK-ID>`. If missing, report the discrepancy and stop. Do NOT check out this branch; stay on main.
+
+4. Compute the diff without checking out:
+   ```bash
+   git diff main..cloverleaf/<TASK-ID>
+   ```
+   Capture this output for the subagent.
+
+5. Dispatch the Reviewer subagent via the Task tool:
+   - `subagent_type`: `general-purpose`
+   - `model`: `sonnet`
+   - Prompt: contents of `~/.claude/plugins/cloverleaf/prompts/reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`.
+
+6. Parse the subagent's response. Expect a feedback envelope JSON of the form `{"verdict": "pass"|"bounce", "summary": "...", "findings": [...]}`. Validate shape: verdict must be `pass` or `bounce`; if `bounce`, findings must have at least one entry with `severity` (one of `blocker|error|warning|info`) and `message`.
+
+7. Branch on verdict:
+
+   **Pass:**
+   ```
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> automated-gates agent
+   ```
+   Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> review passed → automated-gates"`.
+   Report: "✓ Review passed. State → automated-gates. Next: `/cloverleaf-merge <TASK-ID>`."
+
+   **Bounce:**
+   1. Write the feedback envelope to a temp file: `echo '<envelope-json>' > /tmp/cloverleaf-fb.json`.
+   2. `cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/cloverleaf-fb.json` — captures the path like `.cloverleaf/feedback/<TASK-ID>-r<N>.json`.
+   3. `cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent` — loops back.
+   4. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> review bounced → implementing"`.
+   5. Report: "✗ Review bounced. Findings: <summarize findings by severity>. State → implementing. Next: `/cloverleaf-implement <TASK-ID>`."
+
+## Rules
+
+- Never push.
+- Do not modify source code — the reviewer is read-only.
+- On illegal state transition, report and stop without partial commits.

package/skills/cloverleaf-run.md

@@ -0,0 +1,41 @@
+---
+name: cloverleaf-run
+description: End-to-end orchestrator. Loops implement → review → (bounce ↻ implement) → pause at human merge gate. Max 3 bounces before escalation. Usage — /cloverleaf-run <TASK-ID>.
+---
+
+# Cloverleaf — run (orchestrator)
+
+## Branch discipline
+
+The orchestrator runs each sub-skill with the assumption that the working tree starts on `main`. Between steps, confirm the branch is main before proceeding. The Implementer step leaves the user on main after its internal `git checkout main`; the Reviewer and Merge steps start on main.
+
+## Steps
+
+1. Capture the TASK-ID.
+
+2. Load the task: `cloverleaf-cli load-task <repo_root> <TASK-ID>`. Verify `status === "pending"`. If not, report and stop — suggest the user run individual skills instead.
+
+3. Loop, up to `MAX_BOUNCES = 3`:
+
+   a. Invoke `/cloverleaf-implement <TASK-ID>` (inline the steps from that skill — do not actually call the slash command recursively).
+
+   b. Invoke `/cloverleaf-review <TASK-ID>`.
+
+   c. Re-load the task. If `status === "automated-gates"` — pass! Break out of the loop.
+
+   d. Else if `status === "implementing"` — bounce. Increment bounce counter. If counter == MAX_BOUNCES, escalate (step 5) and stop.
+
+   e. Else — unexpected state. Report and stop.
+
+4. On pass: invoke `/cloverleaf-merge <TASK-ID>`, which prompts the user for confirmation.
+
+5. On max bounces exceeded:
+   - `cloverleaf-cli advance-status <repo_root> <TASK-ID> escalated agent`.
+   - Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> escalated after 3 bounces"`.
+   - Report: "✗ Escalated `<TASK-ID>` after 3 bounces. Review the feedback files under `.cloverleaf/feedback/` and either refine the task or take over manually."
+
+## Rules
+
+- MAX_BOUNCES is hardcoded to 3 for v0.1.0.
+- The orchestrator does not skip the human_merge gate; the user's confirmation is still required at merge time.
+- If ANY individual skill reports an error or stops, the orchestrator also stops with a clear message.