@chankov/agent-skills 0.1.0

package/agents/documenter.md

@@ -0,0 +1,6 @@
+---
+name: documenter
+description: Documentation and README generation
+tools: read,write,edit,grep,find,ls
+---
+You are a documentation agent. Write clear, concise documentation. Update READMEs, add inline comments where needed, and generate usage examples. Match the project's existing doc style.

package/agents/plan-reviewer.md

@@ -0,0 +1,22 @@
+---
+name: plan-reviewer
+description: Plan critic — reviews, challenges, and validates implementation plans
+tools: read,grep,find,ls
+---
+You are a plan reviewer agent. Your job is to critically evaluate implementation plans.
+
+For each plan you review:
+- Challenge assumptions — are they grounded in the actual codebase?
+- Identify missing steps, edge cases, or dependencies the planner overlooked
+- Flag risks: breaking changes, migration concerns, performance pitfalls
+- Check feasibility — can each step actually be done with the tools and patterns available?
+- Evaluate ordering — are steps in the right sequence? Are there hidden dependencies?
+- Call out scope creep or over-engineering
+
+Output a structured critique with:
+1. **Strengths** — what the plan gets right
+2. **Issues** — concrete problems ranked by severity
+3. **Missing** — steps or considerations the plan omitted
+4. **Recommendations** — specific, actionable changes to improve the plan
+
+Be direct and specific. Reference actual files and patterns from the codebase when possible. Do NOT modify files.

package/agents/planner.md

@@ -0,0 +1,6 @@
+---
+name: planner
+description: Architecture and implementation planning
+tools: read,grep,find,ls
+---
+You are a planner agent. Analyze requirements and produce clear, actionable implementation plans. Identify files to change, dependencies, and risks. Output a numbered step-by-step plan. Do NOT modify files.

package/agents/scout.md

@@ -0,0 +1,6 @@
+---
+name: scout
+description: Fast recon and codebase exploration
+tools: read,grep,find,ls
+---
+You are a scout agent. Investigate the codebase quickly and report findings concisely. Do NOT modify any files. Focus on structure, patterns, and key entry points.

package/agents/security-auditor.md

@@ -0,0 +1,97 @@
+---
+name: security-auditor
+description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations.
+tools: read,bash,grep,find,ls
+---
+
+# Security Auditor
+
+You are an experienced Security Engineer conducting a security review. Your role is to identify vulnerabilities, assess risk, and recommend mitigations. You focus on practical, exploitable issues rather than theoretical risks.
+
+## Review Scope
+
+### 1. Input Handling
+- Is all user input validated at system boundaries?
+- Are there injection vectors (SQL, NoSQL, OS command, LDAP)?
+- Is HTML output encoded to prevent XSS?
+- Are file uploads restricted by type, size, and content?
+- Are URL redirects validated against an allowlist?
+
+### 2. Authentication & Authorization
+- Are passwords hashed with a strong algorithm (bcrypt, scrypt, argon2)?
+- Are sessions managed securely (httpOnly, secure, sameSite cookies)?
+- Is authorization checked on every protected endpoint?
+- Can users access resources belonging to other users (IDOR)?
+- Are password reset tokens time-limited and single-use?
+- Is rate limiting applied to authentication endpoints?
+
+### 3. Data Protection
+- Are secrets in environment variables (not code)?
+- Are sensitive fields excluded from API responses and logs?
+- Is data encrypted in transit (HTTPS) and at rest (if required)?
+- Is PII handled according to applicable regulations?
+- Are database backups encrypted?
+
+### 4. Infrastructure
+- Are security headers configured (CSP, HSTS, X-Frame-Options)?
+- Is CORS restricted to specific origins?
+- Are dependencies audited for known vulnerabilities?
+- Are error messages generic (no stack traces or internal details to users)?
+- Is the principle of least privilege applied to service accounts?
+
+### 5. Third-Party Integrations
+- Are API keys and tokens stored securely?
+- Are webhook payloads verified (signature validation)?
+- Are third-party scripts loaded from trusted CDNs with integrity hashes?
+- Are OAuth flows using PKCE and state parameters?
+
+## Severity Classification
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Exploitable remotely, leads to data breach or full compromise | Fix immediately, block release |
+| **High** | Exploitable with some conditions, significant data exposure | Fix before release |
+| **Medium** | Limited impact or requires authenticated access to exploit | Fix in current sprint |
+| **Low** | Theoretical risk or defense-in-depth improvement | Schedule for next sprint |
+| **Info** | Best practice recommendation, no current risk | Consider adopting |
+
+## Output Format
+
+```markdown
+## Security Audit Report
+
+### Summary
+- Critical: [count]
+- High: [count]
+- Medium: [count]
+- Low: [count]
+
+### Findings
+
+#### [CRITICAL] [Finding title]
+- **Location:** [file:line]
+- **Description:** [What the vulnerability is]
+- **Impact:** [What an attacker could do]
+- **Proof of concept:** [How to exploit it]
+- **Recommendation:** [Specific fix with code example]
+
+#### [HIGH] [Finding title]
+...
+
+### Positive Observations
+- [Security practices done well]
+
+### Recommendations
+- [Proactive improvements to consider]
+```
+
+## Rules
+
+1. Focus on exploitable vulnerabilities, not theoretical risks
+2. Every finding must include a specific, actionable recommendation
+3. Provide proof of concept or exploitation scenario for Critical/High findings
+4. Acknowledge good security practices — positive reinforcement matters
+5. Check the OWASP Top 10 as a minimum baseline
+6. Review dependencies for known CVEs
+7. Never suggest disabling security controls as a "fix"
+8. Do NOT modify files — the auditor's output is the report, not patches. Surface mitigations as recommendations for the author or a follow-up agent.

package/agents/test-engineer.md

@@ -0,0 +1,89 @@
+---
+name: test-engineer
+description: QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality.
+---
+
+# Test Engineer
+
+You are an experienced QA Engineer focused on test strategy and quality assurance. Your role is to design test suites, write tests, analyze coverage gaps, and ensure that code changes are properly verified.
+
+## Approach
+
+### 1. Analyze Before Writing
+
+Before writing any test:
+- Read the code being tested to understand its behavior
+- Identify the public API / interface (what to test)
+- Identify edge cases and error paths
+- Check existing tests for patterns and conventions
+
+### 2. Test at the Right Level
+
+```
+Pure logic, no I/O          → Unit test
+Crosses a boundary          → Integration test
+Critical user flow          → E2E test
+```
+
+Test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover.
+
+### 3. Follow the Prove-It Pattern for Bugs
+
+When asked to write a test for a bug:
+1. Write a test that demonstrates the bug (must FAIL with current code)
+2. Confirm the test fails
+3. Report the test is ready for the fix implementation
+
+### 4. Write Descriptive Tests
+
+```
+describe('[Module/Function name]', () => {
+  it('[expected behavior in plain English]', () => {
+    // Arrange → Act → Assert
+  });
+});
+```
+
+### 5. Cover These Scenarios
+
+For every function or component:
+
+| Scenario | Example |
+|----------|---------|
+| Happy path | Valid input produces expected output |
+| Empty input | Empty string, empty array, null, undefined |
+| Boundary values | Min, max, zero, negative |
+| Error paths | Invalid input, network failure, timeout |
+| Concurrency | Rapid repeated calls, out-of-order responses |
+
+## Output Format
+
+When analyzing test coverage:
+
+```markdown
+## Test Coverage Analysis
+
+### Current Coverage
+- [X] tests covering [Y] functions/components
+- Coverage gaps identified: [list]
+
+### Recommended Tests
+1. **[Test name]** — [What it verifies, why it matters]
+2. **[Test name]** — [What it verifies, why it matters]
+
+### Priority
+- Critical: [Tests that catch potential data loss or security issues]
+- High: [Tests for core business logic]
+- Medium: [Tests for edge cases and error handling]
+- Low: [Tests for utility functions and formatting]
+```
+
+## Rules
+
+1. Test behavior, not implementation details
+2. Each test should verify one concept
+3. Tests should be independent — no shared mutable state between tests
+4. Avoid snapshot tests unless reviewing every change to the snapshot
+5. Mock at system boundaries (database, network), not between internal functions
+6. Every test name should read like a specification
+7. A test that never fails is as useless as a test that always fails

package/bin/cli.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+// agent-skills — thin dispatcher into the LLM-driven guided setup.
+//
+// Three commands:
+//   init     materialize the package, detect the coding agent, hand off to /setup
+//   doctor   deterministic preflight scan (broken symlinks, stale persona refs)
+//   update   refresh the package, then hand off to /setup for the version-diff
+//
+// The CLI itself never decides which skills to install or what to overwrite —
+// that is the job of the guided-workspace-setup skill, run by the user's
+// coding agent. We just put the source files where the agent can find them
+// and print the next-step command.
+
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout, exit } from "node:process";
+
+import { runDoctor } from "./lib/doctor.js";
+import { detectAgent, agentLabel, AGENTS } from "./lib/detect-agent.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(__dirname, "..");
+const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
+
+// ── argv parsing ──────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+
+if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+  printHelp();
+  exit(0);
+}
+if (sub === "--version" || sub === "-v" || sub === "version") {
+  console.log(pkg.version);
+  exit(0);
+}
+
+const parsed = (() => {
+  try {
+    return parseArgs({
+      args: argv.slice(1),
+      allowPositionals: true,
+      options: {
+        agent:     { type: "string" },
+        method:    { type: "string" },
+        workspace: { type: "string" },
+        yes:       { type: "boolean", short: "y" },
+        "dry-run": { type: "boolean" },
+        launch:    { type: "boolean" },
+        help:      { type: "boolean", short: "h" },
+      },
+    });
+  } catch (err) {
+    fail(err.message);
+  }
+})();
+
+const opts = parsed.values;
+const workspace = resolve(opts.workspace ?? process.cwd());
+
+if (opts.help) {
+  printHelp(sub);
+  exit(0);
+}
+
+// ── dispatch ──────────────────────────────────────────────────────────────
+
+switch (sub) {
+  case "init":    await cmdInit();    break;
+  case "doctor":  await cmdDoctor();  break;
+  case "update":  await cmdUpdate();  break;
+  default:        fail(`unknown command: ${sub}\n\nRun "agent-skills --help" for usage.`);
+}
+
+// ── commands ──────────────────────────────────────────────────────────────
+
+async function cmdInit() {
+  await mustBeDirectory(workspace, "workspace");
+
+  printBanner(`agent-skills v${pkg.version} — guided init`);
+  console.log(`Workspace: ${workspace}`);
+  console.log(`Source:    ${pkgRoot}`);
+  console.log();
+
+  const agent = await chooseAgent(opts.agent);
+  console.log(`Coding agent: ${agentLabel(agent)}`);
+
+  // The CLI doesn't write any skill / persona / command files itself —
+  // that is the job of `guided-workspace-setup` running inside the agent.
+  // What it CAN do is record the chosen agent + method as a hint the skill
+  // will pick up, and print the exact next-step command.
+  const method = opts.method ?? "copy";
+  if (!["copy", "symlink"].includes(method)) {
+    fail(`--method must be "copy" or "symlink" (got "${method}")`);
+  }
+
+  printSection("Next step");
+  printHandoff({ agent, method, workspace, source: pkgRoot, version: pkg.version });
+
+  if (opts.launch) {
+    tryLaunch(agent, workspace);
+  }
+}
+
+async function cmdDoctor() {
+  await mustBeDirectory(workspace, "workspace");
+
+  printBanner(`agent-skills v${pkg.version} — doctor scan`);
+  console.log(`Workspace: ${workspace}`);
+  console.log();
+
+  const findings = await runDoctor({ workspace, sourceRoot: pkgRoot });
+
+  if (findings.length === 0) {
+    console.log("✓ No broken symlinks or stale persona references found.");
+    exit(0);
+  }
+
+  console.log(`Found ${findings.length} issue(s):\n`);
+  console.log(formatFindingsTable(findings));
+  console.log();
+
+  if (opts["dry-run"]) {
+    console.log("(--dry-run set: no fixes applied)");
+    exit(0);
+  }
+
+  const apply = opts.yes
+    ? true
+    : await confirm("Apply the suggested fixes now? [y/N] ");
+
+  if (!apply) {
+    console.log("No changes made. Re-run without --dry-run to apply.");
+    exit(0);
+  }
+
+  const { repaired, deleted, skipped } = await runDoctor({
+    workspace,
+    sourceRoot: pkgRoot,
+    apply:      true,
+  });
+
+  console.log(
+    `\n✓ Doctor finished — repaired ${repaired}, deleted ${deleted}, skipped ${skipped}.`,
+  );
+  console.log(
+    "Re-run /setup inside your coding agent if you also want to add or remove artifacts.",
+  );
+}
+
+async function cmdUpdate() {
+  await mustBeDirectory(workspace, "workspace");
+
+  printBanner(`agent-skills v${pkg.version} — update`);
+  console.log(`Workspace: ${workspace}`);
+  console.log();
+
+  // npm itself does the package upgrade. The CLI's job here is to read the
+  // workspace's install record, surface the version delta, and tell the user
+  // to run /setup so the skill can drive the diff-aware refresh.
+  const recordPath = join(workspace, ".ai", "agent-skills-setup.md");
+  if (!existsSync(recordPath)) {
+    console.log("This workspace has no .ai/agent-skills-setup.md install record.");
+    console.log("Run `npx agent-skills init` first, then re-run `update` later.");
+    exit(1);
+  }
+
+  const recorded = readRecordedVersion(recordPath);
+  const current  = pkg.version;
+
+  if (recorded === current) {
+    console.log(`Recorded version (${recorded}) matches the installed package.`);
+    console.log("Nothing to do. To upgrade the package itself, run:");
+    console.log("  npm install -g agent-skills@latest    # global");
+    console.log("  npx agent-skills@latest update         # one-shot");
+    exit(0);
+  }
+
+  console.log(`Recorded in workspace: v${recorded ?? "(pre-versioning)"}`);
+  console.log(`Installed package:     v${current}`);
+  console.log();
+  console.log("Run /setup inside your coding agent — the guided-workspace-setup");
+  console.log("skill will detect the version delta, show the CHANGELOG between");
+  console.log("the two versions, and offer a per-artifact three-way diff before");
+  console.log("touching any file.");
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────
+
+async function chooseAgent(supplied) {
+  if (supplied) {
+    if (!AGENTS.includes(supplied)) {
+      fail(`--agent must be one of: ${AGENTS.join(", ")} (got "${supplied}")`);
+    }
+    return supplied;
+  }
+  const detected = detectAgent({ workspace, env: process.env });
+  if (detected) return detected;
+
+  console.log("Could not auto-detect your coding agent.");
+  const answer = (await prompt(
+    `Which coding agent? [${AGENTS.join("/")}] (claude-code): `,
+  )).trim() || "claude-code";
+
+  if (!AGENTS.includes(answer)) {
+    fail(`Unknown agent "${answer}". Allowed: ${AGENTS.join(", ")}`);
+  }
+  return answer;
+}
+
+function printHandoff({ agent, method, workspace, source, version }) {
+  const rel = relative(process.cwd(), workspace) || ".";
+  const lines = [
+    `agent-skills v${version} is ready.`,
+    "",
+    `Workspace:       ${rel}`,
+    `Coding agent:    ${agentLabel(agent)}`,
+    `Install method:  ${method}`,
+    `Source root:     ${source}`,
+    "",
+    "Open your coding agent in this directory and run:",
+    "",
+    `  /setup`,
+    "",
+    "The guided-workspace-setup skill will:",
+    "  • analyse the workspace",
+    "  • show grouped install menus with recommendations",
+    "  • offer project overrides",
+    "  • confirm everything before writing a single file",
+    "",
+    "Re-run `npx agent-skills doctor` any time to scan for broken symlinks.",
+  ];
+  for (const line of lines) console.log(line);
+}
+
+function tryLaunch(agent, cwd) {
+  const cmd = { "claude-code": "claude", "opencode": "opencode", "pi": "pi" }[agent];
+  if (!cmd) return;
+  console.log(`\nLaunching: ${cmd} (cwd: ${cwd})`);
+  const r = spawnSync(cmd, [], { cwd, stdio: "inherit" });
+  if (r.error) {
+    console.log(`(could not launch ${cmd}: ${r.error.message})`);
+    console.log(`Open ${cmd} manually and run /setup.`);
+  }
+}
+
+function readRecordedVersion(path) {
+  const text = readFileSync(path, "utf8");
+  const m = text.match(/^version:\s*([^\s#]+)/m);
+  return m ? m[1].trim() : null;
+}
+
+function formatFindingsTable(findings) {
+  const rows = findings.map((f, i) => [
+    String(i + 1),
+    f.path,
+    f.issue,
+    f.fix,
+  ]);
+  const headers = ["#", "Path", "Issue", "Suggested fix"];
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => r[i].length)),
+  );
+  const pad = (cells) =>
+    cells.map((c, i) => c.padEnd(widths[i])).join("  ");
+  return [
+    pad(headers),
+    pad(widths.map((w) => "─".repeat(w))),
+    ...rows.map(pad),
+  ].join("\n");
+}
+
+async function mustBeDirectory(p, label) {
+  if (!existsSync(p) || !statSync(p).isDirectory()) {
+    fail(`${label} is not a directory: ${p}`);
+  }
+}
+
+async function prompt(question) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try { return await rl.question(question); }
+  finally { rl.close(); }
+}
+
+async function confirm(question) {
+  const ans = (await prompt(question)).trim().toLowerCase();
+  return ans === "y" || ans === "yes";
+}
+
+function printBanner(text) {
+  const bar = "─".repeat(Math.min(text.length, 70));
+  console.log(`\n${text}\n${bar}`);
+}
+
+function printSection(text) {
+  console.log(`\n── ${text} ${"─".repeat(Math.max(0, 60 - text.length))}`);
+}
+
+function fail(msg) {
+  console.error(`agent-skills: ${msg}`);
+  exit(1);
+}
+
+function printHelp(sub) {
+  if (sub === "init") {
+    console.log(`agent-skills init [options]
+
+  Materialize the package and hand off to the LLM-driven /setup skill.
+
+Options:
+  --agent <claude-code|opencode|pi>   Skip the agent auto-detection
+  --method <copy|symlink>             Default install method (default: copy)
+  --workspace <path>                  Target workspace (default: cwd)
+  --launch                            Attempt to launch the coding agent after init
+  -h, --help                          Show this help
+`);
+    return;
+  }
+  if (sub === "doctor") {
+    console.log(`agent-skills doctor [options]
+
+  Scan the workspace for broken symlinks and stale persona references.
+
+Options:
+  --workspace <path>   Target workspace (default: cwd)
+  --dry-run            Show findings, do not apply fixes
+  -y, --yes            Apply all suggested fixes without prompting
+  -h, --help           Show this help
+`);
+    return;
+  }
+  if (sub === "update") {
+    console.log(`agent-skills update [options]
+
+  Read the workspace's install record and surface the version delta. The
+  actual diff-aware refresh runs inside your coding agent via /setup.
+
+Options:
+  --workspace <path>   Target workspace (default: cwd)
+  -h, --help           Show this help
+
+To upgrade the package itself first:
+  npm install -g agent-skills@latest
+  npx agent-skills@latest update
+`);
+    return;
+  }
+  console.log(`agent-skills v${pkg.version}
+
+Usage:
+  npx agent-skills <command> [options]
+
+Commands:
+  init       Materialize the package + hand off to /setup in your agent
+  doctor     Scan for broken symlinks and stale persona references
+  update     Surface the version delta + hand off to /setup for the refresh
+
+Options:
+  -v, --version    Print the package version
+  -h, --help       Print this help (or per-command help)
+
+Examples:
+  npx agent-skills init
+  npx agent-skills init --agent claude-code --method copy
+  npx agent-skills doctor --workspace ~/projects/foo
+  npx agent-skills update
+
+Docs: https://github.com/chankov/agent-skills#readme
+`);
+}

package/bin/lib/detect-agent.js

@@ -0,0 +1,37 @@
+// Agent detection — used by `agent-skills init` to pick a sensible default
+// for the coding agent. The user can always override with --agent.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export const AGENTS = ["claude-code", "opencode", "pi"];
+
+const LABELS = {
+  "claude-code": "Claude Code",
+  "opencode":    "OpenCode",
+  "pi":          "pi",
+};
+
+export function agentLabel(agent) {
+  return LABELS[agent] ?? agent;
+}
+
+// Detection precedence:
+//   1. Explicit env vars from the coding agent runtime
+//   2. Workspace directory hints (.claude/ / .opencode/ / .pi/)
+//   3. Null — let the caller prompt
+export function detectAgent({ workspace, env = process.env } = {}) {
+  // 1. Env-based detection. Any agent that injects its own env var wins.
+  if (env.CLAUDECODE === "1" || env.CLAUDE_CODE_ENTRYPOINT) return "claude-code";
+  if (env.OPENCODE === "1" || env.OPENCODE_VERSION)         return "opencode";
+  if (env.PI === "1" || env.PI_SESSION_ID)                  return "pi";
+
+  // 2. Workspace hints. Only one match → pick it; multiple → don't guess.
+  if (!workspace) return null;
+  const hits = [];
+  if (existsSync(join(workspace, ".claude"))) hits.push("claude-code");
+  if (existsSync(join(workspace, ".opencode"))) hits.push("opencode");
+  if (existsSync(join(workspace, ".pi"))) hits.push("pi");
+
+  return hits.length === 1 ? hits[0] : null;
+}