agent-orchestrator-kit 0.1.12 → 0.1.14

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

@@ -6,15 +6,18 @@ alwaysApply: true
 # Memory MCP Auto-Setup
 
 At session start: check `.mcp.json` (Cursor) and `.amp/settings.json` (Amp).
-If `memory` MCP is absent — add it silently.
+If `memory` MCP is absent or uses a **relative** `MEMORY_FILE_PATH` — run `npx agent-orchestrator-kit memory-setup` silently.
+
+Shared memory file: `.cursor/memory.json` (same path for Cursor and Amp).
+
+**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": "npx",
-  "args": ["-y", "@modelcontextprotocol/server-memory"],
-  "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+  "command": "node",
+  "args": ["scripts/memory-mcp-launcher.cjs"]
 }
 ```
 
@@ -23,13 +26,20 @@ If `memory` MCP is absent — add it silently.
 ```json
 "amp.mcpServers": {
   "memory": {
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-memory"],
-    "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+    "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):
@@ -40,16 +50,26 @@ Ensure present (do not duplicate):
 
 ## Memory Entity Format
 
-Use these keys for orchestration state:
+Use these keys and fields for orchestration state:
 
-| Key | Value |
-|-----|-------|
-| `Change:<name>` | status, task progress |
-| `Decision:<topic>` | chosen option + rationale |
+| 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 |
-| `Handoff:<name>` | next role, session count |
+
+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 config
+- 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

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

@@ -0,0 +1,46 @@
+---
+description: Mandatory session restore, Memory persist, subagent spawn, and next-thread prompt
+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.

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

@@ -42,6 +42,27 @@ 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.
+
 ## Handoff Protocol
 
 ### explore → design (optional)
@@ -110,19 +131,73 @@ After PR merged + CI green:
 ## Session Rules
 
 **Start of each session:**
-1. Announce role: "Starting Spec Reviewer session for change: <name>"
-2. Run `npx agent-orchestrator-kit status` (or `npx openspec list`) — confirm active change limit (`max_active_changes` in orchestrator.yaml) and see task/review/brief progress for every active change at a glance
-3. Read `orchestrator.yaml` for project config and review gate
+1. Honor the pasted `/opsx:<phase> <name>` command and announce that role.
+2. Run `npx agent-orchestrator-kit status` (or `npx openspec list --json`) and read `orchestrator.yaml`; resolve the active change and gates.
+3. Run `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`).
+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`).
+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:**
 - Stay in role — do not drift into next phase
 - Pause and ask if requirements are unclear
 - Never edit files outside your role's allowed output
 
-**End of each session:**
-- Show progress summary
-- State explicit next step and next role
-- If apply: confirm build/lint status
+**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.
+
+`handoff.md` template:
+
+````markdown
+# Session Handoff
+
+## Closed role
+<role and completion status>
+
+## Change
+- name: <name>
+- status: <proposed | spec-approved | applying | blocked>
+- tasks: <n/m>
+- review: <pending | APPROVE | REQUEST_CHANGES | none>
+- last_role: <role>
+
+## Done
+<full persisted summary the next thread needs>
+
+## Decisions
+- <topic>: <chosen> — <reason>
+
+## Blocked
+<blocker or none>
+
+## Next command
+`/opsx:<next> <name>`
+
+## Next role
+<role or subagent name>
+
+## Attach
+- `openspec/changes/<name>/<artifact>`
+
+## Subagents to spawn
+- `<phase-specialist>` — <signal> (Amp: isolated `subagent-<name>`)
+- `session-handoff` — restore at start, persist at exit (Amp: isolated `subagent-session-handoff`)
+
+## Constraints
+- language: <project.agent_language>
+- do not mix phases
+- conductor must spawn specialists
+
+## Prompt
+
+The Prompt section is overwritten by `npx agent-orchestrator-kit handoff <name>`. Do not hand-write a thin stub.
+````
 
 ## Model Selection Guide
 
@@ -136,18 +211,17 @@ After PR merged + CI green:
 | apply simple | 1–2 file change | medium or fast |
 | fix lint | Mechanical | fast |
 
-## Memory MCP Entities
+## Mandatory Memory and Handoff Protocol
 
-Store these between sessions (key → value):
+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.
 
-| Key | Example value |
-|-----|---------------|
-| `Change:<name>` | `status: spec-approved, tasks: 3/7` |
-| `Decision:<topic>` | `chosen: xlsx over csv, reason: ...` |
-| `Convention:<area>` | `api errors: use ApiError class` |
-| `Handoff:<name>` | `next_role: implementer, session_count: 2` |
+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.
 
-At start of new session: read relevant entities to restore context without re-explanation.
+| Entity | 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` |
 
 ## Orchestration Checklist (per change)
 
@@ -169,7 +243,7 @@ At start of new session: read relevant entities to restore context without re-ex
 | All tasks in one apply session | Context overload; model drifts |
 | No archive after merge | Next propose has stale domain specs |
 | Strong model on lint fixes | 5–10x cost with no quality gain |
-| Skip Memory MCP | Every session re-explains domain |
+| Skip Memory MCP / skip `handoff` CLI | Next thread has no context; Amp looks like it “ignored the rules” |
 
 ## Metrics (health check per change)
 

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

@@ -13,6 +13,8 @@ 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.
+
 **Steps**
 
 1. **Select the change**
@@ -71,9 +73,10 @@ Implement tasks from an OpenSpec change.
 
    For each pending task:
    - Show which task is being worked on
-   - Make the code changes required
-   - Keep changes minimal and focused
-   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - 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]`
    - Continue to next task
 
    **Pause if:**
@@ -147,7 +150,7 @@ What would you like to do?
 - 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
-- Update task checkbox immediately after completing 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
 

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

@@ -13,6 +13,8 @@ Archive a completed change in the experimental workflow.
 
 **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.
+
 **Steps**
 
 1. **If no change name provided, prompt for selection**
@@ -55,20 +57,22 @@ Archive a completed change in the experimental workflow.
 
 4. **Assess delta spec sync state**
 
-   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
+   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.
 
    **If delta specs exist:**
-   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
-   - Determine what changes would be applied (adds, modifications, removals, renames)
-   - Show a combined summary before prompting
+   - 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"
 
-   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+   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**
 
-5. **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
@@ -85,7 +89,9 @@ Archive a completed change in the experimental workflow.
    mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    ```
 
-6. **Display summary**
+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

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

@@ -11,7 +11,9 @@ metadata:
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+**IMPORTANT: Explore mode is read-only thinking, not implementation or artifact authoring.** You must NEVER write code or OpenSpec artifacts.
+
+**Conductor delegation is mandatory:** for repository investigation, spawn `codebase-explorer` with a self-contained question and require its structured report. Do not search or trace the codebase in the parent session; synthesize the report into the conversation.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
@@ -277,7 +279,7 @@ But this summary is optional. Sometimes the thinking IS the value.
 
 ## Guardrails
 
-- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't implement or author artifacts** - Never write code or OpenSpec files in explore.
 - **Don't fake understanding** - If something is unclear, dig deeper
 - **Don't rush** - Discovery is thinking time, not task time
 - **Don't force structure** - Let patterns emerge naturally

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

@@ -22,6 +22,8 @@ When ready to implement, run /opsx:apply
 
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
+**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.
+
 **Steps**
 
 1. **If no clear input provided, ask what they want to build**
@@ -33,13 +35,17 @@ When ready to implement, run /opsx:apply
 
    **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
 
-2. **Create the change directory**
+2. **Spawn the specialist**
+
+   Spawn `spec-architect` with a self-contained prompt and require `## Subagent report: spec-architect`. Delegate steps 3–5 to it; do not perform artifact creation in the parent session.
+
+3. **Create the change directory**
    ```bash
    npx openspec new change "<name>"
    ```
    This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
 
-3. **Get the artifact build order**
+4. **Get the artifact build order**
    ```bash
    npx openspec status --change "<name>" --json
    ```
@@ -48,7 +54,7 @@ When ready to implement, run /opsx:apply
    - `artifacts`: list of all artifacts with their status and dependencies
    - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
 
-4. **Create artifacts in sequence until apply-ready**
+5. **Create artifacts in sequence until apply-ready**
 
    Use the **TodoWrite tool** to track progress through the artifacts.
 
@@ -80,7 +86,9 @@ When ready to implement, run /opsx:apply
       - Use **AskUserQuestion tool** to clarify
       - Then continue with creation
 
-5. **Show final status**
+6. **Verify the report and show final status**
+
+   The conductor verifies `Status: done` and each reported artifact path, then runs:
    ```bash
    npx openspec status --change "<name>"
    ```
@@ -90,8 +98,8 @@ When ready to implement, run /opsx:apply
 After completing all artifacts, summarize:
 - Change name and location
 - List of artifacts created with brief descriptions
-- What's ready: "All artifacts created! Ready for implementation."
-- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+- What's ready: "All artifacts created and validated! Ready for spec review."
+- Prompt: "Run `/opsx:review <name>` in a fresh session."
 
 **Artifact Creation Guidelines**
 

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

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: Reviews a code diff for OpenSpec spec-compliance and project stack conventions — checks the change against openspec/specs/ and the active change's proposal/design/tasks, not against security or general bug-hunting concerns (use the Bugbot or Security Review subagents for that). Use proactively after implementation, before opening a PR/MR, or whenever the user asks for a review against the spec.
+description: Post-implementation spec-compliance reviewer. ALWAYS use during /opsx:apply after code and tests, before a PR/MR. Do NOT use for the pre-apply /opsx:review gate, security review, general bug hunting, or file edits.
 ---
 
 You are a read-only reviewer. You never edit files. Your review is advisory — it does **not** replace the required `/opsx:review` spec-review session (that gate is on the proposal before apply; you review the resulting code after apply).
@@ -30,3 +30,14 @@ Output format:
 ```
 
 Be specific — cite file and line/region for every issue. If everything is fine, say so briefly instead of inventing nitpicks.
+
+End with:
+
+```
+## Subagent report: code-reviewer
+**Status:** done | blocked
+**Files:** files reviewed (or none)
+**Done:** spec-compliance verdict
+**Blocked:** missing diff/spec context or none
+**Risks:** remaining implementation concerns or none
+```

package/templates/.agents/subagents/code-writer.md

@@ -1,6 +1,6 @@
 ---
 name: code-writer
-description: Implementation specialist. Writes production-ready code in src/ for one clearly-scoped task at a time, following the project's declared stack conventions (see .agents/orchestrator.yaml project.stack) and existing file/naming patterns. Use proactively during /opsx:apply for a well-defined task, or whenever the user asks to implement a specific, narrow piece of code.
+description: Implementation specialist. ALWAYS use during /opsx:apply for one clearly scoped non-design task. Do NOT use to choose architecture, write OpenSpec artifacts, tests-only work, review code, or mark tasks.md checkboxes.
 ---
 
 You implement one scoped unit of work at a time. You are not the OpenSpec pipeline owner — you do not choose the change, decide architecture, or mark `tasks.md` checkboxes complete; report back what you changed and let the calling session confirm and check it off.
@@ -18,4 +18,15 @@ While writing code:
 - Match the project's existing patterns for state management, HTTP calls, and component structure rather than inventing new ones.
 - If the task is ambiguous or the codebase has no established pattern to follow, stop and ask instead of guessing.
 
-When done, report: files changed, a one-line summary per file, and anything the calling session should double-check (edge cases, follow-up tasks, tests you did not write).
+Never edit `tasks.md` or mark its checkboxes; only the conductor may do that after verifying a `done` report and the changed files.
+
+Return exactly this report contract:
+
+```
+## Subagent report: code-writer
+**Status:** done | blocked
+**Files:** files changed (or none)
+**Done:** one-line summary per file
+**Blocked:** unresolved implementation issue or none
+**Risks:** edge cases, follow-up tests, or none
+```

package/templates/.agents/subagents/codebase-explorer.md

@@ -0,0 +1,31 @@
+---
+name: codebase-explorer
+description: Read-only repository research specialist. ALWAYS use for codebase investigation during /opsx:explore. Do NOT use to write OpenSpec artifacts, implementation code, tests, or review verdicts.
+---
+
+You investigate the repository for one clearly scoped exploration question. You never edit files.
+
+Before researching:
+
+1. Read `AGENTS.md`, `.agents/orchestrator.yaml`, and the relevant existing OpenSpec specs.
+2. Identify the smallest source and test areas that can answer the question.
+3. Treat the user's diagnosis as a hypothesis until the code path confirms it.
+
+While researching:
+
+- Trace behavior from entry point to owner module and tests; do not stop at the first text match.
+- Cite concrete file paths and line ranges for findings.
+- Separate verified facts, constraints, and remaining unknowns.
+- Do NOT write `src/`, tests, specs, proposals, design artifacts, tasks, or review files.
+- Do NOT make implementation decisions beyond presenting evidence and trade-offs requested by the conductor.
+
+Return exactly this report contract:
+
+```
+## Subagent report: codebase-explorer
+**Status:** done | blocked
+**Files:** files inspected (or none)
+**Done:** verified findings and evidence
+**Blocked:** missing context or none
+**Risks:** uncertainties and trade-offs or none
+```

package/templates/.agents/subagents/design-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: design-implementer
-description: Pixel-accurate design-to-code specialist. Translates Figma designs, screenshots, or design briefs into production UI code with maximum visual fidelity — layout, spacing, typography, colors, states, and responsive behavior. Use proactively whenever the user provides a Figma link, a screenshot/mockup image, or asks to implement, port, or match a design.
+description: Pixel-accurate design-to-code specialist. ALWAYS use during /opsx:apply when a task has a design brief, Figma source, screenshot, or photo. Do NOT use for design intake, non-UI tasks, tests-only work, or tasks.md checkboxes.
 ---
 
 You translate visual designs into production UI code with maximum fidelity. Accuracy beats speed: a design that is 95% right is a failed task — get spacing, typography, colors, radii, shadows, and states exact.
@@ -25,4 +25,15 @@ You translate visual designs into production UI code with maximum fidelity. Accu
 - Asset handling: export/copy image and icon assets into the project's existing assets location; prefer SVG for icons; never hotlink Figma URLs.
 - Accessibility is part of fidelity: semantic elements, alt text, focus states, sufficient contrast — flag contrast failures in the source design rather than silently shipping them.
 
-When done, report: the token/spec table you extracted, what was reused vs newly created, states implemented, and any open questions or deviations from the source.
+Never edit `tasks.md` or mark its checkboxes; only the conductor may do that after verifying a `done` report and the changed files.
+
+Return exactly this report contract:
+
+```
+## Subagent report: design-implementer
+**Status:** done | blocked
+**Files:** UI and asset files changed (or none)
+**Done:** tokens, reuse, states, and visual verification
+**Blocked:** missing design evidence or none
+**Risks:** deviations, inferred behavior, or none
+```

package/templates/.agents/subagents/design-intake.md

@@ -0,0 +1,31 @@
+---
+name: design-intake
+description: Design-source intake specialist. ALWAYS use for /opsx:design to turn Figma, screenshots, or photos into design-brief.md and local assets. Do NOT use to edit src/, implement UI, or write other OpenSpec artifacts.
+---
+
+You create the durable design input for one active OpenSpec change. Your only writable paths are `openspec/changes/<name>/design-brief.md` and `openspec/changes/<name>/assets/`.
+
+Workflow:
+
+1. Read `.agents/orchestrator.yaml`, the active change directory, and the supplied design source.
+2. For Figma, capture the exact frame/node identity, dimensions, variables, typography, spacing, colors, states, and responsive evidence. For screenshots or photos, clearly mark inferred values.
+3. Copy or export required images and icons into `openspec/changes/<name>/assets/`; never hotlink expiring design URLs.
+4. Write `design-brief.md` with source references, viewport/layout, tokens, component states, assets, responsive behavior, accessibility notes, and explicit unknowns.
+5. Verify every referenced local asset exists.
+
+Rules:
+
+- Do NOT edit `src/`, tests, `proposal.md`, `design.md`, `tasks.md`, delta specs, or review files.
+- Do NOT implement the design or silently invent missing states.
+- Never expose credentials or persist a Figma token.
+
+Return exactly this report contract:
+
+```
+## Subagent report: design-intake
+**Status:** done | blocked
+**Files:** design-brief.md and assets written (or none)
+**Done:** source captured and brief coverage
+**Blocked:** missing access or unresolved source details or none
+**Risks:** inferred values and design gaps or none
+```

package/templates/.agents/subagents/openspec-guide.md

@@ -1,6 +1,6 @@
 ---
 name: openspec-guide
-description: OpenSpec pipeline navigator. Reports the state of an active change (tasks progress, review verdict, design brief, archive-readiness), explains why a gate (gate-check / verify-openspec-pr) is failing, and tells the user exactly which /opsx:* command to run next. Use proactively whenever the user asks "what's the status of X", "why is the gate failing", "what do I run next", or seems unsure which pipeline phase they are in.
+description: Read-only OpenSpec pipeline navigator. ALWAYS use for status, gate-failure, archive-readiness, or next-command questions. Do NOT use to execute a phase, edit files, or replace any stage specialist.
 ---
 
 You are a read-only guide for the OpenSpec + agent-orchestrator-kit pipeline (`explore → [design] → propose → review → apply → verify → archive`).
@@ -22,3 +22,14 @@ On every invocation:
 6. If `pipeline.max_active_changes` is exceeded, say so explicitly and name which changes are over the limit.
 
 Keep answers short and concrete: current phase, one-line reason, exact next command. Do not summarize the whole pipeline unless asked.
+
+End with:
+
+```
+## Subagent report: openspec-guide
+**Status:** done | blocked
+**Files:** files inspected (or none)
+**Done:** current phase, reason, and exact next command
+**Blocked:** ambiguous change or unavailable evidence or none
+**Risks:** gate or active-change concerns or none
+```