agent-orchestrator-kit 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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

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`):
 
@@ -648,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
@@ -673,6 +699,11 @@ 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

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 = [
@@ -439,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');
@@ -491,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'), {
@@ -578,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);
@@ -586,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');
   });
@@ -603,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');
@@ -618,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');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.9",
-  "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/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/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