agent-orchestrator-kit 0.1.13 → 0.1.14

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

@@ -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.
 

package/templates/AGENTS.md

@@ -34,6 +34,7 @@ The parent `/opsx:*` session is a **conductor**: it restores handoff state, spaw
 | 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` |
@@ -90,11 +91,15 @@ See `.agents/orchestrator.yaml` for role config, pipeline flags, and MCP baselin
 
 ## Session Handoff
 
-At session start: honor the pasted `/opsx:*` command, read Memory `Change:<name>`, `Handoff:<name>`, `Decision:*`, then fall back to `openspec/changes/<name>/handoff.md` when Memory is unavailable or empty.
+**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 exit, in order: update Memory → write `handoff.md` → print one fenced next-session prompt beginning with `/opsx:*`. The prompt body uses `project.agent_language`, asks the next session to read Memory, has no service banner, and does not repeat the full summary. Never start the next phase in the current chat.
+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).
 
-OpenSpec artifacts remain the source of truth for requirements and tasks. Memory and `handoff.md` are only a durable index of the current phase, decisions, blockers, and next command.
+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
 

package/templates/CLAUDE.md

@@ -36,6 +36,7 @@ The parent command session is a conductor. It MUST spawn the phase specialist an
 | 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` |
@@ -57,9 +58,11 @@ The parent command session is a conductor. It MUST spawn the phase specialist an
 
 ## Session Handoff
 
-Before work, read Memory `Change:<name>`, `Handoff:<name>`, `Decision:*`; if unavailable or empty, read `openspec/changes/<name>/handoff.md`. At exit: Memory → `handoff.md` → one fenced `/opsx:*` prompt localized to `project.agent_language`, with no banner or duplicated summary. Do not begin the next phase in the same chat.
+**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.
 
-OpenSpec files are the requirements/tasks source of truth. Memory and `handoff.md` only index phase state, decisions, blockers, and the next command.
+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
 

package/templates/orchestrator.yaml

@@ -49,10 +49,13 @@ handoff:
   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:
@@ -76,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,7 +50,7 @@ if [ -d .agents/subagents ]; then
       echo ""
       echo "<!-- AUTO-GENERATED from ${sub} — edit the source file, then re-run this script -->"
       echo ""
-      echo "Parent MUST spawn this skill as an isolated subagent with fresh context. Do not execute it in the main thread. Return only the structured subagent report."
+      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"