agent-orchestrator-kit 0.1.9 → 0.1.11

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

@@ -31,13 +31,13 @@ When ready to implement, run /opsx:apply
 
 2. **Create the change directory**
    ```bash
-   openspec new change "<name>"
+   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**
    ```bash
-   openspec status --change "<name>" --json
+   npx openspec status --change "<name>" --json
    ```
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
@@ -53,7 +53,7 @@ When ready to implement, run /opsx:apply
    a. **For each artifact that is `ready` (dependencies satisfied)**:
       - Get instructions:
         ```bash
-        openspec instructions <artifact-id> --change "<name>" --json
+        npx openspec instructions <artifact-id> --change "<name>" --json
         ```
       - The instructions JSON includes:
         - `context`: Project background (constraints for you - do NOT include in output)
@@ -68,7 +68,7 @@ When ready to implement, run /opsx:apply
       - Show brief progress: "Created <artifact-id>"
 
    b. **Continue until all `applyRequires` artifacts are complete**
-      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - After creating each artifact, re-run `npx openspec status --change "<name>" --json`
       - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
       - Stop when all `applyRequires` artifacts are done
 
@@ -78,7 +78,7 @@ When ready to implement, run /opsx:apply
 
 5. **Show final status**
    ```bash
-   openspec status --change "<name>"
+   npx openspec status --change "<name>"
    ```
 
 **Output**

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

@@ -31,7 +31,7 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 2. **Create change (minimal artifacts)**
 
    ```bash
-   openspec new change "<name>"
+   npx openspec new change "<name>"
    ```
 
    Create **lightweight** artifacts (no delta specs unless user asks):
@@ -44,7 +44,7 @@ Quick mode for **small changes, demos, and hypothesis testing**. Combines propos
 3. **Validate**
 
    ```bash
-   openspec validate <name> --strict --type change
+   npx openspec validate <name> --strict --type change
    ```
 
 4. **Apply immediately**

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

@@ -18,7 +18,7 @@ Review an OpenSpec change. Read artifacts, validate structure, output Approve or
 ### 1. Select the change
 
 If name provided — use it. Otherwise:
-- Run `openspec list --json` to list active changes.
+- Run `npx openspec list --json` to list active changes.
 - Auto-select if only one exists.
 - Ask the user with AskUserQuestion if ambiguous.
 
@@ -27,7 +27,7 @@ Announce: "Reviewing change: **<name>**"
 ### 2. Validate structure
 
 ```bash
-openspec validate <name> --strict --type change
+npx openspec validate <name> --strict --type change
 ```
 
 If ✗ — list each error and immediately output **Request Changes** with the validation errors. Stop here.
@@ -35,7 +35,7 @@ If ✗ — list each error and immediately output **Request Changes** with the v
 ### 3. Read all artifacts
 
 ```bash
-openspec status --change "<name>" --json
+npx openspec status --change "<name>" --json
 ```
 
 Read every file from `artifactPaths`:

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

@@ -15,7 +15,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `npx openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
    Show changes that have delta specs (under `specs/` directory).
 
@@ -25,7 +25,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
    Run:
    ```bash
-   openspec status --change "<name>" --json
+   npx openspec status --change "<name>" --json
    ```
 
    If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.

package/templates/.agents/figma.local.env.example

@@ -0,0 +1,10 @@
+# Figma Personal Access Token (local only — never commit this file)
+# Create: Figma → Settings → Security → Personal access tokens
+# Recommended scopes: file content read (as needed for your org)
+#
+# 1. Copy:  cp .agents/figma.local.env.example .agents/figma.local.env
+# 2. Paste your token below (do NOT paste it into AI chat)
+# 3. Restart Cursor / Amp after saving
+# 4. Check:  npx agent-orchestrator-kit figma-status
+
+FIGMA_ACCESS_TOKEN=

package/templates/.agents/mcp.json.example

@@ -6,6 +6,10 @@
       "env": {
         "MEMORY_FILE_PATH": ".cursor/memory.json"
       }
+    },
+    "figma": {
+      "command": "node",
+      "args": ["scripts/figma-mcp-launcher.cjs"]
     }
   }
 }

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

@@ -26,6 +26,7 @@ This project uses a spec-driven role pipeline. Read `.agents/orchestrator.yaml`
 - Apply uses the design brief, not live Figma MCP
 - After apply: build + lint before PR
 - After merge: run `/opsx:archive` (when `archive_after_merge: true`)
+- CLI: `npx agent-orchestrator-kit status`, `npx openspec …` — never bare globals (see `cli-via-npm.mdc`)
 
 ## Never
 - Mix propose and apply in one session

package/templates/.agents/rules/cli-via-npm.mdc

@@ -0,0 +1,40 @@
+---
+description: Always invoke OpenSpec and agent-orchestrator-kit via npx/npm (Amp + Cursor PATH)
+alwaysApply: true
+---
+
+# CLI via npx / npm (Cursor + Amp)
+
+Amp Code і багато агентських shell **не мають** глобальних `openspec`, `agent-orchestrator-kit`, `rg` у PATH → exit **127**.  
+Не викликай голі бінарні імена. Завжди з кореня репо (де є `package.json` / `node_modules/`):
+
+## Обов’язкові форми
+
+| Замість (ламає Amp) | Використовуй |
+|---------------------|--------------|
+| `agent-orchestrator-kit status` | `npx agent-orchestrator-kit status` (або `npm run agent:status`, якщо script є) |
+| `agent-orchestrator-kit gate-check` | `npx agent-orchestrator-kit gate-check` (або `npm run agent:gate-check`) |
+| `openspec list` | `npx openspec list` (або `npm run openspec:list`) |
+| `openspec validate --strict` | **ніколи без цілі** → `npx openspec validate <name> --strict --type change` |
+| `openspec validate --all --strict` | `npx openspec validate --all --strict` (або `npm run openspec:validate` / `verify:openspec`) |
+| `openspec status --change X` | `npx openspec status --change "X"` |
+| `rg …` | IDE Grep / читання файлів; не покладайся на глобальний `rg` |
+
+## Session start
+
+```bash
+npx agent-orchestrator-kit status
+npx openspec list
+```
+
+## Validate перед review / apply
+
+```bash
+npx openspec validate "<change-name>" --strict --type change
+```
+
+## Правила
+
+- Якщо exit **127** — одразу `npx` / `npm run`, не повторюй голу команду.
+- `openspec validate --strict` без `<name>` / `--all` / `--changes` — помилка контракту.
+- CI вже використовує `npx …` — локальні агенти мають робити так само.

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

@@ -0,0 +1,35 @@
+---
+description: Figma personal access token setup — local env file, never ask for token in chat
+alwaysApply: true
+---
+
+# Figma Token Setup
+
+Optional Figma access for design intake (`/opsx:design`) uses a **local Personal Access Token**.
+
+## Where the token lives
+
+| File | Git |
+|------|-----|
+| `.agents/figma.local.env` | **ignored** — real token |
+| `.agents/figma.local.env.example` | committed — template |
+
+Key: `FIGMA_ACCESS_TOKEN=`
+
+## Developer setup (tell the user this — never ask them to paste the token here)
+
+```bash
+cp .agents/figma.local.env.example .agents/figma.local.env
+# edit .agents/figma.local.env in the IDE and paste the token
+npx agent-orchestrator-kit figma-status
+```
+
+Restart Cursor / Amp after saving. MCP starts via `scripts/figma-mcp-launcher.cjs` (no secret in `.mcp.json`).
+
+## Agent rules
+
+- **NEVER** ask the user to paste a Figma token into chat
+- Check with `npx agent-orchestrator-kit figma-status` (yes/no only)
+- If missing → point to `.agents/figma.local.env` + README “Figma token” section
+- Use live Figma only in design-intake; apply uses `design-brief.md`
+- Optional REST dump: `npx agent-orchestrator-kit figma-fetch --file <key> --nodes <id> --out openspec/changes/<name>/assets/figma-nodes.json`

package/templates/.agents/rules/openspec-workflow.mdc

@@ -30,13 +30,16 @@ alwaysApply: true
 - `/opsx:archive` → skill `openspec-archive-change`
 - `/opsx:sync` → skill `openspec-sync-specs`
 
-## CLI (read-only)
+## CLI (via npx — never bare binaries)
+
+See also `.agents/rules/cli-via-npm.mdc`.
 
 ```bash
-openspec list
-openspec validate <name> --strict --type change
-openspec status --change "<name>" --json
-openspec instructions apply --change "<name>" --json
+npx openspec list
+npx openspec validate "<name>" --strict --type change
+npx openspec status --change "<name>" --json
+npx openspec instructions apply --change "<name>" --json
+npx agent-orchestrator-kit status
 ```
 
 Do NOT search for opsx in `src/` — nothing there.

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

@@ -77,9 +77,10 @@ Context from explore:
 ### propose → review
 Exit Architect when:
 ```bash
-openspec validate <name> --strict --type change  # must pass ✓
-openspec status --change "<name>"                # applyRequires artifacts all done
+npx openspec validate <name> --strict --type change  # must pass ✓
+npx openspec status --change "<name>"                # applyRequires artifacts all done
 ```
+(Use `npx` / `npm run` — bare `openspec` / `agent-orchestrator-kit` often exit 127 in Amp. See `cli-via-npm.mdc`.)
 
 ### review → apply
 Exit Reviewer only when verdict is explicit **APPROVE ✓** and `review.md` written.
@@ -90,7 +91,7 @@ Before apply, check `.agents/orchestrator.yaml`:
 
 If Request Changes — fix artifacts, re-run `/opsx:review`.
 
-This is no longer only a chat convention: `agent-orchestrator-kit gate-check` runs in CI (both `agent-verify.yml` fragments) and fails the pipeline if `src/` changed without an approved `review.md` — a forgotten or skipped review is caught at merge time, not just at apply time. When `require_design_brief: true`, the same command also requires `design-brief.md` (or `Design: none` in `proposal.md`).
+This is no longer only a chat convention: `npx agent-orchestrator-kit gate-check` runs in CI (both `agent-verify.yml` fragments) and fails the pipeline if `src/` changed without an approved `review.md` — a forgotten or skipped review is caught at merge time, not just at apply time. When `require_design_brief: true`, the same command also requires `design-brief.md` (or `Design: none` in `proposal.md`).
 
 ### apply → verify
 Exit Implementer when:
@@ -110,7 +111,7 @@ After PR merged + CI green:
 
 **Start of each session:**
 1. Announce role: "Starting Spec Reviewer session for change: <name>"
-2. Run `agent-orchestrator-kit status` (or `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
+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
 
 **During session:**
@@ -151,12 +152,12 @@ At start of new session: read relevant entities to restore context without re-ex
 ## Orchestration Checklist (per change)
 
 - [ ] explore session closed before propose started
-- [ ] `openspec validate --strict` passed before review
+- [ ] `npx openspec validate <name> --strict --type change` passed before review
 - [ ] explicit **Approve** received before apply (when `require_spec_review: true`)
 - [ ] `review.md` with `Verdict: APPROVE` exists (when review required)
 - [ ] all tasks `[x]` + build OK before PR
-- [ ] `agent-orchestrator-kit gate-check` passes locally before pushing (mirrors the CI gate)
-- [ ] `/opsx:archive` run after merge — `agent-orchestrator-kit status` shows "ready to archive"
+- [ ] `npx agent-orchestrator-kit gate-check` passes locally before pushing (mirrors the CI gate)
+- [ ] `/opsx:archive` run after merge — `npx agent-orchestrator-kit status` shows "ready to archive"
 
 ## Anti-patterns
 

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

@@ -20,13 +20,13 @@ Implement tasks from an OpenSpec change.
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, run `npx openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
 
    Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
 
 2. **Check status to understand the schema**
    ```bash
-   openspec status --change "<name>" --json
+   npx openspec status --change "<name>" --json
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
@@ -36,7 +36,7 @@ Implement tasks from an OpenSpec change.
 3. **Get apply instructions**
 
    ```bash
-   openspec instructions apply --change "<name>" --json
+   npx openspec instructions apply --change "<name>" --json
    ```
 
    This returns:

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

@@ -17,7 +17,7 @@ Archive a completed change in the experimental workflow.
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   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.
@@ -26,7 +26,7 @@ Archive a completed change in the experimental workflow.
 
 2. **Check artifact completion status**
 
-   Run `openspec status --change "<name>" --json` to check artifact completion.
+   Run `npx openspec status --change "<name>" --json` to check artifact completion.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used

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

@@ -83,7 +83,7 @@ You have full context of the OpenSpec system. Use it naturally, don't force it.
 
 At the start, quickly check what exists:
 ```bash
-openspec list --json
+npx openspec list --json
 ```
 
 This tells you:
@@ -103,7 +103,7 @@ Think freely. When insights crystallize, you might offer:
 If the user mentions a change or you detect one is relevant:
 
 1. **Resolve and read existing artifacts for context**
-   - Run `openspec status --change "<name>" --json`.
+   - Run `npx openspec status --change "<name>" --json`.
    - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
    - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
 

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

@@ -55,6 +55,10 @@ openspec/
 
 ## CLI (read-only — не змінює код)
 
+Завжди `npx openspec …` або `npm run openspec:*` / `npx agent-orchestrator-kit …`.  
+Голі `openspec` / `agent-orchestrator-kit` у Amp часто дають exit **127**.  
+Див. `.agents/rules/cli-via-npm.mdc`. Ніколи `openspec validate --strict` без `<name>` / `--all`.
+
 | Команда | Навіщо |
 |---------|--------|
 | `list` | Активні changes або specs |

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

@@ -35,13 +35,13 @@ When ready to implement, run /opsx:apply
 
 2. **Create the change directory**
    ```bash
-   openspec new change "<name>"
+   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**
    ```bash
-   openspec status --change "<name>" --json
+   npx openspec status --change "<name>" --json
    ```
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
@@ -57,7 +57,7 @@ When ready to implement, run /opsx:apply
    a. **For each artifact that is `ready` (dependencies satisfied)**:
       - Get instructions:
         ```bash
-        openspec instructions <artifact-id> --change "<name>" --json
+        npx openspec instructions <artifact-id> --change "<name>" --json
         ```
       - The instructions JSON includes:
         - `context`: Project background (constraints for you - do NOT include in output)
@@ -72,7 +72,7 @@ When ready to implement, run /opsx:apply
       - Show brief progress: "Created <artifact-id>"
 
    b. **Continue until all `applyRequires` artifacts are complete**
-      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - After creating each artifact, re-run `npx openspec status --change "<name>" --json`
       - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
       - Stop when all `applyRequires` artifacts are done
 
@@ -82,7 +82,7 @@ When ready to implement, run /opsx:apply
 
 5. **Show final status**
    ```bash
-   openspec status --change "<name>"
+   npx openspec status --change "<name>"
    ```
 
 **Output**

package/templates/.agents/skills/openspec-sync-specs/SKILL.md

@@ -19,7 +19,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `npx openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
    Show changes that have delta specs (under `specs/` directory).
 
@@ -29,7 +29,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
    Run:
    ```bash
-   openspec status --change "<name>" --json
+   npx openspec status --change "<name>" --json
    ```
 
    If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.

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

@@ -0,0 +1,32 @@
+---
+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.
+---
+
+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).
+
+Steps:
+
+1. Determine the diff: `git diff` against the target branch, or the files the user points you to.
+2. Identify the active OpenSpec change (`npx openspec list --json`, or ask if ambiguous). Read `openspec/changes/<name>/proposal.md`, `design.md`, and every touched `specs/*/spec.md`.
+3. Check spec compliance: does the diff implement every ADDED/MODIFIED requirement in the delta specs? Does it avoid touching anything marked out of scope? Flag missing or extra behavior explicitly, quoting the requirement.
+4. Check stack conventions from `.agents/orchestrator.yaml` (`project.stack`) — e.g. for `vue3`: Composition API only, `<script setup>`, no Options API, Pinia via `storeToRefs`, Axios via the project's shared instance/interceptors, no business logic left in templates.
+5. Check task hygiene: does `tasks.md` reflect what was actually implemented (no task marked `[x]` without matching code, no implemented work left unchecked)?
+
+Output format:
+
+```
+## Code Review: <change-name>
+
+**Spec compliance:** Compliant | Gaps found
+- ...
+
+**Convention issues**
+- Critical: ...
+- Warning: ...
+- Suggestion: ...
+
+**Verdict:** Ready for MR | Needs changes before MR
+```
+
+Be specific — cite file and line/region for every issue. If everything is fine, say so briefly instead of inventing nitpicks.

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

@@ -0,0 +1,21 @@
+---
+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.
+---
+
+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.
+
+Before writing code:
+
+1. Read `.agents/orchestrator.yaml` → `project.stack` and `roles.implementer.notes` to know which stack skills apply (e.g. `vue-core`, `vue-pinia`, `vue-axios`, `vue-router`, `vue-composables` for `stack: vue3`; adapt to whatever stack is declared otherwise).
+2. If working from an OpenSpec change, read the specific task in `openspec/changes/<name>/tasks.md` plus the relevant section of `design.md` and `specs/*/spec.md` — implement exactly what is scoped, nothing more.
+3. Look at 2-3 existing files of the same kind (component, composable, store, API module) already in the codebase and match their structure, naming, and idioms before introducing anything new.
+
+While writing code:
+
+- Keep the diff minimal and scoped to the task — no drive-by refactors, no unrelated formatting changes.
+- No comments that narrate obvious code; only comment non-obvious intent, trade-offs, or constraints.
+- 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).

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

@@ -0,0 +1,28 @@
+---
+name: design-implementer
+description: Pixel-accurate design-to-code specialist. Translates Figma designs, screenshots, or design briefs into production UI code with maximum visual fidelity — layout, spacing, typography, colors, states, and responsive behavior. Use proactively whenever the user provides a Figma link, a screenshot/mockup image, or asks to implement, port, or match a design.
+---
+
+You translate visual designs into production UI code with maximum fidelity. Accuracy beats speed: a design that is 95% right is a failed task — get spacing, typography, colors, radii, shadows, and states exact.
+
+## Source of truth — strict priority order
+
+1. **Design brief first.** If an active OpenSpec change has `openspec/changes/<name>/design-brief.md` + `assets/`, that is your only design source. Do NOT call live Figma MCP when a brief exists — this is a hard pipeline rule.
+2. **Figma MCP** (Cursor: `get_design_context`, `get_screenshot`; load the figma-design-to-code skill first if available). Use only when no design brief exists. Extract exact values — never eyeball a Figma frame.
+3. **Screenshot/image only.** Read the image carefully. Measure proportions from the image; state explicitly which values are inferred (exact px, fonts) so the user can correct them.
+
+## Workflow
+
+1. **Extract the spec before writing any code.** Build a token table from the source: colors (exact hex), font family/size/weight/line-height per text style, spacing values, border radii, shadows, breakpoints. For Figma, prefer design tokens/variables over raw hex.
+2. **Map to the project's system — never hardcode what already exists.** Check the project's existing tokens first (CSS variables, SCSS variables, framework theme — e.g. `quasar.variables.scss`, Tailwind config). Reuse existing UI components (check `src/components/` and the UI framework's components) instead of rebuilding them. Only introduce new tokens/components when nothing matches, and say so.
+3. **Implement.** Follow the project's stack conventions from `.agents/orchestrator.yaml` (`project.stack`). Match existing component structure and naming. Implement all states visible or implied in the design: hover, focus, active, disabled, empty, loading, error. Handle responsive behavior — if the design shows one viewport, apply the project's existing responsive patterns and note the assumption.
+4. **Verify against the reference.** Render the result (dev server + browser/screenshot when available) and compare side by side with the source image: alignment, spacing rhythm, font rendering, color accuracy. Fix discrepancies before reporting. If you cannot render, do a line-by-line self-review of the extracted spec table against your code.
+
+## Rules
+
+- Never approximate a color, spacing, or font size when the exact value is available in the source.
+- Never invent design decisions not present in the source; if something is ambiguous (missing state, unclear breakpoint), list it as an open question instead of guessing silently.
+- Asset handling: export/copy image and icon assets into the project's existing assets location; prefer SVG for icons; never hotlink Figma URLs.
+- Accessibility is part of fidelity: semantic elements, alt text, focus states, sufficient contrast — flag contrast failures in the source design rather than silently shipping them.
+
+When done, report: the token/spec table you extracted, what was reused vs newly created, states implemented, and any open questions or deviations from the source.

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

@@ -0,0 +1,24 @@
+---
+name: openspec-guide
+description: OpenSpec pipeline navigator. Reports the state of an active change (tasks progress, review verdict, design brief, archive-readiness), explains why a gate (gate-check / verify-openspec-pr) is failing, and tells the user exactly which /opsx:* command to run next. Use proactively whenever the user asks "what's the status of X", "why is the gate failing", "what do I run next", or seems unsure which pipeline phase they are in.
+---
+
+You are a read-only guide for the OpenSpec + agent-orchestrator-kit pipeline (`explore → [design] → propose → review → apply → verify → archive`).
+
+**Never edit files.** You only read and explain. If the user wants to act on your findings (write a proposal, implement a task, etc.), tell them which `/opsx:*` command to run in a fresh session — do not do it yourself.
+
+On every invocation:
+
+1. Read `.agents/orchestrator.yaml` — note `pipeline.require_spec_review`, `pipeline.require_design_brief`, `pipeline.max_active_changes`, and `pipeline.archive_after_merge`.
+2. Run `npx openspec list --json` (or `agent-orchestrator status` if the CLI is available) to see active changes.
+3. If the user named a change, run `npx openspec status --change "<name>" --json` and read `openspec/changes/<name>/tasks.md` and `review.md` directly for ground truth.
+4. Map what you find to the correct next command:
+   - No `proposal.md` yet → `/opsx:propose <name>`
+   - `require_design_brief: true`, UI-touching change, no `design-brief.md`, no `Design: none` in `proposal.md` → `/opsx:design <name>`
+   - `proposal.md` exists but no `review.md` with `Verdict: APPROVE` → `/opsx:review <name>` (must run in a separate read-only session)
+   - `review.md` says APPROVE but `tasks.md` has unchecked `- [ ]` items → `/opsx:apply <name>`
+   - All tasks `[x]` and review approved → ready to archive, suggest `/opsx:archive <name>` (or note that GitLab/GitHub CI auto-archives after merge if `archive_after_merge: true`)
+5. If a CI gate (`gate-check`, `verify-openspec-pr`) is failing, reproduce the check locally (`npx agent-orchestrator-kit gate-check <name>`, `npm run verify:openspec:pr`) and quote the exact failing reason from its output — don't guess.
+6. If `pipeline.max_active_changes` is exceeded, say so explicitly and name which changes are over the limit.
+
+Keep answers short and concrete: current phase, one-line reason, exact next command. Do not summarize the whole pipeline unless asked.

package/templates/.agents/subagents/setup-doctor.md

@@ -0,0 +1,26 @@
+---
+name: setup-doctor
+description: Diagnoses and fixes agent-orchestrator-kit setup problems — failing `verify:agents`/`gate-check`, missing .mcp.json or .amp/settings.json, out-of-sync .cursor/ or .claude/ directories, stale kit_version. Use proactively whenever verify:agents or CI setup checks fail, MCP/skills/subagents seem missing in the IDE, or the user asks to fix, set up, or update the orchestrator.
+---
+
+You diagnose and repair the *orchestrator's own* setup — not the project's business logic. Never touch `src/` or `openspec/changes/` content; only `.agents/`, `.cursor/`, `.claude/`, `.amp/`, `.mcp.json`, and root config files the kit manages.
+
+Diagnosis steps:
+
+1. Run `npm run verify:agents` (or the project's equivalent) and read every failing check line by line — don't summarize, quote them.
+2. Run `npx agent-orchestrator-kit status` and `npx agent-orchestrator-kit gate-check` to see pipeline-level gate state.
+3. Check `.agents/orchestrator.yaml` → `kit_version` against the installed package version; flag drift.
+4. Check that `.mcp.json` / `.amp/settings.json` exist (copy from their `.example` files if missing) and that the `memory` MCP server is configured with `MEMORY_FILE_PATH: .cursor/memory.json`.
+5. Optional Figma: run `npx agent-orchestrator-kit figma-status`. If not configured, tell the user to run `npx agent-orchestrator-kit figma-setup` and edit `.agents/figma.local.env` locally — **never ask them to paste the token into chat**. Confirm `.gitignore` contains `.agents/figma.local.env` and that `scripts/figma-mcp-launcher.cjs` exists.
+6. Check `.cursor/skills/`, `.cursor/rules/`, `.cursor/agents/` (and `.claude/` equivalents) are present and not stale relative to `.agents/` — if stale, this is fixed by running `sync`, not by hand-editing.
+
+Fix, in this priority order, applying only safe/reversible changes:
+
+- Missing local IDE files → run `./scripts/sync-local-agent-skills.sh` or `npx agent-orchestrator-kit sync --target all`
+- Stale kit-managed files → run `npx agent-orchestrator-kit update`, then re-sync
+- Missing `.mcp.json`/`.amp/settings.json` → copy from the `.example` file
+- Missing cache directories (`.agents/cache/handoffs`, `.agents/cache/checkpoints`) → create them with `.gitkeep`
+
+Never attempt fixes that require credentials or external side effects you don't have (npm login/publish, `sudo`, pushing to protected branches, rotating CI/CD variables) — instead tell the user the exact command they need to run themselves.
+
+Report: what you fixed, what still needs the user's action (with exact commands), and re-run `verify:agents` at the end to confirm.

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

@@ -0,0 +1,17 @@
+---
+name: test-writer
+description: Writes and updates automated tests for recently changed or newly implemented code, using the project's testing stack (e.g. Vitest + Vue Test Utils for vue3 projects). Use proactively right after implementing a feature or fixing a bug, or whenever the user asks to add or update tests.
+---
+
+You write tests for code that already exists — you do not implement features. If the code you're asked to test doesn't exist yet, say so and ask for it to be implemented first (or hand off to the `code-writer` subagent).
+
+Steps:
+
+1. Find what changed: `git diff --name-only` against the target branch, or the files the user names.
+2. For each changed source file, find its existing test file (co-located or in a mirrored test directory) or determine where a new one belongs, following the project's existing test file naming/location convention.
+3. Read `.agents/orchestrator.yaml` → `verifier.test_command` to know how tests are run in this project.
+4. Write tests following AAA structure (Arrange, Act, Assert). For Vue 3 projects: use Vue Test Utils `mount`/`shallowMount`, mock Pinia stores and Axios calls, test component behavior and composable outputs — not implementation details (internal refs, private state).
+5. Cover: the happy path, at least one edge case, and any error/rejection path that the changed code explicitly handles.
+6. Run the test command (from `verifier.test_command`) and report pass/fail. If tests fail, fix your own test code first; only flag the source code as broken if you're confident the test is correct and the implementation genuinely violates the expected behavior.
+
+Do not test trivial getters/setters, third-party library internals, or purely visual styling. Report which files you added/changed and the final test run result.

package/templates/.github/workflows/agent-verify.yml

@@ -9,13 +9,13 @@ jobs:
   verify:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Detect package manager
         id: pm

package/templates/.github/workflows/spec-verify.yml

@@ -30,13 +30,13 @@ jobs:
   spec-verify:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Install Amp CLI
         run: npm install -g @sourcegraph/amp@latest