agent-orchestrator-kit 0.2.0 → 0.4.0

package/package.json

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

package/profiles/generic/orchestrator.yaml

@@ -10,6 +10,7 @@ pipeline:
   require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
+  task_contract: warn
 
 roles:
   explorer:
@@ -48,7 +49,7 @@ handoff:
   persist_on_exit: true
   emit_next_session_prompt: true
   prompt_self_contained: true
-  spawn_handoff_subagent: true
+  spawn_handoff_subagent: false
 
 memory:
   enabled: true
@@ -60,6 +61,22 @@ mcp:
     - memory
   optional:
     - figma
+    - github
+    - gitlab
+    - browser
+
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    - openspec-explore
+    - openspec-propose
+    - openspec-apply-change
+    - openspec-archive-change
+    - openspec-sync-specs
+    - spec-workflow-openspec
+  stack: []
+  external: ""
 
 figma:
   env_file: .agents/figma.local.env

package/profiles/mvp/openspec-config.yaml.example

@@ -12,6 +12,8 @@ rules:
     - Acceptance criteria — 3–5 перевірних пунктів
   tasks:
     - 3–7 атомарних задач
+    - "Контракт таска: індентовані поля Files: (реальні шляхи; нові — з префіксом new file:), Do: (конкретна зміна, 1–3 рядки), Done-when: (перевірна умова або команда)"
+    - Таск самодостатній без design.md; без неконкретних формулювань («as needed», «if necessary», «за потреби»)
     - Останній пункт: build + lint
   specs:
     - Опційно для MVP — пропускай якщо change тривіальний

package/profiles/mvp/orchestrator.yaml

@@ -15,6 +15,7 @@ pipeline:
   max_active_changes: 3
   archive_after_merge: false
   quick_mode_enabled: true
+  task_contract: off
 
 roles:
   explorer:
@@ -55,7 +56,7 @@ handoff:
   persist_on_exit: true
   emit_next_session_prompt: true
   prompt_self_contained: true
-  spawn_handoff_subagent: true
+  spawn_handoff_subagent: false
 
 memory:
   enabled: true
@@ -67,6 +68,22 @@ mcp:
     - memory
   optional:
     - figma
+    - github
+    - gitlab
+    - browser
+
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    - openspec-explore
+    - openspec-propose
+    - openspec-apply-change
+    - openspec-archive-change
+    - openspec-sync-specs
+    - spec-workflow-openspec
+  stack: []
+  external: ""
 
 figma:
   env_file: .agents/figma.local.env

package/profiles/node/orchestrator.yaml

@@ -13,6 +13,7 @@ pipeline:
   require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
+  task_contract: warn
 
 roles:
   explorer:
@@ -35,7 +36,6 @@ roles:
     command: /opsx:apply
     mode: code
     model_hint: strong
-    notes: "Use javascript-core, javascript-node, javascript-testing skills during apply"
   verifier:
     type: ci
     gates:
@@ -53,7 +53,7 @@ handoff:
   persist_on_exit: true
   emit_next_session_prompt: true
   prompt_self_contained: true
-  spawn_handoff_subagent: true
+  spawn_handoff_subagent: false
 
 memory:
   enabled: true
@@ -65,6 +65,25 @@ mcp:
     - memory
   optional:
     - figma
+    - github
+    - gitlab
+    - browser
+
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    - openspec-explore
+    - openspec-propose
+    - openspec-apply-change
+    - openspec-archive-change
+    - openspec-sync-specs
+    - spec-workflow-openspec
+  stack:
+    - javascript-core
+    - javascript-node
+    - javascript-testing
+  external: frontend-agent-skills
 
 figma:
   env_file: .agents/figma.local.env

package/profiles/vue3/openspec-config.yaml.example

@@ -15,6 +15,8 @@ rules:
     - Описуй зміни на рівні компонентів, stores, API
   tasks:
     - Розбивай на задачі до ~2 годин
+    - "Контракт таска: індентовані поля Files: (реальні шляхи; нові — з префіксом new file:), Do: (конкретна зміна, 1–3 рядки), Done-when: (перевірна умова або команда)"
+    - Таск самодостатній без design.md; без неконкретних формулювань («as needed», «if necessary», «за потреби»)
     - Останній пункт: build + lint без помилок
   specs:
     - Delta format: ADDED / MODIFIED / REMOVED

package/profiles/vue3/orchestrator.yaml

@@ -13,6 +13,7 @@ pipeline:
   require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
+  task_contract: warn
 
 roles:
   explorer:
@@ -35,7 +36,6 @@ roles:
     command: /opsx:apply
     mode: code
     model_hint: strong
-    notes: "Use vue-core, vue-pinia, vue-axios, vue-router skills during apply"
   verifier:
     type: ci
     gates:
@@ -52,7 +52,7 @@ handoff:
   persist_on_exit: true
   emit_next_session_prompt: true
   prompt_self_contained: true
-  spawn_handoff_subagent: true
+  spawn_handoff_subagent: false
 
 memory:
   enabled: true
@@ -65,8 +65,26 @@ mcp:
   optional:
     - figma
     - github
+    - gitlab
     - browser
 
+skills:
+  kit:
+    - agent-orchestration
+    - openspec-howto
+    - openspec-explore
+    - openspec-propose
+    - openspec-apply-change
+    - openspec-archive-change
+    - openspec-sync-specs
+    - spec-workflow-openspec
+  stack:
+    - vue-core
+    - vue-pinia
+    - vue-axios
+    - vue-router
+  external: frontend-agent-skills
+
 figma:
   env_file: .agents/figma.local.env
   token_key: FIGMA_ACCESS_TOKEN

package/templates/.agents/amp.settings.json.example

@@ -7,6 +7,18 @@
     "figma": {
       "command": "node",
       "args": ["scripts/figma-mcp-launcher.cjs"]
+    },
+    "github": {
+      "command": "node",
+      "args": ["scripts/github-mcp-launcher.cjs"]
+    },
+    "gitlab": {
+      "command": "node",
+      "args": ["scripts/gitlab-mcp-launcher.cjs"]
+    },
+    "browser": {
+      "command": "node",
+      "args": ["scripts/browser-mcp-launcher.cjs"]
     }
   }
 }

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

@@ -5,15 +5,17 @@ category: Workflow
 description: Implement tasks from an OpenSpec change (Experimental)
 ---
 
-## Session Start (Before Any Work)
+## Session Start
 
-Honor the pasted command and announce the Implementer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
+Follow the canonical Session Start protocol in `.agents/rules/session-handoff.mdc`, then announce the Implementer role.
 
 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.
+**Parent-driven apply:** the parent reads `tasks.md` + `apply-notes.md` (open `design.md`/`proposal.md` only when a task explicitly references them or a contract field is incomplete) and writes code and tests itself, task by task, checking its own `tasks.md` checkboxes. Subagents are optional: spawn `code-writer`/`test-writer` for ≥ 2 independent tasks with no shared files (parallelization) or on explicit user request. `design-implementer` remains mandatory for tasks with a design-brief/Figma signal.
+
+**Escape valve (STOP — improvisation is forbidden):** if a task requires information beyond its Files/Do/Done-when + `apply-notes.md` + artifacts it explicitly references, STOP: record the gap in `handoff.md`, set the next command to `/opsx:propose <name>` (plan amendment), and end the session. Do not guess.
 
 **Steps**
 
@@ -28,16 +30,7 @@ Implement tasks from an OpenSpec change.
 
 1.5. **Check review gate**
 
-   Read `.agents/orchestrator.yaml` → `pipeline.require_spec_review`.
-
-   If `true` (default for generic/vue3/node):
-   - Look for `openspec/changes/<name>/review.md` with `Verdict: APPROVE`
-   - OR explicit **APPROVE ✓** from `/opsx:review <name>` in this session (user pasted verdict)
-   - OR Memory MCP entity `Change:<name>` with `status: spec-approved`
-   - If none found → **STOP**. Tell user:
-     > "Spec review required. Run `/opsx:review <name>` in a separate read-only session, then start a new apply session after **Approve ✓`."
-
-   If `false` (mvp profile) or user confirms quick/demo mode → proceed.
+   Read `.agents/orchestrator.yaml` → `pipeline.require_spec_review`. If `true` (default for generic/vue3/node), require one of: `review.md` with `Verdict: APPROVE`, a pasted **APPROVE ✓** verdict from `/opsx:review <name>`, or Memory `Change:<name>` with `status: spec-approved`. If none found → **STOP** and tell the user to run `/opsx:review <name>` in a separate read-only session first. If `false` (mvp profile) or quick/demo mode is confirmed → proceed.
 
 2. **Check status to understand the schema**
    ```bash
@@ -67,12 +60,9 @@ Implement tasks from an OpenSpec change.
 
    **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
 
-4. **Read context files**
+4. **Read the working set**
 
-   Read every file path listed under `contextFiles` from the apply instructions output.
-   The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
-   - Other schemas: follow the contextFiles from CLI output
+   Read `tasks.md` and `apply-notes.md` — they are the primary input for apply. Open `design.md`, `proposal.md`, or delta specs only when a task explicitly references them or a contract field is incomplete. For non-spec-driven schemas, follow `contextFiles` from the CLI output.
 
 5. **Show current progress**
 
@@ -86,17 +76,12 @@ Implement tasks from an OpenSpec change.
 
    For each pending task:
    - Show which task is being worked on
-   - 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]`
+   - Implement it in the parent session from its Files/Do/Done-when contract (subagent rules: see "Parent-driven apply" above)
+   - Verify the task's Done-when condition actually holds
+   - Mark the task complete in the tasks file: `- [ ]` → `- [x]`
    - Continue to next task
 
-   **Pause if:**
-   - Task is unclear → ask for clarification
-   - Implementation reveals a design issue → suggest updating artifacts
-   - Error or blocker encountered → report and wait for guidance
-   - User interrupts
+   **STOP if:** the escape valve triggers (see above), an error or blocker is encountered (report and wait), or the user interrupts.
 
 7. **On completion or pause, show status**
 
@@ -114,10 +99,6 @@ Implement tasks from an OpenSpec change.
 Working on task 3/7: <task description>
 [...implementation happening...]
 ✓ Task complete
-
-Working on task 4/7: <task description>
-[...implementation happening...]
-✓ Task complete
 ```
 
 **Output On Completion**
@@ -159,24 +140,15 @@ What would you like to do?
 
 ## Session Exit (HARD STOP)
 
-You have NOT finished until every step succeeds. Do not say done/готово, do not start archive, and do not omit the fenced next-thread prompt.
-
-1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
-2. Write `openspec/changes/<name>/handoff.md` with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints. Include task and build/lint status in Done.
-3. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI upserts Memory JSON (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:*`.
-5. Paste CLI stdout into chat as one fenced block beginning with the next `/opsx:*` role command. Keep it complete. No banner.
-6. Stop. Never start archive in this apply chat.
+Close via the canonical Session Exit protocol in `.agents/rules/session-handoff.mdc`. Include task and build/lint status in Done. 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
-- 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
+- Always read `tasks.md` + `apply-notes.md` before starting
+- If a task contract is insufficient, STOP via the escape valve — don't guess or improvise
+- Keep code changes minimal and scoped to each task's `Files:` list
+- Never let a spawned specialist update `tasks.md`; the parent checks a box only after verifying Done-when
+- Pause on errors and blockers
 
 **Fluid Workflow Integration**
 

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

@@ -2,180 +2,27 @@
 name: /opsx-archive
 id: opsx-archive
 category: Workflow
-description: Archive a completed change in the experimental workflow
+description: Archive a completed change via the agent-orchestrator-kit CLI
 ---
 
-## Session Start (Before Any Work)
+Session Start / Session Exit: follow the protocol in `.agents/rules/session-handoff.mdc`. Announce the Archiver role.
 
-Honor the pasted command and announce the Archiver role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
-
-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.
+Archive is fully deterministic — one CLI call, no phase subagents.
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
-
-   Run `npx openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show only active changes (not already archived).
-   Include the schema used for each change if available.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check artifact completion status**
-
-   Run `npx openspec status --change "<name>" --json` to check artifact completion.
-
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used
-   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
-   - `artifacts`: List of artifacts with their status (`done` or other)
-
-   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
-
-   **If any artifacts are not `done`:**
-   - Display warning listing incomplete artifacts
-   - Prompt user for confirmation to continue
-   - Proceed if user confirms
-
-3. **Check task completion status**
-
-   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
-
-   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
-
-   **If incomplete tasks found:**
-   - Display warning showing count of incomplete tasks
-   - Prompt user for confirmation to continue
-   - Proceed if user confirms
-
-   **If no tasks file exists:** Proceed without task-related warning.
-
-4. **Assess delta spec sync state**
-
-   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:**
-   - Ask whether main specs should be synced before archive
-   - Include the delta and main spec paths in the `spec-archiver` prompt
-   - Have `spec-archiver` return the combined sync summary in its report
-
-   **Prompt options:**
-   - If changes needed: "Sync now (recommended)", "Archive without syncing"
-   - If already synced: "Archive now", "Sync anyway", "Cancel"
-
-   The `spec-archiver` performs any requested comparison and sync as part of its isolated work; do not spawn a generic sync agent.
-
-5. **Spawn the specialist and perform the archive**
-
-   Spawn `spec-archiver`, require `## Subagent report: spec-archiver`, and delegate the sync/archive operations below. Do not run them in the parent session.
-
-   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
-   ```bash
-   mkdir -p "<planningHome.changesDir>/archive"
-   ```
+1. **Resolve the change name.** Use the name after `/opsx:archive`. If omitted or ambiguous, run `npx openspec list --json` and use the **AskUserQuestion tool** to let the user pick an active change. Never guess.
 
-   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+2. **Decide on delta-spec sync.** If the change has delta specs, ask the user: merge them into main specs (`--sync`, recommended) or archive without merging (`--no-sync --force`).
 
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move `changeRoot` to the archive directory
+3. **Run the CLI:**
 
    ```bash
-   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
+   npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
    ```
 
-6. **Verify the report and display summary**
-
-   The conductor verifies `Status: done`, the reported archive path, and modified main specs before reporting completion.
-
-   Show archive completion summary including:
-   - Change name
-   - Schema that was used
-   - Archive location
-   - Spec sync status (synced / sync skipped / no delta specs)
-   - Note about any warnings (incomplete artifacts/tasks)
-
-**Output On Success**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
-**Specs:** ✓ Synced to main specs
-
-All artifacts complete. All tasks complete.
-```
-
-**Output On Success (No Delta Specs)**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
-**Specs:** No delta specs
-
-All artifacts complete. All tasks complete.
-```
-
-**Output On Success With Warnings**
-
-```
-## Archive Complete (with warnings)
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
-**Specs:** Sync skipped (user chose to skip)
-
-**Warnings:**
-- Archived with 2 incomplete artifacts
-- Archived with 3 incomplete tasks
-- Delta spec sync was skipped (user chose to skip)
-
-Review the archive if this was not intentional.
-```
-
-**Output On Error (Archive Exists)**
-
-```
-## Archive Failed
-
-**Change:** <change-name>
-**Target:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
-
-Target archive directory already exists.
-
-**Options:**
-1. Rename the existing archive
-2. Delete the existing archive if it's a duplicate
-3. Wait until a different date to archive
-```
-
-## Session Exit (HARD STOP)
-
-You have NOT finished until every step succeeds. Do not say done/готово and do not omit the fenced next-thread prompt when another role is required.
+   The CLI checks gates (review APPROVE, all tasks `[x]`, no existing target), merges delta specs on `--sync`, moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>`, runs `npx openspec validate --all --strict` with full rollback on failure, and writes the final `handoff.md` (`next_command: none`) plus memory upsert.
 
-1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
-2. Write the final handoff state at the archived change path with: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints.
-3. Run `npx agent-orchestrator-kit handoff <name>` from the archived path context when possible, or write Memory JSON via the same CLI against the active name before the move. Require exit 0 when the change dir still exists.
-4. If Memory MCP tools work, also update `Change:<name>`, `Handoff:<name>`, and new `Decision:*`.
-5. When another role is required, paste CLI stdout as one fenced `/opsx:*` prompt. Keep it complete. No banner.
-6. Stop. Do not start another phase in this chat.
+4. **Show the CLI stdout as-is.** On exit ≠ 0, report the failed gate from stderr and stop — do not merge or move anything manually.
 
-**Guardrails**
-- Always prompt for change selection if not provided
-- Use artifact graph (openspec status --json) for completion checking
-- Don't block archive on warnings - just inform and confirm
-- Preserve .openspec.yaml when moving to archive (it moves with the directory)
-- Show clear summary of what happened
-- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
-- If delta specs exist, always run the sync assessment and show the combined summary before prompting
+The pipeline ends here: no next-thread prompt is required after a successful archive.

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

@@ -5,9 +5,9 @@ category: Workflow
 description: Capture design from any source into a durable design brief for an OpenSpec change
 ---
 
-## Session Start (Before Any Work)
+## Session Start
 
-Honor the pasted command and announce the Design Intake role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
+Follow the canonical Session Start protocol in `.agents/rules/session-handoff.mdc`, then announce the Design Intake role.
 
 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.
 
@@ -130,14 +130,7 @@ For non-UI changes: do not invent a brief. Tell the Architect to add a line `Des
 
 ## Session Exit (HARD STOP)
 
-You have NOT finished until every step succeeds. Do not say done/готово, do not start propose, and do not omit the fenced next-thread prompt.
-
-1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
-2. Write `openspec/changes/<name>/handoff.md` with: 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 Memory JSON (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:*`.
-5. Paste CLI stdout into chat as one fenced block beginning `/opsx:propose <name>`. Keep it complete. No banner.
-6. Stop. Do not start propose in this chat.
+Close via the canonical Session Exit protocol in `.agents/rules/session-handoff.mdc`. First line of the pasted prompt is `/opsx:propose <name>`. Do not start propose in this chat.
 
 ## Guardrails
 

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

@@ -5,9 +5,9 @@ category: Workflow
 description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
 ---
 
-## Session Start (Before Any Work)
+## Session Start
 
-Honor the pasted command and announce the Explorer role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
+Follow the canonical Session Start protocol in `.agents/rules/session-handoff.mdc`, then announce the Explorer role.
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
@@ -168,14 +168,7 @@ When things crystallize, you might offer a summary - but it's optional. Sometime
 
 ## Session Exit (HARD STOP)
 
-You have NOT finished until every step succeeds. Do not say done/готово, do not start the next phase, and do not omit the fenced next-thread prompt.
-
-1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
-2. Write `openspec/changes/<name>/handoff.md` with: 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 Memory JSON (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:*`.
-5. Paste CLI stdout into chat as one fenced block. Keep it complete. No banner. First line is `/opsx:design <name>` or `/opsx:propose <name>`.
-6. Stop. Do not start that phase in this chat.
+Close via the canonical Session Exit protocol in `.agents/rules/session-handoff.mdc`. First line of the pasted prompt is `/opsx:design <name>` or `/opsx:propose <name>`. Do not start that phase in this chat.
 
 ## Guardrails
 

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

@@ -5,9 +5,9 @@ category: Workflow
 description: Propose a new change - create it and generate all artifacts in one step
 ---
 
-## Session Start (Before Any Work)
+## Session Start
 
-Honor the pasted command and announce the Architect role. Run `npx agent-orchestrator-kit status` or `npx openspec list --json`, then `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). Read Memory `Change:<name>`, `Handoff:<name>`, and `Decision:*` when MCP works. If restore CLI fails and Memory is empty, read `openspec/changes/<name>/handoff.md`; this fallback is not a blocker. Spawn `session-handoff` in restore mode when context is incomplete (Amp: isolated `subagent-session-handoff`). For free-form “continue” / “next” with one active change, execute its `Handoff.next_command` instead of asking for the phase. Only then spawn the routed phase specialist (Amp: isolated `subagent-<name>`, never the main thread). Follow `.agents/rules/session-handoff.mdc`.
+Follow the canonical Session Start protocol in `.agents/rules/session-handoff.mdc`, then announce the Architect role.
 
 Propose a new change - create the change and generate all artifacts in one step.
 
@@ -24,6 +24,17 @@ When ready to implement, run /opsx:apply
 
 **Conductor delegation is mandatory:** spawn `spec-architect` with the resolved name, decision brief, design brief if present, and artifact instructions. The parent MUST NOT create or edit proposal/design/specs/tasks; after the structured report it may only verify files, run status, and run strict validation.
 
+**Task contract (mandatory tasks.md format):** every task must carry indented `Files:`, `Do:`, `Done-when:` fields:
+
+```markdown
+- [ ] 2.1 Short title
+  Files: src/router/index.js, new file: src/stores/auth.js
+  Do: concrete change in 1–3 lines — no vague wording ("as needed", "if necessary", "as appropriate")
+  Done-when: verifiable condition or command
+```
+
+Each task must be self-contained for a blind implementer — executable without reading design.md. `Files:` paths must exist unless prefixed with `new file:`. Lint: `npx agent-orchestrator-kit gate-check --tasks <name>` (mode via `pipeline.task_contract: warn|strict|off`).
+
 **Steps**
 
 1. **If no input provided, ask what they want to build**
@@ -103,14 +114,7 @@ After completing all artifacts, summarize:
 
 ## Session Exit (HARD STOP)
 
-You have NOT finished until every step succeeds. Do not say done/готово, do not start review, and do not omit the fenced next-thread prompt.
-
-1. Spawn `session-handoff` in persist mode (Amp: isolated `subagent-session-handoff`). If spawn fails, persist in the parent — never skip.
-2. Write `openspec/changes/<name>/handoff.md` with: 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 Memory JSON (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:*`.
-5. Paste CLI stdout into chat as one fenced block beginning `/opsx:review <name>`. Keep it complete. No banner.
-6. Stop. Do not start review in this chat.
+Close via the canonical Session Exit protocol in `.agents/rules/session-handoff.mdc`. First line of the pasted prompt is `/opsx:review <name>`. Do not start review in this chat.
 
 **Artifact Creation Guidelines**