@slamb2k/mad-skills 2.0.6

package/skills/sync/instructions.md

@@ -0,0 +1,178 @@
+# Sync Instructions
+
+Synchronize local repository with the remote default branch using a single
+Bash subagent to isolate all git operations from the primary conversation.
+
+## Flags
+
+Parse optional flags from the request:
+- `--no-stash`: Don't auto-stash uncommitted changes
+- `--no-cleanup`: Don't delete stale local branches
+- `--no-rebase`: Use merge instead of rebase when on a feature branch
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| git | cli | `git --version` | yes | stop | Install from https://git-scm.com |
+
+For each row, in order:
+1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+   - **stop**: notify user with Detail, halt execution
+   - **url**: notify user with Detail (install link), halt execution
+   - **install**: notify user, run the command in Detail, continue if successful
+   - **ask**: notify user, offer to run command in Detail, continue either way (or halt if required)
+   - **fallback**: notify user with Detail, continue with degraded behavior
+4. After all checks: summarize what's available and what's degraded
+
+---
+
+## Pre-flight Detection
+
+Before launching the subagent, detect the remote and default branch:
+
+```
+REMOTE=$(git remote | head -1)   # usually "origin"
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/$REMOTE/HEAD 2>/dev/null | sed 's|.*/||')
+```
+
+Fallback chain if `symbolic-ref` fails:
+1. Check `git show-ref --verify refs/heads/main` → use `main`
+2. Check `git show-ref --verify refs/heads/master` → use `master`
+3. If neither exists, report error and stop
+
+Pass `{REMOTE}` and `{DEFAULT_BRANCH}` into the subagent prompt.
+
+---
+
+## Execution
+
+Launch a **Bash subagent** (haiku — pure git commands, no code analysis needed):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Sync repo with {DEFAULT_BRANCH}",
+  prompt: <see prompt below>
+)
+```
+
+### Subagent Prompt
+
+```
+Synchronize this git repository with {REMOTE}/{DEFAULT_BRANCH}. Execute the
+following steps in order and report results.
+
+Limit SYNC_REPORT to 15 lines maximum.
+
+FLAGS: {flags from request, or "none"}
+
+## Steps
+
+1. **Check state**
+   BRANCH=$(git branch --show-current 2>/dev/null || echo "DETACHED")
+   CHANGES=$(git status --porcelain | head -20)
+   Record: current_branch=$BRANCH, has_changes=(non-empty CHANGES)
+
+   If BRANCH == "DETACHED":
+     Record error: "Detached HEAD — cannot sync. Checkout a branch first."
+     Skip to Output.
+
+2. **Stash changes** (skip if --no-stash or no changes)
+   If has_changes and not --no-stash:
+     git stash push -m "sync-auto-stash-$(date +%Y%m%d-%H%M%S)"
+     Record: stash_created=true
+
+3. **Sync {DEFAULT_BRANCH}**
+   git fetch {REMOTE}
+   If BRANCH != "{DEFAULT_BRANCH}":
+     git checkout {DEFAULT_BRANCH}
+   git pull {REMOTE} {DEFAULT_BRANCH} --ff-only
+   If pull fails (diverged):
+     git pull {REMOTE} {DEFAULT_BRANCH} --rebase
+   Record: main_commit=$(git rev-parse --short HEAD)
+   Record: main_message=$(git log -1 --format=%s)
+
+4. **Return to branch and update** (skip if already on {DEFAULT_BRANCH})
+   If current_branch != "{DEFAULT_BRANCH}":
+     git checkout $BRANCH
+     If --no-rebase:
+       git merge {DEFAULT_BRANCH} --no-edit
+     Else:
+       git rebase {DEFAULT_BRANCH}
+       If rebase fails:
+         git rebase --abort
+         Record: rebase_status="conflict — aborted, branch unchanged"
+
+5. **Restore stash** (if created in step 2)
+   If stash_created:
+     git stash pop
+     If pop fails (conflict):
+       Record: stash="conflict — run 'git stash show' to inspect"
+     Else:
+       Record: stash="restored"
+
+6. **Cleanup branches** (skip if --no-cleanup)
+   git fetch --prune
+
+   # Delete branches whose remote is gone
+   for branch in $(git branch -vv | grep ': gone]' | awk '{print $1}'); do
+     if [ "$branch" != "$BRANCH" ]; then
+       git branch -d "$branch" 2>/dev/null && echo "Deleted: $branch"
+     fi
+   done
+
+   # Delete branches fully merged into {DEFAULT_BRANCH} (except current)
+   for branch in $(git branch --merged {DEFAULT_BRANCH} | grep -v '^\*' | grep -v '{DEFAULT_BRANCH}'); do
+     branch=$(echo "$branch" | xargs)
+     if [ "$branch" != "$BRANCH" ] && [ -n "$branch" ]; then
+       git branch -d "$branch" 2>/dev/null && echo "Deleted: $branch"
+     fi
+   done
+
+   Record: branches_cleaned={list of deleted branches, or "none"}
+
+7. **Final state**
+   echo "Branch: $(git branch --show-current)"
+   echo "HEAD: $(git log -1 --format='%h %s')"
+   echo "Status: $(git status --short | wc -l) modified files"
+
+## Output Format
+
+SYNC_REPORT:
+- status: success|failed
+- remote: {REMOTE}
+- default_branch: {DEFAULT_BRANCH}
+- main_updated_to: {commit} - {message}
+- current_branch: {branch}
+- stash: restored|none|conflict
+- rebase: success|conflict|skipped
+- branches_cleaned: {list or "none"}
+- errors: {any errors encountered}
+```
+
+---
+
+## Report to User
+
+Parse the subagent's SYNC_REPORT and present a clean summary:
+
+```
+Sync complete
+  Main:    {commit} - {message}
+  Branch:  {current_branch}
+  Stash:   {status}
+  Cleaned: {branches or "none"}
+```
+
+If errors occurred, report them clearly with suggested resolution:
+- Detached HEAD → suggest `git checkout <branch>`
+- Rebase conflict → suggest `git rebase {DEFAULT_BRANCH}` manually and resolve
+- Stash conflict → suggest `git stash show` and `git stash pop` manually

package/skills/sync/tests/evals.json

@@ -0,0 +1,29 @@
+[
+  {
+    "name": "banner-and-tagline",
+    "prompt": "Sync my repository",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "regex", "value": "(Pulling the latest|All aboard the sync|same page|plot twists|steal everyone|Catching up|rinse, repeat|Previously on main)" },
+      { "type": "semantic", "value": "The response begins with an ASCII art banner displayed BEFORE any explanation or workflow steps" }
+    ]
+  },
+  {
+    "name": "workflow-awareness",
+    "prompt": "I need to get my local repo up to date with the remote",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "regex", "value": "(stash|uncommitted)", "flags": "i" },
+      { "type": "regex", "value": "(fetch|pull)", "flags": "i" },
+      { "type": "semantic", "value": "Describes a git sync workflow that handles uncommitted changes, fetches from remote, and cleans up stale branches" }
+    ]
+  },
+  {
+    "name": "flag-handling",
+    "prompt": "Sync my repo --no-stash --no-cleanup",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "semantic", "value": "Acknowledges the --no-stash flag (will skip stashing uncommitted changes) and the --no-cleanup flag (will skip deleting stale branches)" }
+    ]
+  }
+]

package/src/cli.js

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Skills Installer CLI
+ *
+ * Usage:
+ *   npx @your-scope/claude-skills                    # Install all skills
+ *   npx @your-scope/claude-skills --list             # List available skills
+ *   npx @your-scope/claude-skills --skill foo,bar    # Install specific skills
+ *   npx @your-scope/claude-skills --target ./path    # Custom install path
+ *   npx @your-scope/claude-skills --upgrade          # Upgrade existing skills
+ */
+
+import { readdir, readFile, mkdir, access, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_SRC = resolve(__dirname, "..", "skills");
+
+const DEFAULT_TARGETS = [
+  ".claude/skills", // Project-level (preferred)
+  join(process.env.HOME ?? "~", ".claude", "skills"), // User-level fallback
+];
+
+const { values: args } = parseArgs({
+  options: {
+    list: { type: "boolean", default: false },
+    skill: { type: "string", default: "" },
+    target: { type: "string", default: "" },
+    upgrade: { type: "boolean", default: false },
+    force: { type: "boolean", short: "f", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+  strict: true,
+});
+
+if (args.help) {
+  console.log(`
+Claude Skills Installer
+
+Usage:
+  npx @your-scope/claude-skills [options]
+
+Options:
+  --list              List available skills with descriptions
+  --skill <names>     Comma-separated skill names to install (default: all)
+  --target <path>     Installation directory (default: .claude/skills)
+  --upgrade           Overwrite existing skills
+  --force, -f         Skip confirmation prompts
+  --help, -h          Show this help
+
+Examples:
+  npx @your-scope/claude-skills --list
+  npx @your-scope/claude-skills --skill git-workflow,mcp-builder
+  npx @your-scope/claude-skills --target ./my-project/.claude/skills --upgrade
+`);
+  process.exit(0);
+}
+
+async function discoverSkills() {
+  const entries = await readdir(SKILLS_SRC, { withFileTypes: true });
+  const skills = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+
+    const skillMd = join(SKILLS_SRC, entry.name, "SKILL.md");
+    try {
+      await access(skillMd);
+      const content = await readFile(skillMd, "utf-8");
+      const frontmatter = parseFrontmatter(content);
+
+      skills.push({
+        name: entry.name,
+        displayName: frontmatter.name ?? entry.name,
+        description: frontmatter.description ?? "(no description)",
+        path: join(SKILLS_SRC, entry.name),
+      });
+    } catch {
+      // Skip directories without SKILL.md
+    }
+  }
+
+  return skills;
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const result = {};
+  for (const line of match[1].split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    result[key] = value;
+  }
+  return result;
+}
+
+async function resolveTarget() {
+  if (args.target) return resolve(args.target);
+
+  // Prefer project-level if we're in a git repo or have .claude dir
+  for (const candidate of DEFAULT_TARGETS) {
+    const resolved = resolve(candidate);
+    try {
+      await access(dirname(resolved));
+      return resolved;
+    } catch {
+      continue;
+    }
+  }
+
+  return resolve(DEFAULT_TARGETS[0]);
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dependency management
+// ---------------------------------------------------------------------------
+
+const VALID_DEP_TYPES = new Set(["cli", "npm", "agent", "skill", "plugin"]);
+const VALID_DEP_RESOLUTIONS = new Set(["url", "install", "ask", "fallback", "stop"]);
+
+/**
+ * Parse a markdown dependency table from instructions.md content.
+ * Returns an array of { name, type, check, required, resolution, detail }.
+ */
+function parseDependencyTable(content) {
+  const lines = content.split("\n");
+  const deps = [];
+
+  const headerIdx = lines.findIndex((l) =>
+    /^\|\s*Dependency\s*\|/i.test(l)
+  );
+  if (headerIdx === -1) return deps;
+
+  for (let i = headerIdx + 2; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line.startsWith("|")) break;
+
+    const cells = line
+      .split("|")
+      .slice(1, -1)
+      .map((c) => c.trim());
+    if (cells.length < 6) continue;
+
+    const check = cells[2].replace(/^`|`$/g, "");
+    deps.push({
+      name: cells[0],
+      type: cells[1],
+      check: check === "—" || check === "-" || check === "" ? null : check,
+      required: cells[3].toLowerCase() === "yes",
+      resolution: cells[4],
+      detail: cells[5].replace(/^`|`$/g, ""),
+    });
+  }
+
+  return deps;
+}
+
+/**
+ * Check whether a single dependency is available.
+ * Returns true if found, false if missing.
+ */
+function checkDependency(dep, targetDir) {
+  if (!dep.check) return true;
+
+  try {
+    switch (dep.type) {
+      case "cli":
+      case "npm":
+        execSync(dep.check, { stdio: "ignore", timeout: 15000 });
+        return true;
+      case "agent":
+      case "skill": {
+        const p = dep.check.replace(/^~/, process.env.HOME ?? "~");
+        if (existsSync(resolve(p))) return true;
+        // For skill deps, also check inside the install target directory
+        if (targetDir && dep.type === "skill") {
+          const parts = dep.check.split("/");
+          const idx = parts.indexOf("skills");
+          if (idx !== -1 && idx + 1 < parts.length) {
+            const targetPath = join(targetDir, parts[idx + 1], "SKILL.md");
+            if (existsSync(targetPath)) return true;
+          }
+        }
+        return false;
+      }
+      case "plugin":
+        return false;
+      default:
+        return true;
+    }
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Apply the resolution strategy for a missing dependency.
+ * Returns "installed" | "warning" | "info".
+ */
+function resolveDependency(dep) {
+  switch (dep.resolution) {
+    case "stop":
+    case "url": {
+      const icon = dep.required ? "⚠" : "ℹ";
+      console.log(`     ${icon}  ${dep.name} not found — ${dep.detail}`);
+      return "warning";
+    }
+    case "install": {
+      try {
+        execSync(dep.detail, { stdio: "pipe", timeout: 60000 });
+        console.log(`     ✅ ${dep.name} installed (ran: ${dep.detail})`);
+        return "installed";
+      } catch {
+        console.log(
+          `     ⚠  ${dep.name} auto-install failed — run manually: ${dep.detail}`
+        );
+        return "warning";
+      }
+    }
+    case "ask": {
+      console.log(
+        `     ℹ  ${dep.name} not found — optional, install with: ${dep.detail}`
+      );
+      return "info";
+    }
+    case "fallback": {
+      console.log(`     ℹ  ${dep.name} not found — ${dep.detail}`);
+      return "info";
+    }
+    default:
+      return "ok";
+  }
+}
+
+/**
+ * Check all dependencies declared in a skill's instructions.md.
+ * Returns { installed, warnings } counts.
+ */
+async function checkSkillDependencies(skillName, targetDir) {
+  const instructionsPath = join(targetDir, skillName, "instructions.md");
+  let content;
+  try {
+    content = await readFile(instructionsPath, "utf-8");
+  } catch {
+    return { installed: 0, warnings: 0 };
+  }
+
+  const deps = parseDependencyTable(content);
+  if (deps.length === 0) return { installed: 0, warnings: 0 };
+
+  let installed = 0;
+  let warnCount = 0;
+
+  for (const dep of deps) {
+    if (checkDependency(dep, targetDir)) continue;
+    const result = resolveDependency(dep);
+    if (result === "installed") installed++;
+    if (result === "warning") warnCount++;
+  }
+
+  return { installed, warnings: warnCount };
+}
+
+async function installSkill(skill, targetDir) {
+  const dest = join(targetDir, skill.name);
+  const destExists = await exists(dest);
+
+  if (destExists && !args.upgrade) {
+    return { name: skill.name, status: "skipped" };
+  }
+
+  // Copy skill, filtering out CI-only directories
+  await cpFiltered(skill.path, dest);
+
+  return { name: skill.name, status: destExists ? "upgraded" : "installed" };
+}
+
+/**
+ * Recursively copies a skill directory, excluding CI/test artefacts
+ * that consumers don't need. Matches the .skill package exclusions.
+ */
+const INSTALL_EXCLUDE_DIRS = new Set([
+  "tests",
+  "evals",
+  "__pycache__",
+  "node_modules",
+  ".git",
+]);
+const INSTALL_EXCLUDE_FILES = new Set([".DS_Store", ".gitkeep"]);
+
+async function cpFiltered(src, dest) {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      if (INSTALL_EXCLUDE_DIRS.has(entry.name)) continue;
+      await cpFiltered(srcPath, destPath);
+    } else if (entry.isFile()) {
+      if (INSTALL_EXCLUDE_FILES.has(entry.name)) continue;
+      if (entry.name.endsWith(".pyc")) continue;
+      const { copyFile } = await import("node:fs/promises");
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function main() {
+  const skills = await discoverSkills();
+
+  if (skills.length === 0) {
+    console.error("No skills found in package. This is likely a packaging error.");
+    process.exit(1);
+  }
+
+  // --list mode
+  if (args.list) {
+    console.log("\nAvailable skills:\n");
+    const maxName = Math.max(...skills.map((s) => s.name.length));
+    for (const skill of skills) {
+      const desc =
+        skill.description.length > 80
+          ? skill.description.slice(0, 77) + "..."
+          : skill.description;
+      console.log(`  ${skill.name.padEnd(maxName + 2)} ${desc}`);
+    }
+    console.log(`\n${skills.length} skill(s) available\n`);
+    process.exit(0);
+  }
+
+  // Filter skills if --skill specified
+  let toInstall = skills;
+  if (args.skill) {
+    const requested = new Set(args.skill.split(",").map((s) => s.trim()));
+    toInstall = skills.filter((s) => requested.has(s.name));
+    const found = new Set(toInstall.map((s) => s.name));
+    const missing = [...requested].filter((r) => !found.has(r));
+    if (missing.length > 0) {
+      console.error(`Unknown skills: ${missing.join(", ")}`);
+      console.error(`Use --list to see available skills`);
+      process.exit(1);
+    }
+  }
+
+  const targetDir = await resolveTarget();
+  await mkdir(targetDir, { recursive: true });
+
+  console.log(`\nInstalling ${toInstall.length} skill(s) to ${targetDir}\n`);
+
+  // Pass 1: Install all skills (file copy)
+  const results = [];
+  for (const skill of toInstall) {
+    results.push(await installSkill(skill, targetDir));
+  }
+
+  // Pass 2: Print results and check dependencies
+  let totalDepsInstalled = 0;
+  let totalDepsWarnings = 0;
+
+  for (const result of results) {
+    if (result.status === "skipped") {
+      console.log(`  ⏭  ${result.name} (exists, use --upgrade to overwrite)`);
+    } else {
+      console.log(`  ✅ ${result.name} (${result.status})`);
+      const depResult = await checkSkillDependencies(result.name, targetDir);
+      totalDepsInstalled += depResult.installed;
+      totalDepsWarnings += depResult.warnings;
+    }
+  }
+
+  const installed = results.filter((r) => r.status === "installed").length;
+  const upgraded = results.filter((r) => r.status === "upgraded").length;
+  const skipped = results.filter((r) => r.status === "skipped").length;
+
+  console.log(
+    `\nDone: ${installed} installed, ${upgraded} upgraded, ${skipped} skipped`
+  );
+  if (totalDepsInstalled > 0 || totalDepsWarnings > 0) {
+    const parts = [];
+    if (totalDepsInstalled > 0) {
+      parts.push(
+        `${totalDepsInstalled} ${totalDepsInstalled === 1 ? "dependency" : "dependencies"} installed`
+      );
+    }
+    if (totalDepsWarnings > 0) {
+      parts.push(
+        `${totalDepsWarnings} ${totalDepsWarnings === 1 ? "warning" : "warnings"}`
+      );
+    }
+    console.log(`  ${parts.join(", ")}`);
+  }
+  console.log();
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err.message);
+  process.exit(1);
+});