agent-orchestrator-kit 0.2.0 → 0.4.0

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

@@ -5,9 +5,9 @@ category: Workflow
 description: Fast path for MVP/demo — propose artifacts and apply in one session (skips review gate)
 ---
 
-## Session Start (Before Any Work)
+## Session Start
 
-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`.
+Follow the canonical Session Start protocol in `.agents/rules/session-handoff.mdc`, then announce the Quick conductor role.
 
 Quick mode for **small changes, demos, and hypothesis testing**. Combines propose + apply in one session.
 
@@ -75,14 +75,7 @@ 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.
+Close via the canonical Session Exit protocol in `.agents/rules/session-handoff.mdc` at the end of the whole quick session only — no mid-session prompt between propose and apply. Include task and build/lint status in Done. Paste exactly one fenced prompt (verify/archive). Do not start archive in this chat.
 
 **Guardrails**
 - Max ~3 hours of work — if bigger, switch to full pipeline

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/github.local.env.example

@@ -0,0 +1,10 @@
+# GitHub Personal Access Token (local only — never commit this file)
+# Create: GitHub → Settings → Developer settings → Personal access tokens
+# Recommended scopes: repo (private) or public_repo, plus pull requests as needed
+#
+# 1. Copy:  cp .agents/github.local.env.example .agents/github.local.env
+# 2. Paste your token below (do NOT paste it into AI chat)
+# 3. Restart Cursor / Amp after saving
+# 4. Check:  npx agent-orchestrator-kit status
+
+GITHUB_PERSONAL_ACCESS_TOKEN=

package/templates/.agents/gitlab.local.env.example

@@ -0,0 +1,12 @@
+# GitLab Personal Access Token (local only — never commit this file)
+# Create: GitLab → Preferences → Access Tokens (api or read_api as needed)
+# Self-hosted: set GITLAB_API_URL to https://<hostname>/api/v4
+# mcp-setup writes GITLAB_API_URL from git remote origin when it detects GitLab
+#
+# 1. Copy:  cp .agents/gitlab.local.env.example .agents/gitlab.local.env
+# 2. Paste your token below (do NOT paste it into AI chat)
+# 3. Restart Cursor / Amp after saving
+# 4. Check:  npx agent-orchestrator-kit status
+
+GITLAB_PERSONAL_ACCESS_TOKEN=
+GITLAB_API_URL=

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

@@ -7,6 +7,18 @@
     "figma": {
       "command": "node",
       "args": ["scripts/figma-mcp-launcher.cjs"]
+    },
+    "github": {
+      "command": "node",
+      "args": ["scripts/github-mcp-launcher.cjs"]
+    },
+    "gitlab": {
+      "command": "node",
+      "args": ["scripts/gitlab-mcp-launcher.cjs"]
+    },
+    "browser": {
+      "command": "node",
+      "args": ["scripts/browser-mcp-launcher.cjs"]
     }
   }
 }

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

@@ -10,22 +10,21 @@ Spec-driven pipeline. Read `.agents/orchestrator.yaml`. Details: skill `agent-or
 ## 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` |
+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`.
+
+| 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) |
 
 ## 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`.

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

@@ -9,4 +9,4 @@ If `.mcp.json` / `.amp/settings.json` lacks `memory`, or `MEMORY_FILE_PATH` is r
 
 Use `node scripts/memory-mcp-launcher.cjs` (no relative `MEMORY_FILE_PATH`). Shared file: `.cursor/memory.json` (gitignored). Do not delete other MCP servers.
 
-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.”
+Entities: `Change:<name>` (status, tasks n/m, last_role, review) · `Handoff:<name>` (next_role, next_command, session_count, summary, blocked) · `Decision:<topic>` (chosen, reason) — mirror of git-tracked `openspec/changes/<name>/decisions.md` (file → Memory only; never Memory → file). Writer: `npx agent-orchestrator-kit handoff <name>` (same command appends `decisions.md`). Notify once: “Memory MCP connected.”

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

@@ -1,28 +1,33 @@
 ---
-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
+# Session Handoff — canonical protocol (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.
+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.
 
-## Start (before specialist work)
-1. Honor pasted `/opsx:<phase> <name>`.
+Agents (local or cloud) write session artifacts only to git-tracked paths — never `/tmp`, never gitignored caches.
+
+## 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`)
-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`.
+3. `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). The CLI briefing is canonical — it already reads memory.json and handoff.md; accumulated decisions print from git-tracked `openspec/changes/<name>/decisions.md`, not from Memory. 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).
 
-## 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.
+## 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, Runtime.
+2. `npx agent-orchestrator-kit handoff <name>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, prints the expanded prompt on stdout). `decisions.md` is the git canon of change decisions; Memory `Decision:*` is a file→Memory mirror only. Cloud sessions pass `--runtime cloud` (or set `AOK_RUNTIME=cloud` / `AOK_AGENT_ID` in the cloud-agent environment).
+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.
+6. If runtime is cloud: after persist, `git add openspec/changes/<name>/` → `git commit` → `git push` → `npx agent-orchestrator-kit handoff <name> --cloud-check` (exit 0 required). Closing without this is an incomplete handoff. Persist prints these steps on stderr; the CLI never runs `git commit` / `git push`.
+7. Stop. Next role = new chat.
+
+## 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.
 
 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,13 +126,14 @@ 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
 
 **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. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`).
+3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Accumulated decisions print from git-tracked `openspec/changes/<name>/decisions.md`, not from Memory.
 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.
@@ -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 appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (the git canon), upserts Memory JSON with an absolute path (`Decision:*` is a file→Memory mirror only), 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:
 
@@ -194,6 +193,10 @@ After PR merged + CI green:
 - do not mix phases
 - conductor must spawn specialists
 
+## Runtime
+- runtime: <local | cloud>
+- agent_id: <id | none>
+
 ## Prompt
 
 The Prompt section is overwritten by `npx agent-orchestrator-kit handoff <name>`. Do not hand-write a thin stub.
@@ -213,9 +216,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) — this CLI appends `decisions.md` and mirrors `Decision:*` file→Memory; 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. Never write Memory back into `decisions.md`. 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. Write session artifacts only to git-tracked paths (never `/tmp`, never gitignored caches). If runtime is cloud: after persist, commit → push → `npx agent-orchestrator-kit handoff <name> --cloud-check` with exit 0; closing without that is an incomplete handoff.
 
 | 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**