@dtlabs/ai-toolkit 0.3.1 → 0.5.0

package/.claude/agents/install-toolkit.md

@@ -171,51 +171,7 @@ configuration is out of scope and risks clobbering the user's existing settings.
 
 ---
 
-## Step 5 — Matt Pocock Skills (version check + optional install/update)
-
-After copying the toolkit files, check the state of Matt Pocock's skills:
-
-1. **Detect installed version**: check if `~/.claude/skills/mattpocock/.version` exists and read it. If not found, try `npm list -g mattpocock --json` to get the cached version. If neither works, assume not installed.
-
-2. **Detect latest available version**: run `npm view mattpocock version` to get the current version on npm. If offline or unavailable, skip the version comparison.
-
-3. **Present the appropriate prompt** using `AskUserQuestion`:
-
-   **Not installed:**
-   ```
-   question: "Matt Pocock's skills are not installed. Install them now?"
-   description: "Includes define-feature, grilling, TDD, prototype, handoff, and more.
-                 Installs globally via: npx skills@latest add mattpocock/skills"
-   options:
-     - "Yes — install now"
-     - "No — skip (install manually later)"
-   ```
-
-   **Installed, update available (installed=vX, latest=vY):**
-   ```
-   question: "Matt Pocock skills v{installed} is installed. Update to v{latest}?"
-   options:
-     - "Yes — update now"
-     - "No — keep current version"
-   ```
-
-   **Already up to date:**
-   ```
-   question: "Matt Pocock skills v{installed} is already up to date. Re-install?"
-   options:
-     - "Yes — re-install"
-     - "No — skip"
-   ```
-
-4. If the user selects **Yes** (install or update), run:
-   ```bash
-   npx skills@latest add mattpocock/skills
-   ```
-   Report the outcome. If it fails, show the manual install command.
-
----
-
-## Step 6 — Compact Instructions opt-in
+## Step 5 — Compact Instructions opt-in
 
 The toolkit includes a `# Compact instructions` section for `~/.claude/CLAUDE.md` that guides Claude's auto-compaction (what to keep, what to drop) and enables proactive topic-change suggestions.
 
@@ -304,7 +260,6 @@ New files copied:    N
 Modified/overwritten: N
 Modified/kept:        N  (user chose to keep existing version)
 Unchanged (same):    N  (skipped silently)
-Matt Pocock skills: ✅ installed v{X} / ⬆️ updated v{old}→v{new} / ⏭ skipped / ✅ already up to date v{X}
 Spawn depth: ✅ CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=2+ present / ⚠️ MISSING — see action above
 Compact instructions: {compact_instructions_status}
 ──────────────────────────────────────────────────

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

@@ -93,16 +93,18 @@ Write {feature_dir}/{PREFIX}-Effort-Estimate.md with this format:
 | Human estimate | {human_estimate} (sequential, no parallelism) |
 | Agent estimate | {agent_estimate} (parallel dispatch, critical path only) |
 
-## Per-User-Story Breakdown
+## Per-Phase Breakdown
 
-| US | Title | Tasks | Domains | Est. hours |
-|----|-------|-------|---------|------------|
-{one row per US extracted from Section 4}
+| Phase | Title | Tasks | Domains | Est. Human | Est. Agent | Actual Human | Actual Agent |
+|-------|-------|-------|---------|-----------|-----------|-------------|-------------|
+{one row per phase (INFRA + each US) extracted from Section 4 of the Work Breakdown — use ~2h per BE task, ~1h per TEST task, ~30min per INFRA task for human estimate; agent estimate = human / 6 as baseline}
+| **Total** | | **{total_tasks}** | | **{human_estimate}** | **{agent_estimate}** | **—** | **—** |
 
 ## Notes
 - Human estimate assumes sequential execution with no parallelism.
-- Agent estimate assumes parallel dispatch of independent tasks within each phase.
-- Actual effort will be recorded in the Actuals section after implementation.
+- Agent estimate assumes parallel dispatch of independent tasks within each phase (critical path only).
+- Actual Human: filled in if a human developer performed or reviewed the implementation.
+- Actual Agent: filled in by pm-phase3 after implementation completes.
 
 TASK 3 — Write the Token-Estimate.md file.
 Write {feature_dir}/{PREFIX}-Token-Estimate.md with this format:
@@ -111,39 +113,43 @@ Write {feature_dir}/{PREFIX}-Token-Estimate.md with this format:
 
 ## Phase 1 — Documentation (Actuals)
 
-| Agent | Task | Model | Tokens (actual) |
-|-------|------|-------|----------------|
-| generate-requirements | Generate requirements from feature.md | haiku | ${phase1Tokens} (phase delta) |
-| generate-tech-spec | Generate tech spec from feature.md | haiku | (see phase delta) |
-| validate-feature-docs | Validate requirements + tech spec | haiku | (see phase delta) |
+| Agent | Task | Model | Tokens Est. | Tokens Actual |
+|-------|------|-------|------------|--------------|
+| generate-requirements | Generate requirements from feature.md | haiku | — | {phase1_req_tokens} |
+| generate-tech-spec | Generate tech spec from feature.md | haiku | — | {phase1_spec_tokens} |
+| validate-feature-docs | Validate requirements + tech spec | haiku | — | {phase1_val_tokens} |
+| **Phase 1 total** | | | **—** | **${phase1Tokens}** |
 
 ## Phase 2 — Work Breakdown (Actuals)
 
-| Agent | Task | Model | Tokens (actual) |
-|-------|------|-------|----------------|
-| generate-work-breakdown | Generate work breakdown from docs | haiku | ${phase1Tokens} (phase delta) |
+| Agent | Task | Model | Tokens Est. | Tokens Actual |
+|-------|------|-------|------------|--------------|
+| generate-work-breakdown | Generate work breakdown from docs | haiku | — | {wbTokens from above} |
+| **Phase 2 total** | | | **—** | **{wbTokens from above}** |
 
 ## Phase 3 — Implementation (Estimates)
 
 Estimates based on {total_tasks} tasks ({domain_breakdown}), {user_stories} User Stories.
-Token estimates use ~15,000 tokens per BE task, ~8,000 per TEST task, ~5,000 per INFRA task as baseline.
-
-| Agent | Task | Model | Tokens (estimated) |
-|-------|------|-------|-------------------|
-| implementation-orchestrator | Full implementation loop | sonnet | {estimated: total_tasks * 12000} |
-| review-solution (×{user_stories}) | Architect review per US | sonnet | {estimated: user_stories * 8000} |
-| remediation | Fix WARNING issues | sonnet | ~10,000 |
-| pr-and-registry | Push branch, create PR | sonnet | ~5,000 |
-| write-actuals | Update Token/Effort Estimate | sonnet | ~3,000 |
-
-## Grand Total (Estimate)
-
-| Phase | Tokens (estimated) | Notes |
-|-------|-------------------|-------|
-| Phase 1 — Documentation | ${phase1Tokens} | Actual (phase delta) |
-| Phase 2 — Work Breakdown | {wbTokens from above} | Actual (phase delta) |
-| Phase 3 — Implementation | {sum of phase 3 estimates} | Estimated |
-| **Total** | **{grand total}** | |
+Baseline: ~15,000 tokens/BE task, ~8,000/TEST task, ~5,000/INFRA task.
+
+| Agent | Task | Model | Tokens Est. | Tokens Actual |
+|-------|------|-------|------------|--------------|
+| developer-backend | Implement BE/INFRA tasks | sonnet | {estimated: be_tasks * 15000 + infra_tasks * 5000} | — |
+| developer-testing | Implement TEST tasks | sonnet | {estimated: test_tasks * 8000} | — |
+| review-solution (×{user_stories}) | Architect review per US | sonnet | {estimated: user_stories * 8000} | — |
+| remediation | Fix review issues | sonnet | ~10,000 | — |
+| pr-and-registry | Push branch, create PR | sonnet | ~5,000 | — |
+| write-actuals | Update Token/Effort Estimate | sonnet | ~3,000 | — |
+| **Phase 3 total** | | | **{sum of phase 3 estimates}** | **—** |
+
+## Grand Total
+
+| Phase | Tokens Est. | Tokens Actual |
+|-------|------------|--------------|
+| Phase 1 — Documentation | — | ${phase1Tokens} |
+| Phase 2 — Work Breakdown | — | {wbTokens from above} |
+| Phase 3 — Implementation | {sum of phase 3 estimates} | — |
+| **Total** | **{sum of phase 3 estimates}** | **{phase1Tokens + wbTokens} (partial)** |
 
 ---
 *Actuals will be appended by pm-phase3 after implementation completes.*

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

@@ -1,10 +1,10 @@
 export const meta = {
   name: 'pm-phase3',
-  description: 'Feature delivery phase 3: parse WB → dispatch specialist agents per US (developer-backend/frontend/testing + review-solution per US, max 2 rework cycles, git commit per US) → remediation → PR → Token-Estimate actuals → Effort-Estimate actuals.',
+  description: 'Feature delivery phase 3: parse WB → dispatch specialist agents per US (commit per phase) → single architect review → PR → actuals.',
   phases: [
-    { title: 'Parse',          detail: 'Parse Work Breakdown into structured implementation phases' },
-    { title: 'Implementation', detail: 'Dispatch developer agents per US, review, commit' },
-    { title: 'Remediation',    detail: 'Fix OPEN issues from Issues Register' },
+    { title: 'Parse',          detail: 'Parse Work Breakdown CSV into structured phases' },
+    { title: 'Implementation', detail: 'Dispatch developer agents per phase, commit each one' },
+    { title: 'Review',         detail: 'Single architect review on full feature diff' },
     { title: 'PR',             detail: 'Push branch, create PR, update registry' },
     { title: 'Actuals',        detail: 'Write Token-Estimate and Effort-Estimate actuals' },
   ],
@@ -17,12 +17,10 @@ const branchMatch = argStr.match(/--branch\s+(\S+)/)
 const branch      = branchMatch ? branchMatch[1] : null
 
 const tokenLedger = []
-const escalations = []
 
 // ── Parse Work Breakdown CSV (deterministic, no AI) ───────────────────────────
 phase('Parse')
 
-// Derive feature_dir and prefix from featurePath (e.g. "docs/features/FTR-004-.../feature.md")
 const featureDir  = featurePath.replace(/\/[^/]+$/, '')
 const prefixMatch = featureDir.match(/([A-Z]+-\d+)/)
 const prefix      = prefixMatch ? prefixMatch[1] : 'FTR-000'
@@ -30,22 +28,16 @@ const csvPath     = `${featureDir}/${prefix}-Work-Breakdown.csv`
 
 log(`Reading CSV: ${csvPath}`)
 
-const READ_SCHEMA = {
-  type: 'object',
-  properties: { content: { type: 'string' } },
-  required: ['content'],
-}
-
-const csvResult = await agent(
-  `Read the file at path: ${csvPath}\nReturn its full text content as the "content" field.`,
-  { label: 'read-wb-csv', phase: 'Parse', schema: READ_SCHEMA, model: 'haiku' }
+const csvContent = await agent(
+  `Read the file at path: ${csvPath}\nReturn ONLY the raw file contents, nothing else. No explanation, no formatting, no JSON wrapping — just the raw text of the file.`,
+  { label: 'read-wb-csv', phase: 'Parse', model: 'haiku' }
 )
 
 // Parse CSV into structured phases — pure JS, no AI
-const rows = csvResult.content
+const rows = csvContent
   .split('\n')
   .map(l => l.trim())
-  .filter(l => l && !l.startsWith('phase_id'))  // skip header and empty lines
+  .filter(l => l && !l.startsWith('phase_id'))
   .map(l => {
     const [phase_id, phase_title, commit_message, depends_on, task_id, task_title, domain, agent_type] = l.split('|')
     return { phase_id, phase_title, commit_message, depends_on: depends_on || '', task_id, task_title, domain, agent_type }
@@ -60,7 +52,7 @@ for (const row of rows) {
       phase_id:       row.phase_id,
       title:          row.phase_title,
       commit_message: row.commit_message,
-      depends_on:     row.depends_on.split(' ').filter(Boolean),  // [] for empty
+      depends_on:     row.depends_on.split(' ').filter(Boolean),
       impl_tasks:     [],
       test_tasks:     [],
     })
@@ -93,11 +85,9 @@ const allPhases = Array.from(phaseMap.values()).map(p => ({
 }))
 
 const wb = { prefix, feature_dir: featureDir, phases: allPhases }
-
 log(`CSV parsed: ${rows.length} tasks → ${wb.phases.length} phases for ${wb.prefix}`)
 
-// Build execution waves: phases whose dependencies are all satisfied can run in parallel.
-// Wave 0 = no deps, Wave 1 = depends only on Wave 0 phases, etc.
+// Build execution waves: phases whose dependencies are all satisfied run in parallel
 const buildWaves = (phases) => {
   const done   = new Set()
   const waves  = []
@@ -105,7 +95,6 @@ const buildWaves = (phases) => {
   while (remaining.length > 0) {
     const ready = remaining.filter(p => p.depends_on.every(d => done.has(d)))
     if (ready.length === 0) {
-      // Circular or unresolvable deps — run the rest sequentially to avoid deadlock
       waves.push(remaining)
       break
     }
@@ -119,131 +108,71 @@ const buildWaves = (phases) => {
 const waves = buildWaves(wb.phases)
 log(`Execution plan: ${waves.length} wave(s) — ${waves.map((w, i) => `wave${i+1}:[${w.map(p => p.phase_id).join(',')}]`).join(' ')}`)
 
-const prefix     = wb.prefix
-let phasesDone   = 0
-const usPassed   = []
-const usEscalated = []
-let issuesPath   = ''
-let issuesOpen   = 0
+let phasesDone = 0
+const usPassed = []
 
 // ── Implementation ────────────────────────────────────────────────────────────
 phase('Implementation')
 
-const REVIEW_SCHEMA = {
-  type: 'object',
-  properties: {
-    has_critical: { type: 'boolean' },
-    findings:     { type: 'string' },
-    issues_md:    { type: 'string' },
-  },
-  required: ['has_critical'],
-}
-
-// executePhase: runs impl_groups → test_groups → review → rework → commit for one phase
+// executePhase: impl_groups (parallel) → test_groups (parallel) → commit
+// No inline review — review runs once after all phases complete.
 const executePhase = async (implPhase) => {
   log(`Starting phase ${implPhase.phase_id}: ${implPhase.title}`)
 
-  let reworkCycle  = 0
-  let passed       = false
-  let lastFindings = ''
-
-  while (reworkCycle <= 2 && !passed) {
-    const reworkSuffix = reworkCycle > 0
-      ? ` -- REWORK CYCLE ${reworkCycle}: address these critical findings:\n${lastFindings}`
-      : ''
-
-    // Step 1 — impl groups in parallel (INFRA / BE / FE)
-    if (implPhase.impl_groups.length > 0) {
-      const beforeImpl = budget.spent()
-      await parallel(implPhase.impl_groups.map(group => () =>
-        agent(
-          `${featurePath} ${group.task_ids.join(',')}${reworkSuffix}`,
-          {
-            agentType: group.agent_type,
-            label:     `${group.agent_type}:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`,
-            phase:     'Implementation',
-          }
-        )
-      ))
-      const implTokens = budget.spent() - beforeImpl
-      tokenLedger.push({
-        agent: `${implPhase.impl_groups.map(g => g.agent_type).join('+')}:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`,
-        model: 'sonnet',
-        phase_delta_tokens: implTokens,
-      })
-      log(`Phase ${implPhase.phase_id} impl groups done — ${implTokens} tokens`)
-    }
-
-    // Step 2 — test groups in parallel (TEST) — after impl groups
-    if (implPhase.test_groups.length > 0) {
-      const beforeTest = budget.spent()
-      await parallel(implPhase.test_groups.map(group => () =>
-        agent(
-          `${featurePath} ${group.task_ids.join(',')}${reworkSuffix}`,
-          {
-            agentType: group.agent_type,
-            label:     `${group.agent_type}:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`,
-            phase:     'Implementation',
-          }
-        )
-      ))
-      const testTokens = budget.spent() - beforeTest
-      tokenLedger.push({
-        agent: `developer-testing:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`,
-        model: 'sonnet',
-        phase_delta_tokens: testTokens,
-      })
-      log(`Phase ${implPhase.phase_id} test groups done — ${testTokens} tokens`)
-    }
-
-    // Step 3 — review-solution
-    const beforeReview = budget.spent()
-    const review = await agent(
-      `${featurePath} --scope ${implPhase.phase_id}`,
-      {
-        agentType: 'review-solution',
-        label:     `review-solution:${implPhase.phase_id}`,
-        phase:     'Implementation',
-        schema:    REVIEW_SCHEMA,
-      }
-    )
-    const reviewTokens = budget.spent() - beforeReview
+  // Step 1 — impl groups in parallel (INFRA / BE / FE)
+  if (implPhase.impl_groups.length > 0) {
+    const beforeImpl = budget.spent()
+    await parallel(implPhase.impl_groups.map(group => () =>
+      agent(
+        `${featurePath} ${group.task_ids.join(',')}`,
+        {
+          agentType: group.agent_type,
+          label:     `${group.agent_type}:${implPhase.phase_id}`,
+          phase:     'Implementation',
+        }
+      )
+    ))
+    const implTokens = budget.spent() - beforeImpl
     tokenLedger.push({
-      agent: `review-solution:${implPhase.phase_id}`,
-      model: 'sonnet',
-      phase_delta_tokens: reviewTokens,
+      agent:              `${implPhase.impl_groups.map(g => g.agent_type).join('+')}:${implPhase.phase_id}`,
+      model:              'sonnet',
+      phase_delta_tokens: implTokens,
     })
-
-    if (review && !review.has_critical) {
-      passed = true
-      if (review.issues_md) {
-        await agent(
-          `Append the following WARNING/INFO findings to ${wb.feature_dir}/${prefix}-Issues.md (create the file if it does not exist, with a header "# Issues Register — ${prefix}"):\n\n${review.issues_md}`,
-          { label: `log-issues:${implPhase.phase_id}`, phase: 'Implementation' }
-        )
-      }
-    } else {
-      lastFindings = review?.findings || 'unspecified critical issues'
-      reworkCycle++
-      log(`Phase ${implPhase.phase_id}: critical findings — rework cycle ${reworkCycle}`)
-    }
+    log(`Phase ${implPhase.phase_id} impl done — ${implTokens} tokens`)
   }
 
-  if (!passed) {
-    log(`Phase ${implPhase.phase_id} ESCALATED after 2 rework cycles`)
-    escalations.push({ phaseId: implPhase.phase_id, reason: 'CRITICAL review findings unresolved after 2 rework cycles' })
-    usEscalated.push(implPhase.phase_id)
-  } else {
-    const commitMsg = implPhase.commit_message || `feat(${prefix}): implement ${implPhase.phase_id}`
-    await agent(
-      `Run these git commands in the repository root:\ngit add -A\ngit commit -m "${commitMsg}"\nIf there is nothing to commit, that is fine — just report success.`,
-      { label: `commit:${implPhase.phase_id}`, phase: 'Implementation' }
-    )
-    if (implPhase.phase_id !== 'INFRA') usPassed.push(implPhase.phase_id)
-    log(`Phase ${implPhase.phase_id} passed review and committed`)
+  // Step 2 — test groups in parallel (TEST)
+  if (implPhase.test_groups.length > 0) {
+    const beforeTest = budget.spent()
+    await parallel(implPhase.test_groups.map(group => () =>
+      agent(
+        `${featurePath} ${group.task_ids.join(',')}`,
+        {
+          agentType: group.agent_type,
+          label:     `developer-testing:${implPhase.phase_id}`,
+          phase:     'Implementation',
+        }
+      )
+    ))
+    const testTokens = budget.spent() - beforeTest
+    tokenLedger.push({
+      agent:              `developer-testing:${implPhase.phase_id}`,
+      model:              'sonnet',
+      phase_delta_tokens: testTokens,
+    })
+    log(`Phase ${implPhase.phase_id} tests done — ${testTokens} tokens`)
   }
 
+  // Step 3 — commit this phase
+  const commitMsg = implPhase.commit_message || `feat(${prefix}): implement ${implPhase.phase_id}`
+  await agent(
+    `Run these git commands in the repository root:\ngit add -A\ngit commit -m "${commitMsg}"\nIf there is nothing to commit, that is fine — just report success.`,
+    { label: `commit:${implPhase.phase_id}`, phase: 'Implementation', model: 'haiku' }
+  )
+
+  if (implPhase.phase_id !== 'INFRA') usPassed.push(implPhase.phase_id)
   phasesDone++
+  log(`Phase ${implPhase.phase_id} committed`)
 }
 
 // Execute waves: phases in the same wave run in parallel, waves are sequential
@@ -256,69 +185,57 @@ for (const wave of waves) {
   }
 }
 
-// Count open issues
-const ISSUES_SCHEMA = {
-  type: 'object',
-  properties: {
-    exists:     { type: 'boolean' },
-    open_count: { type: 'number' },
-    path:       { type: 'string' },
-  },
-  required: ['exists', 'open_count'],
-}
-const issuesResult = await agent(
-  `Check if ${wb.feature_dir}/${prefix}-Issues.md exists. If it does, count rows with status OPEN. Return exists, open_count, and the full path.`,
-  { label: 'count-open-issues', phase: 'Implementation', schema: ISSUES_SCHEMA }
-)
-issuesPath = issuesResult?.path || ''
-issuesOpen = issuesResult?.open_count || 0
-log(`Implementation complete — ${phasesDone} phases, ${usPassed.length} US passed, ${usEscalated.length} escalated, ${issuesOpen} open issues`)
+log(`Implementation complete — ${phasesDone} phases, ${usPassed.length} US implemented`)
 
-// ── Remediation ───────────────────────────────────────────────────────────────
-phase('Remediation')
+// ── Review — single pass over the full feature diff ───────────────────────────
+phase('Review')
 
-const REM_SCHEMA = {
+const REVIEW_SCHEMA = {
   type: 'object',
   properties: {
-    issues_fixed:    { type: 'number' },
-    issues_deferred: { type: 'number' },
+    has_critical:  { type: 'boolean' },
+    findings:      { type: 'string' },
+    issues_md:     { type: 'string' },
   },
-  required: ['issues_fixed', 'issues_deferred'],
+  required: ['has_critical'],
 }
 
-let issuesFixed    = 0
-let issuesDeferred = 0
-
-if (issuesOpen > 0 && issuesPath) {
-  log(`Remediation: ${issuesOpen} 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 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 }
+const beforeReview = budget.spent()
+const review = await agent(
+  `${featurePath} --scope all`,
+  {
+    agentType: 'review-solution',
+    label:     'review-solution:full-feature',
+    phase:     'Review',
+    schema:    REVIEW_SCHEMA,
+  }
+)
+const reviewTokens = budget.spent() - beforeReview
+tokenLedger.push({ agent: 'review-solution:full-feature', model: 'sonnet', phase_delta_tokens: reviewTokens })
 
-Update the Issues Register Status column in place for each resolved/deferred issue.`,
-    {
-      label:  'remediation',
-      phase:  'Remediation',
-      schema: REM_SCHEMA,
-    }
-  )
+let issuesOpen     = 0
+let issuesPath     = `${wb.feature_dir}/${prefix}-Issues.md`
+let hasCritical    = false
 
-  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} — ${remTokens} tokens`)
+if (review) {
+  hasCritical = review.has_critical || false
+  if (review.issues_md) {
+    await agent(
+      `Write the following content to ${issuesPath} (create or overwrite the file):\n\n# Issues Register — ${prefix}\n\n${review.issues_md}`,
+      { label: 'write-issues', phase: 'Review', model: 'haiku' }
+    )
+    // Count OPEN issues from issues_md (rough count of "OPEN" occurrences)
+    issuesOpen = (review.issues_md.match(/\bOPEN\b/g) || []).length
+    log(`Review complete — has_critical: ${hasCritical}, open issues: ${issuesOpen}`)
+  } else {
+    log(`Review complete — no issues found`)
+  }
 } else {
-  log('Remediation: no OPEN issues — skipped')
+  log(`Review agent returned null — skipping issues register`)
+}
+
+if (hasCritical) {
+  log(`WARNING: critical issues found — PR will be created but marked as blocked. Inspect ${prefix}-Issues.md before merging.`)
 }
 
 // ── PR ────────────────────────────────────────────────────────────────────────
@@ -341,39 +258,37 @@ const prResult = await agent(
 Feature path: ${featurePath}
 Branch: ${branch || 'current branch'}
 Prefix: ${prefix}
-Issues fixed: ${issuesFixed}, deferred: ${issuesDeferred}
+Critical issues found: ${hasCritical}
+Open issues: ${issuesOpen}
 
 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:
+1. Push the branch:
    git push -u origin ${branch || 'HEAD'}
 
-3. Create a PR targeting develop:
+2. 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)
+- Implements <Feature Title from feature.md> (${usPassed.length} User Stories, ${phasesDone} phases)
 - 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
+- Phases implemented: ${usPassed.join(', ') || 'N/A'}
+- Architect review: ${hasCritical ? '⚠️ CRITICAL issues found — see ' + prefix + '-Issues.md before merging' : '✅ No critical issues'}
+- Open issues: ${issuesOpen} → 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".
+3. Update the Feature Registry (internal_docs/features/REGISTRY.md):
+   Find or append the entry for ${prefix}. Set Status to "${hasCritical ? 'review-required' : 'completed'}".
 
 Return { "pr_url": "<url>", "registry_updated": true/false }.
-If the PR creation fails, return { "pr_url": "(PR creation failed)", "registry_updated": false }.`,
+If the PR already exists, return its URL. If creation fails, return { "pr_url": "(PR creation failed)", "registry_updated": false }.`,
   {
     label:  'pr-and-registry',
     phase:  'PR',
@@ -390,15 +305,6 @@ phase('Actuals')
 
 const totalPhase3Tokens = 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(
@@ -419,42 +325,56 @@ Append this section at the end of the file:
 
 ---
 
-## Actuals vs Estimate (pm-phase3)
+## Phase 3 — Implementation (Actuals)
 
 > Phase totals are exact measurements from budget tracking.
 > Per-agent values are exact where each agent ran separately; proportional where merged.
 
-| Agent | Phase | Model | Phase delta tokens |
-|-------|-------|-------|-------------------|
-${tokenLedger.map(e => `| ${e.agent} | — | ${e.model} | ${e.phase_delta_tokens} |`).join('\n')}
+| Agent | Phase | Model | Tokens Est. | Tokens Actual |
+|-------|-------|-------|------------|--------------|
+${tokenLedger.map(e => `| ${e.agent} | — | ${e.model} | — | ${e.phase_delta_tokens} |`).join('\n')}
+| **Phase 3 total** | | | **—** | **${totalPhase3Tokens}** |
+
+## Grand Total (updated)
 
-## Grand Total (pm-phase3)
+| Phase | Tokens Est. | Tokens Actual |
+|-------|------------|--------------|
+| Phase 1 — Documentation | — | *(see above)* |
+| Phase 2 — Work Breakdown | — | *(see above)* |
+| Phase 3 — Implementation | *(see above)* | ${totalPhase3Tokens} |
+
+## Implementation Summary
 
 | Metric | Value |
 |--------|-------|
-| Total tokens (pm-phase3) | ${totalPhase3Tokens} (exact) |
 | Implementation phases done | ${phasesDone} |
-| US passed | ${usPassed.join(', ') || 'N/A'} |
-| US escalated | ${usEscalated.join(', ') || 'none'} |
+| US implemented | ${usPassed.join(', ') || 'N/A'} |
+| Critical issues | ${hasCritical} |
+| Open issues | ${issuesOpen} |
+
+TASK 2 — Update actuals in ${prefix}-Effort-Estimate.md:
+Find the file in the feature directory. Read the existing Per-Phase Breakdown table and update
+the "Actual Agent" column for each phase that was implemented:
+- Phases implemented (${usPassed.join(', ') || 'none'} + INFRA): write "done (agent)"
+- Any phase not in the list: leave "—"
 
-TASK 2 — Append actuals to ${prefix}-Effort-Estimate.md:
-Find the file in the feature directory. Append:
+Also append this section at the end of the file:
 
 ---
 
-## Actuals vs Estimate
+## Implementation Summary
 
 | Metric | Estimated | Actual |
 |--------|-----------|--------|
 | Implementation phases | ${phasesDone} | ${phasesDone} |
-| Issues fixed | — | ${issuesFixed} |
-| Issues deferred | — | ${issuesDeferred} |
+| Critical review issues | — | ${hasCritical ? 'yes' : 'none'} |
+| Open issues | — | ${issuesOpen} |
 
 Return { "token_estimate_path": "<path>", "effort_estimate_path": "<path>" }.`,
   {
     label:  'write-actuals',
     phase:  'Actuals',
-    schema: ACTUALS_SCHEMA,
+    schema: { type: 'object', properties: { token_estimate_path: { type: 'string' }, effort_estimate_path: { type: 'string' } }, required: [] },
   }
 )
 
@@ -463,28 +383,22 @@ tokenLedger.push({ agent: 'write-actuals', model: 'sonnet', phase_delta_tokens:
 log(`Actuals written — ${actualsTokens} tokens`)
 
 // ── Append to process-log ─────────────────────────────────────────────────────
-const usPassed3    = usPassed.join(', ')    || 'none'
-const usEscalated3 = usEscalated.join(', ') || 'none'
 const phase3Events = [
   `APPROVAL GRANTED by user — Gate 2`,
   `pm-phase3 START — implementation phase — branch: ${branch || '(current)'}`,
   `WB parsed: ${wb.phases.length} phases`,
-  `Implementation DONE — ${phasesDone} phases | US passed: ${usPassed3} | US escalated: ${usEscalated3}`,
-  issuesFixed + issuesDeferred > 0
-    ? `Remediation: ${issuesFixed} fixed, ${issuesDeferred} deferred`
-    : `Remediation: skipped (no open issues)`,
+  `Implementation DONE — ${phasesDone} phases implemented: ${usPassed.join(', ') || 'none'}`,
+  `Review DONE — critical: ${hasCritical}, open issues: ${issuesOpen}`,
   `PR created: ${prResult.pr_url}`,
   `Actuals written: Token-Estimate.md + Effort-Estimate.md`,
   `RUN COMPLETE`,
   `════════════════════════════════════════════════════════`,
 ].join('\n')
 
-const featureDir3 = featurePath.replace(/\/[^/]+$/, '')
-
 await agent(
   `Append phase 3 events to the process-log for this feature delivery run.
 
-Process-log path: ${featureDir3}/${prefix}-process-log.txt
+Process-log path: ${featureDir}/${prefix}-process-log.txt
 
 Steps:
 1. Get current UTC datetime via Bash: run \`date -u +"%Y-%m-%dT%H:%M:%S"\`
@@ -494,16 +408,14 @@ Steps:
 
 Events to append:
 ${phase3Events}`,
-  { label: 'finalize-process-log', phase: 'Actuals' }
+  { label: 'finalize-process-log', phase: 'Actuals', model: 'haiku' }
 )
 
 return {
   pr_url:       prResult.pr_url,
   token_ledger: tokenLedger,
   issues_summary: {
-    escalations:        escalations.length,
-    escalation_details: escalations,
-    issues_fixed:       issuesFixed,
-    issues_deferred:    issuesDeferred,
+    has_critical: hasCritical,
+    open_issues:  issuesOpen,
   },
 }

package/CHANGELOG.md

@@ -1,4 +1,26 @@
 ## 0.1.4 (2026-07-21)
+## [0.5.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.4.0...v0.5.0) (2026-07-29)
+
+
+### Features
+
+* **pm-phase3:** Option C review architecture + estimate format improvements ([b385b3e](https://github.com/dtlab-tech/ai-toolkit/commit/b385b3e35ef9121b8d9008223c77c88291c4173a))
+
+## [0.4.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.3.1...v0.4.0) (2026-07-29)
+
+
+### Features
+
+* **effort-estimate:** add Est./Actual Human/Agent columns to Per-Phase Breakdown ([696146c](https://github.com/dtlab-tech/ai-toolkit/commit/696146cc583ca13ee18914af19ff4de87a91cb60))
+* FTR-010 unit tests, process-log, OPT-02/03/04, remove Matt Pocock dependency ([1f43a4e](https://github.com/dtlab-tech/ai-toolkit/commit/1f43a4e6bf98a4b5821f1a0ae2dac33aca090597))
+* **token-estimate:** split tokens into Est./Actual columns in pm-phase2 and pm-phase3 ([d85b6e4](https://github.com/dtlab-tech/ai-toolkit/commit/d85b6e4aa871a934190e1d65995cb8e7e8db4495))
+
+
+### Bug Fixes
+
+* **pm-phase3:** read CSV as raw string instead of schema-wrapped object ([1737842](https://github.com/dtlab-tech/ai-toolkit/commit/17378422f6a9dc9168a35c7114cdd227e9214ce8))
+* **pm-phase3:** remove duplicate const prefix declaration ([85455e8](https://github.com/dtlab-tech/ai-toolkit/commit/85455e83929ccc6274d7d888fd429fc83ad78137))
+
 ## [0.3.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.3.0...v0.3.1) (2026-07-28)
 
 

package/CLAUDE.global.md

@@ -0,0 +1,34 @@
+# AI Toolkit — Gate Protocol
+
+> Full catalog (Skills, Commands, Agents, Procedures): see `CLAUDE.md` in the project root,
+> or [`docs/reference.md`](docs/reference.md) for the cheatsheet.
+
+## 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.

package/CLAUDE.md

@@ -2,19 +2,7 @@
 
 A reusable set of AI agents and procedures for software feature delivery and codebase assessment — from requirements to PR, and from audit to remediation.
 
-> **Need a quick overview of what's available?** See [`docs/reference.md`](docs/reference.md) for the cheatsheet.
-
-## Dependencies
-
-This toolkit expects the **`define-feature`** agent from [Matt Pocock's skills package](https://github.com/mattpocock/skills) to be available. That agent is responsible for producing the `feature.md` input file that `/implement-feature` and all downstream agents consume.
-
-Install it with:
-
-```bash
-npx skills@latest add mattpocock/skills
-```
-
-> **Tip:** Install Matt's skills globally (`~/.claude/skills/`) so they are available in every project without repeating the setup.
+> **Full catalog of skills, commands, agents, and procedures:** [`docs/reference.md`](docs/reference.md)
 
 ## How it works
 
@@ -81,89 +69,17 @@ When any gate notification arrives (Gate 1, Gate 2, Findings Gate, or any **HARD
 
 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
-
-| Skill | Command | Purpose |
-|-------|---------|---------|
-| Install Toolkit | `/install-toolkit` | Copies all agents, skills, commands, and procedures into a destination project (no local toolkit repo needed) |
-| Init AGENTS.md | `/init-agents` | Analyzes a project codebase and generates the AGENTS.md convention file required by all developer agents |
-| Define Feature | `/define-feature` | Interviews you to define a new feature and writes `feature.md` — required input for `/implement-feature` |
-| Implement Feature | `/implement-feature` | Starts the full feature delivery pipeline: docs → approval → implement → review → PR |
-
-### Assessment & Remediation
-
-| Skill | Command | Purpose |
-|-------|---------|---------|
-| Assess Codebase | `/assess-codebase` | Starts the full assessment pipeline: parallel assessment → intervention docs → approval gate → remediation → review → PR |
-
-### General
-
-| Skill | Command | Purpose |
-|-------|---------|---------|
-| Gaia | `/hi-gaia [topic]` | Your toolkit assistant — introduces herself, explains pipelines, agents, and commands; helps you find the right tool for your situation |
-
-## Commands (slash shortcuts, in `.claude/commands/`)
-
-### Feature Delivery
-
-| Command | Purpose |
-|---------|---------|
-| `/feature-status <slug>` | Reports presence/state of feature.md, requirements, tech-spec, work-breakdown, and implementation progress |
-| `/check-docs <slug>` | Terse consistency check between feature docs — outputs only the inconsistencies |
-| `/pr-description` | Generates a PR description from the current branch commits + linked feature.md |
-| `/next-task [slug]` | Finds the next unblocked task in the work breakdown and suggests the agent to delegate it to |
-
-### Assessment & Remediation
-
-| 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/`)
-
-### Feature Delivery
-
-| Agent | subagent_type | Purpose |
-|-------|---------------|---------|
-| Install Toolkit | `install-toolkit` | Copies toolkit files into a destination project |
-| Init AGENTS.md | `init-agents-md` | Analyzes codebase and generates AGENTS.md |
-| Define Feature | `define-feature` | Interviews the user and writes `feature.md` in `docs/features/FTR-XXX-slug/` |
-| Generate Requirements | `generate-requirements` | Produces functional requirements from feature.md |
-| Generate Tech-Spec | `generate-tech-spec` | Produces technical specification from feature + requirements |
-| Validate Docs | `validate-feature-docs` | Cross-validates requirements + tech-spec against feature.md |
-| Generate Work Breakdown | `generate-work-breakdown` | Creates User Stories + tasks from approved docs |
-| Backend Developer | `developer-backend` | Implements backend tasks (DB, BE, INFRA domains) |
-| Frontend Developer | `developer-frontend` | Implements frontend tasks (FE domain) |
-| Testing Agent | `developer-testing` | Creates unit/integration tests (TEST domain) |
-| Review Solution | `review-solution` | Architect-level code review |
-| Project Manager | `project-manager` | Orchestrates the full feature delivery pipeline |
-
-### Assessment & Remediation
-
-| Agent | subagent_type | Purpose |
-|-------|---------------|---------|
-| Assessment Manager | `assessment-manager` | Orchestrates the assessment pipeline: parallel assessment → intervention docs → approval gate → effort/token estimates → summary |
-| Generic Software Assessment | `generic-software-assessment` | Broad quality analysis across architecture, security, testability, observability, DevOps |
-| Intervention Documentation Standard | `intervention-documentation-standard` | Generates structured, self-contained intervention documents from assessment findings |
-| God Class Decomposition | `god-class-decomposition` | Safe incremental decomposition of oversized classes and methods |
-| Domain Model Refactoring | `domain-model-refactoring` | Splits monolithic model files, introduces type hierarchies, aligns domain vocabulary |
-| Layered Architecture Assessment | `layered-architecture-assessment` | Audits layer boundary violations and namespace/package misalignment |
-| Dependency Injection Refactoring | `dependency-injection-refactoring` | Converts static/direct coupling to constructor-injected services |
-| Security Hardening | `security-hardening` | Input validation, parameterised queries, secret management, log sanitisation, TLS |
-| Dependency Supply Chain Security | `dependency-supply-chain-security` | Lock files, integrity verification, unused dependency audit, SCA in CI |
-| Concurrency Safety Assessment | `concurrency-safety-assessment` | Race conditions, shared mutable state, unsafe shutdown patterns |
-
-## Available procedures (in `docs/procedures/`)
-
-| Procedure | Purpose |
-|-----------|---------|
-| `code-generation.md` | Step-by-step workflow for generating/modifying code |
-| `code-review.md` | Checklist and process for reviewing code |
-| `secure-coding.md` | Security checklist for auth/data handling |
-| `testing.md` | Strategy and guidelines for writing tests |
+## Compact instructions
+
+When compacting this conversation, preserve:
+- Current objective and which pipeline step we are on
+- User decisions and approvals (Gate 1, Gate 2, Findings Gate)
+- Files created or modified this session
+- Open errors or blockers
+- Feature/assessment prefix IDs and artifact paths (e.g. FTR-010, ASSESS-001)
+
+Discard:
+- Raw grep/glob/read output that has already been acted on
+- Successful tool-call results that produced no follow-up action
+- Repeated explanations of the same concept
+- Superseded plans or approaches

package/bin/cli.js

@@ -225,53 +225,6 @@ async function runInstall(label, mappings, force) {
   );
 }
 
-// ── Matt Pocock skills ───────────────────────────────────────────────────────
-
-function isMattPocockInstalled() {
-  const homedir = require('os').homedir();
-  // 'grilling' is a skill exclusive to Matt Pocock's package — not included in this toolkit
-  const pathsToCheck = [
-    path.join(homedir, '.claude', 'skills', 'grilling', 'SKILL.md'),
-    path.join(process.cwd(), '.claude', 'skills', 'grilling', 'SKILL.md'),
-  ];
-  return pathsToCheck.some(p => fs.existsSync(p));
-}
-
-async function installMattPocock() {
-  const { execSync } = require('child_process');
-  console.log(`\n  ${clr('cyan', '↓')}  Running: ${dim('npx skills@latest add mattpocock/skills')}\n`);
-  try {
-    execSync('npx skills@latest add mattpocock/skills', { stdio: 'inherit' });
-    console.log(`\n  ${clr('green', '✔')}  Matt Pocock skills installed successfully.\n`);
-  } catch (err) {
-    console.error(`\n  ${clr('red', '✖')}  Install failed: ${err.message}`);
-    console.error(`     Run manually: ${dim('npx skills@latest add mattpocock/skills')}\n`);
-  }
-}
-
-async function askMattPocock() {
-  const installed = isMattPocockInstalled();
-
-  console.log(divider());
-  console.log(bold('  Matt Pocock Skills'));
-  console.log(divider());
-  console.log(`  ${dim('Includes: define-feature, grilling, TDD, prototype, handoff, and more.')}`);
-  console.log();
-
-  if (!installed) {
-    console.log(`  ${clr('gray', '○')}  Status : ${clr('gray', 'not installed')}\n`);
-    const ok = await askConfirm('Install Matt Pocock\'s skills now?');
-    if (ok) await installMattPocock();
-    else console.log(`\n  ${clr('gray', 'Skipped. Install later with: npx skills@latest add mattpocock/skills')}\n`);
-    return;
-  }
-
-  console.log(`  ${clr('green', '✔')}  Status : ${clr('green', 'installed')}\n`);
-  const ok = await askConfirm('Re-install / update Matt Pocock skills?');
-  if (ok) await installMattPocock();
-  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';
@@ -334,7 +287,6 @@ async function installLocal(targetDir, force) {
   writeInstalledVersion(targetDir);
   console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
   checkSpawnDepth(targetDir);
-  await askMattPocock();
   console.log(divider());
   console.log(`\n  ${bold('Next steps:')}`);
   console.log(`  ${clr('cyan', '1.')} Run ${clr('cyan', '/init-agents')} to generate AGENTS.md`);
@@ -355,13 +307,12 @@ async function installGlobal(force) {
       { 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') },
+      { src: path.join(packageRoot, 'CLAUDE.global.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:')}`);
     console.log(`  ${clr('cyan', '1.')} The toolkit is now available in all your projects`);
@@ -419,7 +370,6 @@ if (require.main === module) {
     expandMappings,
     categorize,
     readInstalledVersion,
-    isMattPocockInstalled,
     NEVER_COPY,
   };
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",
     "CLAUDE.md",
     "CHANGELOG.md",
     "README.md",
+    "CLAUDE.global.md",
     ".claude",
     "bin"
   ],