agent-orchestrator-kit 0.1.13 → 0.2.0

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

@@ -5,71 +5,31 @@ alwaysApply: true
 
 # Agent Orchestration Rules
 
-This project uses a spec-driven role pipeline. Read `.agents/orchestrator.yaml` for config.
-
-## Role Commands
-- `/opsx:explore` → read-only thinking, no code
-- `/opsx:design <name>` → writes only `design-brief.md` + `assets/` (optional design intake)
-- `/opsx:propose <name>` → creates `openspec/changes/<name>/` artifacts only
-- `/opsx:review <name>` → read-only spec review, writes `review.md`, outputs Approve or Request Changes
-- `/opsx:apply <name>` → writes `src/`, marks `tasks.md [x]` (blocked if no review when `require_spec_review: true`)
-- `/opsx:quick <name>` → MVP: propose + apply in one session (when `require_spec_review: false`)
-- `/opsx:archive` → merges delta specs, moves change to archive
-
-## Conductor Routing (Mandatory and Exclusive)
-
-The parent `/opsx:*` session is the conductor. For specialist work it MUST spawn the one subagent selected below with a self-contained prompt, MUST verify the structured report, and MUST NOT perform that specialist's work itself. One signal maps to one primary subagent; do not substitute a generic agent.
-
-| Phase / signal | MUST spawn | Specialist scope the conductor MUST NOT do |
-|----------------|------------|--------------------------------------------|
-| Status, gate failure, next command | `openspec-guide` | Pipeline diagnosis |
-| 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/` |
-| `/opsx:propose` | `spec-architect` | Change proposal/design/specs/tasks |
-| `/opsx:review` | `spec-reviewer` | Pre-apply spec verdict and `review.md` |
-| Apply task with design brief/Figma/image | `design-implementer` | UI implementation |
-| Apply ordinary implementation task | `code-writer` | One task's production code |
-| Apply after implementation | `test-writer` | Automated tests |
-| Apply before PR/MR | `code-reviewer` | Post-implementation spec review |
-| `/opsx:archive` | `spec-archiver` | Delta merge and archive move |
-
-`spec-reviewer` is never interchangeable with `code-reviewer`. During apply, only the conductor may mark a `tasks.md` checkbox, and only after a subagent reports `Status: done` and the conductor verifies the reported files.
-
-## Session Start Protocol (Before Any Specialist Work)
-
-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.
-
-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.
-
-## Session Exit Protocol (Mandatory Order)
-
-A phase is not closed until the conductor performs these steps in order:
-
-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.
-
-## Session Rules
-- One active change at a time (unless mvp profile: up to 3)
-- Each role = new chat session (except `/opsx:quick` combines propose+apply)
-- No code in explore, design, or review sessions
-- Design Intake may write only `openspec/changes/<name>/design-brief.md` and `assets/`
-- No apply without review when `pipeline.require_spec_review: true` — check `review.md` or Approve in context
-- When `require_design_brief: true` and the change touches UI — need `design-brief.md`, or `Design: none` in `proposal.md` for non-UI
-- Apply uses the design brief, not live Figma MCP
-- After apply: build + lint before PR
-- After merge: run `/opsx:archive` (when `archive_after_merge: true`)
-- CLI: `npx agent-orchestrator-kit status`, `npx openspec …` — never bare globals (see `cli-via-npm.mdc`)
-
-## Never
-- Mix propose and apply in one session
-- Edit `src/` during explore, design, or review
-- Skip spec review before apply
-- Call live Figma MCP during apply when a design brief exists
-- Leave changes un-archived after merge
+Spec-driven pipeline. Read `.agents/orchestrator.yaml`. Details: skill `agent-orchestration`. Handoff: `.agents/rules/session-handoff.mdc`. CLI: `npx` only (`.agents/rules/cli-via-npm.mdc`).
+
+## Commands
+`/opsx:explore` read-only · `/opsx:design <name>` brief+assets only · `/opsx:propose <name>` change artifacts · `/opsx:review <name>` review.md · `/opsx:apply <name>` code (blocked without Approve when `require_spec_review`) · `/opsx:quick <name>` MVP propose+apply · `/opsx:archive`
+
+The parent `/opsx:*` session is the **conductor**. It MUST spawn the one routed specialist, verify the structured report, and MUST NOT do that specialist's work. Only the conductor marks `tasks.md`, after `Status: done` and file check. `spec-reviewer` ≠ `code-reviewer`.
+
+| Signal | MUST spawn |
+|--------|------------|
+| Status / gate / next command | `openspec-guide` |
+| Restore if CLI briefing missing; persist on exit | `session-handoff` |
+| Broken kit / MCP / sync | `setup-doctor` |
+| `/opsx:explore` | `codebase-explorer` |
+| `/opsx:design` | `design-intake` |
+| `/opsx:propose` | `spec-architect` |
+| `/opsx:review` | `spec-reviewer` |
+| Apply + design brief/Figma/image | `design-implementer` |
+| Apply ordinary task | `code-writer` |
+| Apply tests | `test-writer` |
+| Apply pre-PR | `code-reviewer` |
+| `/opsx:archive` | `spec-archiver` |
+
+## Session
+Start: honor pasted `/opsx:*` → `npx agent-orchestrator-kit status` → `handoff --restore`. Spawn `session-handoff` restore **only if** restore CLI failed or printed no briefing (Amp: isolated `subagent-session-handoff`). Then spawn the phase specialist isolated. Free-form continue → `Handoff.next_command`.
+
+Exit HARD STOP: persist via `session-handoff` → `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste CLI stdout as one fenced `/opsx:*` prompt. Do not start the next phase here.
+
+Never mix propose+apply (except `/opsx:quick`). No `src/` in explore/design/review. Skip live Figma during apply when a brief exists.

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/figma-token-setup.mdc

@@ -1,6 +1,6 @@
 ---
 description: Figma personal access token setup — local env file, never ask for token in chat
-alwaysApply: true
+alwaysApply: false
 ---
 
 # Figma Token Setup

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

@@ -3,60 +3,10 @@ description: Memory MCP auto-setup for Cursor and Amp
 alwaysApply: true
 ---
 
-# Memory MCP Auto-Setup
+# Memory MCP
 
-At session start: check `.mcp.json` (Cursor) and `.amp/settings.json` (Amp).
-If `memory` MCP is absent — add it silently.
+If `.mcp.json` / `.amp/settings.json` lacks `memory`, or `MEMORY_FILE_PATH` is relative: run `npx agent-orchestrator-kit memory-setup`. Relative paths resolve inside npx `dist/` and look like “memory ignored”.
 
-## Cursor (.mcp.json)
+Use `node scripts/memory-mcp-launcher.cjs` (no relative `MEMORY_FILE_PATH`). Shared file: `.cursor/memory.json` (gitignored). Do not delete other MCP servers.
 
-```json
-"memory": {
-  "command": "npx",
-  "args": ["-y", "@modelcontextprotocol/server-memory"],
-  "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
-}
-```
-
-## Amp (.amp/settings.json)
-
-```json
-"amp.mcpServers": {
-  "memory": {
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-memory"],
-    "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
-  }
-}
-```
-
-## .gitignore
-
-Ensure present (do not duplicate):
-```
-.cursor/memory.json
-.amp/settings.json
-```
-
-## Memory Entity Format
-
-Use these keys and fields for orchestration state:
-
-| Key | Required fields |
-|-----|-----------------|
-| `Change:<name>` | `status`, `tasks n/m`, `last_role`, `review` |
-| `Handoff:<name>` | `next_role`, `next_command`, `session_count`, `summary`, `blocked` |
-| `Decision:<topic>` | `chosen`, `reason` |
-| `Convention:<area>` | project-specific rules |
-
-## 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 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.
-
-## Rules
-- Do not overwrite existing correct 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
+Entities: `Change:<name>` (status, tasks n/m, last_role, review) · `Handoff:<name>` (next_role, next_command, session_count, summary, blocked) · `Decision:<topic>` (chosen, reason). Writer: `npx agent-orchestrator-kit handoff <name>`. Notify once: “Memory MCP connected.”

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

@@ -0,0 +1,28 @@
+---
+description: Mandatory session restore, Memory persist, subagent spawn, and next-thread prompt
+alwaysApply: true
+---
+
+# Session Handoff — HARD STOP
+
+A `/opsx:*` session is incomplete without persist + the fenced next-thread prompt. FORBIDDEN until persist succeeds: done/готово, next phase, or omitting the prompt.
+
+## Start (before specialist work)
+1. Honor pasted `/opsx:<phase> <name>`.
+2. `npx agent-orchestrator-kit status`
+3. `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`)
+4. Read Memory `Change:<name>`, `Handoff:<name>`, `Decision:*` when MCP works
+5. If restore CLI failed and Memory is empty → `openspec/changes/<name>/handoff.md`. Memory failure is not a blocker when the file exists.
+6. Spawn `session-handoff` restore **only if** step 3 failed or printed no briefing (Amp: isolated `subagent-session-handoff`). Skip this spawn when CLI restore exit 0.
+7. Spawn the routed phase specialist. Amp: isolated `subagent-<name>`. Do not do specialist work in the parent.
+8. Free-form continue/next/«далі» with one active change → execute `Handoff.next_command`.
+
+## Exit (order)
+1. Spawn `session-handoff` persist (Amp isolated). If spawn fails, persist in the parent — never skip.
+2. Write `handoff.md`: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
+3. `npx agent-orchestrator-kit handoff <name>` — require exit 0 (upserts absolute-path Memory JSON, prints the prompt).
+4. Update Memory entities when tools work.
+5. Paste CLI stdout as one fenced block. First line `/opsx:…`. Body uses `project.agent_language`. Self-contained (Done/Decisions/Blocked/spawn/HARD STOP). No banner.
+6. Stop. Next role = new chat.
+
+Memory MCP: launcher `node scripts/memory-mcp-launcher.cjs`, never a relative `MEMORY_FILE_PATH`.

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 **only if** `handoff --restore` failed or printed no briefing (Amp: isolated `subagent-session-handoff`). Skip this spawn when CLI restore exits 0.
+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)