@dtlabs/ai-toolkit 0.1.7 → 0.2.1

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

@@ -0,0 +1,166 @@
+export const meta = {
+  name: 'am-phase2',
+  description: 'Assessment pipeline phase 2: write Approvals file → update Assessment Registry → return summary. Runs after Findings Gate is completed in the main loop.',
+  phases: [
+    { title: 'Approvals', detail: 'Write {PREFIX}-Approvals.md with gate acknowledgement and flagged interventions' },
+    { title: 'Registry',  detail: 'Append row to docs/assessments/registry.md' },
+    { title: 'Summary',   detail: 'Build and return run summary' },
+  ],
+}
+
+// args: "--prefix ASSESS-NNN --output-dir <path> --flagged INT-001,INT-003 --ack \"text\""
+const argStr = typeof args === 'string' ? args : ''
+
+const prefixMatch    = argStr.match(/--prefix\s+(\S+)/)
+const outputDirMatch = argStr.match(/--output-dir\s+(\S+)/)
+const flaggedMatch   = argStr.match(/--flagged\s+([^\s"]+)/)
+const ackMatch       = argStr.match(/--ack\s+"([^"]*)"/)
+
+const prefix    = prefixMatch    ? prefixMatch[1]    : 'ASSESS-001'
+const outputDir = outputDirMatch ? outputDirMatch[1] : `docs/assessments/${prefix}`
+const flaggedRaw = flaggedMatch  ? flaggedMatch[1]   : 'none'
+const ackText    = ackMatch      ? ackMatch[1]        : 'Acknowledged'
+
+const flaggedIds = flaggedRaw.toLowerCase() === 'none'
+  ? []
+  : flaggedRaw.split(',').map(s => s.trim().toUpperCase())
+
+// ── Approvals ─────────────────────────────────────────────────────────────────
+phase('Approvals')
+
+const APPROVALS_SCHEMA = {
+  type: 'object',
+  properties: {
+    approvals_path: { type: 'string' },
+    written:        { type: 'boolean' },
+  },
+  required: ['approvals_path', 'written'],
+}
+
+log(`Writing Approvals file for ${prefix} — flagged: ${flaggedIds.join(', ') || 'none'}`)
+
+const approvalsResult = await agent(
+  `Write the Approvals file for assessment ${prefix}.
+
+Output path: ${outputDir}/${prefix}-Approvals.md
+
+Read the Interventions Index at: ${outputDir}/${prefix}-Interventions-Index.md
+Extract all INT-NNN identifiers and their titles.
+
+Flagged interventions (to mark as Yes): ${flaggedIds.join(', ') || 'none'}
+Acknowledgement text: "${ackText}"
+Today's date: use the current date in YYYY-MM-DD format.
+
+Write the file with this exact structure:
+
+# Assessment Approvals — ${prefix}
+
+## Findings Gate Acknowledgement
+
+| Field | Value |
+|-------|-------|
+| Acknowledged by | Toolkit user |
+| Date | {today} |
+| Acknowledgement | ${ackText} |
+
+## Interventions Flagged for Feature Delivery
+
+| Intervention | Flagged | Date | Notes |
+|---|---|---|---|
+{one row per intervention: | INT-NNN — {title} | Yes/No | {today} | — or "Not selected" |}
+
+Rules:
+- Mark "Yes" for interventions whose ID is in: ${flaggedIds.join(', ') || '(none)'}
+- Mark "No" for all others, Notes = "Not selected"
+- "Flagged" column values must be exactly "Yes" or "No" (case-sensitive)
+
+After writing, verify the file exists and is non-empty.
+Return { "approvals_path": "<full path>", "written": true }.`,
+  {
+    label:  'write-approvals',
+    phase:  'Approvals',
+    schema: APPROVALS_SCHEMA,
+  }
+)
+
+log(`Approvals written: ${approvalsResult.approvals_path}`)
+
+// ── Registry ──────────────────────────────────────────────────────────────────
+phase('Registry')
+
+const REGISTRY_SCHEMA = {
+  type: 'object',
+  properties: {
+    registry_result: { type: 'string' },
+  },
+  required: ['registry_result'],
+}
+
+log(`Updating Assessment Registry`)
+
+const registryResult = await agent(
+  `Update the Assessment Registry at: docs/assessments/registry.md
+
+Prefix: ${prefix}
+Output directory: ${outputDir}
+
+STEP 1 — Read severity counts from ${outputDir}/${prefix}-Interventions-Index.md.
+Count rows by Criticality column: CRITICAL, HIGH, MEDIUM, LOW, compute total.
+
+STEP 2 — Count flagged interventions from ${outputDir}/${prefix}-Approvals.md.
+Find the "## Interventions Flagged for Feature Delivery" section.
+Count rows where the Flagged column value is exactly "Yes" (case-sensitive).
+
+STEP 3 — Build the registry row:
+| {today-YYYY-MM-DD} | [${prefix}](${prefix}/) | {total} | {CRITICAL} | {HIGH} | {MEDIUM} | {LOW} | {flagged_count} |
+
+STEP 4 — Write to docs/assessments/registry.md:
+- If the file does not exist: create it with header + the new row:
+  # Assessment Registry
+  | Date | Prefix | Total | CRITICAL | HIGH | MEDIUM | LOW | Flagged |
+  |------|--------|-------|----------|------|--------|-----|---------|
+  {row}
+- If the file exists: read it, strip trailing whitespace, append the new row, write back.
+
+STEP 5 — Verify the file is readable after writing.
+
+Return { "registry_result": "docs/assessments/registry.md [created]" }
+  or    { "registry_result": "docs/assessments/registry.md [updated — row N appended]" }
+  or    { "registry_result": "docs/assessments/registry.md [ERROR — {reason}]" }`,
+  {
+    label:  'update-registry',
+    phase:  'Registry',
+    schema: REGISTRY_SCHEMA,
+  }
+)
+
+log(`Registry: ${registryResult.registry_result}`)
+
+// ── Summary ───────────────────────────────────────────────────────────────────
+phase('Summary')
+
+const summaryText = [
+  `Assessment Manager — Run Summary`,
+  `─────────────────────────────────────────────────────`,
+  `Target: ${argStr.split('--')[0].trim() || '.'}  |  Prefix: ${prefix}`,
+  `─────────────────────────────────────────────────────`,
+  `Approvals:           ${approvalsResult.approvals_path}`,
+  `Registry:            ${registryResult.registry_result}`,
+  `Effort Estimate:     ${outputDir}/${prefix}-Effort-Estimate.md`,
+  `Token Estimate:      ${outputDir}/${prefix}-Token-Estimate.md`,
+  `Process log:         ${outputDir}/${prefix}-process-log.txt`,
+  `─────────────────────────────────────────────────────`,
+  `Flagged interventions (${flaggedIds.length}): ${flaggedIds.join(', ') || 'none'}`,
+  `Flagged interventions can be actioned via /define-feature`,
+  `referencing the INT-NNN document.`,
+  `─────────────────────────────────────────────────────`,
+].join('\n')
+
+log('am-phase2 complete')
+
+return {
+  approvals_path:   approvalsResult.approvals_path,
+  registry_updated: registryResult.registry_result,
+  flagged_count:    flaggedIds.length,
+  summary:          summaryText,
+}

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

@@ -0,0 +1,164 @@
+export const meta = {
+  name: 'pm-phase1',
+  description: 'Feature delivery phase 1: discovery → generate-requirements → generate-tech-spec → validate-feature-docs (revision loop) → Effort-Estimate stub. Returns gate1_payload.',
+  phases: [
+    { title: 'Discovery', detail: 'Read feature.md, check existing outputs' },
+    { title: 'Requirements', detail: 'Run generate-requirements' },
+    { title: 'Tech-Spec', detail: 'Run generate-tech-spec' },
+    { title: 'Validation', detail: 'Run validate-feature-docs (revision loop, max 3×)' },
+  ],
+}
+
+// ── Parse args ────────────────────────────────────────────────────────────────
+// args is the raw prompt string: "<path-to-feature.md> [--force]"
+const featurePath = args.split(/\s+/)[0]
+const force       = typeof args === 'string' && args.includes('--force')
+
+// ── Discovery ─────────────────────────────────────────────────────────────────
+phase('Discovery')
+
+const discoveryResult = await agent(
+  `You are a discovery agent for the feature delivery pipeline.
+
+Read the feature.md file at: ${featurePath}
+
+Extract:
+1. The feature PREFIX from the directory name (pattern [A-Z]+-[0-9]+, e.g. FTR-009)
+2. The feature directory path (parent of feature.md)
+3. Whether these files exist and are NOT stale vs feature.md (stale = older mtime):
+   - {PREFIX}-Requirements.md
+   - {PREFIX}-Tech-Spec.md
+   - {PREFIX}-Validation-Report.md
+
+Return a JSON object:
+{
+  "prefix": "FTR-009",
+  "feature_dir": "internal_docs/features/FTR-009-workflow-orchestrators",
+  "needs_requirements": true,
+  "needs_tech_spec": true,
+  "needs_validation": true,
+  "force": ${force}
+}
+
+If force=true, set all needs_* to true regardless of file state.
+If feature.md does not exist, return { "error": "feature.md not found: ${featurePath}" }.`,
+  {
+    label: 'discovery',
+    phase: 'Discovery',
+    schema: {
+      type: 'object',
+      properties: {
+        prefix:             { type: 'string' },
+        feature_dir:        { type: 'string' },
+        needs_requirements: { type: 'boolean' },
+        needs_tech_spec:    { type: 'boolean' },
+        needs_validation:   { type: 'boolean' },
+        force:              { type: 'boolean' },
+        error:              { type: 'string' },
+      },
+      required: ['prefix', 'feature_dir'],
+    },
+  }
+)
+
+if (discoveryResult.error) {
+  return { error: discoveryResult.error }
+}
+
+const { prefix, feature_dir } = discoveryResult
+
+log(`Prefix: ${prefix} | Dir: ${feature_dir}`)
+log(`needs_requirements=${discoveryResult.needs_requirements} needs_tech_spec=${discoveryResult.needs_tech_spec}`)
+
+// ── generate-requirements ─────────────────────────────────────────────────────
+phase('Requirements')
+
+const tokenLedger = []
+const errors      = []
+
+if (discoveryResult.needs_requirements) {
+  const beforeReq = budget.spent()
+  const reqResult = await agent(featurePath, { agentType: 'generate-requirements', label: 'generate-requirements', phase: 'Requirements' })
+  const reqTokens = budget.spent() - beforeReq
+  tokenLedger.push({ agent: 'generate-requirements', model: 'haiku', phase_delta_tokens: reqTokens })
+  log(`generate-requirements done — phase delta: ${reqTokens} tokens`)
+} else {
+  log('generate-requirements: fresh — skipped')
+}
+
+// ── generate-tech-spec ────────────────────────────────────────────────────────
+phase('Tech-Spec')
+
+if (discoveryResult.needs_tech_spec) {
+  const beforeSpec = budget.spent()
+  const specResult = await agent(featurePath, { agentType: 'generate-tech-spec', label: 'generate-tech-spec', phase: 'Tech-Spec' })
+  const specTokens = budget.spent() - beforeSpec
+  tokenLedger.push({ agent: 'generate-tech-spec', model: 'haiku', phase_delta_tokens: specTokens })
+  log(`generate-tech-spec done — phase delta: ${specTokens} tokens`)
+} else {
+  log('generate-tech-spec: fresh — skipped')
+}
+
+// ── validate-feature-docs (revision loop, max 3 cycles) ──────────────────────
+phase('Validation')
+
+let validationSummary = 'skipped'
+const MAX_CYCLES = 3
+
+for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
+  log(`validate-feature-docs cycle ${cycle}`)
+  const beforeVal = budget.spent()
+  const valResult = await agent(featurePath, { agentType: 'validate-feature-docs', label: `validate-feature-docs (cycle ${cycle})`, phase: 'Validation' })
+  const valTokens = budget.spent() - beforeVal
+  tokenLedger.push({ agent: `validate-feature-docs (cycle ${cycle})`, model: 'haiku', phase_delta_tokens: valTokens })
+
+  // valResult is the agent's text output — check for gap indicators
+  // Use only 'MISSING:' as the gap signal: 'gaps found' also matches 'ZERO GAPS FOUND'
+  const resultText = typeof valResult === 'string' ? valResult : JSON.stringify(valResult)
+  const hasGaps    = resultText.includes('MISSING:')
+
+  if (!hasGaps) {
+    validationSummary = `0 gaps (clean on cycle ${cycle})`
+    log(`Validation clean on cycle ${cycle}`)
+    break
+  }
+
+  log(`Validation cycle ${cycle}: gaps found`)
+
+  if (cycle < MAX_CYCLES) {
+    // Re-run failing docs before next validation cycle
+    if (resultText.includes('Requirements')) {
+      await agent(featurePath, { agentType: 'generate-requirements', label: `generate-requirements (revision ${cycle})`, phase: 'Validation' })
+    }
+    if (resultText.includes('Tech-Spec')) {
+      await agent(featurePath, { agentType: 'generate-tech-spec', label: `generate-tech-spec (revision ${cycle})`, phase: 'Validation' })
+    }
+  } else {
+    validationSummary = 'gaps remain after 3 cycles'
+    errors.push('validate-feature-docs: gaps remain after 3 revision cycles')
+  }
+}
+
+// ── Build gate1_payload ───────────────────────────────────────────────────────
+const gate1Payload = {
+  prefix,
+  feature_dir,
+  feature_path: featurePath,
+  requirements: {
+    path:    `${feature_dir}/${prefix}-Requirements.md`,
+    summary: `${prefix}-Requirements.md — generated`,
+  },
+  tech_spec: {
+    path:    `${feature_dir}/${prefix}-Tech-Spec.md`,
+    summary: `${prefix}-Tech-Spec.md — generated`,
+  },
+  validation: {
+    path:    `${feature_dir}/${prefix}-Validation-Report.md`,
+    summary: validationSummary,
+  },
+  token_ledger: tokenLedger,
+  errors,
+}
+
+log(`pm-phase1 complete — gate1_payload ready`)
+return gate1Payload

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:                [],
+}