agent-orchestrator-kit 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.9] - 2026-07-12
+
+### Added
+- **Design intake** — optional `/opsx:design` phase: captures Figma / export / screenshot / photo into `design-brief.md` + `assets/` (writes only those paths)
+- **Role `design_intake`** in templates and all profiles (`generic`, `vue3`, `node`, `mvp`) with `pipeline.require_design_brief: false` (opt-in)
+- **`gate-check` design brief gate** — when `require_design_brief: true` and `src/` changed, requires `design-brief.md` or `Design: none` in `proposal.md`
+- **`status`** shows `brief: yes/no` for every active change
+- **Docs** — AGENTS.md / CLAUDE.md / rules / agent-orchestration skill / README section for design intake and manual enable after `update`
+
+## [0.1.8] - 2026-07-07
+
+### Changed
+- **README** — Quickstart block (new vs existing project) and upgrade guide for `status` / `gate-check` / GitHub Spec Verifier adoption
+
 ## [0.1.7] - 2026-07-07
 
 ### Added
@@ -89,6 +103,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[0.1.8]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.6...v0.1.7
 [0.1.5]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.3...v0.1.4

package/README.md

@@ -26,6 +26,28 @@ Without role separation, AI agents tend to mix thinking with implementation, ski
 
 The `AGENTS.md` / `CLAUDE.md` files tell each IDE exactly what the roles are, so you don't repeat yourself every session.
 
+## Quickstart
+
+**🆕 New project:**
+
+```bash
+npm i -D @fission-ai/openspec && npx openspec init
+npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-verify
+./scripts/sync-local-agent-skills.sh
+```
+
+See [Installation](#installation) for profile/CI options.
+
+**🔄 Already have the kit installed? Get `status` / `gate-check` / GitHub Spec Verifier (v0.1.7+):**
+
+```bash
+npx agent-orchestrator-kit@latest update
+./scripts/sync-local-agent-skills.sh
+npx agent-orchestrator-kit@latest status       # try it right away
+```
+
+See [Upgrading an existing project](#upgrading-an-existing-project-to-v017-status--gate-check--github-spec-verifier) for what changes and what stays opt-in.
+
 ## Installation
 
 ### Prerequisites
@@ -389,13 +411,54 @@ Orchestration hard rules (review approval, one active change) used to rely entir
 npx agent-orchestrator-kit status
 ```
 
-Prints every active OpenSpec change with task progress (`N/M tasks`), review verdict (`APPROVE` / `REQUEST CHANGES` / `none`), and a `ready to archive` flag once all tasks are `[x]` — no more running `openspec status` per change by hand.
+Prints every active OpenSpec change with task progress (`N/M tasks`), review verdict (`APPROVE` / `REQUEST CHANGES` / `none`), design brief (`brief: yes/no`), and a `ready to archive` flag once all tasks are `[x]` — no more running `openspec status` per change by hand.
 
 ```bash
 npx agent-orchestrator-kit gate-check [change-name] [--src-glob src/] [--base HEAD~1]
 ```
 
-Fails (non-zero exit) when `pipeline.require_spec_review: true`, the diff against `--base` touches `--src-glob`, and the active change has no `review.md` with `Verdict: APPROVE`. It degrades gracefully to exit 0 (with a message, not silently) when: `.agents/orchestrator.yaml` is missing, review isn't required, the diff can't be computed (e.g. shallow clone), or nothing under `--src-glob` changed. It also warns (never fails) when active changes exceed `pipeline.max_active_changes`. Both `agent-verify.yml` fragments (GitHub and GitLab) call `gate-check` automatically.
+Fails (non-zero exit) when `pipeline.require_spec_review: true`, the diff against `--base` touches `--src-glob`, and the active change has no `review.md` with `Verdict: APPROVE`. When `pipeline.require_design_brief: true` and `src/` changed, it also requires `design-brief.md` (or a `Design: none` line in `proposal.md` for non-UI changes). It degrades gracefully to exit 0 (with a message, not silently) when: `.agents/orchestrator.yaml` is missing, neither review nor design brief is required, the diff can't be computed (e.g. shallow clone), or nothing under `--src-glob` changed. It also warns (never fails) when active changes exceed `pipeline.max_active_changes`. Both `agent-verify.yml` fragments (GitHub and GitLab) call `gate-check` automatically.
+
+---
+
+### Design intake: `/opsx:design`
+
+Optional phase between explore and propose (or before apply) that captures design into a durable artifact so implement sessions do not depend on live Figma MCP:
+
+```
+/opsx:design add-login-form
+```
+
+Writes only:
+- `openspec/changes/<name>/design-brief.md` — Source, Structure, Tokens, Reference images, Constraints, Confidence notes
+- `openspec/changes/<name>/assets/` — reference PNGs
+
+Source fallback: Figma MCP (one pass) → exported images → screenshots → photos. Raster sources must mark inferred values with confidence notes.
+
+**Opt-in gate** (default off — existing projects unchanged):
+
+```yaml
+pipeline:
+  require_design_brief: true   # gate-check fails without brief when src/ changed
+```
+
+Non-UI changes: add this line to `proposal.md`:
+
+```
+Design: none
+```
+
+**Existing projects after `update`:** the command file `opsx-design.md` is installed automatically. Your `orchestrator.yaml` is never overwritten — add the role and flag manually if you want the gate:
+
+```yaml
+pipeline:
+  require_design_brief: false   # set true to enforce
+roles:
+  design_intake:
+    command: /opsx:design
+    mode: brief-only
+    model_hint: strong
+```
 
 ---
 
@@ -419,6 +482,7 @@ project:
 
 pipeline:
   require_spec_review: true
+  require_design_brief: false   # opt-in: require design-brief.md when src/ changed
   max_active_changes: 1
   archive_after_merge: true
 
@@ -444,6 +508,31 @@ npx agent-orchestrator-kit update
 - `openspec/changes/`
 - Any project-conventions skills
 
+### Upgrading an existing project to v0.1.7 (status / gate-check / GitHub Spec Verifier)
+
+If the kit is already installed and you just want the new deterministic gates, no re-`init` needed:
+
+```bash
+npx agent-orchestrator-kit@latest update
+./scripts/sync-local-agent-skills.sh
+```
+
+What this gets you automatically:
+- `.github/workflows/agent-verify.yml` / `.gitlab/agent-verify.yml` refreshed with a `gate-check` step (fails CI if `src/` changed without an approved `review.md`)
+- `sync` (both the CLI command and the shell script) starts removing skills that no longer exist in `.agents/skills/`
+- `agent-orchestrator status` and `agent-orchestrator gate-check` are available immediately (they ship inside `bin/`, not as opt-in templates) — try `npx agent-orchestrator-kit@latest status` right away
+
+Two things `update` will **not** do for you (by design — opt-in, and it never touches your CI root file):
+
+1. **GitLab-only projects that already had `--spec-verify`** — `update` refreshes `.gitlab/spec-verify.yml` and the scripts automatically (only because they already exist in your project).
+2. **Adding GitHub Spec Verifier where you didn't have it before** — that's a new opt-in, run it once:
+   ```bash
+   npx agent-orchestrator-kit@latest init --ci github --spec-verify
+   ```
+   then add the `AMP_API_KEY` repo secret (Settings → Secrets and variables → Actions).
+
+Nothing about `update` retroactively edits your `.gitlab-ci.yml` / already-included workflows — if `gate-check` doesn't seem to run, check that your `.gitlab-ci.yml` still `include`s `.gitlab/agent-verify.yml` (GitHub Actions picks up `.github/workflows/*.yml` automatically, no include step needed).
+
 ## Profiles
 
 | Profile | Stack | Extra (separate install) |
@@ -584,6 +673,14 @@ openspec/                # Committed — spec-driven workflow
 
 ## Changelog
 
+### 0.1.9
+- Design intake — `/opsx:design` captures design into `design-brief.md` + `assets/` (Figma / export / screenshot / photo)
+- Role `design_intake` + opt-in `pipeline.require_design_brief` (default `false`) in all profiles
+- `gate-check` enforces design brief when enabled (`Design: none` opt-out for non-UI); `status` shows `brief: yes/no`
+
+### 0.1.8
+- README — Quickstart (new vs existing project) and upgrade guide for adopting `status`, `gate-check`, and GitHub Spec Verifier
+
 ### 0.1.7
 - `agent-orchestrator status` — dashboard for active OpenSpec changes: task progress, review verdict, archive readiness
 - `agent-orchestrator gate-check` — deterministic review-gate check (exit non-zero without an approved `review.md`); wired into both `agent-verify.yml` CI fragments

package/bin/agent-orchestrator.js

@@ -178,14 +178,27 @@ function parseReviewVerdict(changeDir) {
   return match ? match[1].trim() : 'unknown';
 }
 
+function parseDesignBrief(changeDir) {
+  return existsSync(join(changeDir, 'design-brief.md'));
+}
+
+function hasDesignOptOut(changeDir) {
+  const proposalPath = join(changeDir, 'proposal.md');
+  if (!existsSync(proposalPath)) return false;
+  const content = readFileSync(proposalPath, 'utf-8');
+  return /^Design:\s*none/mi.test(content);
+}
+
 function readPipelineConfig(projectDir) {
   const orchPath = join(projectDir, '.agents', 'orchestrator.yaml');
   if (!existsSync(orchPath)) return null;
   const content = readFileSync(orchPath, 'utf-8');
   const requireReviewMatch = content.match(/require_spec_review:\s*(true|false)/);
+  const requireBriefMatch = content.match(/require_design_brief:\s*(true|false)/);
   const maxActiveMatch = content.match(/max_active_changes:\s*(\d+)/);
   return {
     requireSpecReview: requireReviewMatch ? requireReviewMatch[1] === 'true' : true,
+    requireDesignBrief: requireBriefMatch ? requireBriefMatch[1] === 'true' : false,
     maxActiveChanges: maxActiveMatch ? parseInt(maxActiveMatch[1], 10) : null,
   };
 }
@@ -643,6 +656,7 @@ program
       const changeDir = join(projectDir, 'openspec', 'changes', name);
       const progress = parseTasksProgress(changeDir);
       const verdict = parseReviewVerdict(changeDir);
+      const hasBrief = parseDesignBrief(changeDir);
       const progressStr = progress ? `${progress.done}/${progress.total} tasks` : 'no tasks.md';
       const verdictStr = verdict || 'none';
       const readyToArchive = Boolean(progress && progress.total > 0 && progress.done === progress.total);
@@ -650,6 +664,7 @@ program
       console.log(`\n${pc.bold(name)}`);
       console.log(`  tasks:  ${progressStr}`);
       console.log(`  review: ${verdictStr}`);
+      console.log(`  brief:  ${hasBrief ? 'yes' : 'no'}`);
       if (readyToArchive) log.ok('ready to archive');
     }
     console.log('');
@@ -670,7 +685,7 @@ program
       return;
     }
 
-    if (!config.requireSpecReview) {
+    if (!config.requireSpecReview && !config.requireDesignBrief) {
       log.ok('review not required (pipeline.require_spec_review: false)');
       return;
     }
@@ -709,15 +724,28 @@ program
       return;
     }
 
-    const verdict = parseReviewVerdict(changeDir);
-    if (verdict && /^APPROVE/i.test(verdict)) {
+    if (config.requireSpecReview) {
+      const verdict = parseReviewVerdict(changeDir);
+      if (!(verdict && /^APPROVE/i.test(verdict))) {
+        log.err(`review gate failed — change "${target}" has ${verdict ? `verdict "${verdict}"` : 'no review.md'}`);
+        log.err(`Run /opsx:review ${target} and get an explicit APPROVE before apply/merge.`);
+        process.exitCode = 1;
+        return;
+      }
       log.ok(`review gate passed — ${target}: APPROVE`);
-      return;
+    } else {
+      log.ok('review not required (pipeline.require_spec_review: false)');
     }
 
-    log.err(`review gate failed — change "${target}" has ${verdict ? `verdict "${verdict}"` : 'no review.md'}`);
-    log.err(`Run /opsx:review ${target} and get an explicit APPROVE before apply/merge.`);
-    process.exitCode = 1;
+    if (config.requireDesignBrief) {
+      if (parseDesignBrief(changeDir) || hasDesignOptOut(changeDir)) {
+        log.ok(`design brief gate passed — ${target}`);
+      } else {
+        log.err(`design brief gate failed — change "${target}" has no design-brief.md`);
+        log.err(`Run /opsx:design ${target} (or add "Design: none" to proposal.md for non-UI changes).`);
+        process.exitCode = 1;
+      }
+    }
   });
 
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven pipeline with OpenSpec integration",
   "keywords": [
     "ai-agent",

package/profiles/generic/orchestrator.yaml

@@ -7,6 +7,7 @@ project:
 
 pipeline:
   require_spec_review: true
+  require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
 
@@ -15,6 +16,10 @@ roles:
     command: /opsx:explore
     mode: read-only
     model_hint: fast
+  design_intake:
+    command: /opsx:design
+    mode: brief-only
+    model_hint: strong
   architect:
     command: /opsx:propose
     mode: specs-only

package/profiles/mvp/orchestrator.yaml

@@ -11,6 +11,7 @@ package_manager: npm
 
 pipeline:
   require_spec_review: false
+  require_design_brief: false
   max_active_changes: 3
   archive_after_merge: false
   quick_mode_enabled: true
@@ -20,6 +21,11 @@ roles:
     command: /opsx:explore
     mode: read-only
     model_hint: fast
+  design_intake:
+    command: /opsx:design
+    mode: brief-only
+    model_hint: strong
+    notes: "In quick mode, the same session may create the brief before propose+apply"
   architect:
     command: /opsx:propose
     mode: specs-only

package/profiles/node/orchestrator.yaml

@@ -10,6 +10,7 @@ package_manager: npm
 
 pipeline:
   require_spec_review: true
+  require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
 
@@ -18,6 +19,10 @@ roles:
     command: /opsx:explore
     mode: read-only
     model_hint: fast
+  design_intake:
+    command: /opsx:design
+    mode: brief-only
+    model_hint: strong
   architect:
     command: /opsx:propose
     mode: specs-only

package/profiles/vue3/orchestrator.yaml

@@ -10,6 +10,7 @@ package_manager: npm
 
 pipeline:
   require_spec_review: true
+  require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
 
@@ -18,6 +19,10 @@ roles:
     command: /opsx:explore
     mode: read-only
     model_hint: fast
+  design_intake:
+    command: /opsx:design
+    mode: brief-only
+    model_hint: strong
   architect:
     command: /opsx:propose
     mode: specs-only

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

@@ -0,0 +1,127 @@
+---
+name: /opsx-design
+id: opsx-design
+category: Workflow
+description: Capture design from any source into a durable design brief for an OpenSpec change
+---
+
+Capture design into a durable brief for an OpenSpec change. One-shot intake from Figma, exports, screenshots, or photos — then apply never needs live design tools.
+
+**IMPORTANT: You must NEVER edit any file in `src/` or any source code. You may write only `openspec/changes/<name>/design-brief.md` and files under `openspec/changes/<name>/assets/`.**
+
+**Input**: Optionally specify a change name (e.g., `/opsx:design add-login-form`). If omitted, auto-select if one active change exists, otherwise list and ask. If the change does not exist yet, create the change directory when writing the brief (after explore chose the name).
+
+---
+
+## Steps
+
+### 1. Select the change
+
+If name provided — use it. Otherwise:
+- Run `openspec list --json` to list active changes.
+- Auto-select if only one exists.
+- Ask the user if ambiguous.
+
+Announce: "Design intake for change: **<name>**"
+
+### 2. Choose source (fallback ladder)
+
+Use the first available source; do not climb the ladder twice:
+
+1. **Figma MCP** — one pass only (`get_design_context` / screenshot / metadata). Capture everything needed immediately; never call Figma again during later apply.
+2. **Exported images** — PNG/SVG already in the repo or attached by the user.
+3. **Screenshots** — UI captures (desktop/mobile).
+4. **Photos** — physical mockups or whiteboard photos.
+
+Ask the user for the source if unclear. Prefer Figma when a `figma.com` URL is given.
+
+### 3. Capture into assets/
+
+Save reference images under `openspec/changes/<name>/assets/`:
+- Prefer compressed PNG; ~1–2 images per breakpoint
+- Do not commit raw video, PSD, or huge originals
+- Name files clearly: `desktop.png`, `mobile.png`, `hero-detail.png`
+
+### 4. Write design-brief.md
+
+Create or overwrite `openspec/changes/<name>/design-brief.md` using this template:
+
+```markdown
+# Design Brief
+
+**Change:** <name>
+**Captured:** <ISO date>
+
+## Source
+
+- Type: Figma | export | screenshot | photo
+- URL / path: <figma URL or file path>
+- File key / node ids: <if Figma>
+- Capture date: <ISO date>
+- Notes: <auth, branch, frame names>
+
+## Structure
+
+- Layout hierarchy (sections, regions, key components)
+- Responsive breakpoints if known
+- Navigation / interaction notes relevant to implementation
+
+## Tokens
+
+- Colors: <hex or token names>
+- Typography: <families, sizes, weights>
+- Spacing: <scale or measured gaps>
+- Radii / shadows / borders: <as observed>
+
+## Reference images
+
+- `assets/<file>` — <what it shows>
+
+## Constraints
+
+- Must match: <hard constraints from design>
+- Out of scope / approximate OK: <soft areas>
+- Non-UI change? If this change has no UI, put `Design: none` in `proposal.md` instead of this brief.
+
+## Confidence notes
+
+- Measured / from Figma: <list>
+- Inferred (screenshot/photo): mark each inferred value with a confidence marker, e.g. `~8px (medium confidence)` or `color ≈ #1a1a1a (low confidence)`
+```
+
+### 5. Confidence markers for raster sources
+
+When the source is a **screenshot** or **photo** (not Figma MCP / vector export):
+- Do not present guessed spacing, colors, or type sizes as facts
+- Mark every inferred token/value with a confidence note in **Confidence notes** and inline in **Tokens** where useful
+- Prefer ranges or approximations over fake precision
+
+### 6. Handoff
+
+Output a short summary:
+
+```
+## Design Intake Complete
+
+**Change:** <name>
+**Brief:** openspec/changes/<name>/design-brief.md
+**Assets:** N file(s) under assets/
+
+### Next
+- Continue with `/opsx:propose <name>` if artifacts are missing
+- Or `/opsx:apply <name>` — Implementer must use the brief, not live Figma MCP
+```
+
+For non-UI changes: do not invent a brief. Tell the Architect to add a line `Design: none` in `proposal.md` so `gate-check` can opt out when `require_design_brief: true`.
+
+---
+
+## Guardrails
+
+- **Never** edit source code or `src/`
+- **Never** edit `tasks.md`, `review.md`, or other OpenSpec artifacts except creating the change folder if needed for the brief
+- **May write only** `openspec/changes/<name>/design-brief.md` and `openspec/changes/<name>/assets/*`
+- **Never** rely on a second Figma MCP pass later — store everything in the brief now
+- **Never** tell apply sessions to open live Figma; point them at the brief + assets
+- Keep `assets/` small (compressed PNG, few files)
+- Ask for clarification only if the source is missing or unreadable

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

@@ -5,10 +5,11 @@ alwaysApply: true
 
 # Agent Orchestration Rules
 
-This project uses a spec-driven 5-role pipeline. Read `.agents/orchestrator.yaml` for config.
+This project uses a spec-driven role pipeline. Read `.agents/orchestrator.yaml` for config.
 
 ## Role Commands
 - `/opsx:explore` → read-only thinking, no code
+- `/opsx:design <name>` → writes only `design-brief.md` + `assets/` (optional design intake)
 - `/opsx:propose <name>` → creates `openspec/changes/<name>/` artifacts only
 - `/opsx:review <name>` → read-only spec review, writes `review.md`, outputs Approve or Request Changes
 - `/opsx:apply <name>` → writes `src/`, marks `tasks.md [x]` (blocked if no review when `require_spec_review: true`)
@@ -18,13 +19,17 @@ This project uses a spec-driven 5-role pipeline. Read `.agents/orchestrator.yaml
 ## Session Rules
 - One active change at a time (unless mvp profile: up to 3)
 - Each role = new chat session (except `/opsx:quick` combines propose+apply)
-- No code in explore or review sessions
+- No code in explore, design, or review sessions
+- Design Intake may write only `openspec/changes/<name>/design-brief.md` and `assets/`
 - No apply without review when `pipeline.require_spec_review: true` — check `review.md` or Approve in context
+- When `require_design_brief: true` and the change touches UI — need `design-brief.md`, or `Design: none` in `proposal.md` for non-UI
+- 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`)
 
 ## Never
 - Mix propose and apply in one session
-- Edit `src/` during explore or review
+- Edit `src/` during explore, design, or review
 - Skip spec review before apply
+- Call live Figma MCP during apply when a design brief exists
 - Leave changes un-archived after merge

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

@@ -5,7 +5,7 @@ alwaysApply: true
 
 # OpenSpec Workflow (/opsx)
 
-`/opsx:explore`, `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `/opsx:sync`, `/opsx:review`, `/opsx:quick` — AI workflow commands, not source code.
+`/opsx:explore`, `/opsx:design`, `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `/opsx:sync`, `/opsx:review`, `/opsx:quick` — AI workflow commands, not source code.
 
 ## File Locations
 
@@ -15,12 +15,14 @@ alwaysApply: true
 | Skills | `.agents/skills/` |
 | Specs (source of truth) | `openspec/specs/` |
 | Active changes | `openspec/changes/` |
+| Design brief | `openspec/changes/<name>/design-brief.md` + `assets/` |
 | Project config | `openspec/config.yaml` |
 | Orchestration config | `.agents/orchestrator.yaml` |
 
 ## Command → Skill Mapping
 
 - `/opsx:explore` → skill `openspec-explore` (thinking only)
+- `/opsx:design <name>` → command `opsx-design` (writes design-brief.md + assets/)
 - `/opsx:propose <name>` → skill `openspec-propose`
 - `/opsx:review <name>` → command `opsx-review` (read-only, writes review.md)
 - `/opsx:apply` → skill `openspec-apply-change`

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

@@ -3,7 +3,7 @@ name: agent-orchestration
 description: >
   Spec-driven AI agent pipeline orchestration built on OpenSpec. Load when deciding which
   role/command to use, how to handoff between phases, which model to pick, or when a session
-  should stop and a new one start. Commands: /opsx:explore, /opsx:propose, /opsx:review,
+  should stop and a new one start. Commands: /opsx:explore, /opsx:design, /opsx:propose, /opsx:review,
   /opsx:apply, /opsx:archive, /opsx:quick.
 disable-model-invocation: false
 allowed-tools: Bash, Read
@@ -17,13 +17,16 @@ is the primary source of wasted tokens and failed implementations.
 ## Pipeline
 
 ```
-explore → propose → review → apply → verify → archive
+explore → [design] → propose → review → apply → verify → archive
 ```
 
+`[design]` is optional (`/opsx:design`) — capture UI into `design-brief.md` + `assets/` so apply does not depend on live Figma.
+
 **MVP profile** (`require_spec_review: false`):
 ```
 explore → quick (propose+apply) → verify → archive (optional)
 ```
+In quick mode the same session may create the design brief before propose+apply.
 
 Read `.agents/orchestrator.yaml` for project-specific config (language, flags, MCP, review gate).
 
@@ -32,6 +35,7 @@ Read `.agents/orchestrator.yaml` for project-specific config (language, flags, M
 | Role | Command | Mode | Model hint | Allowed output |
 |------|---------|------|------------|----------------|
 | Explorer | `/opsx:explore` | read-only | fast | chat only |
+| Design Intake | `/opsx:design <name>` | brief-only | strong | `design-brief.md`, `assets/` |
 | Architect | `/opsx:propose <name>` | specs-only | strong | `openspec/changes/` |
 | Spec Reviewer | `/opsx:review <name>` | read-only | medium | `review.md`, Approve / Request Changes |
 | Implementer | `/opsx:apply <name>` | code | strong | `src/`, `tasks.md [x]` |
@@ -40,6 +44,19 @@ Read `.agents/orchestrator.yaml` for project-specific config (language, flags, M
 
 ## Handoff Protocol
 
+### explore → design (optional)
+Exit Explorer into Design Intake when:
+- Change has UI and a Figma URL, export, screenshot, or photo is available
+- kebab-case change name chosen
+
+Start Design Intake with:
+```
+/opsx:design <name>
+```
+
+### design → propose
+Exit Design Intake when `design-brief.md` (+ `assets/`) is written. Non-UI changes: skip design and put `Design: none` in `proposal.md` when `require_design_brief: true`.
+
 ### explore → propose
 Exit Explorer when:
 - Problem is stated in 3–5 sentences
@@ -57,7 +74,6 @@ Context from explore:
 - Non-goals: ...
 - Draft acceptance: ...
 ```
-
 ### propose → review
 Exit Architect when:
 ```bash
@@ -74,7 +90,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.
+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`).
 
 ### apply → verify
 Exit Implementer when:
@@ -82,6 +98,7 @@ Exit Implementer when:
 - `npm run build` (or project build cmd) exits 0
 - `npm run lint` exits 0
 - Commit ready
+- UI work followed `design-brief.md` — do **not** open live Figma MCP in the apply session
 
 ### verify → archive
 After PR merged + CI green:
@@ -93,7 +110,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 progress for every active change at a glance
+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
 3. Read `orchestrator.yaml` for project config and review gate
 
 **During session:**
@@ -111,6 +128,7 @@ After PR merged + CI green:
 | Phase | Use case | Recommended |
 |-------|----------|-------------|
 | explore | Q&A, brainstorm | fast (rush/flash) |
+| design | Vision / layout capture | strong (vision-capable) |
 | propose | Architecture decisions | strong (opus/sonnet) |
 | review | Artifact analysis | medium or strong |
 | apply complex | Multi-file refactor | strong |
@@ -146,6 +164,7 @@ At start of new session: read relevant entities to restore context without re-ex
 |-------------|--------|
 | Explore + propose in one chat | Architect has stale exploration context |
 | Apply without review | ~60% chance of rework |
+| Live Figma MCP in apply session | Token/quota loss; context not durable across sessions |
 | All tasks in one apply session | Context overload; model drifts |
 | No archive after merge | Next propose has stale domain specs |
 | Strong model on lint fixes | 5–10x cost with no quality gain |

package/templates/AGENTS.md

@@ -8,9 +8,11 @@ Every feature follows the same cycle regardless of stack or IDE.
 ## Pipeline
 
 ```
-explore → propose → review → apply → verify → archive
+explore → [design] → propose → review → apply → verify → archive
 ```
 
+`[design]` is optional — run `/opsx:design` when the change has UI and you need a durable design brief (Figma, screenshot, or photo). Skip for non-UI work; use `Design: none` in `proposal.md` when `require_design_brief: true`.
+
 Each phase runs in a **separate agent session** with a dedicated role, model hint, and permissions.
 Never mix phases in one chat — this is the single most important rule.
 
@@ -19,6 +21,7 @@ Never mix phases in one chat — this is the single most important rule.
 | Role | Command | Mode | Model hint |
 |------|---------|------|------------|
 | Explorer | `/opsx:explore` | read-only | fast |
+| Design Intake | `/opsx:design <name>` | writes `design-brief.md` + `assets/` only | strong |
 | Architect | `/opsx:propose <name>` | writes `openspec/changes/` only | strong |
 | Spec Reviewer | `/opsx:review <name>` | read-only | medium/strong |
 | Implementer | `/opsx:apply <name>` | writes `src/` | strong |
@@ -28,13 +31,13 @@ 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`). Run `agent-orchestrator-kit status` at the start of any session to see task progress, review verdict, and archive readiness for every active change without querying `openspec` per change.
+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.
 
 ## Hard Rules
 
 - **One active change per developer** at a time.
 - **No apply without spec-review approval** (explicit Approve in chat).
-- **No code edits** during explore or spec-review sessions.
+- **No code edits** during explore, design-intake, or spec-review sessions.
 - **Archive after every merge** (`/opsx:archive`).
 - **Always run local build/lint** before opening a PR.
 
@@ -42,7 +45,9 @@ Both CI fragments also run `agent-orchestrator-kit gate-check` — a determinist
 
 | Transition | Gate |
 |------------|------|
-| explore → propose | Decision brief written; change name chosen |
+| 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 ✓ |
 | review → apply | Reviewer writes explicit **Approve** — enforced in CI by `gate-check` |
 | apply → verify | All `tasks.md` checkboxes `[x]`; local build OK |
@@ -53,9 +58,10 @@ Both CI fragments also run `agent-orchestrator-kit gate-check` — a determinist
 | Role | Attach (`@`) |
 |------|-------------|
 | Explorer | `@openspec/specs/` + relevant `@src/` subtree |
-| Architect | `@openspec/config.yaml` + explore brief |
+| Design Intake | design source (Figma URL / images) + `@openspec/changes/<name>/` |
+| Architect | `@openspec/config.yaml` + explore brief (+ `@design-brief.md` if present) |
 | Reviewer | entire `@openspec/changes/<name>/` |
-| Implementer | `@openspec/changes/<name>/tasks.md` |
+| Implementer | `@openspec/changes/<name>/tasks.md` + `@openspec/changes/<name>/design-brief.md` |
 
 ## Configuration
 

package/templates/CLAUDE.md

@@ -24,6 +24,7 @@ Use `/skill-name` or let Claude auto-load based on context.
 
 ```
 /opsx:explore   — think through ideas (read-only, no code)
+/opsx:design    — capture design into design-brief.md + assets/ (optional)
 /opsx:propose   — create change artifacts
 /opsx:review    — spec review (read-only, no code)
 /opsx:apply     — implement tasks
@@ -34,7 +35,8 @@ Use `/skill-name` or let Claude auto-load based on context.
 
 - Check `.agents/orchestrator.yaml` for project-specific pipeline config.
 - One active change at a time — run `openspec list` to confirm.
-- No code edits in explore or review mode.
+- 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.
 
@@ -43,6 +45,7 @@ Use `/skill-name` or let Claude auto-load based on context.
 | What | Where |
 |------|-------|
 | Active changes | `openspec/changes/` |
+| Design brief | `openspec/changes/<name>/design-brief.md` + `assets/` |
 | Specs (source of truth) | `openspec/specs/` |
 | Project config | `openspec/config.yaml` |
 | Orchestration config | `.agents/orchestrator.yaml` |

package/templates/orchestrator.yaml

@@ -9,6 +9,7 @@ package_manager: npm
 
 pipeline:
   require_spec_review: true
+  require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
 
@@ -17,6 +18,10 @@ roles:
     command: /opsx:explore
     mode: read-only
     model_hint: fast
+  design_intake:
+    command: /opsx:design
+    mode: brief-only
+    model_hint: strong
   architect:
     command: /opsx:propose
     mode: specs-only