agent-orchestrator-kit 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.8] - 2026-07-07
+
+### Changed
+- **README** — Quickstart block (new vs existing project) and upgrade guide for `status` / `gate-check` / GitHub Spec Verifier adoption
+
+## [0.1.7] - 2026-07-07
+
+### Added
+- **`agent-orchestrator status`** — dashboard for active OpenSpec changes: task progress (`N/M`), review verdict, `ready to archive` flag
+- **`agent-orchestrator gate-check`** — deterministic review-gate check; exits non-zero when `src/` changed without an approved `review.md` (`require_spec_review: true`); warns (non-blocking) when active changes exceed `max_active_changes`; graceful no-op without `.agents/orchestrator.yaml`, when review isn't required, or when the diff can't be computed
+- **GitHub AI Spec Verifier** — `init --ci github --spec-verify` installs `.github/workflows/spec-verify.yml` + `scripts/post-pr-verdict-github.sh` (via `gh pr comment`), reusing the existing stack-agnostic `scripts/verify-specs.sh`
+- **OpenSpec specs** — `orchestrator-cli-controls`, `github-spec-verify`
+
+### Changed
+- **`sync`** (CLI) now removes stale skills/rules no longer present in `.agents/skills|rules` — matches `sync-local-agent-skills.sh` (`rsync --delete`); does not touch `memory.json`, `.mcp.json`, `CLAUDE.md`, `settings.json`
+- **`agent-verify.yml`** (both GitHub and GitLab fragments) now run `gate-check` as part of verify
+- **`--spec-verify`** — no longer GitLab-only; valid with `--ci gitlab` or `--ci github`
+- **README / AGENTS.md / agent-orchestration skill** — document `status`, `gate-check`, and GitHub Spec Verifier parity
+
 ## [0.1.6] - 2026-07-02
 
 ### Added
@@ -75,6 +94,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.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.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

@@ -26,6 +26,28 @@ Without role separation, AI agents tend to mix thinking with implementation, ski
 
 The `AGENTS.md` / `CLAUDE.md` files tell each IDE exactly what the roles are, so you don't repeat yourself every session.
 
+## Quickstart
+
+**🆕 New project:**
+
+```bash
+npm i -D @fission-ai/openspec && npx openspec init
+npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-verify
+./scripts/sync-local-agent-skills.sh
+```
+
+See [Installation](#installation) for profile/CI options.
+
+**🔄 Already have the kit installed? Get `status` / `gate-check` / GitHub Spec Verifier (v0.1.7+):**
+
+```bash
+npx agent-orchestrator-kit@latest update
+./scripts/sync-local-agent-skills.sh
+npx agent-orchestrator-kit@latest status       # try it right away
+```
+
+See [Upgrading an existing project](#upgrading-an-existing-project-to-v017-status--gate-check--github-spec-verifier) for what changes and what stays opt-in.
+
 ## Installation
 
 ### Prerequisites
@@ -99,8 +121,9 @@ your-project/
 ├── AGENTS.md
 ├── CLAUDE.md
 ├── .github/workflows/agent-verify.yml   # CI (default --ci github)
+├── .github/workflows/spec-verify.yml    # AI Spec Verifier (--ci github --spec-verify, opt-in)
 ├── .gitlab/agent-verify.yml             # CI fragment (--ci gitlab)
-├── .gitlab/spec-verify.yml              # AI Spec Verifier (--spec-verify, opt-in)
+├── .gitlab/spec-verify.yml              # AI Spec Verifier (--ci gitlab --spec-verify, opt-in)
 ├── .agents/
 │   ├── orchestrator.yaml
 │   ├── mcp.json.example                 # Cursor MCP template
@@ -117,7 +140,7 @@ your-project/
 │       ├── openspec-sync-specs/
 │       └── spec-workflow-openspec/
 ├── scripts/sync-local-agent-skills.sh
-└── scripts/verify-specs.sh + post-mr-verdict.sh   # (--spec-verify, opt-in)
+└── scripts/verify-specs.sh + post-mr-verdict.sh / post-pr-verdict-github.sh   # (--spec-verify, opt-in)
 ```
 
 ### Included in kit
@@ -126,9 +149,10 @@ your-project/
 |----------|----------|
 | Orchestration | 5-role pipeline, `AGENTS.md`, `orchestrator.yaml`, review command |
 | OpenSpec skills | All 7 skills for `/opsx:*` workflow |
-| IDE sync | Cursor + Claude Code sync script |
-| CI | `agent-verify.yml` — GitHub (default) or GitLab fragment + `prebuild` hook |
-| AI Spec Verifier | `spec-verify.yml` + verifier scripts — GitLab opt-in (`--spec-verify`) |
+| IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills) |
+| CLI gates | `agent-orchestrator status` / `gate-check` — deterministic review-gate checks |
+| 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 |
 
 ### Not included (install separately)
@@ -329,15 +353,18 @@ Optional: include `.gitlab/agent-verify.yml` in `.gitlab-ci.yml` for full lint/b
 
 Blocks merge if any gate fails.
 
-#### AI Spec Verifier (GitLab, opt-in)
+Every CI fragment (`agent-verify.yml`, GitHub and GitLab) also runs `npx agent-orchestrator-kit gate-check` — see [Deterministic gates](#deterministic-gates-status--gate-check) below. It never fails the pipeline for projects without `.agents/orchestrator.yaml`.
+
+#### AI Spec Verifier (GitLab or GitHub, opt-in)
 
 ```bash
 npx agent-orchestrator-kit init --ci gitlab --spec-verify
+npx agent-orchestrator-kit init --ci github --spec-verify
 ```
 
-Installs an AI verification layer on top of the deterministic gates: on every merge request that changes `src/`, an Amp agent reads `openspec/specs/`, checks the changed code against every relevant requirement, posts a **PASS / BLOCKED** comment to the MR, and **fails the pipeline on BLOCKED** — specs become an enforceable merge contract, not just documentation.
+Installs an AI verification layer on top of the deterministic gates: on every merge/pull request that changes `src/`, an Amp agent reads `openspec/specs/`, checks the changed code against every relevant requirement, posts a **PASS / BLOCKED** comment to the MR/PR, and **fails the pipeline on BLOCKED** — specs become an enforceable merge contract, not just documentation.
 
-Installed files:
+Installed files (GitLab):
 
 | File | Purpose |
 |------|---------|
@@ -345,9 +372,17 @@ Installed files:
 | `scripts/verify-specs.sh` | Collects changed files + specs, builds prompt (project context from `openspec/config.yaml`), calls `amp -x`, writes `artifacts/verdict.json` |
 | `scripts/post-mr-verdict.sh` | Posts the verdict as an MR comment via GitLab API |
 
+Installed files (GitHub):
+
+| File | Purpose |
+|------|---------|
+| `.github/workflows/spec-verify.yml` | Workflow triggered on `pull_request` for `src/**` — same verdict evaluation, `permissions: pull-requests: write` |
+| `scripts/verify-specs.sh` | Same script as GitLab — stack-agnostic, reused as-is |
+| `scripts/post-pr-verdict-github.sh` | Posts the verdict as a PR comment via `gh pr comment` |
+
 The flag also adds `spec-verify-blocking` to `roles.verifier.gates` in `.agents/orchestrator.yaml`.
 
-Setup after install:
+Setup after install (GitLab):
 
 1. Include the fragment from `.gitlab-ci.yml`:
 
@@ -358,11 +393,31 @@ include:
 
 2. Add CI/CD variables (Settings → CI/CD → Variables, masked): `AMP_API_KEY`, `GITLAB_VERIFIER_TOKEN` (project access token with `api` scope).
 
+Setup after install (GitHub): the workflow runs automatically on `pull_request` — just add the repo secret `AMP_API_KEY` (Settings → Secrets and variables → Actions). `GITHUB_TOKEN` is provided by Actions automatically.
+
 Verdict schema (`artifacts/verdict.json`): `pass`, `score` (0–100), `summary`, `findings[]` with `severity` (`error` fails the job), `spec`, `requirement`, `message`, `file`. The script degrades gracefully — no `src/` changes, no specs, missing `amp` CLI, or missing `AMP_API_KEY` produce a skipped passing verdict and never block the pipeline. Secrets are never logged; `.env`/key/token files are excluded from prompts.
 
-**Warning-only rollout (Phase 1):** uncomment `allow_failure: true` in `.gitlab/spec-verify.yml` to keep the pipeline green while the team builds trust in verdicts, then remove it to enforce blocking (Phase 2).
+**Warning-only rollout (Phase 1):** uncomment `allow_failure: true` (GitLab) or `continue-on-error: true` (GitHub) to keep the pipeline green while the team builds trust in verdicts, then remove it to enforce blocking (Phase 2).
 
-`update` refreshes the three spec-verify files only in projects that already installed them — the feature stays opt-in.
+`update` refreshes the spec-verify files only in projects that already installed them — the feature stays opt-in.
+
+---
+
+### Deterministic gates: `status` / `gate-check`
+
+Orchestration hard rules (review approval, one active change) used to rely entirely on the agent remembering to check them in chat. Two CLI commands make them checkable and CI-enforceable:
+
+```bash
+npx agent-orchestrator-kit status
+```
+
+Prints every active OpenSpec change with task progress (`N/M tasks`), review verdict (`APPROVE` / `REQUEST CHANGES` / `none`), and a `ready to archive` flag once all tasks are `[x]` — no more running `openspec status` per change by hand.
+
+```bash
+npx agent-orchestrator-kit gate-check [change-name] [--src-glob src/] [--base HEAD~1]
+```
+
+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`. It degrades gracefully to exit 0 (with a message, not silently) when: `.agents/orchestrator.yaml` is missing, review isn't 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.
 
 ---
 
@@ -411,6 +466,31 @@ npx agent-orchestrator-kit update
 - `openspec/changes/`
 - Any project-conventions skills
 
+### Upgrading an existing project to v0.1.7 (status / gate-check / GitHub Spec Verifier)
+
+If the kit is already installed and you just want the new deterministic gates, no re-`init` needed:
+
+```bash
+npx agent-orchestrator-kit@latest update
+./scripts/sync-local-agent-skills.sh
+```
+
+What this gets you automatically:
+- `.github/workflows/agent-verify.yml` / `.gitlab/agent-verify.yml` refreshed with a `gate-check` step (fails CI if `src/` changed without an approved `review.md`)
+- `sync` (both the CLI command and the shell script) starts removing skills that no longer exist in `.agents/skills/`
+- `agent-orchestrator status` and `agent-orchestrator gate-check` are available immediately (they ship inside `bin/`, not as opt-in templates) — try `npx agent-orchestrator-kit@latest status` right away
+
+Two things `update` will **not** do for you (by design — opt-in, and it never touches your CI root file):
+
+1. **GitLab-only projects that already had `--spec-verify`** — `update` refreshes `.gitlab/spec-verify.yml` and the scripts automatically (only because they already exist in your project).
+2. **Adding GitHub Spec Verifier where you didn't have it before** — that's a new opt-in, run it once:
+   ```bash
+   npx agent-orchestrator-kit@latest init --ci github --spec-verify
+   ```
+   then add the `AMP_API_KEY` repo secret (Settings → Secrets and variables → Actions).
+
+Nothing about `update` retroactively edits your `.gitlab-ci.yml` / already-included workflows — if `gate-check` doesn't seem to run, check that your `.gitlab-ci.yml` still `include`s `.gitlab/agent-verify.yml` (GitHub Actions picks up `.github/workflows/*.yml` automatically, no include step needed).
+
 ## Profiles
 
 | Profile | Stack | Extra (separate install) |
@@ -498,15 +578,26 @@ npx agent-orchestrator-kit init [options]
   --lang <code>      Agent language: en | uk | ...
   --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 only)
+  --spec-verify      Install AI Spec Verifier blocking gate (GitLab or GitHub)
   --force            Overwrite existing files
 
 npx agent-orchestrator-kit update
   Updates kit-managed files, preserves project overlay
 
 npx agent-orchestrator-kit sync [options]
-  --target <ide>     cursor | claude | all (default: all)
-  Copies .agents/ to local IDE directories
+  --target <ide>     cursor | claude | amp | all (default: all)
+  Copies .agents/ to local IDE directories, removing skills/rules no longer
+  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
+
+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)
+  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).
 ```
 
 ## Directory Reference
@@ -540,6 +631,15 @@ openspec/                # Committed — spec-driven workflow
 
 ## Changelog
 
+### 0.1.8
+- README — Quickstart (new vs existing project) and upgrade guide for adopting `status`, `gate-check`, and GitHub Spec Verifier
+
+### 0.1.7
+- `agent-orchestrator status` — dashboard for active OpenSpec changes: task progress, review verdict, archive readiness
+- `agent-orchestrator gate-check` — deterministic review-gate check (exit non-zero without an approved `review.md`); wired into both `agent-verify.yml` CI fragments
+- `init --ci github --spec-verify` — GitHub parity for the AI Spec Verifier (`.github/workflows/spec-verify.yml`, `scripts/post-pr-verdict-github.sh`), reusing the existing stack-agnostic `verify-specs.sh`
+- `sync` (CLI) now removes skills/rules that no longer exist in `.agents/` — matches `sync-local-agent-skills.sh` (`rsync --delete`) behavior; leaves `memory.json`, `.mcp.json`, `CLAUDE.md`, `settings.json` untouched
+
 ### 0.1.6
 - `init --ci gitlab --spec-verify` — opt-in AI Spec Verifier: blocking MR gate via Amp CLI
 - Templates: `.gitlab/spec-verify.yml`, `scripts/verify-specs.sh`, `scripts/post-mr-verdict.sh`

package/bin/agent-orchestrator.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program } from 'commander';
 import pc from 'picocolors';
-import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync } from 'fs';
 import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -32,12 +32,25 @@ const KIT_MANAGED_PATHS = [
   'scripts/sync-local-agent-skills.sh',
 ];
 
-// Opt-in files: refreshed by `update` only when already present in the project
-const KIT_OPTIN_PATHS = [
+// Opt-in AI Spec Verifier files, per CI provider. `scripts/verify-specs.sh` is
+// shared — it is stack- and CI-agnostic already.
+const GITLAB_SPEC_VERIFY_PATHS = [
   '.gitlab/spec-verify.yml',
   'scripts/verify-specs.sh',
   'scripts/post-mr-verdict.sh',
 ];
+const GITHUB_SPEC_VERIFY_PATHS = [
+  '.github/workflows/spec-verify.yml',
+  'scripts/verify-specs.sh',
+  'scripts/post-pr-verdict-github.sh',
+];
+
+// Opt-in files: refreshed by `update` only when already present in the project
+const KIT_OPTIN_PATHS = [...new Set([...GITLAB_SPEC_VERIFY_PATHS, ...GITHUB_SPEC_VERIFY_PATHS])];
+
+function specVerifyPathsFor(ci) {
+  return ci === 'github' ? GITHUB_SPEC_VERIFY_PATHS : GITLAB_SPEC_VERIFY_PATHS;
+}
 
 const VALID_CI_PROVIDERS = ['gitlab', 'github', 'none'];
 const VERIFY_OPENSPEC_SCRIPT = 'npx openspec validate --all --strict';
@@ -53,10 +66,11 @@ const log = {
 };
 
 function copyDir(src, dest, opts = {}) {
-  const { overwrite = true, skip = [] } = opts;
+  const { overwrite = true, skip = [], delete: deleteStale = false } = opts;
   if (!existsSync(src)) return;
   mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
+  const srcEntries = readdirSync(src);
+  for (const entry of srcEntries) {
     if (skip.includes(entry)) continue;
     const srcPath = join(src, entry);
     const destPath = join(dest, entry);
@@ -71,6 +85,17 @@ function copyDir(src, dest, opts = {}) {
       log.ok(destPath.replace(process.cwd() + '/', ''));
     }
   }
+
+  // Remove entries that exist in dest but no longer exist in src (e.g. skills
+  // removed by a kit `update`), keeping .cursor/.claude in sync with .agents/.
+  if (deleteStale && existsSync(dest)) {
+    for (const entry of readdirSync(dest)) {
+      if (skip.includes(entry) || srcEntries.includes(entry)) continue;
+      const destPath = join(dest, entry);
+      rmSync(destPath, { recursive: true, force: true });
+      log.warn(`removed stale: ${destPath.replace(process.cwd() + '/', '')}`);
+    }
+  }
 }
 
 function gitignoreLines(content) {
@@ -128,6 +153,59 @@ function hasOpenSpec(projectDir) {
   return existsSync(join(projectDir, 'openspec', 'config.yaml'));
 }
 
+function listActiveChanges(projectDir) {
+  const changesDir = join(projectDir, 'openspec', 'changes');
+  if (!existsSync(changesDir)) return [];
+  return readdirSync(changesDir)
+    .filter((name) => name !== 'archive' && statSync(join(changesDir, name)).isDirectory())
+    .sort();
+}
+
+function parseTasksProgress(changeDir) {
+  const tasksPath = join(changeDir, 'tasks.md');
+  if (!existsSync(tasksPath)) return null;
+  const content = readFileSync(tasksPath, 'utf-8');
+  const total = (content.match(/^\s*- \[[ xX]\]/gm) || []).length;
+  const done = (content.match(/^\s*- \[[xX]\]/gm) || []).length;
+  return { total, done };
+}
+
+function parseReviewVerdict(changeDir) {
+  const reviewPath = join(changeDir, 'review.md');
+  if (!existsSync(reviewPath)) return null;
+  const content = readFileSync(reviewPath, 'utf-8');
+  const match = content.match(/\*\*Verdict:\*\*\s*(.+)/);
+  return match ? match[1].trim() : 'unknown';
+}
+
+function readPipelineConfig(projectDir) {
+  const orchPath = join(projectDir, '.agents', 'orchestrator.yaml');
+  if (!existsSync(orchPath)) return null;
+  const content = readFileSync(orchPath, 'utf-8');
+  const requireReviewMatch = content.match(/require_spec_review:\s*(true|false)/);
+  const maxActiveMatch = content.match(/max_active_changes:\s*(\d+)/);
+  return {
+    requireSpecReview: requireReviewMatch ? requireReviewMatch[1] === 'true' : true,
+    maxActiveChanges: maxActiveMatch ? parseInt(maxActiveMatch[1], 10) : null,
+  };
+}
+
+// Returns true/false when the diff is known, or null when it could not be
+// determined (no git repo, invalid base ref, shallow clone, etc.) — callers
+// must treat null as "skip gracefully", never as "block".
+function gitDiffTouchesGlob(projectDir, base, srcGlob) {
+  try {
+    const out = execSync(`git diff --name-only ${base}...HEAD -- "${srcGlob}"`, {
+      cwd: projectDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf-8',
+    });
+    return out.trim().length > 0;
+  } catch {
+    return null;
+  }
+}
+
 function installOpenspecConfigExample(projectDir, profile, vars, force) {
   const src = resolveTemplate('openspec-config.yaml.example', profile);
   if (!existsSync(src)) return;
@@ -230,8 +308,9 @@ function installCi(projectDir, templateDir, ci, force) {
   }
 }
 
-function installSpecVerify(projectDir, templateDir, force) {
-  for (const rel of KIT_OPTIN_PATHS) {
+function installSpecVerify(projectDir, templateDir, force, ci) {
+  const paths = specVerifyPathsFor(ci);
+  for (const rel of paths) {
     const src = join(templateDir, rel);
     const dest = join(projectDir, rel);
     if (!existsSync(src)) continue;
@@ -243,8 +322,9 @@ function installSpecVerify(projectDir, templateDir, force) {
     copyFileSync(src, dest);
     log.ok(rel);
   }
+  const scripts = paths.filter((rel) => rel.startsWith('scripts/')).map((rel) => join(projectDir, rel));
   try {
-    execSync(`chmod +x ${join(projectDir, 'scripts', 'verify-specs.sh')} ${join(projectDir, 'scripts', 'post-mr-verdict.sh')}`);
+    execSync(`chmod +x ${scripts.join(' ')}`);
   } catch {}
 }
 
@@ -332,9 +412,15 @@ function printNextSteps(profile, projectDir, ci = 'github', specVerify = false)
 
   if (specVerify) {
     lines.push(`  ${pc.bold('AI Spec Verifier:')}`);
-    lines.push(`    - include ${pc.cyan(".gitlab/spec-verify.yml")} from your .gitlab-ci.yml`);
-    lines.push(`    - add CI/CD variables: ${pc.cyan('AMP_API_KEY')}, ${pc.cyan('GITLAB_VERIFIER_TOKEN')} (masked)`);
-    lines.push(`    - BLOCKED verdict fails the MR pipeline (uncomment allow_failure for warning-only rollout)`);
+    if (ci === 'gitlab') {
+      lines.push(`    - include ${pc.cyan(".gitlab/spec-verify.yml")} from your .gitlab-ci.yml`);
+      lines.push(`    - add CI/CD variables: ${pc.cyan('AMP_API_KEY')}, ${pc.cyan('GITLAB_VERIFIER_TOKEN')} (masked)`);
+      lines.push(`    - BLOCKED verdict fails the MR pipeline (uncomment allow_failure for warning-only rollout)`);
+    } else if (ci === 'github') {
+      lines.push(`    - workflow ${pc.cyan('.github/workflows/spec-verify.yml')} runs automatically on pull_request`);
+      lines.push(`    - add repo secret: ${pc.cyan('AMP_API_KEY')} (Settings → Secrets and variables → Actions)`);
+      lines.push(`    - BLOCKED verdict fails the PR pipeline (remove continue-on-error for warning-only rollout)`);
+    }
   }
 
   console.log('\n' + lines.join('\n') + '\n');
@@ -368,7 +454,7 @@ program
   .option('--name <name>', 'Project name (defaults to directory name)')
   .option('--force', 'Overwrite existing files', false)
   .option('--ci <provider>', 'CI provider: gitlab | github | none', 'github')
-  .option('--spec-verify', 'Install AI Spec Verifier blocking gate (GitLab only)', false)
+  .option('--spec-verify', 'Install AI Spec Verifier blocking gate (GitLab or GitHub)', false)
   .action((opts) => {
     const projectDir = process.cwd();
     const projectName = opts.name || basename(projectDir);
@@ -408,13 +494,13 @@ program
       injectVerifyScripts(projectDir, { pm });
     }
 
-    const specVerify = Boolean(opts.specVerify) && ci === 'gitlab';
-    if (opts.specVerify && ci !== 'gitlab') {
-      log.warn('--spec-verify requires --ci gitlab — skipping AI Spec Verifier install');
+    const specVerify = Boolean(opts.specVerify) && (ci === 'gitlab' || ci === 'github');
+    if (opts.specVerify && !specVerify) {
+      log.warn('--spec-verify requires --ci gitlab or --ci github — skipping AI Spec Verifier install');
     }
     if (specVerify) {
       log.title('Installing AI Spec Verifier (opt-in)');
-      installSpecVerify(projectDir, templateDir, opts.force);
+      installSpecVerify(projectDir, templateDir, opts.force, ci);
     }
 
     log.title('Installing root files');
@@ -506,8 +592,8 @@ program
 
     if (syncCursor) {
       log.info('Syncing .agents/ → .cursor/');
-      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.cursor', 'skills'), { overwrite: true });
-      copyDir(join(projectDir, '.agents', 'rules'), join(projectDir, '.cursor', 'rules'), { overwrite: true });
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.cursor', 'skills'), { overwrite: true, delete: true });
+      copyDir(join(projectDir, '.agents', 'rules'), join(projectDir, '.cursor', 'rules'), { overwrite: true, delete: true });
 
       const mcpExample = join(projectDir, '.agents', 'mcp.json.example');
       const mcpDest = join(projectDir, '.mcp.json');
@@ -519,7 +605,7 @@ program
 
     if (syncClaude) {
       log.info('Syncing .agents/ → .claude/');
-      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.claude', 'skills'), { overwrite: true });
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.claude', 'skills'), { overwrite: true, delete: true });
 
       const claudeMd = join(projectDir, 'CLAUDE.md');
       const claudeDir = join(projectDir, '.claude');
@@ -540,4 +626,98 @@ program
     log.warn('.cursor/, .claude/, .amp/ are local only — not committed to git');
   });
 
+program
+  .command('status')
+  .description('Show status of active OpenSpec changes (tasks progress, review verdict, archive readiness)')
+  .action(() => {
+    const projectDir = process.cwd();
+    log.title('agent-orchestrator status');
+
+    const changes = listActiveChanges(projectDir);
+    if (changes.length === 0) {
+      log.info('No active changes');
+      return;
+    }
+
+    for (const name of changes) {
+      const changeDir = join(projectDir, 'openspec', 'changes', name);
+      const progress = parseTasksProgress(changeDir);
+      const verdict = parseReviewVerdict(changeDir);
+      const progressStr = progress ? `${progress.done}/${progress.total} tasks` : 'no tasks.md';
+      const verdictStr = verdict || 'none';
+      const readyToArchive = Boolean(progress && progress.total > 0 && progress.done === progress.total);
+
+      console.log(`\n${pc.bold(name)}`);
+      console.log(`  tasks:  ${progressStr}`);
+      console.log(`  review: ${verdictStr}`);
+      if (readyToArchive) log.ok('ready to archive');
+    }
+    console.log('');
+  });
+
+program
+  .command('gate-check [change-name]')
+  .description('Deterministically check the review gate before apply/merge (exit non-zero if unmet)')
+  .option('--src-glob <glob>', 'source path filter used to detect code changes', 'src/')
+  .option('--base <ref>', 'git ref to diff against', 'HEAD~1')
+  .action((changeName, opts) => {
+    const projectDir = process.cwd();
+    log.title('agent-orchestrator gate-check');
+
+    const config = readPipelineConfig(projectDir);
+    if (!config) {
+      log.info('.agents/orchestrator.yaml not found — nothing to gate');
+      return;
+    }
+
+    if (!config.requireSpecReview) {
+      log.ok('review not required (pipeline.require_spec_review: false)');
+      return;
+    }
+
+    const touchesSrc = gitDiffTouchesGlob(projectDir, opts.base, opts.srcGlob);
+    if (touchesSrc === false) {
+      log.ok(`no changes under ${opts.srcGlob} — nothing to gate`);
+      return;
+    }
+    if (touchesSrc === null) {
+      log.warn('could not compute git diff — skipping gate-check');
+      return;
+    }
+
+    const changes = listActiveChanges(projectDir);
+    if (config.maxActiveChanges && changes.length > config.maxActiveChanges) {
+      log.warn(`${changes.length} active changes exceed pipeline.max_active_changes (${config.maxActiveChanges})`);
+    }
+
+    let target = changeName;
+    if (!target) {
+      if (changes.length === 0) {
+        log.warn(`${opts.srcGlob} changed but no active OpenSpec change found — cannot verify review gate`);
+        return;
+      }
+      target = changes
+        .map((name) => ({ name, mtime: statSync(join(projectDir, 'openspec', 'changes', name)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime)[0].name;
+      log.info(`auto-selected change: ${target} (override: gate-check <name>)`);
+    }
+
+    const changeDir = join(projectDir, 'openspec', 'changes', target);
+    if (!existsSync(changeDir)) {
+      log.err(`change not found: ${target}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const verdict = parseReviewVerdict(changeDir);
+    if (verdict && /^APPROVE/i.test(verdict)) {
+      log.ok(`review gate passed — ${target}: APPROVE`);
+      return;
+    }
+
+    log.err(`review gate failed — change "${target}" has ${verdict ? `verdict "${verdict}"` : 'no review.md'}`);
+    log.err(`Run /opsx:review ${target} and get an explicit APPROVE before apply/merge.`);
+    process.exitCode = 1;
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven pipeline with OpenSpec integration",
   "keywords": [
     "ai-agent",

package/templates/.agents/skills/agent-orchestration/SKILL.md

@@ -74,6 +74,8 @@ Before apply, check `.agents/orchestrator.yaml`:
 
 If Request Changes — fix artifacts, re-run `/opsx:review`.
 
+This is no longer only a chat convention: `agent-orchestrator-kit gate-check` runs in CI (both `agent-verify.yml` fragments) and fails the pipeline if `src/` changed without an approved `review.md` — a forgotten or skipped review is caught at merge time, not just at apply time.
+
 ### apply → verify
 Exit Implementer when:
 - All `tasks.md` boxes `[x]`
@@ -91,7 +93,7 @@ After PR merged + CI green:
 
 **Start of each session:**
 1. Announce role: "Starting Spec Reviewer session for change: <name>"
-2. Check `openspec list` — confirm active change limit (`max_active_changes` in orchestrator.yaml)
+2. Run `agent-orchestrator-kit status` (or `openspec list`) — confirm active change limit (`max_active_changes` in orchestrator.yaml) and see task/review progress for every active change at a glance
 3. Read `orchestrator.yaml` for project config and review gate
 
 **During session:**
@@ -135,7 +137,8 @@ At start of new session: read relevant entities to restore context without re-ex
 - [ ] explicit **Approve** received before apply (when `require_spec_review: true`)
 - [ ] `review.md` with `Verdict: APPROVE` exists (when review required)
 - [ ] all tasks `[x]` + build OK before PR
-- [ ] `/opsx:archive` run after merge
+- [ ] `agent-orchestrator-kit gate-check` passes locally before pushing (mirrors the CI gate)
+- [ ] `/opsx:archive` run after merge — `agent-orchestrator-kit status` shows "ready to archive"
 
 ## Anti-patterns
 

package/templates/.github/workflows/agent-verify.yml

@@ -10,6 +10,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-node@v4
         with:
@@ -45,6 +47,9 @@ jobs:
       - name: OpenSpec validate
         run: npx openspec validate --all --strict
 
+      - name: Gate check (review gate)
+        run: npx agent-orchestrator-kit gate-check --base "${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || 'HEAD~1' }}"
+
       - name: Lint (npm)
         if: steps.pm.outputs.manager == 'npm'
         run: npm run lint --if-present

package/templates/.github/workflows/spec-verify.yml

@@ -0,0 +1,82 @@
+name: spec-verify
+
+# ──────────────────────────────────────────────────────────────
+# AI Spec Verifier — blocking gate on pull requests.
+# Verifies that changed src/ code complies with openspec/specs/
+# via Amp CLI, posts a PASS / BLOCKED comment to the PR, and
+# fails the pipeline on a BLOCKED verdict.
+#
+# Installed by agent-orchestrator-kit (init --ci github --spec-verify).
+#
+# Required repo secret (Settings → Secrets and variables → Actions):
+#   AMP_API_KEY — Amp API key
+# GITHUB_TOKEN is provided automatically by Actions.
+#
+# Phase 1 (warning-only rollout): uncomment `continue-on-error: true` on the
+# "Evaluate verdict" step below, then remove it once the team trusts the
+# verdicts (Phase 2, blocking by default).
+# ──────────────────────────────────────────────────────────────
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  spec-verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install Amp CLI
+        run: npm install -g @sourcegraph/amp@latest
+
+      - name: Make scripts executable
+        run: chmod +x scripts/verify-specs.sh scripts/post-pr-verdict-github.sh
+
+      - name: Run spec verifier
+        env:
+          AMP_API_KEY: ${{ secrets.AMP_API_KEY }}
+          # verify-specs.sh is shared with the GitLab variant and reads this
+          # variable name as the diff base — reused as-is, not GitHub-specific.
+          CI_MERGE_REQUEST_DIFF_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: bash scripts/verify-specs.sh
+
+      - name: Post PR comment
+        if: always()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: bash scripts/post-pr-verdict-github.sh
+
+      - name: Upload verifier artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: spec-verify-artifacts
+          path: |
+            artifacts/verdict.json
+            artifacts/verifier-prompt.md
+          retention-days: 7
+          if-no-files-found: ignore
+
+      - name: Evaluate verdict
+        # Phase 1 (warning-only rollout): uncomment the next line to let the
+        # pipeline stay green while the team builds trust in verdicts.
+        # continue-on-error: true
+        run: |
+          PASS=$(python3 -c "import json; v=json.load(open('artifacts/verdict.json')); print(str(v.get('pass', True)).lower())")
+          if [ "$PASS" != "true" ]; then
+            echo "Spec verifier found errors. See PR comment for details."
+            exit 1
+          fi
+          echo "Spec verification passed."

package/templates/.gitlab/agent-verify.yml

@@ -1,5 +1,7 @@
 .agent-verify-base:
   image: node:20
+  variables:
+    GIT_DEPTH: 0
   before_script:
     - |
       if [ -f pnpm-lock.yaml ]; then
@@ -15,6 +17,7 @@
       fi
   script:
     - npx openspec validate --all --strict
+    - npx agent-orchestrator-kit gate-check --base "${CI_MERGE_REQUEST_DIFF_BASE_SHA:-HEAD~1}"
     - |
       run_pm_script() {
         local name=$1

package/templates/AGENTS.md

@@ -26,7 +26,9 @@ Never mix phases in one chat — this is the single most important rule.
 
 Verifier runs on **GitHub Actions** (default) or **GitLab** via `prebuild` → `verify:openspec` when using `init --ci gitlab`. GitLab projects do not use `.github/workflows/`.
 
-With `init --ci gitlab --spec-verify`, an **AI Spec Verifier** also runs on MRs changing `src/`: an Amp agent checks the changed code against `openspec/specs/` and a **BLOCKED verdict fails the pipeline** (gate `spec-verify-blocking` in `.agents/orchestrator.yaml`).
+With `init --ci gitlab --spec-verify` or `init --ci github --spec-verify`, an **AI Spec Verifier** also runs on MRs/PRs changing `src/`: an Amp agent checks the changed code against `openspec/specs/` and a **BLOCKED verdict fails the pipeline** (gate `spec-verify-blocking` in `.agents/orchestrator.yaml`).
+
+Both CI fragments also run `agent-orchestrator-kit gate-check` — a deterministic check that fails the pipeline when `src/` changed but the active change has no `review.md` with `Verdict: APPROVE` (when `require_spec_review: true`). Run `agent-orchestrator-kit status` at the start of any session to see task progress, review verdict, and archive readiness for every active change without querying `openspec` per change.
 
 ## Hard Rules
 
@@ -42,9 +44,9 @@ With `init --ci gitlab --spec-verify`, an **AI Spec Verifier** also runs on MRs
 |------------|------|
 | explore → propose | Decision brief written; change name chosen |
 | propose → review | `openspec validate --strict` passes ✓ |
-| review → apply | Reviewer writes explicit **Approve** |
+| review → apply | Reviewer writes explicit **Approve** — enforced in CI by `gate-check` |
 | apply → verify | All `tasks.md` checkboxes `[x]`; local build OK |
-| verify → archive | CI green; PR merged |
+| verify → archive | CI green; PR merged — check `agent-orchestrator status` for "ready to archive" |
 
 ## Context to Pin per Role
 

package/templates/scripts/post-pr-verdict-github.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────
+# Posts spec verifier verdict as a GitHub PR comment via gh CLI.
+#
+# Installed by agent-orchestrator-kit (init --ci github --spec-verify).
+#
+# Usage:  ./scripts/post-pr-verdict-github.sh
+# Env:    GH_TOKEN / GITHUB_TOKEN — provided by GitHub Actions
+#         GITHUB_EVENT_PATH, GITHUB_REPOSITORY, GITHUB_RUN_ID — Actions runtime
+#         PR_NUMBER — optional override, auto-detected from the pull_request event otherwise
+#
+# Security: GH_TOKEN/GITHUB_TOKEN is never logged or echoed.
+# ──────────────────────────────────────────────────────────────
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+VERDICT_FILE="$ROOT/artifacts/verdict.json"
+
+if [ ! -f "$VERDICT_FILE" ]; then
+  echo "No verdict file found — skipping PR comment."
+  exit 0
+fi
+
+TOKEN="${GH_TOKEN:-${GITHUB_TOKEN:-}}"
+if [ -z "$TOKEN" ]; then
+  echo "GH_TOKEN/GITHUB_TOKEN not set — skipping PR comment."
+  exit 0
+fi
+
+if ! command -v gh &>/dev/null; then
+  echo "gh CLI not found — skipping PR comment."
+  exit 0
+fi
+
+PR_NUMBER="${PR_NUMBER:-}"
+if [ -z "$PR_NUMBER" ] && [ -n "${GITHUB_EVENT_PATH:-}" ] && [ -f "$GITHUB_EVENT_PATH" ]; then
+  PR_NUMBER=$(python3 -c "
+import json
+try:
+    data = json.load(open('$GITHUB_EVENT_PATH'))
+    print(data.get('pull_request', {}).get('number', ''))
+except Exception:
+    print('')
+" 2>/dev/null || true)
+fi
+
+if [ -z "$PR_NUMBER" ]; then
+  echo "Not running in a pull_request context — skipping PR comment."
+  exit 0
+fi
+
+export GH_TOKEN="$TOKEN"
+
+PASS=$(python3 -c "import json; v=json.load(open('$VERDICT_FILE')); print(str(v.get('pass',True)).lower())")
+SCORE=$(python3 -c "import json; v=json.load(open('$VERDICT_FILE')); print(v.get('score',0))")
+SUMMARY=$(python3 -c "import json; v=json.load(open('$VERDICT_FILE')); print(v.get('summary',''))")
+SKIPPED=$(python3 -c "import json; v=json.load(open('$VERDICT_FILE')); print(str(v.get('skipped',False)).lower())")
+
+if [ "$SKIPPED" = "true" ]; then
+  ICON="⏭️"
+  STATUS="SKIPPED"
+elif [ "$PASS" = "true" ]; then
+  ICON="✅"
+  STATUS="PASS"
+else
+  ICON="❌"
+  STATUS="BLOCKED"
+fi
+
+# Build findings table
+FINDINGS_TABLE=$(python3 <<'PYEOF'
+import json, sys
+
+with open("artifacts/verdict.json") as f:
+    v = json.load(f)
+
+findings = v.get("findings", [])
+if not findings:
+    print("_No findings._")
+    sys.exit(0)
+
+severity_icons = {"error": "🔴", "warning": "🟡", "info": "🔵"}
+
+print("| | Severity | Spec | Requirement | Message | File |")
+print("|---|----------|------|-------------|---------|------|")
+for f in findings:
+    icon = severity_icons.get(f.get("severity", "info"), "⚪")
+    sev = f.get("severity", "—")
+    spec = f.get("spec", "—")
+    req = f.get("requirement", "—")
+    msg = f.get("message", "—")
+    file = f.get("file", "—")
+    line = f.get("line")
+    if line:
+        file = f"{file}:{line}"
+    print(f"| {icon} | {sev} | {spec} | {req} | {msg} | {file} |")
+PYEOF
+)
+
+# Build comment body
+COMMENT_BODY="## ${ICON} Spec Verifier — ${STATUS}
+
+**Score:** ${SCORE}/100
+**Verdict:** ${STATUS}
+
+### Summary
+${SUMMARY}
+
+### Findings
+${FINDINGS_TABLE}
+
+---
+_AI Spec Verifier • agent-orchestrator-kit • Run: ${GITHUB_RUN_ID:-local}_"
+
+TMP_BODY_FILE=$(mktemp)
+trap 'rm -f "$TMP_BODY_FILE"' EXIT
+echo "$COMMENT_BODY" > "$TMP_BODY_FILE"
+
+GH_REPO_FLAG=()
+if [ -n "${GITHUB_REPOSITORY:-}" ]; then
+  GH_REPO_FLAG=(--repo "$GITHUB_REPOSITORY")
+fi
+
+# Security: token is passed via GH_TOKEN env var, never logged
+if gh pr comment "$PR_NUMBER" "${GH_REPO_FLAG[@]}" --body-file "$TMP_BODY_FILE" >/dev/null 2>&1; then
+  echo "PR comment posted successfully"
+else
+  echo "Failed to post PR comment"
+fi