agent-orchestrator-kit 0.1.9 → 0.1.11

package/templates/AGENTS.md

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

package/templates/CLAUDE.md

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

package/templates/orchestrator.yaml

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

package/templates/scripts/figma-mcp-launcher.cjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const { existsSync, readFileSync } = require('fs');
+const { join } = require('path');
+
+const projectDir = join(__dirname, '..');
+const envPath = join(projectDir, '.agents', 'figma.local.env');
+
+function readLocalToken() {
+  if (!existsSync(envPath)) {
+    console.error(
+      `[figma-mcp-launcher] Missing ${envPath}. Copy .agents/figma.local.env.example → .agents/figma.local.env and add FIGMA_ACCESS_TOKEN (do not paste the token into chat).`
+    );
+    process.exit(1);
+  }
+
+  const raw = readFileSync(envPath, 'utf-8');
+  const values = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+
+  return values.FIGMA_ACCESS_TOKEN || values.FIGMA_API_KEY || '';
+}
+
+const token = readLocalToken();
+if (!token) {
+  console.error(
+    '[figma-mcp-launcher] FIGMA_ACCESS_TOKEN is empty in .agents/figma.local.env. Add your Figma personal access token locally (never in chat).'
+  );
+  process.exit(1);
+}
+
+const child = spawn('npx', ['-y', 'figma-developer-mcp', '--stdio'], {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    FIGMA_API_KEY: token,
+    FIGMA_ACCESS_TOKEN: token,
+  },
+  shell: process.platform === 'win32',
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code == null ? 1 : code);
+});
+
+child.on('error', (error) => {
+  console.error(`[figma-mcp-launcher] Failed to start figma-developer-mcp: ${error.message}`);
+  process.exit(1);
+});

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