agent-orchestrator-kit 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.10] - 2026-07-15
+
+### Added
+- **Custom subagents** — new `.agents/subagents/` asset category, synced to `.cursor/agents/` and `.claude/agents/` (like skills/rules, delete-stale semantics on `sync`)
+- 6 default subagents: `openspec-guide` (pipeline navigator, read-only), `code-writer` (scoped task implementation), `code-reviewer` (spec-compliance + convention review), `test-writer` (test authoring), `setup-doctor` (orchestrator setup diagnosis/repair), `design-implementer` (pixel-accurate Figma/screenshot → code, honors design-brief priority)
+- **Amp support via skill wrappers** — Amp has no file-based subagents, so `init`/`update`/`sync` auto-generate a committed `.agents/skills/subagent-<name>/SKILL.md` wrapper per subagent (Amp loads `.agents/skills/` natively); wrappers are excluded from `.cursor/`/`.claude/` skill sync and removed when the source subagent is deleted
+- `update` and `sync --target cursor|claude|all` now manage `.agents/subagents/` alongside skills and rules
+- `scripts/sync-local-agent-skills.sh` generates Amp wrappers and rsyncs `.agents/subagents/` → `.cursor/agents/` and `.claude/agents/`
+
+### Fixed
+- `update` no longer resurrects a CI workflow file the project deleted (e.g. `.github/workflows/agent-verify.yml` after switching to GitLab CI) — CI files are refreshed only when already present
+- `update` keeps `scripts/sync-local-agent-skills.sh` executable
+
+## [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

package/README.md

@@ -1,24 +1,39 @@
 # agent-orchestrator-kit
 
-Universal AI agent orchestration kit for **Cursor**, **Claude Code**, and **Amp Code** — spec-driven pipeline built on [OpenSpec](https://github.com/fission-ai/openspec).
+Universal AI agent orchestration kit for **Cursor**, **Claude Code**, and **Amp Code** — spec-driven OpenSpec pipeline with **cross-IDE custom subagents**.
 
 [![npm version](https://img.shields.io/npm/v/agent-orchestrator-kit)](https://www.npmjs.com/package/agent-orchestrator-kit)
 [![license](https://img.shields.io/npm/l/agent-orchestrator-kit)](LICENSE)
 
 ## What It Is
 
-A portable kit that installs a **5-role AI pipeline** into any project:
+A portable kit that installs a **role-separated AI pipeline** into any project:
 
 ```
-explore → propose → review → apply → verify → archive
+explore → [design] → propose → review → apply → verify → archive
 ```
 
 Each role runs in a **separate agent session** with dedicated permissions, model hints, and handoff gates. The `openspec/changes/` folder acts as the **contract between agents** — no shared memory between sessions, only files.
 
+**Custom subagents (v0.1.10+)** ship with the kit and work in all three IDEs:
+
+| Subagent | Role |
+|----------|------|
+| `openspec-guide` | Pipeline navigator — status, gates, next `/opsx:*` command |
+| `code-writer` | Scoped task implementation against stack conventions |
+| `code-reviewer` | Spec-compliance + convention review of the resulting code |
+| `test-writer` | Automated tests for recently changed code |
+| `setup-doctor` | Orchestrator / MCP / sync diagnosis and repair |
+| `design-implementer` | Pixel-accurate Figma / screenshot → production UI |
+
+- **Cursor** → `.cursor/agents/` (native subagents)
+- **Claude Code** → `.claude/agents/` (native subagents)
+- **Amp Code** → auto-generated `subagent-*` skill wrappers in `.agents/skills/` (Amp has no file-based subagents)
+
 Works with:
-- [Cursor](https://cursor.sh) — via `.cursor/rules/` + `.cursor/skills/`
-- [Claude Code](https://code.claude.com) — via `CLAUDE.md` + `.claude/skills/`
-- [Amp Code](https://ampcode.com) — via `AGENTS.md` + `.agents/skills/` (native, no sync needed)
+- [Cursor](https://cursor.sh) — via `.cursor/rules/` + `.cursor/skills/` + `.cursor/agents/`
+- [Claude Code](https://code.claude.com) — via `CLAUDE.md` + `.claude/skills/` + `.claude/agents/`
+- [Amp Code](https://ampcode.com) — via `AGENTS.md` + `.agents/skills/` (native, including `subagent-*` wrappers)
 
 ## Why
 
@@ -38,15 +53,15 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Get `status` / `gate-check` / GitHub Spec Verifier (v0.1.7+):**
+**🔄 Already have the kit installed? Upgrade to latest (subagents in v0.1.10+):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
-./scripts/sync-local-agent-skills.sh
-npx agent-orchestrator-kit@latest status       # try it right away
+npx agent-orchestrator-kit@latest sync         # or: ./scripts/sync-local-agent-skills.sh
+npx agent-orchestrator-kit@latest status
 ```
 
-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.
+This refreshes kit-managed files, installs `.agents/subagents/`, generates Amp `subagent-*` skill wrappers, and syncs agents into `.cursor/agents/` + `.claude/agents/`. See [Changelog](#changelog) for the full list.
 
 ## Installation
 
@@ -130,6 +145,7 @@ your-project/
 │   ├── amp.settings.json.example        # Amp MCP template
 │   ├── commands/                        # 6 /opsx:* commands
 │   ├── rules/                           # 3 auto-applied rules
+│   ├── subagents/                       # 6 default custom subagents (Cursor/Claude/Amp)
 │   └── skills/
 │       ├── agent-orchestration/         # Pipeline orchestration
 │       ├── openspec-howto/
@@ -149,7 +165,8 @@ your-project/
 |----------|----------|
 | Orchestration | 5-role pipeline, `AGENTS.md`, `orchestrator.yaml`, review command |
 | OpenSpec skills | All 7 skills for `/opsx:*` workflow |
-| IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills) |
+| IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills/subagents) |
+| Subagents | `openspec-guide`, `code-writer`, `code-reviewer`, `test-writer`, `setup-doctor`, `design-implementer` — native in Cursor (`.cursor/agents/`) + Claude Code (`.claude/agents/`), exposed to Amp as auto-generated `subagent-*` skill wrappers in `.agents/skills/` |
 | CLI gates | `agent-orchestrator status` / `gate-check` — deterministic review-gate checks |
 | CI | `agent-verify.yml` — GitHub (default) or GitLab fragment + `prebuild` hook, both run `gate-check` |
 | AI Spec Verifier | `spec-verify.yml` + verifier scripts — GitLab or GitHub, opt-in (`--spec-verify`) |
@@ -183,6 +200,8 @@ cp .agents/amp.settings.json.example .amp/settings.json
 
 Or run `./scripts/sync-local-agent-skills.sh` — it creates `.amp/settings.json` automatically.
 
+**Subagents in Amp:** Amp has no file-based custom subagents (only skills and plugin agents), so the kit exposes every `.agents/subagents/<name>.md` as an auto-generated skill `subagent-<name>` in `.agents/skills/`. These wrappers are committed to git, so Amp picks them up with zero local setup — just say "use the subagent-design-implementer skill" or let Amp auto-load it from the description. Edit the source file in `.agents/subagents/` (never the wrapper) and re-run `sync` to regenerate.
+
 4. Use commands directly:
 
 ```
@@ -210,9 +229,10 @@ Switch modes in Amp CLI: `Ctrl+O` → `mode`.
 1. Run sync: `./scripts/sync-local-agent-skills.sh`
 2. This creates:
    - `.claude/CLAUDE.md` — project context
-   - `.claude/skills/` — all skills from `.agents/skills/`
+   - `.claude/skills/` — all skills from `.agents/skills/` (excluding Amp `subagent-*` wrappers)
+   - `.claude/agents/` — custom subagents from `.agents/subagents/` (native Claude Code subagents)
 3. Skills are auto-loaded by Claude Code from `.claude/skills/`.
-4. Invoke directly: `/agent-orchestration`, `/openspec-howto`, etc.
+4. Invoke directly: `/agent-orchestration`, `/openspec-howto`, etc. Subagents are delegated automatically by description or on request ("use the design-implementer subagent").
 
 **CLAUDE.md tiers used:**
 - Project level: `.claude/CLAUDE.md` (synced from `CLAUDE.md`)
@@ -237,8 +257,10 @@ You can add `context: fork` to explore/review skills for isolated subagent sessi
 2. Creates:
    - `.cursor/skills/` — all skills
    - `.cursor/rules/` — `.mdc` rule files
+   - `.cursor/agents/` — custom subagents (`openspec-guide`, `code-writer`, `code-reviewer`, `test-writer`, `setup-doctor`, `design-implementer`)
    - `.mcp.json` — from `mcp.json.example` (if not present)
 3. Rules are applied automatically per `alwaysApply: true`.
+4. Subagents are invoked by name in chat (e.g. "use the code-reviewer subagent on this diff") or delegated to automatically by Cursor when their `description` matches the task. Add project-specific subagents by dropping `.md` files into `.agents/subagents/` and re-running sync.
 
 **Memory MCP for Cursor** (`.mcp.json`):
 
@@ -411,13 +433,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
+```
 
 ---
 
@@ -441,6 +504,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
 
@@ -606,16 +670,20 @@ npx agent-orchestrator-kit gate-check [change-name] [options]
 .agents/                 # Committed — source of truth for all IDEs
   commands/              # /opsx:* command definitions
   rules/                 # Auto-applied rules for Cursor
+  subagents/             # Custom subagents (source of truth, all IDEs)
   skills/                # Skills for Cursor, Claude Code, Amp
+                         #   subagent-*/ — auto-generated Amp wrappers (do not edit)
   orchestrator.yaml      # Project pipeline config
 
 .cursor/                 # Local only — Cursor IDE runtime
   skills/                # Synced from .agents/skills/
   rules/                 # Synced from .agents/rules/
+  agents/                # Synced from .agents/subagents/
   memory.json            # Memory MCP data
 
 .claude/                 # Local only — Claude Code runtime
   skills/                # Synced from .agents/skills/
+  agents/                # Synced from .agents/subagents/
   CLAUDE.md              # Synced from root CLAUDE.md
 
 .amp/                    # Local only — Amp config
@@ -631,6 +699,16 @@ openspec/                # Committed — spec-driven workflow
 
 ## Changelog
 
+### 0.1.10
+- Custom subagents (`.agents/subagents/`) synced to `.cursor/agents/` + `.claude/agents/`, exposed to Amp via auto-generated `subagent-*` skill wrappers
+- 6 default subagents: `openspec-guide`, `code-writer`, `code-reviewer`, `test-writer`, `setup-doctor`, `design-implementer`
+- `update` no longer resurrects deleted CI workflow files
+
+### 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
 

package/bin/agent-orchestrator.js

@@ -26,12 +26,17 @@ const KIT_SKILL_DIRS = [
 const KIT_MANAGED_PATHS = [
   '.agents/commands',
   '.agents/rules',
+  '.agents/subagents',
   ...KIT_SKILL_DIRS.map((s) => `.agents/skills/${s}`),
-  '.github/workflows/agent-verify.yml',
-  '.gitlab/agent-verify.yml',
   'scripts/sync-local-agent-skills.sh',
 ];
 
+// CI workflow files are provider-specific and chosen once at `init --ci`.
+// `update` must only refresh them if already present — never resurrect a
+// workflow file for a provider the project doesn't use (e.g. after switching
+// from GitHub Actions to GitLab CI and deleting the GitHub workflow).
+const CI_WORKFLOW_PATHS = ['.github/workflows/agent-verify.yml', '.gitlab/agent-verify.yml'];
+
 // Opt-in AI Spec Verifier files, per CI provider. `scripts/verify-specs.sh` is
 // shared — it is stack- and CI-agnostic already.
 const GITLAB_SPEC_VERIFY_PATHS = [
@@ -178,14 +183,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,
   };
 }
@@ -426,8 +444,65 @@ function printNextSteps(profile, projectDir, ci = 'github', specVerify = false)
   console.log('\n' + lines.join('\n') + '\n');
 }
 
+// Amp has no file-based custom subagents (only skills and plugin agents), but
+// it natively loads skills from .agents/skills/ with the same description-driven
+// delegation. Each .agents/subagents/<name>.md therefore gets a committed skill
+// wrapper .agents/skills/subagent-<name>/SKILL.md so subagents work in Amp with
+// zero local setup. Wrappers are regenerated on init/update/sync and stale ones
+// are removed when their source subagent is deleted.
+const AMP_SUBAGENT_SKILL_PREFIX = 'subagent-';
+
+function listAmpSubagentWrappers(projectDir) {
+  const skillsDir = join(projectDir, '.agents', 'skills');
+  if (!existsSync(skillsDir)) return [];
+  return readdirSync(skillsDir).filter((entry) => entry.startsWith(AMP_SUBAGENT_SKILL_PREFIX));
+}
+
+function generateAmpSubagentSkills(projectDir) {
+  const subagentsDir = join(projectDir, '.agents', 'subagents');
+  const skillsDir = join(projectDir, '.agents', 'skills');
+  const expected = new Set();
+
+  if (existsSync(subagentsDir)) {
+    for (const file of readdirSync(subagentsDir).filter((f) => f.endsWith('.md'))) {
+      const content = readFileSync(join(subagentsDir, file), 'utf-8');
+      const parsed = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+      const name = parsed?.[1].match(/^name:\s*(.+)$/m)?.[1]?.trim();
+      const description = parsed?.[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
+      if (!name || !description) {
+        log.warn(`skip Amp wrapper (missing name/description frontmatter): .agents/subagents/${file}`);
+        continue;
+      }
+
+      const skillName = `${AMP_SUBAGENT_SKILL_PREFIX}${name}`;
+      expected.add(skillName);
+      mkdirSync(join(skillsDir, skillName), { recursive: true });
+      const skill = [
+        '---',
+        `name: ${skillName}`,
+        `description: ${description}`,
+        '---',
+        '',
+        `<!-- AUTO-GENERATED from .agents/subagents/${file} — edit the source file, then run: npx agent-orchestrator-kit sync -->`,
+        '',
+        parsed[2].trim(),
+        '',
+      ].join('\n');
+      writeFileSync(join(skillsDir, skillName, 'SKILL.md'), skill);
+      log.ok(`.agents/skills/${skillName}/SKILL.md (Amp wrapper)`);
+    }
+  }
+
+  for (const entry of listAmpSubagentWrappers(projectDir)) {
+    if (!expected.has(entry)) {
+      rmSync(join(projectDir, '.agents', 'skills', entry), { recursive: true, force: true });
+      log.warn(`removed stale Amp wrapper: .agents/skills/${entry}`);
+    }
+  }
+}
+
 function syncAmp(projectDir) {
-  log.info('Amp Code reads .agents/ natively — no skill sync needed');
+  log.info('Amp Code reads .agents/ natively — subagents exposed via skill wrappers');
   mkdirSync(join(projectDir, '.amp'), { recursive: true });
   const ampExample = join(projectDir, '.agents', 'amp.settings.json.example');
   const ampDest = join(projectDir, '.amp', 'settings.json');
@@ -478,6 +553,7 @@ program
     if (existsSync(join(profileDir, '.agents'))) {
       copyDir(join(profileDir, '.agents'), join(projectDir, '.agents'), { overwrite: opts.force });
     }
+    generateAmpSubagentSkills(projectDir);
 
     log.title('Installing scripts/');
     copyDir(join(templateDir, 'scripts'), join(projectDir, 'scripts'), {
@@ -565,6 +641,16 @@ program
       }
     }
 
+    generateAmpSubagentSkills(projectDir);
+
+    for (const rel of CI_WORKFLOW_PATHS) {
+      const src = join(templateDir, rel);
+      const dest = join(projectDir, rel);
+      if (!existsSync(src) || !existsSync(dest)) continue;
+      copyFileSync(src, dest);
+      log.ok(rel);
+    }
+
     for (const rel of KIT_OPTIN_PATHS) {
       const src = join(templateDir, rel);
       const dest = join(projectDir, rel);
@@ -573,6 +659,10 @@ program
       log.ok(`${rel} (opt-in)`);
     }
 
+    try {
+      execSync(`chmod +x ${join(projectDir, 'scripts', 'sync-local-agent-skills.sh')}`);
+    } catch {}
+
     log.ok(`Updated to v${KIT_VERSION}`);
     log.info('Run ./scripts/sync-local-agent-skills.sh to sync to local IDE');
   });
@@ -590,10 +680,20 @@ program
     const syncClaude = ['claude', 'all'].includes(opts.target);
     const syncAmpTarget = ['amp', 'all'].includes(opts.target);
 
+    generateAmpSubagentSkills(projectDir);
+
+    // Amp skill wrappers are redundant in Cursor/Claude (they get native
+    // subagents from .agents/subagents/), so exclude them from skill sync.
+    const ampWrappers = listAmpSubagentWrappers(projectDir);
+
     if (syncCursor) {
       log.info('Syncing .agents/ → .cursor/');
-      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.cursor', 'skills'), { overwrite: true, delete: true });
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.cursor', 'skills'), { overwrite: true, delete: true, skip: ampWrappers });
+      for (const wrapper of ampWrappers) {
+        rmSync(join(projectDir, '.cursor', 'skills', wrapper), { recursive: true, force: true });
+      }
       copyDir(join(projectDir, '.agents', 'rules'), join(projectDir, '.cursor', 'rules'), { overwrite: true, delete: true });
+      copyDir(join(projectDir, '.agents', 'subagents'), join(projectDir, '.cursor', 'agents'), { overwrite: true, delete: true });
 
       const mcpExample = join(projectDir, '.agents', 'mcp.json.example');
       const mcpDest = join(projectDir, '.mcp.json');
@@ -605,7 +705,11 @@ program
 
     if (syncClaude) {
       log.info('Syncing .agents/ → .claude/');
-      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.claude', 'skills'), { overwrite: true, delete: true });
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.claude', 'skills'), { overwrite: true, delete: true, skip: ampWrappers });
+      for (const wrapper of ampWrappers) {
+        rmSync(join(projectDir, '.claude', 'skills', wrapper), { recursive: true, force: true });
+      }
+      copyDir(join(projectDir, '.agents', 'subagents'), join(projectDir, '.claude', 'agents'), { overwrite: true, delete: true });
 
       const claudeMd = join(projectDir, 'CLAUDE.md');
       const claudeDir = join(projectDir, '.claude');
@@ -643,6 +747,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 +755,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 +776,7 @@ program
       return;
     }
 
-    if (!config.requireSpecReview) {
+    if (!config.requireSpecReview && !config.requireDesignBrief) {
       log.ok('review not required (pipeline.require_spec_review: false)');
       return;
     }
@@ -709,15 +815,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,7 +1,7 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.8",
-  "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven pipeline with OpenSpec integration",
+  "version": "0.1.10",
+  "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline with cross-IDE custom subagents (openspec-guide, code-writer, code-reviewer, test-writer, setup-doctor, design-implementer)",
   "keywords": [
     "ai-agent",
     "cursor",
@@ -10,6 +10,9 @@
     "openspec",
     "sdd",
     "agent-orchestration",
+    "subagents",
+    "custom-subagents",
+    "design-to-code",
     "developer-tools"
   ],
   "author": "Maksim Shevyakov <makshc2>",

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/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 (`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 `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.
+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,25 @@
+---
+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. 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/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

package/templates/scripts/sync-local-agent-skills.sh

@@ -21,18 +21,59 @@ echo ""
 echo "sync-local-agent-skills"
 echo "-----------------------"
 
+# ── Amp subagent skill wrappers ────────────────────────────────────────
+# Amp has no file-based subagents; it loads skills from .agents/skills/.
+# Generate a skill wrapper per subagent so they work in Amp too.
+if [ -d .agents/subagents ]; then
+  echo ""
+  info "Generating Amp skill wrappers from .agents/subagents/"
+
+  for old in .agents/skills/subagent-*; do
+    [ -d "$old" ] && rm -rf "$old"
+  done
+
+  for sub in .agents/subagents/*.md; do
+    [ -f "$sub" ] || continue
+    NAME="$(awk '/^---$/{c++; next} c==1 && /^name:/{sub(/^name:[ \t]*/,""); print; exit}' "$sub")"
+    DESC="$(awk '/^---$/{c++; next} c==1 && /^description:/{sub(/^description:[ \t]*/,""); print; exit}' "$sub")"
+    if [ -z "$NAME" ] || [ -z "$DESC" ]; then
+      warn "skip (no name/description): $sub"
+      continue
+    fi
+    DIR=".agents/skills/subagent-${NAME}"
+    mkdir -p "$DIR"
+    {
+      echo "---"
+      echo "name: subagent-${NAME}"
+      echo "description: ${DESC}"
+      echo "---"
+      echo ""
+      echo "<!-- AUTO-GENERATED from ${sub} — edit the source file, then re-run this script -->"
+      echo ""
+      awk '/^---$/{c++; next} c>=2{print}' "$sub"
+    } > "$DIR/SKILL.md"
+    ok "$DIR/SKILL.md"
+  done
+fi
+
 # ── Cursor ─────────────────────────────────────────────────────────────
 echo ""
 info "Syncing → .cursor/ (Cursor)"
-mkdir -p .cursor/skills .cursor/rules
+mkdir -p .cursor/skills .cursor/rules .cursor/agents
 
-rsync -a --delete .agents/skills/ .cursor/skills/
+rsync -a --delete --exclude 'subagent-*' .agents/skills/ .cursor/skills/
+rm -rf .cursor/skills/subagent-*
 ok ".cursor/skills/"
 
 for rule in .agents/rules/*.mdc; do
   [ -f "$rule" ] && cp "$rule" .cursor/rules/ && ok ".cursor/rules/$(basename "$rule")"
 done
 
+if [ -d .agents/subagents ]; then
+  rsync -a --delete .agents/subagents/ .cursor/agents/
+  ok ".cursor/agents/"
+fi
+
 if [ ! -f .mcp.json ] && [ -f .agents/mcp.json.example ]; then
   cp .agents/mcp.json.example .mcp.json
   ok ".mcp.json created from example"
@@ -43,11 +84,17 @@ fi
 # ── Claude Code ────────────────────────────────────────────────────────
 echo ""
 info "Syncing → .claude/ (Claude Code)"
-mkdir -p .claude/skills
+mkdir -p .claude/skills .claude/agents
 
-rsync -a --delete .agents/skills/ .claude/skills/
+rsync -a --delete --exclude 'subagent-*' .agents/skills/ .claude/skills/
+rm -rf .claude/skills/subagent-*
 ok ".claude/skills/"
 
+if [ -d .agents/subagents ]; then
+  rsync -a --delete .agents/subagents/ .claude/agents/
+  ok ".claude/agents/"
+fi
+
 if [ -f CLAUDE.md ]; then
   cp CLAUDE.md .claude/CLAUDE.md
   ok ".claude/CLAUDE.md"
@@ -55,7 +102,7 @@ fi
 
 # ── Amp Code ───────────────────────────────────────────────────────────
 echo ""
-info "Amp Code reads .agents/ directly — no sync needed"
+info "Amp Code reads .agents/ directly — subagents exposed via skill wrappers"
 mkdir -p .amp
 if [ ! -f .amp/settings.json ] && [ -f .agents/amp.settings.json.example ]; then
   cp .agents/amp.settings.json.example .amp/settings.json