@dtlabs/ai-toolkit 0.1.6 → 0.2.0

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

@@ -0,0 +1,108 @@
+export const meta = {
+  name: 'pm-phase2',
+  description: 'Feature delivery phase 2: generate-work-breakdown → Effort-Estimate → gate2_payload. Precondition: Gate 1 approved.',
+  phases: [
+    { title: 'Work Breakdown', detail: 'Run generate-work-breakdown' },
+    { title: 'Effort Estimate', detail: 'Parse WB metrics, write Effort-Estimate.md' },
+  ],
+}
+
+// args: "<path-to-feature.md>"
+const featurePath = (typeof args === 'string' ? args : '').trim().split(/\s+/)[0]
+
+// ── generate-work-breakdown ───────────────────────────────────────────────────
+phase('Work Breakdown')
+
+const tokenLedger = []
+
+log(`Running generate-work-breakdown for ${featurePath}`)
+const beforeWB = budget.spent()
+await agent(featurePath, {
+  agentType: 'generate-work-breakdown',
+  label:     'generate-work-breakdown',
+  phase:     'Work Breakdown',
+})
+const wbTokens = budget.spent() - beforeWB
+tokenLedger.push({ agent: 'generate-work-breakdown', model: 'haiku', phase_delta_tokens: wbTokens })
+log(`generate-work-breakdown done — phase delta: ${wbTokens} tokens`)
+
+// ── Parse WB + write Effort-Estimate ─────────────────────────────────────────
+phase('Effort Estimate')
+
+const PARSE_SCHEMA = {
+  type: 'object',
+  properties: {
+    prefix:                { type: 'string' },
+    feature_dir:           { type: 'string' },
+    user_stories:          { type: 'number' },
+    total_tasks:           { type: 'number' },
+    domain_breakdown:      { type: 'string' },
+    implementation_phases: { type: 'number' },
+    human_estimate:        { type: 'string' },
+    agent_estimate:        { type: 'string' },
+    work_breakdown_path:   { type: 'string' },
+    effort_estimate_path:  { type: 'string' },
+  },
+  required: ['prefix', 'user_stories', 'total_tasks', 'work_breakdown_path'],
+}
+
+const metrics = await agent(
+  `You have two tasks:
+
+TASK 1 — Read the Work Breakdown file.
+The feature.md is at: ${featurePath}
+The directory containing feature.md also contains the Work Breakdown file named {PREFIX}-Work-Breakdown.md,
+where PREFIX matches the pattern [A-Z]+-[0-9]+ from the directory name (e.g. FTR-009).
+Use Glob or Read to find and read that file.
+
+Extract from the Summary table:
+- prefix (e.g. "FTR-009")
+- feature_dir (directory containing feature.md)
+- user_stories (integer)
+- total_tasks (integer)
+- domain_breakdown (e.g. "DB:0, BE:11, FE:0, INFRA:4, TEST:0")
+- implementation_phases (integer)
+- human_estimate (e.g. "~34h")
+- agent_estimate (e.g. "~2h 6min")
+- work_breakdown_path (full path to the Work Breakdown file)
+
+TASK 2 — Write the Effort-Estimate.md file.
+Write {feature_dir}/{PREFIX}-Effort-Estimate.md with the extracted metrics in this format:
+
+# Effort Estimate — {PREFIX} — {Feature Title}
+
+| Metric | Value |
+|--------|-------|
+| User Stories | {user_stories} |
+| Total tasks | {total_tasks} ({domain_breakdown}) |
+| Implementation phases | {implementation_phases} |
+| Human estimate | {human_estimate} (sequential, no parallelism) |
+| Agent estimate | {agent_estimate} (parallel dispatch, critical path only) |
+
+Set effort_estimate_path to the full path of the written file.
+
+Return the extracted metrics as structured output.`,
+  {
+    label:  'parse-wb-write-effort-estimate',
+    phase:  'Effort Estimate',
+    schema: PARSE_SCHEMA,
+  }
+)
+
+log(`WB parsed: ${metrics.user_stories} US, ${metrics.total_tasks} tasks, ${metrics.implementation_phases} phases`)
+log(`Effort-Estimate written: ${metrics.effort_estimate_path}`)
+
+return {
+  prefix:                metrics.prefix,
+  feature_path:          featurePath,
+  user_stories:          metrics.user_stories,
+  total_tasks:           metrics.total_tasks,
+  domain_breakdown:      metrics.domain_breakdown  || 'N/A',
+  implementation_phases: metrics.implementation_phases,
+  human_estimate:        metrics.human_estimate    || 'N/A',
+  agent_estimate:        metrics.agent_estimate    || 'N/A',
+  work_breakdown_path:   metrics.work_breakdown_path,
+  effort_estimate_path:  metrics.effort_estimate_path || '',
+  token_ledger:          tokenLedger,
+  errors:                [],
+}

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,102 @@
-## 0.1.6 (2026-07-16)
-## 0.1.5 (2026-07-14)
-## 0.1.4 (2026-07-14)
+## 0.1.4 (2026-07-21)
+## [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)
+
+
+### Features
+
+* add effort estimation and actuals tracking to project manager workflow ([0b81915](https://github.com/dtlab-tech/ai-toolkit/commit/0b819154584c725ccca09a825888aee8f3f5f34f))
+* add effort estimation and actuals tracking to project manager workflow ([f9e74ef](https://github.com/dtlab-tech/ai-toolkit/commit/f9e74ef39972e3f0f3b0d3b6e4311d15fa9035cc))
+* add GitHub Actions workflow to auto-publish to npm on merge to main ([f8d89ea](https://github.com/dtlab-tech/ai-toolkit/commit/f8d89ea20364796ce699b8228041f7f436ff3bdd))
+* add GitHub Actions workflow to auto-publish to npm on merge to main ([abe2c45](https://github.com/dtlab-tech/ai-toolkit/commit/abe2c45336586794267d4ac7faf164cb82758fb6))
+* add option to install Matt Pocock's skills during toolkit installation ([441183d](https://github.com/dtlab-tech/ai-toolkit/commit/441183d30214ed6eb570ae41ddf858229276b6d5))
+* add option to install Matt Pocock's skills during toolkit installation ([f0d4fa3](https://github.com/dtlab-tech/ai-toolkit/commit/f0d4fa3ff783498d77e5b399d22d5828c8b157a6))
+* add pricing documentation for cost estimation and blended cost formula ([91f6392](https://github.com/dtlab-tech/ai-toolkit/commit/91f63926ef2eabd20ad09a186f323d00abba9963))
+* add pricing documentation for cost estimation and blended cost formula ([a9361ed](https://github.com/dtlab-tech/ai-toolkit/commit/a9361eda75b2c36d2515df976782af67bba1c4e4))
+* Add SWF AI Toolkit with agents, skills, commands, and procedures for software feature delivery ([327a282](https://github.com/dtlab-tech/ai-toolkit/commit/327a2826bf4a147bcf2f993bc3ea254eaa12b18b))
+* Add SWF AI Toolkit with agents, skills, commands, and procedures for software feature delivery ([97eb589](https://github.com/dtlab-tech/ai-toolkit/commit/97eb589a2b63a9ea45634c71aaae07d08bc1deaf))
+* add version check during toolkit installation and update installed version file ([0e0eeea](https://github.com/dtlab-tech/ai-toolkit/commit/0e0eeea1bafe78e4d5c4214efc1b7acab9799ac8))
+* add version check during toolkit installation and update installed version file ([4681ed4](https://github.com/dtlab-tech/ai-toolkit/commit/4681ed445a83c7f3bee5677bb773deaa7b0f86e2))
+* assessment pipeline enhancements — token/effort estimation, registry, intervention commands, and Gaia assistant ([0cb512c](https://github.com/dtlab-tech/ai-toolkit/commit/0cb512cfd6d18c38216584ca454ab2077e641762))
+* auto-generate CHANGELOG.md on publish via conventional-changelog ([6fdbd69](https://github.com/dtlab-tech/ai-toolkit/commit/6fdbd69c011ad3d568f3070f4c2dcd87092623e9))
+* auto-generate CHANGELOG.md on publish via conventional-changelog ([49df865](https://github.com/dtlab-tech/ai-toolkit/commit/49df865633ebcede49f6c879921e775f1945271b))
+* Enhance agent descriptions and add completion summaries ([a3aa811](https://github.com/dtlab-tech/ai-toolkit/commit/a3aa81169f102a09c95a46a98aa3b4f82bbb3b31))
+* Enhance agent descriptions and add completion summaries ([1b2fe4a](https://github.com/dtlab-tech/ai-toolkit/commit/1b2fe4a2bf1c52107c8605533f2a0cdd85d1afbf))
+* enhance file installation process with detailed status reporting and user prompts ([c12ca72](https://github.com/dtlab-tech/ai-toolkit/commit/c12ca72e111ead2f3c53b8846507f61fb572125b))
+* enhance file installation process with detailed status reporting and user prompts ([10b56a4](https://github.com/dtlab-tech/ai-toolkit/commit/10b56a4d10455366cfec0690b8e9e428399f845a))
+* enhance installation process with version checks and optional Matt Pocock skills installation ([16411e7](https://github.com/dtlab-tech/ai-toolkit/commit/16411e755c6586e8d33bd13b62402b3648e05b9c))
+* enhance installation process with version checks and optional Matt Pocock skills installation ([8c1f0ae](https://github.com/dtlab-tech/ai-toolkit/commit/8c1f0ae92828e27b8a7ffb110eb35e27094b7006))
+* enhance project manager with feature registry checks for cross-feature analysis ([30eb5e5](https://github.com/dtlab-tech/ai-toolkit/commit/30eb5e50fc16501e9cc38a5b4a8264e3eac96e5d))
+* enhance project manager with feature registry checks for cross-feature analysis ([0d44ec3](https://github.com/dtlab-tech/ai-toolkit/commit/0d44ec35caa0460203c7c55d7eacff9320ef681f))
+* enhance SWF AI Toolkit guide with detailed introduction and context awareness ([60bb2b8](https://github.com/dtlab-tech/ai-toolkit/commit/60bb2b86f3915f9844b58e7eeb44e88ce3877a4c))
+* enhance SWF AI Toolkit guide with detailed introduction and context awareness ([f4ca293](https://github.com/dtlab-tech/ai-toolkit/commit/f4ca2938f6b4103785274018376ac2997e28cfc2))
+* enhance token tracking and reporting in project manager and implement feature workflow ([fa873b8](https://github.com/dtlab-tech/ai-toolkit/commit/fa873b82b84bd3b332b44c0e2dd458820defd502))
+* enhance token tracking and reporting in project manager and implement feature workflow ([92336ed](https://github.com/dtlab-tech/ai-toolkit/commit/92336edb3b523a5f5ed40d21b6fe38f7024ba322))
+* **FTR-001:** add token estimation to assessment pipeline ([2f8a630](https://github.com/dtlab-tech/ai-toolkit/commit/2f8a63077e79c09ac25b2d60c74946fc7d229282))
+* **FTR-001:** add token estimation to assessment pipeline ([93879ad](https://github.com/dtlab-tech/ai-toolkit/commit/93879ad00c60e9985424f07c104fa332883a4921))
+* **FTR-002:** Add assessment pipeline effort estimation documentation and process log ([873c28f](https://github.com/dtlab-tech/ai-toolkit/commit/873c28f925a820292a1dc68600b1ebf991336903))
+* **FTR-002:** Add assessment pipeline effort estimation documentation and process log ([30c891b](https://github.com/dtlab-tech/ai-toolkit/commit/30c891be8e337c63064982413570c1c4ade4d08f))
+* **FTR-003:** reduce assessment pipeline to read-only — findings gate replaces remediation gate ([681f6fc](https://github.com/dtlab-tech/ai-toolkit/commit/681f6fc6500514c21f03ae61ee82e788ff65a6c6))
+* **FTR-003:** reduce assessment pipeline to read-only — findings gate replaces remediation gate ([918ca26](https://github.com/dtlab-tech/ai-toolkit/commit/918ca2608e25d0ee2aa91b9047d921b7eaa5c021))
+* **FTR-004:** generate requirements, tech-spec, validation, and work breakdown docs ([5ba2da7](https://github.com/dtlab-tech/ai-toolkit/commit/5ba2da7bee2e7bde5136874f277f19ad83be8464))
+* **FTR-004:** implement INFRA + US-01 through US-03 — assessment registry write logic ([1989e38](https://github.com/dtlab-tech/ai-toolkit/commit/1989e38fc1b0ef5b40ff2e54cc83a2cd49e5c5d3))
+* **FTR-004:** implement US-04 through US-06 — test specification ([baad095](https://github.com/dtlab-tech/ai-toolkit/commit/baad09524d8c352330a024fc7a80e89c635c0fc8))
+* **FTR-004:** update project-manager token estimates to complete status ([959cc99](https://github.com/dtlab-tech/ai-toolkit/commit/959cc9921d470bfa874c5108f320848718d97c9a))
+* **FTR-005:** add /next-intervention and /check-interventions commands ([f744ad2](https://github.com/dtlab-tech/ai-toolkit/commit/f744ad2032abe936feff9ae67ddd863ba86511a1))
+* **FTR-006:** add assessment-aware PR description command to enhance context for intervention branches ([3023729](https://github.com/dtlab-tech/ai-toolkit/commit/302372919a2c07de313175c61f51000fcb2c99bc))
+* refactor Matt Pocock skills installation checks and simplify version handling ([58d3efd](https://github.com/dtlab-tech/ai-toolkit/commit/58d3efddf35b453cf25de701ed5f4b829d0a1a34))
+* refactor Matt Pocock skills installation checks and simplify version handling ([7de059e](https://github.com/dtlab-tech/ai-toolkit/commit/7de059e01fe5d71b75331732a833e00acfbb2a98))
+* rename help skill to hi-gaia and introduce Gaia as toolkit assistant ([4c7c6f4](https://github.com/dtlab-tech/ai-toolkit/commit/4c7c6f422c8f97b9e79361faed4c95ed5001322c))
+* rename help skill to hi-gaia and introduce Gaia as toolkit assistant ([c45fef0](https://github.com/dtlab-tech/ai-toolkit/commit/c45fef09a475dc795dfbbc12485e1ea01f4776d4))
+* update Azure pipeline to dynamically resolve NPM registry URL ([2c6a817](https://github.com/dtlab-tech/ai-toolkit/commit/2c6a81777475f9ed6ad3f9f4b42fe7e7b2ada67e))
+* update Azure pipeline to dynamically resolve NPM registry URL ([0f4601f](https://github.com/dtlab-tech/ai-toolkit/commit/0f4601fabb4b885dadc28e3f868feacdb97e474b))
+* update Matt Pocock skills check to verify 'grilling' skill presence ([47b0592](https://github.com/dtlab-tech/ai-toolkit/commit/47b0592be0438c2d5152030e95674f0d0c23bf9a))
+* update Matt Pocock skills check to verify 'grilling' skill presence ([d92d729](https://github.com/dtlab-tech/ai-toolkit/commit/d92d72946920c1cd9bf29f470a7a95b7bd84a254))
+* update package name and installation instructions to reflect new organization ([b67193a](https://github.com/dtlab-tech/ai-toolkit/commit/b67193a630e3bb95cc5b58e4ead1b914cc74b9dc))
+* update package name and installation instructions to reflect new organization ([0b09994](https://github.com/dtlab-tech/ai-toolkit/commit/0b09994220a563f1d3d12e5286be4a884af34aab))
+
+
+### Bug Fixes
+
+* add git tag on publish so conventional-changelog can read commit range ([6d4e427](https://github.com/dtlab-tech/ai-toolkit/commit/6d4e427d068da80d607db6e356cc79ea6e6ded9d))
+* add git tag on publish so conventional-changelog can read commit range ([114f558](https://github.com/dtlab-tech/ai-toolkit/commit/114f55871c8e5892b36754cad3ba5d88b082706a))
+* correct shell syntax in version bump commit message ([f988609](https://github.com/dtlab-tech/ai-toolkit/commit/f98860994d1cd3c4ef3d9b86aade6155e0ec6408))
+* correct shell syntax in version bump commit message ([8e25e16](https://github.com/dtlab-tech/ai-toolkit/commit/8e25e160496125387e4a69707b04c24739008c5c))
+* enhance NPM registry resolution by adding ADO_FEED_SCOPE variable ([2ff13e4](https://github.com/dtlab-tech/ai-toolkit/commit/2ff13e44510f507453136b5840d9dfc5c2afc3c5))
+* enhance NPM registry resolution by adding ADO_FEED_SCOPE variable ([77b79c6](https://github.com/dtlab-tech/ai-toolkit/commit/77b79c6f1836b71bf96e1b7457d1c1ca28324253))
+* **FTR-005:** address review warnings + add gate protocol to CLAUDE.md ([2e64780](https://github.com/dtlab-tech/ai-toolkit/commit/2e647809ba5279c492060dde52ab8134490fc59d))
+* pull --rebase before pushing version bump to avoid rejection ([cf751d0](https://github.com/dtlab-tech/ai-toolkit/commit/cf751d0984bdddc683dfc67e378b4f563c6cfbe2))
+* pull --rebase before pushing version bump to avoid rejection ([b70c748](https://github.com/dtlab-tech/ai-toolkit/commit/b70c74832f48e9261fbe894542de5977c3bcafa4))
+* remove project-specific references and fix stale artifact filenames ([c272354](https://github.com/dtlab-tech/ai-toolkit/commit/c2723549f1a3de4f099b85b44c87603b9c601e72))
+* remove project-specific references and fix stale artifact filenames ([1861fb9](https://github.com/dtlab-tech/ai-toolkit/commit/1861fb98708ce8ff8fcae7f5947f4e9dc9ba6937))
+* remove run_in_background from PM and assessment-manager — background notifications not delivered to sub-agent contexts ([29a7b97](https://github.com/dtlab-tech/ai-toolkit/commit/29a7b97649ad5798eaf96c5a1acabb214c0c0c96))
+* update installation instructions in README for clarity and completeness ([293a2dd](https://github.com/dtlab-tech/ai-toolkit/commit/293a2ddf0bebd386ba799ee24f6465b317897495))
+* update installation instructions in README for clarity and completeness ([d682026](https://github.com/dtlab-tech/ai-toolkit/commit/d6820268dc1a60d99e80162e262adaba2974f9f7))
+* update package references from [@denistomada](https://github.com/denistomada) to [@fincantieri](https://github.com/fincantieri) in README and installation documentation ([32ad6ae](https://github.com/dtlab-tech/ai-toolkit/commit/32ad6ae24db1719ad3cb1f4eea02bc11494cacd6))
+* update package references from [@denistomada](https://github.com/denistomada) to [@fincantieri](https://github.com/fincantieri) in README and installation documentation ([5854119](https://github.com/dtlab-tech/ai-toolkit/commit/585411991604acc06a85ecf5b8a9beffe1ef82a2))
+* update package.json to correct author and package name ([53dae47](https://github.com/dtlab-tech/ai-toolkit/commit/53dae47132da53e4fce98fdd683eb7acb4678b5a))
+* update package.json to correct author and package name ([81a6b7c](https://github.com/dtlab-tech/ai-toolkit/commit/81a6b7c1ebfe6fab632eb44ddc48c962efc69997))
+* update repository URL in package.json and remove publishConfig ([7f3dc15](https://github.com/dtlab-tech/ai-toolkit/commit/7f3dc15df57653bed00b139123396d5d2ba24d3e))
+* update repository URL in package.json and remove publishConfig ([b912958](https://github.com/dtlab-tech/ai-toolkit/commit/b9129582804758128f3e9dffdd8cd9302d4e529f))
+
 ## 0.1.3 (2026-07-14)

package/CLAUDE.md

@@ -51,6 +51,38 @@ An `AGENTS.md` file in the project root with:
 
 Generic procedures live in `docs/procedures/` in this toolkit. Projects can override any procedure by placing a file with the same name at `docs/procedures/` in their own root. Agents check the project first, then fall back to the toolkit.
 
+## Gate Protocol — MANDATORY RULES
+
+These rules apply in every session, without exception.
+
+### Launching the Project Manager
+
+**Always pass `run_in_background: false` when spawning the `project-manager` agent.**
+
+Running the PM in the background leaves the main loop free to act independently. This creates two parallel execution paths that will conflict. The PM must block the main loop until it reaches a gate and returns.
+
+### While the PM is running
+
+**Do nothing.** No file reads "to prepare", no file writes "to accelerate", no implementation "because it seems stuck". The only permitted actions are:
+
+- Receiving gate notifications and presenting them to the user
+- Responding to the user's status questions ("still running")
+- Sending messages to the PM via SendMessage if it is genuinely blocked and the user asks to unblock it
+
+If the PM produces relay agents that appear to do nothing useful, that is noise — not a signal that the PM is stuck. Wait.
+
+### Gate notifications are hard stops
+
+When any gate notification arrives (Gate 1, Gate 2, Findings Gate, or any **HARD STOP** in any agent output):
+
+1. Stop immediately — even if mid-turn
+2. Present the full gate content to the user
+3. Wait for explicit written approval before touching any file or spawning any agent
+
+This applies even if the PM appears stuck, in a relay loop, or the gate arrives while another tool call is in progress.
+
+---
+
 ## Skills (user-invocable, in `.claude/skills/`)
 
 ### Feature Delivery
@@ -90,6 +122,8 @@ Generic procedures live in `docs/procedures/` in this toolkit. Projects can over
 | Command | Purpose |
 |---------|---------|
 | `/assessment-status <prefix>` | Reports presence/state of all assessment artifacts (assessments, interventions, approvals, issues register) |
+| `/next-intervention [prefix]` | Finds the next un-actioned flagged intervention and suggests the `/define-feature` invocation to start on it |
+| `/check-interventions [prefix]` | Full reconciliation table: every intervention cross-referenced against the Index, on-disk files, and existing feature folders |
 
 ## Agents (spawnable subagents, in `.claude/agents/`)
 

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