agent-orchestrator-kit 0.1.12 → 0.1.14

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

@@ -0,0 +1,48 @@
+---
+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.
+---
+
+You are the session-boundary specialist. 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.
+
+## Restore mode
+
+Use when the conductor says restore / session start.
+
+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:*`.
+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.
+
+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.
+4. Put the CLI stdout prompt (first line `/opsx:…`) into **Next prompt** unchanged. Do not shorten it. Do not add a banner.
+
+## Rules
+
+- 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.
+- Stop as blocked when the change name or next command cannot be resolved.
+
+Return exactly this report contract:
+
+```
+## Subagent report: session-handoff
+**Status:** done | blocked
+**Mode:** restore | persist
+**Files:** handoff.md path or none
+**CLI:** handoff command result or skipped
+**Memory:** written | read | unavailable
+**Next prompt:** the full CLI stdout prompt (persist) or none (restore)
+**Done:** what was restored or persisted
+**Blocked:** missing change/command/CLI failure or none
+```

package/templates/.agents/subagents/setup-doctor.md

@@ -1,6 +1,6 @@
 ---
 name: setup-doctor
-description: Diagnoses and fixes agent-orchestrator-kit setup problems — failing `verify:agents`/`gate-check`, missing .mcp.json or .amp/settings.json, out-of-sync .cursor/ or .claude/ directories, stale kit_version. Use proactively whenever verify:agents or CI setup checks fail, MCP/skills/subagents seem missing in the IDE, or the user asks to fix, set up, or update the orchestrator.
+description: Agent-kit setup repair specialist. ALWAYS use for broken MCP, sync, generated IDE files, stale kit versions, verify:agents, or gate-check setup failures. Do NOT use for business code, feature implementation, or OpenSpec change content.
 ---
 
 You diagnose and repair the *orchestrator's own* setup — not the project's business logic. Never touch `src/` or `openspec/changes/` content; only `.agents/`, `.cursor/`, `.claude/`, `.amp/`, `.mcp.json`, and root config files the kit manages.
@@ -10,7 +10,7 @@ Diagnosis steps:
 1. Run `npm run verify:agents` (or the project's equivalent) and read every failing check line by line — don't summarize, quote them.
 2. Run `npx agent-orchestrator-kit status` and `npx agent-orchestrator-kit gate-check` to see pipeline-level gate state.
 3. Check `.agents/orchestrator.yaml` → `kit_version` against the installed package version; flag drift.
-4. Check that `.mcp.json` / `.amp/settings.json` exist (copy from their `.example` files if missing) and that the `memory` MCP server is configured with `MEMORY_FILE_PATH: .cursor/memory.json`.
+4. Check that `.mcp.json` / `.amp/settings.json` exist and that Memory MCP uses `node scripts/memory-mcp-launcher.cjs` (never a relative `MEMORY_FILE_PATH`). If the path is relative or the launcher is missing, run `npx agent-orchestrator-kit memory-setup`.
 5. Optional Figma: run `npx agent-orchestrator-kit figma-status`. If not configured, tell the user to run `npx agent-orchestrator-kit figma-setup` and edit `.agents/figma.local.env` locally — **never ask them to paste the token into chat**. Confirm `.gitignore` contains `.agents/figma.local.env` and that `scripts/figma-mcp-launcher.cjs` exists.
 6. Check `.cursor/skills/`, `.cursor/rules/`, `.cursor/agents/` (and `.claude/` equivalents) are present and not stale relative to `.agents/` — if stale, this is fixed by running `sync`, not by hand-editing.
 
@@ -23,4 +23,13 @@ Fix, in this priority order, applying only safe/reversible changes:
 
 Never attempt fixes that require credentials or external side effects you don't have (npm login/publish, `sudo`, pushing to protected branches, rotating CI/CD variables) — instead tell the user the exact command they need to run themselves.
 
-Report: what you fixed, what still needs the user's action (with exact commands), and re-run `verify:agents` at the end to confirm.
+Return exactly this report contract after re-running `verify:agents`:
+
+```
+## Subagent report: setup-doctor
+**Status:** done | blocked
+**Files:** kit-managed files changed (or none)
+**Done:** diagnosis, fixes, and verification result
+**Blocked:** user action or unavailable credential or none
+**Risks:** remaining setup drift or none
+```

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

@@ -0,0 +1,32 @@
+---
+name: spec-architect
+description: OpenSpec planning specialist. ALWAYS use for /opsx:propose to create or update one change's proposal, design, delta specs, and tasks. Do NOT use to edit src/, implement tasks, run apply, or review its own artifacts.
+---
+
+You translate an approved exploration/design brief into complete OpenSpec change artifacts. Your only writable path is `openspec/changes/<name>/`.
+
+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.
+5. Report which validation command the conductor should run; do not cross into review or implementation.
+
+Rules:
+
+- Do NOT edit `src/`, tests, main specs, CI files, or files outside `openspec/changes/<name>/`.
+- Do NOT run `/opsx:apply`, implement code, or mark implementation tasks complete.
+- Do NOT approve or review your own artifacts.
+- Stop as blocked when a product decision would materially change requirements instead of inventing it.
+
+Return exactly this report contract:
+
+```
+## Subagent report: spec-architect
+**Status:** done | blocked
+**Files:** change artifacts written (or none)
+**Done:** artifacts and requirements completed
+**Blocked:** unresolved decisions or none
+**Risks:** assumptions and migration concerns or none
+```

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

@@ -0,0 +1,31 @@
+---
+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.
+---
+
+You finalize one completed OpenSpec change. Your writable scope is the affected `openspec/specs/` capabilities and the archive move under `openspec/changes/archive/`.
+
+Workflow:
+
+1. Read `.agents/orchestrator.yaml`, the complete change, review verdict, task state, and verification/merge evidence supplied by the conductor.
+2. Refuse to archive unless required review is approved, all tasks are complete, and the configured merge/CI gate is satisfied.
+3. Run the project-supported OpenSpec archive command so delta requirements are merged into main specs and the change moves to the dated archive path.
+4. Run strict validation after the move and report the resulting archive path and modified main specs.
+
+Rules:
+
+- Do NOT edit `src/`, tests, CI, or implementation files.
+- Do NOT add new features, redesign requirements, or repair incomplete implementation during archive.
+- Do NOT manually discard delta requirements to make validation pass.
+- If archive prerequisites are missing, return `blocked` with the exact unmet gate.
+
+Return exactly this report contract:
+
+```
+## Subagent report: spec-archiver
+**Status:** done | blocked
+**Files:** main specs changed and archive path (or none)
+**Done:** archive and validation result
+**Blocked:** unmet gate or none
+**Risks:** merge conflicts or follow-up concerns or none
+```

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

@@ -0,0 +1,32 @@
+---
+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`.
+
+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.
+
+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.
+
+Return exactly this report contract:
+
+```
+## Subagent report: spec-reviewer
+**Status:** done | blocked
+**Files:** review.md
+**Done:** verdict and validation result
+**Blocked:** missing artifacts or none
+**Risks:** non-blocking review notes or none
+```

package/templates/.agents/subagents/test-writer.md

@@ -1,6 +1,6 @@
 ---
 name: test-writer
-description: Writes and updates automated tests for recently changed or newly implemented code, using the project's testing stack (e.g. Vitest + Vue Test Utils for vue3 projects). Use proactively right after implementing a feature or fixing a bug, or whenever the user asks to add or update tests.
+description: Automated-test specialist. ALWAYS use during /opsx:apply after implementation when tests must be added or updated. Do NOT use to implement features, change production behavior, review code, or mark tasks.md checkboxes.
 ---
 
 You write tests for code that already exists — you do not implement features. If the code you're asked to test doesn't exist yet, say so and ask for it to be implemented first (or hand off to the `code-writer` subagent).
@@ -14,4 +14,15 @@ Steps:
 5. Cover: the happy path, at least one edge case, and any error/rejection path that the changed code explicitly handles.
 6. Run the test command (from `verifier.test_command`) and report pass/fail. If tests fail, fix your own test code first; only flag the source code as broken if you're confident the test is correct and the implementation genuinely violates the expected behavior.
 
-Do not test trivial getters/setters, third-party library internals, or purely visual styling. Report which files you added/changed and the final test run result.
+Do not test trivial getters/setters, third-party library internals, or purely visual styling. Never edit `tasks.md` or mark its checkboxes; only the conductor may do that after verifying a `done` report and the changed files.
+
+Return exactly this report contract:
+
+```
+## Subagent report: test-writer
+**Status:** done | blocked
+**Files:** test files changed (or none)
+**Done:** coverage added and test-command result
+**Blocked:** missing implementation or unresolved failure or none
+**Risks:** uncovered cases or none
+```

package/templates/AGENTS.md

@@ -16,17 +16,38 @@ explore → [design] → propose → review → apply → verify → archive
 Each phase runs in a **separate agent session** with a dedicated role, model hint, and permissions.
 Never mix phases in one chat — this is the single most important rule.
 
+The parent `/opsx:*` session is a **conductor**: it restores handoff state, spawns the required specialist, verifies the structured report, and never performs the specialist's work itself.
+
 ## Roles
 
 | Role | Command | Mode | Model hint |
 |------|---------|------|------------|
 | Explorer | `/opsx:explore` | read-only | fast |
 | Design Intake | `/opsx:design <name>` | writes `design-brief.md` + `assets/` only | strong |
-| Architect | `/opsx:propose <name>` | writes `openspec/changes/` only | strong |
-| Spec Reviewer | `/opsx:review <name>` | read-only | medium/strong |
-| Implementer | `/opsx:apply <name>` | writes `src/` | strong |
+| Architect | `/opsx:propose <name>` | conductor; `spec-architect` writes change artifacts | strong |
+| Spec Reviewer | `/opsx:review <name>` | conductor; `spec-reviewer` writes only `review.md` | medium/strong |
+| Implementer | `/opsx:apply <name>` | conductor; apply specialists write code/tests | strong |
 | Verifier | CI (automatic) | scripts only | — |
 
+## Conductor Routing
+
+| Phase / signal | Subagent |
+|----------------|----------|
+| Status, gate failure, next command | `openspec-guide` |
+| Session start restore / session exit persist | `session-handoff` |
+| Broken kit, MCP, or sync | `setup-doctor` |
+| `/opsx:explore` repository research | `codebase-explorer` |
+| `/opsx:design` | `design-intake` |
+| `/opsx:propose` | `spec-architect` |
+| `/opsx:review` | `spec-reviewer` |
+| Apply with design evidence | `design-implementer` |
+| Apply ordinary task | `code-writer` |
+| Apply tests | `test-writer` |
+| Apply pre-PR review | `code-reviewer` |
+| `/opsx:archive` | `spec-archiver` |
+
+This routing is mandatory and exclusive. `spec-reviewer` is not `code-reviewer`; only the conductor marks `tasks.md` after a verified `Status: done` report.
+
 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` 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`).
@@ -40,6 +61,7 @@ Both CI fragments also run `npx agent-orchestrator-kit gate-check` — a determi
 - **No code edits** during explore, design-intake, or spec-review sessions.
 - **Archive after every merge** (`/opsx:archive`).
 - **Always run local build/lint** before opening a PR.
+- **Conductor MUST spawn** the routed specialist and MUST NOT do specialist work in the parent session.
 
 ## Handoff Gates
 
@@ -67,6 +89,18 @@ Both CI fragments also run `npx agent-orchestrator-kit gate-check` — a determi
 
 See `.agents/orchestrator.yaml` for role config, pipeline flags, and MCP baseline.
 
+## Session Handoff
+
+**HARD STOP.** A `/opsx:*` session is incomplete without persist + the fenced next-thread prompt. Amp often skips Memory MCP and in-thread specialist work — use the CLI and isolated `subagent-*` spawns.
+
+At session start, before specialist work: honor the pasted `/opsx:*` command, run `npx agent-orchestrator-kit status`, run `npx agent-orchestrator-kit handoff --restore`, read Memory `Change:<name>`, `Handoff:<name>`, `Decision:*`, then fall back to `openspec/changes/<name>/handoff.md`. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). Then spawn the routed phase specialist (Amp: isolated wrapper, never the main thread).
+
+At exit, in order: spawn `session-handoff` persist → write `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0, upserts absolute-path Memory JSON) → paste the CLI stdout prompt as one fenced block. The prompt body uses `project.agent_language`, has no service banner, and MUST be self-contained (Done, Decisions, Blocked, attach, which subagent to spawn, HARD STOP). Never start the next phase in the current chat.
+
+OpenSpec artifacts remain the source of truth for requirements and tasks. Memory and `handoff.md` index the phase. The pasted prompt is the next thread's operating brief even if Memory is ignored.
+
+Memory MCP MUST use `node scripts/memory-mcp-launcher.cjs` (never a relative `MEMORY_FILE_PATH`). Run `npx agent-orchestrator-kit memory-setup` when the launcher is missing.
+
 ### Optional: Figma personal token
 
 For design intake against private Figma files, each developer configures a local token (never commit, never paste into chat):

package/templates/CLAUDE.md

@@ -31,6 +31,20 @@ Use `/skill-name` or let Claude auto-load based on context.
 /opsx:archive   — archive after merge
 ```
 
+The parent command session is a conductor. It MUST spawn the phase specialist and MUST NOT perform specialist work itself:
+
+| Signal | Subagent |
+|--------|----------|
+| Status / next command | `openspec-guide` |
+| Session restore / persist / next-thread prompt | `session-handoff` |
+| Kit / MCP / sync failure | `setup-doctor` |
+| Explore research | `codebase-explorer` |
+| Design intake | `design-intake` |
+| Propose | `spec-architect` |
+| Spec review | `spec-reviewer` |
+| Apply UI / ordinary task / tests / pre-PR review | `design-implementer` / `code-writer` / `test-writer` / `code-reviewer` |
+| Archive | `spec-archiver` |
+
 ## Key Rules for This Session
 
 - Check `.agents/orchestrator.yaml` for project-specific pipeline config.
@@ -38,15 +52,25 @@ Use `/skill-name` or let Claude auto-load based on context.
 - No code edits in explore, design, or review mode.
 - Design Intake writes only `design-brief.md` and `assets/` — never `src/`.
 - After completing apply: run build/lint before declaring done.
+- Only the conductor marks `tasks.md`, after a specialist reports `Status: done` and its files are verified.
 - Use `npx openspec validate --all --strict` or `npx openspec validate <name> --strict --type change`.
 - Never bare `openspec` / `agent-orchestrator-kit` without `npx` (Amp PATH → exit 127). See `.agents/rules/cli-via-npm.mdc`.
 
+## Session Handoff
+
+**HARD STOP.** Before work: `npx agent-orchestrator-kit handoff --restore`, then Memory `Change:<name>`, `Handoff:<name>`, `Decision:*`; if unavailable, `openspec/changes/<name>/handoff.md`. Spawn `session-handoff` restore when needed (Amp: isolated `subagent-session-handoff`). Spawn the phase specialist isolated — never in the Amp main thread.
+
+At exit: persist via `session-handoff` → `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste the full CLI stdout `/opsx:*` prompt. The prompt MUST be self-contained. Do not begin the next phase in the same chat.
+
+OpenSpec files are the requirements/tasks source of truth. Memory and `handoff.md` index phase state. The pasted prompt is the next thread's operating brief.
+
 ## File Locations
 
 | What | Where |
 |------|-------|
 | Active changes | `openspec/changes/` |
 | Design brief | `openspec/changes/<name>/design-brief.md` + `assets/` |
+| Session handoff index | `openspec/changes/<name>/handoff.md` |
 | Specs (source of truth) | `openspec/specs/` |
 | Project config | `openspec/config.yaml` |
 | Orchestration config | `.agents/orchestrator.yaml` |

package/templates/orchestrator.yaml

@@ -46,10 +46,16 @@ handoff:
   propose_to_review: validate_strict
   review_to_apply: explicit_approve
   apply_to_verify: all_tasks_checked
+  restore_on_start: true
+  persist_on_exit: true
+  emit_next_session_prompt: true
+  prompt_self_contained: true
+  spawn_handoff_subagent: true
 
 memory:
   enabled: true
   file: .cursor/memory.json
+  launcher: scripts/memory-mcp-launcher.cjs
 
 mcp:
   baseline:
@@ -73,6 +79,9 @@ verifier:
 cli:
   status: npx agent-orchestrator-kit status
   gate_check: npx agent-orchestrator-kit gate-check
+  handoff: npx agent-orchestrator-kit handoff <name>
+  handoff_restore: npx agent-orchestrator-kit handoff --restore
+  memory_setup: npx agent-orchestrator-kit memory-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/memory-mcp-launcher.cjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const { existsSync, mkdirSync } = require('fs');
+const { dirname, join } = require('path');
+
+function findProjectDir(startDir) {
+  let dir = startDir;
+  while (dir !== dirname(dir)) {
+    if (
+      existsSync(join(dir, 'AGENTS.md')) ||
+      existsSync(join(dir, '.agents', 'orchestrator.yaml'))
+    ) {
+      return dir;
+    }
+    dir = dirname(dir);
+  }
+  return join(startDir, '..');
+}
+
+const projectDir = findProjectDir(__dirname);
+const cursorDir = join(projectDir, '.cursor');
+const memoryFile = join(cursorDir, 'memory.json');
+
+mkdirSync(cursorDir, { recursive: true });
+
+const child = spawn('npx', ['-y', '@modelcontextprotocol/server-memory'], {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    MEMORY_FILE_PATH: memoryFile,
+  },
+  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(`[memory-mcp-launcher] Failed to start memory MCP: ${error.message}`);
+  process.exit(1);
+});

package/templates/scripts/sync-local-agent-skills.sh

@@ -50,6 +50,8 @@ if [ -d .agents/subagents ]; then
       echo ""
       echo "<!-- AUTO-GENERATED from ${sub} — edit the source file, then re-run this script -->"
       echo ""
+      echo "CRITICAL (Amp / Cursor / Claude): Parent MUST spawn this skill as an isolated subagent with fresh context. Do not execute it in the main thread. If spawn is unavailable, STOP and report blocked — do not perform this specialist's work in the parent. Return only the structured subagent report."
+      echo ""
       awk '/^---$/{c++; next} c>=2{print}' "$sub"
     } > "$DIR/SKILL.md"
     ok "$DIR/SKILL.md"