agent-orchestrator-kit 0.1.14 → 0.3.0

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:

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,138 +2,36 @@
 
 > Powered by [agent-orchestrator-kit](https://github.com/makshc2/agent-orchestrator-kit) v{{KIT_VERSION}}
 
-This project uses a **spec-driven, role-separated AI pipeline** built on [OpenSpec](https://github.com/fission-ai/openspec).
-Every feature follows the same cycle regardless of stack or IDE.
-
-## Pipeline
+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
 ```
 
-`[design]` is optional — run `/opsx:design` when the change has UI and you need a durable design brief (Figma, screenshot, or photo). Skip for non-UI work; use `Design: none` in `proposal.md` when `require_design_brief: true`.
-
-Each phase runs in a **separate agent session** with a dedicated role, model hint, and permissions.
-Never mix phases in one chat — this is the single most important rule.
-
-The parent `/opsx:*` session is a **conductor**: it restores handoff state, spawns the required specialist, verifies the structured report, and never performs the specialist's work itself.
-
-## Roles
-
-| Role | Command | Mode | Model hint |
-|------|---------|------|------------|
-| Explorer | `/opsx:explore` | read-only | fast |
-| Design Intake | `/opsx:design <name>` | writes `design-brief.md` + `assets/` only | strong |
-| Architect | `/opsx:propose <name>` | conductor; `spec-architect` writes change artifacts | strong |
-| Spec Reviewer | `/opsx:review <name>` | conductor; `spec-reviewer` writes only `review.md` | medium/strong |
-| Implementer | `/opsx:apply <name>` | conductor; apply specialists write code/tests | strong |
-| Verifier | CI (automatic) | scripts only | — |
-
-## Conductor Routing
-
-| Phase / signal | Subagent |
-|----------------|----------|
-| Status, gate failure, next command | `openspec-guide` |
-| Session start restore / session exit persist | `session-handoff` |
-| Broken kit, MCP, or sync | `setup-doctor` |
-| `/opsx:explore` repository research | `codebase-explorer` |
-| `/opsx:design` | `design-intake` |
-| `/opsx:propose` | `spec-architect` |
-| `/opsx:review` | `spec-reviewer` |
-| Apply with design evidence | `design-implementer` |
-| Apply ordinary task | `code-writer` |
-| Apply tests | `test-writer` |
-| Apply pre-PR review | `code-reviewer` |
-| `/opsx:archive` | `spec-archiver` |
-
-This routing is mandatory and exclusive. `spec-reviewer` is not `code-reviewer`; only the conductor marks `tasks.md` after a verified `Status: done` report.
-
-Verifier runs on **GitHub Actions** (default) or **GitLab** via `prebuild` → `verify:openspec` when using `init --ci gitlab`. GitLab projects do not use `.github/workflows/`.
-
-With `init --ci gitlab --spec-verify` or `init --ci github --spec-verify`, an **AI Spec Verifier** also runs on MRs/PRs changing `src/`: an Amp agent checks the changed code against `openspec/specs/` and a **BLOCKED verdict fails the pipeline** (gate `spec-verify-blocking` in `.agents/orchestrator.yaml`).
-
-Both CI fragments also run `npx agent-orchestrator-kit gate-check` — a deterministic check that fails the pipeline when `src/` changed but the active change has no `review.md` with `Verdict: APPROVE` (when `require_spec_review: true`), and optionally requires `design-brief.md` (when `require_design_brief: true`, unless `proposal.md` has `Design: none`). At session start run `npx agent-orchestrator-kit status` (not a bare global binary — Amp PATH often lacks it; see `.agents/rules/cli-via-npm.mdc`).
-
-## Hard Rules
-
-- **One active change per developer** at a time.
-- **No apply without spec-review approval** (explicit Approve in chat).
-- **No code edits** during explore, design-intake, or spec-review sessions.
-- **Archive after every merge** (`/opsx:archive`).
-- **Always run local build/lint** before opening a PR.
-- **Conductor MUST spawn** the routed specialist and MUST NOT do specialist work in the parent session.
-
-## Handoff Gates
-
-| Transition | Gate |
-|------------|------|
-| explore → design | UI change needs a brief; change name chosen |
-| explore → propose | Decision brief written; change name chosen (skip design if non-UI) |
-| design → propose | `design-brief.md` (+ `assets/`) written |
-| propose → review | `npx openspec validate <name> --strict --type change` passes ✓ |
-| review → apply | Reviewer writes explicit **Approve** — enforced in CI by `gate-check` |
-| apply → verify | All `tasks.md` checkboxes `[x]`; local build OK |
-| verify → archive | CI green; PR merged — check `npx agent-orchestrator-kit status` for "ready to archive" |
-
-## Context to Pin per Role
-
-| Role | Attach (`@`) |
-|------|-------------|
-| Explorer | `@openspec/specs/` + relevant `@src/` subtree |
-| Design Intake | design source (Figma URL / images) + `@openspec/changes/<name>/` |
-| Architect | `@openspec/config.yaml` + explore brief (+ `@design-brief.md` if present) |
-| Reviewer | entire `@openspec/changes/<name>/` |
-| Implementer | `@openspec/changes/<name>/tasks.md` + `@openspec/changes/<name>/design-brief.md` |
-
-## Configuration
-
-See `.agents/orchestrator.yaml` for role config, pipeline flags, and MCP baseline.
-
-## Session Handoff
-
-**HARD STOP.** A `/opsx:*` session is incomplete without persist + the fenced next-thread prompt. Amp often skips Memory MCP and in-thread specialist work — use the CLI and isolated `subagent-*` spawns.
-
-At session start, before specialist work: honor the pasted `/opsx:*` command, run `npx agent-orchestrator-kit status`, run `npx agent-orchestrator-kit handoff --restore`, read Memory `Change:<name>`, `Handoff:<name>`, `Decision:*`, then fall back to `openspec/changes/<name>/handoff.md`. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). Then spawn the routed phase specialist (Amp: isolated wrapper, never the main thread).
-
-At exit, in order: spawn `session-handoff` persist → write `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0, upserts absolute-path Memory JSON) → paste the CLI stdout prompt as one fenced block. The prompt body uses `project.agent_language`, has no service banner, and MUST be self-contained (Done, Decisions, Blocked, attach, which subagent to spawn, HARD STOP). Never start the next phase in the current chat.
-
-OpenSpec artifacts remain the source of truth for requirements and tasks. Memory and `handoff.md` index the phase. The pasted prompt is the next thread's operating brief even if Memory is ignored.
-
-Memory MCP MUST use `node scripts/memory-mcp-launcher.cjs` (never a relative `MEMORY_FILE_PATH`). Run `npx agent-orchestrator-kit memory-setup` when the launcher is missing.
-
-### Optional: Figma personal token
-
-For design intake against private Figma files, each developer configures a local token (never commit, never paste into chat):
-
-```bash
-npx agent-orchestrator-kit figma-setup
-# edit .agents/figma.local.env → FIGMA_ACCESS_TOKEN=...
-npx agent-orchestrator-kit figma-status
-```
-
-MCP starts via `scripts/figma-mcp-launcher.cjs` (secret stays out of `.mcp.json`). See kit README → **Figma token**.
+`[design]` is optional (`/opsx:design`). Non-UI: `Design: none` in `proposal.md` when `require_design_brief: true`. MVP: `/opsx:quick` when `require_spec_review: false`.
 
-## Skills & Commands
+Routing table, HARD STOP, and CLI forms: `.agents/rules/` (`agent-orchestration`, `session-handoff`, `cli-via-npm`). Config: `.agents/orchestrator.yaml`.
 
-All skills live in `.agents/skills/` (committed to git).
-Local IDE sync: run `./scripts/sync-local-agent-skills.sh`.
+## Commands
+| Role | Command |
+|------|---------|
+| Explorer | `/opsx:explore` |
+| Design Intake | `/opsx:design <name>` |
+| Architect | `/opsx:propose <name>` |
+| Spec Reviewer | `/opsx:review <name>` |
+| Implementer | `/opsx:apply <name>` |
+| Quick (MVP) | `/opsx:quick <name>` |
+| Archive | `/opsx:archive` |
 
-| Skill | When |
-|-------|------|
-| `agent-orchestration` | Pipeline decisions, role selection, handoff |
-| `openspec-howto` | OpenSpec CLI, cycle, naming |
-| `openspec-propose` | Creating change artifacts |
-| `openspec-apply-change` | Implementing tasks |
-| `openspec-archive-change` | Archiving after merge |
+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.
 
-## Metrics (track per change)
+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.
 
-| Metric | Target |
-|--------|--------|
-| Sessions per change | 4–8 |
-| Apply iterations to PR | ≤ 2 |
-| Spec review loops | ≤ 1 |
-| Tasks rework after apply | ≤ 10% |
-| CI fails on PR | ≤ 1 |
+## Hard rules
+- One active change (unless mvp profile).
+- No apply without explicit Approve when `require_spec_review: true`.
+- No `src/` in explore, design, or review.
+- Archive after merge. Build/lint before PR.
+- Memory MCP: `node scripts/memory-mcp-launcher.cjs` (never relative `MEMORY_FILE_PATH`).
 
-If apply iterations > 2 — fix in Architect/Reviewer, not Implementer.
+Pin only the files for the current role (`tasks.md`, the change folder, relevant `src/` subtree) — not entire `openspec/specs/`.

package/templates/CLAUDE.md

@@ -1,77 +1,15 @@
 # {{PROJECT_NAME}} — Claude Code Context
 
-> agent-orchestrator-kit v{{KIT_VERSION}} | Spec-driven pipeline with OpenSpec
+> agent-orchestrator-kit v{{KIT_VERSION}} | OpenSpec pipeline
 
-## Project
-
-See `AGENTS.md` for the full orchestration pipeline, roles, and hard rules.
-See `openspec/config.yaml` for stack context and agent language.
-
-## Skills
-
-Project skills live in `.claude/skills/` (synced from `.agents/skills/`).
-Use `/skill-name` or let Claude auto-load based on context.
-
-| Skill | Command | When |
-|-------|---------|------|
-| Agent Orchestration | `/agent-orchestration` | Role selection, pipeline, handoff decisions |
-| OpenSpec Howto | `/openspec-howto` | CLI, cycle, naming |
-| OpenSpec Propose | `/openspec-propose` | Creating change artifacts |
-| OpenSpec Apply | `/openspec-apply-change` | Implementing tasks |
-| OpenSpec Archive | `/openspec-archive-change` | Archiving after merge |
-
-## Pipeline Commands
+See `AGENTS.md` and `.agents/rules/` for routing, HARD STOP, and CLI (`npx` only). Config: `.agents/orchestrator.yaml`.
 
 ```
-/opsx:explore   — think through ideas (read-only, no code)
-/opsx:design    — capture design into design-brief.md + assets/ (optional)
-/opsx:propose   — create change artifacts
-/opsx:review    — spec review (read-only, no code)
-/opsx:apply     — implement tasks
-/opsx:archive   — archive after merge
+/opsx:explore · /opsx:design · /opsx:propose · /opsx:review · /opsx:apply · /opsx:archive
 ```
 
-The parent command session is a conductor. It MUST spawn the phase specialist and MUST NOT perform specialist work itself:
-
-| Signal | Subagent |
-|--------|----------|
-| Status / next command | `openspec-guide` |
-| Session restore / persist / next-thread prompt | `session-handoff` |
-| Kit / MCP / sync failure | `setup-doctor` |
-| Explore research | `codebase-explorer` |
-| Design intake | `design-intake` |
-| Propose | `spec-architect` |
-| Spec review | `spec-reviewer` |
-| Apply UI / ordinary task / tests / pre-PR review | `design-implementer` / `code-writer` / `test-writer` / `code-reviewer` |
-| Archive | `spec-archiver` |
-
-## Key Rules for This Session
-
-- Check `.agents/orchestrator.yaml` for project-specific pipeline config.
-- One active change at a time — run `npx openspec list` / `npx agent-orchestrator-kit status` to confirm.
-- No code edits in explore, design, or review mode.
-- Design Intake writes only `design-brief.md` and `assets/` — never `src/`.
-- After completing apply: run build/lint before declaring done.
-- Only the conductor marks `tasks.md`, after a specialist reports `Status: done` and its files are verified.
-- Use `npx openspec validate --all --strict` or `npx openspec validate <name> --strict --type change`.
-- Never bare `openspec` / `agent-orchestrator-kit` without `npx` (Amp PATH → exit 127). See `.agents/rules/cli-via-npm.mdc`.
-
-## Session Handoff
-
-**HARD STOP.** Before work: `npx agent-orchestrator-kit handoff --restore`, then Memory `Change:<name>`, `Handoff:<name>`, `Decision:*`; if unavailable, `openspec/changes/<name>/handoff.md`. Spawn `session-handoff` restore when needed (Amp: isolated `subagent-session-handoff`). Spawn the phase specialist isolated — never in the Amp main thread.
-
-At exit: persist via `session-handoff` → `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste the full CLI stdout `/opsx:*` prompt. The prompt MUST be self-contained. Do not begin the next phase in the same chat.
-
-OpenSpec files are the requirements/tasks source of truth. Memory and `handoff.md` index phase state. The pasted prompt is the next thread's operating brief.
+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.
 
-## File Locations
+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.
 
-| What | Where |
-|------|-------|
-| Active changes | `openspec/changes/` |
-| Design brief | `openspec/changes/<name>/design-brief.md` + `assets/` |
-| Session handoff index | `openspec/changes/<name>/handoff.md` |
-| Specs (source of truth) | `openspec/specs/` |
-| Project config | `openspec/config.yaml` |
-| Orchestration config | `.agents/orchestrator.yaml` |
-| Skills | `.claude/skills/` |
+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