agent-orchestrator-kit 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.1.13] - 2026-08-13
+
+### Added
+- **Pipeline subagent conductor** — every `/opsx:*` parent session now delegates through an exclusive phase/signal routing table, with five new stage specialists for explore, design, propose, spec review, and archive (`codebase-explorer`, `design-intake`, `spec-architect`, `spec-reviewer`, `spec-archiver`)
+- **Durable session handoff** — sessions restore and persist `Change:*`, `Handoff:*`, and `Decision:*` Memory entities, mirror state in `openspec/changes/<name>/handoff.md`, and emit one next-session prompt in `project.agent_language` (no service banner, no duplicated summary)
+
+### Changed
+- Amp `subagent-*` wrappers now require isolated fresh-context execution and return only a structured specialist report
+- OpenSpec commands, orchestration rules, skills, profiles, and documentation now enforce conductor-only task marking and phase separation
+
+## [0.1.12] - 2026-07-21
+
+### Added
+- **`figma-fetch --depth <n>`** — limit Figma node tree depth for large frames (omit = full tree)
+
+### Fixed
+- **`figma-fetch` large payloads** — write API response text as-is instead of pretty-printing via `JSON.stringify` (avoids `Invalid string length` on huge trees)
+- Clearer error when Figma API returns a non-JSON body
+
 ## [0.1.11] - 2026-07-21
 
 ### Added

package/README.md

@@ -13,7 +13,7 @@ A portable kit that installs a **role-separated AI pipeline** into any project:
 explore → [design] → propose → review → apply → verify → archive
 ```
 
-Each role runs in a **separate agent session** with dedicated permissions, model hints, and handoff gates. The `openspec/changes/` folder acts as the **contract between agents** — no shared memory between sessions, only files.
+Each role runs in a **separate agent session**. The parent `/opsx:*` session is a conductor: it restores state, spawns the routed specialist, verifies its report, and does not perform specialist work itself. OpenSpec files remain the requirements/tasks source of truth; Memory MCP and `openspec/changes/<name>/handoff.md` index phase state and the next command.
 
 **Figma PAT setup (v0.1.11+)** — local `.agents/figma.local.env` + MCP launcher (token never in chat / committed MCP JSON). See [Figma token](#figma-token-optional).
 
@@ -27,10 +27,26 @@ Each role runs in a **separate agent session** with dedicated permissions, model
 | `test-writer` | Automated tests for recently changed code |
 | `setup-doctor` | Orchestrator / MCP / sync diagnosis and repair |
 | `design-implementer` | Pixel-accurate Figma / screenshot → production UI |
+| `codebase-explorer` | Read-only repository investigation for explore |
+| `design-intake` | Design source → durable brief + assets |
+| `spec-architect` | Proposal, design, delta specs, and tasks |
+| `spec-reviewer` | Pre-apply artifact gate + `review.md` |
+| `spec-archiver` | Delta merge and completed-change archive |
+
+The conductor uses one exclusive route per signal:
+
+| Phase / signal | Subagent |
+|----------------|----------|
+| Status / gates / next command | `openspec-guide` |
+| Kit / MCP / sync repair | `setup-doctor` |
+| Explore repository research | `codebase-explorer` |
+| Design / propose / spec review | `design-intake` / `spec-architect` / `spec-reviewer` |
+| Apply UI / ordinary task / tests / pre-PR review | `design-implementer` / `code-writer` / `test-writer` / `code-reviewer` |
+| Archive | `spec-archiver` |
 
 - **Cursor** → `.cursor/agents/` (native subagents)
 - **Claude Code** → `.claude/agents/` (native subagents)
-- **Amp Code** → auto-generated `subagent-*` skill wrappers in `.agents/skills/` (Amp has no file-based subagents)
+- **Amp Code** → auto-generated `subagent-*` skill wrappers in `.agents/skills/`; each wrapper requires the parent to spawn an isolated subagent, never execute it in the main thread
 
 Works with:
 - [Cursor](https://cursor.sh) — via `.cursor/rules/` + `.cursor/skills/` + `.cursor/agents/`
@@ -55,7 +71,7 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Upgrade to latest (Figma PAT in v0.1.11+, subagents in v0.1.10+):**
+**🔄 Already have the kit installed? Upgrade to latest (conductor + session handoff in v0.1.13+, Figma PAT in v0.1.11+):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
@@ -146,9 +162,9 @@ your-project/
 │   ├── orchestrator.yaml
 │   ├── mcp.json.example                 # Cursor MCP template
 │   ├── amp.settings.json.example        # Amp MCP template
-│   ├── commands/                        # 6 /opsx:* commands
-│   ├── rules/                           # 3 auto-applied rules
-│   ├── subagents/                       # 6 default custom subagents (Cursor/Claude/Amp)
+│   ├── commands/                        # /opsx:* role commands
+│   ├── rules/                           # auto-applied orchestration rules
+│   ├── subagents/                       # 11 stage/custom subagents (Cursor/Claude/Amp)
 │   └── skills/
 │       ├── agent-orchestration/         # Pipeline orchestration
 │       ├── openspec-howto/
@@ -169,7 +185,7 @@ your-project/
 | Orchestration | 5-role pipeline, `AGENTS.md`, `orchestrator.yaml`, review command |
 | OpenSpec skills | All 7 skills for `/opsx:*` workflow |
 | IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills/subagents) |
-| Subagents | `openspec-guide`, `code-writer`, `code-reviewer`, `test-writer`, `setup-doctor`, `design-implementer` — native in Cursor (`.cursor/agents/`) + Claude Code (`.claude/agents/`), exposed to Amp as auto-generated `subagent-*` skill wrappers in `.agents/skills/` |
+| Subagents | 11 exclusive routes: guide/setup, explore/design/propose/review/archive stage agents, and apply implementation/test/code-review agents — native in Cursor + Claude Code, isolated Amp `subagent-*` wrappers |
 | CLI gates | `npx agent-orchestrator-kit status` / `gate-check` — deterministic review-gate checks (always via `npx`; see `cli-via-npm.mdc`) |
 | CI | `agent-verify.yml` — GitHub (default) or GitLab fragment + `prebuild` hook, both run `gate-check` |
 | AI Spec Verifier | `spec-verify.yml` + verifier scripts — GitLab or GitHub, opt-in (`--spec-verify`) |
@@ -205,7 +221,7 @@ cp .agents/amp.settings.json.example .amp/settings.json
 
 Or run `./scripts/sync-local-agent-skills.sh` — it creates `.amp/settings.json` automatically.
 
-**Subagents in Amp:** Amp has no file-based custom subagents (only skills and plugin agents), so the kit exposes every `.agents/subagents/<name>.md` as an auto-generated skill `subagent-<name>` in `.agents/skills/`. These wrappers are committed to git, so Amp picks them up with zero local setup — just say "use the subagent-design-implementer skill" or let Amp auto-load it from the description. Edit the source file in `.agents/subagents/` (never the wrapper) and re-run `sync` to regenerate.
+**Subagents in Amp:** the kit exposes every `.agents/subagents/<name>.md` as an auto-generated `subagent-<name>` skill. The conductor MUST run the wrapper as an isolated subagent with fresh context and MUST NOT execute its body in the main thread. Edit only the source file and re-run `sync` to regenerate wrappers.
 
 4. Use commands directly:
 
@@ -237,7 +253,7 @@ Switch modes in Amp CLI: `Ctrl+O` → `mode`.
    - `.claude/skills/` — all skills from `.agents/skills/` (excluding Amp `subagent-*` wrappers)
    - `.claude/agents/` — custom subagents from `.agents/subagents/` (native Claude Code subagents)
 3. Skills are auto-loaded by Claude Code from `.claude/skills/`.
-4. Invoke directly: `/agent-orchestration`, `/openspec-howto`, etc. Subagents are delegated automatically by description or on request ("use the design-implementer subagent").
+4. Invoke `/opsx:*` or the orchestration skill. The conductor delegates using the mandatory phase/signal routing table rather than relying on description-only selection.
 
 **CLAUDE.md tiers used:**
 - Project level: `.claude/CLAUDE.md` (synced from `CLAUDE.md`)
@@ -262,10 +278,10 @@ You can add `context: fork` to explore/review skills for isolated subagent sessi
 2. Creates:
    - `.cursor/skills/` — all skills
    - `.cursor/rules/` — `.mdc` rule files
-   - `.cursor/agents/` — custom subagents (`openspec-guide`, `code-writer`, `code-reviewer`, `test-writer`, `setup-doctor`, `design-implementer`)
+   - `.cursor/agents/` — all 11 custom/stage subagents
    - `.mcp.json` — from `mcp.json.example` (if not present)
 3. Rules are applied automatically per `alwaysApply: true`.
-4. Subagents are invoked by name in chat (e.g. "use the code-reviewer subagent on this diff") or delegated to automatically by Cursor when their `description` matches the task. Add project-specific subagents by dropping `.md` files into `.agents/subagents/` and re-running sync.
+4. `/opsx:*` sessions use the mandatory conductor routing table to spawn subagents. Add project-specific subagents in `.agents/subagents/`, add an exclusive route, and re-run sync.
 
 **Memory + optional Figma MCP for Cursor** (`.mcp.json`):
 
@@ -295,6 +311,8 @@ Token lives in `.agents/figma.local.env` — see [Figma token](#figma-token-opti
 **Model:** fast/cheap.
 **Purpose:** Understand the problem. Surface options. Choose a direction.
 
+The conductor spawns `codebase-explorer` for repository investigation and stays read-only.
+
 **Exit criteria (before starting Architect):**
 - Problem stated in 3–5 sentences
 - 2–3 solution options + recommendation
@@ -313,6 +331,8 @@ Token lives in `.agents/figma.local.env` — see [Figma token](#figma-token-opti
 **Model:** strong reasoning.
 **Purpose:** Create all change artifacts: proposal, design, tasks, delta specs.
 
+The conductor spawns `spec-architect`; it does not write artifacts in the parent session.
+
 **Exit gate:**
 ```bash
 npx openspec validate <name> --strict --type change  # must be ✓
@@ -330,6 +350,8 @@ npx openspec validate <name> --strict --type change  # must be ✓
 **Model:** medium or strong.
 **Purpose:** Review artifacts. Output **Approve ✓** or **Request Changes ✗**.
 
+The conductor spawns `spec-reviewer` (not `code-reviewer`) and verifies its `review.md`.
+
 Checks:
 - Acceptance criteria are testable
 - Tasks ≤ ~2 hours each
@@ -346,7 +368,7 @@ Checks:
 
 ### Role 4: Implementer — `/opsx:apply <name>`
 
-**Mode:** writes `src/`. Marks `tasks.md [x]`.
+**Mode:** conductor; routed specialists write `src/` and tests. Only the conductor marks `tasks.md [x]` after a verified `Status: done` report.
 **Model:** strong. Use fast for simple mechanical tasks.
 **Purpose:** Implement tasks. One session = 1–3 tasks (not all 15 at once).
 
@@ -624,6 +646,8 @@ npx agent-orchestrator-kit figma-setup
 npx agent-orchestrator-kit figma-status
 npx agent-orchestrator-kit figma-fetch --url "https://www.figma.com/design/FILE_KEY/Name?node-id=1-2" \
   --out openspec/changes/<name>/assets/figma-nodes.json
+# large frames: limit tree depth
+npx agent-orchestrator-kit figma-fetch --file FILE_KEY --nodes 1:2 --depth 2 --out figma-nodes.json
 ```
 
 `figma-fetch` uses the Figma REST API (`X-Figma-Token`) and writes JSON for design-brief capture. Live Figma is for design-intake only — apply uses `design-brief.md`.
@@ -638,21 +662,18 @@ npx agent-orchestrator-kit figma-setup
 
 ## Memory MCP — Shared State Between Sessions
 
-Each role starts a fresh session. Memory MCP persists orchestration state across sessions so you don't re-explain context every time.
+Each role starts a fresh session. OpenSpec artifacts remain the source of truth; Memory MCP and `openspec/changes/<name>/handoff.md` are the phase index used to resume without re-explanation.
 
 **Standard entities to save:**
 
 ```
-Change:add-bulk-export     status: spec-approved, tasks: 0/7
+Change:add-bulk-export     status: spec-approved, tasks: 0/7, last_role: reviewer, review: APPROVE
 Decision:export-format     chosen: xlsx, reason: matches existing reports
-Convention:api-errors      use ApiError class, not raw Error
-Handoff:add-bulk-export    next_role: implementer, session_count: 1
+Handoff:add-bulk-export    next_role: implementer, next_command: /opsx:apply add-bulk-export,
+                           session_count: 2, summary: ..., blocked: none
 ```
 
-At the start of each implementer/reviewer session, read relevant memory:
-```
-What do we know about Change:add-bulk-export?
-```
+Every `/opsx:*` session reads `Change:<name>`, `Handoff:<name>`, and `Decision:*` before specialist work, falling back to `handoff.md` if Memory is unavailable. At exit it writes Memory, mirrors `handoff.md`, then prints one fenced prompt beginning `/opsx:*`, localized to `project.agent_language`, with no service banner or duplicated summary. The next phase always starts in a new chat.
 
 ## Amp Code — Deep Integration Notes
 
@@ -665,21 +686,22 @@ Amp is the **primary target** of this kit. It reads `.agents/skills/` and `AGENT
 | `AGENTS.md` subtree loading | Per-domain AGENTS.md in `openspec/` subtree |
 | `.agents/skills/` | All orchestration + domain skills |
 | `mcp.json` in skill dir | Lazy MCP loading (Memory only when needed) |
-| Subagents | Explore and Review skills use forked subagents |
+| Subagents | Conductor routing + isolated `subagent-*` wrappers |
 | Amp modes (rush/smart/deep) | Per-role model hints in AGENTS.md |
 
-**Amp subagent in skill** (`.agents/skills/openspec-explore/SKILL.md`):
+**Amp generated wrapper** (`.agents/skills/subagent-codebase-explorer/SKILL.md`):
 
 ```yaml
 ---
-name: openspec-explore
-description: Enter explore mode — read-only thinking partner
-disable-model-invocation: false
-allowed-tools: Read, Bash
+name: subagent-codebase-explorer
+description: Read-only repository research specialist...
 ---
+
+Parent MUST spawn this skill as an isolated subagent with fresh context.
+Do not execute it in the main thread.
 ```
 
-Amp will run this skill as a subagent when invoked.
+The conductor invokes the wrapper in isolation and consumes only its structured report.
 
 **Team workflow with Amp:**
 
@@ -748,11 +770,21 @@ CLAUDE.md                # Committed — synced to .claude/CLAUDE.md
 openspec/                # Committed — spec-driven workflow
   config.yaml            # Project context for AI
   specs/                 # Source of truth after archive
-  changes/               # Active work
+  changes/               # Active work; <name>/handoff.md indexes session state
 ```
 
 ## Changelog
 
+### 0.1.13
+- Pipeline **conductor**: `/opsx:*` parent spawns the routed specialist and does not do that work itself
+- Five new stage subagents: `codebase-explorer`, `design-intake`, `spec-architect`, `spec-reviewer`, `spec-archiver`
+- Session handoff: Memory → `handoff.md` → next-session prompt in `project.agent_language` (read Memory on start)
+- Amp `subagent-*` wrappers must run as isolated subagents, not in the main thread
+
+### 0.1.12
+- `figma-fetch --depth <n>` for large frames
+- Write large Figma JSON as raw API text (avoids `Invalid string length` on huge trees)
+
 ### 0.1.11
 - Optional **Figma personal token** setup: `.agents/figma.local.env` (gitignored) + `figma-mcp-launcher.cjs` (no secret in `.mcp.json`)
 - CLI: `figma-setup`, `figma-status`, `figma-fetch` (REST nodes/file JSON)

package/bin/agent-orchestrator.js

@@ -260,13 +260,17 @@ async function figmaApiGet(token, path) {
   try {
     data = JSON.parse(text);
   } catch {
-    data = { err: text };
+    data = null;
   }
   if (!response.ok) {
-    const message = data?.err || data?.message || response.statusText || `HTTP ${response.status}`;
+    const message =
+      (data && (data.err || data.message)) || response.statusText || `HTTP ${response.status}`;
     throw new Error(String(message));
   }
-  return data;
+  if (!data) {
+    throw new Error('Figma API returned non-JSON response');
+  }
+  return { data, text };
 }
 
 function resolveTemplate(templateName, profile) {
@@ -639,6 +643,8 @@ function generateAmpSubagentSkills(projectDir) {
         '',
         `<!-- AUTO-GENERATED from .agents/subagents/${file} — edit the source file, then run: npx agent-orchestrator-kit sync -->`,
         '',
+        'Parent MUST spawn this skill as an isolated subagent with fresh context. Do not execute it in the main thread. Return only the structured subagent report.',
+        '',
         parsed[2].trim(),
         '',
       ].join('\n');
@@ -1063,6 +1069,7 @@ program
   .option('--url <url>', 'Figma design URL (file key + optional node-id)')
   .option('--file <key>', 'Figma file key')
   .option('--nodes <ids>', 'Comma-separated node ids (1:2 or 1-2)')
+  .option('--depth <n>', 'Limit node tree depth (use for large frames; omit = full tree)')
   .option('--out <path>', 'Output JSON path', 'figma-nodes.json')
   .action(async (opts) => {
     const projectDir = process.cwd();
@@ -1096,16 +1103,36 @@ program
       .filter(Boolean)
       .map((id) => id.replace(/-/g, ':'));
 
+    const query = [];
+    if (nodeIds.length) {
+      query.push(`ids=${encodeURIComponent(nodeIds.join(','))}`);
+    }
+    if (opts.depth != null && String(opts.depth).trim() !== '') {
+      const depth = Number(opts.depth);
+      if (!Number.isInteger(depth) || depth < 1) {
+        log.err('--depth must be a positive integer');
+        process.exitCode = 1;
+        return;
+      }
+      query.push(`depth=${depth}`);
+    }
+
     try {
-      const path = nodeIds.length
-        ? `/files/${encodeURIComponent(fileKey)}/nodes?ids=${encodeURIComponent(nodeIds.join(','))}`
-        : `/files/${encodeURIComponent(fileKey)}`;
-      log.info(nodeIds.length ? `Fetching ${nodeIds.length} node(s)…` : 'Fetching full file…');
-      const data = await figmaApiGet(token, path);
+      const apiPath = nodeIds.length
+        ? `/files/${encodeURIComponent(fileKey)}/nodes${query.length ? `?${query.join('&')}` : ''}`
+        : `/files/${encodeURIComponent(fileKey)}${query.length ? `?${query.join('&')}` : ''}`;
+      log.info(
+        nodeIds.length
+          ? `Fetching ${nodeIds.length} node(s)${opts.depth ? ` (depth ${opts.depth})` : ''}…`
+          : `Fetching full file${opts.depth ? ` (depth ${opts.depth})` : ''}…`
+      );
+      const { data, text } = await figmaApiGet(token, apiPath);
       const outPath = join(projectDir, opts.out);
       mkdirSync(dirname(outPath), { recursive: true });
-      writeFileSync(outPath, `${JSON.stringify(data, null, 2)}\n`);
-      log.ok(`Wrote ${opts.out}`);
+      // Write API payload as-is — pretty-print of huge trees can throw "Invalid string length"
+      writeFileSync(outPath, text.endsWith('\n') ? text : `${text}\n`);
+      const nodeCount = data.nodes ? Object.keys(data.nodes).length : 0;
+      log.ok(`Wrote ${opts.out}${nodeCount ? ` (${nodeCount} node key(s))` : ''}`);
     } catch (error) {
       log.err(`Figma API error: ${error.message}`);
       process.exitCode = 1;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.11",
-  "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, cross-IDE subagents, and optional local Figma PAT setup (figma-setup / figma-status / figma-fetch)",
+  "version": "0.1.13",
+  "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, conductor subagents, session handoff, and optional local Figma PAT setup",
   "keywords": [
     "ai-agent",
     "cursor",

package/profiles/generic/orchestrator.yaml

@@ -44,6 +44,9 @@ handoff:
   propose_to_review: validate_strict
   review_to_apply: explicit_approve
   apply_to_verify: all_tasks_checked
+  restore_on_start: true
+  persist_on_exit: true
+  emit_next_session_prompt: true
 
 memory:
   enabled: true

package/profiles/mvp/orchestrator.yaml

@@ -51,6 +51,9 @@ handoff:
   explore_to_propose: decision_brief
   propose_to_apply: validate_or_quick
   apply_to_verify: all_tasks_checked
+  restore_on_start: true
+  persist_on_exit: true
+  emit_next_session_prompt: true
 
 memory:
   enabled: true

package/profiles/node/orchestrator.yaml

@@ -49,6 +49,9 @@ handoff:
   propose_to_review: validate_strict
   review_to_apply: explicit_approve
   apply_to_verify: all_tasks_checked
+  restore_on_start: true
+  persist_on_exit: true
+  emit_next_session_prompt: true
 
 memory:
   enabled: true

package/profiles/vue3/orchestrator.yaml

@@ -48,6 +48,9 @@ handoff:
   propose_to_review: validate_strict
   review_to_apply: explicit_approve
   apply_to_verify: all_tasks_checked
+  restore_on_start: true
+  persist_on_exit: true
+  emit_next_session_prompt: true
 
 memory:
   enabled: true

package/templates/.agents/commands/opsx-apply.md

@@ -5,10 +5,16 @@ category: Workflow
 description: Implement tasks from an OpenSpec change (Experimental)
 ---
 
+## Session Start (Before Any Work)
+
+Honor the pasted command and announce the Implementer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+
 Implement tasks from an OpenSpec change.
 
 **Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). 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`; after implementation spawn `test-writer` when tests are required, and before PR/MR spawn `code-reviewer`. Require each structured report. Only the conductor may edit `tasks.md` checkboxes.
+
 **Steps**
 
 1. **Select the change**
@@ -80,9 +86,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 test work and verify its report
+   - Only then, as conductor, mark the task complete in the tasks file: `- [ ]` → `- [x]`
    - Continue to next task
 
    **Pause if:**
@@ -150,13 +157,17 @@ All tasks complete! You can archive this change with `/opsx:archive`.
 What would you like to do?
 ```
 
+## Session Exit (Mandatory Order)
+
+When apply completes or pauses: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`, including task and build/lint status; (2) write `openspec/changes/<name>/handoff.md` using the orchestration skill template even if Memory fails; (3) print one fenced prompt beginning with the next `/opsx:*` role command. Use `project.agent_language`, tell the next session to read Memory and the file fallback, omit banner labels and the full summary. Never start archive in this apply chat.
+
 **Guardrails**
 - Keep going through tasks until done or blocked
 - Always read context files before starting (from the apply instructions output)
 - If task is ambiguous, pause and ask before implementing
 - If implementation reveals issues, pause and suggest artifact updates
 - Keep code changes minimal and scoped to each task
-- 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/commands/opsx-archive.md

@@ -5,10 +5,16 @@ category: Workflow
 description: Archive a completed change in the experimental workflow
 ---
 
+## Session Start (Before Any Work)
+
+Honor the pasted command and announce the Archiver role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+
 Archive a completed change in the experimental workflow.
 
 **Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). 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 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**
@@ -51,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
@@ -81,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
@@ -150,6 +160,10 @@ Target archive directory already exists.
 3. Wait until a different date to archive
 ```
 
+## Session Exit (Mandatory Order)
+
+Before closing archive: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`; (2) write the final handoff state at the archived change path using the orchestration skill template even if Memory fails; (3) when another role is required, print one fenced `/opsx:*` prompt using `project.agent_language`, Memory keys, and the file fallback, without a banner label or duplicated summary. Do not start another phase in this chat.
+
 **Guardrails**
 - Always prompt for change selection if not provided
 - Use artifact graph (openspec status --json) for completion checking

package/templates/.agents/commands/opsx-design.md

@@ -5,12 +5,18 @@ category: Workflow
 description: Capture design from any source into a durable design brief for an OpenSpec change
 ---
 
+## Session Start (Before Any Work)
+
+Honor the pasted command and announce the Design Intake role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+
 Capture design into a durable brief for an OpenSpec change. One-shot intake from Figma, exports, screenshots, or photos — then apply never needs live design tools.
 
 **IMPORTANT: You must NEVER edit any file in `src/` or any source code. You may write only `openspec/changes/<name>/design-brief.md` and files under `openspec/changes/<name>/assets/`.**
 
 **Input**: Optionally specify a change name (e.g., `/opsx:design add-login-form`). If omitted, auto-select if one active change exists, otherwise list and ask. If the change does not exist yet, create the change directory when writing the brief (after explore chose the name).
 
+**Conductor delegation is mandatory:** after resolving the change and source, spawn `design-intake` with a self-contained prompt. The parent MUST NOT inspect the design source or write the brief/assets itself; it only verifies the structured report and reported files.
+
 ---
 
 ## Steps
@@ -24,7 +30,11 @@ If name provided — use it. Otherwise:
 
 Announce: "Design intake for change: **<name>**"
 
-### 2. Choose source (fallback ladder)
+### 2. Spawn the specialist
+
+Spawn `design-intake` and delegate steps 3–6 below. Require `## Subagent report: design-intake`. Do not perform those steps in the parent session.
+
+### 3. Choose source (fallback ladder)
 
 Use the first available source; do not climb the ladder twice:
 
@@ -35,14 +45,14 @@ Use the first available source; do not climb the ladder twice:
 
 Ask the user for the source if unclear. Prefer Figma when a `figma.com` URL is given.
 
-### 3. Capture into assets/
+### 4. Capture into assets/
 
 Save reference images under `openspec/changes/<name>/assets/`:
 - Prefer compressed PNG; ~1–2 images per breakpoint
 - Do not commit raw video, PSD, or huge originals
 - Name files clearly: `desktop.png`, `mobile.png`, `hero-detail.png`
 
-### 4. Write design-brief.md
+### 5. Write design-brief.md
 
 Create or overwrite `openspec/changes/<name>/design-brief.md` using this template:
 
@@ -89,14 +99,16 @@ Create or overwrite `openspec/changes/<name>/design-brief.md` using this templat
 - Inferred (screenshot/photo): mark each inferred value with a confidence marker, e.g. `~8px (medium confidence)` or `color ≈ #1a1a1a (low confidence)`
 ```
 
-### 5. Confidence markers for raster sources
+### 6. Confidence markers for raster sources
 
 When the source is a **screenshot** or **photo** (not Figma MCP / vector export):
 - Do not present guessed spacing, colors, or type sizes as facts
 - Mark every inferred token/value with a confidence note in **Confidence notes** and inline in **Tokens** where useful
 - Prefer ranges or approximations over fake precision
 
-### 6. Handoff
+### 7. Verify report and handoff
+
+The conductor verifies `Status: done` and that every reported brief/asset path exists, then outputs the handoff summary.
 
 Output a short summary:
 
@@ -116,6 +128,10 @@ For non-UI changes: do not invent a brief. Tell the Architect to add a line `Des
 
 ---
 
+## Session Exit (Mandatory Order)
+
+Before closing design: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`; (2) write `openspec/changes/<name>/handoff.md` using the orchestration skill template even if Memory fails; (3) print one fenced prompt beginning `/opsx:propose <name>`. Use `project.agent_language`, tell the next session to read Memory and the file fallback, omit banner labels and the full summary. Do not start propose in this chat.
+
 ## Guardrails
 
 - **Never** edit source code or `src/`

package/templates/.agents/commands/opsx-explore.md

@@ -5,9 +5,15 @@ category: Workflow
 description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
 ---
 
+## Session Start (Before Any Work)
+
+Honor the pasted command and announce the Explorer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*`. If Memory is unavailable or empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then continue and spawn specialists.
+
 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 may discuss evidence returned by the specialist, but you must NEVER write code or OpenSpec artifacts. If the user asks you to implement or formalize the change, end explore with a handoff to a fresh propose session.
+
+**Conductor delegation is mandatory:** for any 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, and do not let the subagent write specs or code. The parent may synthesize the report and continue the exploratory 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.
 
@@ -160,9 +166,13 @@ When things crystallize, you might offer a summary - but it's optional. Sometime
 
 ---
 
+## Session Exit (Mandatory Order)
+
+Before closing explore: (1) attempt to update Memory `Change:<name>`, `Handoff:<name>`, and new `Decision:*`; (2) write `openspec/changes/<name>/handoff.md` using the orchestration skill template even if Memory fails; (3) print one fenced prompt whose first line is the chosen `/opsx:design <name>` or `/opsx:propose <name>`. Use `project.agent_language`, tell the next session to read Memory and the file fallback, omit banner labels and the full summary. Do not start that phase in this chat.
+
 ## 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