@dtlabs/ai-toolkit 0.12.0 → 0.14.0

package/lib/workflow-artifacts.js

@@ -0,0 +1,102 @@
+'use strict';
+
+function cell(value) { return String(value ?? '—').replace(/\|/g, '\\|').replace(/[\r\n]/g, ' '); }
+function table(headers, rows) {
+  return [headers, headers.map(() => '---'), ...rows].map(row => '| ' + row.map(cell).join(' | ') + ' |').join('\n') + '\n';
+}
+function pricing(control) {
+  if (!control.exists('docs/token-pricing.json')) return null;
+  const value = control.json('docs/token-pricing.json');
+  if (!value || !value.models || !Number.isFinite(value.usd_to_eur) || value.usd_to_eur <= 0) throw new Error('Invalid token pricing');
+  return value;
+}
+function cost(tokens, model, rates) {
+  if (!rates || !Number.isFinite(tokens)) return null;
+  const rate = rates.models[model];
+  if (!rate || ![rate.input_per_1m_usd, rate.output_per_1m_usd].every(v => Number.isFinite(v) && v >= 0)) throw new Error('Invalid model pricing: ' + model);
+  return tokens * (0.8 * rate.input_per_1m_usd + 0.2 * rate.output_per_1m_usd) / 1000000 * rates.usd_to_eur;
+}
+function tokensDocument(c, prefix) {
+  const rates = pricing(c);
+  return `# Token Estimate — ${prefix}\n\nActuals for this invocation only; previous phases remain in the ledger. Missing usage is unavailable, not zero. Costs use an estimated 80/20 input/output split.\n\n` +
+    table(['Agent', 'Model', 'Tokens Actual', 'Estimated cost EUR'], c.tokenLedger.map(e => [e.agent, e.model, e.phase_delta_tokens, cost(e.phase_delta_tokens, e.model, rates)?.toFixed(4)]));
+}
+function estimates(c, dir, prefix, wb) {
+  if (!wb || !Array.isArray(wb.phases) || !wb.phases.length) throw new Error('Invalid Work Breakdown phases');
+  const tasks = wb.phases.flatMap(p => { if (!Array.isArray(p.tasks)) throw new Error('Invalid phase tasks'); return p.tasks; });
+  const rates = { BE: 120, TEST: 60, INFRA: 30, FE: 90, DB: 90, DevOps: 30 };
+  const domains = {};
+  for (const t of tasks) { if (!Object.hasOwn(rates, t.domain)) throw new Error('Unknown task domain'); domains[t.domain] = (domains[t.domain] || 0) + 1; }
+  const human = list => list.reduce((n, t) => n + rates[t.domain], 0);
+  const minutes = human(tasks);
+  const human_estimate = `~${Math.floor(minutes / 60)}h ${minutes % 60}min`;
+  const agentMinutes = tasks.every(t => Number.isFinite(t.estimate?.agentMinutes)) ? tasks.reduce((n, t) => n + t.estimate.agentMinutes, 0) : null;
+  const agent_estimate = agentMinutes == null ? 'unavailable' : `${agentMinutes}min (sequential estimate)`;
+  const base = `${dir}/${prefix}`;
+  const metrics = { prefix, feature_dir: dir, feature_title: wb.title || wb.feature || prefix,
+    total_tasks: tasks.length, user_stories: wb.phases.filter(p => p.id.startsWith('US-')).length,
+    domain_breakdown: Object.entries(domains).map(([d, n]) => `${d}: ${n}`).join(', '),
+    implementation_phases: wb.phases.length, human_estimate, agent_estimate,
+    work_breakdown_path: `${base}-Work-Breakdown.json`, tasks_csv_path: `${base}-Work-Breakdown.csv`,
+    effort_estimate_path: `${base}-Effort-Estimate.md`, token_estimate_path: `${base}-Token-Estimate.md` };
+  c.write(metrics.effort_estimate_path, `# Effort Estimate — ${prefix} — ${cell(metrics.feature_title)}\n\n` +
+    table(['Metric', 'Value'], [['User Stories', metrics.user_stories], ['Total tasks', tasks.length], ['Human estimate', human_estimate], ['Agent estimate', agent_estimate]]) +
+    '\n## Per-Phase Breakdown\n\n' + table(['Phase', 'Title', 'Tasks', 'Est. Human minutes', 'Actual Human', 'Actual Agent'],
+      wb.phases.map(p => [p.id, p.title, p.tasks.length, human(p.tasks), '—', '—'])));
+  c.write(metrics.token_estimate_path, tokensDocument(c, prefix));
+  return metrics;
+}
+function interventions(c, dir, prefix) {
+  const raw = c.read(`${dir}/${prefix}-Interventions-Index.md`);
+  const lines = raw.split(/\r?\n/).filter(l => l.trim().startsWith('|'));
+  const split = line => line.trim().replace(/^\||\|$/g, '').split(/(?<!\\)\|/).map(s => s.trim());
+  const headerAt = lines.findIndex(l => split(l).some(v => /^(Criticality|Severity)$/i.test(v)));
+  if (headerAt < 0) throw new Error('Interventions index missing Criticality column');
+  const headers = split(lines[headerAt]), severityAt = headers.findIndex(v => /^(Criticality|Severity)$/i.test(v));
+  const rows = [];
+  for (const line of lines.slice(headerAt + 1)) {
+    const values = split(line);
+    if (values.every(v => /^:?-+:?$/.test(v))) continue;
+    const id = line.match(/\bINT-\d+\b/);
+    if (!id) continue;
+    const severity = values[severityAt]?.replace(/\*/g, '').toUpperCase();
+    if (!['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].includes(severity)) throw new Error('Unknown intervention severity: ' + severity);
+    if (rows.some(r => r.id === id[0])) throw new Error('Duplicate intervention ID: ' + id[0]);
+    rows.push({ id: id[0], severity });
+  }
+  return rows;
+}
+function assessmentEstimates(c, dir, prefix) {
+  const rows = interventions(c, dir, prefix);
+  const severity_counts = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+  const rates = { CRITICAL: 8, HIGH: 4, MEDIUM: 2, LOW: 1 };
+  rows.forEach(r => severity_counts[r.severity]++);
+  const hours = rows.reduce((n, r) => n + rates[r.severity], 0);
+  const base = `${dir}/${prefix}`;
+  c.write(`${base}-Token-Estimate.md`, tokensDocument(c, prefix));
+  c.write(`${base}-Effort-Estimate.md`, `# Effort Estimate — ${prefix}\n\n` +
+    table(['Severity', 'Count', 'Hours each', 'Subtotal hours'], Object.entries(severity_counts).map(([s, n]) => [s, n, rates[s], n * rates[s]])) + `\nTotal: ${hours} human hours (estimate).\n`);
+  return { severity_counts, total_interventions: rows.length, remediation_hours_est: hours,
+    interventions_index_path: `${base}-Interventions-Index.md`, effort_estimate_path: `${base}-Effort-Estimate.md`, token_estimate_path: `${base}-Token-Estimate.md` };
+}
+function recordAssessmentApproval(c, dir, prefix, ack, flagged) {
+  const rows = interventions(c, dir, prefix);
+  const selected = flagged === 'none' ? [] : flagged.split(',').map(s => s.trim());
+  for (const id of selected) if (!rows.some(r => r.id === id)) throw new Error('Unknown flagged intervention: ' + id);
+  const today = new Date().toISOString().slice(0, 10), approvals_path = `${dir}/${prefix}-Approvals.md`;
+  const content = `# Assessment Approvals — ${prefix}\n\n## Findings Gate Acknowledgement\n\n` +
+    table(['Field', 'Value'], [['Acknowledged by', 'Toolkit user'], ['Date', today], ['Acknowledgement', ack]]) +
+    '\n## Interventions Flagged for Feature Delivery\n\n' + table(['Intervention', 'Flagged', 'Date', 'Notes'], rows.map(r => [r.id, selected.includes(r.id) ? 'Yes' : 'No', today, selected.includes(r.id) ? '—' : 'Not selected']));
+  c.write(approvals_path, content);
+  if (c.read(approvals_path) !== content) throw new Error('Approval readback mismatch');
+  const registryPath = 'docs/assessments/registry.md';
+  const header = '# Assessment Registry\n\n' + table(['Date', 'Prefix', 'Total', 'CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'Flagged'], []);
+  const old = c.exists(registryPath) ? c.read(registryPath) : header;
+  const row = `| ${today} | [${prefix}](${prefix}/) | ${rows.length} | ` +
+    ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].map(s => rows.filter(r => r.severity === s).length).join(' | ') + ` | ${selected.length} |`;
+  c.write(registryPath, old.split('\n').filter(l => !l.includes(`[${prefix}](`)).join('\n').trimEnd() + '\n' + row + '\n');
+  c.read(registryPath);
+  return { approvals_path, registry_updated: registryPath, flagged_count: selected.length, summary: `${prefix}: ${selected.length} interventions selected` };
+}
+
+module.exports = { estimates, assessmentEstimates, recordAssessmentApproval, interventions };

package/lib/workflow-control.js

@@ -0,0 +1,219 @@
+'use strict';
+
+// Node host for workflow control-plane operations. Never ask an LLM to do I/O.
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const registry = require('./agent-registry');
+const ledger = require('./execution-ledger');
+const { spawnClaudeAgent } = require('./task-executor/claude-process');
+const CLI = path.join(__dirname, '..', 'bin', 'cli.js');
+
+
+// Runtime payload has no third-party dependencies. Only these two canonical
+// scalar fields are needed; reject ambiguous/duplicate declarations.
+function definitionFields(source) {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) throw new Error('Agent frontmatter missing');
+  const fields = {};
+  for (const key of ['name', 'model']) {
+    const lines = match[1].split(/\r?\n/).filter(l => l.startsWith(key + ':'));
+    if (lines.length !== 1) throw new Error('Ambiguous agent field: ' + key);
+    fields[key] = lines[0].slice(key.length + 1).trim().replace(/^(['"])(.*)\1$/, '$2');
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(fields.name) || !['haiku', 'sonnet', 'opus'].includes(fields.model)) throw new Error('Invalid agent name/model');
+  return fields;
+}
+
+function validateIdentity(id, record, kind = 'agent') {
+  const entry = registry.CATALOG.find(e => e.agentId === id);
+  if (!entry || (entry.role === 'orchestrator') !== (kind === 'workflow') ||
+      !record || record.agentId !== id || record.status !== 'verified' ||
+      record.nativeName !== entry.nativeNames.claude ||
+      !record.path || !/^sha256:[a-f0-9]{64}$/.test(record.sha256 || '')) {
+    throw new Error('Invalid verified ' + kind + ' identity: ' + id);
+  }
+  const bytes = fs.readFileSync(record.path);
+  if ('sha256:' + crypto.createHash('sha256').update(bytes).digest('hex') !== record.sha256) {
+    throw new Error('Definition hash changed: ' + id);
+  }
+  if (kind === 'agent' && definitionFields(bytes.toString()).name !== record.nativeName) {
+    throw new Error('Agent frontmatter/nativeName mismatch: ' + id);
+  }
+  return record;
+}
+
+function parseArgs(input) {
+  if (Array.isArray(input)) return input.slice();
+  const tokens = [];
+  let value = '', quote = null, started = false;
+  for (const ch of String(input || '')) {
+    if (quote) { if (ch === quote) quote = null; else value += ch; }
+    else if (ch === '"' || ch === "'") { quote = ch; started = true; }
+    else if (/\s/.test(ch)) { if (started) { tokens.push(value); value = ''; started = false; } }
+    else { value += ch; started = true; }
+  }
+  if (quote) throw new Error('Unterminated argument quote');
+  if (started) tokens.push(value);
+  return tokens;
+}
+
+function deriveFeatureDir(featurePath) {
+  return /[/\\]feature\.md$/i.test(featurePath)
+    ? featurePath.replace(/[/\\]feature\.md$/i, '')
+    : featurePath.replace(/[/\\]+$/, '')
+}
+
+function createControl(options) {
+  const root = path.resolve(options.projectDir);
+  const runId = crypto.randomUUID();
+  let context, spent = 0, sequence = 0;
+  const tokenLedger = [];
+  const pending = new Set();
+  const full = p => path.resolve(root, p);
+  const read = p => fs.readFileSync(full(p), 'utf8');
+  const exists = p => { try { return fs.statSync(full(p)).isFile(); } catch (e) { if (e.code === 'ENOENT') return false; throw e; } };
+  const write = (p, content) => {
+    const dest = full(p);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const tmp = dest + '.tmp-' + crypto.randomUUID();
+    try { fs.writeFileSync(tmp, content, 'utf8'); fs.renameSync(tmp, dest); }
+    finally { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); }
+  };
+  async function resolve(id, kind = 'agent') {
+    const record = await registry.resolveAgent({ projectDir: root, homeDir: options.home,
+      agentId: id, requireVerified: true });
+    return validateIdentity(id, record, kind);
+  }
+  function command(argv, accepted = [0]) {
+    if (!Array.isArray(argv) || argv.some(a => typeof a !== 'string')) throw new Error('CLI argv array required');
+    if (options.home && argv[0] === 'run-asset') {
+      argv = argv.slice();
+      const split = argv.indexOf('--');
+      argv.splice(split < 0 ? argv.length : split, 0, '--home', options.home);
+    }
+    const result = spawnSync(process.execPath, [CLI, ...argv], {
+      cwd: root, encoding: 'utf8', shell: false, windowsHide: true,
+      timeout: 120000, maxBuffer: 20 * 1024 * 1024,
+    });
+    if (result.error || !Number.isInteger(result.status) || !accepted.includes(result.status)) {
+      throw new Error('Deterministic command failed: ' + (result.error?.message || result.stderr || result.status));
+    }
+    return { exitCode: result.status, stdout: result.stdout, stderr: result.stderr };
+  }
+  async function activity(label, fn, model, usage = () => null, metadata) {
+    if (!context) throw new Error('Workflow ownership not established');
+    const key = `${context.name}:${label}:${runId}:${++sequence}`;
+    ledger.openOwned(context.dir, context.prefix, key, context.name, model, runId, metadata);
+    try {
+      const result = await fn();
+      ledger.finalizeOwned(context.dir, context.prefix, key, runId, 'done', undefined, usage());
+      return result;
+    } catch (error) {
+      try { ledger.finalizeOwned(context.dir, context.prefix, key, runId, 'failed', String(error), usage()); }
+      catch (persistError) { throw new AggregateError([error, persistError], 'Activity failed and ledger finalization failed'); }
+      throw error;
+    }
+  }
+  async function worker(id, prompt, opts = {}) {
+    let measuredTokens = null;
+    const identity = await resolve(id);
+    const definition = definitionFields(read(identity.path));
+    return activity(opts.label || id, async () => {
+      const cliArgs = ['--print', '--output-format', 'json', '--agent', identity.nativeName];
+      if (opts.schema) cliArgs.push('--json-schema', JSON.stringify(opts.schema));
+      const result = await (options.dispatch || spawnClaudeAgent)({
+        claudePath: options.claudePath, cwd: root, args: cliArgs, prompt,
+        taskTimeoutMs: options.taskTimeoutMs || 1800000,
+      });
+      if (result.exitCode !== 0 || result.parseError || result.timedOut ||
+          !result.result || result.result.is_error !== false) throw new Error('Worker failed: ' + id);
+      const payload = opts.schema ? result.result.structured_output : result.result.result;
+      if (payload == null || (typeof payload === 'string' && !payload.trim())) throw new Error('Worker returned no result: ' + id);
+      if (opts.schema) validateSchema(payload, opts.schema);
+      const usage = result.result.usage;
+      const tokens = usage && [usage.input_tokens, usage.output_tokens].every(Number.isFinite)
+        ? usage.input_tokens + usage.output_tokens + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0) : null;
+      measuredTokens = Number.isInteger(tokens) && tokens > 0 ? tokens : null;
+      spent += measuredTokens || 0;
+      tokenLedger.push({ agent: identity.nativeName, model: definition.model, phase_delta_tokens: measuredTokens });
+      return payload;
+    }, definition.model, () => measuredTokens, { agentId: id, nativeAgentName: identity.nativeName, platform: 'claude', definitionHash: identity.sha256, resolutionScope: identity.scope, toolkitVersion: identity.toolkitVersion });
+  }
+  async function parallel(fns) {
+    // Drain every sibling before finalizing the owner, even if one rejects.
+    const work = Promise.allSettled(fns.map(fn => Promise.resolve().then(fn)));
+    pending.add(work);
+    try {
+      const results = await work;
+      const failed = results.filter(r => r.status === 'rejected');
+      if (failed.length) throw new AggregateError(failed.map(r => r.reason), 'Parallel workers failed');
+      return results.map(r => r.value);
+    } finally { pending.delete(work); }
+  }
+  async function run(name, dir, prefix, fn) {
+    if (context) throw new Error('Nested workflow ownership forbidden');
+    if (!/^(?:FTR|ASSESS|[A-Z]+)-\d+$/.test(prefix)) throw new Error('Invalid workflow prefix');
+    context = { name, dir: full(dir), prefix };
+    fs.mkdirSync(context.dir, { recursive: true });
+    const key = `${name}:self:${runId}`;
+    const runLockPath = path.join(context.dir, prefix + '-workflow.lock');
+    const runLock = ledger._acquireLock(runLockPath);
+    try {
+    ledger.openOwned(context.dir, prefix, key, name, null, runId);
+    try {
+      const result = await fn();
+      await Promise.allSettled([...pending]);
+      if (!result || result.error || result.errors?.length || result.gate2_payload?.gate2_blocked) {
+        throw new Error('Workflow returned unsuccessful result: ' + JSON.stringify(result));
+      }
+      // All work, output validation and serialization precede the terminal commit.
+      const serialized = JSON.stringify(result);
+      const committedResult = JSON.parse(serialized);
+      ledger.finalizeOwned(context.dir, prefix, key, runId, 'done');
+      return committedResult;
+    } catch (error) {
+      await Promise.allSettled([...pending]);
+      try { ledger.finalizeOwned(context.dir, prefix, key, runId, 'failed', String(error)); }
+      catch (persistError) { throw new AggregateError([error, persistError], 'Workflow failed; ledger finalization failed'); }
+      throw error;
+    }
+    } finally { ledger._releaseLock(runLockPath, runLock); }
+  }
+  function feature(p) {
+    if (!p) throw new Error('Feature path required');
+    const file = full(p), dir = deriveFeatureDir(file);
+    const match = path.basename(dir).match(/^([A-Z]+-\d+)(?:-|$)/);
+    if (!match) throw new Error('Cannot derive canonical feature prefix');
+    read(file);
+    return { featurePath: file, featureDir: dir, prefix: match[1] };
+  }
+  const api = { root, runId, read, exists, write, resolve, worker, parallel, run, command, activity,
+    feature, parseArgs, tokenLedger, spent: () => spent,
+    mtime: p => fs.statSync(full(p)).mtimeMs,
+    json: p => JSON.parse(read(p)),
+    log: text => (options.log || (() => {}))(String(text)),
+    append: (p, text) => { fs.mkdirSync(path.dirname(full(p)), { recursive: true }); fs.appendFileSync(full(p), text); },
+  };
+  const artifacts = require('./workflow-artifacts');
+  api.estimates = (...args) => artifacts.estimates(api, ...args);
+  api.assessmentEstimates = (...args) => artifacts.assessmentEstimates(api, ...args);
+  api.recordAssessmentApproval = (...args) => artifacts.recordAssessmentApproval(api, ...args);
+  return api;
+}
+
+function validateSchema(value, schema) {
+  if (schema.type === 'object') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid structured object');
+    for (const key of schema.required || []) if (!(key in value)) throw new Error('Missing structured field: ' + key);
+    for (const [key, sub] of Object.entries(schema.properties || {})) if (key in value) validateSchema(value[key], sub);
+  } else if (schema.type === 'array') {
+    if (!Array.isArray(value)) throw new Error('Invalid structured array');
+    if (schema.items) value.forEach(v => validateSchema(v, schema.items));
+  } else if (schema.type && (typeof value !== schema.type || (schema.type === 'number' && !Number.isFinite(value)))) {
+    throw new Error('Invalid structured ' + schema.type);
+  }
+}
+
+module.exports = { createControl, validateIdentity, validateSchema, parseArgs, deriveFeatureDir };

package/lib/workflow-runner.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const fs = require('fs');
+const { createControl, parseArgs } = require('./workflow-control');
+const IDS = {
+  'pm-phase1': 'gaia.orchestrator.feature.phase1',
+  'pm-phase2': 'gaia.orchestrator.feature.phase2',
+  'am-phase1': 'gaia.orchestrator.assessment.phase1',
+  'am-phase2': 'gaia.orchestrator.assessment.phase2',
+};
+
+async function runWorkflow(name, args, options) {
+  if (!IDS[name]) throw new Error('Unsupported workflow: ' + name + '. For implementation use ai-toolkit tasks start/run (FTR-018).');
+  const control = createControl(options);
+  const identity = await control.resolve(IDS[name], 'workflow');
+  const source = fs.readFileSync(identity.path, 'utf8');
+  if (!/controlPlaneVersion:\s*1\b/.test(source)) throw new Error('Installed workflow does not support deterministic control-plane v1; reinstall toolkit assets.');
+  // Only verified toolkit scripts are evaluated. This host is not a security sandbox.
+  const body = source.replace(/^export const meta\s*=/m, 'const meta =');
+  const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+  return new AsyncFunction('control', 'args', body)(control, parseArgs(args));
+}
+
+async function main(argv) {
+  if (argv[0] !== 'run') throw new Error('Usage: ai-toolkit workflow run NAME --project DIR --claude-path EXE -- ARGS');
+  const split = argv.indexOf('--');
+  if (split < 0) throw new Error('Workflow arguments must follow --');
+  const options = { projectDir: process.cwd(), log: s => process.stderr.write(s + '\n') };
+  const keys = { '--project': 'projectDir', '--home': 'home', '--claude-path': 'claudePath' };
+  for (let i = 2; i < split; i += 2) {
+    if (!keys[argv[i]] || !argv[i + 1] || argv[i + 1].startsWith('--')) throw new Error('Invalid workflow option: ' + argv[i]);
+    options[keys[argv[i]]] = argv[i + 1];
+  }
+  if (!options.claudePath && argv[1] !== 'am-phase2') throw new Error('--claude-path is required');
+  const result = await runWorkflow(argv[1], argv.slice(split + 1), options);
+  process.stdout.write(JSON.stringify(result) + '\n');
+}
+
+module.exports = { runWorkflow, main };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/agents/{concurrency-safety-assessment.md → gaia-concurrency-safety-assessment.md}

@@ -1,5 +1,5 @@
 ---
-name: concurrency-safety-assessment
+name: gaia-concurrency-safety-assessment
 description: "Concurrency Safety Assessment — identifies race conditions, shared mutable state corruption, and non-deterministic behaviour in concurrent or event-driven systems. Language-agnostic; produces structured findings with severity, evidence, and mitigation patterns. Output: {ASSESS_PREFIX}-Concurrency-Assessment.md"
 tools: Read, Grep, Glob, Bash, Write
 model: haiku

package/src/claude/agents/{define-feature.md → gaia-define-feature.md}

@@ -1,5 +1,5 @@
 ---
-name: define-feature
+name: gaia-define-feature
 description: "Define Feature — grills the user with targeted questions to define a new feature, then writes feature.md in docs/features/FTR-XXX-slug/. Output: feature.md ready for /implement-feature"
 model: sonnet
 ---

package/src/claude/agents/{dependency-injection-refactoring.md → gaia-dependency-injection-refactoring.md}

@@ -1,5 +1,5 @@
 ---
-name: dependency-injection-refactoring
+name: gaia-dependency-injection-refactoring
 description: "Dependency Injection Refactoring — guides the incremental conversion of tightly coupled or statically accessed dependencies to constructor-injected services, preserving build integrity at every step. Language-agnostic; reads AGENTS.md for framework-specific DI patterns. Input: target classes from intervention document"
 model: sonnet
 ---

package/src/claude/agents/{dependency-supply-chain-security.md → gaia-dependency-supply-chain-security.md}

@@ -1,5 +1,5 @@
 ---
-name: dependency-supply-chain-security
+name: gaia-dependency-supply-chain-security
 description: "Dependency Supply Chain Security — guides the implementation of dependency integrity controls: trusted package sources, deterministic restore via lock files, unused dependency audit, and SCA integration in CI/CD pipelines. Works with npm, pip, NuGet, Maven, and other package managers; reads AGENTS.md for project stack. Output: remediated configuration files + CI/CD pipeline changes"
 model: sonnet
 ---

package/src/claude/agents/{developer-backend.md → gaia-developer-backend.md}

@@ -1,5 +1,5 @@
 ---
-name: developer-backend
+name: gaia-developer-backend
 description: "Senior Backend Developer — implements backend tasks (DB, BE, INFRA domains) from the Work Breakdown following project conventions. Input: path to feature.md + task IDs"
 model: sonnet
 ---

package/src/claude/agents/{developer-frontend.md → gaia-developer-frontend.md}

@@ -1,5 +1,5 @@
 ---
-name: developer-frontend
+name: gaia-developer-frontend
 description: "Senior Frontend Developer — implements frontend tasks (FE domain) from the Work Breakdown following project conventions. Input: path to feature.md + task IDs"
 model: sonnet
 ---

package/src/claude/agents/{developer-testing.md → gaia-developer-testing.md}

@@ -1,5 +1,5 @@
 ---
-name: developer-testing
+name: gaia-developer-testing
 description: "Senior Test Engineer — creates unit/integration tests for implemented features (TEST domain). Input: path to feature.md + task IDs"
 model: sonnet
 ---

package/src/claude/agents/{domain-model-refactoring.md → gaia-domain-model-refactoring.md}

@@ -1,5 +1,5 @@
 ---
-name: domain-model-refactoring
+name: gaia-domain-model-refactoring
 description: "Domain Model Refactoring — guides the decomposition of monolithic domain model files, introduction of type hierarchies for structurally similar types, and alignment of model names with domain ubiquitous language. Language-agnostic; reads AGENTS.md for project conventions. Input: target model directory from intervention document"
 model: sonnet
 ---

package/src/claude/agents/{generate-requirements.md → gaia-generate-requirements.md}

@@ -1,5 +1,5 @@
 ---
-name: generate-requirements
+name: gaia-generate-requirements
 description: "Generates a functional requirements document from a feature description. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep, Write

package/src/claude/agents/{generate-tech-spec.md → gaia-generate-tech-spec.md}

@@ -1,5 +1,5 @@
 ---
-name: generate-tech-spec
+name: gaia-generate-tech-spec
 description: "Generates a technical specification document from a feature description and requirements. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep, Write

package/src/claude/agents/{generate-work-breakdown.md → gaia-generate-work-breakdown.md}

@@ -1,5 +1,5 @@
 ---
-name: generate-work-breakdown
+name: gaia-generate-work-breakdown
 description: "Generates a structured work breakdown (User Stories + Tasks) from validated and approved Requirements and Tech-Spec. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep, Write
@@ -24,7 +24,7 @@ The user provides the path to a `feature.md` file. From the same directory, read
 ```
 Cannot generate work breakdown: `{file}` not found.
 The work breakdown requires validated and approved Requirements + Tech-Spec.
-Run /agent-project-manager to orchestrate the full pipeline (including validation and approval gates).
+Run /implement-feature to orchestrate the full pipeline (including validation and approval gates).
 ```
 
 ---
@@ -63,7 +63,7 @@ Every task must be the **smallest independently implementable, verifiable, and c
 
 - **One observable outcome** — the task produces exactly one concrete artifact or behavioral change (one file, one endpoint, one migration, one test suite for one check). State it in the `outcome` field as a factual sentence describing what exists after the task is done.
 - **One domain** — choose exactly one: `BE`, `FE`, `DB`, `DevOps`, `INFRA`, or `TEST`.
-- **One agent type** — choose exactly one: `developer-backend`, `developer-frontend`, `developer-testing`, `developer-database`, or `review-solution`.
+- **One agent type** — choose exactly one: `developer-backend`, `developer-frontend`, `developer-testing`, or `review-solution`. (`developer-database` is deprecated — use `developer-backend` for DB domain tasks.)
 - **One commit** — supply a single `commit.subject` describing the change.
 - **Estimated ≤ 15 minutes of agent time** — this is the target. If a task cannot be scoped to ≤ 15 minutes, split it further. Tasks up to 20 minutes are acceptable but above target. Tasks over 30 minutes are invalid and will be rejected by the validator.
 
@@ -126,7 +126,7 @@ Decomposition strategy by domain:
 | `title` | string | Short descriptive title; must not contain `\|`, CR, or LF |
 | `outcome` | string | Single observable outcome — what exists after this task is done |
 | `domain` | string | One of: `BE`, `FE`, `DB`, `DevOps`, `INFRA`, `TEST` |
-| `agentType` | string | One of: `developer-backend`, `developer-frontend`, `developer-testing`, `developer-database`, `review-solution` |
+| `agentType` | string | One of: `developer-backend`, `developer-frontend`, `developer-testing`, `review-solution` (deprecated: `developer-database` — maps to `developer-backend`) |
 | `dependsOn` | array of strings | Task IDs this task depends on; may be empty `[]`; all IDs must be defined within this same JSON |
 | `acceptanceCriteria` | array of strings | AC IDs from Requirements that this task covers; may be empty `[]` |
 | `verification` | object | `{ "commands": ["..."] }` — one or more shell commands that verify the task output; array must be non-empty |
@@ -136,7 +136,7 @@ Decomposition strategy by domain:
 | `commit` | object | `{ "type": "feat", "subject": "..." }` — subject must not contain `\|`, CR, or LF |
 
 **Domain → agentType mapping (default):**
-- `DB` → `developer-database`
+- `DB` → `developer-backend` (note: `developer-database` is a deprecated alias that still resolves — do NOT use it in new Work Breakdowns)
 - `BE`, `INFRA`, `DevOps` → `developer-backend`
 - `FE` → `developer-frontend`
 - `TEST` → `developer-testing`

package/src/claude/agents/{generic-software-assessment.md → gaia-generic-software-assessment.md}

@@ -1,5 +1,5 @@
 ---
-name: generic-software-assessment
+name: gaia-generic-software-assessment
 description: "Generic Software Assessment — performs a broad quality analysis across architecture, code quality, security, testability, observability, and DevOps. Reads AGENTS.md for project conventions. Output: {ASSESS_PREFIX}-Generic-Assessment.md"
 tools: Read, Grep, Glob, Bash, Write
 model: haiku

package/src/claude/agents/{god-class-decomposition.md → gaia-god-class-decomposition.md}

@@ -1,5 +1,5 @@
 ---
-name: god-class-decomposition
+name: gaia-god-class-decomposition
 description: "God Class Decomposition — guides the safe, incremental decomposition of oversized classes and methods using responsibility cluster analysis, extract-method, extract-class, and parameter object refactoring. Language-agnostic; reads AGENTS.md for project conventions. Input: target class(es) from intervention document"
 model: sonnet
 ---

package/src/claude/agents/{init-agents-md.md → gaia-init-agents-md.md}

@@ -1,5 +1,5 @@
 ---
-name: init-agents-md
+name: gaia-init-agents-md
 description: "Analyzes a project codebase and generates a complete AGENTS.md file with tech stack, conventions, real code patterns, build/test commands, and hard constraints. Input: (optional) path to project root — defaults to current working directory."
 model: sonnet
 tools: Read, Glob, Grep, Bash, Write

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

@@ -1,5 +1,5 @@
 ---
-name: install-toolkit
+name: gaia-install-toolkit
 description: "Installs the ai-toolkit into a destination project by copying agents, skills, commands, and procedures. Input: [path-to-destination] [--force] — defaults to current working directory"
 model: sonnet
 ---

package/src/claude/agents/{intervention-documentation-standard.md → gaia-intervention-documentation-standard.md}

@@ -1,5 +1,5 @@
 ---
-name: intervention-documentation-standard
+name: gaia-intervention-documentation-standard
 description: "Intervention Documentation Standard — generates structured, self-contained intervention documents from assessment findings. Each document is independently actionable by an architect or developer agent. Input: assessment findings; Output: {ASSESS_PREFIX}-INT-NNN-{slug}.md per finding + Interventions-Index.md"
 model: sonnet
 tools: Read, Grep, Glob, Bash, Write
@@ -89,12 +89,12 @@ Other interventions that must be completed first (blocking) or should be coordin
 What to do if the intervention fails mid-way: rollback strategy, branch isolation, partial revert steps.
 
 ### 17. Suggested Agent Assignment
-Which agent type should execute this intervention:
-- `developer-backend` — backend/infrastructure implementation
-- `developer-frontend` — frontend/UI implementation
-- `developer-testing` — test writing
-- `review-solution` — post-intervention validation
-- Specialised agent (e.g. `security-hardening`) if available in `.claude/agents/`
+Which verified native agent should implement this intervention (recommendations only, never assessment dispatch):
+- `gaia-developer-backend` — backend/infrastructure implementation
+- `gaia-developer-frontend` — frontend/UI implementation
+- `gaia-developer-testing` — test writing
+- `gaia-review-solution` — post-intervention validation
+- Specialised agent (e.g. `gaia-security-hardening`) if available in `.claude/agents/`
 
 ### 18. Expected Outputs
 List of files to be created or modified. Each entry: `file path` → what changes.
@@ -124,9 +124,9 @@ After writing all intervention documents, produce `{ASSESS_PREFIX}-Interventions
 
 | ID | Title | Area | Criticality | Depends on | Suggested Agent |
 |---|---|---|---|---|---|
-| INT-001 | ... | Security | CRITICAL | — | developer-backend |
-| INT-002 | ... | Code Quality | HIGH | INT-003 | developer-backend |
-| INT-003 | ... | Architecture | HIGH | — | developer-backend |
+| INT-001 | ... | Security | CRITICAL | — | gaia-developer-backend |
+| INT-002 | ... | Code Quality | HIGH | INT-003 | gaia-developer-backend |
+| INT-003 | ... | Architecture | HIGH | — | gaia-developer-backend |
 ```
 
 Order by criticality (CRITICAL first), then by dependency (prerequisites before dependents).

package/src/claude/agents/{layered-architecture-assessment.md → gaia-layered-architecture-assessment.md}

@@ -1,5 +1,5 @@
 ---
-name: layered-architecture-assessment
+name: gaia-layered-architecture-assessment
 description: "Layered Architecture Assessment — audits a codebase for layer boundary violations, missing separation of concerns, and namespace/package misalignment. Produces a violation inventory and a recommended layer model. Language-agnostic; reads AGENTS.md for project conventions. Output: {ASSESS_PREFIX}-Layer-Assessment.md"
 tools: Read, Grep, Glob, Bash, Write
 model: haiku

package/src/claude/agents/{review-solution.md → gaia-review-solution.md}

@@ -1,5 +1,5 @@
 ---
-name: review-solution
+name: gaia-review-solution
 description: "Senior Architect — full solution review across quality, reuse, architecture, and security dimensions. Reports findings without auto-fixing. Input: scope (files, US-XX, or git diff)"
 model: opus
 tools: Read, Grep, Glob, Bash

package/src/claude/agents/{security-hardening.md → gaia-security-hardening.md}

@@ -1,5 +1,5 @@
 ---
-name: security-hardening
+name: gaia-security-hardening
 description: "Security Hardening — guides the implementation of targeted security fixes: input validation at system boundaries, parameterised queries, secret management, log sanitisation, and TLS/transport configuration. Language-agnostic; reads AGENTS.md for project-specific patterns. Input: security findings from assessment"
 model: sonnet
 ---

package/src/claude/agents/{validate-feature-docs.md → gaia-validate-feature-docs.md}

@@ -1,5 +1,5 @@
 ---
-name: validate-feature-docs
+name: gaia-validate-feature-docs
 description: "Validates Requirements and Tech-Spec documents against feature.md. Triggers targeted revision of failing documents if gaps are found. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep, Write
@@ -18,7 +18,7 @@ A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md`
    - `feature.md` — source of truth
    - `{PREFIX}-Requirements.md`
    - `{PREFIX}-Tech-Spec.md`
-3. If either output document is missing, abort and report: "Cannot validate: `{file}` not found. Run /agent-project-manager first."
+3. If either output document is missing, abort and report: "Cannot validate: `{file}` not found. Run /implement-feature first."
 
 ---
 

package/src/claude/agents/{validate-work-breakdown-semantic.md → gaia-validate-work-breakdown-semantic.md}

@@ -1,5 +1,5 @@
 ---
-name: validate-work-breakdown-semantic
+name: gaia-validate-work-breakdown-semantic
 description: "Semantic validator for Work Breakdown JSON — analyzes task coherence, scope alignment, and estimate realism. Runs after wb-validate.js exits 0. Input: path to {PREFIX}-Work-Breakdown.json"
 model: sonnet
 tools: Read, Glob, Grep