agent-orchestrator-kit 0.1.10 → 0.1.12

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

@@ -86,7 +86,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:
@@ -108,7 +108,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/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

@@ -8,7 +8,7 @@ You are a read-only reviewer. You never edit files. Your review is advisory —
 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 (`openspec list --json`, or ask if ambiguous). Read `openspec/changes/<name>/proposal.md`, `design.md`, and every touched `specs/*/spec.md`.
+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)?

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

@@ -10,8 +10,8 @@ You are a read-only guide for the OpenSpec + agent-orchestrator-kit pipeline (`e
 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 `openspec list --json` (or `agent-orchestrator status` if the CLI is available) to see active changes.
-3. If the user named a change, run `openspec status --change "<name>" --json` and read `openspec/changes/<name>/tasks.md` and `review.md` directly for ground truth.
+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>`

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

@@ -11,7 +11,8 @@ Diagnosis steps:
 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. 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.
+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:
 

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

package/templates/AGENTS.md

@@ -31,7 +31,7 @@ Verifier runs on **GitHub Actions** (default) or **GitLab** via `prebuild` → `
 
 With `init --ci gitlab --spec-verify` or `init --ci github --spec-verify`, an **AI Spec Verifier** also runs on MRs/PRs changing `src/`: an Amp agent checks the changed code against `openspec/specs/` and a **BLOCKED verdict fails the pipeline** (gate `spec-verify-blocking` in `.agents/orchestrator.yaml`).
 
-Both CI fragments also run `agent-orchestrator-kit gate-check` — a deterministic check that fails the pipeline when `src/` changed but the active change has no `review.md` with `Verdict: APPROVE` (when `require_spec_review: true`), and optionally requires `design-brief.md` (when `require_design_brief: true`, unless `proposal.md` has `Design: none`). Run `agent-orchestrator-kit status` at the start of any session to see task progress, review verdict, design brief, and archive readiness for every active change without querying `openspec` per change.
+Both CI fragments also run `npx agent-orchestrator-kit gate-check` — a deterministic check that fails the pipeline when `src/` changed but the active change has no `review.md` with `Verdict: APPROVE` (when `require_spec_review: true`), and optionally requires `design-brief.md` (when `require_design_brief: true`, unless `proposal.md` has `Design: none`). At session start run `npx agent-orchestrator-kit status` (not a bare global binary — Amp PATH often lacks it; see `.agents/rules/cli-via-npm.mdc`).
 
 ## Hard Rules
 
@@ -48,10 +48,10 @@ Both CI fragments also run `agent-orchestrator-kit gate-check` — a determinist
 | explore → design | UI change needs a brief; change name chosen |
 | explore → propose | Decision brief written; change name chosen (skip design if non-UI) |
 | design → propose | `design-brief.md` (+ `assets/`) written |
-| propose → review | `openspec validate --strict` passes ✓ |
+| propose → review | `npx openspec validate <name> --strict --type change` passes ✓ |
 | review → apply | Reviewer writes explicit **Approve** — enforced in CI by `gate-check` |
 | apply → verify | All `tasks.md` checkboxes `[x]`; local build OK |
-| verify → archive | CI green; PR merged — check `agent-orchestrator status` for "ready to archive" |
+| verify → archive | CI green; PR merged — check `npx agent-orchestrator-kit status` for "ready to archive" |
 
 ## Context to Pin per Role
 
@@ -67,6 +67,18 @@ Both CI fragments also run `agent-orchestrator-kit gate-check` — a determinist
 
 See `.agents/orchestrator.yaml` for role config, pipeline flags, and MCP baseline.
 
+### Optional: Figma personal token
+
+For design intake against private Figma files, each developer configures a local token (never commit, never paste into chat):
+
+```bash
+npx agent-orchestrator-kit figma-setup
+# edit .agents/figma.local.env → FIGMA_ACCESS_TOKEN=...
+npx agent-orchestrator-kit figma-status
+```
+
+MCP starts via `scripts/figma-mcp-launcher.cjs` (secret stays out of `.mcp.json`). See kit README → **Figma token**.
+
 ## Skills & Commands
 
 All skills live in `.agents/skills/` (committed to git).

package/templates/CLAUDE.md

@@ -34,11 +34,12 @@ Use `/skill-name` or let Claude auto-load based on context.
 ## Key Rules for This Session
 
 - Check `.agents/orchestrator.yaml` for project-specific pipeline config.
-- One active change at a time — run `openspec list` to confirm.
+- One active change at a time — run `npx openspec list` / `npx agent-orchestrator-kit status` to confirm.
 - No code edits in explore, design, or review mode.
 - Design Intake writes only `design-brief.md` and `assets/` — never `src/`.
 - After completing apply: run build/lint before declaring done.
-- Use `openspec validate --all --strict` to verify change artifacts.
+- Use `npx openspec validate --all --strict` or `npx openspec validate <name> --strict --type change`.
+- Never bare `openspec` / `agent-orchestrator-kit` without `npx` (Amp PATH → exit 127). See `.agents/rules/cli-via-npm.mdc`.
 
 ## File Locations
 

package/templates/orchestrator.yaml

@@ -55,10 +55,25 @@ mcp:
   baseline:
     - memory
   optional:
+    - figma
     - github
     - browser
 
+figma:
+  env_file: .agents/figma.local.env
+  token_key: FIGMA_ACCESS_TOKEN
+  mcp_launcher: scripts/figma-mcp-launcher.cjs
+
 verifier:
   lint_command: "npm run lint"
   build_command: "npm run build"
   test_command: ""
+
+# Amp/Cursor often lack global bins — agents must use npx/npm (see .agents/rules/cli-via-npm.mdc)
+cli:
+  status: npx agent-orchestrator-kit status
+  gate_check: npx agent-orchestrator-kit gate-check
+  openspec_list: npx openspec list
+  openspec_validate_change: npx openspec validate <name> --strict --type change
+  openspec_validate_all: npx openspec validate --all --strict
+  openspec_status: npx openspec status --change <name> --json