agent-orchestrator-kit 0.3.0 → 0.5.0

package/package.json

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

package/profiles/generic/orchestrator.yaml

@@ -61,6 +61,22 @@ mcp:
     - memory
   optional:
     - figma
+    - github
+    - gitlab
+    - browser
+
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    - openspec-explore
+    - openspec-propose
+    - openspec-apply-change
+    - openspec-archive-change
+    - openspec-sync-specs
+    - spec-workflow-openspec
+  stack: []
+  external: ""
 
 figma:
   env_file: .agents/figma.local.env

package/profiles/mvp/orchestrator.yaml

@@ -68,6 +68,22 @@ mcp:
     - memory
   optional:
     - figma
+    - github
+    - gitlab
+    - browser
+
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    - openspec-explore
+    - openspec-propose
+    - openspec-apply-change
+    - openspec-archive-change
+    - openspec-sync-specs
+    - spec-workflow-openspec
+  stack: []
+  external: ""
 
 figma:
   env_file: .agents/figma.local.env

package/profiles/node/orchestrator.yaml

@@ -36,7 +36,6 @@ roles:
     command: /opsx:apply
     mode: code
     model_hint: strong
-    notes: "Use javascript-core, javascript-node, javascript-testing skills during apply"
   verifier:
     type: ci
     gates:
@@ -66,6 +65,25 @@ mcp:
     - memory
   optional:
     - figma
+    - github
+    - gitlab
+    - browser
+
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    - openspec-explore
+    - openspec-propose
+    - openspec-apply-change
+    - openspec-archive-change
+    - openspec-sync-specs
+    - spec-workflow-openspec
+  stack:
+    - javascript-core
+    - javascript-node
+    - javascript-testing
+  external: frontend-agent-skills
 
 figma:
   env_file: .agents/figma.local.env

package/profiles/vue3/orchestrator.yaml

@@ -36,7 +36,6 @@ roles:
     command: /opsx:apply
     mode: code
     model_hint: strong
-    notes: "Use vue-core, vue-pinia, vue-axios, vue-router skills during apply"
   verifier:
     type: ci
     gates:
@@ -66,8 +65,26 @@ mcp:
   optional:
     - figma
     - github
+    - gitlab
     - browser
 
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    - openspec-explore
+    - openspec-propose
+    - openspec-apply-change
+    - openspec-archive-change
+    - openspec-sync-specs
+    - spec-workflow-openspec
+  stack:
+    - vue-core
+    - vue-pinia
+    - vue-axios
+    - vue-router
+  external: frontend-agent-skills
+
 figma:
   env_file: .agents/figma.local.env
   token_key: FIGMA_ACCESS_TOKEN

package/templates/.agents/amp.settings.json.example

@@ -7,6 +7,18 @@
     "figma": {
       "command": "node",
       "args": ["scripts/figma-mcp-launcher.cjs"]
+    },
+    "github": {
+      "command": "node",
+      "args": ["scripts/github-mcp-launcher.cjs"]
+    },
+    "gitlab": {
+      "command": "node",
+      "args": ["scripts/gitlab-mcp-launcher.cjs"]
+    },
+    "browser": {
+      "command": "node",
+      "args": ["scripts/browser-mcp-launcher.cjs"]
     }
   }
 }

package/templates/.agents/github.local.env.example

@@ -0,0 +1,10 @@
+# GitHub Personal Access Token (local only — never commit this file)
+# Create: GitHub → Settings → Developer settings → Personal access tokens
+# Recommended scopes: repo (private) or public_repo, plus pull requests as needed
+#
+# 1. Copy:  cp .agents/github.local.env.example .agents/github.local.env
+# 2. Paste your token below (do NOT paste it into AI chat)
+# 3. Restart Cursor / Amp after saving
+# 4. Check:  npx agent-orchestrator-kit status
+
+GITHUB_PERSONAL_ACCESS_TOKEN=

package/templates/.agents/gitlab.local.env.example

@@ -0,0 +1,12 @@
+# GitLab Personal Access Token (local only — never commit this file)
+# Create: GitLab → Preferences → Access Tokens (api or read_api as needed)
+# Self-hosted: set GITLAB_API_URL to https://<hostname>/api/v4
+# mcp-setup writes GITLAB_API_URL from git remote origin when it detects GitLab
+#
+# 1. Copy:  cp .agents/gitlab.local.env.example .agents/gitlab.local.env
+# 2. Paste your token below (do NOT paste it into AI chat)
+# 3. Restart Cursor / Amp after saving
+# 4. Check:  npx agent-orchestrator-kit status
+
+GITLAB_PERSONAL_ACCESS_TOKEN=
+GITLAB_API_URL=

package/templates/.agents/mcp.json.example

@@ -7,6 +7,18 @@
     "figma": {
       "command": "node",
       "args": ["scripts/figma-mcp-launcher.cjs"]
+    },
+    "github": {
+      "command": "node",
+      "args": ["scripts/github-mcp-launcher.cjs"]
+    },
+    "gitlab": {
+      "command": "node",
+      "args": ["scripts/gitlab-mcp-launcher.cjs"]
+    },
+    "browser": {
+      "command": "node",
+      "args": ["scripts/browser-mcp-launcher.cjs"]
     }
   }
 }

package/templates/.agents/rules/memory-mcp-autosetup.mdc

@@ -9,4 +9,4 @@ If `.mcp.json` / `.amp/settings.json` lacks `memory`, or `MEMORY_FILE_PATH` is r
 
 Use `node scripts/memory-mcp-launcher.cjs` (no relative `MEMORY_FILE_PATH`). Shared file: `.cursor/memory.json` (gitignored). Do not delete other MCP servers.
 
-Entities: `Change:<name>` (status, tasks n/m, last_role, review) · `Handoff:<name>` (next_role, next_command, session_count, summary, blocked) · `Decision:<topic>` (chosen, reason). Writer: `npx agent-orchestrator-kit handoff <name>`. Notify once: “Memory MCP connected.”
+Entities: `Change:<name>` (status, tasks n/m, last_role, review) · `Handoff:<name>` (next_role, next_command, session_count, summary, blocked) · `Decision:<topic>` (chosen, reason) — mirror of git-tracked `openspec/changes/<name>/decisions.md` (file → Memory only; never Memory → file). Writer: `npx agent-orchestrator-kit handoff <name>` (same command appends `decisions.md`). Notify once: “Memory MCP connected.”

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

@@ -7,22 +7,25 @@ alwaysApply: true
 
 This rule is the single source of the Session Start / Session Exit protocol. Commands reference it; they do not duplicate it. A `/opsx:*` session is incomplete without persist + the fenced next-thread prompt. FORBIDDEN until persist succeeds: done/готово, next phase, or omitting the prompt.
 
+Agents (local or cloud) write session artifacts only to git-tracked paths — never `/tmp`, never gitignored caches.
+
 ## Session Start (before any work)
 1. Honor pasted `/opsx:<phase> <name>` and announce the role.
 2. `npx agent-orchestrator-kit status`
-3. `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). The CLI briefing is canonical — it already reads memory.json and handoff.md; no separate Memory MCP read step.
+3. `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). The CLI briefing is canonical — it already reads memory.json and handoff.md; accumulated decisions print from git-tracked `openspec/changes/<name>/decisions.md`, not from Memory. No separate Memory MCP read step.
 4. If the restore CLI failed → read `openspec/changes/<name>/handoff.md` directly.
 5. Spawn `session-handoff` in restore mode ONLY if both the CLI and handoff.md are unavailable (Amp: isolated `subagent-session-handoff`). This is a fallback, never a routine step.
 6. Free-form continue/next/«далі» with one active change → execute `Handoff.next_command`.
 7. Only then start phase work (spawn a specialist when the phase routing requires one).
 
 ## Session Exit (order)
-1. The parent writes `openspec/changes/<name>/handoff.md` itself: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
-2. `npx agent-orchestrator-kit handoff <name>` — require exit 0 (upserts absolute-path Memory JSON, prints the expanded prompt on stdout).
+1. The parent writes `openspec/changes/<name>/handoff.md` itself: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime.
+2. `npx agent-orchestrator-kit handoff <name>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, records the session into `openspec/changes/<name>/metrics.json`, prints the expanded prompt on stdout). `decisions.md` is the git canon of change decisions; Memory `Decision:*` is a file→Memory mirror only. Cloud sessions pass `--runtime cloud` (or set `AOK_RUNTIME=cloud` / `AOK_AGENT_ID` in the cloud-agent environment). When session spend is known, pass it to persist: `--model <name> --input-tokens <n> --output-tokens <n> --cost-usd <usd>` — metrics power planning; never guess values you do not know.
 3. Spawn `session-handoff` in persist mode ONLY if step 2 failed (Amp: isolated `subagent-session-handoff`). Fallback, never routine.
 4. Memory MCP is an optional mirror: if tools are available, update `Change:<name>`, `Handoff:<name>`, `Decision:*` in one call; unavailability never blocks closing.
 5. Paste CLI stdout as one fenced block. First line `/opsx:…`. Body uses `project.agent_language`. Self-contained (Done/Decisions/Blocked/spawn/HARD STOP). No banner.
-6. Stop. Next role = new chat.
+6. If runtime is cloud: after persist, `git add openspec/changes/<name>/` → `git commit` → `git push` → `npx agent-orchestrator-kit handoff <name> --cloud-check` (exit 0 required). Closing without this is an incomplete handoff. Persist prints these steps on stderr; the CLI never runs `git commit` / `git push`.
+7. Stop. Next role = new chat.
 
 ## Archive exception
 `npx agent-orchestrator-kit archive <name>` writes the final `handoff.md` (`next_command: none`) in the archive folder and upserts memory itself. After a successful archive no fenced next-prompt is required — the pipeline is complete.

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

@@ -133,7 +133,7 @@ Archive is one deterministic CLI call — `npx agent-orchestrator-kit archive <n
 **Start of each session:**
 1. Honor the pasted `/opsx:<phase> <name>` command and announce that role.
 2. Run `npx agent-orchestrator-kit status` (or `npx openspec list --json`) and read `orchestrator.yaml`; resolve the active change and gates.
-3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`).
+3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Accumulated decisions print from git-tracked `openspec/changes/<name>/decisions.md`, not from Memory.
 4. Read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works.
 5. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; Memory failure alone is not a blocker.
 6. Spawn `session-handoff` in restore mode **only if** `handoff --restore` failed or printed no briefing (Amp: isolated `subagent-session-handoff`). Skip this spawn when CLI restore exits 0.
@@ -146,7 +146,7 @@ Archive is one deterministic CLI call — `npx agent-orchestrator-kit archive <n
 
 **End of each session (HARD STOP — you are NOT done):**
 1. Write `openspec/changes/<name>/handoff.md` in the parent using the template below.
-2. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts Memory JSON with an absolute path and prints the expanded self-contained prompt on stdout. Spawn `session-handoff` in persist mode ONLY if this CLI step failed.
+2. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (the git canon), upserts Memory JSON with an absolute path (`Decision:*` is a file→Memory mirror only), and prints the expanded self-contained prompt on stdout. Spawn `session-handoff` in persist mode ONLY if this CLI step failed.
 3. If Memory MCP tools are available, mirror `Change:<name>`, `Handoff:<name>`, and new `Decision:<topic>` entities in one call — optional; its absence never blocks closing.
 4. Paste the CLI stdout as one fenced next-session prompt. First line is `/opsx:<next> <name>`; body uses `project.agent_language`; keep Done/Decisions/Blocked/spawn/HARD STOP complete. No banner. Do not emit a thin “read Memory” stub.
 5. Do not start the next phase in this chat. If apply, include build/lint status in the persisted Done section.
@@ -193,6 +193,10 @@ Archive is one deterministic CLI call — `npx agent-orchestrator-kit archive <n
 - do not mix phases
 - conductor must spawn specialists
 
+## Runtime
+- runtime: <local | cloud>
+- agent_id: <id | none>
+
 ## Prompt
 
 The Prompt section is overwritten by `npx agent-orchestrator-kit handoff <name>`. Do not hand-write a thin stub.
@@ -214,7 +218,7 @@ The Prompt section is overwritten by `npx agent-orchestrator-kit handoff <name>`
 
 Before specialist work, the parent MUST restore context in order: honor the pasted `/opsx:*` command; run `npx agent-orchestrator-kit handoff --restore` (the CLI briefing is canonical — no separate Memory MCP read step); if the CLI failed, read `openspec/changes/<name>/handoff.md`; spawn `session-handoff` in restore mode ONLY when both failed. Missing Memory MCP never blocks a session. With one active change, free-form “continue” uses `Handoff.next_command` instead of asking for the phase. Amp spawns any needed subagent as an isolated `subagent-*` skill.
 
-Before declaring a session closed, the parent MUST, in order: (1) write `openspec/changes/<name>/handoff.md` itself, (2) run `npx agent-orchestrator-kit handoff <name>` (exit 0) — spawn `session-handoff` persist ONLY if this CLI step failed, (3) paste the CLI stdout prompt whose first line is `/opsx:<next> <name>`. Memory MCP mirroring is an optional single call. The prompt has no `NEXT_SESSION_PROMPT` label, uses `project.agent_language`, and MUST be self-contained (Done, Decisions, Blocked, attach, spawn, HARD STOP) so the next thread can run if Memory MCP is ignored. Never start the next phase in the current chat.
+Before declaring a session closed, the parent MUST, in order: (1) write `openspec/changes/<name>/handoff.md` itself, (2) run `npx agent-orchestrator-kit handoff <name>` (exit 0) — this CLI appends `decisions.md` and mirrors `Decision:*` file→Memory; spawn `session-handoff` persist ONLY if this CLI step failed, (3) paste the CLI stdout prompt whose first line is `/opsx:<next> <name>`. Memory MCP mirroring is an optional single call. Never write Memory back into `decisions.md`. The prompt has no `NEXT_SESSION_PROMPT` label, uses `project.agent_language`, and MUST be self-contained (Done, Decisions, Blocked, attach, spawn, HARD STOP) so the next thread can run if Memory MCP is ignored. Never start the next phase in the current chat. Write session artifacts only to git-tracked paths (never `/tmp`, never gitignored caches). If runtime is cloud: after persist, commit → push → `npx agent-orchestrator-kit handoff <name> --cloud-check` with exit 0; closing without that is an incomplete handoff.
 
 | Entity | Required fields |
 |--------|-----------------|

package/templates/.agents/subagents/session-handoff.md

@@ -12,8 +12,8 @@ When spawned, Amp runs this skill as an isolated subagent (`subagent-session-han
 Use when the parent's restore failed (CLI restore and handoff.md both unavailable).
 
 1. Run `npx agent-orchestrator-kit status`.
-2. Run `npx agent-orchestrator-kit handoff --restore` (add `<name>` when known).
-3. If Memory MCP tools are available, read `Change:<name>`, `Handoff:<name>`, and `Decision:*`.
+2. Run `npx agent-orchestrator-kit handoff --restore` (add `<name>` when known). The briefing prints accumulated decisions from git-tracked `openspec/changes/<name>/decisions.md` (canon), not from Memory.
+3. If Memory MCP tools are available, read `Change:<name>`, `Handoff:<name>`, and `Decision:*` (the latter is a file→Memory mirror of `decisions.md`).
 4. If CLI restore fails, read `openspec/changes/<name>/handoff.md` when it exists.
 5. Return the restore report. Do not spawn the phase specialist yourself.
 
@@ -21,13 +21,15 @@ Use when the parent's restore failed (CLI restore and handoff.md both unavailabl
 
 Use when the parent's persist failed (`npx agent-orchestrator-kit handoff <name>` did not exit 0). A session is not closed until persist succeeds.
 
-1. Write or update `openspec/changes/<name>/handoff.md` with every required section: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
-2. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. This upserts `.cursor/memory.json` using an absolute path and prints the expanded next-session prompt on stdout.
-3. If Memory MCP tools are available, also create/update `Change:<name>`, `Handoff:<name>`, and each `Decision:<topic>` to match the file. MCP failure is not a blocker after the CLI succeeds.
+1. Write or update `openspec/changes/<name>/handoff.md` with every required section: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime.
+2. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. This appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (git canon), upserts `.cursor/memory.json` using an absolute path (`Decision:*` mirrors that file, never the reverse), and prints the expanded next-session prompt on stdout. Cloud sessions pass `--runtime cloud` (or `AOK_RUNTIME` / `AOK_AGENT_ID`).
+3. If Memory MCP tools are available, also create/update `Change:<name>`, `Handoff:<name>`, and each `Decision:<topic>` to match `decisions.md`. MCP failure is not a blocker after the CLI succeeds.
 4. Put the CLI stdout prompt (first line `/opsx:…`) into **Next prompt** unchanged. Do not shorten it. Do not add a banner.
+5. If runtime is cloud: after persist, commit and push `openspec/changes/<name>/`, then `npx agent-orchestrator-kit handoff <name> --cloud-check` (exit 0 required). Closing without this is an incomplete handoff. The CLI never runs `git commit` / `git push`.
 
 ## Rules
 
+- Write session artifacts only to git-tracked paths (never `/tmp`, never gitignored caches).
 - Do NOT edit `src/`, tests, main specs, `tasks.md` checkboxes, or phase artifacts (`proposal.md`, `review.md`, `design-brief.md`) except `handoff.md`.
 - Do NOT start the next OpenSpec phase.
 - Do NOT return a thin prompt. The next thread must be able to run if Memory MCP is ignored.

package/templates/.cursor/memory.json

@@ -0,0 +1,11 @@
+{"type":"entity","name":"Change:add-factory-memory-and-skills","entityType":"Change","observations":["status: archived","tasks: 9/9","last_role: Archiver","review: APPROVE","summary: archived to openspec/changes/archive/2026-08-27-add-factory-memory-and-skills"]}
+{"type":"entity","name":"Handoff:add-factory-memory-and-skills","entityType":"Handoff","observations":["next_role: none","next_command: none","summary: archived to openspec/changes/archive/2026-08-27-add-factory-memory-and-skills","blocked: none"]}
+{"type":"entity","name":"Decision:apply-complete","entityType":"Decision","observations":["all 9 tasks implemented and verified (npm test 101/101, openspec validate --strict, gate-check --tasks)","change: add-factory-memory-and-skills","date: 2026-08-27"]}
+{"type":"entity","name":"Decision:m1-followed","entityType":"Decision","observations":["task 2.3 Skill health stale/missing verified in a temporary init+sync project (smoke test), not in the kit repo","change: add-factory-memory-and-skills","date: 2026-08-27"]}
+{"type":"entity","name":"Decision:m2-followed","entityType":"Decision","observations":["skills.kit drift test iterates all five orchestrator.yaml files against templates/.agents/skills/","change: add-factory-memory-and-skills","date: 2026-08-27"]}
+{"type":"entity","name":"Decision:i1-honored","entityType":"Decision","observations":["did not change templates/orchestrator.yaml handoff.spawn_handoff_subagent (still false)","change: add-factory-memory-and-skills","date: 2026-08-27"]}
+{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Handoff:add-factory-memory-and-skills","relationType":"hasHandoff"}
+{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Decision:apply-complete","relationType":"hasDecision"}
+{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Decision:m1-followed","relationType":"hasDecision"}
+{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Decision:m2-followed","relationType":"hasDecision"}
+{"type":"relation","from":"Change:add-factory-memory-and-skills","to":"Decision:i1-honored","relationType":"hasDecision"}

package/templates/orchestrator.yaml

@@ -64,8 +64,22 @@ mcp:
   optional:
     - figma
     - github
+    - gitlab
     - browser
 
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    - openspec-explore
+    - openspec-propose
+    - openspec-apply-change
+    - openspec-archive-change
+    - openspec-sync-specs
+    - spec-workflow-openspec
+  stack: []
+  external: ""
+
 figma:
   env_file: .agents/figma.local.env
   token_key: FIGMA_ACCESS_TOKEN
@@ -83,6 +97,8 @@ cli:
   handoff: npx agent-orchestrator-kit handoff <name>
   handoff_restore: npx agent-orchestrator-kit handoff --restore
   memory_setup: npx agent-orchestrator-kit memory-setup
+  mcp_setup: npx agent-orchestrator-kit mcp-setup
+  hooks_setup: npx agent-orchestrator-kit hooks-setup
   openspec_list: npx openspec list
   openspec_validate_change: npx openspec validate <name> --strict --type change
   openspec_validate_all: npx openspec validate --all --strict

package/templates/scripts/browser-mcp-launcher.cjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+
+const child = spawn('npx', ['-y', '@playwright/mcp'], {
+  stdio: 'inherit',
+  env: process.env,
+  shell: process.platform === 'win32',
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code == null ? 1 : code);
+});
+
+child.on('error', (error) => {
+  console.error(`[browser-mcp-launcher] Failed to start Playwright MCP: ${error.message}`);
+  process.exit(1);
+});

package/templates/scripts/github-mcp-launcher.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const { existsSync, readFileSync } = require('fs');
+const { join } = require('path');
+
+const projectDir = join(__dirname, '..');
+const envPath = join(projectDir, '.agents', 'github.local.env');
+
+function readLocalEnv() {
+  if (!existsSync(envPath)) {
+    console.error(
+      `[github-mcp-launcher] Missing ${envPath}. Copy .agents/github.local.env.example → .agents/github.local.env and add GITHUB_PERSONAL_ACCESS_TOKEN (do not paste the token into chat).`
+    );
+    process.exit(1);
+  }
+
+  const values = {};
+  for (const line of readFileSync(envPath, 'utf-8').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+  return values;
+}
+
+const envValues = readLocalEnv();
+const token = envValues.GITHUB_PERSONAL_ACCESS_TOKEN || envValues.GITHUB_TOKEN || '';
+if (!token) {
+  console.error(
+    '[github-mcp-launcher] GITHUB_PERSONAL_ACCESS_TOKEN is empty in .agents/github.local.env. Add a GitHub personal access token locally (never in chat).'
+  );
+  process.exit(1);
+}
+
+const child = spawn('npx', ['-y', '@modelcontextprotocol/server-github'], {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    GITHUB_PERSONAL_ACCESS_TOKEN: token,
+    GITHUB_TOKEN: token,
+  },
+  shell: process.platform === 'win32',
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code == null ? 1 : code);
+});
+
+child.on('error', (error) => {
+  console.error(`[github-mcp-launcher] Failed to start GitHub MCP: ${error.message}`);
+  process.exit(1);
+});

package/templates/scripts/gitlab-mcp-launcher.cjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const { existsSync, readFileSync } = require('fs');
+const { join } = require('path');
+
+const projectDir = join(__dirname, '..');
+const envPath = join(projectDir, '.agents', 'gitlab.local.env');
+const DEFAULT_API_URL = 'https://gitlab.com/api/v4';
+
+function readLocalEnv() {
+  if (!existsSync(envPath)) {
+    console.error(
+      `[gitlab-mcp-launcher] Missing ${envPath}. Copy .agents/gitlab.local.env.example → .agents/gitlab.local.env and add GITLAB_PERSONAL_ACCESS_TOKEN (do not paste the token into chat).`
+    );
+    process.exit(1);
+  }
+
+  const values = {};
+  for (const line of readFileSync(envPath, 'utf-8').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+  return values;
+}
+
+const envValues = readLocalEnv();
+const token = envValues.GITLAB_PERSONAL_ACCESS_TOKEN || envValues.GITLAB_TOKEN || '';
+if (!token) {
+  console.error(
+    '[gitlab-mcp-launcher] GITLAB_PERSONAL_ACCESS_TOKEN is empty in .agents/gitlab.local.env. Add a GitLab personal access token locally (never in chat).'
+  );
+  process.exit(1);
+}
+
+const apiUrl = envValues.GITLAB_API_URL || DEFAULT_API_URL;
+
+const child = spawn('npx', ['-y', '@modelcontextprotocol/server-gitlab'], {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    GITLAB_PERSONAL_ACCESS_TOKEN: token,
+    GITLAB_TOKEN: token,
+    GITLAB_API_URL: apiUrl,
+  },
+  shell: process.platform === 'win32',
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code == null ? 1 : code);
+});
+
+child.on('error', (error) => {
+  console.error(`[gitlab-mcp-launcher] Failed to start GitLab MCP: ${error.message}`);
+  process.exit(1);
+});

package/templates/scripts/pre-commit-gate-check.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+# agent-orchestrator-kit pre-commit gate — runs gate-check against staged files.
+# Disable: remove the marked line from .husky/pre-commit, or `git config --unset core.hooksPath`.
+npx agent-orchestrator-kit gate-check --staged