agent-orchestrator-kit 0.1.13 → 0.2.0

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

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

@@ -2,133 +2,36 @@
 
 > Powered by [agent-orchestrator-kit](https://github.com/makshc2/agent-orchestrator-kit) v{{KIT_VERSION}}
 
-This project uses a **spec-driven, role-separated AI pipeline** built on [OpenSpec](https://github.com/fission-ai/openspec).
-Every feature follows the same cycle regardless of stack or IDE.
-
-## Pipeline
+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.
 
 ```
 explore → [design] → propose → review → apply → verify → archive
 ```
 
-`[design]` is optional — run `/opsx:design` when the change has UI and you need a durable design brief (Figma, screenshot, or photo). Skip for non-UI work; use `Design: none` in `proposal.md` when `require_design_brief: true`.
-
-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>` | 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` |
-| 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`).
-
-Both CI fragments also run `npx 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`), and optionally requires `design-brief.md` (when `require_design_brief: true`, unless `proposal.md` has `Design: none`). At session start run `npx agent-orchestrator-kit status` (not a bare global binary — Amp PATH often lacks it; see `.agents/rules/cli-via-npm.mdc`).
-
-## Hard Rules
-
-- **One active change per developer** at a time.
-- **No apply without spec-review approval** (explicit Approve in chat).
-- **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
-
-| Transition | Gate |
-|------------|------|
-| explore → design | UI change needs a brief; change name chosen |
-| explore → propose | Decision brief written; change name chosen (skip design if non-UI) |
-| design → propose | `design-brief.md` (+ `assets/`) written |
-| propose → review | `npx openspec validate <name> --strict --type change` passes ✓ |
-| 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 — check `npx agent-orchestrator-kit status` for "ready to archive" |
-
-## Context to Pin per Role
-
-| Role | Attach (`@`) |
-|------|-------------|
-| Explorer | `@openspec/specs/` + relevant `@src/` subtree |
-| Design Intake | design source (Figma URL / images) + `@openspec/changes/<name>/` |
-| Architect | `@openspec/config.yaml` + explore brief (+ `@design-brief.md` if present) |
-| Reviewer | entire `@openspec/changes/<name>/` |
-| Implementer | `@openspec/changes/<name>/tasks.md` + `@openspec/changes/<name>/design-brief.md` |
-
-## Configuration
-
-See `.agents/orchestrator.yaml` for role config, pipeline flags, and MCP baseline.
-
-## 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.
-
-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.
-
-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.
-
-### Optional: Figma personal token
-
-For design intake against private Figma files, each developer configures a local token (never commit, never paste into chat):
-
-```bash
-npx agent-orchestrator-kit figma-setup
-# edit .agents/figma.local.env → FIGMA_ACCESS_TOKEN=...
-npx agent-orchestrator-kit figma-status
-```
-
-MCP starts via `scripts/figma-mcp-launcher.cjs` (secret stays out of `.mcp.json`). See kit README → **Figma token**.
+`[design]` is optional (`/opsx:design`). Non-UI: `Design: none` in `proposal.md` when `require_design_brief: true`. MVP: `/opsx:quick` when `require_spec_review: false`.
 
-## Skills & Commands
+Routing table, HARD STOP, and CLI forms: `.agents/rules/` (`agent-orchestration`, `session-handoff`, `cli-via-npm`). Config: `.agents/orchestrator.yaml`.
 
-All skills live in `.agents/skills/` (committed to git).
-Local IDE sync: run `./scripts/sync-local-agent-skills.sh`.
+## Commands
+| Role | Command |
+|------|---------|
+| Explorer | `/opsx:explore` |
+| Design Intake | `/opsx:design <name>` |
+| Architect | `/opsx:propose <name>` |
+| Spec Reviewer | `/opsx:review <name>` |
+| Implementer | `/opsx:apply <name>` |
+| Quick (MVP) | `/opsx:quick <name>` |
+| Archive | `/opsx:archive` |
 
-| Skill | When |
-|-------|------|
-| `agent-orchestration` | Pipeline decisions, role selection, handoff |
-| `openspec-howto` | OpenSpec CLI, cycle, naming |
-| `openspec-propose` | Creating change artifacts |
-| `openspec-apply-change` | Implementing tasks |
-| `openspec-archive-change` | Archiving after merge |
+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>`).
 
-## Metrics (track per change)
+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.
 
-| Metric | Target |
-|--------|--------|
-| Sessions per change | 4–8 |
-| Apply iterations to PR | ≤ 2 |
-| Spec review loops | ≤ 1 |
-| Tasks rework after apply | ≤ 10% |
-| CI fails on PR | ≤ 1 |
+## Hard rules
+- One active change (unless mvp profile).
+- No apply without explicit Approve when `require_spec_review: true`.
+- No `src/` in explore, design, or review.
+- Archive after merge. Build/lint before PR.
+- Memory MCP: `node scripts/memory-mcp-launcher.cjs` (never relative `MEMORY_FILE_PATH`).
 
-If apply iterations > 2 — fix in Architect/Reviewer, not Implementer.
+Pin only the files for the current role (`tasks.md`, the change folder, relevant `src/` subtree) — not entire `openspec/specs/`.

package/templates/CLAUDE.md

@@ -1,74 +1,15 @@
 # {{PROJECT_NAME}} — Claude Code Context
 
-> agent-orchestrator-kit v{{KIT_VERSION}} | Spec-driven pipeline with OpenSpec
+> agent-orchestrator-kit v{{KIT_VERSION}} | OpenSpec pipeline
 
-## Project
-
-See `AGENTS.md` for the full orchestration pipeline, roles, and hard rules.
-See `openspec/config.yaml` for stack context and agent language.
-
-## Skills
-
-Project skills live in `.claude/skills/` (synced from `.agents/skills/`).
-Use `/skill-name` or let Claude auto-load based on context.
-
-| Skill | Command | When |
-|-------|---------|------|
-| Agent Orchestration | `/agent-orchestration` | Role selection, pipeline, handoff decisions |
-| OpenSpec Howto | `/openspec-howto` | CLI, cycle, naming |
-| OpenSpec Propose | `/openspec-propose` | Creating change artifacts |
-| OpenSpec Apply | `/openspec-apply-change` | Implementing tasks |
-| OpenSpec Archive | `/openspec-archive-change` | Archiving after merge |
-
-## Pipeline Commands
+See `AGENTS.md` and `.agents/rules/` for routing, HARD STOP, and CLI (`npx` only). Config: `.agents/orchestrator.yaml`.
 
 ```
-/opsx:explore   — think through ideas (read-only, no code)
-/opsx:design    — capture design into design-brief.md + assets/ (optional)
-/opsx:propose   — create change artifacts
-/opsx:review    — spec review (read-only, no code)
-/opsx:apply     — implement tasks
-/opsx:archive   — archive after merge
+/opsx:explore · /opsx:design · /opsx:propose · /opsx:review · /opsx:apply · /opsx:archive
 ```
 
-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` |
-| 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.
-- One active change at a time — run `npx openspec list` / `npx agent-orchestrator-kit status` to confirm.
-- 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
-
-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.
-
-OpenSpec files are the requirements/tasks source of truth. Memory and `handoff.md` only index phase state, decisions, blockers, and the next command.
+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.
 
-## File Locations
+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.
 
-| 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` |
-| Skills | `.claude/skills/` |
+One active change. No `src/` in explore/design/review. After apply: build/lint. Skills: `.claude/skills/` (synced from `.agents/skills/`).

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"