@dtlabs/ai-toolkit 0.1.7 → 0.2.1

package/.claude/workflows/pm-phase3.js

@@ -0,0 +1,309 @@
+export const meta = {
+  name: 'pm-phase3',
+  description: 'Feature delivery phase 3: implementation loop (developer agents + review-solution per US, max 2 rework cycles, git commit per US) → remediation → PR → Feature Registry → Token-Estimate actuals → Effort-Estimate actuals.',
+  phases: [
+    { title: 'Implementation', detail: 'Dispatch developer agents per work breakdown, review per US' },
+    { title: 'Remediation',    detail: 'Fix OPEN issues from Issues Register' },
+    { title: 'PR',             detail: 'Push branch, create PR, update registry' },
+    { title: 'Actuals',        detail: 'Write Token-Estimate and Effort-Estimate actuals' },
+  ],
+}
+
+// args: "<path-to-feature.md> --branch feature/FTR-NNN-slug"
+const argStr      = typeof args === 'string' ? args : ''
+const featurePath = argStr.trim().split(/\s+/)[0]
+const branchMatch = argStr.match(/--branch\s+(\S+)/)
+const branch      = branchMatch ? branchMatch[1] : null
+
+// ── Implementation ────────────────────────────────────────────────────────────
+phase('Implementation')
+
+log(`Starting implementation for ${featurePath}${branch ? ` on branch ${branch}` : ''}`)
+
+const tokenLedger  = []
+const escalations  = []
+
+// Read the Work Breakdown and execute implementation
+// A single orchestration agent handles the full implementation loop:
+// parse WB → per-phase dispatch → review per US → rework (max 2 cycles) → commit per US
+// It uses sub-tool calls (Read, Bash, etc.) to do git work and reads the WB itself.
+// It does NOT spawn further subagents — it reads files and calls Bash for git commands.
+
+const IMPL_SCHEMA = {
+  type: 'object',
+  properties: {
+    prefix:        { type: 'string' },
+    phases_done:   { type: 'number' },
+    us_passed:     { type: 'array', items: { type: 'string' } },
+    us_escalated:  { type: 'array', items: { type: 'string' } },
+    issues_path:   { type: 'string' },
+    issues_open:   { type: 'number' },
+  },
+  required: ['prefix', 'phases_done'],
+}
+
+const beforeImpl = budget.spent()
+
+const implResult = await agent(
+  `You are the implementation orchestrator for the feature delivery pipeline.
+
+Feature path: ${featurePath}
+Branch: ${branch || '(already checked out)'}
+
+Your job:
+
+1. Read {PREFIX}-Work-Breakdown.md (same directory as feature.md).
+   Extract all phases, tasks, domains, and User Story groupings from Section 4.
+
+2. For each phase in order:
+   a. Identify tasks grouped by User Story (US-XX) or INFRA.
+   b. For each group, spawn the correct developer agent:
+      - DB/BE/INFRA tasks → subagent_type: developer-backend
+      - FE tasks          → subagent_type: developer-frontend
+      - TEST tasks        → subagent_type: developer-testing
+      Prompt: "${featurePath} <comma-separated task IDs>"
+      Independent groups within a phase can be dispatched in parallel (multiple Agent calls in same response).
+   c. When ALL tasks for a User Story are done → spawn review-solution:
+      subagent_type: review-solution, prompt: "${featurePath} --scope <US-ID>"
+      - PASS (no CRITICAL): git add -A && git commit -m "feat({PREFIX}): implement {US-ID} — {title}"
+        Log WARNING/INFO findings to {PREFIX}-Issues.md.
+      - FAIL (CRITICAL): rework — re-dispatch the developer agent with the review findings appended to the prompt.
+        Max 2 rework cycles. After 2 failed cycles → escalate (add to escalations list).
+      INFRA tasks: reviewed as a group, commit: "feat({PREFIX}): implement shared infrastructure (INFRA)"
+
+3. After all phases complete:
+   - Read {PREFIX}-Issues.md if it exists. Count OPEN items.
+   - Report: prefix, phases_done, us_passed (list of US IDs that passed), us_escalated (list that escalated), issues_path, issues_open.
+
+IMPORTANT RULES:
+- Never use run_in_background: true when spawning agents.
+- Track escalations: if a US fails review after 2 rework cycles, add its ID to us_escalated and continue.
+- Partial failures are acceptable — continue with remaining phases.
+- All git commands via Bash tool.
+- Commit message format: feat({PREFIX}): implement {US-ID} — {US title}`,
+  {
+    label:  'implementation-orchestrator',
+    phase:  'Implementation',
+    schema: IMPL_SCHEMA,
+  }
+)
+
+const implTokens = budget.spent() - beforeImpl
+tokenLedger.push({ agent: 'implementation-orchestrator', model: 'sonnet', phase_delta_tokens: implTokens })
+log(`Implementation done — ${implResult.phases_done} phases, ${(implResult.us_passed || []).length} US passed, ${(implResult.us_escalated || []).length} escalated`)
+log(`Phase delta: ${implTokens} tokens`)
+
+if (implResult.us_escalated?.length) {
+  for (const usId of implResult.us_escalated) {
+    escalations.push({ usId, reason: 'CRITICAL review finding unresolved after 2 rework cycles' })
+  }
+}
+
+const prefix     = implResult.prefix
+const issuesPath = implResult.issues_path || ''
+
+// ── Remediation ───────────────────────────────────────────────────────────────
+phase('Remediation')
+
+const REM_SCHEMA = {
+  type: 'object',
+  properties: {
+    issues_fixed:    { type: 'number' },
+    issues_deferred: { type: 'number' },
+  },
+  required: ['issues_fixed', 'issues_deferred'],
+}
+
+let issuesFixed    = 0
+let issuesDeferred = 0
+
+if (implResult.issues_open > 0 && issuesPath) {
+  log(`Remediation: ${implResult.issues_open} OPEN issues`)
+  const beforeRem = budget.spent()
+
+  const remResult = await agent(
+    `You are a remediation agent for the feature delivery pipeline.
+
+Read the Issues Register at: ${issuesPath}
+
+For each OPEN issue:
+- If severity is INFO: mark it DEFERRED immediately (update the Status column to DEFERRED). Do not dispatch a developer agent.
+- If severity is WARNING: dispatch the appropriate developer agent (developer-backend for most cases) with the issue description. Then spawn review-solution to verify the fix. Max 1 retry per issue. If unresolved after 1 retry, mark DEFERRED.
+
+After processing all issues, return:
+{ "issues_fixed": N, "issues_deferred": N }
+
+Update the Issues Register Status column in place for each resolved/deferred issue.`,
+    {
+      label:  'remediation',
+      phase:  'Remediation',
+      schema: REM_SCHEMA,
+    }
+  )
+
+  const remTokens = budget.spent() - beforeRem
+  tokenLedger.push({ agent: 'remediation', model: 'sonnet', phase_delta_tokens: remTokens })
+  issuesFixed    = remResult.issues_fixed    || 0
+  issuesDeferred = remResult.issues_deferred || 0
+  log(`Remediation done — fixed: ${issuesFixed}, deferred: ${issuesDeferred} | phase delta: ${remTokens} tokens`)
+} else {
+  log('Remediation: no OPEN issues — skipped')
+}
+
+// ── PR ────────────────────────────────────────────────────────────────────────
+phase('PR')
+
+const PR_SCHEMA = {
+  type: 'object',
+  properties: {
+    pr_url:            { type: 'string' },
+    registry_updated:  { type: 'boolean' },
+  },
+  required: ['pr_url'],
+}
+
+const beforePR = budget.spent()
+
+const prResult = await agent(
+  `You are the PR and registry agent for the feature delivery pipeline.
+
+Feature path: ${featurePath}
+Branch: ${branch || 'current branch'}
+Prefix: ${prefix}
+Issues fixed: ${issuesFixed}, deferred: ${issuesDeferred}
+
+Your tasks:
+
+1. If there are remediation fixes, commit them:
+   git add -A
+   git commit -m "fix(${prefix}): remediate review issues"
+
+2. Push the branch:
+   git push -u origin ${branch || 'HEAD'}
+
+3. Create a PR targeting develop:
+   gh pr create \\
+     --title "feat(${prefix}): <Feature Title from feature.md>" \\
+     --base develop \\
+     --body "## Summary
+- Implements <Feature Title> (<N> User Stories, <N> tasks)
+- Source docs: ${prefix}-Requirements.md, ${prefix}-Tech-Spec.md
+
+## Implementation
+- Architect review: all US passed
+- Issues Register: ${issuesFixed} fixed, ${issuesDeferred} deferred → see ${prefix}-Issues.md
+
+## Test plan
+- [ ] Build passes
+- [ ] Tests pass
+- [ ] Manual smoke test of key flows"
+
+4. Update the Feature Registry (internal_docs/features/REGISTRY.md):
+   Find or append the entry for ${prefix}. Set Status to "completed".
+
+Return { "pr_url": "<url>", "registry_updated": true/false }.
+If the PR creation fails, return { "pr_url": "(PR creation failed)", "registry_updated": false }.`,
+  {
+    label:  'pr-and-registry',
+    phase:  'PR',
+    schema: PR_SCHEMA,
+  }
+)
+
+const prTokens = budget.spent() - beforePR
+tokenLedger.push({ agent: 'pr-and-registry', model: 'sonnet', phase_delta_tokens: prTokens })
+log(`PR done: ${prResult.pr_url} | phase delta: ${prTokens} tokens`)
+
+// ── Actuals ───────────────────────────────────────────────────────────────────
+phase('Actuals')
+
+// Compute proportional distribution of phase tokens across logical agents
+// Phase tokens are exact (budget.spent() deltas); per-agent breakdown is proportional.
+// This is documented in the Token-Estimate file with a disclaimer.
+const totalImplTokens = tokenLedger.reduce((s, e) => s + (e.phase_delta_tokens || 0), 0)
+
+const ACTUALS_SCHEMA = {
+  type: 'object',
+  properties: {
+    token_estimate_path: { type: 'string' },
+    effort_estimate_path: { type: 'string' },
+  },
+  required: [],
+}
+
+const beforeActuals = budget.spent()
+
+await agent(
+  `You are the actuals recorder for the feature delivery pipeline.
+
+Feature path: ${featurePath}
+Prefix: ${prefix}
+
+Token ledger (phase-level measurements):
+${JSON.stringify(tokenLedger, null, 2)}
+
+Total tokens consumed by pm-phase3 workflow (all phases combined): ${totalImplTokens} (exact, from budget tracking)
+
+TASK 1 — Update Token-Estimate.md:
+Find ${prefix}-Token-Estimate.md in the feature directory.
+If it doesn't exist, create it with the structure from docs/procedures/token-estimation.md.
+
+Append this section at the end:
+
+---
+
+## Actuals vs Estimate
+
+> ⚠️ Per-agent values are proportional distributions of the phase total.
+> Phase totals (pm-phase3 total: ${totalImplTokens} tokens) are exact measurements.
+> Individual agent breakdown is estimated proportionally.
+
+| Agent | Task / Scope | Model | Phase delta tokens | Notes |
+|-------|-------------|-------|-------------------|-------|
+${tokenLedger.map(e => `| ${e.agent} | — | ${e.model} | ${e.phase_delta_tokens} | exact phase delta |`).join('\n')}
+
+## Grand Total (pm-phase3)
+
+| Metric | Value |
+|--------|-------|
+| Total tokens (pm-phase3) | ${totalImplTokens} (exact) |
+| Implementation phases | ${implResult.phases_done} |
+| US passed | ${(implResult.us_passed || []).join(', ') || 'N/A'} |
+| US escalated | ${(implResult.us_escalated || []).join(', ') || 'none'} |
+
+TASK 2 — Append actuals to Effort-Estimate.md:
+Find ${prefix}-Effort-Estimate.md in the feature directory.
+Append:
+
+---
+
+## Actuals vs Estimate
+
+| Metric | Estimated | Actual |
+|--------|-----------|--------|
+| Implementation phases | ${implResult.phases_done} | ${implResult.phases_done} |
+| Issues fixed | — | ${issuesFixed} |
+| Issues deferred | — | ${issuesDeferred} |
+
+Return { "token_estimate_path": "<path>", "effort_estimate_path": "<path>" }.`,
+  {
+    label:  'write-actuals',
+    phase:  'Actuals',
+    schema: ACTUALS_SCHEMA,
+  }
+)
+
+const actualsTokens = budget.spent() - beforeActuals
+tokenLedger.push({ agent: 'write-actuals', model: 'sonnet', phase_delta_tokens: actualsTokens })
+log(`Actuals written | phase delta: ${actualsTokens} tokens`)
+
+return {
+  pr_url:       prResult.pr_url,
+  token_ledger: tokenLedger,
+  issues_summary: {
+    escalations: escalations.length,
+    escalation_details: escalations,
+    issues_fixed:    issuesFixed,
+    issues_deferred: issuesDeferred,
+  },
+}

package/CHANGELOG.md

@@ -1,4 +1,33 @@
 ## 0.1.4 (2026-07-21)
+## [0.2.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.2.0...v0.2.1) (2026-07-27)
+
+
+### Bug Fixes
+
+* validate-feature-docs always writes report; fix false-positive gap detection ([68caf3e](https://github.com/dtlab-tech/ai-toolkit/commit/68caf3e25214bcb219df1654c4b3ede5cc42eb3b))
+* validate-feature-docs always writes report; fix false-positive gap detection in pm-phase1 ([d99fdb3](https://github.com/dtlab-tech/ai-toolkit/commit/d99fdb39be1663539bd0ed7e6ca4facc2c53fd76))
+
+## [0.2.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.1.7...v0.2.0) (2026-07-27)
+
+
+### Features
+
+* **FTR-007:** explicit per-agent model assignment ([853eb0f](https://github.com/dtlab-tech/ai-toolkit/commit/853eb0f956a9a1aa64dedac7100fb1ad9eab4b08))
+* **FTR-007:** implement US-01 — explicit per-agent model assignment ([0fe5fba](https://github.com/dtlab-tech/ai-toolkit/commit/0fe5fba9b25dc261e840d99d97105dec7c0c9318))
+* **FTR-008:** compact instructions block for ~/.claude/CLAUDE.md ([738df59](https://github.com/dtlab-tech/ai-toolkit/commit/738df597e2da3edc04de68462f0e4555b232941d))
+* **FTR-008:** implement compact instructions block ([0dab04d](https://github.com/dtlab-tech/ai-toolkit/commit/0dab04d9c14392866c9046eee9e7052a2beac586))
+* **FTR-009:** implement shared infrastructure (INFRA) ([31bceb9](https://github.com/dtlab-tech/ai-toolkit/commit/31bceb9788a1f403eea3f2971b87959fa9e33f97))
+* **FTR-009:** implement US-01 — Feature Delivery Workflow Scripts ([7f6dd7d](https://github.com/dtlab-tech/ai-toolkit/commit/7f6dd7da8280d9bc6b5b9922bf7f751c1837f8ad))
+* **FTR-009:** implement US-02 — Assessment Workflow Scripts ([7b1e668](https://github.com/dtlab-tech/ai-toolkit/commit/7b1e668217f89ef16011fbe253a8e4bfb5714d0c))
+* **FTR-009:** rewrite orchestrators as Workflow scripts ([7f63b20](https://github.com/dtlab-tech/ai-toolkit/commit/7f63b209e6f4826115c74189847f68d77dc16ac1))
+* release develop → main (FTR-007, FTR-008, FTR-009) ([66c9e05](https://github.com/dtlab-tech/ai-toolkit/commit/66c9e05dde12be03f2c3d2a13eea112103fd6a20))
+
+
+### Bug Fixes
+
+* **FTR-009:** remediate review issues; update registry ([6aaeeb0](https://github.com/dtlab-tech/ai-toolkit/commit/6aaeeb0465b4d2003e61f33f7c6d0641bc477f9c))
+* **FTR-009:** rewrite all 5 workflow scripts with correct Workflow SDK API ([2c6da04](https://github.com/dtlab-tech/ai-toolkit/commit/2c6da041c07a1c233678cd0d64dfeaf66f0674a5))
+
 ## 0.1.7 (2026-07-23)
 
 

package/README.md

@@ -65,6 +65,32 @@ The toolkit ships **generic agents** that work with any project. Each agent read
 
 Generic procedures live in `docs/procedures/`. Projects can override any of them by placing a file with the same name at their own `docs/procedures/`. Agents check the project first, then fall back to the toolkit.
 
+## Required configuration — subagent spawn depth
+
+> ⚠️ **This setting is not optional for the orchestrated pipelines.** Without it, `/implement-feature` and `/assess-codebase` silently degrade.
+
+The toolkit is built on a **two-level agent hierarchy**: an orchestrator (`project-manager` or `assessment-manager`) is spawned as a subagent, and it in turn spawns the specialized worker agents (developers, reviewers, assessors), each on its own role-appropriate model with an isolated context.
+
+Since Claude Code **v2.1.217, a subagent cannot spawn further subagents by default** (spawn depth is capped at 1, an intentional guard against unbounded recursive fan-out and cost). Under that default, when an orchestrator runs as a subagent it has **no `Agent` tool** — so instead of delegating, it executes every worker's task *inline, in its own context, on its own model*. The consequences:
+
+- **Per-agent model assignment stops taking effect** — the `haiku`/`sonnet`/`opus` mapping on each agent is never applied, because those agents are never actually spawned. Everything runs on the orchestrator's model.
+- **Context isolation is lost** — one long orchestrator context replaces the intended per-agent isolation.
+- **Per-agent token telemetry disappears** — no per-agent `<usage>` blocks are emitted, so `*-Token-Estimate.md` records only an aggregate orchestrator total.
+
+To let the toolkit work as designed, raise the allowed depth to **2** (main loop → orchestrator → workers). This repo already sets it in [`.claude/settings.json`](.claude/settings.json):
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
+  }
+}
+```
+
+**When you install the toolkit into another project, you must add this setting yourself.** The installers (`npx @dtlabs/ai-toolkit`, `ai-toolkit --global`, and the `/install-toolkit` agent) **never copy or edit any `settings.json`** — that file is user-owned, and merging it automatically would risk clobbering your existing configuration. Instead, each installer **checks** whether `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` is set to `2`+ in the destination and, if it is missing, prints the exact snippet to add (to `.claude/settings.json` for one project, or `~/.claude/settings.json` for all projects). After adding it, restart Claude Code so the variable is loaded.
+
+The orchestrator agents already omit the `tools:` frontmatter field, so they inherit the `Agent` tool automatically once the depth allows it — no per-agent changes are needed.
+
 ## Documentation
 
 - [Quick Reference](docs/reference.md) — cheatsheet of every skill, command, agent, and procedure

package/bin/cli.js

@@ -40,10 +40,18 @@ function banner() {
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
+// User-owned config that must NEVER be copied into a destination. We only verify
+// and advise on these — copying would clobber the user's existing settings.
+const NEVER_COPY = new Set(['settings.json', 'settings.local.json']);
+
 function fileHash(filePath) {
   return crypto.createHash('md5').update(fs.readFileSync(filePath)).digest('hex');
 }
 
+function readJsonSafe(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return null; }
+}
+
 function ensureDir(filePath) {
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -67,10 +75,12 @@ function expandMappings(mappings) {
     if (!fs.existsSync(src)) continue;
     if (fs.statSync(src).isDirectory()) {
       for (const entry of walkDir(src)) {
+        if (NEVER_COPY.has(path.basename(entry))) continue; // never clobber user config
         const rel = path.relative(src, entry);
         files.push({ src: entry, dest: path.join(dest, rel) });
       }
     } else {
+      if (NEVER_COPY.has(path.basename(src))) continue;
       files.push({ src, dest });
     }
   }
@@ -262,6 +272,52 @@ async function askMattPocock() {
   else console.log(`  ${clr('gray', 'Skipped.')}\n`);
 }
 
+// ── subagent spawn-depth check (verify & advise only — never write) ────────────
+
+const SPAWN_DEPTH_VAR = 'CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH';
+
+// Report whether the spawn-depth prerequisite is satisfied for a destination,
+// checking both project-level and local-override settings files. Purely advisory:
+// this NEVER creates or modifies any settings file.
+function checkSpawnDepth(destRoot) {
+  const candidates = [
+    path.join(destRoot, '.claude', 'settings.json'),
+    path.join(destRoot, '.claude', 'settings.local.json'),
+  ];
+
+  console.log(divider());
+  console.log(bold('  Subagent spawn depth (required for orchestrated pipelines)'));
+  console.log(divider());
+
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    const json = readJsonSafe(file);
+    const value = json && json.env && json.env[SPAWN_DEPTH_VAR];
+    if (value !== undefined && Number(value) >= 2) {
+      console.log(`  ${clr('green', '✔')}  ${SPAWN_DEPTH_VAR}=${value} found in ${dim(path.relative(process.cwd(), file))}`);
+      console.log(`     ${dim('Orchestrators can spawn worker subagents — pipelines will run as designed.')}\n`);
+      return;
+    }
+  }
+
+  console.log(`  ${clr('yellow', '⚠')}  ${SPAWN_DEPTH_VAR} is not set to 2+ in this project.`);
+  console.log(`     ${dim('Without it, /implement-feature and /assess-codebase run every worker inline')}`);
+  console.log(`     ${dim('on the orchestrator model: per-agent model assignment, context isolation,')}`);
+  console.log(`     ${dim('and per-agent token telemetry are all lost.')}`);
+  console.log();
+  console.log(`     ${bold('Action required')} — add this to ${clr('cyan', '.claude/settings.json')} (project)`);
+  console.log(`     or ${clr('cyan', '~/.claude/settings.json')} (all projects). We do not edit it for you,`);
+  console.log(`     ${dim('to avoid clobbering your existing configuration:')}`);
+  console.log();
+  console.log(clr('gray', '       {'));
+  console.log(clr('gray', '         "env": {'));
+  console.log(clr('gray', `           "${SPAWN_DEPTH_VAR}": "2"`));
+  console.log(clr('gray', '         }'));
+  console.log(clr('gray', '       }'));
+  console.log();
+  console.log(`     ${dim('Then restart Claude Code so the variable is loaded.')}\n`);
+}
+
 // ── entry points ──────────────────────────────────────────────────────────────
 
 async function installLocal(targetDir, force) {
@@ -277,6 +333,7 @@ async function installLocal(targetDir, force) {
   await runInstall(`local project`, mappings, force);
   writeInstalledVersion(targetDir);
   console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
+  checkSpawnDepth(targetDir);
   await askMattPocock();
   console.log(divider());
   console.log(`\n  ${bold('Next steps:')}`);
@@ -293,15 +350,17 @@ async function installGlobal(force) {
     console.log(`  ${clr('cyan', '▸')}  Target: ${bold(target)}  ${clr('gray', '(global Claude folder)')}\n`);
     await checkVersion(target, force);
     const mappings = [
-      { src: path.join(packageRoot, '.claude', 'agents'),   dest: path.join(target, 'agents') },
-      { src: path.join(packageRoot, '.claude', 'skills'),   dest: path.join(target, 'skills') },
-      { src: path.join(packageRoot, '.claude', 'commands'), dest: path.join(target, 'commands') },
-      { src: path.join(packageRoot, 'docs'),                dest: path.join(target, 'docs') },
-      { src: path.join(packageRoot, 'CLAUDE.md'),           dest: path.join(target, 'CLAUDE.md') },
+      { src: path.join(packageRoot, '.claude', 'agents'),    dest: path.join(target, 'agents') },
+      { src: path.join(packageRoot, '.claude', 'skills'),    dest: path.join(target, 'skills') },
+      { src: path.join(packageRoot, '.claude', 'commands'),  dest: path.join(target, 'commands') },
+      { src: path.join(packageRoot, '.claude', 'workflows'), dest: path.join(target, 'workflows') },
+      { src: path.join(packageRoot, 'docs'),                 dest: path.join(target, 'docs') },
+      { src: path.join(packageRoot, 'CLAUDE.md'),            dest: path.join(target, 'CLAUDE.md') },
     ];
     await runInstall('global Claude folder', mappings, force);
     writeInstalledVersion(target);
     console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
+    checkSpawnDepth(homedir);
     await askMattPocock();
     console.log(divider());
     console.log(`\n  ${bold('Next steps:')}`);

package/docs/token-optimization-backlog.md

@@ -0,0 +1,115 @@
+# Token Optimization — Backlog di feature atomiche
+
+> Deriva da `docs/token-optimization.md`. Data: 2026-07-24.
+> Ogni voce è **atomica**: implementabile e verificabile in isolamento.
+> "Criticità" = priorità di ottimizzazione (impatto/rischio), NON severità di difetto.
+> Nessun intervento è un bug attivo → nessun `CRITICAL`.
+> Sequenza consigliata = ordine degli ID.
+
+## Quadro sintetico
+
+| ID | Intervento | Criticità | Sforzo | Rischio | File toccati | Dipende da |
+|----|-----------|-----------|--------|---------|--------------|-----------|
+| OPT-01 ✅ | `model:` esplicito su ogni agent (→ FTR-007, PR #20) | **HIGH** | Basso | Basso | 15 agent (frontmatter) | — |
+| OPT-02 | Deduplicare CLAUDE.md globale vs progetto | **HIGH** | Minimo | Zero | `~/.claude/CLAUDE.md` | — |
+| OPT-03 | Blocco "Compact instructions" in CLAUDE.md | MEDIUM | Minimo | Zero | `CLAUDE.md` (progetto) | — |
+| OPT-04 | Spostare i cataloghi da CLAUDE.md a reference.md | MEDIUM | Basso | Basso | `CLAUDE.md`, `docs/reference.md` | — |
+| OPT-05 | Procedure on-demand — assessment-manager | MEDIUM | Medio | Basso | `assessment-manager.md` | — |
+| OPT-06 | Procedure on-demand — project-manager | MEDIUM | Medio | Basso | `project-manager.md` | — |
+| OPT-07 | Resource-budget testuale negli assessment agent | MEDIUM | Basso | Basso | 3+ assessment agent | — |
+| OPT-08 | Summary/full split negli output di assessment | **HIGH** | Alto | Medio | assessment agents + int-doc + manager | OPT-07 |
+| OPT-09 | Estrarre calcolo deterministico da assessment-manager | **HIGH** | Alto | Medio | `assessment-manager.md` + nuovo script | — |
+| OPT-10 | generic-software-assessment → ruolo triage | MEDIUM | Medio | Medio | `generic-software-assessment.md` + manager | OPT-08 |
+| OPT-11 | Delegation policy negli orchestratori | LOW | Basso | Basso | 2 orchestratori | — |
+| OPT-12 | Hook di filtro output verboso (opzionale) | LOW | Basso | Basso | `settings.json` + script hook | — |
+
+---
+
+## Feature atomiche
+
+### OPT-01 — `model:` esplicito su ogni agent
+- **Criticità:** HIGH · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** ogni agent dichiara il modello adatto al suo ruolo, così nessuno eredita Opus per default.
+- **Scope (solo frontmatter):** aggiungere `model:` ai 15 agent che ne sono privi. Mappatura:
+  - `sonnet`: `assessment-manager`, `project-manager`, `developer-backend`, `developer-frontend`, `developer-testing`, `god-class-decomposition`, `domain-model-refactoring`, `dependency-injection-refactoring`, `security-hardening`, `dependency-supply-chain-security`, `define-feature`, `init-agents-md`, `install-toolkit`, `intervention-documentation-standard`
+  - `opus`: `review-solution` (unico ruolo con giudizio architetturale profondo)
+- **Fuori scope:** i 7 agent già `haiku` restano invariati.
+- **Criteri di accettazione:** `grep -L "^model:" .claude/agents/*.md` non restituisce nulla; ogni valore ∈ {haiku, sonnet, opus}.
+- **Dipendenze:** nessuna.
+
+### OPT-02 — Deduplicare CLAUDE.md globale vs progetto
+- **Criticità:** HIGH · **Sforzo:** Minimo · **Rischio:** Zero
+- **Obiettivo:** eliminare il duplicato caricato a ogni sessione; il `CLAUDE.md` di progetto resta la fonte unica del catalogo toolkit.
+- **Scope:** ridurre `~/.claude/CLAUDE.md` alle sole preferenze cross-progetto (lingua, stile, convenzioni personali). Rimuovere il catalogo toolkit duplicato.
+- **Criteri di accettazione:** `diff ~/.claude/CLAUDE.md ./CLAUDE.md` NON è più identico; il globale non contiene più le tabelle Skills/Commands/Agents; il Gate Protocol resta accessibile (nel progetto).
+- **Dipendenze:** nessuna. ⚠️ File utente globale — confermare con l'utente prima di modificare.
+
+### OPT-03 — Blocco "Compact instructions" in CLAUDE.md
+- **Criticità:** MEDIUM · **Sforzo:** Minimo · **Rischio:** Zero
+- **Obiettivo:** guidare l'auto-compaction a preservare ciò che conta (decisioni, file, finding IDs) e scartare rumore.
+- **Scope:** aggiungere al `CLAUDE.md` di progetto una sezione `# Compact instructions` (preserva: obiettivo corrente, decisioni confermate, risposte utente, file modificati, errori aperti, finding/artifact IDs; scarta: risultati grep grezzi, output tool riusciti, spiegazioni ripetute, piani superati).
+- **Criteri di accettazione:** la sezione esiste in `CLAUDE.md`; nessun'altra modifica.
+- **Dipendenze:** nessuna. (Coordinare con OPT-04 se si tocca lo stesso file.)
+
+### OPT-04 — Spostare i cataloghi da CLAUDE.md a reference.md
+- **Criticità:** MEDIUM · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** CLAUDE.md sotto ~200 righe, solo essenziali operativi; il catalogo di scoperta vive in reference.md.
+- **Scope:** spostare le tabelle Skills / Commands / Agents / Procedures in `docs/reference.md`. In `CLAUDE.md` restano: Dependencies, How it works, override procedure, **Gate Protocol**. Aggiungere in CLAUDE.md un puntatore a reference.md.
+- **Criteri di accettazione:** `CLAUDE.md` < 200 righe; nessuna tabella-catalogo persa (presente in reference.md); Gate Protocol ancora in CLAUDE.md.
+- **Dipendenze:** nessuna.
+
+### OPT-05 — Procedure on-demand (assessment-manager)
+- **Criticità:** MEDIUM · **Sforzo:** Medio · **Rischio:** Basso
+- **Obiettivo:** leggere ogni procedura nella fase in cui serve, non tutte all'avvio.
+- **Scope:** in `assessment-manager.md`, spostare le istruzioni "read at startup" così che `token-estimation.md`/`pricing.md` si leggano in Phase 3-4, `assessment-findings-gate.md` in Phase 5, ecc.
+- **Criteri di accettazione:** nessuna procedura letta prima della fase che la usa; il comportamento delle fasi resta invariato.
+- **Dipendenze:** nessuna. (Se si fa OPT-09, `token-estimation.md` sparisce del tutto dal contesto LLM.)
+
+### OPT-06 — Procedure on-demand (project-manager)
+- **Criticità:** MEDIUM · **Sforzo:** Medio · **Rischio:** Basso
+- **Obiettivo:** stesso principio di OPT-05 applicato al `project-manager` (che legge ancora più procedure).
+- **Scope:** riorganizzare `project-manager.md` per caricare ogni procedura alla fase pertinente (PR-procedure alla fase PR, ecc.).
+- **Criteri di accettazione:** nessuna procedura caricata anticipatamente; pipeline invariata.
+- **Dipendenze:** nessuna.
+
+### OPT-07 — Resource-budget testuale negli assessment agent
+- **Criticità:** MEDIUM · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** limiti di lettura/output come **istruzioni nel prompt** (NON frontmatter — `budget:` non è supportato dall'harness).
+- **Scope:** aggiungere una sezione `## Resource budget` in prosa agli assessment agent (es. "Inspect at most ~25 files; ≤2 evidence snippets per finding; stop when evidence is sufficient — do not explore to increase coverage").
+- **Criteri di accettazione:** la sezione è testo del prompt, non YAML; presente in `generic-software-assessment`, `layered-architecture-assessment`, `concurrency-safety-assessment`.
+- **Dipendenze:** nessuna.
+
+### OPT-08 — Summary/full split negli output di assessment
+- **Criticità:** HIGH · **Sforzo:** Alto · **Rischio:** Medio
+- **Obiettivo:** l'orchestratore legge un **summary compatto**, non il documento intero. Il guadagno reale (non il formato JSON in sé).
+- **Scope:** ogni assessment agent produce `{PREFIX}-{area}.full.md` (dettagli) + `{PREFIX}-{area}.summary` (conteggi per severità, finding IDs, path del full). `assessment-manager` e `intervention-documentation-standard` consumano il summary; il full si apre solo per i finding accettati.
+- **Criteri di accettazione:** ogni agent scrive entrambi i file; il manager non legge i `.full` in Phase 3; l'int-doc apre i full solo per i finding selezionati.
+- **Dipendenze:** OPT-07 (budget di output coerente).
+
+### OPT-09 — Estrarre calcolo deterministico da assessment-manager
+- **Criticità:** HIGH · **Sforzo:** Alto · **Rischio:** Medio
+- **Obiettivo:** togliere dal prompt ~3.500 parole di pseudo-codice (calcolo token/effort, registry write) che un LLM esegue in modo costoso e fragile.
+- **Scope:** spostare Token-Estimate / Effort-Estimate / registry-write in uno script (`scripts/estimate.*`) invocato via Bash; il prompt dell'agent si riduce a "esegui lo script con questi input e verifica l'output".
+- **Criteri di accettazione:** i tre file prodotti sono identici (per input noti) a prima; `assessment-manager.md` perde le sezioni di calcolo passo-passo; nessun errore aritmetico possibile lato LLM.
+- **Dipendenze:** nessuna hard; sinergica con OPT-05.
+
+### OPT-10 — generic-software-assessment → ruolo triage
+- **Criticità:** MEDIUM · **Sforzo:** Medio · **Rischio:** Medio
+- **Obiettivo:** evitare che il generic duplichi il lavoro degli specialisti (layer, security, concurrency) sullo stesso codebase.
+- **Scope:** trasformare `generic-software-assessment` in triage: scansione superficiale che decide quali specialisti attivare e copre solo le aree non coperte (Opzione A della gap analysis).
+- **Criteri di accettazione:** il generic non riesamina aree già coperte da uno specialista attivo; l'output indica gli specialisti raccomandati.
+- **Dipendenze:** meglio dopo OPT-08 (contratto di output stabile).
+
+### OPT-11 — Delegation policy negli orchestratori
+- **Criticità:** LOW · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** regola esplicita "delega un subagent solo se serve" (task indipendente/parallelo, output voluminoso, riuso multiplo); non delegare ciò che una grep/read risolve.
+- **Scope:** aggiungere una sezione `## Delegation policy` a `assessment-manager` e `project-manager`.
+- **Criteri di accettazione:** entrambi gli orchestratori contengono i criteri delega/non-delega.
+- **Dipendenze:** nessuna.
+
+### OPT-12 — Hook di filtro output verboso (opzionale)
+- **Criticità:** LOW · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** filtrare output verbosi (build/test/log) prima che entrino nel contesto.
+- **Scope:** `PreToolUse` su Bash in `settings.json` + script che riduce l'output di test/build alle sole righe rilevanti.
+- **Criteri di accettazione:** l'hook appare in `/hooks`; un comando di test mostra solo failures.
+- **Dipendenze:** nessuna. Fare solo se gli assessment inizieranno a lanciare build/test.