agent-orchestrator-kit 0.2.0 → 0.4.0

package/templates/.agents/skills/openspec-archive-change/SKILL.md

@@ -9,115 +9,28 @@ metadata:
   generatedBy: "1.4.1"
 ---
 
-Archive a completed change in the experimental workflow.
+Archive a completed change. The phase is fully deterministic — one CLI call, no phase subagents.
 
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Conductor delegation is mandatory:** after resolving the change and confirming archive gates, spawn `spec-archiver` with a self-contained prompt. The parent MUST NOT compare/merge main specs or move the change itself; it only verifies the structured report, archive path, and validation result.
+**Input**: Optionally specify a change name. If omitted or ambiguous, run `npx openspec list --json` and use the **AskUserQuestion tool** to let the user pick an active change. Never guess or auto-select.
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
-
-   Run `npx openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show only active changes (not already archived).
-   Include the schema used for each change if available.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check artifact completion status**
-
-   Run `npx openspec status --change "<name>" --json` to check artifact completion.
-
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used
-   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
-   - `artifacts`: List of artifacts with their status (`done` or other)
-
-   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
-
-   **If any artifacts are not `done`:**
-   - Display warning listing incomplete artifacts
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
-   - Proceed if user confirms
-
-3. **Check task completion status**
-
-   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
-
-   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
-
-   **If incomplete tasks found:**
-   - Display warning showing count of incomplete tasks
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
-   - Proceed if user confirms
-
-   **If no tasks file exists:** Proceed without task-related warning.
-
-4. **Assess delta spec sync state**
+1. **Resolve the change name** (see Input above).
 
-   Use `artifactPaths.specs.existingOutputPaths` from status JSON to identify delta specs. Pass these paths and the user's sync preference to `spec-archiver`; the parent MUST NOT compare or merge specs itself.
+2. **Decide on delta-spec sync.** If the change has delta specs, ask the user: merge them into main specs (`--sync`, recommended) or archive without merging (`--no-sync --force`).
 
-   **If delta specs exist:**
-   - Ask whether main specs should be synced before archive
-   - Include the delta and main spec paths in the `spec-archiver` prompt
-   - Have `spec-archiver` return the combined sync summary in its report
-
-   **Prompt options:**
-   - If changes needed: "Sync now (recommended)", "Archive without syncing"
-   - If already synced: "Archive now", "Sync anyway", "Cancel"
-
-   The `spec-archiver` performs any requested comparison and sync as part of its isolated work; do not spawn a generic sync agent.
-
-5. **Spawn the specialist and perform the archive**
-
-   Spawn `spec-archiver`, require `## Subagent report: spec-archiver`, and delegate the sync/archive operations below. Do not run them in the parent session.
-
-   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
-   ```bash
-   mkdir -p "<planningHome.changesDir>/archive"
-   ```
-
-   Generate target name using current date: `YYYY-MM-DD-<change-name>`
-
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move `changeRoot` to the archive directory
+3. **Run the CLI:**
 
    ```bash
-   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
+   npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
    ```
 
-6. **Verify the report and display summary**
-
-   The conductor verifies `Status: done`, the reported archive path, and modified main specs before reporting completion.
-
-   Show archive completion summary including:
-   - Change name
-   - Schema that was used
-   - Archive location
-   - Whether specs were synced (if applicable)
-   - Note about any warnings (incomplete artifacts/tasks)
-
-**Output On Success**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
-**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+   The CLI checks gates (review APPROVE when `require_spec_review: true`, all tasks `[x]`, no existing target archive), merges delta specs on `--sync` (ADDED append, MODIFIED replace, REMOVED delete), moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>`, runs `npx openspec validate --all --strict` with full rollback on failure, and writes the final `handoff.md` (`next_command: none`) plus memory upsert.
 
-All artifacts complete. All tasks complete.
-```
+4. **Show the CLI stdout as-is.** On exit ≠ 0, report the failed gate from stderr and stop.
 
 **Guardrails**
-- Always prompt for change selection if not provided
-- Use artifact graph (openspec status --json) for completion checking
-- Don't block archive on warnings - just inform and confirm
-- Preserve .openspec.yaml when moving to archive (it moves with the directory)
-- Show clear summary of what happened
-- If sync is requested, use openspec-sync-specs approach (agent-driven)
-- If delta specs exist, always run the sync assessment and show the combined summary before prompting
+- Do NOT merge main specs, move the change, or edit anything manually — the CLI owns the whole operation.
+- Spawn `spec-archiver` ONLY as a fallback when the `agent-orchestrator-kit archive` CLI is unavailable or failed for environmental reasons (not for unmet gates).
+- On a sync conflict reported by the CLI, use the `openspec-sync-specs` skill to resolve it, then re-run `archive`.
+- The pipeline ends here: no next-thread prompt is required after a successful archive.

package/templates/.agents/skills/openspec-propose/SKILL.md

@@ -24,6 +24,17 @@ When ready to implement, run /opsx:apply
 
 **Conductor delegation is mandatory:** spawn `spec-architect` with the resolved name, decision brief, design brief if present, and artifact instructions. The parent MUST NOT create or edit proposal/design/specs/tasks; after the structured report it may only verify paths, run status, and run strict validation.
 
+**Task contract (mandatory tasks.md format):** every task must carry indented `Files:`, `Do:`, `Done-when:` fields:
+
+```markdown
+- [ ] 2.1 Short title
+  Files: src/router/index.js, new file: src/stores/auth.js
+  Do: concrete change in 1–3 lines — no vague wording ("as needed", "if necessary", "as appropriate")
+  Done-when: verifiable condition or command
+```
+
+Each task must be self-contained for a blind implementer — executable without reading design.md. `Files:` paths must exist unless prefixed with `new file:`. Lint: `npx agent-orchestrator-kit gate-check --tasks <name>` (mode via `pipeline.task_contract: warn|strict|off`).
+
 **Steps**
 
 1. **If no clear input provided, ask what they want to build**

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

@@ -1,33 +1,35 @@
 ---
 name: session-handoff
-description: ALWAYS use at the start of every /opsx:* session to restore Memory and handoff.md, and at session exit to persist Memory, write handoff.md, run `npx agent-orchestrator-kit handoff`, and emit the expanded next-thread prompt. Do NOT use to write src/, specs, review.md, or to perform the phase specialist's work.
+description: FALLBACK ONLY — use when the parent-driven protocol in `.agents/rules/session-handoff.mdc` fails. Restore mode when both `npx agent-orchestrator-kit handoff --restore` and reading handoff.md failed; persist mode when `npx agent-orchestrator-kit handoff <name>` failed after the parent wrote handoff.md. Never a routine step. Do NOT use to write src/, specs, review.md, or to perform the phase specialist's work.
 ---
 
-You are the session-boundary specialist. You restore or persist orchestration state. You do not implement features, write specs, or review code.
+You are the session-boundary fallback specialist. The routine Session Start / Session Exit protocol is parent-driven (see `.agents/rules/session-handoff.mdc`); you run only when that protocol failed. You restore or persist orchestration state. You do not implement features, write specs, or review code.
 
-The parent is the conductor. Amp MUST spawn this skill as an isolated subagent (`subagent-session-handoff`) with fresh context and MUST NOT execute this body in the main thread.
+When spawned, Amp runs this skill as an isolated subagent (`subagent-session-handoff`) with fresh context — never as the main thread body.
 
 ## Restore mode
 
-Use when the conductor says restore / session start.
+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.
 
 ## Persist mode
 
-Use when the conductor says persist / session exit. A session is not closed until this mode succeeds.
+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/.agents/subagents/spec-architect.md

@@ -10,7 +10,7 @@ Workflow:
 1. Read `openspec/config.yaml`, existing main specs, the exploration decision brief, and `design-brief.md` when present.
 2. Create or update `proposal.md`, `design.md`, `specs/<capability>/spec.md`, and `tasks.md` using the repository's OpenSpec schema and conventions.
 3. Keep requirements testable: each requirement uses SHALL/MUST language and includes concrete scenarios.
-4. Make tasks ordered, independently verifiable, and traceable to the design and delta specs.
+4. Make tasks ordered, independently verifiable, and traceable to the design and delta specs. Every task MUST follow the task contract: indented `Files:` (existing paths, or `new file:` prefix for new ones), `Do:` (concrete change, no vague wording like "as needed" / "if necessary" / "as appropriate"), and `Done-when:` (verifiable condition or command). Each task must be self-contained for a blind implementer without reading design.md.
 5. Report which validation command the conductor should run; do not cross into review or implementation.
 
 Rules:

package/templates/.agents/subagents/spec-archiver.md

@@ -1,6 +1,6 @@
 ---
 name: spec-archiver
-description: OpenSpec completion specialist. ALWAYS use for /opsx:archive after merge/verification to merge delta specs and archive the completed change. Do NOT use to implement features, alter product behavior, or archive incomplete work.
+description: OpenSpec completion fallback. Use ONLY when the `agent-orchestrator-kit archive` CLI is unavailable or failed for environmental reasons — /opsx:archive normally runs `npx agent-orchestrator-kit archive <name>` directly with no subagent. Do NOT use to implement features, alter product behavior, or archive incomplete work.
 ---
 
 You finalize one completed OpenSpec change. Your writable scope is the affected `openspec/specs/` capabilities and the archive move under `openspec/changes/archive/`.

package/templates/.agents/subagents/spec-reviewer.md

@@ -3,29 +3,33 @@ name: spec-reviewer
 description: Pre-implementation OpenSpec gate reviewer. ALWAYS use for /opsx:review to assess proposal/design/specs/tasks and write review.md. Do NOT use for post-implementation code review, edit src/, or change tasks.md.
 ---
 
-You review one OpenSpec change before apply. You are read-only except for `openspec/changes/<name>/review.md`.
+You are Tier 2 of a two-tier review: you run only after `npx agent-orchestrator-kit gate-check --review <name>` passed. You review one OpenSpec change before apply. You are read-only except for `openspec/changes/<name>/review.md` and, on APPROVE, `openspec/changes/<name>/apply-notes.md`.
 
 Workflow:
 
 1. Read the complete change directory, relevant main specs, `openspec/config.yaml`, and repository paths referenced by the artifacts.
-2. Check proposal → design → delta specs → tasks traceability, scope consistency, testability, migration impact, and compliance with project gates.
-3. Run `npx openspec validate <name> --strict --type change` and record its actual result.
-4. Write `review.md` with findings ordered by severity and exactly one verdict: `APPROVE` or `REQUEST CHANGES`.
-5. Approve only when artifacts are implementable without material guessing and strict validation passes.
+2. Apply the LLM-only checklist — do NOT re-check what Tier 1 covered (strict validation, contract field presence, proposal sections, delta-spec section structure):
+   - proposal ↔ design ↔ tasks consistency (no contradictions or drift);
+   - conflicts with existing `openspec/specs/` requirements;
+   - scope creep vs proposal Non-goals;
+   - task self-sufficiency: a blind implementer can execute each task from Files/Do/Done-when alone, without design.md.
+3. Write `review.md` with findings ordered by severity and exactly one verdict: `APPROVE` or `REQUEST CHANGES`.
+4. On APPROVE, also write `apply-notes.md` (≤ 20 lines): critical constraints, pitfalls, what NOT to touch, verification commands. It is the second and last file you may write.
+5. Approve only when artifacts are implementable without material guessing.
 
 Rules:
 
 - Do NOT edit `src/`, tests, proposal/design/spec files, or `tasks.md`.
 - Do NOT implement fixes found during review.
 - Do NOT substitute for `code-reviewer`; that agent reviews the implementation diff after apply.
-- Do NOT approve based only on validation syntax; verify semantics and repository references.
+- Do NOT approve based only on Tier 1 passing; verify semantics and repository references.
 
 Return exactly this report contract:
 
 ```
 ## Subagent report: spec-reviewer
 **Status:** done | blocked
-**Files:** review.md
+**Files:** review.md (+ apply-notes.md on APPROVE)
 **Done:** verdict and validation result
 **Blocked:** missing artifacts or none
 **Risks:** non-blocking review notes or none

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/AGENTS.md

@@ -2,7 +2,7 @@
 
 > Powered by [agent-orchestrator-kit](https://github.com/makshc2/agent-orchestrator-kit) v{{KIT_VERSION}}
 
-Spec-driven OpenSpec pipeline. Each phase is a **separate chat**. The parent `/opsx:*` session is a **conductor**: restore, spawn the specialist, verify the report — never do specialist work in-thread.
+Spec-driven OpenSpec pipeline. Each phase is a **separate chat**. Delegation is differentiated (lean model): explore/design/propose/review spawn a mandatory specialist; **apply is parent-driven** — the parent implements from `tasks.md` + `apply-notes.md`, subagents are optional (≥ 2 independent tasks or explicit request; `design-implementer` for design-brief/Figma); **archive is a CLI** (`npx agent-orchestrator-kit archive <name> [--sync]`), no subagent.
 
 ```
 explore → [design] → propose → review → apply → verify → archive
@@ -23,9 +23,9 @@ Routing table, HARD STOP, and CLI forms: `.agents/rules/` (`agent-orchestration`
 | Quick (MVP) | `/opsx:quick <name>` |
 | Archive | `/opsx:archive` |
 
-Start: `npx agent-orchestrator-kit status` then `handoff --restore`. Spawn `session-handoff` restore only if that CLI failed. Then spawn the routed specialist (Amp: isolated `subagent-<name>`).
+Session Start / Exit are **parent-driven** — canonical protocol in `.agents/rules/session-handoff.mdc`. Start: `status` → `handoff --restore` → `handoff.md` fallback. Exit HARD STOP: parent writes `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste the CLI `/opsx:*` prompt. `session-handoff` subagent = fallback only. Do not start the next phase here.
 
-Exit HARD STOP: persist `session-handoff` → `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste the CLI `/opsx:*` prompt. Do not start the next phase here.
+Quality gates: `gate-check --tasks <name>` lints the task contract (Files/Do/Done-when, `pipeline.task_contract: warn|strict|off`); `gate-check --review <name>` is deterministic Tier 1 of review — spec-reviewer (Tier 2) is spawned only after it passes and writes `apply-notes.md` on APPROVE.
 
 ## Hard rules
 - One active change (unless mvp profile).

package/templates/CLAUDE.md

@@ -8,8 +8,8 @@ See `AGENTS.md` and `.agents/rules/` for routing, HARD STOP, and CLI (`npx` only
 /opsx:explore · /opsx:design · /opsx:propose · /opsx:review · /opsx:apply · /opsx:archive
 ```
 
-Conductor session: restore with `npx agent-orchestrator-kit handoff --restore`, spawn the phase specialist, do not do specialist work here. Spawn `session-handoff` restore only if CLI restore failed.
+Lean delegation: explore/design/propose/review spawn a mandatory specialist; apply is parent-driven from `tasks.md` + `apply-notes.md` (subagents optional for independent tasks); archive runs `npx agent-orchestrator-kit archive <name> [--sync]` — no subagent. Review is two-tiered: `gate-check --review` (deterministic) before `spec-reviewer`; `gate-check --tasks` lints the Files/Do/Done-when task contract.
 
-Exit: persist → `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste the CLI prompt. Do not start the next phase in this chat.
+Session Start/Exit are parent-driven (canonical: `.agents/rules/session-handoff.mdc`): restore with `npx agent-orchestrator-kit handoff --restore`; exit — write `handoff.md`, run `npx agent-orchestrator-kit handoff <name>` (exit 0), paste the CLI prompt. `session-handoff` subagent is a fallback only. Do not start the next phase in this chat.
 
 One active change. No `src/` in explore/design/review. After apply: build/lint. Skills: `.claude/skills/` (synced from `.agents/skills/`).

package/templates/orchestrator.yaml

@@ -12,6 +12,7 @@ pipeline:
   require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
+  task_contract: warn
 
 roles:
   explorer:
@@ -50,7 +51,7 @@ handoff:
   persist_on_exit: true
   emit_next_session_prompt: true
   prompt_self_contained: true
-  spawn_handoff_subagent: true
+  spawn_handoff_subagent: false
 
 memory:
   enabled: true
@@ -63,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
@@ -82,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