agent-orchestrator-kit 0.1.11 → 0.1.13

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

@@ -5,6 +5,10 @@ category: Workflow
 description: Propose a new change - create it and generate all artifacts in one step
 ---
 
+## Session Start (Before Any Work)
+
+Honor the pasted command and announce the Architect 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.
+
 Propose a new change - create the change and generate all artifacts in one step.
 
 I'll create a change with artifacts:
@@ -18,6 +22,8 @@ When ready to implement, run /opsx:apply
 
 **Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants 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 files, run status, and run strict validation.
+
 **Steps**
 
 1. **If no input provided, ask what they want to build**
@@ -29,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
    ```
@@ -44,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.
 
@@ -76,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>"
    ```
@@ -86,8 +98,12 @@ 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` to start implementing."
+- What's ready: "All artifacts created and validated! Ready for spec review."
+- Prompt: "Run `/opsx:review <name>` in a fresh session."
+
+## Session Exit (Mandatory Order)
+
+After strict validation passes: (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:review <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 review in this chat.
 
 **Artifact Creation Guidelines**
 

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

@@ -5,6 +5,10 @@ category: Workflow
 description: Fast path for MVP/demo — propose artifacts and apply in one session (skips review gate)
 ---
 
+## Session Start (Before Any Work)
+
+Honor the pasted command and announce the Quick conductor 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.
+
 Quick mode for **small changes, demos, and hypothesis testing**. Combines propose + apply in one session.
 
 **Use when:**
@@ -20,6 +24,8 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 
 **Input**: Change name (kebab-case) or description. Example: `/opsx:quick add-export-button`
 
+**Conductor delegation is mandatory inside this one session:** spawn `spec-architect` for minimal artifacts, then `design-implementer` or `code-writer` per implementation task, `test-writer` for tests, and `code-reviewer` before merge. The parent MUST NOT write specialist artifacts/code/tests itself. Specialists never edit `tasks.md`; the conductor verifies each `Status: done` report and marks checkboxes. Do not emit a next-session prompt between propose and apply.
+
 **Steps**
 
 1. **Check orchestrator config**
@@ -30,6 +36,8 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 
 2. **Create change (minimal artifacts)**
 
+   Spawn `spec-architect` with the quick-mode scope and require its structured report. Do not create the artifacts in the parent session.
+
    ```bash
    npx openspec new change "<name>"
    ```
@@ -51,10 +59,13 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 
    Follow `/opsx:apply` steps for the same change:
    - Read tasks.md
-   - Implement 1–3 tasks per pass
-   - Mark `[x]`
+   - Spawn `design-implementer` for design-led work, otherwise `code-writer`, one task per prompt
+   - Spawn `test-writer` for required tests
+   - Verify each structured report and reported file, then let only the conductor mark `[x]`
    - Run build/lint from `orchestrator.yaml` verifier commands
 
+   Continue directly from propose to apply in this session. Do not print or ask the user to paste a mid-session handoff prompt.
+
 5. **Exit**
 
    - If demo done and no merge planned → optionally skip archive
@@ -62,8 +73,13 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 
 ---
 
+## Session Exit (Mandatory Order)
+
+At the end of the whole quick session: (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 exactly one fenced prompt for the verify/archive continuation using `project.agent_language`, Memory keys, and the file fallback, without a banner label or duplicated summary. This is the session's only next-session prompt. Do not start archive in this chat.
+
 **Guardrails**
 - Max ~3 hours of work — if bigger, switch to full pipeline
 - Still run build/lint before declaring done
 - Do not skip OpenSpec entirely — at minimum proposal + tasks
 - For vue3: use vue-core, vue-pinia skills during implementation
+- Never emit or request paste of a next-session prompt between quick propose and apply; emit exactly one only at final exit

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

@@ -5,12 +5,18 @@ category: Workflow
 description: Read-only spec review of an OpenSpec change — approve or request changes before apply
 ---
 
+## Session Start (Before Any Work)
+
+Honor the pasted command and announce the Spec Reviewer 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.
+
 Review an OpenSpec change. Read artifacts, validate structure, output Approve or Request Changes.
 
 **IMPORTANT: This is a read-only mode. You must NEVER edit any file in `src/` or any source code. You may not mark tasks `[x]`. Your only output is a structured review verdict.**
 
 **Input**: Optionally specify a change name (e.g., `/opsx:review add-auth`). If omitted, auto-select if one active change exists, otherwise list and ask.
 
+**Conductor delegation is mandatory:** after selecting the change, spawn `spec-reviewer` with the complete change paths and project constraints. The parent MUST NOT review artifacts or write `review.md`; it only verifies the structured report and that `review.md` contains the reported verdict. Never substitute `code-reviewer`.
+
 ---
 
 ## Steps
@@ -24,7 +30,11 @@ If name provided — use it. Otherwise:
 
 Announce: "Reviewing change: **<name>**"
 
-### 2. Validate structure
+### 2. Spawn the specialist
+
+Spawn `spec-reviewer` and delegate steps 3–6 below. Require `## Subagent report: spec-reviewer`. Do not perform the review in the parent session.
+
+### 3. Validate structure
 
 ```bash
 npx openspec validate <name> --strict --type change
@@ -32,7 +42,7 @@ npx openspec validate <name> --strict --type change
 
 If ✗ — list each error and immediately output **Request Changes** with the validation errors. Stop here.
 
-### 3. Read all artifacts
+### 4. Read all artifacts
 
 ```bash
 npx openspec status --change "<name>" --json
@@ -46,7 +56,7 @@ Read every file from `artifactPaths`:
 
 Also read related `openspec/specs/` domain files to check consistency.
 
-### 4. Review checklist
+### 5. Review checklist
 
 Evaluate each item. Mark ✓ or ✗:
 
@@ -81,7 +91,7 @@ Evaluate each item. Mark ✓ or ✗:
 - [ ] Tasks reference concrete component/store paths under `src/`
 - [ ] No scope creep into unrelated UI refactors
 
-### 5. Output verdict
+### 6. Write and report the verdict
 
 #### If all ✓ (or only minor notes):
 
@@ -125,6 +135,8 @@ For **REQUEST CHANGES**, write the same file with `Verdict: REQUEST CHANGES` and
 
 This is the **only file** you may write during review (not `src/`, not `tasks.md` checkboxes).
 
+The conductor verifies the subagent's `Status: done`, checks that `review.md` exists with the reported verdict, and relays the result without editing it.
+
 #### If any ✗:
 
 ```
@@ -148,6 +160,10 @@ Fix the above, then re-run `/opsx:review <name>`.
 
 ---
 
+## Session Exit (Mandatory Order)
+
+After writing the verdict: (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 with the next `/opsx:*` command (`/opsx:apply <name>` only after APPROVE). 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 the next phase in this chat.
+
 ## Guardrails
 
 - **Never** edit source code, `src/`, or `tasks.md` checkboxes

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

@@ -16,6 +16,45 @@ This project uses a spec-driven role pipeline. Read `.agents/orchestrator.yaml`
 - `/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 |
+| 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. Read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*`.
+4. If Memory MCP is unavailable or those entities are empty, read `openspec/changes/<name>/handoff.md`. Memory failure alone MUST NOT block the session.
+5. Only after context is restored, spawn the routed specialist.
+
+If the user says “continue” / “next” without a command and exactly one active change has `Handoff.next_command` (from Memory or `handoff.md`), execute that command instead of asking which phase to run.
+
+## Session Exit Protocol (Mandatory Order)
+
+A phase is not closed until the conductor performs these steps in order:
+
+1. Attempt to update Memory: `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`).
+2. Write the same state to `openspec/changes/<name>/handoff.md` with sections **Closed role**, **Done**, **Decisions**, **Blocked**, **Next command**, **Attach**, **Subagents to spawn**, and **Prompt**. Do this even if Memory is unavailable.
+3. Print one fenced copy/paste prompt. Its first line MUST be `/opsx:<next> <name>`; its body MUST use `.agents/orchestrator.yaml` → `project.agent_language`, instruct the next session to read `Change:<name>`, `Handoff:<name>`, and `Decision:*`, and mention the `handoff.md` fallback. Do not add a service/banner label or duplicate the session summary.
+4. 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)

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

@@ -40,16 +40,23 @@ 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 |
+
+## Session Lifecycle
+
+At the start of every `/opsx:*` role session, after resolving the change and before specialist work, 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, first attempt to update `Change:<name>`, `Handoff:<name>`, and every new `Decision:<topic>`. Then always mirror the state to `openspec/changes/<name>/handoff.md`, even when the Memory write fails. Only after that attempt may the conductor emit the next-session prompt.
 
 ## Rules
 - Do not overwrite existing correct config
 - Do not delete other MCP servers
 - Notify once: "Memory MCP connected."
+- Never treat unavailable Memory MCP as a reason to stop when `handoff.md` can restore or persist state

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

@@ -42,6 +42,26 @@ 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 |
+| 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,9 +130,11 @@ 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. Read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*`.
+4. If Memory MCP is unavailable or those entities are empty, read `openspec/changes/<name>/handoff.md`; Memory failure alone is not a blocker.
+5. Only after restoration, spawn the routed 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
@@ -120,9 +142,45 @@ After PR merged + CI green:
 - 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
+1. Attempt to update Memory: `Change:<name>` (`status`, `tasks n/m`, `last_role`, `review`), `Handoff:<name>` (`next_role`, `next_command`, `session_count`, `summary`, `blocked`), and new `Decision:<topic>` entities (`chosen`, `reason`).
+2. Even if Memory fails, write `openspec/changes/<name>/handoff.md` using the template below.
+3. Print exactly one fenced next-session prompt after the write attempt. The first line is `/opsx:<next> <name>`; the body uses `project.agent_language`, tells the next session to read Memory and the file fallback, has no banner label, and does not repeat the summary.
+4. Do not start the next phase in this chat. If apply, include build/lint status in the persisted summary.
+
+`handoff.md` template:
+
+````markdown
+# Session Handoff
+
+## Closed role
+<role and completion status>
+
+## Done
+<concise persisted summary>
+
+## Decisions
+- <decision or none>
+
+## Blocked
+<blocker or none>
+
+## Next command
+`/opsx:<next> <name>`
+
+## Attach
+- `openspec/changes/<name>/<artifact>`
+
+## Subagents to spawn
+- `<subagent>` — <signal>
+
+## Prompt
+
+```text
+/opsx:<next> <name>
+
+<Localized start instruction in project.agent_language. Read Memory Change:<name>, Handoff:<name>, Decision:* before work. If Memory is unavailable, read openspec/changes/<name>/handoff.md. Act as conductor and do not mix phases.>
+```
+````
 
 ## Model Selection Guide
 
@@ -136,18 +194,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; read Memory entities `Change:<name>`, `Handoff:<name>`, and `Decision:*`; if Memory is unavailable or empty, 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.
 
-| 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) update Memory, (2) mirror state to `openspec/changes/<name>/handoff.md`, (3) print one fenced next-session prompt whose first line is `/opsx:<next> <name>`. The prompt has no `NEXT_SESSION_PROMPT` label, tells the next session to read Memory, uses `project.agent_language`, and does not duplicate the full summary. 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)
 

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
+```