agent-orchestrator-kit 0.2.0 → 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

@@ -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/session-handoff.mdc

@@ -1,28 +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
+# 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>`.
+## 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; 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.
+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.
 
+## 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,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
 
@@ -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**
 

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

@@ -9,115 +9,28 @@ metadata:
   generatedBy: "1.4.1"
 ---
 
-Archive a completed change in the experimental workflow.
+Archive a completed change. The phase is fully deterministic — one CLI call, no phase subagents.
 
-**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:** after resolving the change and confirming archive gates, spawn `spec-archiver` with a self-contained prompt. The parent MUST NOT compare/merge main specs or move the change itself; it only verifies the structured report, archive path, and validation result.
+**Input**: Optionally specify a change name. If omitted or ambiguous, run `npx openspec list --json` and use the **AskUserQuestion tool** to let the user pick an active change. Never guess or auto-select.
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
-
-   Run `npx openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show only active changes (not already archived).
-   Include the schema used for each change if available.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check artifact completion status**
-
-   Run `npx openspec status --change "<name>" --json` to check artifact completion.
-
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used
-   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
-   - `artifacts`: List of artifacts with their status (`done` or other)
-
-   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
-
-   **If any artifacts are not `done`:**
-   - Display warning listing incomplete artifacts
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
-   - Proceed if user confirms
-
-3. **Check task completion status**
-
-   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
-
-   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
-
-   **If incomplete tasks found:**
-   - Display warning showing count of incomplete tasks
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
-   - Proceed if user confirms
-
-   **If no tasks file exists:** Proceed without task-related warning.
-
-4. **Assess delta spec sync state**
+1. **Resolve the change name** (see Input above).
 
-   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.
+2. **Decide on delta-spec sync.** If the change has delta specs, ask the user: merge them into main specs (`--sync`, recommended) or archive without merging (`--no-sync --force`).
 
-   **If delta specs exist:**
-   - 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"
-
-   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**
-
-   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
-   mkdir -p "<planningHome.changesDir>/archive"
-   ```
-
-   Generate target name using current date: `YYYY-MM-DD-<change-name>`
-
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move `changeRoot` to the archive directory
+3. **Run the CLI:**
 
    ```bash
-   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
+   npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
    ```
 
-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
-   - Schema that was used
-   - Archive location
-   - Whether specs were synced (if applicable)
-   - Note about any warnings (incomplete artifacts/tasks)
-
-**Output On Success**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
-**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+   The CLI checks gates (review APPROVE when `require_spec_review: true`, all tasks `[x]`, no existing target archive), merges delta specs on `--sync` (ADDED append, MODIFIED replace, REMOVED delete), moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>`, runs `npx openspec validate --all --strict` with full rollback on failure, and writes the final `handoff.md` (`next_command: none`) plus memory upsert.
 
-All artifacts complete. All tasks complete.
-```
+4. **Show the CLI stdout as-is.** On exit ≠ 0, report the failed gate from stderr and stop.
 
 **Guardrails**
-- Always prompt for change selection if not provided
-- Use artifact graph (openspec status --json) for completion checking
-- Don't block archive on warnings - just inform and confirm
-- Preserve .openspec.yaml when moving to archive (it moves with the directory)
-- Show clear summary of what happened
-- If sync is requested, use openspec-sync-specs approach (agent-driven)
-- If delta specs exist, always run the sync assessment and show the combined summary before prompting
+- Do NOT merge main specs, move the change, or edit anything manually — the CLI owns the whole operation.
+- Spawn `spec-archiver` ONLY as a fallback when the `agent-orchestrator-kit archive` CLI is unavailable or failed for environmental reasons (not for unmet gates).
+- On a sync conflict reported by the CLI, use the `openspec-sync-specs` skill to resolve it, then re-run `archive`.
+- The pipeline ends here: no next-thread prompt is required after a successful archive.

package/templates/.agents/skills/openspec-propose/SKILL.md

@@ -24,6 +24,17 @@ When ready to implement, run /opsx:apply
 
 **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 paths, run status, and run strict validation.
 
+**Task contract (mandatory tasks.md format):** every task must carry indented `Files:`, `Do:`, `Done-when:` fields:
+
+```markdown
+- [ ] 2.1 Short title
+  Files: src/router/index.js, new file: src/stores/auth.js
+  Do: concrete change in 1–3 lines — no vague wording ("as needed", "if necessary", "as appropriate")
+  Done-when: verifiable condition or command
+```
+
+Each task must be self-contained for a blind implementer — executable without reading design.md. `Files:` paths must exist unless prefixed with `new file:`. Lint: `npx agent-orchestrator-kit gate-check --tasks <name>` (mode via `pipeline.task_contract: warn|strict|off`).
+
 **Steps**
 
 1. **If no clear input provided, ask what they want to build**

package/templates/.agents/subagents/session-handoff.md

@@ -1,15 +1,15 @@
 ---
 name: session-handoff
-description: ALWAYS use at the start of every /opsx:* session to restore Memory and handoff.md, and at session exit to persist Memory, write handoff.md, run `npx agent-orchestrator-kit handoff`, and emit the expanded next-thread prompt. Do NOT use to write src/, specs, review.md, or to perform the phase specialist's work.
+description: FALLBACK ONLY — use when the parent-driven protocol in `.agents/rules/session-handoff.mdc` fails. Restore mode when both `npx agent-orchestrator-kit handoff --restore` and reading handoff.md failed; persist mode when `npx agent-orchestrator-kit handoff <name>` failed after the parent wrote handoff.md. Never a routine step. Do NOT use to write src/, specs, review.md, or to perform the phase specialist's work.
 ---
 
-You are the session-boundary specialist. You restore or persist orchestration state. You do not implement features, write specs, or review code.
+You are the session-boundary fallback specialist. The routine Session Start / Session Exit protocol is parent-driven (see `.agents/rules/session-handoff.mdc`); you run only when that protocol failed. You restore or persist orchestration state. You do not implement features, write specs, or review code.
 
-The parent is the conductor. Amp MUST spawn this skill as an isolated subagent (`subagent-session-handoff`) with fresh context and MUST NOT execute this body in the main thread.
+When spawned, Amp runs this skill as an isolated subagent (`subagent-session-handoff`) with fresh context — never as the main thread body.
 
 ## Restore mode
 
-Use when the conductor says restore / session start.
+Use when the parent's restore failed (CLI restore and handoff.md both unavailable).
 
 1. Run `npx agent-orchestrator-kit status`.
 2. Run `npx agent-orchestrator-kit handoff --restore` (add `<name>` when known).
@@ -19,7 +19,7 @@ Use when the conductor says restore / session start.
 
 ## Persist mode
 
-Use when the conductor says persist / session exit. A session is not closed until this mode succeeds.
+Use when the parent's persist failed (`npx agent-orchestrator-kit handoff <name>` did not exit 0). A session is not closed until persist succeeds.
 
 1. Write or update `openspec/changes/<name>/handoff.md` with every required section: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
 2. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. This upserts `.cursor/memory.json` using an absolute path and prints the expanded next-session prompt on stdout.

package/templates/.agents/subagents/spec-architect.md

@@ -10,7 +10,7 @@ Workflow:
 1. Read `openspec/config.yaml`, existing main specs, the exploration decision brief, and `design-brief.md` when present.
 2. Create or update `proposal.md`, `design.md`, `specs/<capability>/spec.md`, and `tasks.md` using the repository's OpenSpec schema and conventions.
 3. Keep requirements testable: each requirement uses SHALL/MUST language and includes concrete scenarios.
-4. Make tasks ordered, independently verifiable, and traceable to the design and delta specs.
+4. Make tasks ordered, independently verifiable, and traceable to the design and delta specs. Every task MUST follow the task contract: indented `Files:` (existing paths, or `new file:` prefix for new ones), `Do:` (concrete change, no vague wording like "as needed" / "if necessary" / "as appropriate"), and `Done-when:` (verifiable condition or command). Each task must be self-contained for a blind implementer without reading design.md.
 5. Report which validation command the conductor should run; do not cross into review or implementation.
 
 Rules: