agent-orchestrator-kit 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-29
+
+### Added
+- **Change metrics** — git-tracked `openspec/changes/<name>/metrics.json`: `handoff --restore` records the session start (`pending` marker), `handoff <name>` closes the session (duration, closed role → phase `explore|design|spec|review|apply|archive`, runtime, tasks snapshot, optional `--model` / `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd`, `--started-at` when restore was skipped, `--no-metrics` to opt out), `archive <name>` sets `archivedAt`; per-phase and total aggregates (durations, tokens, cost, agents, models, `leadTimeMs`) are recomputed on every write and unreported values stay null-honest
+- **`npx agent-orchestrator-kit metrics [change-name] [--json]`** — human summary (phases table, spend, recent sessions) or raw JSON; resolves archived changes under `openspec/changes/archive/*-<name>` too
+
 ## [0.4.0] - 2026-08-28
 
 ### Added
@@ -193,6 +199,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[0.5.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.14...v0.2.0

package/README.md

@@ -74,7 +74,7 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Upgrade to latest (factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
+**🔄 Already have the kit installed? Upgrade to latest (change metrics in v0.5.0+, factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
@@ -191,7 +191,7 @@ your-project/
 | OpenSpec skills | All 7 skills for `/opsx:*` workflow |
 | IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills/subagents) |
 | Subagents | 12 exclusive routes: guide/setup/session-handoff, explore/design/propose/review/archive stage agents, and apply implementation/test/code-review agents — native in Cursor + Claude Code, isolated Amp `subagent-*` wrappers |
-| CLI gates | `npx agent-orchestrator-kit status` / `gate-check` / `archive` / `handoff` / `memory-setup` — deterministic review-gate, archive, and session-handoff (always via `npx`; see `cli-via-npm.mdc`) |
+| CLI gates | `npx agent-orchestrator-kit status` / `gate-check` / `archive` / `handoff` / `metrics` / `memory-setup` — deterministic review-gate, archive, session-handoff, and change metrics (always via `npx`; see `cli-via-npm.mdc`) |
 | CI | `agent-verify.yml` — GitHub (default) or GitLab fragment + `prebuild` hook, both run `gate-check` |
 | AI Spec Verifier | `spec-verify.yml` + verifier scripts — GitLab or GitHub, opt-in (`--spec-verify`) |
 | MCP templates | Memory MCP for Cursor and Amp |
@@ -797,6 +797,24 @@ npx agent-orchestrator-kit handoff <name> --cloud-check   # require exit 0
 
 Persist with `runtime: cloud` prints those four steps on stderr; stdout stays the pure `/opsx:` next-thread prompt. Local persist is unchanged.
 
+### Change metrics
+
+Every change accumulates git-tracked `openspec/changes/<name>/metrics.json` — the data source for planning the next feature: how long each phase took, how many sessions it needed, what it cost.
+
+- **Session start** — `handoff --restore` writes a `pending` marker (`startedAt`, expected role).
+- **Session end** — `handoff <name>` closes the pending session: duration, closed role, mapped phase (`explore` / `design` / `spec` / `review` / `apply` / `archive`), runtime (local/cloud), tasks snapshot (`n/m`), and — when the agent passes them — `--model`, `--input-tokens`, `--output-tokens`, `--total-tokens`, `--cost-usd`. No restore marker? Pass `--started-at <iso>` or the duration stays honestly `null`.
+- **Archive** — `archive <name>` sets `archivedAt` and clears any pending marker; the file moves to the archive folder with the change.
+
+Aggregates are recomputed on every write: per-phase totals (`durationMs`, tokens, `costUsd`, `sessions`, agents, models) plus overall `totals` (`sessions`, `cloudSessions`, `durationMs` = sum of session work time, `leadTimeMs` = wall clock from first session start to last session end) and `spend` (token/cost sums). Numbers are null-honest: a metric nobody reported stays `null`, never a fake `0`.
+
+```bash
+npx agent-orchestrator-kit handoff add-thing --input-tokens 12000 --output-tokens 3000 --cost-usd 0.42 --model claude-sonnet
+npx agent-orchestrator-kit metrics add-thing          # human summary: phases, tokens, cost, agents
+npx agent-orchestrator-kit metrics add-thing --json   # raw metrics.json (works for archived changes too)
+```
+
+Recording is on by default and never blocks persist; opt out per session with `--no-metrics`.
+
 ### Skill inventory
 
 `.agents/orchestrator.yaml` carries a machine-readable `skills:` section (`kit` / `stack` / `external`) instead of hardcoded skill names in the CLI:
@@ -900,10 +918,21 @@ npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
 
 npx agent-orchestrator-kit handoff [change-name] [options]
   --restore          Print the restore briefing instead of persisting
+                     (also records the session start into metrics.json)
   --runtime <value>  local | cloud (invalid values exit non-zero)
   --agent-id <id>    Cloud agent identifier (default: none)
   --cloud-check      Verify change artifacts are committed and pushed
                      (cloud: non-zero on failure; local: warning, exit 0)
+  --started-at <iso> Session start override when --restore was not run
+  --model <name>     Model used in this session (metrics.json)
+  --input-tokens <n> / --output-tokens <n> / --total-tokens <n>
+                     Token spend for this session (total defaults to in+out)
+  --cost-usd <usd>   Session cost in USD
+  --no-metrics       Skip recording this session into metrics.json
+
+npx agent-orchestrator-kit metrics [change-name] [--json]
+  Show recorded session metrics for a change (active or archived):
+  time per phase, sessions, tokens, cost, agents, models, lead time
 ```
 
 ## Directory Reference
@@ -936,7 +965,7 @@ CLAUDE.md                # Committed — synced to .claude/CLAUDE.md
 openspec/                # Committed — spec-driven workflow
   config.yaml            # Project context for AI
   specs/                 # Source of truth after archive
-  changes/               # Active work; <name>/handoff.md indexes session state
+  changes/               # Active work; <name>/handoff.md + metrics.json index session state
 ```
 
 ## Roadmap
@@ -950,6 +979,11 @@ Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](o
 
 ## Changelog
 
+### 0.5.0
+- **Change metrics** — git-tracked `openspec/changes/<name>/metrics.json` (session start on `handoff --restore`, close on persist)
+- **`metrics` CLI** — human summary or `--json`; phases, tokens, cost, agents, models, lead time
+- Optional persist spend flags: `--model`, `--input-tokens`, `--output-tokens`, `--total-tokens`, `--cost-usd`, `--started-at`, `--no-metrics`
+
 ### 0.4.0
 - Factory phases 1–3: `hooks-setup` / `gate-check --staged`, `mcp-setup` (GitHub / GitLab / browser), MCP and Skill health in `status`
 - Git-canonical append-only `decisions.md`; Memory `Decision:*` is a file→Memory mirror

package/bin/agent-orchestrator.js

@@ -1290,6 +1290,215 @@ function readHandoffFields(projectDir, changeName) {
   return { filePath, fields: fieldsFromSections(changeName, sections) };
 }
 
+const METRICS_VERSION = 1;
+const METRICS_SPEND_KEYS = ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd'];
+
+function metricsFilePath(projectDir, changeName) {
+  return join(projectDir, 'openspec', 'changes', changeName, 'metrics.json');
+}
+
+function emptySpendTotals() {
+  return { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null };
+}
+
+function defaultMetrics(changeName, nowIso) {
+  return {
+    version: METRICS_VERSION,
+    change: changeName,
+    createdAt: nowIso,
+    updatedAt: nowIso,
+    archivedAt: null,
+    spend: emptySpendTotals(),
+    totals: { sessions: 0, durationMs: null, leadTimeMs: null, cloudSessions: 0 },
+    phases: {},
+    sessions: [],
+    pending: null,
+  };
+}
+
+function loadMetricsFile(filePath, changeName, nowIso) {
+  if (!existsSync(filePath)) return defaultMetrics(changeName, nowIso);
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    return defaultMetrics(changeName, nowIso);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return defaultMetrics(changeName, nowIso);
+  }
+  const base = defaultMetrics(changeName, parsed.createdAt || nowIso);
+  return {
+    ...base,
+    ...parsed,
+    version: METRICS_VERSION,
+    change: changeName,
+    spend: { ...base.spend, ...(parsed.spend && typeof parsed.spend === 'object' ? parsed.spend : {}) },
+    totals: { ...base.totals, ...(parsed.totals && typeof parsed.totals === 'object' ? parsed.totals : {}) },
+    phases: parsed.phases && typeof parsed.phases === 'object' && !Array.isArray(parsed.phases) ? parsed.phases : {},
+    sessions: Array.isArray(parsed.sessions) ? parsed.sessions : [],
+  };
+}
+
+function saveMetricsFile(filePath, metrics) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(metrics, null, 2)}\n`);
+}
+
+function numOrNull(value) {
+  if (value == null || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function addNullable(a, b) {
+  if (a == null && b == null) return null;
+  return (a ?? 0) + (b ?? 0);
+}
+
+function phaseForRole(role) {
+  const value = String(role || '').toLowerCase();
+  if (/explor/.test(value)) return 'explore';
+  if (/review/.test(value)) return 'review';
+  if (/implement|apply|code-writer|test-writer/.test(value)) return 'apply';
+  if (/architect|propose/.test(value)) return 'spec';
+  if (/design/.test(value)) return 'design';
+  if (/archiv/.test(value)) return 'archive';
+  return 'other';
+}
+
+function isoOrNull(value) {
+  if (!value) return null;
+  const ms = Date.parse(String(value));
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+
+function recomputeMetricsAggregates(metrics) {
+  const phases = {};
+  const totals = { sessions: 0, durationMs: null, leadTimeMs: null, cloudSessions: 0 };
+  const spend = emptySpendTotals();
+  let firstStart = null;
+  let lastEnd = null;
+  for (const session of metrics.sessions) {
+    totals.sessions += 1;
+    if (session.runtime === 'cloud') totals.cloudSessions += 1;
+    totals.durationMs = addNullable(totals.durationMs, numOrNull(session.durationMs));
+    if (session.startedAt && (firstStart == null || session.startedAt < firstStart)) firstStart = session.startedAt;
+    if (session.endedAt && (lastEnd == null || session.endedAt > lastEnd)) lastEnd = session.endedAt;
+    const key = session.phase || 'other';
+    const phase = phases[key] || { sessions: 0, durationMs: null, ...emptySpendTotals(), agents: [], models: [] };
+    phase.sessions += 1;
+    phase.durationMs = addNullable(phase.durationMs, numOrNull(session.durationMs));
+    for (const spendKey of METRICS_SPEND_KEYS) {
+      const value = numOrNull(session[spendKey]);
+      phase[spendKey] = addNullable(phase[spendKey], value);
+      spend[spendKey] = addNullable(spend[spendKey], value);
+    }
+    if (session.role && !phase.agents.includes(session.role)) phase.agents.push(session.role);
+    if (session.model && !phase.models.includes(session.model)) phase.models.push(session.model);
+    phases[key] = phase;
+  }
+  if (firstStart && lastEnd) {
+    totals.leadTimeMs = Math.max(0, Date.parse(lastEnd) - Date.parse(firstStart));
+  }
+  metrics.phases = phases;
+  metrics.totals = totals;
+  metrics.spend = spend;
+}
+
+function metricsRecordSessionStart(projectDir, changeName, role) {
+  const filePath = metricsFilePath(projectDir, changeName);
+  const nowIso = new Date().toISOString();
+  const metrics = loadMetricsFile(filePath, changeName, nowIso);
+  metrics.pending = { startedAt: nowIso, role: role || '' };
+  metrics.updatedAt = nowIso;
+  saveMetricsFile(filePath, metrics);
+  return filePath;
+}
+
+function metricsRecordSessionEnd(projectDir, fields, opts = {}) {
+  const filePath = metricsFilePath(projectDir, fields.changeName);
+  const nowIso = new Date().toISOString();
+  const metrics = loadMetricsFile(filePath, fields.changeName, nowIso);
+  const startedAt = isoOrNull(opts.startedAt) || (metrics.pending && metrics.pending.startedAt) || null;
+  const durationMs = startedAt ? Math.max(0, Date.parse(nowIso) - Date.parse(startedAt)) : null;
+  const inputTokens = numOrNull(opts.inputTokens);
+  const outputTokens = numOrNull(opts.outputTokens);
+  let totalTokens = numOrNull(opts.totalTokens);
+  if (totalTokens == null && (inputTokens != null || outputTokens != null)) {
+    totalTokens = (inputTokens ?? 0) + (outputTokens ?? 0);
+  }
+  metrics.sessions.push({
+    startedAt,
+    endedAt: nowIso,
+    durationMs,
+    role: fields.closedRole || '',
+    phase: phaseForRole(fields.closedRole),
+    runtime: fields.runtime || 'local',
+    agentId: fields.agentId || 'none',
+    model: opts.model || null,
+    tasks: fields.tasks || null,
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    costUsd: numOrNull(opts.costUsd),
+  });
+  metrics.pending = null;
+  metrics.updatedAt = nowIso;
+  recomputeMetricsAggregates(metrics);
+  saveMetricsFile(filePath, metrics);
+  return filePath;
+}
+
+function metricsFinalizeArchive(targetDir, changeName) {
+  const filePath = join(targetDir, 'metrics.json');
+  if (!existsSync(filePath)) return null;
+  const nowIso = new Date().toISOString();
+  const metrics = loadMetricsFile(filePath, changeName, nowIso);
+  metrics.archivedAt = nowIso;
+  metrics.pending = null;
+  metrics.updatedAt = nowIso;
+  recomputeMetricsAggregates(metrics);
+  saveMetricsFile(filePath, metrics);
+  return filePath;
+}
+
+function formatMetricsDuration(durationMs) {
+  if (durationMs == null || !Number.isFinite(durationMs)) return '—';
+  const totalSeconds = Math.max(0, Math.round(durationMs / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  if (hours > 0) return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  if (minutes > 0) return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+  return `${seconds}s`;
+}
+
+function formatMetricsNumber(value) {
+  return value == null ? '—' : String(value);
+}
+
+function formatMetricsCost(value) {
+  return value == null ? '—' : `$${Number(value).toFixed(2)}`;
+}
+
+function resolveMetricsFile(projectDir, changeName) {
+  const activePath = metricsFilePath(projectDir, changeName);
+  if (existsSync(activePath)) return { filePath: activePath, archived: false };
+  const archiveDir = join(projectDir, 'openspec', 'changes', 'archive');
+  if (existsSync(archiveDir)) {
+    const folders = readdirSync(archiveDir)
+      .filter((name) => name === changeName || name.endsWith(`-${changeName}`))
+      .sort()
+      .reverse();
+    for (const folder of folders) {
+      const archivedPath = join(archiveDir, folder, 'metrics.json');
+      if (existsSync(archivedPath)) return { filePath: archivedPath, archived: true };
+    }
+  }
+  return { filePath: activePath, archived: false, missing: true };
+}
+
 function parseFigmaUrl(url) {
   try {
     const parsed = new URL(url);
@@ -2564,6 +2773,7 @@ program
     };
     writeFileSync(join(targetDir, 'handoff.md'), `${buildHandoffMarkdown(fields).trim()}\n`);
     const memoryPath = persistMemoryFromHandoff(projectDir, fields);
+    const metricsPath = metricsFinalizeArchive(targetDir, name);
 
     console.log(`change:   ${name}`);
     console.log(`schema:   ${status.schemaName || 'unknown'}`);
@@ -2571,6 +2781,7 @@ program
     console.log(`sync:     ${syncStatus}`);
     console.log(`handoff:  ${join(targetRel, 'handoff.md')} (next_command: none)`);
     console.log(`memory:   ${memoryPath.replace(`${projectDir}/`, '')}`);
+    if (metricsPath) console.log(`metrics:  ${metricsPath.replace(`${projectDir}/`, '')} (archived_at set)`);
     log.ok(`archived ${name}`);
   });
 
@@ -2770,6 +2981,13 @@ program
   .option('--runtime <runtime>', 'Session runtime: local | cloud')
   .option('--agent-id <id>', 'Cloud agent identifier')
   .option('--cloud-check', 'Verify change artifacts are committed and pushed', false)
+  .option('--started-at <iso>', 'Session start timestamp (overrides the pending marker from --restore)')
+  .option('--model <name>', 'Model used in this session (recorded in metrics.json)')
+  .option('--input-tokens <n>', 'Input tokens spent in this session')
+  .option('--output-tokens <n>', 'Output tokens spent in this session')
+  .option('--total-tokens <n>', 'Total tokens spent in this session (default: input + output)')
+  .option('--cost-usd <usd>', 'Cost of this session in USD')
+  .option('--no-metrics', 'Skip recording this session into metrics.json')
   .action((changeName, opts) => {
     const projectDir = process.cwd();
     const resolved = resolveHandoffChange(projectDir, changeName);
@@ -2826,6 +3044,10 @@ program
       } else {
         log.warn(`Memory JSON empty or missing at ${memoryPath}`);
       }
+      if (opts.metrics !== false && existsSync(changeDir)) {
+        const metricsPath = metricsRecordSessionStart(projectDir, name, fields ? fields.nextRole : '');
+        log.ok(`metrics: session start recorded (${metricsPath.replace(`${projectDir}/`, '')})`);
+      }
       return;
     }
 
@@ -2902,10 +3124,100 @@ program
     const memoryPath = persistMemoryFromHandoff(projectDir, fields);
     console.error(pc.green('  ✓'), `Memory JSON upserted: ${memoryPath}`);
 
+    if (opts.metrics !== false) {
+      const metricsPath = metricsRecordSessionEnd(projectDir, fields, {
+        startedAt: opts.startedAt,
+        model: opts.model,
+        inputTokens: opts.inputTokens,
+        outputTokens: opts.outputTokens,
+        totalTokens: opts.totalTokens,
+        costUsd: opts.costUsd,
+      });
+      console.error(pc.green('  ✓'), `metrics.json updated: ${metricsPath.replace(`${projectDir}/`, '')}`);
+    }
+
     if (fields.runtime === 'cloud') printCloudPersistNextSteps(name);
 
     console.error(pc.dim('Copy the prompt below into the next chat as one fenced block. Do not include this line.'));
     process.stdout.write(`${prompt}\n`);
   });
 
+program
+  .command('metrics [change-name]')
+  .description('Show recorded session metrics for a change: time per phase, tokens, cost, agents, models')
+  .option('--json', 'Print raw metrics.json', false)
+  .action((changeName, opts) => {
+    const projectDir = process.cwd();
+    let name = changeName;
+    if (!name) {
+      const resolved = resolveHandoffChange(projectDir, changeName);
+      if (!resolved) {
+        log.err('No active change found. Pass a name: npx agent-orchestrator-kit metrics <name>');
+        process.exitCode = 1;
+        return;
+      }
+      if (resolved.ambiguous) {
+        log.err(`Multiple active changes: ${resolved.ambiguous.join(', ')}. Pass the change name argument.`);
+        process.exitCode = 1;
+        return;
+      }
+      name = resolved;
+    }
+
+    const { filePath, archived, missing } = resolveMetricsFile(projectDir, name);
+    if (missing) {
+      log.err(`No metrics.json for ${name}`);
+      log.info(`Expected: ${filePath.replace(`${projectDir}/`, '')}`);
+      log.info('Metrics are recorded by: handoff --restore (session start) and handoff <name> (session end)');
+      process.exitCode = 1;
+      return;
+    }
+
+    const metrics = loadMetricsFile(filePath, name, new Date().toISOString());
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(metrics, null, 2)}\n`);
+      return;
+    }
+
+    log.title(`metrics  ${name}${archived ? '  (archived)' : ''}`);
+    console.log(`file:      ${filePath.replace(`${projectDir}/`, '')}`);
+    console.log(`sessions:  ${metrics.totals.sessions}${metrics.totals.cloudSessions ? ` (cloud: ${metrics.totals.cloudSessions})` : ''}`);
+    console.log(`work time: ${formatMetricsDuration(metrics.totals.durationMs)}`);
+    console.log(`lead time: ${formatMetricsDuration(metrics.totals.leadTimeMs)}`);
+    console.log(`tokens:    ${formatMetricsNumber(metrics.spend.totalTokens)} (in: ${formatMetricsNumber(metrics.spend.inputTokens)}, out: ${formatMetricsNumber(metrics.spend.outputTokens)})`);
+    console.log(`cost:      ${formatMetricsCost(metrics.spend.costUsd)}`);
+    if (metrics.archivedAt) console.log(`archived:  ${metrics.archivedAt}`);
+    if (metrics.pending) log.warn(`open session since ${metrics.pending.startedAt} (${metrics.pending.role || 'unknown role'})`);
+
+    const phaseOrder = ['explore', 'design', 'spec', 'review', 'apply', 'archive', 'other'];
+    const phaseKeys = phaseOrder.filter((key) => metrics.phases[key]);
+    if (phaseKeys.length) {
+      console.log('');
+      console.log('phase      sessions  time      tokens    cost      agents');
+      for (const key of phaseKeys) {
+        const phase = metrics.phases[key];
+        const cols = [
+          key.padEnd(10),
+          String(phase.sessions).padEnd(9),
+          formatMetricsDuration(phase.durationMs).padEnd(9),
+          formatMetricsNumber(phase.totalTokens).padEnd(9),
+          formatMetricsCost(phase.costUsd).padEnd(9),
+          phase.agents.join(', ') || '—',
+        ];
+        console.log(cols.join(' '));
+      }
+    }
+
+    if (metrics.sessions.length) {
+      console.log('');
+      console.log('recent sessions:');
+      for (const session of metrics.sessions.slice(-5)) {
+        const spendLabel = session.totalTokens != null || session.costUsd != null
+          ? ` — ${formatMetricsNumber(session.totalTokens)} tok, ${formatMetricsCost(session.costUsd)}`
+          : '';
+        console.log(`- ${session.endedAt}  ${session.phase.padEnd(7)} ${formatMetricsDuration(session.durationMs).padEnd(9)} ${session.role || '(no role)'}${session.model ? ` [${session.model}]` : ''}${spendLabel}`);
+      }
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, conductor subagents, durable session handoff, factory gates and MCP setup, cloud-agent handoff, and optional local Figma PAT setup",
   "keywords": [
     "ai-agent",

package/templates/.agents/rules/session-handoff.mdc

@@ -20,7 +20,7 @@ Agents (local or cloud) write session artifacts only to git-tracked paths — ne
 
 ## Session Exit (order)
 1. The parent writes `openspec/changes/<name>/handoff.md` itself: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime.
-2. `npx agent-orchestrator-kit handoff <name>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, prints the expanded prompt on stdout). `decisions.md` is the git canon of change decisions; Memory `Decision:*` is a file→Memory mirror only. Cloud sessions pass `--runtime cloud` (or set `AOK_RUNTIME=cloud` / `AOK_AGENT_ID` in the cloud-agent environment).
+2. `npx agent-orchestrator-kit handoff <name>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, records the session into `openspec/changes/<name>/metrics.json`, prints the expanded prompt on stdout). `decisions.md` is the git canon of change decisions; Memory `Decision:*` is a file→Memory mirror only. Cloud sessions pass `--runtime cloud` (or set `AOK_RUNTIME=cloud` / `AOK_AGENT_ID` in the cloud-agent environment). When session spend is known, pass it to persist: `--model <name> --input-tokens <n> --output-tokens <n> --cost-usd <usd>` — metrics power planning; never guess values you do not know.
 3. Spawn `session-handoff` in persist mode ONLY if step 2 failed (Amp: isolated `subagent-session-handoff`). Fallback, never routine.
 4. Memory MCP is an optional mirror: if tools are available, update `Change:<name>`, `Handoff:<name>`, `Decision:*` in one call; unavailability never blocks closing.
 5. Paste CLI stdout as one fenced block. First line `/opsx:…`. Body uses `project.agent_language`. Self-contained (Done/Decisions/Blocked/spawn/HARD STOP). No banner.