@skilly-hand/skilly-hand 0.23.3 → 0.25.0

package/CHANGELOG.md

@@ -16,6 +16,40 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.25.0] - 2026-04-27
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.25.0)
+
+### Added
+- Added the `roaster` planning challenge skill to critique plans, assumptions, sequencing, risks, and verification before implementation.
+- Added native skill hook/rule metadata support so installed skills can surface required guidance in generated native adapter files.
+
+### Changed
+- Updated native setup output and CLI guidance to describe rule/hook adapters alongside native instruction files.
+- Exported deterministic native hook collection from core and included `nativeHooks` plus `nativeHooksStatus` in native setup plan output.
+
+### Fixed
+- _None._
+
+### 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/README.md

@@ -14,6 +14,7 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `project-teacher` | Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. Trigger: user asks to explain, understand, clarify, or learn about anything in the project or codebase. | core, workflow, education | all |
 | `react-guidelines` | Guide React code generation and review using latest stable React verification and modern framework best practices. | react, frontend, workflow, best-practices | all |
 | `review-rangers` | Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict. | core, workflow, review, quality | all |
+| `roaster` | Challenge plans with constructive roast-style critique that exposes weak assumptions, missing angles, shallow sequencing, and unclear success criteria. Trigger: when the user proposes, requests, or evaluates a plan of any kind. | core, workflow, planning, quality | all |
 | `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | core, workflow, authoring | all |
 | `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | core, workflow, planning | all |
 | `test-driven-development` | Guide implementation using the RED → GREEN → REFACTOR TDD cycle: write a failing test first, write the minimum code to pass, then refactor while tests stay green. | testing, workflow, quality, core | all |

package/catalog/catalog-index.json

@@ -9,6 +9,7 @@
   "project-teacher",
   "react-guidelines",
   "review-rangers",
+  "roaster",
   "skill-creator",
   "spec-driven-development",
   "test-driven-development",

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/catalog/skills/roaster/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: "roaster"
+description: "Challenge plans with constructive roast-style critique that exposes weak assumptions, missing angles, shallow sequencing, and unclear success criteria. Trigger: when the user proposes, requests, or evaluates a plan of any kind."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-27"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added roaster planning challenge skill; improves plan quality by forcing constructive skepticism before agreement; affects planning critique workflows and auto-invoke routing"
+  auto-invoke: "When the user proposes, requests, or evaluates a plan of any kind"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "Task"
+---
+# Roaster Guide
+
+## When to Use
+
+Use this skill when:
+
+- The user proposes, requests, or evaluates a plan.
+- A plan sounds under-specified, too agreeable, or too easy.
+- The user needs stronger assumptions, sharper scope, or better sequencing.
+- The work would benefit from a skeptical partner before execution.
+
+Do not use this skill for:
+
+- Emergencies where speed matters more than critique.
+- Trivial one-step tasks with no meaningful planning surface.
+- Sensitive emotional, medical, legal, or crisis conversations where roast tone would be inappropriate.
+- Personal attacks, identity jokes, humiliation, slurs, or cruelty.
+
+---
+
+## Critical Patterns
+
+### Pattern 1: Challenge First, Agree Second
+
+Default posture:
+
+```text
+Do not start with "yes, you are right."
+First identify the weakest part of the plan.
+Then acknowledge what works, if anything works.
+End with a stronger version of the plan or the questions needed to make one.
+```
+
+The target is the plan, not the person. Roast the gap between ambition and current rigor.
+
+### Pattern 2: Constructive Roast Boundaries
+
+Allowed:
+
+- Witty, direct critique of vague goals, missing constraints, shallow sequencing, or lazy acceptance criteria.
+- High standards, pointed questions, and clear pushback.
+- Humor that helps the user think harder.
+
+Not allowed:
+
+- Insults about intelligence, identity, background, appearance, worth, or mental health.
+- Discriminatory, sexual, threatening, or demeaning language.
+- Sarcasm that leaves the user with no actionable next step.
+
+### Pattern 3: Full-Angle Critique
+
+Check every real plan against these angles:
+
+| Angle | Challenge |
+| --- | --- |
+| Goal | Is the outcome specific enough to judge success? |
+| Assumptions | What is being treated as true without evidence? |
+| Stakeholders | Who is affected, blocked, or missing from the plan? |
+| Scope | What is included, excluded, and dangerously implied? |
+| Risks | What can fail technically, socially, financially, or operationally? |
+| Sequencing | Are steps ordered by dependency, learning value, and risk reduction? |
+| Alternatives | Is there a simpler, more complete, or more durable path? |
+| Verification | How will the user prove the result is good enough? |
+
+### Pattern 4: Escalate With Stakes
+
+Use light critique for small plans. Escalate to deeper challenge when the plan affects:
+
+- Architecture or long-term maintainability.
+- Security, privacy, or safety.
+- Delivery timelines, money, reputation, or users.
+- Irreversible decisions or broad organizational impact.
+
+---
+
+## Response Format
+
+Use this structure by default:
+
+```text
+Verdict: {short judgment}
+
+Roast: {constructive jab at the weakest part}
+
+Blind Spots:
+- {missing angle}
+- {missing angle}
+
+Upgrade:
+- {specific improvement}
+- {specific improvement}
+
+Questions:
+- {question that materially improves the plan}
+```
+
+Keep it compact unless the plan is high-risk or the user asks for a deeper review.
+
+---
+
+## Decision Tree
+
+```text
+Is this a plan or planning request?              -> Use roaster
+Is it trivial and one-step?                      -> Skip or give one-line challenge
+Does it affect high-stakes outcomes?             -> Deep critique across all angles
+Is the user asking for validation only?          -> Challenge before validating
+Is roast tone unsafe for the situation?          -> Switch to firm, compassionate critique
+Otherwise                                       -> Constructive roast with actionable upgrade
+```
+
+---
+
+## Examples
+
+### Example 1: Vague Product Plan
+
+```text
+Verdict: Promising, but currently held together with vibes and hope.
+
+Roast: "Launch the feature" is not a plan; it is a calendar event wearing a fake mustache.
+
+Blind Spots:
+- No target user or success metric.
+- No rollback or support path.
+
+Upgrade:
+- Define the primary user, the measurable outcome, and the smallest launch slice.
+- Add one validation step before build and one verification step after release.
+
+Questions:
+- What evidence would prove this is worth building before you spend the full effort?
+```
+
+### Example 2: Technical Refactor Plan
+
+```text
+Verdict: The direction is reasonable, but the blast radius is undercooked.
+
+Roast: "Refactor the service" is how regressions enter the room wearing a nice jacket.
+
+Blind Spots:
+- No compatibility strategy for existing callers.
+- No test boundary around current behavior.
+
+Upgrade:
+- Capture current behavior with focused tests before changing internals.
+- Refactor behind the existing public interface first, then evaluate API changes separately.
+
+Questions:
+- Which behavior must remain identical after the refactor?
+```
+
+---
+
+## Commands
+
+```bash
+rg -n "plan|proposal|roadmap|strategy|approach" .
+rg -n "success criteria|acceptance criteria|risks|assumptions" .
+```

package/catalog/skills/roaster/manifest.json

@@ -0,0 +1,41 @@
+{
+  "id": "roaster",
+  "title": "Roaster",
+  "description": "Challenge plans with constructive roast-style critique that exposes weak assumptions, missing angles, shallow sequencing, and unclear success criteria. Trigger: when the user proposes, requests, or evaluates a plan of any kind.",
+  "portable": true,
+  "tags": ["core", "workflow", "planning", "quality"],
+  "detectors": ["always"],
+  "detectionTriggers": ["always"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
+  "nativeHooks": [
+    {
+      "id": "plan-challenge",
+      "trigger": "When the user proposes, requests, or evaluates a plan of any kind",
+      "instruction": "Invoke roaster to critique assumptions, scope, sequencing, risks, and verification before agreeing with the plan.",
+      "priority": 30,
+      "enforcement": "required"
+    }
+  ],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-04-27",
+    "license": "Apache-2.0",
+    "version": "1.0.0",
+    "changelog": "Added roaster planning challenge skill; improves plan quality by forcing constructive skepticism before agreement; affects planning critique workflows and auto-invoke routing",
+    "auto-invoke": "When the user proposes, requests, or evaluates a plan of any kind",
+    "allowed-tools": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash",
+      "Task"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" }
+  ],
+  "dependencies": []
+}

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.23.3",
+  "version": "0.25.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.25.0",
   "private": true,
   "type": "module"
 }

package/packages/catalog/src/index.js

@@ -80,6 +80,8 @@ export function validateSkillManifest(manifest) {
     throw new Error(`Skill "${manifest.id}" must declare files`);
   }
 
+  validateNativeHooks(manifest);
+
   const hasSkillInstruction = manifest.files.some((file) => file.path === "SKILL.md" && file.kind === "instruction");
   if (!hasSkillInstruction) {
     throw new Error(`Skill "${manifest.id}" must include files entry for SKILL.md as instruction`);
@@ -90,6 +92,36 @@ export function validateSkillManifest(manifest) {
   return true;
 }
 
+function validateNativeHooks(manifest) {
+  if (!("nativeHooks" in manifest)) {
+    return;
+  }
+
+  if (!Array.isArray(manifest.nativeHooks)) {
+    throw new Error(`Skill "${manifest.id}" must declare nativeHooks as an array when present`);
+  }
+
+  for (const hook of manifest.nativeHooks) {
+    if (!hook || typeof hook !== "object" || Array.isArray(hook)) {
+      throw new Error(`Skill "${manifest.id}" has invalid nativeHooks entry; expected an object`);
+    }
+
+    for (const key of ["id", "trigger", "instruction", "enforcement"]) {
+      if (typeof hook[key] !== "string" || hook[key].trim().length === 0) {
+        throw new Error(`Skill "${manifest.id}" has invalid nativeHooks.${key}; expected a non-empty string`);
+      }
+    }
+
+    if (!["required", "recommended"].includes(hook.enforcement)) {
+      throw new Error(`Skill "${manifest.id}" has invalid nativeHooks.enforcement; expected required or recommended`);
+    }
+
+    if (!Number.isFinite(hook.priority)) {
+      throw new Error(`Skill "${manifest.id}" has invalid nativeHooks.priority; expected a finite number`);
+    }
+  }
+}
+
 function toLf(text) {
   return text.replaceAll("\r\n", "\n");
 }

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.23.3",
+  "version": "0.25.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"],
@@ -173,7 +186,7 @@ function buildInstallResultDoc(result, flags, detectionGridText = "") {
         result.applied
           ? [
               "Review generated AGENTS and assistant instruction files.",
-              "Run `npx skilly-hand native setup` to scaffold native instruction/rule adapters.",
+              "Run `npx skilly-hand native setup` to scaffold native instruction/rule/hook adapters.",
               "Run `npx skilly-hand doctor` to validate installation health.",
               "Use `npx skilly-hand uninstall` to restore backed-up files if needed."
             ]
@@ -215,7 +228,7 @@ function buildNativeSetupResultDoc(result, flags) {
     ]),
     section("Status", [
       result.applied
-        ? statusBlock("success", "Native setup completed.", "Native rule/instruction files are synchronized.")
+        ? statusBlock("success", "Native setup completed.", "Native rule/hook/instruction files are synchronized.")
         : statusBlock("info", "Native setup dry run complete.", "No files were written.")
     ]),
     section("Next Steps", [
@@ -223,10 +236,10 @@ function buildNativeSetupResultDoc(result, flags) {
         result.applied
           ? [
               "Run `npx skilly-hand doctor` to verify native coverage.",
-              "Re-run `npx skilly-hand native setup` after changing agent targets."
+              "Re-run `npx skilly-hand native setup` after changing agent targets or skill hook metadata."
             ]
           : [
-              "Run `npx skilly-hand native setup` to apply these native adapter changes."
+              "Run `npx skilly-hand native setup` to apply these native rule/hook adapter changes."
             ]
       )
     ])

package/packages/cli/src/command-registry.js

@@ -10,7 +10,7 @@ const CLI_COMMANDS = [
   {
     value: "native-setup",
     label: "Native Setup",
-    description: "Sync native assistant adapters and instruction files.",
+    description: "Sync native assistant adapters, rules, hooks, and instruction files.",
     bestFor: "After install or when assistant targets change",
     aliases: ["native", "adapters"],
     usage: "npx skilly-hand native setup"
@@ -105,4 +105,3 @@ export function formatHelpUsageLines() {
     ...CLI_COMMANDS.map((command) => command.usage)
   ];
 }
-

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.23.3",
+  "version": "0.25.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"]],
@@ -149,19 +178,57 @@ function resolveNativeAdapterTarget(cwd, adapter) {
   return path.join(cwd, ...adapter.targetPath);
 }
 
-function buildNativeRuleContent(agent, adapter) {
+export function collectNativeHooks({ catalog, skillIds = [] }) {
+  const selected = new Set(skillIds);
+  return catalog
+    .filter((skill) => selected.has(skill.id))
+    .flatMap((skill) => (skill.nativeHooks || []).map((hook) => ({
+      skillId: skill.id,
+      skillTitle: skill.title,
+      id: hook.id,
+      trigger: hook.trigger,
+      instruction: hook.instruction,
+      priority: hook.priority,
+      enforcement: hook.enforcement
+    })))
+    .sort((a, b) => (
+      a.priority - b.priority ||
+      a.skillId.localeCompare(b.skillId) ||
+      a.id.localeCompare(b.id)
+    ));
+}
+
+function renderNativeHookLines(nativeHooks, nativeHooksStatus) {
+  if (nativeHooks.length === 0) {
+    const emptyMessage = nativeHooksStatus === "not-installed"
+      ? "No installed skill hooks found. Run `npx skilly-hand install` before native setup to enable skill-driven rules."
+      : "No installed skills declare native hooks or rules.";
+    return [`- ${emptyMessage}`];
+  }
+
+  return nativeHooks.flatMap((hook) => [
+    `- [${hook.enforcement}] ${hook.skillId}/${hook.id}`,
+    `  - Trigger: ${hook.trigger}`,
+    `  - Rule: ${hook.instruction}`
+  ]);
+}
+
+function buildNativeRuleContent(agent, adapter, nativeHooks = [], nativeHooksStatus = "not-installed") {
   const trigger = "Run token-optimizer before review-rangers when doing risk-heavy review passes.";
   return [
     `${NATIVE_SETUP_MARKER} Re-run \`npx skilly-hand native setup\` to regenerate. -->`,
     `# skilly-hand Native Bootstrap (${agent})`,
     "",
-    `This file is managed by skilly-hand to keep native ${adapter.mode.replace("_", " ")} behavior consistent.`,
+    `This file is managed by skilly-hand to keep native ${adapter.mode.replace("_", " ")} rules/hooks consistent.`,
     "",
     "## Always-On Defaults",
     "- Apply AGENTS guidance from the repository root before task routing.",
     "- Enforce optimizer gate order: `token-optimizer` then `output-optimizer`.",
     "- Keep output concise by default (`step-brief`) unless user asks otherwise.",
     "",
+    "## Skill Hooks / Rules",
+    ...renderNativeHookLines(nativeHooks, nativeHooksStatus),
+    "",
     "## Token-Safe Review Stage",
     `- ${trigger}`,
     "- Keep review verdicts concise unless a blocker requires expanded rationale.",
@@ -263,10 +330,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;
@@ -493,6 +610,10 @@ export async function setupNativeProject({
   const lockPath = path.join(installRoot, "manifest.lock.json");
   const previousLock = await exists(lockPath) ? await readJson(lockPath) : null;
   const selectedAgents = normalizeAgentList(agents ?? previousLock?.agents);
+  const catalog = await loadAllSkills();
+  const installedSkillIds = previousLock?.skills || [];
+  const nativeHooks = collectNativeHooks({ catalog, skillIds: installedSkillIds });
+  const nativeHooksStatus = installedSkillIds.length > 0 ? "loaded" : "not-installed";
   const selectedNativeTargets = selectedAgents
     .map((agent) => NATIVE_ADAPTER_REGISTRY[agent])
     .filter((adapter) => adapter && adapter.supported)
@@ -505,7 +626,9 @@ export async function setupNativeProject({
     generatedAt,
     agents: selectedAgents,
     installRoot,
-    nativeStatus: nativeStatusBefore
+    nativeStatus: nativeStatusBefore,
+    nativeHooks,
+    nativeHooksStatus
   };
 
   if (dryRun) {
@@ -558,7 +681,7 @@ export async function setupNativeProject({
     }
 
     const targetPath = resolveNativeAdapterTarget(cwd, adapter);
-    const content = buildNativeRuleContent(agent, adapter);
+    const content = buildNativeRuleContent(agent, adapter, nativeHooks, nativeHooksStatus);
     await ensureManagedTextFile(targetPath, content, backupsDir, lockData, "managedNativeFiles");
     lockData.nativeProfiles[agent] = {
       status: "configured",
@@ -600,6 +723,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 +745,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.25.0",
   "private": true,
   "type": "module"
 }