nubos-pilot 0.1.0

package/bin/np-tools/add-tests.cjs

@@ -0,0 +1,171 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError, atomicWriteFileSync, withFileLock } = require('../../lib/core.cjs');
+const { getPhase } = require('../../lib/roadmap.cjs');
+const { paddedPhase, phaseSlug, findPhaseDir } = require('../../lib/phase.cjs');
+const { parseVerificationMd } = require('../../lib/verify.cjs');
+
+const BEGIN_MARKER = '// >>> np:add-tests begin';
+const END_MARKER = '// <<< np:add-tests end';
+
+function _validatePhaseArg(raw) {
+  if (raw == null || raw === '' || !/^\d+(\.\d+)?$/.test(String(raw))) {
+    throw new NubosPilotError(
+      'add-tests-invalid-phase',
+      'add-tests requires a numeric phase argument',
+      { value: raw == null ? '' : String(raw) },
+    );
+  }
+  return String(raw);
+}
+
+function _resolveTestTarget(phaseArg, cwd) {
+  const phaseN = Number(phaseArg);
+  const phase = getPhase(phaseN, cwd);
+  const slug = phase.slug || phaseSlug(phase.name);
+  const padded = paddedPhase(phaseN);
+  let dir = path.resolve(cwd);
+  for (let i = 0; i < 10; i++) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return {
+        pkg_root: dir,
+        target_path: path.join(dir, 'test', 'uat', 'phase-' + padded + '-' + slug + '.test.cjs'),
+        padded, slug,
+      };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return {
+    pkg_root: path.resolve(cwd),
+    target_path: path.join(path.resolve(cwd), 'test', 'uat', 'phase-' + padded + '-' + slug + '.test.cjs'),
+    padded, slug,
+  };
+}
+
+function _loadCases(phaseArg, cwd) {
+  const phaseN = Number(phaseArg);
+  const padded = paddedPhase(phaseN);
+  const phase_dir = findPhaseDir(phaseN, cwd);
+  if (!phase_dir) {
+    throw new NubosPilotError(
+      'add-tests-phase-dir-missing',
+      'Phase directory not found for phase ' + phaseN,
+      { phase: phaseN },
+    );
+  }
+  const vp = path.join(phase_dir, padded + '-VERIFICATION.md');
+  if (!fs.existsSync(vp)) {
+    throw new NubosPilotError(
+      'add-tests-verification-missing',
+      'VERIFICATION.md not found — run `/np:verify-work ' + phaseArg + '` first',
+      { path: vp },
+    );
+  }
+  const all = parseVerificationMd(vp);
+  const passes = all.filter((c) => c.status === 'Pass');
+  const skips = all.filter((c) => c.status === 'Fail' || c.status === 'Defer');
+  return { all, passes, skips, verification_path: vp };
+}
+
+function _jsString(s) {
+  return "'" + String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n') + "'";
+}
+
+function _renderBlock(phasePadded, passes, skips) {
+  const date = new Date().toISOString().slice(0, 10);
+  const lines = [];
+  lines.push(BEGIN_MARKER + ' (phase ' + phasePadded + ', generated ' + date + ')');
+  lines.push("const { test } = require('node:test');");
+  lines.push("const assert = require('node:assert');");
+  lines.push('');
+  for (const c of passes) {
+    lines.push('test(' + _jsString(c.id + ': ' + c.text) + ', () => {');
+    lines.push('  // TODO: implement UAT for ' + c.id);
+    lines.push('  assert.ok(true);');
+    lines.push('});');
+  }
+  for (const c of skips) {
+    lines.push('test.skip(' + _jsString(c.id + ': ' + c.text) + ', { todo: ' + _jsString('Deferred: ' + c.status) + ' }, () => {});');
+  }
+  lines.push(END_MARKER);
+  return lines.join('\n');
+}
+
+function _mergeBlock(existing, block) {
+  if (!existing) {
+    return block + '\n';
+  }
+
+  const beginIdx = existing.indexOf(BEGIN_MARKER);
+  const endIdx = existing.indexOf(END_MARKER);
+  if (beginIdx < 0 || endIdx < 0 || endIdx < beginIdx) {
+
+    return existing.replace(/\n*$/, '\n') + block + '\n';
+  }
+  const before = existing.slice(0, beginIdx);
+  const after = existing.slice(endIdx + END_MARKER.length);
+  return before + block + after;
+}
+
+function _emitTests(phaseArg, cwd) {
+  const { passes, skips } = _loadCases(phaseArg, cwd);
+  const target = _resolveTestTarget(phaseArg, cwd);
+  fs.mkdirSync(path.dirname(target.target_path), { recursive: true });
+  const block = _renderBlock(target.padded, passes, skips);
+  return withFileLock(target.target_path, () => {
+    let existing = null;
+    try { existing = fs.readFileSync(target.target_path, 'utf-8'); } catch { existing = null; }
+    const next = _mergeBlock(existing, block);
+    atomicWriteFileSync(target.target_path, next);
+    return {
+      ok: true,
+      target_path: target.target_path,
+      pass_count: passes.length,
+      skip_count: skips.length,
+    };
+  });
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const verb = list[0];
+
+  switch (verb) {
+    case 'init': {
+      const phaseArg = _validatePhaseArg(list[1]);
+      const target = _resolveTestTarget(phaseArg, cwd);
+      const { passes, skips, verification_path } = _loadCases(phaseArg, cwd);
+      const payload = {
+        _workflow: 'add-tests',
+        phase: phaseArg,
+        target_path: target.target_path,
+        verification_path,
+        pass_cases: passes,
+        skip_cases: skips,
+      };
+      stdout.write(JSON.stringify(payload, null, 2));
+      return payload;
+    }
+    case 'emit': {
+      const phaseArg = _validatePhaseArg(list[1]);
+      const result = _emitTests(phaseArg, cwd);
+      stdout.write(JSON.stringify(result));
+      return result;
+    }
+    default:
+      throw new NubosPilotError(
+        'add-tests-unknown-verb',
+        'add-tests: unknown verb: ' + String(verb),
+        { verb },
+      );
+  }
+}
+
+module.exports = { run, BEGIN_MARKER, END_MARKER };

package/bin/np-tools/add-tests.test.cjs

@@ -0,0 +1,122 @@
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { makeSandbox, seedRoadmapYaml, seedPhaseDir, cleanupAll } =
+  require('../../tests/helpers/fixture.cjs');
+const subcmd = require('./add-tests.cjs');
+
+function _roadmap() {
+  return {
+    schema_version: 1,
+    milestones: [{ id: 'v1.0', name: 'm1', phases: [
+      { number: 6, name: 'Execution', slug: 'execution', goal: '', depends_on: [],
+        requirements: [], success_criteria: ['a', 'b', 'c'],
+        status: 'planned', plans: [] },
+    ]}],
+  };
+}
+
+function _capture() { let b = ''; return { stub: { write: (s) => { b += s; return true; } }, get: () => b }; }
+
+function _seedVerification(sandbox) {
+  const phaseDir = seedPhaseDir(sandbox, 6, 'execution', {});
+  const v = [
+    '# Phase 6: Execution - Verification',
+    '',
+    '**Verified:** 2026-04-15',
+    '**Phase Status:** deferred',
+    '',
+    '## Success Criteria',
+    '',
+    '### SC-1: First passes',
+    '- **Status:** Pass',
+    '- **Classified by:** user',
+    '- **Evidence:** —',
+    '',
+    '### SC-2: Second fails',
+    '- **Status:** Fail',
+    '- **Classified by:** user',
+    '- **Evidence:** —',
+    '',
+    '### SC-3: Deferred',
+    '- **Status:** Defer',
+    '- **Classified by:** user',
+    '- **Evidence:** —',
+    '',
+  ].join('\n');
+  fs.writeFileSync(path.join(phaseDir, '06-VERIFICATION.md'), v, 'utf-8');
+
+  fs.writeFileSync(path.join(sandbox, 'package.json'), '{"name":"sandbox"}', 'utf-8');
+  return phaseDir;
+}
+
+afterEach(cleanupAll);
+
+test('AT-1: init emits pass_cases (1) and skip_cases (2) categorized', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _roadmap());
+  _seedVerification(sandbox);
+  const cap = _capture();
+  const p = subcmd.run(['init', '6'], { cwd: sandbox, stdout: cap.stub });
+  assert.equal(p.pass_cases.length, 1);
+  assert.equal(p.skip_cases.length, 2);
+  assert.ok(p.target_path.endsWith('test/uat/phase-06-execution.test.cjs'));
+});
+
+test('AT-2: emit writes node:test file with begin/end sentinels', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _roadmap());
+  _seedVerification(sandbox);
+  const cap = _capture();
+  const r = subcmd.run(['emit', '6'], { cwd: sandbox, stdout: cap.stub });
+  const body = fs.readFileSync(r.target_path, 'utf-8');
+  assert.ok(body.includes('// >>> np:add-tests begin'));
+  assert.ok(body.includes('// <<< np:add-tests end'));
+  assert.ok(body.includes("test('SC-1: First passes'"));
+  assert.ok(body.includes("test.skip('SC-2: Second fails'"));
+  assert.ok(body.includes("test.skip('SC-3: Deferred'"));
+});
+
+test('AT-3: sentinel preservation — user edits OUTSIDE block survive regeneration', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _roadmap());
+  _seedVerification(sandbox);
+  const cap1 = _capture();
+  subcmd.run(['emit', '6'], { cwd: sandbox, stdout: cap1.stub });
+  const target = path.join(sandbox, 'test', 'uat', 'phase-06-execution.test.cjs');
+
+  let body = fs.readFileSync(target, 'utf-8');
+  const userTest = "// USER AUTHORED: do not delete\ntest('user: custom case', () => { assert.ok(1); });\n\n";
+  body = userTest + body;
+  fs.writeFileSync(target, body, 'utf-8');
+
+  const cap2 = _capture();
+  subcmd.run(['emit', '6'], { cwd: sandbox, stdout: cap2.stub });
+  const after = fs.readFileSync(target, 'utf-8');
+  assert.ok(after.includes('// USER AUTHORED: do not delete'), 'user content lost');
+  assert.ok(after.includes("test('user: custom case'"), 'user test lost');
+  assert.ok(after.includes('// >>> np:add-tests begin'));
+});
+
+test('AT-4: missing VERIFICATION.md → loud error', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _roadmap());
+  seedPhaseDir(sandbox, 6, 'execution', {});
+  fs.writeFileSync(path.join(sandbox, 'package.json'), '{}', 'utf-8');
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['init', '6'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'add-tests-verification-missing',
+  );
+});
+
+test('AT-5: unknown verb throws', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['bogus'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'add-tests-unknown-verb',
+  );
+});

package/bin/np-tools/add-todo.cjs

@@ -0,0 +1,108 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { projectStateDir, NubosPilotError } = require('../../lib/core.cjs');
+const { phaseSlug } = require('../../lib/phase.cjs');
+
+const MAX_DESCRIPTION_LENGTH = 500;
+
+function _buildPayload(description, cwd) {
+  if (description == null || typeof description !== 'string' || !description.trim()) {
+    throw new NubosPilotError(
+      'add-todo-missing-description',
+      'add-todo requires a non-empty description argument',
+      { description: description == null ? '' : String(description) },
+    );
+  }
+  if (/\n\n---\n/.test(description)) {
+    throw new NubosPilotError(
+      'add-todo-invalid-description',
+      'add-todo description must not contain YAML separator pattern',
+      { description },
+    );
+  }
+  if (description.length > MAX_DESCRIPTION_LENGTH) {
+    throw new NubosPilotError(
+      'add-todo-description-too-long',
+      'add-todo description must be <= ' + MAX_DESCRIPTION_LENGTH + ' chars',
+      { length: description.length },
+    );
+  }
+  const stateDir = projectStateDir(cwd);
+  const todosDir = path.join(stateDir, 'todos');
+  const pendingDir = path.join(todosDir, 'pending');
+  const now = new Date();
+  const iso = now.toISOString();
+  const date = iso.slice(0, 10);
+  const slug = phaseSlug(description);
+  if (!slug) {
+    throw new NubosPilotError(
+      'add-todo-empty-slug',
+      'add-todo description contains no slug-safe characters: ' + description,
+      { description },
+    );
+  }
+  let todo_count = 0;
+  try {
+    if (fs.existsSync(pendingDir)) {
+      todo_count = fs
+        .readdirSync(pendingDir)
+        .filter((f) => f.endsWith('.md')).length;
+    }
+  } catch (_err) {
+    todo_count = 0;
+  }
+  const todos_dir_exists = fs.existsSync(todosDir);
+  const state_path = path.join(stateDir, 'STATE.md');
+  return {
+    _workflow: 'add-todo',
+    commit_docs: true,
+    description,
+    slug,
+    date,
+    timestamp: iso,
+    state_dir: stateDir,
+    pending_dir: pendingDir,
+    todos_dir_exists,
+    todo_count,
+    state_path,
+    todos: [],
+  };
+}
+
+function _emitError(err, stderr) {
+  if (err && err.name === 'NubosPilotError') {
+    stderr.write(
+      JSON.stringify({ code: err.code, message: err.message, details: err.details }) + '\n',
+    );
+  } else {
+    stderr.write(String((err && err.stack) || err) + '\n');
+  }
+}
+
+function run(argv, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const args = Array.isArray(argv) ? argv.slice() : [];
+  const description = args.join(' ').trim();
+  if (!description) {
+    stderr.write('Usage: np-tools.cjs init add-todo <description>\n');
+    return 1;
+  }
+  try {
+    const payload = _buildPayload(description, cwd);
+    stdout.write(JSON.stringify(payload, null, 2));
+    return 0;
+  } catch (err) {
+    _emitError(err, stderr);
+    return 1;
+  }
+}
+
+module.exports = { run, _buildPayload };
+
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)));
+}

package/bin/np-tools/add-todo.test.cjs

@@ -0,0 +1,112 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const subcmd = require('./add-todo.cjs');
+
+const _sandboxes = [];
+
+function makeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-add-todo-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  _sandboxes.push(root);
+  return root;
+}
+
+function captureStdio(fn) {
+  const outChunks = [];
+  const errChunks = [];
+  const origOut = process.stdout.write.bind(process.stdout);
+  const origErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = (c) => { outChunks.push(String(c)); return true; };
+  process.stderr.write = (c) => { errChunks.push(String(c)); return true; };
+  let rc;
+  try { rc = fn(); } finally {
+    process.stdout.write = origOut;
+    process.stderr.write = origErr;
+  }
+  return { stdout: outChunks.join(''), stderr: errChunks.join(''), rc };
+}
+
+afterEach(() => {
+  while (_sandboxes.length) {
+    try { fs.rmSync(_sandboxes.pop(), { recursive: true, force: true }); } catch {  }
+  }
+});
+
+test('AT-1: _buildPayload("Fix deploy key auth", sandbox) returns payload with kebab-case slug', () => {
+  const cwd = makeSandbox();
+  const payload = subcmd._buildPayload('Fix deploy key auth', cwd);
+  assert.equal(payload._workflow, 'add-todo');
+  assert.equal(payload.slug, 'fix-deploy-key-auth');
+  assert.equal(payload.description, 'Fix deploy key auth');
+  assert.equal(payload.commit_docs, true);
+  assert.match(payload.date, /^\d{4}-\d{2}-\d{2}$/);
+  assert.match(payload.timestamp, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+  assert.ok(payload.pending_dir.endsWith(path.join('.nubos-pilot', 'todos', 'pending')));
+  assert.equal(payload.todo_count, 0);
+  assert.equal(payload.todos_dir_exists, false);
+});
+
+test('AT-2: _buildPayload("", sandbox) throws NubosPilotError code "add-todo-missing-description"', () => {
+  const cwd = makeSandbox();
+  assert.throws(
+    () => subcmd._buildPayload('', cwd),
+    (err) => err && err.name === 'NubosPilotError' && err.code === 'add-todo-missing-description',
+  );
+  assert.throws(
+    () => subcmd._buildPayload('   ', cwd),
+    (err) => err && err.name === 'NubosPilotError' && err.code === 'add-todo-missing-description',
+  );
+});
+
+test('AT-3: _buildPayload(501-char string, sandbox) throws code "add-todo-description-too-long"', () => {
+  const cwd = makeSandbox();
+  const longDesc = 'x'.repeat(501);
+  assert.throws(
+    () => subcmd._buildPayload(longDesc, cwd),
+    (err) => err && err.name === 'NubosPilotError' && err.code === 'add-todo-description-too-long',
+  );
+});
+
+test('AT-4: payload.date matches YYYY-MM-DD and prefix of payload.timestamp', () => {
+  const cwd = makeSandbox();
+  const payload = subcmd._buildPayload('Refactor the router', cwd);
+  assert.equal(payload.date.length, 10);
+  assert.equal(payload.timestamp.slice(0, 10), payload.date);
+});
+
+test('AT-5: run([]) writes usage to stderr and returns 1', () => {
+  const cap = captureStdio(() => subcmd.run([]));
+  assert.equal(cap.rc, 1);
+  assert.match(cap.stderr, /Usage:\s+np-tools\.cjs init add-todo/);
+});
+
+test('AT-6: run(["Fix deploy key auth"]) emits JSON with slug on stdout and exits 0', () => {
+  const cwd = makeSandbox();
+  const orig = process.cwd();
+  process.chdir(cwd);
+  try {
+    const cap = captureStdio(() => subcmd.run(['Fix', 'deploy', 'key', 'auth']));
+    assert.equal(cap.rc, 0, 'stderr: ' + cap.stderr);
+    const parsed = JSON.parse(cap.stdout);
+    assert.equal(parsed.slug, 'fix-deploy-key-auth');
+    assert.equal(parsed._workflow, 'add-todo');
+  } finally {
+    process.chdir(orig);
+  }
+});
+
+test('AT-7: todo_count reflects existing .md files in pending/', () => {
+  const cwd = makeSandbox();
+  const pending = path.join(cwd, '.nubos-pilot', 'todos', 'pending');
+  fs.mkdirSync(pending, { recursive: true });
+  fs.writeFileSync(path.join(pending, '2026-04-01-first.md'), '---\n---\n', 'utf-8');
+  fs.writeFileSync(path.join(pending, '2026-04-02-second.md'), '---\n---\n', 'utf-8');
+  fs.writeFileSync(path.join(pending, 'ignore-me.txt'), 'x', 'utf-8');
+  const payload = subcmd._buildPayload('Something new', cwd);
+  assert.equal(payload.todo_count, 2);
+  assert.equal(payload.todos_dir_exists, true);
+});

package/bin/np-tools/agent-skills.cjs

@@ -0,0 +1,14 @@
+const { getAgentSkills } = require('../../lib/agents.cjs');
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const stdout = context.stdout || process.stdout;
+  const cwd = context.cwd || process.cwd();
+  const name = Array.isArray(args) ? args[0] : undefined;
+  if (!name) { stdout.write('{}\n'); return; }
+  let skills = [];
+  try { skills = getAgentSkills(name, cwd); } catch { skills = []; }
+  stdout.write(JSON.stringify(skills) + '\n');
+}
+
+module.exports = { run };

package/bin/np-tools/agent-skills.test.cjs

@@ -0,0 +1,42 @@
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { makeSandbox, cleanupAll } = require('../../tests/helpers/fixture.cjs');
+const subcmd = require('./agent-skills.cjs');
+
+function _capture() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+afterEach(cleanupAll);
+
+test('AS-1: run([name]) prints JSON.stringify(getAgentSkills(name))', () => {
+  const sandbox = makeSandbox();
+  fs.writeFileSync(
+    path.join(sandbox, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ agent_skills: { 'np-planner': ['s1', 's2'] } }),
+    'utf-8',
+  );
+  const cap = _capture();
+  subcmd.run(['np-planner'], { cwd: sandbox, stdout: cap.stub });
+  const out = cap.get().trim();
+  assert.deepEqual(JSON.parse(out), ['s1', 's2']);
+});
+
+test('AS-2: run([]) prints {} (empty usage response)', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  subcmd.run([], { cwd: sandbox, stdout: cap.stub });
+  assert.equal(cap.get().trim(), '{}');
+});
+
+test('AS-3: run([nonexistent]) prints [] (never throws)', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.doesNotThrow(() => subcmd.run(['nobody'], { cwd: sandbox, stdout: cap.stub }));
+  assert.equal(cap.get().trim(), '[]');
+});

package/bin/np-tools/ai-integration-phase.cjs

@@ -0,0 +1,109 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { getPhase } = require('../../lib/roadmap.cjs');
+const { paddedPhase, phaseSlug, findPhaseDir } = require('../../lib/phase.cjs');
+const { detect } = require('../../lib/runtime/index.cjs');
+
+function _validatePhaseArg(raw) {
+  if (raw == null || raw === '') {
+    throw new NubosPilotError(
+      'ai-integration-phase-invalid-arg',
+      'ai-integration-phase requires a phase number argument',
+      { value: raw == null ? '' : String(raw) },
+    );
+  }
+  const s = String(raw);
+  if (!/^\d+(\.\d+)?$/.test(s)) {
+    throw new NubosPilotError(
+      'ai-integration-phase-invalid-arg',
+      'Invalid phase number: ' + s,
+      { value: s },
+    );
+  }
+  return s;
+}
+
+function _resolvePhaseDir(phaseArg, cwd, slug) {
+  const hit = findPhaseDir(phaseArg, cwd);
+  if (hit) return hit;
+  const padded = paddedPhase(phaseArg);
+  return path.join(path.resolve(cwd), '.nubos-pilot', 'phases', padded + '-' + slug);
+}
+
+function _buildPayload(phaseArg, cwd) {
+  let phase;
+  try {
+    phase = getPhase(phaseArg, cwd);
+  } catch (err) {
+    if (err && err.code === 'phase-not-found') {
+      throw new NubosPilotError(
+        'ai-integration-phase-not-found',
+        'Phase ' + phaseArg + ' not found in roadmap',
+        { number: phaseArg },
+      );
+    }
+    throw err;
+  }
+
+  const padded = paddedPhase(phaseArg);
+  const slug = phase.slug || phaseSlug(phase.name);
+  const phase_dir = _resolvePhaseDir(phaseArg, cwd, slug);
+  const ai_spec_path = path.join(phase_dir, padded + '-AI-SPEC.md');
+  const has_ai_spec = fs.existsSync(ai_spec_path);
+  const template_path = path.join(path.resolve(cwd), 'templates', 'AI-SPEC.md');
+  const { runtime } = detect({ cwd });
+
+  return {
+    _workflow: 'ai-integration-phase',
+    phase: phaseArg,
+    padded,
+    phase_dir,
+    ai_spec_path,
+    has_ai_spec,
+    template_path,
+    agents: {
+      framework_selector: 'np-framework-selector',
+      ai_researcher: 'np-ai-researcher',
+      domain_researcher: 'np-domain-researcher',
+      eval_planner: 'np-eval-planner',
+    },
+    runtime,
+  };
+}
+
+function _emitError(err, stderr) {
+  if (err && err.name === 'NubosPilotError') {
+    stderr.write(
+      JSON.stringify({ code: err.code, message: err.message, details: err.details }) + '\n',
+    );
+  } else {
+    stderr.write(String((err && err.stack) || err) + '\n');
+  }
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const list = Array.isArray(args) ? args : [];
+
+  if (list[0] == null || list[0] === '') {
+    stderr.write('Usage: np-tools.cjs init ai-integration-phase <phase>\n');
+    return 1;
+  }
+
+  try {
+    const phaseArg = _validatePhaseArg(list[0]);
+    const payload = _buildPayload(phaseArg, cwd);
+    stdout.write(JSON.stringify(payload, null, 2));
+    return 0;
+  } catch (err) {
+    _emitError(err, stderr);
+    return 1;
+  }
+}
+
+module.exports = { run, _buildPayload };