agent-orchestrator-kit 0.1.13 → 0.1.14

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

@@ -1,11 +1,8 @@
 {
   "amp.mcpServers": {
     "memory": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-memory"],
-      "env": {
-        "MEMORY_FILE_PATH": ".cursor/memory.json"
-      }
+      "command": "node",
+      "args": ["scripts/memory-mcp-launcher.cjs"]
     },
     "figma": {
       "command": "node",

package/templates/.agents/commands/opsx-apply.md

@@ -7,7 +7,7 @@ description: Implement tasks from an OpenSpec change (Experimental)
 
 ## Session Start (Before Any Work)
 
-Honor the pasted command and announce the Implementer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+Honor the pasted command and announce the Implementer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
 
 Implement tasks from an OpenSpec change.
 
@@ -157,9 +157,16 @@ All tasks complete! You can archive this change with `/opsx:archive`.
 What would you like to do?
 ```
 
-## Session Exit (Mandatory Order)
+## Session Exit (HARD STOP)
 
-When apply completes or pauses: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`, including task and build/lint status; (2) write `openspec/changes/<name>/handoff.md` using the orchestration skill template even if Memory fails; (3) print one fenced prompt beginning with the next `/opsx:*` role command. Use `project.agent_language`, tell the next session to read Memory and the file fallback, omit banner labels and the full summary. Never start archive in this apply chat.
+You have NOT finished until every step succeeds. Do not say done/готово, do not start archive, and do not omit the fenced next-thread prompt.
+
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
+2. Write `openspec/changes/<name>/handoff.md` with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints. Include task and build/lint status in Done.
+3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts Memory JSON (absolute path) and prints the expanded self-contained prompt on stdout.
+4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, and new `Decision:*`.
+5. Paste CLI stdout into chat as one fenced block beginning with the next `/opsx:*` role command. Keep it complete. No banner.
+6. Stop. Never start archive in this apply chat.
 
 **Guardrails**
 - Keep going through tasks until done or blocked

package/templates/.agents/commands/opsx-archive.md

@@ -7,7 +7,7 @@ description: Archive a completed change in the experimental workflow
 
 ## Session Start (Before Any Work)
 
-Honor the pasted command and announce the Archiver role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+Honor the pasted command and announce the Archiver role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
 
 Archive a completed change in the experimental workflow.
 
@@ -160,9 +160,16 @@ Target archive directory already exists.
 3. Wait until a different date to archive
 ```
 
-## Session Exit (Mandatory Order)
+## Session Exit (HARD STOP)
 
-Before closing archive: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`; (2) write the final handoff state at the archived change path using the orchestration skill template even if Memory fails; (3) when another role is required, print one fenced `/opsx:*` prompt using `project.agent_language`, Memory keys, and the file fallback, without a banner label or duplicated summary. Do not start another phase in this chat.
+You have NOT finished until every step succeeds. Do not say done/готово and do not omit the fenced next-thread prompt when another role is required.
+
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
+2. Write the final handoff state at the archived change path with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
+3. Run `npx agent-orchestrator-kit handoff <name>` from the archived path context when possible, or write Memory JSON via the same CLI against the active name before the move. Require exit 0 when the change dir still exists.
+4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, and new `Decision:*`.
+5. When another role is required, paste CLI stdout as one fenced `/opsx:*` prompt. Keep it complete. No banner.
+6. Stop. Do not start another phase in this chat.
 
 **Guardrails**
 - Always prompt for change selection if not provided

package/templates/.agents/commands/opsx-design.md

@@ -7,7 +7,7 @@ description: Capture design from any source into a durable design brief for an O
 
 ## Session Start (Before Any Work)
 
-Honor the pasted command and announce the Design Intake role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+Honor the pasted command and announce the Design Intake role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
 
 Capture design into a durable brief for an OpenSpec change. One-shot intake from Figma, exports, screenshots, or photos — then apply never needs live design tools.
 
@@ -128,9 +128,16 @@ For non-UI changes: do not invent a brief. Tell the Architect to add a line `Des
 
 ---
 
-## Session Exit (Mandatory Order)
+## Session Exit (HARD STOP)
 
-Before closing design: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`; (2) write `openspec/changes/<name>/handoff.md` using the orchestration skill template even if Memory fails; (3) print one fenced prompt beginning `/opsx:propose <name>`. Use `project.agent_language`, tell the next session to read Memory and the file fallback, omit banner labels and the full summary. Do not start propose in this chat.
+You have NOT finished until every step succeeds. Do not say done/готово, do not start propose, and do not omit the fenced next-thread prompt.
+
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
+2. Write `openspec/changes/<name>/handoff.md` with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
+3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts Memory JSON (absolute path) and prints the expanded self-contained prompt on stdout.
+4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, and new `Decision:*`.
+5. Paste CLI stdout into chat as one fenced block beginning `/opsx:propose <name>`. Keep it complete. No banner.
+6. Stop. Do not start propose in this chat.
 
 ## Guardrails
 

package/templates/.agents/commands/opsx-explore.md

@@ -7,7 +7,7 @@ description: "Enter explore mode - think through ideas, investigate problems, cl
 
 ## Session Start (Before Any Work)
 
-Honor the pasted command and announce the Explorer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+Honor the pasted command and announce the Explorer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
@@ -166,9 +166,16 @@ When things crystallize, you might offer a summary - but it's optional. Sometime
 
 ---
 
-## Session Exit (Mandatory Order)
+## Session Exit (HARD STOP)
 
-Before closing explore: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`; (2) write `openspec/changes/<name>/handoff.md` using the orchestration skill template even if Memory fails; (3) print one fenced prompt whose first line is the chosen `/opsx:design <name>` or `/opsx:propose <name>`. Use `project.agent_language`, tell the next session to read Memory and the file fallback, omit banner labels and the full summary. Do not start that phase in this chat.
+You have NOT finished until every step succeeds. Do not say done/готово, do not start the next phase, and do not omit the fenced next-thread prompt.
+
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
+2. Write `openspec/changes/<name>/handoff.md` with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
+3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts Memory JSON (absolute path) and prints the expanded self-contained prompt on stdout.
+4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, and new `Decision:*`.
+5. Paste CLI stdout into chat as one fenced block. Keep it complete. No banner. First line is `/opsx:design <name>` or `/opsx:propose <name>`.
+6. Stop. Do not start that phase in this chat.
 
 ## Guardrails
 

package/templates/.agents/commands/opsx-propose.md

@@ -7,7 +7,7 @@ description: Propose a new change - create it and generate all artifacts in one
 
 ## Session Start (Before Any Work)
 
-Honor the pasted command and announce the Architect role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+Honor the pasted command and announce the Architect role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
 
 Propose a new change - create the change and generate all artifacts in one step.
 
@@ -101,9 +101,16 @@ After completing all artifacts, summarize:
 - What's ready: "All artifacts created and validated! Ready for spec review."
 - Prompt: "Run `/opsx:review <name>` in a fresh session."
 
-## Session Exit (Mandatory Order)
+## Session Exit (HARD STOP)
 
-After strict validation passes: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`; (2) write `openspec/changes/<name>/handoff.md` using the orchestration skill template even if Memory fails; (3) print one fenced prompt beginning `/opsx:review <name>`. Use `project.agent_language`, tell the next session to read Memory and the file fallback, omit banner labels and the full summary. Do not start review in this chat.
+You have NOT finished until every step succeeds. Do not say done/готово, do not start review, and do not omit the fenced next-thread prompt.
+
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
+2. Write `openspec/changes/<name>/handoff.md` with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
+3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts Memory JSON (absolute path) and prints the expanded self-contained prompt on stdout.
+4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, and new `Decision:*`.
+5. Paste CLI stdout into chat as one fenced block beginning `/opsx:review <name>`. Keep it complete. No banner.
+6. Stop. Do not start review in this chat.
 
 **Artifact Creation Guidelines**
 

package/templates/.agents/commands/opsx-quick.md

@@ -7,7 +7,7 @@ description: Fast path for MVP/demo — propose artifacts and apply in one sessi
 
 ## Session Start (Before Any Work)
 
-Honor the pasted command and announce the Quick conductor role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+Honor the pasted command and announce the Quick conductor role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
 
 Quick mode for **small changes, demos, and hypothesis testing**. Combines propose + apply in one session.
 
@@ -73,9 +73,16 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 
 ---
 
-## Session Exit (Mandatory Order)
+## Session Exit (HARD STOP)
 
-At the end of the whole quick session: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`, including task and build/lint status; (2) write `openspec/changes/<name>/handoff.md` using the orchestration skill template even if Memory fails; (3) print exactly one fenced prompt for the verify/archive continuation using `project.agent_language`, Memory keys, and the file fallback, without a banner label or duplicated summary. This is the session's only next-session prompt. Do not start archive in this chat.
+At the end of the whole quick session you have NOT finished until every step succeeds. Do not emit a mid-session next-thread prompt between propose and apply. Do not start archive in this chat.
+
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
+2. Write `openspec/changes/<name>/handoff.md` with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints. Include task and build/lint status.
+3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts Memory JSON (absolute path) and prints the expanded self-contained prompt on stdout.
+4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, and new `Decision:*`.
+5. Paste exactly one fenced prompt for verify/archive. Keep it complete. No banner.
+6. Stop. This is the session's only next-session prompt.
 
 **Guardrails**
 - Max ~3 hours of work — if bigger, switch to full pipeline

package/templates/.agents/commands/opsx-review.md

@@ -7,7 +7,7 @@ description: Read-only spec review of an OpenSpec change — approve or request
 
 ## Session Start (Before Any Work)
 
-Honor the pasted command and announce the Spec Reviewer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+Honor the pasted command and announce the Spec Reviewer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
 
 Review an OpenSpec change. Read artifacts, validate structure, output Approve or Request Changes.
 
@@ -160,9 +160,16 @@ Fix the above, then re-run `/opsx:review <name>`.
 
 ---
 
-## Session Exit (Mandatory Order)
+## Session Exit (HARD STOP)
 
-After writing the verdict: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`; (2) write `openspec/changes/<name>/handoff.md` using the orchestration skill template even if Memory fails; (3) print one fenced prompt beginning with the next `/opsx:*` command (`/opsx:apply <name>` only after APPROVE). Use `project.agent_language`, tell the next session to read Memory and the file fallback, omit banner labels and the full summary. Do not start the next phase in this chat.
+You have NOT finished until every step succeeds. Do not say done/готово, do not start apply, and do not omit the fenced next-thread prompt.
+
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
+2. Write `openspec/changes/<name>/handoff.md` with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
+3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts Memory JSON (absolute path) and prints the expanded self-contained prompt on stdout.
+4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, and new `Decision:*`.
+5. Paste CLI stdout into chat as one fenced block beginning with the next `/opsx:*` command (`/opsx:apply <name>` only after APPROVE). Keep it complete. No banner.
+6. Stop. Do not start the next phase in this chat.
 
 ## Guardrails
 

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

@@ -1,11 +1,8 @@
 {
   "mcpServers": {
     "memory": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-memory"],
-      "env": {
-        "MEMORY_FILE_PATH": ".cursor/memory.json"
-      }
+      "command": "node",
+      "args": ["scripts/memory-mcp-launcher.cjs"]
     },
     "figma": {
       "command": "node",

package/templates/.agents/rules/agent-orchestration.mdc

@@ -23,6 +23,7 @@ The parent `/opsx:*` session is the conductor. For specialist work it MUST spawn
 | Phase / signal | MUST spawn | Specialist scope the conductor MUST NOT do |
 |----------------|------------|--------------------------------------------|
 | Status, gate failure, next command | `openspec-guide` | Pipeline diagnosis |
+| Session start restore / session exit persist | `session-handoff` | Memory, `handoff.md`, next-thread prompt |
 | Broken kit, MCP, or generated-file sync | `setup-doctor` | Kit setup repair |
 | `/opsx:explore` repository investigation | `codebase-explorer` | Repository research; no specs or code |
 | `/opsx:design` | `design-intake` | `design-brief.md` and `assets/` |
@@ -40,20 +41,26 @@ The parent `/opsx:*` session is the conductor. For specialist work it MUST spawn
 
 1. Honor the pasted `/opsx:<phase> <name>` command and announce that role.
 2. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`; resolve the active change without exceeding `max_active_changes`.
-3. Read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*`.
-4. If Memory MCP is unavailable or those entities are empty, read `openspec/changes/<name>/handoff.md`. Memory failure alone MUST NOT block the session.
-5. Only after context is restored, spawn the routed specialist.
+3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Use the printed briefing.
+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 MUST NOT block the session when the file exists.
+6. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`, never the main thread).
+7. Only after context is restored, spawn the routed phase specialist. Amp MUST spawn `subagent-<name>` isolated.
 
-If the user says “continue” / “next” without a command and exactly one active change has `Handoff.next_command` (from Memory or `handoff.md`), execute that command instead of asking which phase to run.
+If the user says “continue” / “next” / «продовжуй» / «далі» without a command and exactly one active change has `Handoff.next_command` (from Memory, CLI restore, or `handoff.md`), execute that command instead of asking which phase to run.
 
-## Session Exit Protocol (Mandatory Order)
+Follow `.agents/rules/session-handoff.mdc`.
 
-A phase is not closed until the conductor performs these steps in order:
+## Session Exit Protocol (HARD STOP)
 
-1. Attempt to update Memory: `Change:<name>` (`status`, `tasks n/m`, `last_role`, `review`), `Handoff:<name>` (`next_role`, `next_command`, `session_count`, `summary`, `blocked`), and each new `Decision:<topic>` (`chosen`, `reason`).
-2. Write the same state to `openspec/changes/<name>/handoff.md` with sections **Closed role**, **Done**, **Decisions**, **Blocked**, **Next command**, **Attach**, **Subagents to spawn**, and **Prompt**. Do this even if Memory is unavailable.
-3. Print one fenced copy/paste prompt. Its first line MUST be `/opsx:<next> <name>`; its body MUST use `.agents/orchestrator.yaml` → `project.agent_language`, instruct the next session to read `Change:<name>`, `Handoff:<name>`, and `Decision:*`, and mention the `handoff.md` fallback. Do not add a service/banner label or duplicate the session summary.
-4. Do NOT start the next phase in this chat.
+A phase is not closed until the conductor performs these steps in order. FORBIDDEN: saying done/готово, starting the next phase, or omitting the fenced prompt.
+
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
+2. Write `openspec/changes/<name>/handoff.md` with sections **Closed role**, **Change**, **Done**, **Decisions**, **Blocked**, **Next command**, **Next role**, **Attach**, **Subagents to spawn**, and **Constraints**. Do this even if Memory MCP is unavailable.
+3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts `.cursor/memory.json` with an absolute path and prints the expanded self-contained next-session prompt on stdout.
+4. If Memory MCP tools work, also update `Change:<name>` (`status`, `tasks n/m`, `last_role`, `review`), `Handoff:<name>` (`next_role`, `next_command`, `session_count`, `summary`, `blocked`), and each new `Decision:<topic>` (`chosen`, `reason`).
+5. Paste the CLI stdout as one fenced copy/paste prompt. First line MUST be `/opsx:<next> <name>`; body MUST use `project.agent_language`; MUST keep Done/Decisions/Blocked/spawn/HARD STOP complete. Do not add a banner or shorten the prompt. Amp often skips Memory MCP — the pasted prompt is the next thread's operating brief.
+6. Do NOT start the next phase in this chat.
 
 ## Session Rules
 - One active change at a time (unless mvp profile: up to 3)

package/templates/.agents/rules/cli-via-npm.mdc

@@ -13,7 +13,8 @@ Amp Code і багато агентських shell **не мають** глоб
 | Замість (ламає Amp) | Використовуй |
 |---------------------|--------------|
 | `agent-orchestrator-kit status` | `npx agent-orchestrator-kit status` (або `npm run agent:status`, якщо script є) |
-| `agent-orchestrator-kit gate-check` | `npx agent-orchestrator-kit gate-check` (або `npm run agent:gate-check`) |
+| `agent-orchestrator-kit handoff` | `npx agent-orchestrator-kit handoff <name>` |
+| `agent-orchestrator-kit memory-setup` | `npx agent-orchestrator-kit memory-setup` |
 | `openspec list` | `npx openspec list` (або `npm run openspec:list`) |
 | `openspec validate --strict` | **ніколи без цілі** → `npx openspec validate <name> --strict --type change` |
 | `openspec validate --all --strict` | `npx openspec validate --all --strict` (або `npm run openspec:validate` / `verify:openspec`) |

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

@@ -6,15 +6,18 @@ alwaysApply: true
 # Memory MCP Auto-Setup
 
 At session start: check `.mcp.json` (Cursor) and `.amp/settings.json` (Amp).
-If `memory` MCP is absent — add it silently.
+If `memory` MCP is absent or uses a **relative** `MEMORY_FILE_PATH` — run `npx agent-orchestrator-kit memory-setup` silently.
+
+Shared memory file: `.cursor/memory.json` (same path for Cursor and Amp).
+
+**CRITICAL:** never set `MEMORY_FILE_PATH` to a relative path. Relative `.cursor/memory.json` resolves inside npx `dist/` — Amp then reads the wrong graph (looks like "memory ignored"). Always start Memory via `node scripts/memory-mcp-launcher.cjs`, which injects an absolute path.
 
 ## Cursor (.mcp.json)
 
 ```json
 "memory": {
-  "command": "npx",
-  "args": ["-y", "@modelcontextprotocol/server-memory"],
-  "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+  "command": "node",
+  "args": ["scripts/memory-mcp-launcher.cjs"]
 }
 ```
 
@@ -23,13 +26,20 @@ If `memory` MCP is absent — add it silently.
 ```json
 "amp.mcpServers": {
   "memory": {
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-memory"],
-    "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+    "command": "node",
+    "args": ["scripts/memory-mcp-launcher.cjs"]
   }
 }
 ```
 
+If Amp CLI is available and memory is missing:
+
+```bash
+npx agent-orchestrator-kit memory-setup
+```
+
+Do not run `amp mcp add` with a relative `MEMORY_FILE_PATH`.
+
 ## .gitignore
 
 Ensure present (do not duplicate):
@@ -49,14 +59,17 @@ Use these keys and fields for orchestration state:
 | `Decision:<topic>` | `chosen`, `reason` |
 | `Convention:<area>` | project-specific rules |
 
+The deterministic writer is `npx agent-orchestrator-kit handoff <name>` — it upserts `.cursor/memory.json` even when MCP tools are ignored. Also call Memory MCP create/update when tools work.
+
 ## Session Lifecycle
 
-At the start of every `/opsx:*` role session, after resolving the change and before specialist work, read `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory MCP is unavailable or those entities are empty, read `openspec/changes/<name>/handoff.md` and continue; Memory failure is not a blocker.
+At the start of every `/opsx:*` role session, after resolving the change and before specialist work: `npx agent-orchestrator-kit handoff --restore`, then read `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory MCP is unavailable or those entities are empty, read `openspec/changes/<name>/handoff.md` and continue; Memory failure is not a blocker.
 
-At session exit, first attempt to update `Change:<name>`, `Handoff:<name>`, and every new `Decision:<topic>`. Then always mirror the state to `openspec/changes/<name>/handoff.md`, even when the Memory write fails. Only after that attempt may the conductor emit the next-session prompt.
+At session exit, spawn `session-handoff` (Amp: isolated `subagent-session-handoff`), write `handoff.md`, then run `npx agent-orchestrator-kit handoff <name>` (exit 0 required). Paste the CLI stdout prompt complete. Only after that attempt Memory MCP updates. You are not done without the fenced prompt.
 
 ## Rules
-- Do not overwrite existing correct config
+- Do not overwrite existing correct launcher config
 - Do not delete other MCP servers
 - Notify once: "Memory MCP connected."
-- Never treat unavailable Memory MCP as a reason to stop when `handoff.md` can restore or persist state
+- Never treat unavailable Memory MCP as a reason to skip `handoff.md` or the CLI
+- Never leave a relative `MEMORY_FILE_PATH` in Cursor or Amp config

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

@@ -0,0 +1,46 @@
+---
+description: Mandatory session restore, Memory persist, subagent spawn, and next-thread prompt
+alwaysApply: true
+---
+
+# Session Handoff — HARD STOP (Amp / Cursor / Claude)
+
+This rule overrides convenience. A `/opsx:*` session that skips these steps is incomplete.
+
+Amp ignores soft reminders. Treat every MUST below as a gate. If a spawn tool exists, use it. If it does not, run the CLI yourself. Never skip persist because “the user already knows”.
+
+## You are not done
+
+FORBIDDEN until persist succeeds: saying done / готово, starting the next phase, or omitting the fenced next-thread prompt.
+
+## Session start (before any specialist work)
+
+1. Honor the pasted `/opsx:<phase> <name>` command and announce that role.
+2. Run `npx agent-orchestrator-kit status`.
+3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Use the printed briefing.
+4. Read Memory `Change:<name>`, `Handoff:<name>`, `Decision:*` when MCP works.
+5. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`. Memory failure is not a blocker when the file exists.
+6. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`, never the main thread).
+7. Spawn the routed phase specialist from `.agents/rules/agent-orchestration.mdc`. Amp: isolated `subagent-<name>`. Executing specialist work in the parent thread is a protocol violation.
+8. Free-form “continue” / “next” / «продовжуй» / «далі» with one active change → execute `Handoff.next_command`. Do not ask which phase.
+
+## Session exit (mandatory order)
+
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, do the persist steps in the parent — never skip.
+2. Write `openspec/changes/<name>/handoff.md` with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
+3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts `.cursor/memory.json` with an absolute path and prints the expanded prompt on stdout.
+4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, `Decision:*` to match.
+5. Paste the CLI stdout into chat as one fenced block. Keep it complete. No `NEXT_SESSION_PROMPT` banner. First line is `/opsx:…`. Body uses `project.agent_language`.
+6. Stop. The next role starts in a **new** chat with that pasted prompt.
+
+## Next-thread prompt must be self-contained
+
+The prompt is the next thread’s operating brief. It MUST include: role, change name, language, hard constraints, start checklist, which subagent to spawn (including Amp isolated wrapper name), full Done / Decisions / Blocked / tasks / review / attach, and the exit HARD STOP. Do not emit a thin “read Memory” stub. Amp often skips Memory MCP; the pasted prompt must still be enough to work.
+
+## Memory path
+
+Never configure Memory MCP with a relative `MEMORY_FILE_PATH`. Relative `.cursor/memory.json` resolves inside npx `dist/` and looks like “memory ignored”. Use `node scripts/memory-mcp-launcher.cjs` (Cursor `.mcp.json` and Amp `.amp/settings.json`). Run `npx agent-orchestrator-kit memory-setup` when the launcher is missing or the path is relative.
+
+## Amp isolation
+
+Every `subagent-*` skill MUST be spawned as an isolated subagent with fresh context. Running the wrapper body in the main Amp thread is a protocol violation. If spawn is unavailable, STOP and report blocked — do not impersonate the specialist.

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

@@ -49,6 +49,7 @@ The parent `/opsx:*` session is the conductor. It MUST spawn the selected specia
 | Phase / signal | MUST spawn | Specialist scope |
 |----------------|------------|------------------|
 | Status, gate failure, next command | `openspec-guide` | Read-only pipeline diagnosis |
+| Session start restore / session exit persist | `session-handoff` | Memory, `handoff.md`, next-thread prompt |
 | Broken kit, MCP, or generated-file sync | `setup-doctor` | Kit setup repair only |
 | `/opsx:explore` repository investigation | `codebase-explorer` | Read-only repository research |
 | `/opsx:design` | `design-intake` | `design-brief.md` and `assets/` only |
@@ -132,20 +133,24 @@ After PR merged + CI green:
 **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. Read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*`.
-4. If Memory MCP is unavailable or those entities are empty, read `openspec/changes/<name>/handoff.md`; Memory failure alone is not a blocker.
-5. Only after restoration, spawn the routed specialist. If the user said “continue” / “next” and exactly one active change has `Handoff.next_command`, execute it instead of asking for a phase.
+3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`).
+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 when context is incomplete (Amp: isolated `subagent-session-handoff`).
+7. Only after restoration, spawn the routed phase specialist. If the user said “continue” / “next” and exactly one active change has `Handoff.next_command`, execute it instead of asking for a phase.
 
 **During session:**
 - Stay in role — do not drift into next phase
 - Pause and ask if requirements are unclear
 - Never edit files outside your role's allowed output
 
-**End of each session:**
-1. Attempt to update Memory: `Change:<name>` (`status`, `tasks n/m`, `last_role`, `review`), `Handoff:<name>` (`next_role`, `next_command`, `session_count`, `summary`, `blocked`), and new `Decision:<topic>` entities (`chosen`, `reason`).
-2. Even if Memory fails, write `openspec/changes/<name>/handoff.md` using the template below.
-3. Print exactly one fenced next-session prompt after the write attempt. The first line is `/opsx:<next> <name>`; the body uses `project.agent_language`, tells the next session to read Memory and the file fallback, has no banner label, and does not repeat the summary.
-4. Do not start the next phase in this chat. If apply, include build/lint status in the persisted summary.
+**End of each session (HARD STOP — you are NOT done):**
+1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
+2. Write `openspec/changes/<name>/handoff.md` using the template below even if Memory MCP fails.
+3. 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.
+4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, and new `Decision:<topic>` entities.
+5. 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.
+6. Do not start the next phase in this chat. If apply, include build/lint status in the persisted Done section.
 
 `handoff.md` template:
 
@@ -155,11 +160,18 @@ After PR merged + CI green:
 ## Closed role
 <role and completion status>
 
+## Change
+- name: <name>
+- status: <proposed | spec-approved | applying | blocked>
+- tasks: <n/m>
+- review: <pending | APPROVE | REQUEST_CHANGES | none>
+- last_role: <role>
+
 ## Done
-<concise persisted summary>
+<full persisted summary the next thread needs>
 
 ## Decisions
-- <decision or none>
+- <topic>: <chosen> — <reason>
 
 ## Blocked
 <blocker or none>
@@ -167,19 +179,24 @@ After PR merged + CI green:
 ## Next command
 `/opsx:<next> <name>`
 
+## Next role
+<role or subagent name>
+
 ## Attach
 - `openspec/changes/<name>/<artifact>`
 
 ## Subagents to spawn
-- `<subagent>` — <signal>
+- `<phase-specialist>` — <signal> (Amp: isolated `subagent-<name>`)
+- `session-handoff` — restore at start, persist at exit (Amp: isolated `subagent-session-handoff`)
 
-## Prompt
+## Constraints
+- language: <project.agent_language>
+- do not mix phases
+- conductor must spawn specialists
 
-```text
-/opsx:<next> <name>
+## Prompt
 
-<Localized start instruction in project.agent_language. Read Memory Change:<name>, Handoff:<name>, Decision:* before work. If Memory is unavailable, read openspec/changes/<name>/handoff.md. Act as conductor and do not mix phases.>
-```
+The Prompt section is overwritten by `npx agent-orchestrator-kit handoff <name>`. Do not hand-write a thin stub.
 ````
 
 ## Model Selection Guide
@@ -196,9 +213,9 @@ After PR merged + CI green:
 
 ## Mandatory Memory and Handoff Protocol
 
-Before specialist work, the conductor MUST restore context in order: honor the pasted `/opsx:*` command; read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*`; if Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`. Memory failure is not a blocker when the file exists. With one active change, free-form “continue” uses `Handoff.next_command` instead of asking for the phase.
+Before specialist work, the conductor MUST restore context in order: honor the pasted `/opsx:*` command; run `npx agent-orchestrator-kit handoff --restore`; read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*`; if restore CLI and Memory fail, read `openspec/changes/<name>/handoff.md`. Memory failure is not a blocker when the file exists. With one active change, free-form “continue” uses `Handoff.next_command` instead of asking for the phase. Amp MUST spawn `session-handoff` and the phase specialist as isolated `subagent-*` skills.
 
-Before declaring a session closed, the conductor MUST, in order: (1) update Memory, (2) mirror state to `openspec/changes/<name>/handoff.md`, (3) print one fenced next-session prompt whose first line is `/opsx:<next> <name>`. The prompt has no `NEXT_SESSION_PROMPT` label, tells the next session to read Memory, uses `project.agent_language`, and does not duplicate the full summary. Never start the next phase in the current chat.
+Before declaring a session closed, the conductor MUST, in order: (1) spawn `session-handoff` persist, (2) write `openspec/changes/<name>/handoff.md`, (3) run `npx agent-orchestrator-kit handoff <name>` (exit 0), (4) paste the CLI stdout prompt whose first line is `/opsx:<next> <name>`. 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.
 
 | Entity | Required fields |
 |--------|-----------------|
@@ -226,7 +243,7 @@ Before declaring a session closed, the conductor MUST, in order: (1) update Memo
 | All tasks in one apply session | Context overload; model drifts |
 | No archive after merge | Next propose has stale domain specs |
 | Strong model on lint fixes | 5–10x cost with no quality gain |
-| Skip Memory MCP | Every session re-explains domain |
+| Skip Memory MCP / skip `handoff` CLI | Next thread has no context; Amp looks like it “ignored the rules” |
 
 ## Metrics (health check per change)
 

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
+```