@skilly-hand/skilly-hand 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -16,6 +16,23 @@ 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)
 

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/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,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "repository": {

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.24.0",
+  "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.24.0",
+  "version": "0.25.0",
   "private": true,
   "type": "module",
   "bin": {

package/packages/cli/src/bin.js

@@ -186,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."
             ]
@@ -228,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", [
@@ -236,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.24.0",
+  "version": "0.25.0",
   "private": true,
   "type": "module"
 }

package/packages/core/src/index.js

@@ -178,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.",
@@ -572,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)
@@ -584,7 +626,9 @@ export async function setupNativeProject({
     generatedAt,
     agents: selectedAgents,
     installRoot,
-    nativeStatus: nativeStatusBefore
+    nativeStatus: nativeStatusBefore,
+    nativeHooks,
+    nativeHooksStatus
   };
 
   if (dryRun) {
@@ -637,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",

package/packages/detectors/package.json

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