@skilly-hand/skilly-hand 0.23.3 → 0.24.0

package/CHANGELOG.md

@@ -16,6 +16,23 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.24.0] - 2026-04-26
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.24.0)
+
+### Added
+- Added install-time creation of the user-owned `.ai/DECISIONS.md` decisions registry, including entry criteria, an entry template, and a required registry changelog section.
+- Added CLI install output that reports the `.ai/DECISIONS.md` decisions registry status during dry runs and applied installs.
+- Added regression coverage for decisions registry planning, creation, existing-registry preservation, uninstall preservation, and invalid `.ai` parent handling.
+
+### Changed
+- Updated `review-rangers` to own decisions registry read/write guidance and bumped the skill metadata version to `1.1.0`.
+
+### Fixed
+- Preserved existing user-owned decisions registry content across reinstalls and uninstalls.
+
+### Removed
+- _None._
+
 ## [0.23.3] - 2026-04-20
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.23.3)
 

package/catalog/skills/review-rangers/SKILL.md

@@ -3,13 +3,15 @@ name: "review-rangers"
 description: "Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-04"
+  last-edit: "2026-04-26"
   license: "Apache-2.0"
-  version: "1.0.0"
-  changelog: "Added multi-perspective review skill with committee + safety guard synthesis; enables adversarial evaluation without permanent agent files; affects catalog skill coverage for review and quality workflows"
+  version: "1.1.0"
+  changelog: "Added DECISIONS.md registry ownership guidance; preserves durable review insights and anti-slop decisions across sessions; affects review-rangers workflow, install scaffolding, and project memory usage"
   auto-invoke: "Reviewing code, decisions, or artifacts where adversarial multi-perspective evaluation adds value"
   allowed-tools:
     - "Read"
+    - "Edit"
+    - "Write"
     - "Grep"
     - "Glob"
     - "Bash"
@@ -38,14 +40,16 @@ Do not use this skill for:
 ## Core Workflow
 
 1. Identify the target (code, decision, artifact) and its domain.
-2. Determine committee size: 3 members for routine reviews, 5 for high-risk or cross-domain targets.
-3. Spawn N committee members using `assets/committee-member-template.md`. Assign each a distinct evaluation lens. Run them independently — no member sees another's output.
-4. Determine the expert domain for the safety guard.
-5. Spawn 1 safety guard using `assets/safety-guard-template.md`. It evaluates the target from an authoritative expert position.
-6. Run the committee and safety guard in parallel.
-7. Collect all outputs.
-8. Synthesize a structured verdict following the Synthesis Rules.
-9. Emit the final verdict with confidence tier, top findings, and recommended action.
+2. Read `.ai/DECISIONS.md` if it exists. Treat it as project memory for avoiding repeated mistakes and reusing documented decisions.
+3. Determine committee size: 3 members for routine reviews, 5 for high-risk or cross-domain targets.
+4. Spawn N committee members using `assets/committee-member-template.md`. Assign each a distinct evaluation lens. Run them independently — no member sees another's output.
+5. Determine the expert domain for the safety guard.
+6. Spawn 1 safety guard using `assets/safety-guard-template.md`. It evaluates the target from an authoritative expert position.
+7. Run the committee and safety guard in parallel.
+8. Collect all outputs.
+9. Synthesize a structured verdict following the Synthesis Rules.
+10. Emit the final verdict with confidence tier, top findings, and recommended action.
+11. Decide whether any insight qualifies for `.ai/DECISIONS.md`; if yes, update the registry and its changelog in the same edit.
 
 ---
 
@@ -142,6 +146,56 @@ RECOMMENDED ACTION:
 
 ---
 
+## Decisions Registry Protocol
+
+`review-rangers` owns `.ai/DECISIONS.md` maintenance when the registry exists. Use it as both:
+
+- A documentary source before solving or reviewing relevant problems.
+- A durable memory target after review when a finding has future value.
+
+### Read Rules
+
+- Read `.ai/DECISIONS.md` near the start of relevant review or problem-solving work.
+- Apply documented decisions and "avoid repeating" notes as project constraints.
+- If the file does not exist, continue the review without creating it unless the current task is installation or explicit registry setup.
+
+### Write Criteria
+
+Write to `.ai/DECISIONS.md` only for:
+
+- Breaking changes.
+- Mid-interest or high-interest solutions.
+- Architectural decisions.
+- Repeated issue patterns.
+- Project-specific conventions likely to matter in future sessions.
+
+Do not write entries for minimal cleanup, obvious one-off bugs, insignificant changes, local-only implementation details, or full review transcripts.
+
+### Write Format
+
+Insert new entries above the final `## Changelog` section so the changelog remains the last section.
+
+```md
+## YYYY-MM-DD - Short Decision Title
+
+- Interest level: Mid | High | Breaking
+- Context:
+- Decision / Insight:
+- Rationale:
+- Avoid repeating:
+- Source:
+```
+
+Every change to `.ai/DECISIONS.md` must update `## Changelog` in the same edit.
+
+```md
+- YYYY-MM-DD: Created/updated entry "<title>" because <why>.
+```
+
+If the changelog section is missing, add it as the final section before making any other registry change.
+
+---
+
 ## Decision Tree
 
 ```text

package/catalog/skills/review-rangers/manifest.json

@@ -10,13 +10,15 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-04",
+    "last-edit": "2026-04-26",
     "license": "Apache-2.0",
-    "version": "1.0.0",
-    "changelog": "Added multi-perspective review skill with committee + safety guard synthesis; enables adversarial evaluation without permanent agent files; affects catalog skill coverage for review and quality workflows",
+    "version": "1.1.0",
+    "changelog": "Added DECISIONS.md registry ownership guidance; preserves durable review insights and anti-slop decisions across sessions; affects review-rangers workflow, install scaffolding, and project memory usage",
     "auto-invoke": "Reviewing code, decisions, or artifacts where adversarial multi-perspective evaluation adds value",
     "allowed-tools": [
       "Read",
+      "Edit",
+      "Write",
       "Grep",
       "Glob",
       "Bash",

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.23.3",
+  "version": "0.24.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Davecelot/skilly-hand.git"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -18,7 +22,8 @@
     "SECURITY.md"
   ],
   "workspaces": [
-    "packages/*"
+    "packages/*",
+    "site"
   ],
   "engines": {
     "node": ">=22.0.0"
@@ -47,7 +52,10 @@
     "cli": "node ./packages/cli/src/bin.js",
     "detect": "node ./packages/cli/src/bin.js detect",
     "list": "node ./packages/cli/src/bin.js list",
-    "doctor": "node ./packages/cli/src/bin.js doctor"
+    "doctor": "node ./packages/cli/src/bin.js doctor",
+    "site:dev": "npm run dev -w @skilly-hand/site",
+    "site:build": "npm run build -w @skilly-hand/site",
+    "site:preview": "npm run preview -w @skilly-hand/site"
   },
   "dependencies": {
     "inquirer": "13.4.1"

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.23.3",
+  "version": "0.24.0",
   "private": true,
   "type": "module"
 }

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.23.3",
+  "version": "0.24.0",
   "private": true,
   "type": "module",
   "bin": {

package/packages/cli/src/bin.js

@@ -131,11 +131,24 @@ function buildHelpText(renderer, appVersion) {
 
 function buildInstallResultDoc(result, flags, detectionGridText = "") {
   const mode = flags.dryRun ? "dry-run" : "apply";
+  const decisionsRegistry = result.plan.decisionsRegistry || {
+    relativePath: ".ai/DECISIONS.md",
+    exists: false,
+    willCreate: false
+  };
+  const decisionsRegistryStatus = decisionsRegistry.created
+    ? "created"
+    : decisionsRegistry.exists
+      ? "existing"
+      : decisionsRegistry.willCreate
+        ? "will create"
+        : "not reported";
   return createResultDoc("Install", [
     section("Install Preflight", [
       kvBlock([
         ["Project", result.plan.cwd],
         ["Install root", result.plan.installRoot],
+        ["Decisions registry", `${decisionsRegistry.relativePath} (${decisionsRegistryStatus})`],
         ["Agents", result.plan.agents.join(", ") || "none"],
         ["Include tags", flags.include.join(", ") || "none"],
         ["Exclude tags", flags.exclude.join(", ") || "none"],

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.23.3",
+  "version": "0.24.0",
   "private": true,
   "type": "module"
 }

package/packages/core/src/index.js

@@ -6,6 +6,35 @@ import { detectProject, inspectProjectFiles } from "../../detectors/src/index.js
 export const DEFAULT_AGENTS = ["standard", "codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"];
 const MANAGED_MARKER = "<!-- Managed by skilly-hand.";
 const NATIVE_SETUP_MARKER = "<!-- Managed by skilly-hand native setup.";
+const DECISIONS_REGISTRY_RELATIVE_PATH = ".ai/DECISIONS.md";
+const DECISIONS_REGISTRY_TEMPLATE = `# AI Decisions
+
+Durable project memory for \`review-rangers\`. Use this file to record breaking changes, mid/high-interest solutions, and important review insights that future agents should reuse.
+
+## Entry Criteria
+
+- Add entries only for breaking changes, mid/high-interest solutions, architectural decisions, repeated issue patterns, or project-specific conventions with future value.
+- Do not add minimal, obvious, one-off, or insignificant changes.
+- Do not paste full review transcripts.
+- Every change to this file must update the changelog at the end.
+
+## Entry Template
+
+\`\`\`md
+## YYYY-MM-DD - Short Decision Title
+
+- Interest level: Mid | High | Breaking
+- Context:
+- Decision / Insight:
+- Rationale:
+- Avoid repeating:
+- Source:
+\`\`\`
+
+## Changelog
+
+- YYYY-MM-DD: Created/updated entry "<title>" because <why>.
+`;
 const AGENT_INSTALL_PROFILES = {
   standard: {
     instructionFiles: [["AGENTS.md"]],
@@ -263,10 +292,60 @@ export function buildInstallPlan({ cwd, detections, skills, agents }) {
       tags: skill.tags
     })),
     installRoot: path.join(cwd, ".skilly-hand"),
+    decisionsRegistry: {
+      path: path.join(cwd, ".ai", "DECISIONS.md"),
+      relativePath: DECISIONS_REGISTRY_RELATIVE_PATH,
+      exists: false,
+      willCreate: true
+    },
     generatedAt: nowIso()
   };
 }
 
+async function planDecisionsRegistry(cwd) {
+  const aiDir = path.join(cwd, ".ai");
+  const registryPath = path.join(cwd, ".ai", "DECISIONS.md");
+
+  if (await exists(aiDir)) {
+    const info = await lstat(aiDir);
+    if (!info.isDirectory()) {
+      throw new Error("Cannot create decisions registry because .ai exists and is not a directory.");
+    }
+  }
+
+  let registryExists = false;
+  if (await exists(registryPath)) {
+    const info = await lstat(registryPath);
+    if (!info.isFile()) {
+      throw new Error("Cannot use decisions registry because .ai/DECISIONS.md exists and is not a file.");
+    }
+    registryExists = true;
+  }
+
+  return {
+    path: registryPath,
+    relativePath: DECISIONS_REGISTRY_RELATIVE_PATH,
+    exists: registryExists,
+    willCreate: !registryExists
+  };
+}
+
+async function ensureDecisionsRegistry(cwd) {
+  const registry = await planDecisionsRegistry(cwd);
+  if (registry.exists) {
+    return registry;
+  }
+
+  await mkdir(path.dirname(registry.path), { recursive: true });
+  await writeFile(registry.path, DECISIONS_REGISTRY_TEMPLATE, "utf8");
+  return {
+    ...registry,
+    exists: true,
+    willCreate: false,
+    created: true
+  };
+}
+
 async function backupPathIfNeeded(targetPath, backupsDir, lockData) {
   if (!(await exists(targetPath))) {
     return null;
@@ -600,6 +679,7 @@ export async function installProject({
         excludeTags: parseTags(excludeTags)
       });
   const plan = buildInstallPlan({ cwd, detections, skills, agents: selectedAgents });
+  plan.decisionsRegistry = await planDecisionsRegistry(cwd);
 
   if (dryRun) {
     return { plan, applied: false };
@@ -621,6 +701,8 @@ export async function installProject({
   await mkdir(installRoot, { recursive: true });
   await mkdir(targetCatalogDir, { recursive: true });
   await mkdir(backupsDir, { recursive: true });
+  const decisionsRegistry = await ensureDecisionsRegistry(cwd);
+  plan.decisionsRegistry = decisionsRegistry;
 
   for (const skill of skills) {
     await copySkillTo(targetCatalogDir, skill.id);

package/packages/detectors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/detectors",
-  "version": "0.23.3",
+  "version": "0.24.0",
   "private": true,
   "type": "module"
 }