agent-orchestrator-kit 0.1.12 → 0.1.14

package/profiles/vue3/orchestrator.yaml

@@ -48,10 +48,16 @@ handoff:
   propose_to_review: validate_strict
   review_to_apply: explicit_approve
   apply_to_verify: all_tasks_checked
+  restore_on_start: true
+  persist_on_exit: true
+  emit_next_session_prompt: true
+  prompt_self_contained: true
+  spawn_handoff_subagent: true
 
 memory:
   enabled: true
   file: .cursor/memory.json
+  launcher: scripts/memory-mcp-launcher.cjs
 
 mcp:
   baseline:

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

@@ -5,10 +5,16 @@ category: Workflow
 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 `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.
 
 **Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
+**Conductor delegation is mandatory:** the parent MUST NOT implement code or tests. For each task spawn `design-implementer` when a design brief/Figma/image signal exists, otherwise `code-writer`; after implementation spawn `test-writer` when tests are required, and before PR/MR spawn `code-reviewer`. Require each structured report. Only the conductor may edit `tasks.md` checkboxes.
+
 **Steps**
 
 1. **Select the change**
@@ -80,9 +86,10 @@ Implement tasks from an OpenSpec change.
 
    For each pending task:
    - Show which task is being worked on
-   - Make the code changes required
-   - Keep changes minimal and focused
-   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Spawn the routed implementation subagent with one self-contained task; do not make code changes in the parent
+   - Verify `Status: done` and that every reported file exists
+   - Spawn `test-writer` for required test work and verify its report
+   - Only then, as conductor, mark the task complete in the tasks file: `- [ ]` → `- [x]`
    - Continue to next task
 
    **Pause if:**
@@ -150,13 +157,24 @@ All tasks complete! You can archive this change with `/opsx:archive`.
 What would you like to do?
 ```
 
+## Session Exit (HARD STOP)
+
+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
 - Always read context files before starting (from the apply instructions output)
 - If task is ambiguous, pause and ask before implementing
 - If implementation reveals issues, pause and suggest artifact updates
 - Keep code changes minimal and scoped to each task
-- Update task checkbox immediately after completing each task
+- Never let a specialist update `tasks.md`; the conductor updates a checkbox only after a verified `done` report
 - Pause on errors, blockers, or unclear requirements - don't guess
 - Use contextFiles from CLI output, don't assume specific file names
 

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

@@ -5,10 +5,16 @@ category: Workflow
 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 `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.
 
 **Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
+**Conductor delegation is mandatory:** after resolving the change and confirming archive gates, spawn `spec-archiver` with a self-contained prompt. The parent MUST NOT merge main specs or move the change itself; it only verifies the structured report, archive path, and validation result.
+
 **Steps**
 
 1. **If no change name provided, prompt for selection**
@@ -51,20 +57,22 @@ Archive a completed change in the experimental workflow.
 
 4. **Assess delta spec sync state**
 
-   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to identify delta specs. Pass these paths and the user's sync preference to `spec-archiver`; the parent MUST NOT compare or merge specs itself.
 
    **If delta specs exist:**
-   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
-   - Determine what changes would be applied (adds, modifications, removals, renames)
-   - Show a combined summary before prompting
+   - Ask whether main specs should be synced before archive
+   - Include the delta and main spec paths in the `spec-archiver` prompt
+   - Have `spec-archiver` return the combined sync summary in its report
 
    **Prompt options:**
    - If changes needed: "Sync now (recommended)", "Archive without syncing"
    - If already synced: "Archive now", "Sync anyway", "Cancel"
 
-   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+   The `spec-archiver` performs any requested comparison and sync as part of its isolated work; do not spawn a generic sync agent.
+
+5. **Spawn the specialist and perform the archive**
 
-5. **Perform the archive**
+   Spawn `spec-archiver`, require `## Subagent report: spec-archiver`, and delegate the sync/archive operations below. Do not run them in the parent session.
 
    Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
    ```bash
@@ -81,7 +89,9 @@ Archive a completed change in the experimental workflow.
    mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    ```
 
-6. **Display summary**
+6. **Verify the report and display summary**
+
+   The conductor verifies `Status: done`, the reported archive path, and modified main specs before reporting completion.
 
    Show archive completion summary including:
    - Change name
@@ -150,6 +160,17 @@ Target archive directory already exists.
 3. Wait until a different date to archive
 ```
 
+## Session Exit (HARD STOP)
+
+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
 - Use artifact graph (openspec status --json) for completion checking

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

@@ -5,12 +5,18 @@ category: Workflow
 description: Capture design from any source into a durable design brief for an OpenSpec change
 ---
 
+## 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 `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.
 
 **IMPORTANT: You must NEVER edit any file in `src/` or any source code. You may write only `openspec/changes/<name>/design-brief.md` and files under `openspec/changes/<name>/assets/`.**
 
 **Input**: Optionally specify a change name (e.g., `/opsx:design add-login-form`). If omitted, auto-select if one active change exists, otherwise list and ask. If the change does not exist yet, create the change directory when writing the brief (after explore chose the name).
 
+**Conductor delegation is mandatory:** after resolving the change and source, spawn `design-intake` with a self-contained prompt. The parent MUST NOT inspect the design source or write the brief/assets itself; it only verifies the structured report and reported files.
+
 ---
 
 ## Steps
@@ -24,7 +30,11 @@ If name provided — use it. Otherwise:
 
 Announce: "Design intake for change: **<name>**"
 
-### 2. Choose source (fallback ladder)
+### 2. Spawn the specialist
+
+Spawn `design-intake` and delegate steps 3–6 below. Require `## Subagent report: design-intake`. Do not perform those steps in the parent session.
+
+### 3. Choose source (fallback ladder)
 
 Use the first available source; do not climb the ladder twice:
 
@@ -35,14 +45,14 @@ Use the first available source; do not climb the ladder twice:
 
 Ask the user for the source if unclear. Prefer Figma when a `figma.com` URL is given.
 
-### 3. Capture into assets/
+### 4. Capture into assets/
 
 Save reference images under `openspec/changes/<name>/assets/`:
 - Prefer compressed PNG; ~1–2 images per breakpoint
 - Do not commit raw video, PSD, or huge originals
 - Name files clearly: `desktop.png`, `mobile.png`, `hero-detail.png`
 
-### 4. Write design-brief.md
+### 5. Write design-brief.md
 
 Create or overwrite `openspec/changes/<name>/design-brief.md` using this template:
 
@@ -89,14 +99,16 @@ Create or overwrite `openspec/changes/<name>/design-brief.md` using this templat
 - Inferred (screenshot/photo): mark each inferred value with a confidence marker, e.g. `~8px (medium confidence)` or `color ≈ #1a1a1a (low confidence)`
 ```
 
-### 5. Confidence markers for raster sources
+### 6. Confidence markers for raster sources
 
 When the source is a **screenshot** or **photo** (not Figma MCP / vector export):
 - Do not present guessed spacing, colors, or type sizes as facts
 - Mark every inferred token/value with a confidence note in **Confidence notes** and inline in **Tokens** where useful
 - Prefer ranges or approximations over fake precision
 
-### 6. Handoff
+### 7. Verify report and handoff
+
+The conductor verifies `Status: done` and that every reported brief/asset path exists, then outputs the handoff summary.
 
 Output a short summary:
 
@@ -116,6 +128,17 @@ For non-UI changes: do not invent a brief. Tell the Architect to add a line `Des
 
 ---
 
+## Session Exit (HARD STOP)
+
+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
 
 - **Never** edit source code or `src/`

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

@@ -5,9 +5,15 @@ category: Workflow
 description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
 ---
 
+## 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 `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.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+**IMPORTANT: Explore mode is read-only thinking, not implementation or artifact authoring.** You may discuss evidence returned by the specialist, but you must NEVER write code or OpenSpec artifacts. If the user asks you to implement or formalize the change, end explore with a handoff to a fresh propose session.
+
+**Conductor delegation is mandatory:** for any repository investigation, spawn `codebase-explorer` with a self-contained question and require its structured report. Do not search or trace the codebase in the parent session, and do not let the subagent write specs or code. The parent may synthesize the report and continue the exploratory conversation.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
@@ -160,9 +166,20 @@ When things crystallize, you might offer a summary - but it's optional. Sometime
 
 ---
 
+## Session Exit (HARD STOP)
+
+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
 
-- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't implement or author artifacts** - Never write code or OpenSpec files in explore.
 - **Don't fake understanding** - If something is unclear, dig deeper
 - **Don't rush** - Discovery is thinking time, not task time
 - **Don't force structure** - Let patterns emerge naturally

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

@@ -5,6 +5,10 @@ category: Workflow
 description: Propose a new change - create it and generate all artifacts in one step
 ---
 
+## 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 `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.
 
 I'll create a change with artifacts:
@@ -18,6 +22,8 @@ When ready to implement, run /opsx:apply
 
 **Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
 
+**Conductor delegation is mandatory:** spawn `spec-architect` with the resolved name, decision brief, design brief if present, and artifact instructions. The parent MUST NOT create or edit proposal/design/specs/tasks; after the structured report it may only verify files, run status, and run strict validation.
+
 **Steps**
 
 1. **If no input provided, ask what they want to build**
@@ -29,13 +35,17 @@ When ready to implement, run /opsx:apply
 
    **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
 
-2. **Create the change directory**
+2. **Spawn the specialist**
+
+   Spawn `spec-architect` with a self-contained prompt and require `## Subagent report: spec-architect`. Delegate steps 3–5 to it; do not perform artifact creation in the parent session.
+
+3. **Create the change directory**
    ```bash
    npx openspec new change "<name>"
    ```
    This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
 
-3. **Get the artifact build order**
+4. **Get the artifact build order**
    ```bash
    npx openspec status --change "<name>" --json
    ```
@@ -44,7 +54,7 @@ When ready to implement, run /opsx:apply
    - `artifacts`: list of all artifacts with their status and dependencies
    - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
 
-4. **Create artifacts in sequence until apply-ready**
+5. **Create artifacts in sequence until apply-ready**
 
    Use the **TodoWrite tool** to track progress through the artifacts.
 
@@ -76,7 +86,9 @@ When ready to implement, run /opsx:apply
       - Use **AskUserQuestion tool** to clarify
       - Then continue with creation
 
-5. **Show final status**
+6. **Verify the report and show final status**
+
+   The conductor verifies `Status: done` and each reported artifact path, then runs:
    ```bash
    npx openspec status --change "<name>"
    ```
@@ -86,8 +98,19 @@ When ready to implement, run /opsx:apply
 After completing all artifacts, summarize:
 - Change name and location
 - List of artifacts created with brief descriptions
-- What's ready: "All artifacts created! Ready for implementation."
-- Prompt: "Run `/opsx:apply` to start implementing."
+- What's ready: "All artifacts created and validated! Ready for spec review."
+- Prompt: "Run `/opsx:review <name>` in a fresh session."
+
+## Session Exit (HARD STOP)
+
+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

@@ -5,6 +5,10 @@ category: Workflow
 description: Fast path for MVP/demo — propose artifacts and apply in one session (skips review gate)
 ---
 
+## 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 `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.
 
 **Use when:**
@@ -20,6 +24,8 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 
 **Input**: Change name (kebab-case) or description. Example: `/opsx:quick add-export-button`
 
+**Conductor delegation is mandatory inside this one session:** spawn `spec-architect` for minimal artifacts, then `design-implementer` or `code-writer` per implementation task, `test-writer` for tests, and `code-reviewer` before merge. The parent MUST NOT write specialist artifacts/code/tests itself. Specialists never edit `tasks.md`; the conductor verifies each `Status: done` report and marks checkboxes. Do not emit a next-session prompt between propose and apply.
+
 **Steps**
 
 1. **Check orchestrator config**
@@ -30,6 +36,8 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 
 2. **Create change (minimal artifacts)**
 
+   Spawn `spec-architect` with the quick-mode scope and require its structured report. Do not create the artifacts in the parent session.
+
    ```bash
    npx openspec new change "<name>"
    ```
@@ -51,10 +59,13 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 
    Follow `/opsx:apply` steps for the same change:
    - Read tasks.md
-   - Implement 1–3 tasks per pass
-   - Mark `[x]`
+   - Spawn `design-implementer` for design-led work, otherwise `code-writer`, one task per prompt
+   - Spawn `test-writer` for required tests
+   - Verify each structured report and reported file, then let only the conductor mark `[x]`
    - Run build/lint from `orchestrator.yaml` verifier commands
 
+   Continue directly from propose to apply in this session. Do not print or ask the user to paste a mid-session handoff prompt.
+
 5. **Exit**
 
    - If demo done and no merge planned → optionally skip archive
@@ -62,8 +73,20 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 
 ---
 
+## Session Exit (HARD STOP)
+
+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
 - Still run build/lint before declaring done
 - Do not skip OpenSpec entirely — at minimum proposal + tasks
 - For vue3: use vue-core, vue-pinia skills during implementation
+- Never emit or request paste of a next-session prompt between quick propose and apply; emit exactly one only at final exit

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

@@ -5,12 +5,18 @@ category: Workflow
 description: Read-only spec review of an OpenSpec change — approve or request changes before apply
 ---
 
+## 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 `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.
 
 **IMPORTANT: This is a read-only mode. You must NEVER edit any file in `src/` or any source code. You may not mark tasks `[x]`. Your only output is a structured review verdict.**
 
 **Input**: Optionally specify a change name (e.g., `/opsx:review add-auth`). If omitted, auto-select if one active change exists, otherwise list and ask.
 
+**Conductor delegation is mandatory:** after selecting the change, spawn `spec-reviewer` with the complete change paths and project constraints. The parent MUST NOT review artifacts or write `review.md`; it only verifies the structured report and that `review.md` contains the reported verdict. Never substitute `code-reviewer`.
+
 ---
 
 ## Steps
@@ -24,7 +30,11 @@ If name provided — use it. Otherwise:
 
 Announce: "Reviewing change: **<name>**"
 
-### 2. Validate structure
+### 2. Spawn the specialist
+
+Spawn `spec-reviewer` and delegate steps 3–6 below. Require `## Subagent report: spec-reviewer`. Do not perform the review in the parent session.
+
+### 3. Validate structure
 
 ```bash
 npx openspec validate <name> --strict --type change
@@ -32,7 +42,7 @@ npx openspec validate <name> --strict --type change
 
 If ✗ — list each error and immediately output **Request Changes** with the validation errors. Stop here.
 
-### 3. Read all artifacts
+### 4. Read all artifacts
 
 ```bash
 npx openspec status --change "<name>" --json
@@ -46,7 +56,7 @@ Read every file from `artifactPaths`:
 
 Also read related `openspec/specs/` domain files to check consistency.
 
-### 4. Review checklist
+### 5. Review checklist
 
 Evaluate each item. Mark ✓ or ✗:
 
@@ -81,7 +91,7 @@ Evaluate each item. Mark ✓ or ✗:
 - [ ] Tasks reference concrete component/store paths under `src/`
 - [ ] No scope creep into unrelated UI refactors
 
-### 5. Output verdict
+### 6. Write and report the verdict
 
 #### If all ✓ (or only minor notes):
 
@@ -125,6 +135,8 @@ For **REQUEST CHANGES**, write the same file with `Verdict: REQUEST CHANGES` and
 
 This is the **only file** you may write during review (not `src/`, not `tasks.md` checkboxes).
 
+The conductor verifies the subagent's `Status: done`, checks that `review.md` exists with the reported verdict, and relays the result without editing it.
+
 #### If any ✗:
 
 ```
@@ -148,6 +160,17 @@ Fix the above, then re-run `/opsx:review <name>`.
 
 ---
 
+## Session Exit (HARD STOP)
+
+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
 
 - **Never** edit source code, `src/`, or `tasks.md` checkboxes

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

@@ -16,6 +16,52 @@ This project uses a spec-driven role pipeline. Read `.agents/orchestrator.yaml`
 - `/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 |
+| 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/` |
+| `/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. 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, CLI restore, or `handoff.md`), execute that command instead of asking which phase to run.
+
+Follow `.agents/rules/session-handoff.mdc`.
+
+## Session Exit Protocol (HARD STOP)
+
+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)
 - Each role = new chat session (except `/opsx:quick` combines propose+apply)

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