@chankov/agent-skills 0.1.0

package/bin/lib/doctor.js

@@ -0,0 +1,209 @@
+// Doctor scan — deterministic preflight extracted from
+// guided-workspace-setup Step 5. Both `agent-skills doctor` (CLI) and the
+// `/doctor` slash command call into this so behaviour cannot drift.
+//
+// Two classes of findings:
+//   1. Broken symlinks — links whose source has been moved, renamed, or deleted
+//   2. Stale persona refs — YAML configs (teams.yaml, agent-chain.yaml) that
+//      still name a persona which no longer exists in the source tree
+//
+// For each broken link we look up a canonical replacement in the source
+// `agents/` or `skills/` tree (many breakages are stale names from the
+// pre-merge layout, e.g. `reviewer` → `code-reviewer`).
+
+import { readdirSync, readlinkSync, existsSync, lstatSync, statSync, unlinkSync, symlinkSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname, basename, relative, isAbsolute } from "node:path";
+
+// Known canonical replacements for personas renamed during the merge.
+const PERSONA_RENAMES = {
+  "reviewer":      "code-reviewer",
+  "red-team":      "security-auditor",
+  "tester":        "test-engineer",
+  "qa":            "test-engineer",
+};
+
+// Install-target directories the scanner walks, when present.
+const TARGET_DIRS = [
+  // Personas
+  "agents",
+  ".claude/agents",
+  ".opencode/agents",
+  ".codex/agents",
+  ".gemini/agents",
+  ".github/agents",
+  ".pi/agents",
+  ".pi/agents/pi-pi",
+  // Skills
+  ".claude/skills",
+  ".opencode/skills",
+  ".pi/skills",
+  ".agents/skills",
+  // Commands / prompts
+  ".claude/commands",
+  ".opencode/commands",
+  ".pi/prompts",
+  // References + hooks
+  ".claude/references",
+  ".claude/hooks",
+];
+
+// YAML configs that may reference persona names.
+const YAML_REFS = [
+  ".pi/agents/teams.yaml",
+  ".pi/agents/agent-chain.yaml",
+];
+
+/**
+ * Run the doctor scan.
+ *
+ * @param {object} opts
+ * @param {string} opts.workspace  Workspace root (absolute path)
+ * @param {string} opts.sourceRoot agent-skills source root (absolute path)
+ * @param {boolean} [opts.apply]   If true, apply suggested fixes; otherwise just report
+ * @returns {Array|object}         Findings array (apply=false) or {repaired,deleted,skipped} (apply=true)
+ */
+export async function runDoctor({ workspace, sourceRoot, apply = false }) {
+  const findings = [];
+
+  // 1. Broken symlinks in install-target directories.
+  for (const rel of TARGET_DIRS) {
+    const dir = join(workspace, rel);
+    if (!existsSync(dir)) continue;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); }
+    catch { continue; }
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      let lst;
+      try { lst = lstatSync(fullPath); } catch { continue; }
+      if (!lst.isSymbolicLink()) continue;
+
+      // Resolve where the link points.
+      const linkTarget = readlinkSync(fullPath);
+      const absTarget = isAbsolute(linkTarget)
+        ? linkTarget
+        : resolve(dirname(fullPath), linkTarget);
+
+      if (existsSync(absTarget)) continue; // healthy link
+
+      const replacement = findReplacement({
+        brokenName: entry.name,
+        kind:       inferKind(rel),
+        sourceRoot,
+      });
+
+      findings.push({
+        type: "broken-symlink",
+        path: relative(workspace, fullPath),
+        issue: `broken symlink → missing ${relative(workspace, absTarget)}`,
+        fix: replacement
+          ? `repoint to ${relative(workspace, join(sourceRoot, replacement))}`
+          : "delete",
+        replacement,
+        absPath: fullPath,
+      });
+    }
+  }
+
+  // 2. Stale persona refs in YAML configs.
+  for (const rel of YAML_REFS) {
+    const file = join(workspace, rel);
+    if (!existsSync(file)) continue;
+    const text = readFileSync(file, "utf8");
+    for (const [stale, canonical] of Object.entries(PERSONA_RENAMES)) {
+      // Match the persona name as a *standalone token* — bounded by
+      // start-of-line, whitespace, quotes, or a YAML separator (:, [, ], ,).
+      // Crucially, "-" must NOT count as a boundary, or we'd match
+      // "reviewer" inside "code-reviewer".
+      const re = new RegExp(
+        `(^|[\\s'"\\[\\],:])${escapeRe(stale)}(?=[\\s'"\\[\\],:]|$)`,
+        "gm",
+      );
+      if (re.test(text)) {
+        findings.push({
+          type: "stale-yaml-ref",
+          path: relative(workspace, file),
+          issue: `references "${stale}"`,
+          fix: `rename to "${canonical}"`,
+          stale,
+          canonical,
+          absPath: file,
+        });
+      }
+    }
+  }
+
+  if (!apply) return findings;
+
+  // ── Apply ──────────────────────────────────────────────────────────────
+  let repaired = 0, deleted = 0, skipped = 0;
+
+  for (const f of findings) {
+    try {
+      if (f.type === "broken-symlink") {
+        if (f.replacement) {
+          const newTarget = join(sourceRoot, f.replacement);
+          unlinkSync(f.absPath);
+          symlinkSync(newTarget, f.absPath);
+          repaired++;
+        } else {
+          unlinkSync(f.absPath);
+          deleted++;
+        }
+      } else if (f.type === "stale-yaml-ref") {
+        const text = readFileSync(f.absPath, "utf8");
+        const re = new RegExp(
+          `(^|[\\s'"\\[\\],:])${escapeRe(f.stale)}(?=[\\s'"\\[\\],:]|$)`,
+          "gm",
+        );
+        writeFileSync(f.absPath, text.replace(re, `$1${f.canonical}`));
+        repaired++;
+      }
+    } catch (err) {
+      skipped++;
+      console.error(`  ⚠ skipped ${f.path}: ${err.message}`);
+    }
+  }
+
+  return { repaired, deleted, skipped, findings };
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function inferKind(targetDir) {
+  if (targetDir.includes("agents")) return "agents";
+  if (targetDir.includes("skills")) return "skills";
+  if (targetDir.includes("commands") || targetDir.includes("prompts")) return "commands";
+  if (targetDir.includes("references")) return "references";
+  if (targetDir.includes("hooks")) return "hooks";
+  return null;
+}
+
+function findReplacement({ brokenName, kind, sourceRoot }) {
+  // Strip .md if present so we can compare bare names.
+  const bare = brokenName.replace(/\.md$/, "");
+
+  // First check the known-renames map.
+  const renamed = PERSONA_RENAMES[bare];
+  if (renamed) {
+    const candidate = kind === "skills"
+      ? join("skills", renamed, "SKILL.md")
+      : join("agents", `${renamed}.md`);
+    if (existsSync(join(sourceRoot, candidate))) return candidate;
+  }
+
+  // Fall back: same name in the canonical source tree.
+  if (kind === "agents") {
+    const candidate = join("agents", `${bare}.md`);
+    if (existsSync(join(sourceRoot, candidate))) return candidate;
+  }
+  if (kind === "skills") {
+    const candidate = join("skills", bare, "SKILL.md");
+    if (existsSync(join(sourceRoot, candidate))) return candidate;
+  }
+
+  return null;
+}

package/bin/snapshot-version.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// snapshot-version.js
+//
+// Copy every shipped artifact into .versions/<x.y.z>/ so a later install can
+// run a three-way diff between:
+//   - source @ recorded version   ←─ this snapshot, read from the installed copy
+//   - installed copy in target    ←─ what the user has on disk
+//   - source @ current version    ←─ the active tree in this package
+//
+// Run by the release workflow right before `changeset publish`. Also runnable
+// by hand if you need to rebuild a snapshot.
+
+import { readFileSync, mkdirSync, cpSync, existsSync, rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const version = pkg.version;
+const snapDir = join(root, ".versions", version);
+
+// Paths that travel into the snapshot — matches package.json `files` for the
+// installable artifacts. We deliberately skip the meta files (README, LICENSE,
+// CHANGELOG, package.json) — the diff only cares about the artifacts.
+const ARTIFACT_PATHS = [
+  "skills",
+  "agents",
+  ".claude/commands",
+  ".opencode/commands",
+  ".pi/prompts",
+  ".pi/extensions",
+  ".pi/harnesses",
+  ".pi/skills",
+  ".pi/agents",
+  ".pi/damage-control-rules.yaml",
+  "references",
+  "hooks",
+];
+
+if (existsSync(snapDir)) {
+  console.log(`snapshot: .versions/${version}/ already exists — rebuilding`);
+  rmSync(snapDir, { recursive: true, force: true });
+}
+
+mkdirSync(snapDir, { recursive: true });
+
+// Skip nested node_modules and build artifacts — they bloat the tarball and
+// the user reinstalls them after init.
+const SKIP_NAMES = new Set(["node_modules", ".DS_Store", "dist", "build"]);
+
+for (const rel of ARTIFACT_PATHS) {
+  const src = join(root, rel);
+  if (!existsSync(src)) continue;
+  const dest = join(snapDir, rel);
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(src, dest, {
+    recursive: true,
+    filter: (srcPath) => {
+      const base = srcPath.split("/").pop();
+      return !SKIP_NAMES.has(base);
+    },
+  });
+}
+
+// Stamp the snapshot with its version so the skill can verify it loaded the right one.
+const stampPath = join(snapDir, ".version");
+const fs = await import("node:fs/promises");
+await fs.writeFile(stampPath, `${version}\n`, "utf8");
+
+console.log(`snapshot: wrote .versions/${version}/`);

package/docs/agent-skills-setup.md

@@ -0,0 +1,187 @@
+# Agent Skills — Project Files
+
+agent-skills keeps up to two small files in a project's `.ai/` directory. They
+have different readers and different lifetimes, so they are kept separate.
+
+| File | Read by | When |
+|------|---------|------|
+| `.ai/agent-skills-overrides.md` | `spec-driven-development`, `planning-and-task-breakdown`, `browser-testing-with-devtools`, `git-workflow-and-versioning` | Every run of those skills |
+| `.ai/agent-skills-setup.md` | `guided-workspace-setup` | Only when setup is run or re-run |
+
+Keep them split: the overrides file is loaded into context constantly, so it
+must stay minimal; the install record is consulted rarely, so it can be large.
+
+## The overrides file — `.ai/agent-skills-overrides.md`
+
+Some skills produce files or need facts specific to each project — where specs
+and plans are saved, how to start a dev server, whether the agent may create
+branches. Each ships a sensible **default**; a project that needs something
+different declares it here, and the skill picks it up.
+
+- **Location:** `.ai/agent-skills-overrides.md` at the project root.
+- **Format:** Markdown. One `## <skill-name>` section per skill, with terse
+  `key: value` lines. Block values use the `key: |` multi-line form. No prose
+  and no install detail — skills parse it by key and load it on every run.
+- **Commit it.** Shared project configuration belongs in version control. Make
+  sure no `.gitignore` rule (for example a broad `.env*` pattern) excludes it.
+- **No secrets.** For anything sensitive (test-account credentials), reference
+  the **name** of an environment variable; the real value lives in a gitignored
+  `.env`.
+- If the file is absent, or a skill has no section in it, the skill uses its
+  built-in default.
+
+### `spec-driven-development`
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `spec-dir` | `docs/prds/{area}` | Directory specs are written to |
+| `naming` | `PRD{n}-{topic}` | File name pattern; `{n}` = next free PRD number, `{topic}` = kebab-case slug |
+
+Default output: `docs/prds/{area}/PRD{n}-{topic}.md`.
+
+### `planning-and-task-breakdown`
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `plan-dir` | `docs/plans/{area}` | Directory plans are written to |
+| `naming` | `PLAN-{prd-name}-{phase}` | File name pattern; `{phase}` suffix only when a plan spans multiple files |
+| `todo` | `embedded` | `embedded` keeps the task list inside the plan; `separate` writes a standalone `todo.md` |
+
+Default output: `docs/plans/{area}/PLAN-{prd-name}-{phase}.md`, task list embedded.
+
+### `browser-testing-with-devtools`
+
+This skill has **no default** — the section is required for browser testing,
+because dev-server commands and login flows cannot be guessed.
+
+| Key | Meaning |
+|-----|---------|
+| `dev-server` | Command to start the local dev server |
+| `ready-check` | How to confirm the server is up |
+| `base-url` | Root URL for navigation |
+| `auth-flow` | Steps to log in (multi-line `|` block) |
+| `roles` | Test account per privilege level, referenced by env-var name |
+| `notes` | Anything else the agent should know (certs, seed data, ...) |
+
+### `git-workflow-and-versioning`
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `branching` | `never` | `never` = agent works in the current branch and never creates or switches branches; `allow` = agent may create feature branches |
+
+## The setup file — `.ai/agent-skills-setup.md`
+
+The `guided-workspace-setup` skill writes this file to record what it installed
+into the project — which skills, commands, personas, and extensions, by what
+method, and when. It reads the file on a re-run to add, update, or remove
+artifacts without reinstalling everything. No other skill loads it.
+
+| Section | Meaning |
+|---------|---------|
+| `workspace-summary` | Workspace path, coding agent, **agent-skills version**, project shape, checks discovered |
+| `install-status` | Installed artifacts, their targets, and the method (`copy` or `symlink`) |
+| `doctor-runs` | One line per doctor pass (preflight / postflight, repaired / deleted / skipped counts) |
+| `verification` | Checks confirming the install |
+
+### The `version:` line
+
+`workspace-summary` carries a `version:` line set to the package version that
+performed the install (e.g. `version: 1.4.2`). It drives the version-aware
+update flow — on every re-run, `guided-workspace-setup` compares this against
+the current package version and:
+
+1. Reads `CHANGELOG.md` between the two versions.
+2. For each installed artifact, runs a three-way diff between
+   *source@recorded*, the installed copy on disk, and *source@current*.
+3. Surfaces the result in the install menu using these `Status` values:
+
+| Status | Meaning |
+|---|---|
+| `installed · upgrade available` | Source changed upstream; user copy still matches the old source → clean refresh |
+| `installed · conflicting upgrade` | Source changed upstream AND user modified the copy → menu shows the three-way diff before overwriting |
+| `installed · removed upstream` | Artifact gone in the new version → menu proposes deletion (subject to the removal-scope rule) |
+| `not installed · new in this version` | New artifact added in the new version → menu offers it, marked `★` if recommended |
+
+The diff sources at *source@recorded* are read from the package's
+`.versions/<x.y.z>/` snapshot tree, which the release pipeline writes for every
+published version. If the snapshot is missing (e.g. an unpublished local
+build), the skill falls back to "treat installed copy as canonical" and
+prompts for an explicit baseline.
+
+### Pre-versioning workspaces
+
+A workspace whose `agent-skills-setup.md` predates the `version:` line is
+treated as "pre-versioning". On first re-run, `guided-workspace-setup` prompts
+for a clean baseline: either accept the installed artifacts as matching the
+current source (stamp the current version), or re-run the install from scratch.
+
+Commit this file if the team should share install state — keep paths relative
+so it stays portable. A self-referencing checkout (agent-skills itself) may
+instead `.gitignore` it, since its recorded paths are local to one machine.
+
+## Templates
+
+### `.ai/agent-skills-overrides.md`
+
+Copy this in and delete the sections you don't need — anything absent falls
+back to the skill default.
+
+```markdown
+# Agent Skills — Project Overrides
+#
+# Each section is applied ON TOP of the skill's built-in defaults.
+# Keys not listed keep the default. Absent file/section → pure defaults.
+
+## spec-driven-development
+spec-dir: docs/prds/{area}
+naming:   PRD{n}-{topic}
+
+## planning-and-task-breakdown
+plan-dir: docs/plans/{area}
+naming:   PLAN-{prd-name}-{phase}
+todo:     embedded
+
+## browser-testing-with-devtools
+dev-server:  <command to start the local dev server>
+ready-check: <url or check that confirms the server is up>
+base-url:    <root url>
+auth-flow: |
+  1. Navigate to <login url>
+  2. Submit credentials for the role needed by the screen under test
+roles:
+  admin:  env APP_TEST_ADMIN_USER / APP_TEST_ADMIN_PASS
+  player: env APP_TEST_PLAYER_USER / APP_TEST_PLAYER_PASS
+notes: |
+  <anything else: self-signed certs, required seed data, ...>
+
+## git-workflow-and-versioning
+branching: never
+```
+
+### `.ai/agent-skills-setup.md`
+
+Written and maintained by `guided-workspace-setup`; shown here for reference.
+
+```markdown
+# Agent Skills — Workspace Setup
+#
+# Maintained by the guided-workspace-setup skill.
+
+## workspace-summary
+agent:   claude-code
+method:  copy
+version: 1.4.2
+shape:   <one line on the project shape>
+
+## install-status
+skills:     [spec-driven-development, test-driven-development, code-review-and-quality]
+commands:   [spec, plan, build]
+personas:   [code-reviewer]
+extensions: []
+harnesses:  []
+updated:    2026-05-22
+
+## verification
+- Every recorded artifact exists at its target path.
+- No secrets are stored in this file.
+```

package/docs/copilot-setup.md

@@ -0,0 +1,94 @@
+# Using agent-skills with GitHub Copilot
+
+## Setup
+
+### Copilot Instructions
+
+Copilot supports creating agent skills using a `.github/skills`, `.claude/skills`, or `.agents/skills` directory in your repository.
+
+```bash
+mkdir -p .github
+
+# Create files for essential skills
+cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .github/skills/test-driven-development/SKILL.md
+cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md > .github/skills/code-review-and-quality/SKILL.md
+```
+
+For more details, refer [Creating agent skills for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills).
+
+### Agent Personas (agents.md)
+
+Copilot supports specialized agent personas. Use the agent-skills agents:
+
+```bash
+# Copy agent definitions — review specialists
+cp /path/to/agent-skills/agents/code-reviewer.md .github/agents/code-reviewer.md
+cp /path/to/agent-skills/agents/test-engineer.md .github/agents/test-engineer.md
+cp /path/to/agent-skills/agents/security-auditor.md .github/agents/security-auditor.md
+
+# Lifecycle specialists
+cp /path/to/agent-skills/agents/planner.md       .github/agents/planner.md
+cp /path/to/agent-skills/agents/plan-reviewer.md .github/agents/plan-reviewer.md
+cp /path/to/agent-skills/agents/builder.md       .github/agents/builder.md
+cp /path/to/agent-skills/agents/scout.md         .github/agents/scout.md
+cp /path/to/agent-skills/agents/documenter.md    .github/agents/documenter.md
+```
+
+Invoke agents in Copilot Chat:
+- `@scout Locate where auth is enforced`
+- `@planner Draft a plan for migrating users to OAuth`
+- `@plan-reviewer Critique the migration plan`
+- `@builder Implement the approved plan`
+- `@code-reviewer Review this PR`
+- `@test-engineer Analyze test coverage for this module`
+- `@security-auditor Check this endpoint for vulnerabilities`
+- `@documenter Update the README for the new endpoint`
+
+### Custom Instructions (User Level)
+
+For skills you want across all repositories:
+
+1. Open VS Code → Settings → GitHub Copilot → Custom Instructions
+2. Add your most-used skill summaries
+
+## Recommended Configuration
+
+### .github/copilot-instructions.md
+
+GitHub Copilot supports project-level instructions via `.github/copilot-instructions.md`.
+
+```markdown
+# Project Coding Standards
+
+## Testing
+- Write tests before code (TDD)
+- For bugs: write a failing test first, then fix (Prove-It pattern)
+- Test hierarchy: unit > integration > e2e (use the lowest level that captures the behavior)
+- Run `npm test` after every change
+
+## Code Quality
+- Review across five axes: correctness, readability, architecture, security, performance
+- Every PR must pass: lint, type check, tests, build
+- No secrets in code or version control
+
+## Implementation
+- Build in small, verifiable increments
+- Each increment: implement → test → verify → commit
+- Never mix formatting changes with behavior changes
+
+## Boundaries
+- Always: Run tests before commits, validate user input
+- Ask first: Database schema changes, new dependencies
+- Never: Commit secrets, remove failing tests, skip verification
+```
+
+### Specialized Agents
+
+Use the agents for targeted review workflows in Copilot Chat.
+
+## Usage Tips
+
+1. **Keep instructions concise** — Copilot instructions work best when focused. Summarize the key rules rather than including full skill files.
+2. **Use agents for review** — The code-reviewer, test-engineer, and security-auditor agents are designed for Copilot's agent model.
+3. **Reference in chat** — When working on a specific phase, paste the relevant skill content into Copilot Chat for context.
+4. **Combine with PR reviews** — Set up Copilot to review PRs using the code-reviewer agent persona.

package/docs/cursor-setup.md

@@ -0,0 +1,67 @@
+# Using agent-skills with Cursor
+
+## Setup
+
+### Option 1: Rules Directory (Recommended)
+
+Cursor supports a `.cursor/rules/` directory for project-specific rules:
+
+```bash
+# Create the rules directory
+mkdir -p .cursor/rules
+
+# Copy skills you want as rules
+cp /path/to/agent-skills/skills/test-driven-development/SKILL.md .cursor/rules/test-driven-development.md
+cp /path/to/agent-skills/skills/code-review-and-quality/SKILL.md .cursor/rules/code-review-and-quality.md
+cp /path/to/agent-skills/skills/incremental-implementation/SKILL.md .cursor/rules/incremental-implementation.md
+```
+
+Rules in this directory are automatically loaded into Cursor's context.
+
+### Option 2: .cursorrules File
+
+Create a `.cursorrules` file in your project root with the essential skills inlined:
+
+```bash
+# Generate a combined rules file
+cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .cursorrules
+echo "\n---\n" >> .cursorrules
+cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> .cursorrules
+```
+
+### Option 3: Notepads
+
+Cursor's Notepads feature lets you store reusable context. Create a notepad for each skill you use frequently:
+
+1. Open Cursor → Settings → Notepads
+2. Create a new notepad named "swe: Test-Driven Development"
+3. Paste the content of `skills/test-driven-development/SKILL.md`
+4. Reference it in chat with `@notepad swe: Test-Driven Development`
+
+## Recommended Configuration
+
+### Essential Skills (Always Load)
+
+Add these to `.cursor/rules/`:
+
+1. `test-driven-development.md` — TDD workflow and Prove-It pattern
+2. `code-review-and-quality.md` — Five-axis review
+3. `incremental-implementation.md` — Build in small verifiable slices
+
+### Phase-Specific Skills (Load as Notepads)
+
+Create notepads for skills you use contextually:
+
+- "swe: Spec Development" → `spec-driven-development/SKILL.md`
+- "swe: Frontend UI" → `frontend-ui-engineering/SKILL.md`
+- "swe: Security" → `security-and-hardening/SKILL.md`
+- "swe: Performance" → `performance-optimization/SKILL.md`
+
+Reference them with `@notepad` when working on relevant tasks.
+
+## Usage Tips
+
+1. **Don't load all skills at once** — Cursor has context limits. Load 2-3 skills as rules and keep others as notepads.
+2. **Reference skills explicitly** — Tell Cursor "Follow the test-driven-development rules for this change" to ensure it reads the loaded rules.
+3. **Use agents for review** — Copy `agents/code-reviewer.md` content and tell Cursor to "review this diff using this code review framework." The full set under `agents/` (`code-reviewer`, `test-engineer`, `security-auditor`, `planner`, `plan-reviewer`, `builder`, `scout`, `documenter`) can be loaded the same way — the read-only ones (`code-reviewer`, `security-auditor`, `planner`, `plan-reviewer`, `scout`) declare `tools: read,bash,grep,find,ls` and explicitly will not modify files.
+4. **Load references on demand** — When working on performance, reference `@notepad performance-checklist` or paste the checklist content.