@adityaaria/agent-os 1.0.0

package/scripts/orchestrate.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderReport } from './lib/run-utils.mjs';
+import { wantsHelp, showHelp } from './lib/cli-utils.mjs';
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'orchestrate',
+    description: 'Create deterministic execution plans from prompts',
+    usage: [
+      'agent-os orchestrate "<TRIGGER>: <description>"',
+      'agent-os orchestrate --run-root <dir> "<TRIGGER>: <description>"'
+    ],
+    required: [
+      { flag: '<prompt>', desc: 'Trigger prompt (e.g., "BUG: Fix login", "ENHANCEMENT: Add CSV export")' }
+    ],
+    options: [
+      { flag: '--root <dir>', desc: 'Agent OS source root', default: '(auto-detected)' },
+      { flag: '--chain <skills>', desc: 'Explicit skill chain (comma-separated)' },
+      { flag: '--write-report <file>', desc: 'Write master report stub to file' },
+      { flag: '--run-root <dir>', desc: 'Create run directory under this root' },
+      { flag: '--run-id <id>', desc: 'Explicit run ID' }
+    ],
+    examples: [
+      'agent-os orchestrate "BUG: Fix the login redirect"',
+      'agent-os orchestrate --run-root .agent-os/runs "ENHANCEMENT: Add CSV export"',
+      'agent-os orchestrate --write-report reports/master.md "AUDIT: Review auth module"'
+    ]
+  });
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const defaultRepoRoot = path.resolve(path.dirname(__filename), '..');
+const args = process.argv.slice(2);
+
+function takeOption(name) {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  const value = args[index + 1] ?? null;
+  args.splice(index, 2);
+  return value;
+}
+
+const root = path.resolve(process.cwd(), takeOption('--root') ?? defaultRepoRoot);
+const explicitChain = takeOption('--chain');
+const reportOutputPath = takeOption('--write-report');
+const runRoot = takeOption('--run-root');
+const requestedRunId = takeOption('--run-id');
+const prompt = args.join(' ').trim();
+
+const reportSections = [
+  'Executive Summary',
+  'Scope',
+  'Knowledge Confidence',
+  'Knowledge Classification',
+  'Traceability Matrix',
+  'Evidence',
+  'Root Cause',
+  'Impact',
+  'Recommendation',
+  'Quality Gate',
+  'Enterprise Readiness',
+  'Final Decision'
+];
+
+const triggerMap = [
+  { trigger: 'ANALYZE PROJECT', skill: 'project-onboarding', pattern: /^ANALYZE PROJECT:/i, traceability: false },
+  { trigger: 'AUDIT FRAMEWORK', skill: 'self-audit', pattern: /^AUDIT FRAMEWORK$/i, traceability: false },
+  { trigger: 'BUG', skill: 'bug-fix', pattern: /^BUG:/i },
+  { trigger: 'ENHANCEMENT', skill: 'enhancement', pattern: /^ENHANCEMENT:/i },
+  { trigger: 'NEW PAGE', skill: 'new-page', pattern: /^NEW PAGE:/i },
+  { trigger: 'AUDIT', skill: 'audit', pattern: /^AUDIT:/i },
+  { trigger: 'TEST', skill: 'selenium-e2e', pattern: /^TEST:/i }
+];
+
+function detectPrimarySkill(input) {
+  const matched = triggerMap.find((item) => item.pattern.test(input));
+  if (!matched) {
+    return { trigger: 'UNKNOWN', skill: null, traceability: true };
+  }
+  if (matched.trigger === 'AUDIT' && /\b(agent os|framework)\b/i.test(input)) {
+    return { trigger: 'AUDIT', skill: 'self-audit', traceability: false };
+  }
+  return {
+    trigger: matched.trigger,
+    skill: matched.skill,
+    traceability: matched.traceability !== false
+  };
+}
+
+function detectDependentSkills(input) {
+  const normalized = input.toLowerCase();
+  const dependents = [];
+
+  if (/\baudit\b|\breview\b|\binspect\b/.test(normalized)) {
+    dependents.push('audit');
+  }
+
+  if (/\be2e\b|\bselenium\b|\btest\b|\btests\b/.test(normalized)) {
+    dependents.push('selenium-e2e');
+  }
+
+  return dependents;
+}
+
+function unique(items) {
+  return [...new Set(items)];
+}
+
+function skillExists(skill) {
+  return {
+    source: fs.existsSync(path.join(root, 'skills', skill, 'SKILL.md')),
+    runtime: fs.existsSync(path.join(root, '.agent-os', 'skills', skill, 'SKILL.md'))
+  };
+}
+
+function validatePlan(trigger, skillChain) {
+  const errors = [];
+  const warnings = [];
+
+  if (trigger === 'UNKNOWN') {
+    errors.push('Unsupported task trigger. Expected ANALYZE PROJECT, AUDIT FRAMEWORK, BUG, ENHANCEMENT, NEW PAGE, AUDIT, or TEST.');
+  }
+
+  for (const skill of skillChain) {
+    const exists = skillExists(skill);
+    if (!exists.source) errors.push(`Missing source skill: ${skill}`);
+    if (!exists.runtime) errors.push(`Missing runtime skill: ${skill}`);
+  }
+
+  const traceabilityIndex = skillChain.indexOf('traceability-analysis');
+  for (const skill of ['bug-fix', 'enhancement', 'new-page', 'audit', 'selenium-e2e']) {
+    const index = skillChain.indexOf(skill);
+    if (index !== -1 && (traceabilityIndex === -1 || traceabilityIndex > index)) {
+      errors.push(`traceability-analysis must run before ${skill}`);
+    }
+  }
+
+  return {
+    status: errors.length === 0 ? 'PASS' : 'FAIL',
+    errors,
+    warnings
+  };
+}
+
+function buildPlan(input) {
+  const primary = detectPrimarySkill(input);
+  const skillChain = explicitChain
+    ? explicitChain.split(',').map((skill) => skill.trim()).filter(Boolean)
+    : unique([
+      primary.traceability ? 'traceability-analysis' : null,
+      primary.skill,
+      ...(primary.traceability ? detectDependentSkills(input) : [])
+    ].filter(Boolean));
+  const validation = validatePlan(primary.trigger, skillChain);
+
+  return {
+    mode: 'sequential',
+    trigger: primary.trigger,
+    prompt: input,
+    skillChain,
+    validation,
+    executionPlan: skillChain.map((skill, index) => ({
+      step: index + 1,
+      skill,
+      status: 'pending',
+      dependsOn: index === 0 ? [] : [skillChain[index - 1]]
+    })),
+    masterReport: {
+      format: 'Agent OS Master Execution Report',
+      sections: reportSections
+    }
+  };
+}
+
+function timestampRunId() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function writeReport(outputPath, plan) {
+  const absolutePath = path.resolve(process.cwd(), outputPath);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, renderReport(plan));
+}
+
+function createRun(baseDir, runId, plan) {
+  const id = runId || timestampRunId();
+  const runDir = path.resolve(process.cwd(), baseDir, id);
+  const runPlan = {
+    ...plan,
+    run: {
+      id,
+      directory: runDir,
+      status: 'created'
+    }
+  };
+
+  fs.mkdirSync(runDir, { recursive: true });
+  fs.writeFileSync(path.join(runDir, 'plan.json'), JSON.stringify(runPlan, null, 2) + '\n');
+  fs.writeFileSync(path.join(runDir, 'steps.json'), JSON.stringify(runPlan.executionPlan, null, 2) + '\n');
+  fs.writeFileSync(path.join(runDir, 'master-report.md'), renderReport(runPlan));
+  return runPlan;
+}
+
+if (!prompt) {
+  console.error('✗ ERROR [orchestrate]: No task prompt provided.');
+  console.error('  → Suggestion: agent-os orchestrate "BUG: describe the issue here"');
+  process.exit(1);
+}
+
+const plan = buildPlan(prompt);
+
+// Inject entrypoint status from pre-flight check
+if (process.env.AGENT_OS_ENTRYPOINT_MISSING === 'true') {
+  plan.entrypoint_missing = true;
+} else if (process.env.AGENT_OS_ENTRYPOINT_PATH) {
+  plan.entrypoint_path = process.env.AGENT_OS_ENTRYPOINT_PATH;
+}
+
+let outputPlan = plan;
+if (reportOutputPath && plan.validation.status === 'PASS') {
+  writeReport(reportOutputPath, plan);
+}
+if (runRoot && plan.validation.status === 'PASS') {
+  outputPlan = createRun(runRoot, requestedRunId, plan);
+}
+console.log(JSON.stringify(outputPlan, null, 2));
+process.exit(outputPlan.validation.status === 'PASS' ? 0 : 1);

package/scripts/quality-static.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+
+  if (result.status !== 0) {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    process.exit(result.status ?? 1);
+  }
+}
+
+run('git', ['diff', '--check']);
+
+console.log('Static quality checks passed.');

package/scripts/report-export.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertEnabledChannel, collectRun, collectRuns, loadReportChannel, renderRunSummariesCsv } from './lib/run-utils.mjs';
+import { createCli, fail, failAll, showHelp, wantsHelp } from './lib/cli-utils.mjs';
+
+const { takeOption } = createCli(process.argv.slice(2));
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'report-export',
+    description: 'Export run reports as JSON or CSV',
+    usage: [
+      'agent-os report-export --run-dir <dir> --output <file> [options]',
+      'agent-os report-export --run-root <dir> --output <file> [options]'
+    ],
+    required: [
+      { flag: '--run-dir <dir> | --run-root <dir>', desc: 'Single run directory or runs root' },
+      { flag: '--output <file>', desc: 'Output file path' }
+    ],
+    options: [
+      { flag: '--format <json|csv>', desc: 'Output format', default: 'json' },
+      { flag: '--channel-config <file>', desc: 'Channel config file (reads format/output from channel)' },
+      { flag: '--channel <name>', desc: 'Channel name' }
+    ],
+    examples: [
+      'agent-os report-export --run-root .agent-os/runs --output reports/runs.json',
+      'agent-os report-export --run-dir .agent-os/runs/my-run --output report.csv --format csv',
+      'agent-os report-export --run-root .agent-os/runs --channel-config .agent-os/project/report-channels.json --channel spreadsheet'
+    ]
+  });
+}
+
+const runDir = takeOption('--run-dir');
+const runRoot = takeOption('--run-root');
+const channelConfig = takeOption('--channel-config');
+const channelName = takeOption('--channel');
+let format = takeOption('--format') ?? null;
+let output = takeOption('--output');
+
+const errors = [];
+if (!runDir && !runRoot) errors.push('Missing --run-dir <dir> or --run-root <dir>.');
+if (runDir && runRoot) errors.push('Use either --run-dir or --run-root, not both.');
+if (channelName && !channelConfig) errors.push('Missing --channel-config <file> when using --channel.');
+failAll(errors, 'agent-os report-export --run-root .agent-os/runs --output reports/runs.json', 'report-export');
+
+let outputBaseDir = process.cwd();
+if (channelConfig) {
+  if (channelName) {
+    try {
+      const channelContext = loadReportChannel(channelConfig, channelName);
+      assertEnabledChannel(channelContext);
+      outputBaseDir = channelContext.outputBaseDir;
+      format = format ?? channelContext.channel.format;
+      output = output ?? channelContext.channel.output;
+    } catch (err) {
+      fail(err.message);
+    }
+  }
+}
+
+format = format ?? 'json';
+
+if (!['json', 'csv'].includes(format)) {
+  fail(`Unsupported format: ${format}. Expected json or csv.`);
+}
+
+if (!output) {
+  fail('Missing required --output <file>.');
+}
+
+let payload;
+try {
+  payload = runDir ? collectRun(runDir) : collectRuns(runRoot);
+} catch (err) {
+  fail(err.message);
+}
+const body = format === 'csv'
+  ? renderRunSummariesCsv(payload)
+  : `${JSON.stringify(payload, null, 2)}\n`;
+const outputPath = path.resolve(outputBaseDir, output);
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, body);
+if (channelName) console.log(`Channel: ${channelName}`);
+console.log(`Exported report: ${outputPath}`);

package/scripts/report-notify.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertEnabledChannel, collectRun, collectRuns, loadReportChannel } from './lib/run-utils.mjs';
+import { escapeTelegramMarkdown } from './lib/telegram-utils.mjs';
+import { createCli, fail, failAll, resolveDefault, showHelp, wantsHelp } from './lib/cli-utils.mjs';
+
+const { hasFlag, takeOption } = createCli(process.argv.slice(2));
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'report-notify',
+    description: 'Send run notifications via configured channels',
+    usage: [
+      'agent-os report-notify --run-dir <dir> --dry-run [options]',
+      'agent-os report-notify --run-root <dir> --send [options]'
+    ],
+    required: [
+      { flag: '--run-dir <dir> | --run-root <dir>', desc: 'Single run directory or runs root' },
+      { flag: '--send | --dry-run', desc: 'Send notification or write payload to file' }
+    ],
+    options: [
+      { flag: '--channel-config <file>', desc: 'Channel config file', default: '.agent-os/project/report-channels.json' },
+      { flag: '--channel <name>', desc: 'Channel name', default: 'telegram' },
+      { flag: '--output <file>', desc: 'Override output path' }
+    ],
+    examples: [
+      'agent-os report-notify --run-root .agent-os/runs --dry-run',
+      'agent-os report-notify --run-dir .agent-os/runs/my-run --send'
+    ]
+  });
+}
+
+function renderTelegramText(runs, event) {
+  const rows = Array.isArray(runs) ? runs : [runs];
+  const lines = [];
+  if (event) {
+    lines.push(`🚨 *Agent OS Lifecycle Alert: ${event.toUpperCase()}*`);
+  } else {
+    lines.push('*Agent OS Run Report*');
+  }
+  for (const run of rows) {
+    lines.push(`\n📅 *Run ID*: \`${escapeTelegramMarkdown(run.runId)}\``);
+    lines.push(`📊 *Status*: *${run.status.toUpperCase()}* (${run.counts.passed}/${run.total} passed, ${run.counts.failed} failed, ${run.counts.blocked} blocked)`);
+    if (run.plan) {
+      lines.push(`🎯 *Trigger*: ${escapeTelegramMarkdown(run.plan.trigger)}`);
+      lines.push(`📝 *Prompt*: _${escapeTelegramMarkdown(run.plan.prompt)}_`);
+    }
+    if (run.steps && run.steps.length > 0) {
+      lines.push('\n*Execution Steps:*');
+      run.steps.forEach(step => {
+        const icon = step.status === 'passed' ? '✅' : step.status === 'failed' ? '❌' : step.status === 'running' ? '⏳' : step.status === 'blocked' ? '🚧' : '⏳';
+        lines.push(`${icon} Step ${step.step}: \`${escapeTelegramMarkdown(step.skill)}\` (${step.status})`);
+      });
+    }
+    if (run.reportDetails && run.reportDetails.evidence && run.reportDetails.evidence !== 'N/A. Reason: Skills were not executed by this stub.') {
+      lines.push(`\n🔎 *Test Evidence:*`);
+      lines.push(`${run.reportDetails.evidence}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+const runDir = takeOption('--run-dir');
+const runRoot = takeOption('--run-root');
+const channelConfig = takeOption('--channel-config') ?? resolveDefault(null, '.agent-os/project/report-channels.json');
+const channelName = takeOption('--channel') ?? 'telegram';
+const outputOverride = takeOption('--output');
+const event = takeOption('--event');
+const dryRun = hasFlag('--dry-run');
+const send = hasFlag('--send');
+
+const errors = [];
+if ((dryRun && send) || (!dryRun && !send)) errors.push('Use either --dry-run or --send (exactly one required).');
+if (!runDir && !runRoot) errors.push('Missing --run-dir <dir> or --run-root <dir>.');
+if (runDir && runRoot) errors.push('Use either --run-dir or --run-root, not both.');
+if (!channelConfig) errors.push('Missing --channel-config <file> (no default found at .agent-os/project/report-channels.json).');
+failAll(errors, 'agent-os report-notify --run-root .agent-os/runs --channel telegram --dry-run', 'report-notify');
+
+let channelContext;
+try {
+  channelContext = loadReportChannel(channelConfig, channelName);
+  assertEnabledChannel(channelContext);
+} catch (err) {
+  fail(err.message);
+}
+
+const channel = channelContext.channel;
+if (channel.type !== 'telegram') {
+  fail(`Report channel is not a telegram channel: ${channelName}`);
+}
+
+let runs;
+try {
+  runs = runDir ? collectRun(runDir) : collectRuns(runRoot);
+} catch (err) {
+  fail(err.message);
+}
+const rows = Array.isArray(runs) ? runs : [runs];
+const botTokenEnv = channel.botTokenEnv ?? 'AGENT_OS_TELEGRAM_BOT_TOKEN';
+const chatIdEnv = channel.chatIdEnv ?? 'AGENT_OS_TELEGRAM_CHAT_ID';
+const chatId = process.env[chatIdEnv] ?? null;
+const message = {
+  parse_mode: 'Markdown',
+  text: renderTelegramText(rows, event)
+};
+
+if (send) {
+  const botToken = process.env[botTokenEnv];
+  if (!botToken) {
+    fail(`Missing required environment variable: ${botTokenEnv}`);
+  }
+  if (!chatId) {
+    fail(`Missing required environment variable: ${chatIdEnv}`);
+  }
+
+  const apiBaseUrl = channel.apiBaseUrl ?? 'https://api.telegram.org';
+  const telegramRequest = {
+    method: 'POST',
+    url: `${apiBaseUrl}/bot${botToken}/sendMessage`,
+    body: {
+      chat_id: chatId,
+      ...message
+    }
+  };
+
+  if (channel.mockRequestFile) {
+    const mockRequestPath = path.resolve(channelContext.outputBaseDir, channel.mockRequestFile);
+    fs.mkdirSync(path.dirname(mockRequestPath), { recursive: true });
+    fs.writeFileSync(mockRequestPath, `${JSON.stringify(telegramRequest, null, 2)}\n`);
+    console.log(`Channel: ${channelName}`);
+    console.log(`Sent notification: ${channelName}`);
+    process.exit(0);
+  }
+
+  const response = await fetch(telegramRequest.url, {
+    method: telegramRequest.method,
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(telegramRequest.body)
+  });
+
+  if (!response.ok) {
+    const responseText = await response.text();
+    fail(`Telegram send failed (${response.status}): ${responseText}`);
+  }
+
+  console.log(`Channel: ${channelName}`);
+  console.log(`Sent notification: ${channelName}`);
+  process.exit(0);
+}
+
+const payload = {
+  channel: channelName,
+  event: event,
+  mode: 'dry-run',
+  transport: 'telegram',
+  botTokenEnv,
+  chatIdEnv,
+  chatId,
+  message,
+  runs: rows
+};
+
+const outputPath = path.resolve(channelContext.outputBaseDir, outputOverride ?? channel.output ?? 'reports/telegram-payload.json');
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}\n`);
+console.log(`Channel: ${channelName}`);
+console.log(`Dry-run notification payload: ${outputPath}`);

package/scripts/run-execution.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { renderReport } from './lib/run-utils.mjs';
+import { createCli, fail, showHelp, wantsHelp } from './lib/cli-utils.mjs';
+
+const { takeOption } = createCli(process.argv.slice(2));
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'run-execution',
+    description: 'Execute a reviewed run directory',
+    usage: ['agent-os run-execution --run-dir <dir>'],
+    required: [{ flag: '--run-dir <dir>', desc: 'Path to the run directory' }],
+    examples: ['agent-os run-execution --run-dir .agent-os/runs/my-run']
+  });
+}
+
+const runDir = takeOption('--run-dir');
+if (!runDir) {
+  fail('Missing --run-dir <dir>. Run \'agent-os run-execution --help\' for usage.');
+}
+
+const absoluteRunDir = path.resolve(process.cwd(), runDir);
+const planPath = path.join(absoluteRunDir, 'plan.json');
+const stepsPath = path.join(absoluteRunDir, 'steps.json');
+const reportPath = path.join(absoluteRunDir, 'master-report.md');
+
+if (!fs.existsSync(planPath) || !fs.existsSync(stepsPath)) {
+  fail(`Run directory is missing plan.json or steps.json: ${absoluteRunDir}`);
+}
+
+const plan = JSON.parse(fs.readFileSync(planPath, 'utf8'));
+const steps = JSON.parse(fs.readFileSync(stepsPath, 'utf8'));
+
+if (plan.validation?.status !== 'PASS') {
+  fail(`Cannot execute invalid plan: ${plan.validation?.status ?? 'unknown'}`);
+}
+
+const evidence = [];
+for (const step of steps) {
+  if (step.status === 'failed' || step.status === 'blocked') {
+    fail(`Cannot execute step ${step.step} with status ${step.status}`);
+  }
+  if (step.status === 'passed') {
+    evidence.push(`Deterministic executor skipped already-passed step ${step.step}: ${step.skill}`);
+    continue;
+  }
+
+  const incompleteDependencies = step.dependsOn.filter((dependencySkill) => {
+    const dependencyStep = steps.find((candidate) => candidate.skill === dependencySkill);
+    return !dependencyStep || dependencyStep.status !== 'passed';
+  });
+  if (incompleteDependencies.length > 0) {
+    fail(`Dependencies must pass before step ${step.step} can execute: ${incompleteDependencies.join(', ')}`);
+  }
+
+  step.status = 'running';
+  step.status = 'passed';
+  evidence.push(`Deterministic executor passed step ${step.step}: ${step.skill}`);
+}
+
+plan.executionPlan = plan.executionPlan.map((step) => (
+  steps.find((updatedStep) => updatedStep.step === step.step) ?? step
+));
+plan.executionEvidence = [
+  ...(plan.executionEvidence ?? []),
+  ...evidence
+];
+plan.run = {
+  ...(plan.run ?? {}),
+  status: steps.every((step) => step.status === 'passed') ? 'complete' : 'running'
+};
+
+fs.writeFileSync(stepsPath, JSON.stringify(steps, null, 2) + '\n');
+fs.writeFileSync(planPath, JSON.stringify(plan, null, 2) + '\n');
+fs.writeFileSync(reportPath, renderReport(plan));
+
+console.log(JSON.stringify({
+  runDir: absoluteRunDir,
+  status: plan.run.status,
+  steps: steps.length
+}, null, 2));

package/scripts/run-list.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { collectRuns, renderRunSummariesCsv } from './lib/run-utils.mjs';
+import { createCli, fail, resolveDefault, showHelp, wantsHelp } from './lib/cli-utils.mjs';
+
+const { takeOption } = createCli(process.argv.slice(2));
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'run-list',
+    description: 'List all known runs',
+    usage: ['agent-os run-list [options]'],
+    options: [
+      { flag: '--run-root <dir>', desc: 'Run directory root', default: '.agent-os/runs' },
+      { flag: '--format <json|csv>', desc: 'Output format', default: 'json' }
+    ],
+    examples: [
+      'agent-os run-list',
+      'agent-os run-list --format csv'
+    ]
+  });
+}
+
+const runRoot = takeOption('--run-root') ?? resolveDefault(null, '.agent-os/runs');
+const format = takeOption('--format') ?? 'json';
+if (!runRoot) {
+  fail('Missing --run-root <dir> (no default found at .agent-os/runs). Run \'agent-os run-list --help\' for usage.');
+}
+
+if (!['json', 'csv'].includes(format)) {
+  fail(`Unsupported format: ${format}. Expected json or csv.`);
+}
+
+let runs;
+try {
+  runs = collectRuns(runRoot);
+} catch (err) {
+  fail(err.message);
+}
+
+if (format === 'csv') {
+  process.stdout.write(renderRunSummariesCsv(runs));
+} else {
+  console.log(JSON.stringify(runs, null, 2));
+}

package/scripts/run-status.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { collectRun, renderRunSummariesCsv } from './lib/run-utils.mjs';
+import { createCli, fail, showHelp, wantsHelp } from './lib/cli-utils.mjs';
+
+const { takeOption } = createCli(process.argv.slice(2));
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'run-status',
+    description: 'Show status of a specific run',
+    usage: ['agent-os run-status --run-dir <dir> [options]'],
+    required: [{ flag: '--run-dir <dir>', desc: 'Path to the run directory' }],
+    options: [{ flag: '--format <json|csv>', desc: 'Output format', default: 'json' }],
+    examples: ['agent-os run-status --run-dir .agent-os/runs/my-run']
+  });
+}
+
+const runDir = takeOption('--run-dir');
+const format = takeOption('--format') ?? 'json';
+if (!runDir) {
+  fail('Missing --run-dir <dir>. Run \'agent-os run-status --help\' for usage.');
+}
+
+if (!['json', 'csv'].includes(format)) {
+  fail(`Unsupported format: ${format}. Expected json or csv.`);
+}
+
+let summary;
+try {
+  summary = collectRun(runDir);
+} catch (err) {
+  fail(err.message);
+}
+if (format === 'csv') {
+  process.stdout.write(renderRunSummariesCsv(summary));
+} else {
+  console.log(JSON.stringify(summary, null, 2));
+}