@skilly-hand/skilly-hand 0.1.0

package/catalog/skills/token-optimizer/references/complexity-indicators.md

@@ -0,0 +1,138 @@
+# Task Complexity Indicators
+
+Use this reference to score task complexity before selecting reasoning depth and token budget.
+
+---
+
+## Scoring Bands
+
+| Total Points | Tier |
+| --- | --- |
+| 0-2 | Trivial |
+| 3-5 | Simple |
+| 6-10 | Moderate |
+| 11-15 | Complex |
+| 16+ | Expert |
+
+---
+
+## Scoring Matrix
+
+### File Scope
+
+| Indicator | Points |
+| --- | --- |
+| Single file, known location | 0 |
+| Single file, needs search | +1 |
+| 2-3 related files | +2 |
+| 4-6 files | +4 |
+| 7+ files or cross-package | +6 |
+| Build/config/tooling impact | +3 |
+
+### Decision Complexity
+
+| Indicator | Points |
+| --- | --- |
+| Single obvious approach | 0 |
+| 2-3 valid approaches, clear best option | +2 |
+| Multiple trade-off-heavy approaches | +4 |
+| Architectural design required | +6 |
+| System-wide pattern impact | +8 |
+
+### Context Requirements
+
+| Indicator | Points |
+| --- | --- |
+| Can answer from current context | 0 |
+| Requires 1-2 file reads | +1 |
+| Requires 3-5 file reads | +2 |
+| Requires codebase-wide search | +3 |
+| Requires dependency understanding | +4 |
+| Requires external docs/specs | +2 |
+
+### Impact Level
+
+| Indicator | Points |
+| --- | --- |
+| Internal helper only | 0 |
+| Private module behavior | +1 |
+| Public API behavior | +3 |
+| Shared utility used broadly | +4 |
+| Breaking public change | +6 |
+| Security-sensitive code | +8 |
+| Performance-critical path | +6 |
+
+### Testing and Validation
+
+| Indicator | Points |
+| --- | --- |
+| No tests needed | 0 |
+| Small unit test update | +1 |
+| Multiple test scenarios | +2 |
+| Integration/e2e coverage changes | +3 |
+| Manual QA verification required | +3 |
+| Accessibility validation required | +4 |
+
+### User Clarity (Reduction)
+
+| Indicator | Points |
+| --- | --- |
+| Vague request | 0 |
+| Clear goal | -1 |
+| Exact file paths provided | -2 |
+| Specific line numbers provided | -3 |
+| Reference implementation provided | -4 |
+| Explicit acceptance criteria | -2 |
+
+---
+
+## Keyword Signals
+
+High-complexity signals (+3 to +5):
+
+- optimize, performance, security, refactor, migrate, architect, scale
+
+Moderate signals (+1 to +2):
+
+- improve, extend, integrate, validate, fix bug
+
+Low signals (0):
+
+- show, list, find, read, check existence
+
+---
+
+## Context Size Heuristic
+
+| Context Size | Reads/Searches | Typical Tier |
+| --- | --- | --- |
+| Minimal | 0-1 | Trivial-Simple |
+| Light | 2-3 | Simple-Moderate |
+| Moderate | 4-7 | Moderate |
+| Heavy | 8-15 | Complex |
+| Extensive | 16+ | Expert |
+
+---
+
+## Reassessment Triggers
+
+Re-score during execution when:
+
+1. Scope expands into additional systems.
+2. The initial approach fails and alternatives are needed.
+3. User adds new constraints or quality requirements.
+4. Gathered context is insufficient for a safe answer.
+
+Escalate one tier when any of these materially changes risk or effort.
+
+---
+
+## Quick Card
+
+```text
+TRIVIAL (0-2)   -> Minimal reasoning, direct answer
+SIMPLE (3-5)    -> Light reasoning, focused context
+MODERATE (6-10) -> Selective reasoning, targeted exploration
+COMPLEX (11-15) -> Regular reasoning, systematic analysis
+EXPERT (16+)    -> Deep reasoning, broad trade-off evaluation
+```

package/catalog/templates/AGENTS.template.md

@@ -0,0 +1,37 @@
+# {{projectName}} AI Agent Orchestrator
+
+This file is generated by `skilly-hand`.
+
+## Where
+
+- Scope: repository root and all descendants unless overridden by deeper AGENTS files.
+- Installation generated at: `{{generatedAt}}`.
+- Detected technologies: `{{detectedTechnologies}}`.
+
+## What
+
+### Installed Skill Registry
+
+| Skill | Purpose | Tags |
+| ----- | ------- | ---- |
+{{skillsTable}}
+
+## When
+
+### Auto-invoke Triggers
+
+| Action | Skill |
+| ------ | ----- |
+{{autoInvokeTable}}
+
+## Chaining Notations
+
+Chaining notations document integrated workflows where multiple skills are sequentially invoked for complex tasks. Always invoke skills in documented order.
+
+### Root AGENTS Maintenance Workflow
+
+```text
+Updating root AGENTS.md guidance
+  -> agents-root-orchestrator
+  -> skill-creator (if reusable workflow docs changed)
+```

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@skilly-hand/skilly-hand",
+  "version": "0.1.0",
+  "license": "CC-BY-NC-4.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "skilly-hand": "packages/cli/src/bin.js"
+  },
+  "files": [
+    "catalog",
+    "packages",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "workspaces": [
+    "packages/*"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "node ./scripts/build-catalog-index.mjs",
+    "catalog:check": "node ./scripts/check-catalog.mjs",
+    "catalog:sync": "node ./scripts/sync-catalog-readme.mjs",
+    "agentic:self:sync": "node ./scripts/sync-self-agentic.mjs",
+    "test": "node --test tests/*.test.js",
+    "verify:packlist": "node ./scripts/verify-packlist.mjs",
+    "verify:publish": "npm run catalog:check && npm test && npm run verify:packlist",
+    "prepublishOnly": "npm run verify:publish",
+    "version": "node ./scripts/release-changelog.mjs",
+    "changelog:release": "node ./scripts/release-changelog.mjs",
+    "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"
+  }
+}

package/packages/catalog/package.json

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

package/packages/catalog/src/index.js

@@ -0,0 +1,223 @@
+import { cp, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "../../..");
+export const catalogDir = path.join(rootDir, "catalog");
+export const skillsDir = path.join(catalogDir, "skills");
+export const templatesDir = path.join(catalogDir, "templates");
+
+const REQUIRED_FIELDS = [
+  "id",
+  "title",
+  "description",
+  "portable",
+  "tags",
+  "detectors",
+  "installsFor",
+  "agentSupport",
+  "files",
+  "dependencies"
+];
+
+export function getCatalogRoot() {
+  return catalogDir;
+}
+
+export async function listSkillIds() {
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+export async function loadSkillManifest(skillId) {
+  const manifestPath = path.join(skillsDir, skillId, "manifest.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  validateSkillManifest(manifest);
+  return manifest;
+}
+
+export async function loadAllSkills() {
+  const ids = await listSkillIds();
+  const manifests = [];
+
+  for (const skillId of ids) {
+    manifests.push(await loadSkillManifest(skillId));
+  }
+
+  return manifests;
+}
+
+export function validateSkillManifest(manifest) {
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in manifest)) {
+      throw new Error(`Missing required field "${field}" in skill manifest`);
+    }
+  }
+
+  if (!Array.isArray(manifest.tags) || manifest.tags.length === 0) {
+    throw new Error(`Skill "${manifest.id}" must declare at least one tag`);
+  }
+
+  if (!Array.isArray(manifest.agentSupport) || manifest.agentSupport.length === 0) {
+    throw new Error(`Skill "${manifest.id}" must declare agentSupport`);
+  }
+
+  if (!Array.isArray(manifest.files) || manifest.files.length === 0) {
+    throw new Error(`Skill "${manifest.id}" must declare files`);
+  }
+
+  return true;
+}
+
+export async function copySkillTo(targetCatalogDir, skillId) {
+  const source = path.join(skillsDir, skillId);
+  const destination = path.join(targetCatalogDir, skillId);
+
+  await mkdir(targetCatalogDir, { recursive: true });
+  await cp(source, destination, { recursive: true, force: true });
+
+  return destination;
+}
+
+export async function readTemplate(templateName) {
+  return readFile(path.join(templatesDir, templateName), "utf8");
+}
+
+export function renderAgentsMarkdown({ skills, detections, generatedAt, projectName }) {
+  const sortedSkills = [...skills].sort((a, b) => a.id.localeCompare(b.id));
+  const sortedDetections = [...detections].sort((a, b) => a.technology.localeCompare(b.technology));
+  const autoInvokeSkills = sortedSkills.filter((skill) => skill.skillMetadata?.["auto-invoke"]);
+
+  const lines = [
+    "<!-- Managed by skilly-hand. Re-run `npx skilly-hand install` or `npm run agentic:self:sync` to regenerate. -->",
+    `# ${projectName || "Project"} AI Agent Orchestrator`,
+    "",
+    "> Root guidance for repository-wide AI routing. Use this file to understand where work belongs, what skills to invoke, and when triggers apply.",
+    "",
+    "## Where",
+    "",
+    "- Scope: repository root and all descendant folders unless a deeper AGENTS guide overrides locally.",
+    `- Generated at: ${generatedAt}`,
+    `- Detected technologies: ${sortedDetections.length === 0 ? "none" : sortedDetections.map((item) => item.technology).join(", ")}`,
+    "- Escalation boundary: when work changes global architecture, CI/CD, release, or security policy, escalate before implementation.",
+    "",
+    "## What",
+    "",
+    "### Installed Skill Registry",
+    "",
+    "| Skill | Description | Tags |",
+    "| ----- | ----------- | ---- |"
+  ];
+
+  for (const skill of sortedSkills) {
+    lines.push(`| \`${skill.id}\` | ${skill.description} | ${skill.tags.join(", ")} |`);
+  }
+
+  lines.push(
+    "",
+    "### Task Routing",
+    "",
+    "**SDD-first policy:** for feature delivery, bug fixes, or any multi-step implementation, start with `spec-driven-development` unless the task is clearly trivial and one-step.",
+    "",
+    "| Task Type | Recommended Skill Chain |",
+    "| --------- | ----------------------- |",
+    "| Planning feature work, bug fixes, and multi-phase implementation | `spec-driven-development` |",
+    "| Executing approved implementation plans | `spec-driven-development` -> task-specific skills |",
+    "| Creating or updating reusable skills | `skill-creator` |",
+    "| Creating or updating root AGENTS orchestration guidance | `agents-root-orchestrator` |",
+    "",
+    "## When",
+    "",
+    "### Auto-invoke Triggers",
+    ""
+  );
+
+  if (autoInvokeSkills.length === 0) {
+    lines.push("No explicit auto-invoke triggers were found in installed skill metadata.");
+  } else {
+    lines.push("| Action | Skill |", "| ------ | ----- |");
+    for (const skill of autoInvokeSkills) {
+      lines.push(`| ${skill.skillMetadata["auto-invoke"]} | \`${skill.id}\` |`);
+    }
+  }
+
+  lines.push(
+    "",
+    "### Sequencing Rules",
+    "",
+    "1. Classify task intent and scope first.",
+    "2. If work is non-trivial, invoke `spec-driven-development` before implementation.",
+    "3. Invoke prerequisite skills before implementation skills.",
+    "4. Verify outcomes and update this routing map when workflows change.",
+    "",
+    "## Chaining Notations",
+    "",
+    "Chaining notations document integrated workflows where multiple skills are sequentially invoked for complex tasks. Always invoke skills in documented order.",
+    "",
+    "### Root AGENTS Maintenance Workflow",
+    "",
+    "```text",
+    "Updating root AGENTS.md guidance",
+    "  -> agents-root-orchestrator",
+    "  -> skill-creator (if reusable workflow docs changed)",
+    "```",
+    "",
+    "### Skill Introduction Workflow",
+    "",
+    "```text",
+    "Asking for a new reusable skill",
+    "  -> skill-creator",
+    "  -> spec-driven-development",
+    "  -> agents-root-orchestrator",
+    "```",
+    "",
+    "### SDD-First Delivery Workflow",
+    "",
+    "```text",
+    "Feature, bug, or multi-step execution request",
+    "  -> spec-driven-development",
+    "  -> task-specific implementation skill(s)",
+    "  -> agents-root-orchestrator (if routing guidance changed)",
+    "```",
+    "",
+    "## Usage",
+    "",
+    "- Read the relevant `SKILL.md` file before starting a specialized task.",
+    "- Prefer installed skills under `.skilly-hand/catalog/` or repository `catalog/skills` as the source of truth.",
+    "- Use project-specific docs only as a supplement to these portable rules."
+  );
+
+  return lines.join("\n") + "\n";
+}
+
+export async function writeCatalogIndex() {
+  const ids = await listSkillIds();
+  const outputPath = path.join(catalogDir, "catalog-index.json");
+  await writeFile(outputPath, JSON.stringify(ids, null, 2) + "\n", "utf8");
+  return outputPath;
+}
+
+export async function verifyCatalogFiles() {
+  const skillIds = await listSkillIds();
+  const issues = [];
+
+  for (const skillId of skillIds) {
+    const skillPath = path.join(skillsDir, skillId);
+    const manifest = await loadSkillManifest(skillId);
+
+    for (const file of manifest.files) {
+      const filePath = path.join(skillPath, file.path);
+      try {
+        await stat(filePath);
+      } catch {
+        issues.push(`Missing file for ${skillId}: ${file.path}`);
+      }
+    }
+  }
+
+  return issues;
+}

package/packages/cli/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@skilly-hand/cli",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "skilly-hand": "./src/bin.js"
+  }
+}

package/packages/cli/src/bin.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { loadAllSkills } from "../../catalog/src/index.js";
+import { installProject, runDoctor, uninstallProject } from "../../core/src/index.js";
+import { detectProject } from "../../detectors/src/index.js";
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const positional = [];
+  const flags = {
+    dryRun: false,
+    yes: false,
+    verbose: false,
+    agents: [],
+    include: [],
+    exclude: []
+  };
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (!token.startsWith("-")) {
+      positional.push(token);
+      continue;
+    }
+
+    if (token === "--dry-run") flags.dryRun = true;
+    else if (token === "--yes" || token === "-y") flags.yes = true;
+    else if (token === "--verbose" || token === "-v") flags.verbose = true;
+    else if (token === "--agent" || token === "-a") flags.agents.push(args.shift());
+    else if (token === "--cwd") flags.cwd = args.shift();
+    else if (token === "--include") flags.include.push(args.shift());
+    else if (token === "--exclude") flags.exclude.push(args.shift());
+    else if (token === "--help" || token === "-h") flags.help = true;
+    else throw new Error(`Unknown flag: ${token}`);
+  }
+
+  return { command: positional[0], flags };
+}
+
+function printHelp() {
+  console.log(`skilly-hand
+
+Usage:
+  npx skilly-hand [install]
+  npx skilly-hand detect
+  npx skilly-hand list
+  npx skilly-hand doctor
+  npx skilly-hand uninstall
+
+Flags:
+  --dry-run
+  --yes
+  --verbose
+  --agent <codex|claude|cursor|gemini|copilot>
+  --cwd <path>
+  --include <tag>
+  --exclude <tag>
+`);
+}
+
+function printDetections(detections) {
+  if (detections.length === 0) {
+    console.log("No technology signals were detected.");
+    return;
+  }
+
+  for (const item of detections) {
+    console.log(`- ${item.technology} (${item.confidence})`);
+    console.log(`  reasons: ${item.reasons.join("; ")}`);
+    console.log(`  recommended skills: ${item.recommendedSkillIds.join(", ")}`);
+  }
+}
+
+function printPlan(plan) {
+  console.log(`Project: ${plan.cwd}`);
+  console.log(`Install root: ${plan.installRoot}`);
+  console.log(`Agents: ${plan.agents.join(", ")}`);
+  console.log("Detected technologies:");
+  printDetections(plan.detections);
+  console.log("Skills to install:");
+  for (const skill of plan.skills) {
+    console.log(`- ${skill.id}: ${skill.title} [${skill.tags.join(", ")}]`);
+  }
+}
+
+async function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+
+  if (flags.help) {
+    printHelp();
+    return;
+  }
+
+  const cwd = path.resolve(flags.cwd || process.cwd());
+  const effectiveCommand = command || "install";
+
+  if (effectiveCommand === "detect") {
+    printDetections(await detectProject(cwd));
+    return;
+  }
+
+  if (effectiveCommand === "list") {
+    const skills = await loadAllSkills();
+    for (const skill of skills) {
+      console.log(`- ${skill.id}: ${skill.title}`);
+      console.log(`  tags: ${skill.tags.join(", ")}`);
+      console.log(`  agents: ${skill.agentSupport.join(", ")}`);
+    }
+    return;
+  }
+
+  if (effectiveCommand === "doctor") {
+    const result = await runDoctor(cwd);
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (effectiveCommand === "uninstall") {
+    const result = await uninstallProject(cwd);
+    console.log(result.removed ? "skilly-hand installation removed." : result.reason);
+    return;
+  }
+
+  if (effectiveCommand === "install") {
+    const result = await installProject({
+      cwd,
+      agents: flags.agents,
+      dryRun: flags.dryRun,
+      includeTags: flags.include,
+      excludeTags: flags.exclude
+    });
+
+    printPlan(result.plan);
+    console.log(result.applied ? "Installation completed." : "Dry run only; nothing was written.");
+    return;
+  }
+
+  throw new Error(`Unknown command: ${effectiveCommand}`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/packages/core/package.json

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