@lifeaitools/rdc-skills 0.8.7

package/scripts/install.ps1

@@ -0,0 +1,165 @@
+# DEPRECATED as of v0.6.0 — use /plugin install rdc-skills.
+# Will be removed in v0.7.0. See README.md "Install" section.
+#
+# Install rdc-skills plugin to Claude Code
+# Windows PowerShell script
+#
+# Usage:
+#   ./install.ps1                  # standard install
+#   ./install.ps1 -SkipHooks       # skip hooks registration (e.g. if you manage hooks manually)
+#   ./install.ps1 -ClaudeHome <path>  # custom CLAUDE_HOME
+
+param(
+    [string]$ClaudeHome = "",
+    [switch]$SkipHooks = $false,
+    [switch]$Force = $false
+)
+
+# Detect CLAUDE_HOME
+if (-not $ClaudeHome) {
+    $ClaudeHome = Join-Path $env:USERPROFILE ".claude"
+}
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$repoRoot  = Split-Path -Parent $scriptDir
+
+Write-Host ""
+Write-Host "  rdc-skills Installer" -ForegroundColor Green
+Write-Host "  ====================" -ForegroundColor Green
+Write-Host ""
+Write-Host "  CLAUDE_HOME : $ClaudeHome" -ForegroundColor Cyan
+Write-Host "  Plugin root : $repoRoot" -ForegroundColor Cyan
+Write-Host ""
+
+if (-not (Test-Path $ClaudeHome)) {
+    Write-Host "  ERROR: CLAUDE_HOME not found: $ClaudeHome" -ForegroundColor Red
+    exit 1
+}
+
+# ── 1. Skills ────────────────────────────────────────────────────────────────
+
+$skillsDir = Join-Path $ClaudeHome "skills" "user"
+if (-not (Test-Path $skillsDir)) {
+    New-Item -ItemType Directory -Path $skillsDir -Force | Out-Null
+}
+
+$srcSkills = Join-Path $repoRoot "skills"
+$skillFiles = Get-ChildItem -Path $srcSkills -Filter "*.md" -ErrorAction SilentlyContinue
+foreach ($f in $skillFiles) {
+    Copy-Item -Path $f.FullName -Destination (Join-Path $skillsDir $f.Name) -Force
+}
+Write-Host "  [1/3] Skills      ✓  $($skillFiles.Count) file(s) → $skillsDir" -ForegroundColor Green
+
+# ── 2. Hooks (files) ─────────────────────────────────────────────────────────
+
+$hooksDir = Join-Path $ClaudeHome "hooks"
+if (-not (Test-Path $hooksDir)) {
+    New-Item -ItemType Directory -Path $hooksDir -Force | Out-Null
+}
+
+$srcHooks  = Join-Path $repoRoot "hooks"
+$hookFiles = Get-ChildItem -Path $srcHooks -Filter "*.js" -ErrorAction SilentlyContinue
+foreach ($f in $hookFiles) {
+    Copy-Item -Path $f.FullName -Destination (Join-Path $hooksDir $f.Name) -Force
+}
+Write-Host "  [2/3] Hook files  ✓  $($hookFiles.Count) file(s) → $hooksDir" -ForegroundColor Green
+
+# ── 3. Register hooks in settings.json ───────────────────────────────────────
+
+if ($SkipHooks) {
+    Write-Host "  [3/3] Hook wiring ⏭  skipped (--SkipHooks)" -ForegroundColor DarkGray
+} else {
+    $settingsPath = Join-Path $ClaudeHome "settings.json"
+
+    # Load existing settings (or start fresh)
+    if (Test-Path $settingsPath) {
+        $settings = Get-Content $settingsPath -Raw | ConvertFrom-Json
+    } else {
+        $settings = [PSCustomObject]@{}
+    }
+
+    # Build hooks block — all paths use forward slashes for cross-platform compat
+    $hooksBase = $hooksDir.Replace("\", "/")
+
+    $hooksConfig = [PSCustomObject]@{
+        SessionStart = @(
+            [PSCustomObject]@{
+                hooks = @(
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/check-cwd.js`"" },
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/check-stale-work-items.js`""; statusMessage = "Checking for stale work items..." }
+                )
+            }
+        )
+        PreToolUse = @(
+            [PSCustomObject]@{
+                matcher = "Bash"
+                hooks   = @(
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/require-work-item-on-commit.js`"" }
+                )
+            }
+        )
+        PostToolUse = @(
+            [PSCustomObject]@{
+                hooks = @(
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/check-services.js`"" }
+                )
+            }
+        )
+        PreCompact = @(
+            [PSCustomObject]@{
+                hooks = @(
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/precompact-log.js`"" }
+                )
+            }
+        )
+        PostCompact = @(
+            [PSCustomObject]@{
+                hooks = @(
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/postcompact-log.js`"" },
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/restart-brief.js`""; statusMessage = "Writing restart brief..." }
+                )
+            }
+        )
+        Stop = @(
+            [PSCustomObject]@{
+                hooks = @(
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/rate-limit-retry.js`""; statusMessage = "Checking for rate limits..." },
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/post-work-check.js`""; statusMessage = "Checking for undocumented work..." },
+                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/no-stop-open-epics.js`""; statusMessage = "Checking for open epics..." }
+                )
+            }
+        )
+    }
+
+    # Add/replace hooks key
+    if ($settings.PSObject.Properties["hooks"]) {
+        $settings.hooks = $hooksConfig
+    } else {
+        $settings | Add-Member -NotePropertyName "hooks" -NotePropertyValue $hooksConfig -Force
+    }
+
+    # Write back with 2-space indent
+    $settings | ConvertTo-Json -Depth 20 | Set-Content $settingsPath -Encoding UTF8
+    Write-Host "  [3/3] Hook wiring ✓  registered in $settingsPath" -ForegroundColor Green
+}
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+
+Write-Host ""
+Write-Host "  Installation complete!" -ForegroundColor Green
+Write-Host ""
+Write-Host "  Next steps:" -ForegroundColor Yellow
+Write-Host "  1. Create project overlay guides (required for project-specific context):"
+Write-Host "     docs/guides/agent-bootstrap.md  ← credentials, git rules, Supabase ref"
+Write-Host "     docs/guides/frontend.md          ← your design system rules"
+Write-Host "     docs/guides/backend.md           ← your API/DB patterns"
+Write-Host "     docs/guides/data.md              ← your migration patterns"
+Write-Host ""
+Write-Host "  2. Use rdc-skills/guides/*.md as starting-point templates"
+Write-Host ""
+Write-Host "  3. Restart Claude Code so hook changes take effect"
+Write-Host ""
+Write-Host "  4. Run /rdc:status in Claude Code to verify"
+Write-Host ""
+Write-Host "  Docs: https://github.com/LIFEAI/rdc-skills#readme" -ForegroundColor Cyan
+Write-Host ""

package/scripts/install.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# DEPRECATED as of v0.6.0 — use /plugin install rdc-skills.
+# Will be removed in v0.7.0. See README.md "Install" section.
+#
+# Install rdc-skills plugin to Claude Code
+# Unix/macOS bash script
+
+set -u
+# NOTE: intentionally NOT using `set -e`
+
+# Guard: warn if rdc-skills plugin is already active in settings.json
+# Running this script alongside the plugin creates duplicate skill entries.
+SETTINGS_FILE="${HOME}/.claude/settings.json"
+if [ -f "$SETTINGS_FILE" ] && python3 -c "
+import json, sys
+s = json.load(open('$SETTINGS_FILE'))
+plugins = s.get('enabledPlugins', {})
+if plugins.get('rdc-skills@rdc-skills'):
+    sys.exit(1)
+" 2>/dev/null; then
+    : # plugin not active — safe to proceed
+else
+    echo "⚠️  WARNING: rdc-skills@rdc-skills plugin is active in ~/.claude/settings.json"
+    echo "   Running this script alongside the plugin creates DUPLICATE skill entries."
+    echo "   Each skill will appear 2-3x in your skill list."
+    echo ""
+    echo "   If you want to use the plugin (recommended), do NOT run this script."
+    echo "   If you want to use this script instead, disable the plugin first:"
+    echo "     Set \"rdc-skills@rdc-skills\": false in ~/.claude/settings.json"
+    echo ""
+    read -p "Continue anyway? (y/N) " confirm
+    if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then
+        echo "Aborted."
+        exit 0
+    fi
+fi — it aborts the whole install on any
+# single file glitch (stale lock, permission hiccup, cp retry). We want the
+# loop to power through and report failures at the end, not die silently
+# after the first file. Past bug: every install "only copied rdc-backend.md".
+
+CLAUDE_HOME="${CLAUDE_HOME:-$HOME/.claude}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+
+echo "rdc-skills Installer"
+echo "==================="
+echo ""
+
+# Check CLAUDE_HOME exists
+if [ ! -d "$CLAUDE_HOME" ]; then
+    echo "ERROR: CLAUDE_HOME does not exist: $CLAUDE_HOME"
+    echo "       Create it first: mkdir -p \"$CLAUDE_HOME\""
+    exit 1
+fi
+
+echo "CLAUDE_HOME: $CLAUDE_HOME"
+echo ""
+
+# Create skills directory
+SKILLS_DIR="$CLAUDE_HOME/skills/user"
+mkdir -p "$SKILLS_DIR"
+echo "✓ Skills directory: $SKILLS_DIR"
+
+# Copy skills — bulk cp is atomic and much harder to kill than a per-file loop.
+# Prior bug: per-file loop under `set -e` aborted after the first file on any
+# cp glitch, leaving the install half-applied. Bulk cp runs once, reports once.
+if [ -d "$REPO_ROOT/skills" ]; then
+    SKILL_COUNT=0
+    # Read version from package.json
+    PKG_VERSION=$(python3 -c "import json; print(json.load(open('$REPO_ROOT/package.json'))['version'])" 2>/dev/null || echo "unknown")
+    VERSION_STAMP="<!-- rdc-skills v${PKG_VERSION} -->"
+
+    # Skills are in subdirectories: skills/<name>/SKILL.md → rdc-<name>.md
+    for skill_dir in "$REPO_ROOT"/skills/*/; do
+        name=$(basename "$skill_dir")
+        src="$skill_dir/SKILL.md"
+        dst="$SKILLS_DIR/rdc-${name}.md"
+        if [ -f "$src" ]; then
+            # Prepend version stamp then file content
+            { echo "$VERSION_STAMP"; cat "$src"; } > "$dst" 2>&1 || echo "  (cp warning — failed to copy $name)"
+            SKILL_COUNT=$((SKILL_COUNT + 1))
+            echo "  → rdc-${name}.md  [v${PKG_VERSION}]"
+        fi
+    done
+    if [ "$SKILL_COUNT" -gt 0 ]; then
+        echo "  ✓ Copied $SKILL_COUNT skill(s)"
+        INSTALLED=$(ls -1 "$SKILLS_DIR"/rdc-*.md 2>/dev/null | wc -l)
+        echo "  ✓ Verified: $INSTALLED rdc-*.md file(s) present in $SKILLS_DIR"
+        if [ "$INSTALLED" -lt "$SKILL_COUNT" ]; then
+            echo "  ⚠ WARNING: only $INSTALLED of $SKILL_COUNT installed — run install again or check permissions"
+        fi
+    else
+        echo "  (no SKILL.md files found in skills/ subdirectories)"
+    fi
+fi
+echo ""
+
+# Create hooks directory
+HOOKS_DIR="$CLAUDE_HOME/hooks"
+mkdir -p "$HOOKS_DIR"
+echo "✓ Hooks directory: $HOOKS_DIR"
+
+# Copy hooks
+HOOK_COUNT=0
+if ls "$REPO_ROOT"/hooks/*.js >/dev/null 2>&1; then
+    cp "$REPO_ROOT"/hooks/*.js "$HOOKS_DIR/" 2>&1 || echo "  (cp warning — some hooks may not have copied)"
+    chmod +x "$HOOKS_DIR"/*.js 2>/dev/null || true
+    HOOK_COUNT=$(ls -1 "$REPO_ROOT"/hooks/*.js 2>/dev/null | wc -l)
+    for hook in "$REPO_ROOT"/hooks/*.js; do
+        [ -f "$hook" ] && echo "  → $(basename "$hook")"
+    done
+fi
+if [ "$HOOK_COUNT" -gt 0 ]; then
+    echo "  ✓ Copied $HOOK_COUNT hook(s)"
+fi
+echo ""
+
+echo "Installation Complete"
+echo "====================="
+echo ""
+echo "Next steps:"
+echo "1. Create project-specific guides in your codebase:"
+echo "   - docs/guides/agent-bootstrap.md (required — credentials, git rules)"
+echo "   - docs/guides/frontend.md (if building UI)"
+echo "   - docs/guides/backend.md (if building APIs)"
+echo "   - docs/guides/data.md (if doing DB work)"
+echo ""
+echo "2. Use rdc-skills/guides/*.md as starting point templates for your project overlays"
+echo ""
+echo "3. Run /rdc:status in Claude Code to verify setup"
+echo ""
+echo "For help: https://github.com/LIFEAI/rdc-skills#readme"

package/scripts/lib/assertions.mjs

@@ -0,0 +1,264 @@
+// assertions.mjs — Tier 2 declarative assertion evaluator.
+//
+// Consumed by scripts/lib/runner.mjs. Each predicate is a pure function
+// (assertion, observed) => { pass, message } where observed is:
+//   {
+//     exit_code:         number,
+//     stdout:            string,
+//     stderr:            string,
+//     files_modified:    string[],   // forward-slash relative paths
+//     commits:           [{ sha, subject, body }],
+//     work_items_delta:  [{ id, status, labels }],
+//   }
+//
+// evaluateAssertions(manifest.assertions, observed) → { pass, failures[] }
+// where failures is an array of { predicate, message } — empty iff pass.
+//
+// Self-test at the bottom; run `node scripts/lib/assertions.mjs`.
+
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+
+// ─── predicates ─────────────────────────────────────────────────────────────
+
+export function checkExitCode(expected, observed) {
+  if (expected === undefined) return { pass: true };
+  if (observed.exit_code === expected) return { pass: true };
+  return {
+    pass: false,
+    message: `exit_code expected ${expected}, got ${observed.exit_code}`,
+  };
+}
+
+export function checkWorkItemsCreated(spec, observed) {
+  if (spec === undefined) return { pass: true };
+  const items = Array.isArray(observed.work_items_delta) ? observed.work_items_delta : [];
+  let filtered = items;
+  if (spec.status !== undefined) {
+    filtered = filtered.filter((wi) => wi && wi.status === spec.status);
+  }
+  if (Array.isArray(spec.labels_include) && spec.labels_include.length > 0) {
+    filtered = filtered.filter((wi) => {
+      const labels = Array.isArray(wi?.labels) ? wi.labels : [];
+      return spec.labels_include.every((lbl) => labels.includes(lbl));
+    });
+  }
+  const count = filtered.length;
+  if (spec.min !== undefined && count < spec.min) {
+    return {
+      pass: false,
+      message: `work_items_created: expected >= ${spec.min} matching, got ${count}`,
+    };
+  }
+  if (spec.max !== undefined && count > spec.max) {
+    return {
+      pass: false,
+      message: `work_items_created: expected <= ${spec.max} matching, got ${count}`,
+    };
+  }
+  return { pass: true };
+}
+
+export function checkFilesModified(expected, observed) {
+  if (expected === undefined) return { pass: true };
+  if (!Array.isArray(expected)) {
+    return { pass: false, message: "files_modified assertion is not an array" };
+  }
+  const seen = new Set(
+    (observed.files_modified || []).map((p) => String(p).replace(/\\/g, "/")),
+  );
+  const missing = expected.filter((p) => !seen.has(String(p).replace(/\\/g, "/")));
+  if (missing.length === 0) return { pass: true };
+  return {
+    pass: false,
+    message: `files_modified: missing from git diff: ${missing.join(", ")}`,
+  };
+}
+
+export function checkCommitsMade(spec, observed) {
+  if (spec === undefined) return { pass: true };
+  const commits = Array.isArray(observed.commits) ? observed.commits : [];
+  if (spec.min !== undefined && commits.length < spec.min) {
+    return {
+      pass: false,
+      message: `commits_made: expected >= ${spec.min}, got ${commits.length}`,
+    };
+  }
+  if (spec.message_matches !== undefined) {
+    let re;
+    try {
+      re = new RegExp(spec.message_matches);
+    } catch (e) {
+      return { pass: false, message: `commits_made.message_matches invalid regex: ${e.message}` };
+    }
+    const hit = commits.some((c) => {
+      const msg = `${c?.subject || ""}\n${c?.body || ""}`;
+      return re.test(msg);
+    });
+    if (!hit) {
+      return {
+        pass: false,
+        message: `commits_made.message_matches /${spec.message_matches}/ did not match any commit`,
+      };
+    }
+  }
+  return { pass: true };
+}
+
+export function checkStderrEmpty(expected, observed) {
+  if (expected === undefined) return { pass: true };
+  if (expected !== true) return { pass: true };
+  const s = (observed.stderr || "").trim();
+  if (s.length === 0) return { pass: true };
+  const preview = s.length > 200 ? s.slice(0, 200) + "..." : s;
+  return { pass: false, message: `stderr_empty: expected empty, got ${s.length} chars: ${preview}` };
+}
+
+export function checkStdoutContains(expected, observed) {
+  if (expected === undefined) return { pass: true };
+  if (!Array.isArray(expected)) {
+    return { pass: false, message: "stdout_contains assertion is not an array" };
+  }
+  const stdout = observed.stdout || "";
+  const missing = expected.filter((s) => !stdout.includes(s));
+  if (missing.length === 0) return { pass: true };
+  return {
+    pass: false,
+    message: `stdout_contains: missing substrings: ${missing.map((s) => JSON.stringify(s)).join(", ")}`,
+  };
+}
+
+// ─── evaluator ──────────────────────────────────────────────────────────────
+
+const PREDICATES = [
+  ["exit_code", checkExitCode],
+  ["work_items_created", checkWorkItemsCreated],
+  ["files_modified", checkFilesModified],
+  ["commits_made", checkCommitsMade],
+  ["stderr_empty", checkStderrEmpty],
+  ["stdout_contains", checkStdoutContains],
+];
+
+export function evaluateAssertions(assertions, observed) {
+  const failures = [];
+  if (assertions == null || typeof assertions !== "object") {
+    return { pass: false, failures: [{ predicate: "", message: "assertions missing or not an object" }] };
+  }
+  for (const [key, fn] of PREDICATES) {
+    const res = fn(assertions[key], observed || {});
+    if (!res.pass) failures.push({ predicate: key, message: res.message });
+  }
+  return { pass: failures.length === 0, failures };
+}
+
+// ─── self-test ──────────────────────────────────────────────────────────────
+
+const __isMain = (() => {
+  try {
+    return fileURLToPath(import.meta.url) === resolve(process.argv[1] || "");
+  } catch {
+    return false;
+  }
+})();
+
+if (__isMain) {
+  const baseObserved = {
+    exit_code: 0,
+    stdout: "✓ done\nVerdict: PASS\n",
+    stderr: "",
+    files_modified: ["README.md", "src/foo.ts"],
+    commits: [{ sha: "abc123", subject: "fix: typo in README", body: "" }],
+    work_items_delta: [
+      { id: "w1", status: "done", labels: ["fixit", "cs2"] },
+      { id: "w2", status: "todo", labels: ["other"] },
+    ],
+  };
+
+  const cases = [
+    {
+      n: 1,
+      desc: "all predicates pass",
+      assertions: {
+        exit_code: 0,
+        work_items_created: { min: 1, max: 1, status: "done", labels_include: ["fixit"] },
+        files_modified: ["README.md"],
+        commits_made: { min: 1, message_matches: "fix.*README" },
+        stderr_empty: true,
+        stdout_contains: ["✓", "Verdict:"],
+      },
+      observed: baseObserved,
+      expect: (r) => r.pass && r.failures.length === 0,
+    },
+    {
+      n: 2,
+      desc: "exit_code mismatch",
+      assertions: { exit_code: 1 },
+      observed: baseObserved,
+      expect: (r) => !r.pass && r.failures.some((f) => f.predicate === "exit_code"),
+    },
+    {
+      n: 3,
+      desc: "files_modified missing",
+      assertions: { files_modified: ["CHANGELOG.md"] },
+      observed: baseObserved,
+      expect: (r) => !r.pass && r.failures.some((f) => f.predicate === "files_modified"),
+    },
+    {
+      n: 4,
+      desc: "commits_made regex no match",
+      assertions: { commits_made: { message_matches: "^feat" } },
+      observed: baseObserved,
+      expect: (r) => !r.pass && r.failures.some((f) => f.predicate === "commits_made"),
+    },
+    {
+      n: 5,
+      desc: "stderr not empty",
+      assertions: { stderr_empty: true },
+      observed: { ...baseObserved, stderr: "warning: something" },
+      expect: (r) => !r.pass && r.failures.some((f) => f.predicate === "stderr_empty"),
+    },
+    {
+      n: 6,
+      desc: "stdout_contains missing substring",
+      assertions: { stdout_contains: ["NOTPRESENT"] },
+      observed: baseObserved,
+      expect: (r) => !r.pass && r.failures.some((f) => f.predicate === "stdout_contains"),
+    },
+    {
+      n: 7,
+      desc: "work_items_created label filter rejects",
+      assertions: { work_items_created: { min: 1, labels_include: ["nonexistent"] } },
+      observed: baseObserved,
+      expect: (r) => !r.pass && r.failures.some((f) => f.predicate === "work_items_created"),
+    },
+    {
+      n: 8,
+      desc: "work_items_created max exceeded",
+      assertions: { work_items_created: { max: 0 } },
+      observed: baseObserved,
+      expect: (r) => !r.pass && r.failures.some((f) => f.predicate === "work_items_created"),
+    },
+    {
+      n: 9,
+      desc: "empty assertions → pass",
+      assertions: {},
+      observed: baseObserved,
+      expect: (r) => r.pass,
+    },
+  ];
+
+  let passed = 0;
+  console.log("\nassertions self-test\n");
+  for (const c of cases) {
+    const r = evaluateAssertions(c.assertions, c.observed);
+    const ok = c.expect(r);
+    console.log(
+      `${String(c.n).padEnd(3)} ${c.desc.padEnd(44)} ${ok ? "PASS" : "FAIL"}${
+        ok ? "" : "  → " + JSON.stringify(r.failures)
+      }`,
+    );
+    if (ok) passed++;
+  }
+  console.log(`\n${passed}/${cases.length} passed\n`);
+  process.exit(passed === cases.length ? 0 : 1);
+}