@dtlabs/ai-toolkit 0.10.1 → 0.11.0

package/docs/installation.md

@@ -13,7 +13,8 @@ No authentication setup required — it is a public package.
 
 ### Local installation (default)
 
-Copies `.claude/`, `docs/`, and `CLAUDE.md` into the current directory:
+Copies all asset categories from the toolkit's `src/claude/` tree into the target project's `.claude/`
+directory, plus `docs/` and `CLAUDE.md`:
 
 ```bash
 npx @dtlabs/ai-toolkit
@@ -31,9 +32,15 @@ Overwrite existing files without confirmation:
 npx @dtlabs/ai-toolkit --local . --force
 ```
 
+Preview what would change without writing any files (dry run):
+
+```bash
+npx @dtlabs/ai-toolkit --local . --dry-run
+```
+
 ### Global installation
 
-Merges `.claude/agents`, `.claude/skills`, `.claude/commands`, `docs/`, and `CLAUDE.md` into `~/.claude/`:
+Merges all asset categories into `~/.claude/<category>/`, plus `docs/` and `CLAUDE.md`:
 
 ```bash
 npm install -g @dtlabs/ai-toolkit
@@ -46,20 +53,79 @@ Force overwrite:
 ai-toolkit --global --force
 ```
 
+Preview the global install without writing any files:
+
+```bash
+ai-toolkit --global --dry-run
+```
+
+### Asset catalog
+
+The installer derives the list of installable directories from the **asset catalog**
+(`lib/asset-catalog.js`). Each catalog entry defines:
+
+| Field | Description |
+|---|---|
+| `name` | Category name (e.g. `agents`, `skills`) |
+| `sourceDir` | Location inside the package (`src/claude/<name>`) |
+| `runtimeDir` | Destination inside the installed `.claude/` folder (`.claude/<name>`) |
+
+Adding a new category to the catalog automatically includes it in every install — no
+changes to `bin/cli.js` are required.
+
 ### What gets copied where
 
 | Mode | Source (in package) | Destination |
 |---|---|---|
-| Local | `.claude/` | `<target>/.claude/` |
+| Local | `src/claude/agents/` | `<target>/.claude/agents/` |
+| Local | `src/claude/skills/` | `<target>/.claude/skills/` |
+| Local | `src/claude/commands/` | `<target>/.claude/commands/` |
+| Local | `src/claude/workflows/` | `<target>/.claude/workflows/` |
+| Local | `src/claude/scripts/` | `<target>/.claude/scripts/` |
 | Local | `docs/` | `<target>/docs/` |
 | Local | `CLAUDE.md` | `<target>/CLAUDE.md` |
-| Global | `.claude/agents/` | `~/.claude/agents/` |
-| Global | `.claude/skills/` | `~/.claude/skills/` |
-| Global | `.claude/commands/` | `~/.claude/commands/` |
+| Global | `src/claude/agents/` | `~/.claude/agents/` |
+| Global | `src/claude/skills/` | `~/.claude/skills/` |
+| Global | `src/claude/commands/` | `~/.claude/commands/` |
+| Global | `src/claude/workflows/` | `~/.claude/workflows/` |
+| Global | `src/claude/scripts/` | `~/.claude/scripts/` |
 | Global | `docs/` | `~/.claude/docs/` |
-| Global | `CLAUDE.md` | `~/.claude/CLAUDE.md` |
+| Global | `CLAUDE.global.md` | `~/.claude/CLAUDE.md` |
+
+> The toolkit sources assets from `src/claude/` (versioned, purity-guarded), not from
+> `.claude/` at the project root. The `.claude/` folder in the toolkit repository is for
+> personal configuration only (gitignored).
 
-> The asymmetry is intentional: locally you mirror the package layout, globally you merge into Claude Code's standard folder structure.
+---
+
+## Upgrade path
+
+When a newer version of the toolkit is installed over an existing one, the installer
+automatically detects and removes **orphaned files** — files that were part of a previous
+installation but no longer exist in the current package.
+
+Orphaned files are moved to `.claude/.ai-toolkit-trash/<timestamp>/` rather than
+deleted outright, so they can be recovered if needed. Each upgrade session uses a
+unique ISO-timestamp subdirectory, ensuring that repeated upgrades never overwrite
+previously trashed files.
+
+The manifest (`.claude/.ai-toolkit-manifest.json`) is updated after each install to
+reflect the current file set. The trash directory is excluded from the manifest automatically.
+
+---
+
+## Developer workflow
+
+When developing the toolkit itself, use the convenience scripts in `package.json`:
+
+```bash
+# Preview global install without writing files
+npm run toolkit:dev-install-global
+# (this runs --global --dry-run first, then --global)
+
+# Validate that no test files have crept into src/claude/
+npm run toolkit:validate-purity
+```
 
 ---
 

package/docs/reference.md

@@ -41,7 +41,7 @@ Cheatsheet of every skill, command, agent, and procedure shipped with this toolk
 
 ---
 
-## Skills (in `.claude/skills/`)
+## Skills (in `src/claude/skills/`, installed to `.claude/skills/`)
 
 Invoked as `/<name>`. Comprehensive workflows that may chain multiple agents.
 
@@ -68,7 +68,7 @@ Invoked as `/<name>`. Comprehensive workflows that may chain multiple agents.
 
 ---
 
-## Commands (in `.claude/commands/`)
+## Commands (in `src/claude/commands/`, installed to `.claude/commands/`)
 
 Invoked as `/<name>`. Lightweight shortcuts focused on the current state of the repo. Do **not** spawn long-running workflows.
 
@@ -89,7 +89,7 @@ Invoked as `/<name>`. Lightweight shortcuts focused on the current state of the
 
 ---
 
-## Agents (in `.claude/agents/`)
+## Agents (in `src/claude/agents/`, installed to `.claude/agents/`)
 
 Invoked via the Agent tool with `subagent_type`. Specialised sub-conversations that produce a single deliverable.
 
@@ -160,6 +160,52 @@ Reusable text procedures referenced by agents. **Override locally** by placing a
 
 ---
 
+## CLI Commands (`ai-toolkit <command>`)
+
+The `ai-toolkit` binary (from `bin/cli.js`) provides commands for runtime asset resolution, script execution, and diagnostics.
+
+### Asset resolution
+
+| Command | Purpose | Exit |
+|---|---|---|
+| `ai-toolkit resolve-asset <relativePath> [--project <dir>] [--home <dir>]` | Resolve a runtime asset path using the six-phase algorithm; stdout=resolved path | 0 success / 1 error |
+| `ai-toolkit run-asset <relativePath> [--project <dir>] [--home <dir>] [-- ...args]` | Resolve and execute a `scripts/*.js` asset; propagates exit code | script exit code |
+| `ai-toolkit list-assets [--category <name>] [--format json\|plain] [--project <dir>] [--home <dir>]` | List installed runtime assets from `.claude/<category>/`; exit 0 even when empty | 0 always |
+| `ai-toolkit doctor-resolution [--project <dir>] [--home <dir>]` | Doctor resolution diagnostics: reports presence mode, install mode, version, completeness gaps | 0 / 1 |
+| `ai-toolkit validate-purity [<sourceDir>]` | Check that `src/claude/` contains no test or fixture files | 0 clean / 1 violations |
+
+### `resolveClaudeRuntimeAsset(relativePath, options)` — resolver API
+
+The core runtime resolution algorithm exposed from `bin/cli.js`:
+
+```javascript
+const { resolveClaudeRuntimeAsset } = require('@dtlabs/ai-toolkit/bin/cli');
+const resolvedPath = resolveClaudeRuntimeAsset('agents/developer-backend.md', {
+  projectDir: '/path/to/project',   // optional; defaults to process.cwd()
+  home: '/path/to/home',            // optional; defaults to os.homedir()
+});
+```
+
+Six-phase algorithm:
+- **Phase 0**: Input validation (relativePath must be a non-empty string)
+- **Phase A**: Presence detection — checks manifest (condA), version stamp (condB), payload files (condC)
+- **Phase B**: Mode decision — local (project `.claude/`) vs global (`~/.claude/`)
+- **Phase C**: Metadata warnings (version stamp missing, mode ambiguity)
+- **Phase D**: Completeness check — verifies requested file exists, validates catalog membership
+- **Phase E**: Return resolved absolute path with confinement check
+
+### Doctor resolution
+
+`ai-toolkit doctor-resolution` reports the full resolution diagnosis for a project:
+- Detected presence mode (manifest / stamp / payload / none)
+- Install mode (local / global)
+- Installed version
+- Catalog completeness gaps (files present in asset catalog but missing from runtime)
+
+Used by workflow agents to verify installation via doctor resolution before dispatching asset-dependent tasks.
+
+---
+
 ## Typical flows
 
 ### Flow 1 — Brand new feature, end-to-end
@@ -217,12 +263,14 @@ Then delegate manually to the suggested agent, or rerun `/implement-feature` to
 
 ## File locations
 
-| What | Local install | Global install |
-|---|---|---|
-| Agents | `<project>/.claude/agents/` | `~/.claude/agents/` |
-| Skills | `<project>/.claude/skills/` | `~/.claude/skills/` |
-| Commands | `<project>/.claude/commands/` | `~/.claude/commands/` |
-| Procedures | `<project>/docs/procedures/` | `~/.claude/docs/procedures/` |
-| Feature docs | `<project>/docs/features/FTR-NNN-slug/` | — |
-| Assessment docs | `<project>/docs/assessments/ASSESS-NNN/` | — |
-| This reference | `<project>/docs/reference.md` | `~/.claude/docs/reference.md` |
+| What | Source (toolkit repo) | Local install | Global install |
+|---|---|---|---|
+| Agents | `src/claude/agents/` | `<project>/.claude/agents/` | `~/.claude/agents/` |
+| Skills | `src/claude/skills/` | `<project>/.claude/skills/` | `~/.claude/skills/` |
+| Commands | `src/claude/commands/` | `<project>/.claude/commands/` | `~/.claude/commands/` |
+| Workflows | `src/claude/workflows/` | `<project>/.claude/workflows/` | `~/.claude/workflows/` |
+| Scripts | `src/claude/scripts/` | `<project>/.claude/scripts/` | `~/.claude/scripts/` |
+| Procedures | `docs/procedures/` | `<project>/docs/procedures/` | `~/.claude/docs/procedures/` |
+| Feature docs | — | `<project>/docs/features/FTR-NNN-slug/` | — |
+| Assessment docs | — | `<project>/docs/assessments/ASSESS-NNN/` | — |
+| This reference | `docs/reference.md` | `<project>/docs/reference.md` | `~/.claude/docs/reference.md` |

package/lib/asset-catalog.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const ASSET_CATEGORIES = [
+  {
+    name: 'agents',
+    sourceDir: 'src/claude/agents',
+    runtimeDir: '.claude/agents',
+    description: 'Agent definition files (.md with YAML frontmatter)',
+  },
+  {
+    name: 'commands',
+    sourceDir: 'src/claude/commands',
+    runtimeDir: '.claude/commands',
+    description: 'Slash command definition files',
+  },
+  {
+    name: 'skills',
+    sourceDir: 'src/claude/skills',
+    runtimeDir: '.claude/skills',
+    description: 'User-invocable skill directories with SKILL.md',
+  },
+  {
+    name: 'workflows',
+    sourceDir: 'src/claude/workflows',
+    runtimeDir: '.claude/workflows',
+    description: 'Claude Code Workflow orchestrator scripts (.js)',
+  },
+  {
+    name: 'scripts',
+    sourceDir: 'src/claude/scripts',
+    runtimeDir: '.claude/scripts',
+    description: 'Utility and helper scripts',
+  },
+];
+
+function getAssetCategories() {
+  return ASSET_CATEGORIES;
+}
+
+function getCategoryByName(name) {
+  return ASSET_CATEGORIES.find(cat => cat.name === name);
+}
+
+if (require.main === module) {
+  console.log(JSON.stringify(ASSET_CATEGORIES, null, 2));
+} else {
+  module.exports = {
+    ASSET_CATEGORIES,
+    getAssetCategories,
+    getCategoryByName,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",
@@ -8,12 +8,8 @@
     "CHANGELOG.md",
     "README.md",
     "CLAUDE.global.md",
-    ".claude/agents",
-    ".claude/commands",
-    ".claude/workflows",
-    ".claude/skills",
-    ".claude/scripts/*.js",
-    ".claude/scripts/.gitkeep",
+    "src/claude",
+    "lib",
     "bin"
   ],
   "bin": {
@@ -21,7 +17,13 @@
   },
   "scripts": {
     "prepublishOnly": "npm pack --dry-run",
+    "prepack": "node bin/cli.js validate-purity",
+    "toolkit:validate-purity": "node bin/cli.js validate-purity",
+    "toolkit:dev-install-global": "node bin/cli.js --global --dry-run && node bin/cli.js --global && node bin/cli.js doctor resolution && node bin/cli.js verify-install",
     "test": "jest --bail",
+    "test:cli": "jest --bail --testPathPattern=tests/cli/",
+    "test:frontmatter": "jest --bail --testPathPattern=tests/frontmatter/",
+    "test:regression": "jest --bail --testPathPattern=tests/regression/",
     "test:coverage": "jest --coverage"
   },
   "devDependencies": {

package/{.claude → src/claude}/agents/install-toolkit.md

@@ -6,7 +6,7 @@ model: sonnet
 
 # Install Toolkit
 
-Copies the toolkit's agents, skills, commands, and procedures into a destination project so it can use `/implement-feature`, `/init-agents`, all developer agents, and all slash commands without needing the toolkit repo locally.
+Installs the ai-toolkit into a destination project so it can use `/implement-feature`, `/init-agents`, all developer agents, and all slash commands without needing the toolkit repo locally.
 
 ---
 
@@ -15,130 +15,57 @@ Copies the toolkit's agents, skills, commands, and procedures into a destination
 The user provides:
 1. **Path to the destination project root** (optional) — defaults to the current working directory if not specified
 2. **`--force`** flag (optional) — overwrite files that already exist in the destination
+3. **`--global`** flag (optional) — install into the global Claude Code config directory (`~/.claude/`) instead of a project
 
 ---
 
-## Step 1 — Validate inputs and check version
-
-1. Determine the **toolkit root**: the current working directory (this agent runs from the toolkit repo).
-2. Verify the toolkit root contains `.claude/agents/` — if not, abort: "Error: must be run from the ai-toolkit directory."
-3. Verify the destination path exists — if not, abort: "Error: destination path not found: {path}"
-4. Check if destination is a git repository (look for `.git/`) — warn if not, but continue.
-5. **Version check**:
-   - Read `package.json` from the toolkit root to get the current version (e.g. `0.2.0`)
-   - Check if `.claude/.ai-toolkit-version` exists in the destination:
-     - **File missing** → first install, no prompt needed, continue
-     - **Same version** → inform the user and ask: "Toolkit v{x} is already installed. Re-install anyway?"
-       - If No: abort cleanly
-     - **Different version** → show both versions and ask:
-       ```
-       Version check:
-         Installed : v{installed}
-         Available : v{current}
-
-       Proceed and update from v{installed} to v{current}?
-       ```
-       - If No: abort cleanly with "Your current installation was not changed."
+## Step 1 — Validate inputs
 
----
-
-## Step 2 — Plan what to copy
-
-Six source directories to install:
-
-| Source (toolkit) | Destination | Purpose |
-|------------------|-------------|---------|
-| `.claude/agents/` | `{dest}/.claude/agents/` | All spawnable subagents |
-| `.claude/skills/` | `{dest}/.claude/skills/` | All user-invocable skills (except `install-toolkit/`) |
-| `.claude/commands/` | `{dest}/.claude/commands/` | All slash commands |
-| `.claude/workflows/` | `{dest}/.claude/workflows/` | Claude Code Workflow scripts for orchestrated pipelines |
-| `.claude/scripts/` | `{dest}/.claude/scripts/` | CLI scripts for work breakdown validation and rendering |
-| `docs/procedures/` | `{dest}/docs/procedures/` | Generic procedures (only if destination has no override) |
-
-For each file, compare source content against destination using an MD5/hash check and determine status:
-- **NEW** — file does not exist in destination → copy automatically, no prompt
-- **SAME** — file exists and content is identical → skip silently, no prompt
-- **MODIFIED** — file exists but content differs → show to user, ask per-file
-
-Build and display the plan before executing:
-
-```
-📦 Install Plan  →  {destination}
-──────────────────────────────────────────────────
-.claude/agents/
-  ✅ NEW       generate-requirements.md
-  ⚠️  MODIFIED  developer-backend.md    ← content differs
-  ⏭  SAME      review-solution.md
-
-.claude/skills/
-  ✅ NEW       implement-feature/SKILL.md
-  ⏭  SAME      init-agents/SKILL.md
-
-.claude/workflows/
-  ✅ NEW       pm-phase1.js
-  ✅ NEW       pm-phase2.js
-  ✅ NEW       pm-phase3.js
-  ✅ NEW       am-phase1.js
-  ✅ NEW       am-phase2.js
-
-.claude/scripts/
-  ✅ NEW       wb-validate.js
-  ✅ NEW       wb-render.js
-
-docs/procedures/
-  ✅ NEW       code-generation.md
-  ⏭  SAME      testing.md
-──────────────────────────────────────────────────
-New: N  |  Modified: N  |  Unchanged: N
-```
+1. Determine destination:
+   - If `--global` was passed: destination is `~/.claude/` (user-global config dir)
+   - Otherwise: destination is the path provided, or the current working directory if omitted
+2. Verify the destination path exists — if not, abort: "Error: destination path not found: {path}"
+3. Check if destination is a git repository (look for `.git/`) — warn if not, but continue.
 
 ---
 
-## Step 3 — Execute
-
-**Phase A — New files** (no prompt needed): copy all NEW files, creating directories as needed.
+## Step 2 — Run installer
 
-**Phase B — Modified files** (per-file prompt):
+Invoke the ai-toolkit CLI installer. The CLI handles source resolution (no CWD assumption), version checking, asset catalog enumeration, and file copy:
 
-For each MODIFIED file, show:
-```
-  ⚠️  MODIFIED: .claude/agents/developer-backend.md
-  The toolkit version differs from the one already in your project.
-  Overwrite? (y/N):
+```bash
+ai-toolkit install --project "{dest}"   # for a project install
+# or
+ai-toolkit install --global             # for a global install
 ```
 
-Wait for the user's response before moving to the next file. If `--force` was passed, overwrite all modified files without prompting.
-
-**Phase C — Same files**: skip silently (no output for these).
-
-Use shell commands appropriate for the OS. On Windows with bash:
+If `--force` was passed:
 ```bash
-mkdir -p "{dest_dir}"
-cp "{source_file}" "{dest_file}"
+ai-toolkit install --project "{dest}" --force
 ```
 
-**Never copy the `install-toolkit/` skill directory** — this skill is toolkit-internal and has no use in a destination project.
+The installer will:
+- Compare installed version vs available version and ask for confirmation if already installed at the same version
+- Enumerate all installable assets from the asset catalog (`src/claude/`)
+- Copy NEW files automatically; prompt for MODIFIED files (or overwrite silently if `--force`)
+- Skip SAME files silently
+- Never copy `install-toolkit` skill or `settings.json` / `settings.local.json`
+- Never clobber `docs/procedures/` overrides that exist in the destination
+- Stamp the installed version in `{dest}/.claude/.ai-toolkit-version`
 
-**Never copy `.claude/settings.json` or `.claude/settings.local.json`** — these are user-owned configuration. Copying them would clobber the destination's existing settings. The toolkit's own `settings.json` exists only to configure this repo; it is verified and advised on (Step 4b), never installed.
-
-**For `docs/procedures/`**: copy only files that don't already exist in the destination (regardless of `--force`) — project-specific procedure overrides must never be clobbered.
+Show the installer's output to the user without modification.
 
 ---
 
-## Step 4 — Verify and stamp version
+## Step 3 — Verify result
 
-After copying:
-1. Verify all expected files are present in the destination
-2. Verify no files are zero bytes
-3. Write the installed version to `.claude/.ai-toolkit-version` in the destination:
-   ```bash
-   echo "{current_version}" > "{dest}/.claude/.ai-toolkit-version"
-   ```
-   This file is read on future installs to show the version comparison prompt.
+After the installer exits:
+1. Confirm exit code was 0 — if non-zero, report the error and stop
+2. Verify `.claude/.ai-toolkit-version` was written in the destination
 
 ---
 
-## Step 4b — Verify subagent spawn depth (verify & advise ONLY — never write)
+## Step 4 — Verify subagent spawn depth (verify & advise ONLY — never write)
 
 The orchestrated pipelines (`/implement-feature`, `/assess-codebase`) require the
 environment variable `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` to be set to `2` or higher.

package/{.claude → src/claude}/workflows/am-phase1.js

@@ -2,7 +2,7 @@ export const meta = {
   name: 'am-phase1',
   description: 'Assessment pipeline phase 1: discover assessment agents → scope filter → parallel assessment → intervention-documentation-standard → Token-Estimate → Effort-Estimate → findings_gate_payload.',
   phases: [
-    { title: 'Discovery',      detail: 'Scan .claude/agents/ for assessment agents, apply scope filter' },
+    { title: 'Discovery',      detail: 'Run ai-toolkit list-assets --category agents --format json, apply scope filter' },
     { title: 'Assessment',     detail: 'Dispatch all assessment agents in parallel' },
     { title: 'Interventions',  detail: 'Run intervention-documentation-standard on all findings' },
     { title: 'Estimates',      detail: 'Write Token-Estimate and Effort-Estimate files' },
@@ -66,17 +66,14 @@ const SCOPE_AGENT_MAP = {
 }
 
 const discovery = await agent(
-  `Scan .claude/agents/ and list all assessment agents.
-
-An assessment agent is a .md file whose name or description contains one of: "assessment", "audit", "analysis".
-Exclude orchestrators (files containing "manager" in their name).
-Exclude remediation-only agents (files containing "refactoring", "hardening", "decomposition" in their name UNLESS they also contain "assessment" or "audit").
-
-For each matching agent, read its frontmatter and extract:
-- name (from the name: field in frontmatter)
-- description (from the description: field)
-
-Return { "assessment_agents": [ { "name": "...", "description": "..." }, ... ] }`,
+  `Run this command and parse its output:\n` +
+  `ai-toolkit list-assets --category agents --format json\n\n` +
+  `The command outputs a JSON array of installed agent file paths (e.g. [".claude/agents/foo.md", ...]).\n` +
+  `For each path in the array, read the file and extract the YAML frontmatter fields: name, description.\n\n` +
+  `An assessment agent is one whose file name or description contains one of: "assessment", "audit", "analysis".\n` +
+  `Exclude orchestrators (files containing "manager" in their name).\n` +
+  `Exclude remediation-only agents (files containing "refactoring", "hardening", "decomposition" in their name UNLESS they also contain "assessment" or "audit").\n\n` +
+  `Return { "assessment_agents": [ { "name": "...", "description": "..." }, ... ] }`,
   {
     label:  'discover-assessment-agents',
     phase:  'Discovery',

package/{.claude → src/claude}/workflows/pm-phase2.js

@@ -138,7 +138,7 @@ const beforeValidate = budget.spent()
 try {
   const validateWrapper = await agent(
     `Run this command and return the result as structured output:\n` +
-    `node .claude/scripts/wb-validate.js "${featureDir}/${prefix}-Work-Breakdown.json" "${featureDir}/${prefix}-Requirements.md"\n\n` +
+    `ai-toolkit run-asset scripts/wb-validate.js -- "${featureDir}/${prefix}-Work-Breakdown.json" "${featureDir}/${prefix}-Requirements.md"\n\n` +
     `Capture exitCode (integer), stdout (string), stderr (string). Return all three.`,
     {
       label:  'wb-validate',
@@ -253,7 +253,7 @@ if (!canRender) {
   try {
     renderResult = await agent(
       `Run this command and return the result as structured output:\n` +
-      `node .claude/scripts/wb-render.js "${featureDir}/${prefix}-Work-Breakdown.json" "${prefix}"\n\n` +
+      `ai-toolkit run-asset scripts/wb-render.js -- "${featureDir}/${prefix}-Work-Breakdown.json" "${prefix}"\n\n` +
       `Capture exitCode (integer), stdout (string), stderr (string).\n` +
       `Resolve the expected output paths:\n` +
       `  markdownPath = "${featureDir}/${prefix}-Work-Breakdown.md"\n` +