agent-orchestrator-kit 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [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
+- **`npx agent-orchestrator-kit archive <name>`** — deterministic archive CLI: gates (APPROVE, all tasks `[x]`, free target), delta-spec merge into main specs with `--sync` (ADDED append / MODIFIED replace / REMOVED delete), explicit refusal without a sync decision (`--sync` or `--no-sync --force`), snapshot + full rollback when `openspec validate --all --strict` fails, final `handoff.md` (`next_command: none`) + memory upsert
+- **Task contract lint** — `gate-check --tasks <name>` enforces `Files:` / `Do:` / `Done-when:` per task, rejects vague phrasing and nonexistent `Files:` paths without `new file:`; controlled by `pipeline.task_contract: warn|strict|off` (default `warn`, mvp `off`)
+- **Tiered review** — `gate-check --review <name> [--json]` is deterministic Tier 1 (strict validation, task-contract lint, proposal `Non-goals`/`Acceptance criteria`, non-empty delta sections); `spec-reviewer` runs only after Tier 1 passes and writes `apply-notes.md` (≤ 20 lines) on APPROVE
+
+### Changed
+- **Lean delegation model** — apply is parent-driven (implementer reads `tasks.md` + `apply-notes.md`, spawns subagents only for ≥ 2 independent tasks or on request, STOP escape valve instead of improvisation); archive is CLI-only with `spec-archiver` demoted to fallback; propose/review specialists remain mandatory
+- **Parent-driven session handoff** — canonical Session Start/Exit protocol consolidated in `.agents/rules/session-handoff.mdc`; `/opsx:*` commands reference it instead of duplicating it; `session-handoff` subagent and Memory MCP mirror are fallbacks (`handoff.spawn_handoff_subagent: false` in all profiles); `opsx-archive.md` slimmed to a ≤ 1.5 KB CLI wrapper
+
+## [0.2.0] - 2026-08-18
+
 ### Changed
 - **Context budget** — thinned always-apply rules and `AGENTS.md` / `CLAUDE.md`; details stay in on-demand skills. `figma-token-setup.mdc` is no longer `alwaysApply`. Restore spawn of `session-handoff` is skipped when `handoff --restore` already printed a briefing.
 
@@ -168,8 +193,18 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[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
+[0.1.13]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.12...v0.1.13
+[0.1.12]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.11...v0.1.12
+[0.1.11]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.10...v0.1.11
+[0.1.10]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.9...v0.1.10
+[0.1.9]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.6...v0.1.7
+[0.1.6]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.2...v0.1.3

package/README.md

@@ -34,17 +34,18 @@ Each role runs in a **separate agent session**. The parent `/opsx:*` session is
 | `spec-archiver` | Delta merge and completed-change archive |
 | `session-handoff` | Restore/persist Memory + `handoff.md` + expanded next-thread prompt |
 
-The conductor uses one exclusive route per signal:
+Delegation is **differentiated per phase** (lean model): thinking-heavy phases spawn a mandatory specialist, apply is parent-driven, archive is a deterministic CLI:
 
-| Phase / signal | Subagent |
-|----------------|----------|
+| Phase / signal | Delegation |
+|----------------|------------|
 | Status / gates / next command | `openspec-guide` |
-| Session start restore / session exit persist | `session-handoff` |
+| Session start restore / session exit persist | parent-driven CLI (`handoff --restore` / `handoff <name>`); `session-handoff` is a fallback only |
 | Kit / MCP / sync repair | `setup-doctor` |
-| Explore repository research | `codebase-explorer` |
-| Design / propose / spec review | `design-intake` / `spec-architect` / `spec-reviewer` |
-| Apply UI / ordinary task / tests / pre-PR review | `design-implementer` / `code-writer` / `test-writer` / `code-reviewer` |
-| Archive | `spec-archiver` |
+| Explore repository research | `codebase-explorer` (mandatory) |
+| Design / propose / spec review | `design-intake` / `spec-architect` / `spec-reviewer` (mandatory) |
+| Apply | parent implements from `tasks.md` + `apply-notes.md`; `code-writer` / `test-writer` optional for ≥ 2 independent tasks or explicit request; `design-implementer` for design-brief/Figma tasks |
+| Pre-PR code review | `code-reviewer` |
+| Archive | `npx agent-orchestrator-kit archive <name>` (CLI — no subagent; `spec-archiver` is a fallback when the CLI is unavailable) |
 
 - **Cursor** → `.cursor/agents/` (native subagents)
 - **Claude Code** → `.claude/agents/` (native subagents)
@@ -73,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 (hardened handoff CLI + Memory launcher in v0.1.14+, conductor in v0.1.13+, Figma PAT in v0.1.11+):**
+**🔄 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+):**
 
 ```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
 ```
 
@@ -188,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` / `handoff` / `memory-setup` — deterministic review-gate and session-handoff (always via `npx`; see `cli-via-npm.mdc`) |
+| 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`) |
 | 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 |
@@ -351,13 +354,13 @@ npx openspec validate <name> --strict --type change  # must be ✓
 **Model:** medium or strong.
 **Purpose:** Review artifacts. Output **Approve ✓** or **Request Changes ✗**.
 
-The conductor spawns `spec-reviewer` (not `code-reviewer`) and verifies its `review.md`.
+Review is **two-tiered**. Tier 1 is deterministic: `npx agent-orchestrator-kit gate-check --review <name>` runs strict OpenSpec validation, the task-contract lint, and structural checks (Non-goals / Acceptance criteria in `proposal.md`, non-empty delta-spec sections). If Tier 1 fails, the verdict is REQUEST CHANGES without spawning anyone. Only on a Tier 1 pass does the conductor spawn `spec-reviewer` (not `code-reviewer`) for Tier 2 judgment and verify its `review.md`. On APPROVE the reviewer also writes `apply-notes.md` (≤ 20 lines of constraints and pitfalls for the implementer).
 
-Checks:
-- Acceptance criteria are testable
-- Tasks ≤ ~2 hours each
+Tier 2 checks (judgment only — no duplication of Tier 1):
+- Consistency proposal ↔ design ↔ tasks
 - No scope creep vs Non-goals
 - No conflicts with existing domain specs
+- Tasks self-sufficient for a blind implementer (Files / Do / Done-when)
 
 ```
 /opsx:review add-bulk-camera-export
@@ -467,13 +470,79 @@ 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>
+```
+
+Lints the task contract in `tasks.md`: every task needs `Files:` / `Do:` / `Done-when:`, no vague phrasing (`as needed`, `if necessary`, …), and every `Files:` path must exist unless prefixed `new file:`. Behavior follows `pipeline.task_contract` in `orchestrator.yaml`: `warn` (default) exits 0 with warnings, `strict` exits 1 on violations, `off` skips the lint.
+
+```bash
+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.
 
 ---
 
@@ -525,7 +594,13 @@ After PR merged + CI green:
 /opsx:archive add-bulk-camera-export
 ```
 
-Merges delta specs into `openspec/specs/` and moves change to `archive/`.
+Archive is a **deterministic CLI**, not an agent workflow:
+
+```bash
+npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
+```
+
+It checks the gates (APPROVE in `review.md` when required, all tasks `[x]`, target folder free), merges delta specs into `openspec/specs/` (`--sync`: ADDED append, MODIFIED replace, REMOVED delete), moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>`, and runs `npx openspec validate --all --strict` with a full rollback on failure (main specs restored, new spec files deleted, move reverted). With delta specs present you must decide: `--sync` merges, `--no-sync --force` archives without merging, and no flag refuses with exit 1. It finishes by writing the final `handoff.md` (`next_command: none`) and updating memory. The `/opsx:archive` command is a thin wrapper that calls this CLI; the `spec-archiver` subagent remains only as a fallback when the CLI is unavailable.
 
 ## Configuration
 
@@ -674,7 +749,75 @@ Handoff:add-bulk-export    next_role: implementer, next_command: /opsx:apply add
                            session_count: 2, summary: ..., blocked: none
 ```
 
-Every `/opsx:*` session restores via `npx agent-orchestrator-kit handoff --restore`, then Memory `Change:<name>`, `Handoff:<name>`, `Decision:*`, falling back to `handoff.md` if Memory is unavailable. At exit it MUST spawn `session-handoff`, write `handoff.md`, run `npx agent-orchestrator-kit handoff <name>` (upserts `.cursor/memory.json` with an absolute path), and paste the CLI stdout prompt. 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.
+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.
+
+### 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
 
@@ -720,6 +863,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
@@ -731,14 +875,35 @@ 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
+  --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)
 ```
 
 ## Directory Reference
@@ -774,8 +939,31 @@ openspec/                # Committed — spec-driven workflow
   changes/               # Active work; <name>/handoff.md indexes 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.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`)
+- **Tiered review** — `gate-check --review` is machine Tier 1; `spec-reviewer` writes `apply-notes.md` on APPROVE
+- Lean apply (parent-driven) and parent-driven session handoff; `opsx-archive.md` is a thin CLI wrapper
+
+### 0.2.0
+- Thinned always-apply rules and `AGENTS.md` / `CLAUDE.md` (context budget); details stay in on-demand skills
+
 ### 0.1.14
 - **HARD STOP session handoff** — `session-handoff` subagent at start/exit; Amp isolated `subagent-session-handoff`
 - **`handoff` CLI** — writes `handoff.md`, upserts `.cursor/memory.json` with an absolute path, prints an expanded self-contained next-thread prompt