agent-orchestrator-kit 0.2.0 → 0.3.0

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

@@ -1,6 +1,6 @@
 ---
 name: spec-archiver
-description: OpenSpec completion specialist. ALWAYS use for /opsx:archive after merge/verification to merge delta specs and archive the completed change. Do NOT use to implement features, alter product behavior, or archive incomplete work.
+description: OpenSpec completion fallback. Use ONLY when the `agent-orchestrator-kit archive` CLI is unavailable or failed for environmental reasons — /opsx:archive normally runs `npx agent-orchestrator-kit archive <name>` directly with no subagent. Do NOT use to implement features, alter product behavior, or archive incomplete work.
 ---
 
 You finalize one completed OpenSpec change. Your writable scope is the affected `openspec/specs/` capabilities and the archive move under `openspec/changes/archive/`.

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

@@ -3,29 +3,33 @@ name: spec-reviewer
 description: Pre-implementation OpenSpec gate reviewer. ALWAYS use for /opsx:review to assess proposal/design/specs/tasks and write review.md. Do NOT use for post-implementation code review, edit src/, or change tasks.md.
 ---
 
-You review one OpenSpec change before apply. You are read-only except for `openspec/changes/<name>/review.md`.
+You are Tier 2 of a two-tier review: you run only after `npx agent-orchestrator-kit gate-check --review <name>` passed. You review one OpenSpec change before apply. You are read-only except for `openspec/changes/<name>/review.md` and, on APPROVE, `openspec/changes/<name>/apply-notes.md`.
 
 Workflow:
 
 1. Read the complete change directory, relevant main specs, `openspec/config.yaml`, and repository paths referenced by the artifacts.
-2. Check proposal → design → delta specs → tasks traceability, scope consistency, testability, migration impact, and compliance with project gates.
-3. Run `npx openspec validate <name> --strict --type change` and record its actual result.
-4. Write `review.md` with findings ordered by severity and exactly one verdict: `APPROVE` or `REQUEST CHANGES`.
-5. Approve only when artifacts are implementable without material guessing and strict validation passes.
+2. Apply the LLM-only checklist — do NOT re-check what Tier 1 covered (strict validation, contract field presence, proposal sections, delta-spec section structure):
+   - proposal ↔ design ↔ tasks consistency (no contradictions or drift);
+   - conflicts with existing `openspec/specs/` requirements;
+   - scope creep vs proposal Non-goals;
+   - task self-sufficiency: a blind implementer can execute each task from Files/Do/Done-when alone, without design.md.
+3. Write `review.md` with findings ordered by severity and exactly one verdict: `APPROVE` or `REQUEST CHANGES`.
+4. On APPROVE, also write `apply-notes.md` (≤ 20 lines): critical constraints, pitfalls, what NOT to touch, verification commands. It is the second and last file you may write.
+5. Approve only when artifacts are implementable without material guessing.
 
 Rules:
 
 - Do NOT edit `src/`, tests, proposal/design/spec files, or `tasks.md`.
 - Do NOT implement fixes found during review.
 - Do NOT substitute for `code-reviewer`; that agent reviews the implementation diff after apply.
-- Do NOT approve based only on validation syntax; verify semantics and repository references.
+- Do NOT approve based only on Tier 1 passing; verify semantics and repository references.
 
 Return exactly this report contract:
 
 ```
 ## Subagent report: spec-reviewer
 **Status:** done | blocked
-**Files:** review.md
+**Files:** review.md (+ apply-notes.md on APPROVE)
 **Done:** verdict and validation result
 **Blocked:** missing artifacts or none
 **Risks:** non-blocking review notes or none

package/templates/AGENTS.md

@@ -2,7 +2,7 @@
 
 > Powered by [agent-orchestrator-kit](https://github.com/makshc2/agent-orchestrator-kit) v{{KIT_VERSION}}
 
-Spec-driven OpenSpec pipeline. Each phase is a **separate chat**. The parent `/opsx:*` session is a **conductor**: restore, spawn the specialist, verify the report — never do specialist work in-thread.
+Spec-driven OpenSpec pipeline. Each phase is a **separate chat**. Delegation is differentiated (lean model): explore/design/propose/review spawn a mandatory specialist; **apply is parent-driven** — the parent implements from `tasks.md` + `apply-notes.md`, subagents are optional (≥ 2 independent tasks or explicit request; `design-implementer` for design-brief/Figma); **archive is a CLI** (`npx agent-orchestrator-kit archive <name> [--sync]`), no subagent.
 
 ```
 explore → [design] → propose → review → apply → verify → archive
@@ -23,9 +23,9 @@ Routing table, HARD STOP, and CLI forms: `.agents/rules/` (`agent-orchestration`
 | Quick (MVP) | `/opsx:quick <name>` |
 | Archive | `/opsx:archive` |
 
-Start: `npx agent-orchestrator-kit status` then `handoff --restore`. Spawn `session-handoff` restore only if that CLI failed. Then spawn the routed specialist (Amp: isolated `subagent-<name>`).
+Session Start / Exit are **parent-driven** — canonical protocol in `.agents/rules/session-handoff.mdc`. Start: `status` → `handoff --restore` → `handoff.md` fallback. Exit HARD STOP: parent writes `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste the CLI `/opsx:*` prompt. `session-handoff` subagent = fallback only. Do not start the next phase here.
 
-Exit HARD STOP: persist `session-handoff` → `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste the CLI `/opsx:*` prompt. Do not start the next phase here.
+Quality gates: `gate-check --tasks <name>` lints the task contract (Files/Do/Done-when, `pipeline.task_contract: warn|strict|off`); `gate-check --review <name>` is deterministic Tier 1 of review — spec-reviewer (Tier 2) is spawned only after it passes and writes `apply-notes.md` on APPROVE.
 
 ## Hard rules
 - One active change (unless mvp profile).

package/templates/CLAUDE.md

@@ -8,8 +8,8 @@ See `AGENTS.md` and `.agents/rules/` for routing, HARD STOP, and CLI (`npx` only
 /opsx:explore · /opsx:design · /opsx:propose · /opsx:review · /opsx:apply · /opsx:archive
 ```
 
-Conductor session: restore with `npx agent-orchestrator-kit handoff --restore`, spawn the phase specialist, do not do specialist work here. Spawn `session-handoff` restore only if CLI restore failed.
+Lean delegation: explore/design/propose/review spawn a mandatory specialist; apply is parent-driven from `tasks.md` + `apply-notes.md` (subagents optional for independent tasks); archive runs `npx agent-orchestrator-kit archive <name> [--sync]` — no subagent. Review is two-tiered: `gate-check --review` (deterministic) before `spec-reviewer`; `gate-check --tasks` lints the Files/Do/Done-when task contract.
 
-Exit: persist → `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste the CLI prompt. Do not start the next phase in this chat.
+Session Start/Exit are parent-driven (canonical: `.agents/rules/session-handoff.mdc`): restore with `npx agent-orchestrator-kit handoff --restore`; exit — write `handoff.md`, run `npx agent-orchestrator-kit handoff <name>` (exit 0), paste the CLI prompt. `session-handoff` subagent is a fallback only. Do not start the next phase in this chat.
 
 One active change. No `src/` in explore/design/review. After apply: build/lint. Skills: `.claude/skills/` (synced from `.agents/skills/`).

package/templates/orchestrator.yaml

@@ -12,6 +12,7 @@ pipeline:
   require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
+  task_contract: warn
 
 roles:
   explorer:
@@ -50,7 +51,7 @@ handoff:
   persist_on_exit: true
   emit_next_session_prompt: true
   prompt_self_contained: true
-  spawn_handoff_subagent: true
+  spawn_handoff_subagent: false
 
 memory:
   enabled: true