agent-orchestrator-kit 0.1.14 → 0.3.0

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

@@ -5,9 +5,9 @@ category: Workflow
 description: Read-only spec review of an OpenSpec change — approve or request changes before apply
 ---
 
-## Session Start (Before Any Work)
+## Session Start
 
-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`.
+Follow the canonical Session Start protocol in `.agents/rules/session-handoff.mdc`, then announce the Spec Reviewer role.
 
 Review an OpenSpec change. Read artifacts, validate structure, output Approve or Request Changes.
 
@@ -15,7 +15,7 @@ Review an OpenSpec change. Read artifacts, validate structure, output Approve or
 
 **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`.
+**Review is two-tiered:** Tier 1 is a deterministic script (`gate-check --review`) run by the parent **before** any artifact is read by an LLM. Tier 2 is the `spec-reviewer` subagent with a shortened, LLM-only checklist. Spawning `spec-reviewer` is mandatory only when Tier 1 passes. The parent MUST NOT review artifacts or write `review.md` itself when Tier 2 runs. Never substitute `code-reviewer`.
 
 ---
 
@@ -30,59 +30,36 @@ If name provided — use it. Otherwise:
 
 Announce: "Reviewing change: **<name>**"
 
-### 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
+### 2. Tier 1 — deterministic gate-check
 
 ```bash
-npx openspec validate <name> --strict --type change
+npx agent-orchestrator-kit gate-check --review <name>
 ```
 
-If ✗ — list each error and immediately output **Request Changes** with the validation errors. Stop here.
+The script runs `openspec validate --strict --type change`, the task-contract lint (Files/Do/Done-when), the `Non-goals` / `Acceptance criteria` proposal sections check, and non-empty ADDED/MODIFIED/REMOVED delta-spec sections check. Add `--json` for a `{pass, errors[]}` report.
 
-### 4. Read all artifacts
+**If Tier 1 fails (exit ≠ 0):** do NOT spawn `spec-reviewer` and do NOT read the artifacts. Write `openspec/changes/<name>/review.md` with `Verdict: REQUEST CHANGES` listing the gate-check errors (source: gate-check), output the Request Changes verdict in chat, and go straight to Session Exit.
 
-```bash
-npx openspec status --change "<name>" --json
-```
+### 3. Tier 2 — spawn the specialist
 
-Read every file from `artifactPaths`:
-- `proposal.md`
-- `design.md`
-- `tasks.md`
-- all `specs/<domain>/spec.md` files
+Only after Tier 1 passes: spawn `spec-reviewer` with the complete change paths, project constraints, and the shortened checklist below. Require `## Subagent report: spec-reviewer`. Do not perform the review in the parent session.
 
-Also read related `openspec/specs/` domain files to check consistency.
+### 4. Review checklist (Tier 2 — LLM-only)
 
-### 5. Review checklist
+Do NOT re-check what Tier 1 already covered (strict validation, contract field presence, proposal sections, delta-spec section structure). Evaluate each item. Mark ✓ or ✗:
 
-Evaluate each item. Mark ✓ or ✗:
+**Consistency**
+- [ ] proposal ↔ design ↔ tasks tell the same story — no contradictions or drift
+- [ ] Delta specs cover all changed/added behavior described in design
 
-**Proposal**
-- [ ] Problem statement is clear and specific (not vague)
-- [ ] Non-goals are listed
-- [ ] Acceptance criteria are present and testable (not "should work" — must be verifiable)
-- [ ] Scope matches a ~1–3 day change
+**Main specs**
+- [ ] No conflicts with existing `openspec/specs/` requirements
 
-**Design**
-- [ ] Approach is concrete (not "we will handle this")
-- [ ] Trade-offs or alternatives mentioned
-- [ ] Does not contradict existing `openspec/specs/` domain specs
+**Scope**
 - [ ] No scope creep vs proposal Non-goals
 
-**Tasks**
-- [ ] Each task is ≤ ~2 hours of work
-- [ ] Each task has a clear done condition
-- [ ] Tasks are in logical implementation order
-- [ ] No task requires information not in design/spec
-- [ ] No task says "update X as needed" (must be specific)
-
-**Delta Specs**
-- [ ] Cover all changed/added behavior
-- [ ] ADDED/MODIFIED/REMOVED sections used correctly
-- [ ] No conflicts with main `openspec/specs/`
+**Task self-sufficiency**
+- [ ] A blind implementer can execute each task from Files/Do/Done-when alone, without reading design.md
 
 **Vue 3** (when `project.stack: vue3` in `.agents/orchestrator.yaml`)
 - [ ] Components use `<script setup>` + Composition API (no Options API)
@@ -91,7 +68,7 @@ Evaluate each item. Mark ✓ or ✗:
 - [ ] Tasks reference concrete component/store paths under `src/`
 - [ ] No scope creep into unrelated UI refactors
 
-### 6. Write and report the verdict
+### 5. Write and report the verdict
 
 #### If all ✓ (or only minor notes):
 
@@ -131,11 +108,13 @@ Create or update `openspec/changes/<name>/review.md`:
 <optional notes>
 ```
 
-For **REQUEST CHANGES**, write the same file with `Verdict: REQUEST CHANGES` and issues list.
+On **APPROVE**, `spec-reviewer` also writes `openspec/changes/<name>/apply-notes.md` (≤ 20 lines): critical constraints, pitfalls, what NOT to touch, verification commands. It is the distilled input for `/opsx:apply` and the **second allowed file** next to `review.md`.
+
+For **REQUEST CHANGES**, write only `review.md` with `Verdict: REQUEST CHANGES` and the issues list.
 
-This is the **only file** you may write during review (not `src/`, not `tasks.md` checkboxes).
+`review.md` (always) and `apply-notes.md` (on APPROVE) are the **only files** 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.
+The conductor verifies the subagent's `Status: done`, checks that `review.md` exists with the reported verdict (and `apply-notes.md` on APPROVE), and relays the result without editing them.
 
 #### If any ✗:
 
@@ -162,19 +141,12 @@ 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.
+Close via the canonical Session Exit protocol in `.agents/rules/session-handoff.mdc`. First line of the pasted prompt is the next `/opsx:*` command (`/opsx:apply <name>` only after APPROVE). Do not start the next phase in this chat.
 
 ## Guardrails
 
 - **Never** edit source code, `src/`, or `tasks.md` checkboxes
-- **May write only** `openspec/changes/<name>/review.md` (verdict record for apply gate)
+- **May write only** `openspec/changes/<name>/review.md` (verdict record for apply gate) and, on APPROVE, `openspec/changes/<name>/apply-notes.md`
 - **Never** run apply commands
 - Ask for clarification only if a critical artifact is missing or unreadable
 - If proposal is ambiguous on scope, flag as ✗ — do not assume intent

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

@@ -7,6 +7,8 @@ description: Sync delta specs from a change to main specs
 
 Sync delta specs from a change to main specs.
 
+If run as a standalone `/opsx:*` session, follow the canonical Session Start / Session Exit protocol in `.agents/rules/session-handoff.mdc`.
+
 This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
 
 **Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

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

@@ -5,78 +5,30 @@ alwaysApply: true
 
 # Agent Orchestration Rules
 
-This project uses a spec-driven role pipeline. Read `.agents/orchestrator.yaml` for config.
+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`).
 
-## 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
+## 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`
 
-## Conductor Routing (Mandatory and Exclusive)
+The parent `/opsx:*` session is the **conductor**. Delegation is differentiated by phase: propose/review MUST spawn their specialist; apply is parent-driven with optional subagents; archive is a CLI call with phase subagents forbidden. Only the parent marks `tasks.md`. `spec-reviewer` ≠ `code-reviewer`.
 
-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 | Subagent | Status |
+|--------|------------|--------|
+| Status / gate / next command | `openspec-guide` | optional |
+| Restore/persist when handoff CLI failed | `session-handoff` | fallback only |
+| Broken kit / MCP / sync | `setup-doctor` | on signal |
+| `/opsx:explore` | `codebase-explorer` | mandatory |
+| `/opsx:design` | `design-intake` | mandatory |
+| `/opsx:propose` | `spec-architect` | mandatory |
+| `/opsx:review` (after `gate-check --review` passes) | `spec-reviewer` | mandatory |
+| Apply + design brief/Figma/image | `design-implementer` | mandatory on signal |
+| Apply: ≥ 2 independent tasks, no shared files, or explicit request | `code-writer` / `test-writer` | optional |
+| Apply pre-PR | `code-reviewer` | optional |
+| `/opsx:archive` | — use `npx agent-orchestrator-kit archive <name>` | CLI; subagent forbidden (`spec-archiver` = CLI-failure fallback only) |
 
-| 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 |
+## 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`.
 
-`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.
+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.
 
-## 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)
-- 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
+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/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,73 +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 or uses a **relative** `MEMORY_FILE_PATH` — run `npx agent-orchestrator-kit memory-setup` 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”.
 
-Shared memory file: `.cursor/memory.json` (same path for Cursor and Amp).
+Use `node scripts/memory-mcp-launcher.cjs` (no relative `MEMORY_FILE_PATH`). Shared file: `.cursor/memory.json` (gitignored). Do not delete other MCP servers.
 
-**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": "node",
-  "args": ["scripts/memory-mcp-launcher.cjs"]
-}
-```
-
-## Amp (.amp/settings.json)
-
-```json
-"amp.mcpServers": {
-  "memory": {
-    "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):
-```
-.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 |
-
-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: `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, 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 launcher config
-- Do not delete other MCP servers
-- Notify once: "Memory MCP connected."
-- 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
+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

@@ -1,46 +1,30 @@
 ---
-description: Mandatory session restore, Memory persist, subagent spawn, and next-thread prompt
+description: Canonical Session Start and Session Exit protocol for every /opsx:* session
 alwaysApply: true
 ---
 
-# Session Handoff — HARD STOP (Amp / Cursor / Claude)
+# Session Handoff — canonical protocol (HARD STOP)
 
-This rule overrides convenience. A `/opsx:*` session that skips these steps is incomplete.
+This rule is the single source of the Session Start / Session Exit protocol. Commands reference it; they do not duplicate it. A `/opsx:*` session is incomplete without persist + the fenced next-thread prompt. FORBIDDEN until persist succeeds: done/готово, next phase, or omitting the prompt.
 
-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”.
+## Session Start (before any work)
+1. Honor pasted `/opsx:<phase> <name>` and announce the role.
+2. `npx agent-orchestrator-kit status`
+3. `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). The CLI briefing is canonical — it already reads memory.json and handoff.md; no separate Memory MCP read step.
+4. If the restore CLI failed → read `openspec/changes/<name>/handoff.md` directly.
+5. Spawn `session-handoff` in restore mode ONLY if both the CLI and handoff.md are unavailable (Amp: isolated `subagent-session-handoff`). This is a fallback, never a routine step.
+6. Free-form continue/next/«далі» with one active change → execute `Handoff.next_command`.
+7. Only then start phase work (spawn a specialist when the phase routing requires one).
 
-## You are not done
+## Session Exit (order)
+1. The parent writes `openspec/changes/<name>/handoff.md` itself: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
+2. `npx agent-orchestrator-kit handoff <name>` — require exit 0 (upserts absolute-path Memory JSON, prints the expanded prompt on stdout).
+3. Spawn `session-handoff` in persist mode ONLY if step 2 failed (Amp: isolated `subagent-session-handoff`). Fallback, never routine.
+4. Memory MCP is an optional mirror: if tools are available, update `Change:<name>`, `Handoff:<name>`, `Decision:*` in one call; unavailability never blocks closing.
+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.
 
-FORBIDDEN until persist succeeds: saying done / готово, starting the next phase, or omitting the fenced next-thread prompt.
+## Archive exception
+`npx agent-orchestrator-kit archive <name>` writes the final `handoff.md` (`next_command: none`) in the archive folder and upserts memory itself. After a successful archive no fenced next-prompt is required — the pipeline is complete.
 
-## 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.
+Memory MCP: launcher `node scripts/memory-mcp-launcher.cjs`, never a relative `MEMORY_FILE_PATH`.

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

@@ -42,26 +42,25 @@ Read `.agents/orchestrator.yaml` for project-specific config (language, flags, M
 | Quick (MVP) | `/opsx:quick <name>` | specs+code | strong | `openspec/changes/` + `src/` |
 | Verifier | CI / local scripts | — | — | exit codes |
 
-## Conductor Routing (Mandatory and Exclusive)
-
-The parent `/opsx:*` session is the conductor. It MUST spawn the selected specialist with a self-contained prompt, MUST verify the structured report, and MUST NOT do the specialist's work itself. Each signal has exactly one primary subagent.
-
-| 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 |
-| `/opsx:propose` | `spec-architect` | Change artifacts only |
-| `/opsx:review` | `spec-reviewer` | Pre-apply verdict and `review.md` only |
-| Apply task with design brief/Figma/image | `design-implementer` | UI implementation |
-| Apply ordinary implementation task | `code-writer` | One production-code task |
-| 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 not `code-reviewer`. During apply, specialists MUST NOT edit `tasks.md`; only the conductor may mark a checkbox after a `Status: done` report and verification that the reported files exist.
+## Conductor Routing (Differentiated by Phase)
+
+The parent `/opsx:*` session is the conductor. Delegation cost must match phase uncertainty: **propose and review MUST spawn their specialist** (the parent never writes artifacts or the verdict); **apply is parent-driven** — the parent writes code and tests itself from `tasks.md` + `apply-notes.md`, subagents are optional; **archive is one CLI call** — phase subagents are forbidden.
+
+| Phase / signal | Subagent | Status |
+|----------------|------------|--------|
+| Status, gate failure, next command | `openspec-guide` | optional |
+| Restore/persist when handoff CLI failed | `session-handoff` | fallback only |
+| Broken kit, MCP, or generated-file sync | `setup-doctor` | on signal |
+| `/opsx:explore` repository investigation | `codebase-explorer` | mandatory |
+| `/opsx:design` | `design-intake` | mandatory |
+| `/opsx:propose` | `spec-architect` | mandatory |
+| `/opsx:review` (Tier 2, after `gate-check --review` passes) | `spec-reviewer` | mandatory |
+| Apply task with design brief/Figma/image | `design-implementer` | mandatory on signal |
+| Apply: ≥ 2 independent tasks with no shared files, or explicit user request | `code-writer` / `test-writer` | optional |
+| Apply before PR/MR | `code-reviewer` | optional |
+| `/opsx:archive` | — run `npx agent-orchestrator-kit archive <name>` | CLI; phase subagent forbidden (`spec-archiver` = CLI-failure fallback only) |
+
+`spec-reviewer` is not `code-reviewer`. Spawned specialists MUST NOT edit `tasks.md`; the parent checks a box only after verifying the task's Done-when condition. If an apply task requires information beyond its Files/Do/Done-when contract + `apply-notes.md` + referenced artifacts, STOP: record the gap in `handoff.md` and route back to `/opsx:propose <name>` — improvisation is forbidden.
 
 ## Handoff Protocol
 
@@ -127,6 +126,7 @@ After PR merged + CI green:
 ```
 /opsx:archive <name>
 ```
+Archive is one deterministic CLI call — `npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]` — which checks gates, merges delta specs on `--sync`, moves the change to the dated archive, validates with rollback, and writes the final handoff. No phase subagent.
 
 ## Session Rules
 
@@ -136,7 +136,7 @@ After PR merged + CI green:
 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`).
+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:**
@@ -145,12 +145,11 @@ After PR merged + CI green:
 - Never edit files outside your role's allowed output
 
 **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.
+1. Write `openspec/changes/<name>/handoff.md` in the parent using the template below.
+2. 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. Spawn `session-handoff` in persist mode ONLY if this CLI step failed.
+3. If Memory MCP tools are available, mirror `Change:<name>`, `Handoff:<name>`, and new `Decision:<topic>` entities in one call — optional; its absence never blocks closing.
+4. 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.
+5. Do not start the next phase in this chat. If apply, include build/lint status in the persisted Done section.
 
 `handoff.md` template:
 
@@ -213,9 +212,9 @@ The Prompt section is overwritten by `npx agent-orchestrator-kit handoff <name>`
 
 ## Mandatory Memory and Handoff Protocol
 
-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 specialist work, the parent MUST restore context in order: honor the pasted `/opsx:*` command; run `npx agent-orchestrator-kit handoff --restore` (the CLI briefing is canonical — no separate Memory MCP read step); if the CLI failed, read `openspec/changes/<name>/handoff.md`; spawn `session-handoff` in restore mode ONLY when both failed. Missing Memory MCP never blocks a session. With one active change, free-form “continue” uses `Handoff.next_command` instead of asking for the phase. Amp spawns any needed subagent as an isolated `subagent-*` skill.
 
-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.
+Before declaring a session closed, the parent MUST, in order: (1) write `openspec/changes/<name>/handoff.md` itself, (2) run `npx agent-orchestrator-kit handoff <name>` (exit 0) — spawn `session-handoff` persist ONLY if this CLI step failed, (3) paste the CLI stdout prompt whose first line is `/opsx:<next> <name>`. Memory MCP mirroring is an optional single call. 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 |
 |--------|-----------------|

package/templates/.agents/skills/openspec-apply-change/SKILL.md

@@ -13,7 +13,9 @@ Implement tasks from an OpenSpec change.
 
 **Input**: Optionally specify a change name. 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`; then spawn `test-writer` for required tests and `code-reviewer` before PR/MR. Require each structured report. Only the conductor may edit `tasks.md` checkboxes.
+**Parent-driven apply:** the parent reads `tasks.md` + `apply-notes.md` (open `design.md`/`proposal.md` only when a task explicitly references them or a contract field is incomplete) and writes code and tests itself, task by task, checking its own `tasks.md` checkboxes. Subagents are optional: spawn `code-writer`/`test-writer` for ≥ 2 independent tasks with no shared files (parallelization) or on explicit user request. `design-implementer` remains mandatory for tasks with a design-brief/Figma signal.
+
+**Escape valve (STOP — improvisation is forbidden):** if a task requires information beyond its Files/Do/Done-when + `apply-notes.md` + artifacts it explicitly references, STOP: record the gap in `handoff.md`, set the next command to `/opsx:propose <name>` (plan amendment), and end the session. Do not guess.
 
 **Steps**
 
@@ -54,12 +56,9 @@ Implement tasks from an OpenSpec change.
 
    **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
 
-4. **Read context files**
+4. **Read the working set**
 
-   Read every file path listed under `contextFiles` from the apply instructions output.
-   The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
-   - Other schemas: follow the contextFiles from CLI output
+   Read `tasks.md` and `apply-notes.md` — they are the primary input for apply. Open `design.md`, `proposal.md`, or delta specs only when a task explicitly references them or a contract field is incomplete. For non-spec-driven schemas, follow `contextFiles` from the CLI output.
 
 5. **Show current progress**
 
@@ -73,15 +72,13 @@ Implement tasks from an OpenSpec change.
 
    For each pending task:
    - Show which task is being worked on
-   - 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 tests and verify its report
-   - Only then, as conductor, mark the task complete in the tasks file: `- [ ]` → `- [x]`
+   - Implement it in the parent session from its Files/Do/Done-when contract (spawn `code-writer`/`test-writer` only for ≥ 2 independent tasks with no shared files, or on explicit user request; `design-implementer` for design-brief/Figma tasks)
+   - Verify the task's Done-when condition actually holds
+   - Mark the task complete in the tasks file: `- [ ]` → `- [x]`
    - Continue to next task
 
-   **Pause if:**
-   - Task is unclear → ask for clarification
-   - Implementation reveals a design issue → suggest updating artifacts
+   **STOP (escape valve) if:**
+   - The task requires information beyond its contract + `apply-notes.md` + referenced artifacts → record the gap in `handoff.md`, next command `/opsx:propose <name>` — never improvise
    - Error or blocker encountered → report and wait for guidance
    - User interrupts
 
@@ -146,13 +143,11 @@ What would you like to do?
 
 **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
-- 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
+- Always read `tasks.md` + `apply-notes.md` before starting
+- If a task contract is insufficient, STOP via the escape valve — don't guess or improvise
+- Keep code changes minimal and scoped to each task's `Files:` list
+- Never let a spawned specialist update `tasks.md`; the parent checks a box only after verifying Done-when
+- Pause on errors and blockers
 
 **Fluid Workflow Integration**