agent-orchestrator-kit 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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
+- **Phase 3 cloud agent handoff** — persist writes `## Runtime` (`runtime: local|cloud`, `agent_id`) via `--runtime` → `AOK_RUNTIME` → `CLOUD_ENV_MARKERS` → existing section → `local`; `handoff <name> --cloud-check` blocks on uncommitted/unpushed artifacts for cloud (local: warning, exit 0); persist never commits/pushes — cloud sessions print persist → commit → push → cloud-check on stderr
+- **Phase 2 decisions canon** — git-tracked append-only `openspec/changes/<name>/decisions.md`; `npx agent-orchestrator-kit handoff <name>` appends dated bullets from `handoff.md ## Decisions` (no duplicates; same topic + new text keeps history); Memory `Decision:*` mirrors the file (last topic wins, file → Memory only); `handoff --restore` prints from the git file or `decisions: none`
+- **Skill inventory** — `skills.kit` / `skills.stack` / `skills.external` in `orchestrator.yaml` (template + all profiles); kit skill list for `init`/`update` is enumerated from `templates/.agents/skills/` (no hardcoded `KIT_SKILL_DIRS`); `status` prints warn-only Skill health (`ok` / `missing` / `stale`) plus Amp wrapper freshness; missing stack skills hint `npx <external> install --agent all --yes` without running an install
+- **`agentic-factory-roadmap`** — planning (docs-only) capability: sequences factory phases 1–4 and records platform-level non-goals; implementation stays in later changes
+- **Phase 1 factory gates & MCP** — opt-in pre-commit `gate-check --staged` via `hooks-setup` / `init --hooks` (husky-first, otherwise `core.hooksPath=.githooks`; never writes `.git/hooks/`)
+- **`mcp-setup`** — GitHub / GitLab / browser stdio launchers (Figma pattern); VCS host from `git remote origin` (not `--ci`); `--vcs` override; `--no-browser`
+- **MCP health** in `status` (`ok` / `not configured` / `skipped`) without printing token values
+- Committed examples list `memory`, `figma`, `github`, `gitlab`, `browser`; gitignored `.agents/github.local.env` and `.agents/gitlab.local.env`
+
 ## [0.3.0] - 2026-08-18
 
 ### Added
@@ -181,6 +199,8 @@ 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
 [0.1.14]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.13...v0.1.14

package/README.md

@@ -74,12 +74,14 @@ 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 (lean pipeline v2 / 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
 npx agent-orchestrator-kit@latest sync         # or: ./scripts/sync-local-agent-skills.sh
+npx agent-orchestrator-kit@latest mcp-setup    # optional — GitHub/GitLab from origin + browser
 npx agent-orchestrator-kit@latest figma-setup  # optional — local Figma token
+npx agent-orchestrator-kit@latest hooks-setup  # optional — pre-commit review gate
 npx agent-orchestrator-kit@latest status
 ```
 
@@ -189,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 |
@@ -468,13 +470,13 @@ Orchestration hard rules (review approval, one active change) used to rely entir
 npx agent-orchestrator-kit status
 ```
 
-Prints every active OpenSpec change with task progress (`N/M tasks`), review verdict (`APPROVE` / `REQUEST CHANGES` / `none`), design brief (`brief: yes/no`), and a `ready to archive` flag once all tasks are `[x]` — no more running `openspec status` per change by hand.
+Prints every active OpenSpec change with task progress (`N/M tasks`), review verdict (`APPROVE` / `REQUEST CHANGES` / `none`), design brief (`brief: yes/no`), a `ready to archive` flag once all tasks are `[x]`, and an **MCP health** section (launcher / env / live config — never prints token values). VCS tools that do not match `git remote origin` show as `skipped (no origin match)`.
 
 ```bash
-npx agent-orchestrator-kit gate-check [change-name] [--src-glob src/] [--base HEAD~1]
+npx agent-orchestrator-kit gate-check [change-name] [--src-glob src/] [--base HEAD~1] [--staged]
 ```
 
-Fails (non-zero exit) when `pipeline.require_spec_review: true`, the diff against `--base` touches `--src-glob`, and the active change has no `review.md` with `Verdict: APPROVE`. When `pipeline.require_design_brief: true` and `src/` changed, it also requires `design-brief.md` (or a `Design: none` line in `proposal.md` for non-UI changes). It degrades gracefully to exit 0 (with a message, not silently) when: `.agents/orchestrator.yaml` is missing, neither review nor design brief is required, the diff can't be computed (e.g. shallow clone), or nothing under `--src-glob` changed. It also warns (never fails) when active changes exceed `pipeline.max_active_changes`. Both `agent-verify.yml` fragments (GitHub and GitLab) call `gate-check` automatically.
+Fails (non-zero exit) when `pipeline.require_spec_review: true`, the diff against `--base` (or **staged** files with `--staged`) touches `--src-glob`, and the active change has no `review.md` with `Verdict: APPROVE`. When `pipeline.require_design_brief: true` and `src/` changed, it also requires `design-brief.md` (or a `Design: none` line in `proposal.md` for non-UI changes). It degrades gracefully to exit 0 (with a message, not silently) when: `.agents/orchestrator.yaml` is missing, neither review nor design brief is required, the diff can't be computed (e.g. shallow clone), or nothing under `--src-glob` changed. It also warns (never fails) when active changes exceed `pipeline.max_active_changes`. Both `agent-verify.yml` fragments (GitHub and GitLab) call `gate-check` automatically. Pre-commit uses `--staged` so it checks the index, not `HEAD~1`.
 
 ```bash
 npx agent-orchestrator-kit gate-check --tasks <change-name>
@@ -488,6 +490,60 @@ npx agent-orchestrator-kit gate-check --review <change-name> [--json]
 
 Deterministic Tier 1 of the review phase: strict OpenSpec validation, the task-contract lint, `Non-goals` / `Acceptance criteria` sections in `proposal.md`, and non-empty ADDED/MODIFIED/REMOVED sections in delta specs. Human-readable stdout, or `--json` for a `{pass, errors[]}` report.
 
+### Pre-commit review gate (optional)
+
+`gate-check` already exists; it is **not** wired to `git commit` unless you opt in. The kit never writes `.git/hooks/` directly.
+
+```bash
+npx agent-orchestrator-kit hooks-setup
+# or: npx agent-orchestrator-kit init --hooks
+```
+
+- If `.husky/` exists, a marked line `sh scripts/pre-commit-gate-check.sh` is appended to `.husky/pre-commit` (idempotent; existing content is kept). `core.hooksPath` is not changed.
+- Otherwise the kit writes committed `.githooks/pre-commit` and runs `git config core.hooksPath .githooks`. If `core.hooksPath` is already set to something else, the command refuses and prints a manual line to add.
+- Lefthook: add `sh scripts/pre-commit-gate-check.sh` to your pre-commit job yourself (no auto-write).
+- `init` without `--hooks` still installs `scripts/pre-commit-gate-check.sh` as a managed file, unconnected.
+- Disable: remove the marked line from `.husky/pre-commit`, or `git config --unset core.hooksPath`.
+- MVP (`require_spec_review: false`): the hook is a no-op (exit 0).
+- Keep `agent-orchestrator-kit` in the project's **devDependencies** so `npx agent-orchestrator-kit` on every commit does not cold-fetch from the registry.
+
+Run `hooks-setup` on each machine (`git config` is local), same as `figma-setup`.
+
+### Optional MCP: GitHub, GitLab, browser
+
+Same pattern as Figma: stdio launcher + gitignored env + committed `.example`. Tokens never go in chat or committed MCP JSON.
+
+```bash
+npx agent-orchestrator-kit mcp-setup
+```
+
+Detection uses `git remote get-url origin` (https and ssh). `--ci` is ignored.
+
+| Origin hostname | Installed VCS MCP |
+|-----------------|-------------------|
+| `github.com` | GitHub only |
+| `gitlab.com` or hostname contains `gitlab` (self-hosted) | GitLab only; `GITLAB_API_URL=https://<hostname>/api/v4` |
+| missing / unrecognized | no VCS MCP (`status` shows skipped) |
+
+Browser MCP (`@playwright/mcp`) is always added unless you pass `--no-browser`. Override detection with `--vcs github` or `--vcs gitlab`.
+
+```bash
+npx agent-orchestrator-kit mcp-setup --vcs gitlab --no-browser
+```
+
+Then put tokens **only** in the gitignored files (never in chat):
+
+| Path | Git |
+|------|-----|
+| `.agents/github.local.env` | ignored |
+| `.agents/gitlab.local.env` | ignored |
+| `.agents/*.local.env.example` | committed |
+| `scripts/*-mcp-launcher.cjs` | committed |
+
+Cursor, Claude Code, and Amp all spawn the same launchers. Committed examples list all five servers (`memory`, `figma`, `github`, `gitlab`, `browser`); live `.mcp.json` / `.amp/settings.json` receive only the detected VCS plus browser.
+
+`npx agent-orchestrator-kit status` prints MCP health (`ok` / `not configured` / `skipped`) without token values.
+
 ---
 
 ### Design intake: `/opsx:design`
@@ -695,6 +751,92 @@ Handoff:add-bulk-export    next_role: implementer, next_command: /opsx:apply add
 
 Session boundaries are **parent-driven** (no routine subagent): every `/opsx:*` session restores via `npx agent-orchestrator-kit handoff --restore` (the CLI briefing already reads memory.json and `handoff.md`), falling back to reading `handoff.md` directly if the CLI fails. At exit the parent itself writes `handoff.md`, runs `npx agent-orchestrator-kit handoff <name>` (upserts `.cursor/memory.json` with an absolute path), and pastes the CLI stdout prompt. The `session-handoff` subagent is spawned only when the CLI path fails; Memory MCP is an optional mirror. The prompt is self-contained — Amp often skips Memory MCP, so the next thread must be able to work from the pasted text alone. Never configure Memory with a relative `MEMORY_FILE_PATH`; use `scripts/memory-mcp-launcher.cjs` (`npx agent-orchestrator-kit memory-setup`). The next phase always starts in a new chat. The canonical Session Start / Exit protocol lives in one place — `.agents/rules/session-handoff.mdc` — and the `/opsx:*` commands reference it instead of duplicating it.
 
+### Change decisions (`decisions.md`)
+
+Session decisions accumulate in git-tracked, append-only `openspec/changes/<name>/decisions.md`. That file is the canon visible in a PR/MR; Memory `Decision:*` is a **file → Memory** mirror only.
+
+```bash
+npx agent-orchestrator-kit handoff add-bulk-export
+# appends dated bullets from handoff.md ## Decisions (skips duplicates; same topic + new text → new row)
+npx agent-orchestrator-kit handoff add-bulk-export --restore
+# prints decisions from the git file (or `decisions: none` if the file does not exist)
+```
+
+`Decisions: none` does not create the file. Re-running persist with the same handoff does not duplicate rows. A later revision of the same topic is a new line; the old line stays. `update` does not migrate historical Memory entities into the file.
+
+### Cloud agent handoff (Phase 3)
+
+Every persist writes a `## Runtime` section to `openspec/changes/<name>/handoff.md`:
+
+```
+## Runtime
+- runtime: local|cloud
+- agent_id: <id|none>
+```
+
+Detection is a fixed chain (no TTY / `CURSOR_AGENT` magic): `--runtime` → env `AOK_RUNTIME` → `CLOUD_ENV_MARKERS` (starts with `CURSOR_BACKGROUND_AGENT`) → existing `## Runtime` in the file → `local`. `agent_id` uses `--agent-id` → `AOK_AGENT_ID` → existing value → `none`. Invalid `--runtime` (not `local` or `cloud`) exits non-zero. Legacy files without Runtime stay valid; the next persist appends the section.
+
+Configure a cloud agent once:
+
+```
+AOK_RUNTIME=cloud
+AOK_AGENT_ID=<vm-or-run-id>
+```
+
+`--cloud-check` is a **separate** branch of `handoff`, never part of persist (persist has just rewritten `handoff.md`, so the tree is always dirty at that point). It verifies (1) `git status --porcelain -- openspec/changes/<name>/` is empty and (2) the current branch has an upstream with no unpushed commits. Verdict: `cloud` + any failure = non-zero; `local` + the same failure = warning + exit 0; clean = exit 0. The CLI never runs `git commit` or `git push`.
+
+Cloud Session Exit order:
+
+```bash
+npx agent-orchestrator-kit handoff <name> --runtime cloud
+git add openspec/changes/<name>/
+git commit
+git push
+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:
+
+```yaml
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    # ... remaining kit skills
+  stack: []                 # vue3: vue-core, vue-pinia, vue-axios, vue-router
+  external: ""              # vue3/node: frontend-agent-skills
+```
+
+`npx agent-orchestrator-kit status` prints **Skill health** after MCP health (`ok` / `missing` / `stale`) for kit + stack skills and Amp `subagent-*` wrappers. The section is warn-only: missing or stale skills never change the exit code. Repair with the existing commands — `sync` (stale IDE copies), `update` (missing kit files), or a manual stack install:
+
+```bash
+npx frontend-agent-skills install --agent all --yes
+```
+
+The CLI never auto-installs external skill packages. `.agents/orchestrator.yaml` is outside kit-managed paths, so `update` does **not** refresh `skills.kit` — after a kit skill is added or removed, edit that list by hand (or re-init with `--force`).
+
 ## Amp Code — Deep Integration Notes
 
 Amp is the **primary target** of this kit. It reads `.agents/skills/` and `AGENTS.md` without any sync step — your team commits `.agents/` and everyone gets the same orchestration behavior automatically.
@@ -739,6 +881,7 @@ npx agent-orchestrator-kit init [options]
   --name <name>      Project name (default: directory name)
   --ci <provider>    CI provider: gitlab | github | none (default: github)
   --spec-verify      Install AI Spec Verifier blocking gate (GitLab or GitHub)
+  --hooks            Opt-in: install pre-commit gate-check hook (husky-first)
   --force            Overwrite existing files
 
 npx agent-orchestrator-kit update
@@ -750,20 +893,46 @@ npx agent-orchestrator-kit sync [options]
   present in .agents/ (does not touch memory.json, .mcp.json, CLAUDE.md, etc.)
 
 npx agent-orchestrator-kit status
-  Show progress, review verdict, and archive-readiness for active changes
+  Show progress, review verdict, archive-readiness, MCP health, and Skill health
+  (warn-only; missing/stale skills do not fail the command)
 
 npx agent-orchestrator-kit gate-check [change-name] [options]
   --src-glob <glob>  Source path filter used to detect code changes (default: src/)
   --base <ref>       Git ref to diff against (default: HEAD~1)
+  --staged           Check staged files (git diff --cached) instead of --base
   --tasks <name>     Lint task contracts (Files / Do / Done-when)
   --review <name>    Deterministic Tier 1 review (optional --json)
   Exit non-zero when require_spec_review is true, src/ changed, and the
   active change has no review.md with Verdict: APPROVE. Graceful no-op
   otherwise (missing config, review not required, no relevant diff).
 
+npx agent-orchestrator-kit hooks-setup
+  Opt-in pre-commit gate (husky-first, else core.hooksPath=.githooks)
+
+npx agent-orchestrator-kit mcp-setup [--vcs github|gitlab] [--no-browser]
+  Install GitHub/GitLab (from origin) and browser MCP launchers
+
 npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
   Gate-check a completed change, optionally merge delta specs, move to
   openspec/changes/archive/YYYY-MM-DD-<name>, validate, write final handoff
+
+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
@@ -796,11 +965,30 @@ 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
+
+The kit moves toward an Agentic Factory in four phases. **One phase = one OpenSpec change**; the next phase does not start until the previous change is archived.
+1. `add-factory-gates-and-mcp` — local review gate on commit and Figma-style MCP launchers (GitHub / GitLab / browser). Implemented: `hooks-setup`, `mcp-setup`, `gate-check --staged`, MCP health in `status`.
+2. `add-factory-memory-and-skills` — git-canonical decisions with Memory MCP as a mirror, plus a machine skill inventory. Implemented: append-only `decisions.md`, Skill health in `status`.
+3. `add-cloud-agent-handoff` — session artifacts exist only on git-tracked paths. Implemented: `## Runtime` in `handoff.md`, `--runtime` / `--agent-id` / `--cloud-check`, cloud Session Exit.
+4. Phase 4 (`add-factory-control-plane`) is an opt-in platform decision, not the next sprint.
+Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](openspec/specs/agentic-factory-roadmap/spec.md).
+
 ## 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
+- Cloud agent handoff: `## Runtime` in `handoff.md`, `--runtime` / `--agent-id` / `--cloud-check`
+
 ### 0.3.0
 - **`archive` CLI** — deterministic archive with gates, `--sync` delta merge, and rollback on validate failure
 - **Task contract** — `gate-check --tasks` enforces `Files:` / `Do:` / `Done-when:` (`pipeline.task_contract: warn|strict|off`)