agent-orchestrator-kit 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [0.1.11] - 2026-07-21
+
+### Added
+- **Figma personal token setup** — local `.agents/figma.local.env` (gitignored) + committed `.agents/figma.local.env.example`
+- **`scripts/figma-mcp-launcher.cjs`** — starts `figma-developer-mcp` with token from the env file (no secret in `.mcp.json`)
+- **CLI** — `figma-setup`, `figma-status`, `figma-fetch` (REST file/nodes JSON via `X-Figma-Token`)
+- Cursor/Amp MCP examples include optional `figma` server pointing at the launcher
+- Agent rule `figma-token-setup.mdc`; setup-doctor + `/opsx:design` guidance (never ask for token in chat)
+- `orchestrator.yaml` / profiles: `mcp.optional` includes `figma` + `figma.env_file` metadata
+
+### Fixed
+- **Amp / agent PATH** — templates now document and require `npx` / `npm run` for OpenSpec and `agent-orchestrator-kit` CLIs (bare binaries often exit 127 in Amp shells)
+- Added always-apply rule `templates/.agents/rules/cli-via-npm.mdc`; updated openspec skills/commands, `AGENTS.md`, `CLAUDE.md`, `orchestrator.yaml` `cli.*` hints
+- Never recommend `openspec validate --strict` without `<name>` / `--all`
+
+## [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,41 @@
 # 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.
 
+**Figma PAT setup (v0.1.11+)** — local `.agents/figma.local.env` + MCP launcher (token never in chat / committed MCP JSON). See [Figma token](#figma-token-optional).
+
+**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 +55,16 @@ 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 (Figma PAT in v0.1.11+, 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 figma-setup  # optional — local Figma token
+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 +148,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,8 +168,9 @@ 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) |
-| CLI gates | `agent-orchestrator status` / `gate-check` — deterministic review-gate checks |
+| 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 | `npx agent-orchestrator-kit status` / `gate-check` — deterministic review-gate checks (always via `npx`; see `cli-via-npm.mdc`) |
 | 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`) |
 | MCP templates | Memory MCP for Cursor and Amp |
@@ -173,6 +193,8 @@ Local only (not committed): `.cursor/` `.claude/` `.amp/`
 
 Amp reads `.agents/skills/` and `AGENTS.md` **natively** — no sync needed.
 
+**CLI note:** Amp shells often lack global `openspec` / `agent-orchestrator-kit` on PATH (exit 127). Agents must use `npx …` / `npm run …` — see always-apply rule `.agents/rules/cli-via-npm.mdc`.
+
 1. Install the kit → `AGENTS.md` is created automatically.
 2. Amp picks up skills from `.agents/skills/` on session start.
 3. Copy Amp MCP config (on first sync):
@@ -183,6 +205,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 +234,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,10 +262,12 @@ 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`):
+**Memory + optional Figma MCP for Cursor** (`.mcp.json`):
 
 ```json
 {
@@ -249,11 +276,17 @@ You can add `context: fork` to explore/review skills for isolated subagent sessi
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-memory"],
       "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+    },
+    "figma": {
+      "command": "node",
+      "args": ["scripts/figma-mcp-launcher.cjs"]
     }
   }
 }
 ```
 
+Token lives in `.agents/figma.local.env` — see [Figma token](#figma-token-optional).
+
 ## The Pipeline in Detail
 
 ### Role 1: Explorer — `/opsx:explore`
@@ -282,7 +315,7 @@ You can add `context: fork` to explore/review skills for isolated subagent sessi
 
 **Exit gate:**
 ```bash
-openspec validate <name> --strict --type change  # must be ✓
+npx openspec validate <name> --strict --type change  # must be ✓
 ```
 
 ```
@@ -560,6 +593,49 @@ npx frontend-agent-skills install --agent all --yes
 
 > **Migrating from `vue-cursor-skills`?** Renamed to `frontend-agent-skills` v2 — same package, old CLI alias still works.
 
+## Figma token (optional)
+
+Personal Access Token for design intake (`/opsx:design`) and the optional Framelink `figma-developer-mcp` server. **Never paste the token into AI chat.**
+
+### Setup (each developer, once)
+
+```bash
+npx agent-orchestrator-kit figma-setup
+# open .agents/figma.local.env in the IDE and set:
+# FIGMA_ACCESS_TOKEN=figd_...
+npx agent-orchestrator-kit figma-status
+```
+
+Then restart Cursor / Amp.
+
+| Path | Purpose | Git |
+|------|---------|-----|
+| `.agents/figma.local.env` | Your token (`FIGMA_ACCESS_TOKEN`) | **ignored** |
+| `.agents/figma.local.env.example` | Template | committed |
+| `scripts/figma-mcp-launcher.cjs` | Starts MCP with token from the env file | committed |
+| `.mcp.json` → `figma` | Points at the launcher (no secret inline) | committed OK |
+
+Create a token: Figma → Settings → Security → Personal access tokens (file content read as needed).
+
+### CLI
+
+```bash
+npx agent-orchestrator-kit figma-setup
+npx agent-orchestrator-kit figma-status
+npx agent-orchestrator-kit figma-fetch --url "https://www.figma.com/design/FILE_KEY/Name?node-id=1-2" \
+  --out openspec/changes/<name>/assets/figma-nodes.json
+```
+
+`figma-fetch` uses the Figma REST API (`X-Figma-Token`) and writes JSON for design-brief capture. Live Figma is for design-intake only — apply uses `design-brief.md`.
+
+### Upgrade existing projects
+
+```bash
+npx agent-orchestrator-kit@latest update
+npx agent-orchestrator-kit figma-setup
+./scripts/sync-local-agent-skills.sh
+```
+
 ## Memory MCP — Shared State Between Sessions
 
 Each role starts a fresh session. Memory MCP persists orchestration state across sessions so you don't re-explain context every time.
@@ -648,16 +724,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 +753,17 @@ openspec/                # Committed — spec-driven workflow
 
 ## Changelog
 
+### 0.1.11
+- Optional **Figma personal token** setup: `.agents/figma.local.env` (gitignored) + `figma-mcp-launcher.cjs` (no secret in `.mcp.json`)
+- CLI: `figma-setup`, `figma-status`, `figma-fetch` (REST nodes/file JSON)
+- Agent rule + docs: never paste Figma tokens into chat
+- Amp PATH hardening: prefer `npx` / `npm run` for OpenSpec and kit CLIs (`cli-via-npm` rule)
+
+### 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