agent-orchestrator-kit 0.1.14 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Changed
+- **Context budget** — thinned always-apply rules and `AGENTS.md` / `CLAUDE.md`; details stay in on-demand skills. `figma-token-setup.mdc` is no longer `alwaysApply`. Restore spawn of `session-handoff` is skipped when `handoff --restore` already printed a briefing.
+
 ## [0.1.14] - 2026-08-13
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.14",
+  "version": "0.2.0",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, conductor subagents, durable session handoff CLI, and optional local Figma PAT setup",
   "keywords": [
     "ai-agent",

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

@@ -5,78 +5,31 @@ alwaysApply: true
 
 # Agent Orchestration Rules
 
-This project uses a spec-driven role pipeline. Read `.agents/orchestrator.yaml` for config.
-
-## Role Commands
-- `/opsx:explore` → read-only thinking, no code
-- `/opsx:design <name>` → writes only `design-brief.md` + `assets/` (optional design intake)
-- `/opsx:propose <name>` → creates `openspec/changes/<name>/` artifacts only
-- `/opsx:review <name>` → read-only spec review, writes `review.md`, outputs Approve or Request Changes
-- `/opsx:apply <name>` → writes `src/`, marks `tasks.md [x]` (blocked if no review when `require_spec_review: true`)
-- `/opsx:quick <name>` → MVP: propose + apply in one session (when `require_spec_review: false`)
-- `/opsx:archive` → merges delta specs, moves change to archive
-
-## Conductor Routing (Mandatory and Exclusive)
-
-The parent `/opsx:*` session is the conductor. For specialist work it MUST spawn the one subagent selected below with a self-contained prompt, MUST verify the structured report, and MUST NOT perform that specialist's work itself. One signal maps to one primary subagent; do not substitute a generic agent.
-
-| Phase / signal | MUST spawn | Specialist scope the conductor MUST NOT do |
-|----------------|------------|--------------------------------------------|
-| Status, gate failure, next command | `openspec-guide` | Pipeline diagnosis |
-| Session start restore / session exit persist | `session-handoff` | Memory, `handoff.md`, next-thread prompt |
-| Broken kit, MCP, or generated-file sync | `setup-doctor` | Kit setup repair |
-| `/opsx:explore` repository investigation | `codebase-explorer` | Repository research; no specs or code |
-| `/opsx:design` | `design-intake` | `design-brief.md` and `assets/` |
-| `/opsx:propose` | `spec-architect` | Change proposal/design/specs/tasks |
-| `/opsx:review` | `spec-reviewer` | Pre-apply spec verdict and `review.md` |
-| Apply task with design brief/Figma/image | `design-implementer` | UI implementation |
-| Apply ordinary implementation task | `code-writer` | One task's production code |
-| Apply after implementation | `test-writer` | Automated tests |
-| Apply before PR/MR | `code-reviewer` | Post-implementation spec review |
-| `/opsx:archive` | `spec-archiver` | Delta merge and archive move |
-
-`spec-reviewer` is never interchangeable with `code-reviewer`. During apply, only the conductor may mark a `tasks.md` checkbox, and only after a subagent reports `Status: done` and the conductor verifies the reported files.
-
-## Session Start Protocol (Before Any Specialist Work)
-
-1. Honor the pasted `/opsx:<phase> <name>` command and announce that role.
-2. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`; resolve the active change without exceeding `max_active_changes`.
-3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Use the printed briefing.
-4. Read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works.
-5. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`. Memory failure alone MUST NOT block the session when the file exists.
-6. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`, never the main thread).
-7. Only after context is restored, spawn the routed phase specialist. Amp MUST spawn `subagent-<name>` isolated.
-
-If the user says “continue” / “next” / «продовжуй» / «далі» without a command and exactly one active change has `Handoff.next_command` (from Memory, CLI restore, or `handoff.md`), execute that command instead of asking which phase to run.
-
-Follow `.agents/rules/session-handoff.mdc`.
-
-## Session Exit Protocol (HARD STOP)
-
-A phase is not closed until the conductor performs these steps in order. FORBIDDEN: saying done/готово, starting the next phase, or omitting the fenced prompt.
-
-1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
-2. Write `openspec/changes/<name>/handoff.md` with sections **Closed role**, **Change**, **Done**, **Decisions**, **Blocked**, **Next command**, **Next role**, **Attach**, **Subagents to spawn**, and **Constraints**. Do this even if Memory MCP is unavailable.
-3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts `.cursor/memory.json` with an absolute path and prints the expanded self-contained next-session prompt on stdout.
-4. If Memory MCP tools work, also update `Change:<name>` (`status`, `tasks n/m`, `last_role`, `review`), `Handoff:<name>` (`next_role`, `next_command`, `session_count`, `summary`, `blocked`), and each new `Decision:<topic>` (`chosen`, `reason`).
-5. Paste the CLI stdout as one fenced copy/paste prompt. First line MUST be `/opsx:<next> <name>`; body MUST use `project.agent_language`; MUST keep Done/Decisions/Blocked/spawn/HARD STOP complete. Do not add a banner or shorten the prompt. Amp often skips Memory MCP — the pasted prompt is the next thread's operating brief.
-6. Do NOT start the next phase in this chat.
-
-## Session Rules
-- One active change at a time (unless mvp profile: up to 3)
-- Each role = new chat session (except `/opsx:quick` combines propose+apply)
-- No code in explore, design, or review sessions
-- Design Intake may write only `openspec/changes/<name>/design-brief.md` and `assets/`
-- No apply without review when `pipeline.require_spec_review: true` — check `review.md` or Approve in context
-- When `require_design_brief: true` and the change touches UI — need `design-brief.md`, or `Design: none` in `proposal.md` for non-UI
-- Apply uses the design brief, not live Figma MCP
-- After apply: build + lint before PR
-- After merge: run `/opsx:archive` (when `archive_after_merge: true`)
-- CLI: `npx agent-orchestrator-kit status`, `npx openspec …` — never bare globals (see `cli-via-npm.mdc`)
-
-## Never
-- Mix propose and apply in one session
-- Edit `src/` during explore, design, or review
-- Skip spec review before apply
-- Call live Figma MCP during apply when a design brief exists
-- Leave changes un-archived after merge
+Spec-driven pipeline. Read `.agents/orchestrator.yaml`. Details: skill `agent-orchestration`. Handoff: `.agents/rules/session-handoff.mdc`. CLI: `npx` only (`.agents/rules/cli-via-npm.mdc`).
+
+## 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` |
+
+## 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`.
+
+Exit HARD STOP: persist via `session-handoff` → `handoff.md` → `npx agent-orchestrator-kit handoff <name>` (exit 0) → paste CLI stdout as one fenced `/opsx:*` prompt. Do not start the next phase here.
+
+Never mix propose+apply (except `/opsx:quick`). No `src/` in explore/design/review. Skip live Figma during apply when a brief exists.

package/templates/.agents/rules/figma-token-setup.mdc

@@ -1,6 +1,6 @@
 ---
 description: Figma personal access token setup — local env file, never ask for token in chat
-alwaysApply: true
+alwaysApply: false
 ---
 
 # Figma Token Setup

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

@@ -3,73 +3,10 @@ description: Memory MCP auto-setup for Cursor and Amp
 alwaysApply: true
 ---
 
-# Memory MCP Auto-Setup
+# Memory MCP
 
-At session start: check `.mcp.json` (Cursor) and `.amp/settings.json` (Amp).
-If `memory` MCP is absent or uses a **relative** `MEMORY_FILE_PATH` — run `npx agent-orchestrator-kit memory-setup` silently.
+If `.mcp.json` / `.amp/settings.json` lacks `memory`, or `MEMORY_FILE_PATH` is relative: run `npx agent-orchestrator-kit memory-setup`. Relative paths resolve inside npx `dist/` and look like “memory ignored”.
 
-Shared memory file: `.cursor/memory.json` (same path for Cursor and Amp).
+Use `node scripts/memory-mcp-launcher.cjs` (no relative `MEMORY_FILE_PATH`). Shared file: `.cursor/memory.json` (gitignored). Do not delete other MCP servers.
 
-**CRITICAL:** never set `MEMORY_FILE_PATH` to a relative path. Relative `.cursor/memory.json` resolves inside npx `dist/` — Amp then reads the wrong graph (looks like "memory ignored"). Always start Memory via `node scripts/memory-mcp-launcher.cjs`, which injects an absolute path.
-
-## Cursor (.mcp.json)
-
-```json
-"memory": {
-  "command": "node",
-  "args": ["scripts/memory-mcp-launcher.cjs"]
-}
-```
-
-## Amp (.amp/settings.json)
-
-```json
-"amp.mcpServers": {
-  "memory": {
-    "command": "node",
-    "args": ["scripts/memory-mcp-launcher.cjs"]
-  }
-}
-```
-
-If Amp CLI is available and memory is missing:
-
-```bash
-npx agent-orchestrator-kit memory-setup
-```
-
-Do not run `amp mcp add` with a relative `MEMORY_FILE_PATH`.
-
-## .gitignore
-
-Ensure present (do not duplicate):
-```
-.cursor/memory.json
-.amp/settings.json
-```
-
-## Memory Entity Format
-
-Use these keys and fields for orchestration state:
-
-| Key | Required fields |
-|-----|-----------------|
-| `Change:<name>` | `status`, `tasks n/m`, `last_role`, `review` |
-| `Handoff:<name>` | `next_role`, `next_command`, `session_count`, `summary`, `blocked` |
-| `Decision:<topic>` | `chosen`, `reason` |
-| `Convention:<area>` | project-specific rules |
-
-The deterministic writer is `npx agent-orchestrator-kit handoff <name>` — it upserts `.cursor/memory.json` even when MCP tools are ignored. Also call Memory MCP create/update when tools work.
-
-## Session Lifecycle
-
-At the start of every `/opsx:*` role session, after resolving the change and before specialist work: `npx agent-orchestrator-kit handoff --restore`, then read `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory MCP is unavailable or those entities are empty, read `openspec/changes/<name>/handoff.md` and continue; Memory failure is not a blocker.
-
-At session exit, spawn `session-handoff` (Amp: isolated `subagent-session-handoff`), write `handoff.md`, then run `npx agent-orchestrator-kit handoff <name>` (exit 0 required). Paste the CLI stdout prompt complete. Only after that attempt Memory MCP updates. You are not done without the fenced prompt.
-
-## Rules
-- Do not overwrite existing correct launcher config
-- Do not delete other MCP servers
-- Notify once: "Memory MCP connected."
-- Never treat unavailable Memory MCP as a reason to skip `handoff.md` or the CLI
-- Never leave a relative `MEMORY_FILE_PATH` in Cursor or Amp config
+Entities: `Change:<name>` (status, tasks n/m, last_role, review) · `Handoff:<name>` (next_role, next_command, session_count, summary, blocked) · `Decision:<topic>` (chosen, reason). Writer: `npx agent-orchestrator-kit handoff <name>`. Notify once: “Memory MCP connected.”

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

@@ -3,44 +3,26 @@ description: Mandatory session restore, Memory persist, subagent spawn, and next
 alwaysApply: true
 ---
 
-# Session Handoff — HARD STOP (Amp / Cursor / Claude)
-
-This rule overrides convenience. A `/opsx:*` session that skips these steps is incomplete.
-
-Amp ignores soft reminders. Treat every MUST below as a gate. If a spawn tool exists, use it. If it does not, run the CLI yourself. Never skip persist because “the user already knows”.
-
-## You are not done
-
-FORBIDDEN until persist succeeds: saying done / готово, starting the next phase, or omitting the fenced next-thread prompt.
-
-## Session start (before any specialist work)
-
-1. Honor the pasted `/opsx:<phase> <name>` command and announce that role.
-2. Run `npx agent-orchestrator-kit status`.
-3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Use the printed briefing.
-4. Read Memory `Change:<name>`, `Handoff:<name>`, `Decision:*` when MCP works.
-5. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`. Memory failure is not a blocker when the file exists.
-6. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`, never the main thread).
-7. Spawn the routed phase specialist from `.agents/rules/agent-orchestration.mdc`. Amp: isolated `subagent-<name>`. Executing specialist work in the parent thread is a protocol violation.
-8. Free-form “continue” / “next” / «продовжуй» / «далі» with one active change → execute `Handoff.next_command`. Do not ask which phase.
-
-## Session exit (mandatory order)
-
-1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, do the persist steps in the parent — never skip.
-2. Write `openspec/changes/<name>/handoff.md` with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
-3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts `.cursor/memory.json` with an absolute path and prints the expanded prompt on stdout.
-4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, `Decision:*` to match.
-5. Paste the CLI stdout into chat as one fenced block. Keep it complete. No `NEXT_SESSION_PROMPT` banner. First line is `/opsx:…`. Body uses `project.agent_language`.
-6. Stop. The next role starts in a **new** chat with that pasted prompt.
-
-## Next-thread prompt must be self-contained
-
-The prompt is the next thread’s operating brief. It MUST include: role, change name, language, hard constraints, start checklist, which subagent to spawn (including Amp isolated wrapper name), full Done / Decisions / Blocked / tasks / review / attach, and the exit HARD STOP. Do not emit a thin “read Memory” stub. Amp often skips Memory MCP; the pasted prompt must still be enough to work.
-
-## Memory path
-
-Never configure Memory MCP with a relative `MEMORY_FILE_PATH`. Relative `.cursor/memory.json` resolves inside npx `dist/` and looks like “memory ignored”. Use `node scripts/memory-mcp-launcher.cjs` (Cursor `.mcp.json` and Amp `.amp/settings.json`). Run `npx agent-orchestrator-kit memory-setup` when the launcher is missing or the path is relative.
-
-## Amp isolation
-
-Every `subagent-*` skill MUST be spawned as an isolated subagent with fresh context. Running the wrapper body in the main Amp thread is a protocol violation. If spawn is unavailable, STOP and report blocked — do not impersonate the specialist.
+# Session Handoff — 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.
+
+## Start (before specialist work)
+1. Honor pasted `/opsx:<phase> <name>`.
+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`.
+
+## 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.
+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.
+
+Memory MCP: launcher `node scripts/memory-mcp-launcher.cjs`, never a relative `MEMORY_FILE_PATH`.

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

@@ -136,7 +136,7 @@ After PR merged + CI green:
 3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`).
 4. Read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works.
 5. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; Memory failure alone is not a blocker.
-6. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`).
+6. Spawn `session-handoff` in restore mode **only if** `handoff --restore` failed or printed no briefing (Amp: isolated `subagent-session-handoff`). Skip this spawn when CLI restore exits 0.
 7. Only after restoration, spawn the routed phase specialist. If the user said “continue” / “next” and exactly one active change has `Handoff.next_command`, execute it instead of asking for a phase.
 
 **During session:**

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**. The parent `/opsx:*` session is a **conductor**: restore, spawn the specialist, verify the report — never do specialist work in-thread.
 
 ```
 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 |
+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>`).
 
-## Metrics (track per change)
+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.
 
-| 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.
+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.
 
-## File Locations
+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.
 
-| 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/`).