@cloverleaf/reference-impl 0.3.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "cloverleaf",
+  "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge).",
+  "version": "0.4.0",
+  "author": {
+    "name": "Renato D'Arrigo",
+    "email": "renato.darrigo@gmail.com"
+  },
+  "homepage": "https://github.com/cloverleaf-org/cloverleaf",
+  "repository": "https://github.com/cloverleaf-org/cloverleaf",
+  "license": "MIT",
+  "keywords": [
+    "cloverleaf",
+    "methodology",
+    "ai-first",
+    "reference-implementation"
+  ]
+}

package/README.md

@@ -52,12 +52,43 @@ Two JSON config files in `config/` (overridable per consumer project):
 - `config/ui-paths.json` — glob patterns that trigger UI Reviewer (default: `site/**`)
 - `config/qa-rules.json` — per-package test commands
 
+### Customizing for your repo
+
+The package ships with cloverleaf-flavored defaults in `config/`. Your repo overrides any of them by placing a file of the same name at `<repoRoot>/.cloverleaf/config/<name>.json`. Consumer override is a **full replacement** — your file becomes the complete source of truth for that config.
+
+Available overrides:
+
+| Override file | Purpose |
+|---|---|
+| `.cloverleaf/config/ui-paths.json` | Controls `detect-ui-paths` — which diffs trigger the `ui-review` state |
+| `.cloverleaf/config/qa-rules.json` | Per-package test commands for the QA agent |
+| `.cloverleaf/config/affected-routes.json` | Rules for mapping diffs to site routes (UI Reviewer scope); includes `contentRoutes` for content-collection mapping |
+| `.cloverleaf/config/astro-base.json` | Explicit Astro `base` path — avoids best-effort parsing of `astro.config.*` |
+
+Example `affected-routes.json` override for a Next.js project:
+
+```json
+{
+  "pageRoots": ["apps/web/app/"],
+  "globalPatterns": ["apps/web/components/**", "apps/web/styles/**"],
+  "routeScope": ["apps/web/**"],
+  "contentRoutes": {}
+}
+```
+
+Example `astro-base.json`:
+
+```json
+{ "base": "/my-docs" }
+```
+
+All overrides are read fresh on every skill invocation; no caching. Edit and the next `/cloverleaf-run` picks it up.
+
 ### Known limitations
 
 - Concurrent `/cloverleaf-run` on the same repo may race on preview ports.
 - UI Reviewer visual diff + multi-viewport deferred to v0.4.
 - QA does not produce HTML reports (no `report_uri`).
-- Astro `base` path is parsed best-effort; if misdetected, UI Reviewer may return escalate.
 
 ### Prerequisites for UI Reviewer
 

package/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

package/config/affected-routes.json

@@ -1,12 +1,11 @@
 {
-  "pageRoots": ["site/src/pages/"],
+  "pageRoots": ["src/pages/"],
   "globalPatterns": [
-    "site/src/layouts/**",
-    "site/src/components/**",
-    "site/src/styles/**",
-    "site/public/**",
-    "site/astro.config.*",
-    "site/src/content/**"
+    "src/layouts/**",
+    "src/components/**",
+    "src/styles/**",
+    "public/**"
   ],
-  "routeScope": ["site/src/**", "site/public/**"]
+  "routeScope": ["src/**", "public/**"],
+  "contentRoutes": {}
 }

package/config/qa-rules.json

@@ -1,19 +1,9 @@
 {
   "rules": [
     {
-      "cwd": "standard",
-      "match": ["standard/**"],
-      "command": "npm ci && npm test"
-    },
-    {
-      "cwd": "reference-impl",
-      "match": ["reference-impl/**"],
-      "command": "npm ci && npm test"
-    },
-    {
-      "cwd": "site",
-      "match": ["site/**"],
-      "command": "npm ci && npm run build"
+      "cwd": ".",
+      "match": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.json"],
+      "command": "npm test"
     }
   ]
 }

package/config/ui-paths.json

@@ -1,3 +1,8 @@
 {
-  "patterns": ["site/**"]
+  "patterns": [
+    "src/pages/**",
+    "src/components/**",
+    "src/layouts/**",
+    "src/styles/**"
+  ]
 }

package/config/ui-review.json

@@ -0,0 +1,17 @@
+{
+  "viewports": {
+    "mobile":  { "width": 375,  "height": 667 },
+    "tablet":  { "width": 768,  "height": 1024 },
+    "desktop": { "width": 1280, "height": 800 }
+  },
+  "visualDiff": {
+    "enabled": true,
+    "threshold": 0.1,
+    "maxDiffRatio": 0.01,
+    "mask": []
+  },
+  "axe": {
+    "viewports": ["desktop"],
+    "dedupeBy": ["ruleId", "target"]
+  }
+}

package/dist/affected-routes.mjs

@@ -25,7 +25,7 @@ function routeForPage(file, pageRoot) {
         return '/';
     return `/${withoutExt}/`;
 }
-export function loadDefaultConfig() {
+function loadDefaultConfig() {
     if (!existsSync(DEFAULT_CONFIG)) {
         throw new Error(`affected-routes config not found at ${DEFAULT_CONFIG}`);
     }
@@ -34,8 +34,31 @@ export function loadDefaultConfig() {
         pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
         globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
         routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+        contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+            ? doc.contentRoutes
+            : {},
     };
 }
+export function loadAffectedRoutesConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'affected-routes.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const doc = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            return {
+                pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
+                globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
+                routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+                contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+                    ? doc.contentRoutes
+                    : {},
+            };
+        }
+        catch {
+            // fall through
+        }
+    }
+    return loadDefaultConfig();
+}
 export function computeAffectedRoutes(changedFiles, config) {
     const routes = new Set();
     let inScopeButUnmatched = false;
@@ -55,6 +78,16 @@ export function computeAffectedRoutes(changedFiles, config) {
             routes.add(mapped);
             continue;
         }
+        // contentRoutes: map content-collection files to specific routes
+        for (const [pattern, route] of Object.entries(config.contentRoutes)) {
+            if (globToRegex(pattern).test(file)) {
+                routes.add(route);
+                mapped = route;
+                break;
+            }
+        }
+        if (mapped)
+            continue;
         if (matchesAny(file, config.routeScope)) {
             inScopeButUnmatched = true;
         }

package/dist/axe-dedupe.mjs

@@ -0,0 +1,38 @@
+const SEVERITY_MAP = {
+    critical: 'blocker',
+    serious: 'error',
+    moderate: 'warning',
+    minor: 'info',
+};
+function dedupeKeyOf(raw, keys) {
+    return keys.map((k) => raw[k]).join('||');
+}
+export function dedupeAxeFindings(raws, keys) {
+    const groups = new Map();
+    for (const raw of raws) {
+        const key = dedupeKeyOf(raw, keys);
+        const existing = groups.get(key);
+        if (existing) {
+            if (!existing.viewports.includes(raw.viewport))
+                existing.viewports.push(raw.viewport);
+        }
+        else {
+            groups.set(key, { first: raw, viewports: [raw.viewport] });
+        }
+    }
+    const out = [];
+    for (const { first, viewports } of groups.values()) {
+        out.push({
+            severity: SEVERITY_MAP[first.impact],
+            message: first.message,
+            rule: first.ruleId,
+            metadata: {
+                target: first.target,
+                impact: first.impact,
+                viewports,
+                ...(first.helpUrl ? { helpUrl: first.helpUrl } : {}),
+            },
+        });
+    }
+    return out;
+}

package/dist/cli.mjs

@@ -12,6 +12,7 @@
  *   write-feedback <repoRoot> <taskId> <envelopeJsonPath>
  *   latest-feedback <repoRoot> <taskId>
  *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
+ *   ui-review-config --repo-root <repoRoot>
  */
 import { readFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
@@ -20,8 +21,11 @@ import { advanceStatus } from './state.mjs';
 import { emitGateDecision } from './events.mjs';
 import { writeFeedback, latestFeedback } from './feedback.mjs';
 import { nextTaskId, inferProject } from './ids.mjs';
-import { matchesUiPaths, loadDefaultPatterns } from './ui-paths.mjs';
-import { computeAffectedRoutes, loadDefaultConfig } from './affected-routes.mjs';
+import { matchesUiPaths } from './ui-paths.mjs';
+import { loadUiPathsConfig } from './ui-paths.mjs';
+import { computeAffectedRoutes } from './affected-routes.mjs';
+import { loadAffectedRoutesConfig } from './affected-routes.mjs';
+import { loadUiReviewConfig } from './ui-review-config.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -37,7 +41,8 @@ function usage(msg) {
         '  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');
+        '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
+        '  ui-review-config --repo-root <repoRoot>\n');
     process.exit(2);
 }
 const [, , command, ...rest] = process.argv;
@@ -177,7 +182,7 @@ try {
                 console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
                 process.exit(2);
             }
-            const patterns = loadDefaultPatterns();
+            const { patterns } = loadUiPathsConfig(repoRoot);
             const result = matchesUiPaths(changed, patterns);
             process.stdout.write(`${result}\n`);
             process.exit(0);
@@ -204,11 +209,32 @@ try {
                 console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
                 process.exit(2);
             }
-            const config = loadDefaultConfig();
+            const config = loadAffectedRoutesConfig(repoRoot);
             const result = computeAffectedRoutes(changed, config);
             process.stdout.write(`${JSON.stringify(result)}\n`);
             process.exit(0);
         }
+        case 'ui-review-config': {
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const repoRootFlag = flags.find((f) => f.startsWith('--repo-root=') || f === '--repo-root');
+            let repoRoot;
+            if (repoRootFlag === '--repo-root') {
+                repoRoot = rest[rest.indexOf('--repo-root') + 1];
+            }
+            else if (repoRootFlag) {
+                repoRoot = repoRootFlag.replace('--repo-root=', '');
+            }
+            else {
+                repoRoot = rest.filter((a) => !a.startsWith('--'))[0];
+            }
+            if (!repoRoot) {
+                console.error('usage: ui-review-config --repo-root <repoRoot>');
+                process.exit(1);
+            }
+            const config = loadUiReviewConfig(repoRoot);
+            process.stdout.write(JSON.stringify(config, null, 2));
+            process.exit(0);
+        }
         default:
             usage(`Unknown command: ${command}`);
     }

package/dist/qa-report.mjs

@@ -0,0 +1,65 @@
+function escape(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function renderRow(r) {
+    const status = r.passed ? 'PASS' : 'FAIL';
+    const statusClass = r.passed ? 'pass' : 'fail';
+    return `
+    <tr class="${statusClass}">
+      <td>${escape(r.ruleId)}</td>
+      <td><code>${escape(r.command)}</code></td>
+      <td>${escape(r.cwd)}</td>
+      <td>${r.durationMs}ms</td>
+      <td class="status">${status}</td>
+    </tr>
+    <tr class="detail ${statusClass}">
+      <td colspan="5">
+        ${r.stdoutTail ? `<details><summary>stdout (tail)</summary><pre>${escape(r.stdoutTail)}</pre></details>` : ''}
+        ${r.stderrTail ? `<details open><summary>stderr (tail)</summary><pre>${escape(r.stderrTail)}</pre></details>` : ''}
+      </td>
+    </tr>
+  `;
+}
+export function renderQaReport(runs) {
+    const empty = runs.length === 0
+        ? `<p class="empty">No runs / results.</p>`
+        : '';
+    const rows = runs.map(renderRow).join('');
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Cloverleaf QA Report</title>
+  <style>
+    body { font: 14px/1.4 system-ui, sans-serif; margin: 2rem; color: #111; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { padding: 0.5rem; border-bottom: 1px solid #ddd; text-align: left; vertical-align: top; }
+    .status { font-weight: 600; }
+    .pass .status { color: #0a7; }
+    .fail .status { color: #c33; }
+    tr.detail td { background: #fafafa; padding-top: 0; }
+    pre { overflow: auto; background: #f4f4f4; padding: 0.5rem; }
+    .empty { color: #888; }
+  </style>
+</head>
+<body>
+  <h1>Cloverleaf QA Report</h1>
+  ${empty}
+  ${runs.length > 0 ? `
+  <table>
+    <thead>
+      <tr><th>Rule</th><th>Command</th><th>CWD</th><th>Duration</th><th>Status</th></tr>
+    </thead>
+    <tbody>
+      ${rows}
+    </tbody>
+  </table>
+  ` : ''}
+</body>
+</html>`;
+}

package/dist/qa-rules.mjs

@@ -4,12 +4,27 @@ import { dirname, join } from 'node:path';
 import { matchesUiPaths } from './ui-paths.mjs';
 const here = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_CONFIG = join(here, '..', 'config', 'qa-rules.json');
-export function loadDefaultRules() {
+function loadDefaultRules() {
     if (!existsSync(DEFAULT_CONFIG))
         return [];
     const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));
     return Array.isArray(doc.rules) ? doc.rules : [];
 }
+export function loadQaRulesConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'qa-rules.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const doc = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            if (Array.isArray(doc.rules)) {
+                return doc.rules;
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return loadDefaultRules();
+}
 export function selectTestCommands(changedFiles, rules) {
     return rules.filter((rule) => matchesUiPaths(changedFiles, rule.match));
 }

package/dist/route-slug.mjs

@@ -0,0 +1,23 @@
+/**
+ * Turn a URL path into a filesystem-safe slug used in baseline/diff filenames.
+ * - "/" → "index"
+ * - "/faq/" → "faq"
+ * - "/guide/chapter-3/" → "guide-chapter-3"
+ * - "/docs/v1.2/getting started/" → "docs-v1-2-getting-started"
+ * Query/hash are stripped.
+ */
+export function slugifyRoute(route) {
+    const pathOnly = route.split(/[?#]/)[0];
+    if (pathOnly === '/' || pathOnly === '')
+        return 'index';
+    const trimmed = pathOnly.replace(/^\/+|\/+$/g, '');
+    if (trimmed === '')
+        return 'index';
+    const slugged = trimmed
+        .toLowerCase()
+        .replace(/[^a-z0-9/-]+/g, '-')
+        .replace(/\/+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return slugged || 'index';
+}

package/dist/ui-paths.mjs

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 const here = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_CONFIG = join(here, '..', 'config', 'ui-paths.json');
-export function loadDefaultPatterns() {
+function loadDefaultPatterns() {
     if (!existsSync(DEFAULT_CONFIG))
         return ['site/**'];
     const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));
@@ -17,6 +17,21 @@ function globToRegex(pattern) {
         .replace(/\u0000/g, '.*');
     return new RegExp(`^${regex}$`);
 }
+export function loadUiPathsConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'ui-paths.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const doc = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            if (Array.isArray(doc.patterns)) {
+                return { patterns: doc.patterns };
+            }
+        }
+        catch {
+            // fall through to package default
+        }
+    }
+    return { patterns: loadDefaultPatterns() };
+}
 export function matchesUiPaths(changedFiles, patterns) {
     if (changedFiles.length === 0)
         return false;

package/dist/ui-review-config.mjs

@@ -0,0 +1,37 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const here = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DEFAULT = join(here, '..', 'config', 'ui-review.json');
+const HARDCODED_FALLBACK = {
+    viewports: {
+        mobile: { width: 375, height: 667 },
+        tablet: { width: 768, height: 1024 },
+        desktop: { width: 1280, height: 800 },
+    },
+    visualDiff: { enabled: true, threshold: 0.1, maxDiffRatio: 0.01, mask: [] },
+    axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'] },
+};
+function readAsConfig(path) {
+    try {
+        const doc = JSON.parse(readFileSync(path, 'utf-8'));
+        return doc;
+    }
+    catch {
+        return null;
+    }
+}
+export function loadUiReviewConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'ui-review.json');
+    if (existsSync(consumerPath)) {
+        const parsed = readAsConfig(consumerPath);
+        if (parsed)
+            return parsed;
+    }
+    if (existsSync(PACKAGE_DEFAULT)) {
+        const parsed = readAsConfig(PACKAGE_DEFAULT);
+        if (parsed)
+            return parsed;
+    }
+    return HARDCODED_FALLBACK;
+}

package/dist/visual-diff.mjs

@@ -0,0 +1,62 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+function ensureDir(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+function writeBaseline(baselinePath, buf) {
+    ensureDir(baselinePath);
+    writeFileSync(baselinePath, buf);
+}
+export function compareVisual(args) {
+    const candidatePng = PNG.sync.read(args.candidateBuf);
+    if (!existsSync(args.baselinePath)) {
+        writeBaseline(args.baselinePath, args.candidateBuf);
+        return {
+            status: 'new-baseline',
+            diffPixels: 0,
+            diffRatio: 0,
+            width: candidatePng.width,
+            height: candidatePng.height,
+        };
+    }
+    const baselineBuf = readFileSync(args.baselinePath);
+    const baselinePng = PNG.sync.read(baselineBuf);
+    if (baselinePng.width !== candidatePng.width || baselinePng.height !== candidatePng.height) {
+        writeBaseline(args.baselinePath, args.candidateBuf);
+        return {
+            status: 'dimension-mismatch',
+            diffPixels: 0,
+            diffRatio: 0,
+            width: candidatePng.width,
+            height: candidatePng.height,
+        };
+    }
+    const diffPng = new PNG({ width: candidatePng.width, height: candidatePng.height });
+    const diffPixels = pixelmatch(baselinePng.data, candidatePng.data, diffPng.data, candidatePng.width, candidatePng.height, { threshold: args.threshold });
+    const totalPixels = candidatePng.width * candidatePng.height;
+    const diffRatio = diffPixels / totalPixels;
+    if (diffRatio > args.maxDiffRatio) {
+        ensureDir(args.diffPath);
+        writeFileSync(args.diffPath, PNG.sync.write(diffPng));
+        ensureDir(args.candidateOutPath);
+        writeFileSync(args.candidateOutPath, args.candidateBuf);
+        writeBaseline(args.baselinePath, args.candidateBuf);
+        return {
+            status: 'diff',
+            diffPixels,
+            diffRatio,
+            width: candidatePng.width,
+            height: candidatePng.height,
+        };
+    }
+    writeBaseline(args.baselinePath, args.candidateBuf);
+    return {
+        status: 'match',
+        diffPixels,
+        diffRatio,
+        width: candidatePng.width,
+        height: candidatePng.height,
+    };
+}

package/install.sh

@@ -2,59 +2,45 @@
 set -euo pipefail
 
 # Cloverleaf Reference Impl installer.
-# Default: installs skills + CLI shim into ~/.claude/plugins/cloverleaf/.
-# --project: installs locally into ./.claude/plugins/cloverleaf/.
+#
+# As of v0.4.0, cloverleaf installs as a proper Claude Code plugin via the
+# `claude plugin` CLI. Point Claude Code at the cloverleaf repo root (where
+# .claude-plugin/marketplace.json lives), then install the plugin from the
+# resulting marketplace.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-MODE="user"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 
-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"
+if ! command -v claude >/dev/null 2>&1; then
+  echo "error: 'claude' CLI not found on PATH."
+  echo "Install Claude Code first: https://docs.claude.com/claude-code"
+  exit 1
 fi
 
-mkdir -p "${INSTALL_ROOT}/skills" "${INSTALL_ROOT}/prompts" "${INSTALL_ROOT}/bin"
-
-# Symlink config directory
-ln -sf "${SCRIPT_DIR}/config" "${INSTALL_ROOT}/config"
-
-# Symlink skills
-for f in "${SCRIPT_DIR}/skills/"*.md; do
-  name="$(basename "$f")"
-  ln -sf "$f" "${INSTALL_ROOT}/skills/${name}"
-done
+if [ ! -f "${REPO_ROOT}/.claude-plugin/marketplace.json" ]; then
+  echo "error: ${REPO_ROOT}/.claude-plugin/marketplace.json not found."
+  echo "This script expects to be run from inside a cloverleaf checkout."
+  exit 1
+fi
 
-# Symlink prompts
-for f in "${SCRIPT_DIR}/prompts/"*.md; do
-  name="$(basename "$f")"
-  ln -sf "$f" "${INSTALL_ROOT}/prompts/${name}"
-done
+echo "Registering cloverleaf marketplace from ${REPO_ROOT}..."
+claude plugin marketplace add "${REPO_ROOT}"
 
-# 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 "Installing cloverleaf plugin..."
+claude plugin install cloverleaf@cloverleaf-local
 
-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."
+echo "Cloverleaf installed. Slash commands:"
+echo "  /cloverleaf-new-task   — scaffold a Task from a brief"
+echo "  /cloverleaf-run        — full pipeline orchestrator"
+echo "  /cloverleaf-implement  — run Implementer"
+echo "  /cloverleaf-document   — run Documenter"
+echo "  /cloverleaf-review     — run Reviewer"
+echo "  /cloverleaf-ui-review  — run UI Reviewer (visual diff + multi-viewport + axe)"
+echo "  /cloverleaf-qa         — run QA"
+echo "  /cloverleaf-merge      — merge gate"
+echo ""
+echo "Restart any open Claude Code sessions to pick up the new skills."
 
 # Post-install: warn about Playwright chromium if not cached
 if [ ! -d "${HOME}/.cache/ms-playwright" ] || [ -z "$(ls -A "${HOME}/.cache/ms-playwright" 2>/dev/null)" ]; then