agent-orchestrator-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Shevyakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,446 @@
+# 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).
+
+[![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:
+
+```
+explore → 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.
+
+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)
+
+## Why
+
+Without role separation, AI agents tend to mix thinking with implementation, skip spec review, and accumulate context debt across one long chat. This kit enforces the discipline at the filesystem level: each role has explicit allowed files, a checklist, and a handoff gate before the next role starts.
+
+The `AGENTS.md` / `CLAUDE.md` files tell each IDE exactly what the roles are, so you don't repeat yourself every session.
+
+## Installation
+
+### Prerequisites
+
+- Node.js ≥ 18
+- [OpenSpec](https://github.com/fission-ai/openspec) installed in the project:
+
+```bash
+npm i -D @fission-ai/openspec
+npx openspec init
+```
+
+### Install the kit
+
+```bash
+npx agent-orchestrator-kit init
+```
+
+With a stack profile:
+
+```bash
+npx agent-orchestrator-kit init --profile vue3
+npx agent-orchestrator-kit init --profile node
+npx agent-orchestrator-kit init --profile generic
+```
+
+With options:
+
+```bash
+npx agent-orchestrator-kit init \
+  --profile vue3 \
+  --name "My Project" \
+  --lang uk
+```
+
+### Sync to local IDEs
+
+After init (and after every update):
+
+```bash
+./scripts/sync-local-agent-skills.sh
+```
+
+This copies `.agents/` to your local IDE directories (not committed to git).
+
+## What Gets Installed
+
+```
+your-project/
+├── AGENTS.md                          # Amp Code + universal pipeline manifest
+├── CLAUDE.md                          # Claude Code context
+├── .agents/
+│   ├── orchestrator.yaml              # Pipeline config (committed)
+│   ├── mcp.json.example               # MCP template
+│   ├── commands/
+│   │   ├── opsx-explore.md
+│   │   ├── opsx-propose.md
+│   │   ├── opsx-review.md             # new: read-only spec review
+│   │   ├── opsx-apply.md
+│   │   ├── opsx-archive.md
+│   │   └── opsx-sync.md
+│   ├── rules/
+│   │   ├── agent-orchestration.mdc
+│   │   ├── openspec-workflow.mdc
+│   │   └── memory-mcp-autosetup.mdc
+│   └── skills/
+│       └── agent-orchestration/
+│           └── SKILL.md
+└── scripts/
+    └── sync-local-agent-skills.sh
+```
+
+Git-committed: `.agents/` + `AGENTS.md` + `CLAUDE.md` + `scripts/`
+Local only (not committed): `.cursor/` `.claude/` `.amp/`
+
+## IDE Integration
+
+### Amp Code (primary — zero config)
+
+Amp reads `.agents/skills/` and `AGENTS.md` **natively** — no sync needed.
+
+1. Install the kit → `AGENTS.md` is created automatically.
+2. Amp picks up skills from `.agents/skills/` on session start.
+3. Configure Memory MCP in `.amp/settings.json`:
+
+```json
+{
+  "amp.mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+    }
+  }
+}
+```
+
+4. Use commands directly:
+
+```
+/opsx:explore
+/opsx:propose add-feature-name
+/opsx:review add-feature-name
+/opsx:apply add-feature-name
+/opsx:archive
+```
+
+**Model hints per role** (Amp modes):
+
+| Role | Recommended Amp mode |
+|------|---------------------|
+| explore | `rush` |
+| propose | `smart` or `deep` |
+| review | `smart` |
+| apply (complex) | `smart` or `deep` |
+| apply (simple task) | `rush` |
+
+Switch modes in Amp CLI: `Ctrl+O` → `mode`.
+
+### Claude Code
+
+1. Run sync: `./scripts/sync-local-agent-skills.sh`
+2. This creates:
+   - `.claude/CLAUDE.md` — project context
+   - `.claude/skills/` — all skills from `.agents/skills/`
+3. Skills are auto-loaded by Claude Code from `.claude/skills/`.
+4. Invoke directly: `/agent-orchestration`, `/openspec-howto`, etc.
+
+**CLAUDE.md tiers used:**
+- Project level: `.claude/CLAUDE.md` (synced from `CLAUDE.md`)
+- Personal (optional): `~/.claude/CLAUDE.md` for preferences
+
+**Claude Code subagent config** (in skill frontmatter):
+
+```yaml
+---
+name: openspec-explore
+context: fork
+agent: Explore
+allowed-tools: Read, Bash
+---
+```
+
+The kit pre-configures Explore skills to use `context: fork` + `agent: Explore` for clean context isolation.
+
+### Cursor
+
+1. Run sync: `./scripts/sync-local-agent-skills.sh`
+2. Creates:
+   - `.cursor/skills/` — all skills
+   - `.cursor/rules/` — `.mdc` rule files
+   - `.mcp.json` — from `mcp.json.example` (if not present)
+3. Rules are applied automatically per `alwaysApply: true`.
+
+**Memory MCP for Cursor** (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+    }
+  }
+}
+```
+
+## The Pipeline in Detail
+
+### Role 1: Explorer — `/opsx:explore`
+
+**Mode:** read-only. Cannot edit any files.
+**Model:** fast/cheap.
+**Purpose:** Understand the problem. Surface options. Choose a direction.
+
+**Exit criteria (before starting Architect):**
+- Problem stated in 3–5 sentences
+- 2–3 solution options + recommendation
+- kebab-case change name chosen
+- Non-goals listed
+
+```
+/opsx:explore How should we handle bulk camera export?
+```
+
+---
+
+### Role 2: Architect — `/opsx:propose <name>`
+
+**Mode:** writes `openspec/changes/<name>/` only. Cannot touch `src/`.
+**Model:** strong reasoning.
+**Purpose:** Create all change artifacts: proposal, design, tasks, delta specs.
+
+**Exit gate:**
+```bash
+openspec validate <name> --strict --type change  # must be ✓
+```
+
+```
+/opsx:propose add-bulk-camera-export
+```
+
+---
+
+### Role 3: Spec Reviewer — `/opsx:review <name>`
+
+**Mode:** read-only. No code edits.
+**Model:** medium or strong.
+**Purpose:** Review artifacts. Output **Approve ✓** or **Request Changes ✗**.
+
+Checks:
+- Acceptance criteria are testable
+- Tasks ≤ ~2 hours each
+- No scope creep vs Non-goals
+- No conflicts with existing domain specs
+
+```
+/opsx:review add-bulk-camera-export
+```
+
+**Only after explicit APPROVE can apply start.**
+
+---
+
+### Role 4: Implementer — `/opsx:apply <name>`
+
+**Mode:** writes `src/`. Marks `tasks.md [x]`.
+**Model:** strong. Use fast for simple mechanical tasks.
+**Purpose:** Implement tasks. One session = 1–3 tasks (not all 15 at once).
+
+**Exit gate:**
+```bash
+npm run build   # must pass
+npm run lint    # must pass
+```
+
+```
+/opsx:apply add-bulk-camera-export
+```
+
+---
+
+### Role 5: Verifier — CI (automatic)
+
+```yaml
+# .github/workflows/agent-verify.yml (generated by kit)
+- run: npx openspec validate --all --strict
+- run: npm run lint
+- run: npm run build
+```
+
+Blocks merge if any gate fails.
+
+---
+
+### Archive — `/opsx:archive`
+
+After PR merged + CI green:
+```
+/opsx:archive add-bulk-camera-export
+```
+
+Merges delta specs into `openspec/specs/` and moves change to `archive/`.
+
+## Configuration
+
+Edit `.agents/orchestrator.yaml` after init:
+
+```yaml
+project:
+  name: "My Project"
+  agent_language: uk      # response language for agents
+
+pipeline:
+  require_spec_review: true
+  max_active_changes: 1
+  archive_after_merge: true
+
+verifier:
+  lint_command: "npm run lint"
+  build_command: "npm run build"
+  test_command: "npm test"   # optional
+```
+
+## Update
+
+When a new version of the kit is released:
+
+```bash
+npx agent-orchestrator-kit update
+./scripts/sync-local-agent-skills.sh
+```
+
+`update` only touches kit-managed files (commands, rules, skills). It never overwrites:
+- `orchestrator.yaml`
+- `openspec/config.yaml`
+- `openspec/specs/`
+- `openspec/changes/`
+- Any project-conventions skills
+
+## Profiles
+
+| Profile | Stack | Extra skills installed |
+|---------|-------|----------------------|
+| `generic` | Any | Orchestration only |
+| `vue3` | Vue 3 + Vite | + vue-cursor-skills (separate install) |
+| `node` | Node.js | + javascript-core, javascript-node |
+
+For `vue3`, after kit init also run:
+
+```bash
+npx vue-cursor-skills install
+rsync -a .cursor/skills/ .agents/skills/
+./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.
+
+**Standard entities to save:**
+
+```
+Change:add-bulk-export     status: spec-approved, tasks: 0/7
+Decision:export-format     chosen: xlsx, reason: matches existing reports
+Convention:api-errors      use ApiError class, not raw Error
+Handoff:add-bulk-export    next_role: implementer, session_count: 1
+```
+
+At the start of each implementer/reviewer session, read relevant memory:
+```
+What do we know about Change:add-bulk-export?
+```
+
+## Amp Code — Deep Integration Notes
+
+Amp is the **primary target** of this kit. It reads `.agents/skills/` and `AGENTS.md` without any sync step — your team commits `.agents/` and everyone gets the same orchestration behavior automatically.
+
+**Amp-specific features used:**
+
+| Feature | How the kit uses it |
+|---------|-------------------|
+| `AGENTS.md` subtree loading | Per-domain AGENTS.md in `openspec/` subtree |
+| `.agents/skills/` | All orchestration + domain skills |
+| `mcp.json` in skill dir | Lazy MCP loading (Memory only when needed) |
+| Subagents | Explore and Review skills use forked subagents |
+| Amp modes (rush/smart/deep) | Per-role model hints in AGENTS.md |
+
+**Amp subagent in skill** (`.agents/skills/openspec-explore/SKILL.md`):
+
+```yaml
+---
+name: openspec-explore
+description: Enter explore mode — read-only thinking partner
+disable-model-invocation: false
+allowed-tools: Read, Bash
+---
+```
+
+Amp will run this skill as a subagent when invoked.
+
+**Team workflow with Amp:**
+
+1. Commit `.agents/` to git.
+2. Team members clone — skills available immediately.
+3. No `sync-local-agent-skills.sh` needed for Amp users.
+4. Cursor/Claude Code users run sync once after clone.
+
+## CLI Reference
+
+```bash
+npx agent-orchestrator-kit init [options]
+  --profile <name>   Stack profile: generic | vue3 | node | python
+  --lang <code>      Agent language: en | uk | ...
+  --name <name>      Project name (default: directory name)
+  --force            Overwrite existing files
+
+npx agent-orchestrator-kit update
+  Updates kit-managed files, preserves project overlay
+
+npx agent-orchestrator-kit sync [options]
+  --target <ide>     cursor | claude | all (default: all)
+  Copies .agents/ to local IDE directories
+```
+
+## Directory Reference
+
+```
+.agents/                 # Committed — source of truth for all IDEs
+  commands/              # /opsx:* command definitions
+  rules/                 # Auto-applied rules for Cursor
+  skills/                # Skills for Cursor, Claude Code, Amp
+  orchestrator.yaml      # Project pipeline config
+
+.cursor/                 # Local only — Cursor IDE runtime
+  skills/                # Synced from .agents/skills/
+  rules/                 # Synced from .agents/rules/
+  memory.json            # Memory MCP data
+
+.claude/                 # Local only — Claude Code runtime
+  skills/                # Synced from .agents/skills/
+  CLAUDE.md              # Synced from root CLAUDE.md
+
+.amp/                    # Local only — Amp config
+  settings.json          # MCP servers (manual or via amp mcp add)
+
+AGENTS.md                # Committed — Amp + Claude (AGENT.md fallback)
+CLAUDE.md                # Committed — synced to .claude/CLAUDE.md
+openspec/                # Committed — spec-driven workflow
+  config.yaml            # Project context for AI
+  specs/                 # Source of truth after archive
+  changes/               # Active work
+```
+
+## License
+
+MIT © [Maksim Shevyakov](https://github.com/makshc2)

package/bin/agent-orchestrator.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import pc from 'picocolors';
+import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync } from 'fs';
+import { join, dirname, basename } from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = join(__dirname, '..');
+const KIT_VERSION = JSON.parse(readFileSync(join(KIT_ROOT, 'package.json'), 'utf-8')).version;
+
+const log = {
+  info: (msg) => console.log(pc.cyan('  →'), msg),
+  ok: (msg) => console.log(pc.green('  ✓'), msg),
+  warn: (msg) => console.log(pc.yellow('  !'), msg),
+  err: (msg) => console.log(pc.red('  ✗'), msg),
+  title: (msg) => console.log(pc.bold(pc.white(`\n${msg}`))),
+};
+
+function copyDir(src, dest, opts = {}) {
+  const { overwrite = true, skip = [] } = opts;
+  if (!existsSync(src)) return;
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    if (skip.includes(entry)) continue;
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDir(srcPath, destPath, opts);
+    } else {
+      if (!overwrite && existsSync(destPath)) {
+        log.warn(`skip (exists): ${destPath}`);
+        continue;
+      }
+      copyFileSync(srcPath, destPath);
+      log.ok(destPath.replace(process.cwd() + '/', ''));
+    }
+  }
+}
+
+function mergeGitignore(projectDir, lines) {
+  const gitignorePath = join(projectDir, '.gitignore');
+  let content = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
+  let changed = false;
+  for (const line of lines) {
+    if (!content.includes(line)) {
+      content += `\n${line}`;
+      changed = true;
+    }
+  }
+  if (changed) {
+    writeFileSync(gitignorePath, content.trimStart());
+    log.ok('.gitignore updated');
+  }
+}
+
+function resolveTemplate(templateName, profile) {
+  const profilePath = join(KIT_ROOT, 'profiles', profile, templateName);
+  if (existsSync(profilePath)) return profilePath;
+  return join(KIT_ROOT, 'templates', templateName);
+}
+
+function applyPlaceholders(filePath, vars) {
+  if (!existsSync(filePath)) return;
+  let content = readFileSync(filePath, 'utf-8');
+  for (const [key, val] of Object.entries(vars)) {
+    content = content.replaceAll(`{{${key}}}`, val);
+  }
+  writeFileSync(filePath, content);
+}
+
+program
+  .name('agent-orchestrator')
+  .description('Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code')
+  .version(KIT_VERSION);
+
+program
+  .command('init')
+  .description('Install orchestrator kit into the current project')
+  .option('--profile <profile>', 'Stack profile: generic | vue3 | node | python', 'generic')
+  .option('--lang <lang>', 'Agent response language (en | uk | ...)', 'en')
+  .option('--name <name>', 'Project name (defaults to directory name)')
+  .option('--force', 'Overwrite existing files', false)
+  .action((opts) => {
+    const projectDir = process.cwd();
+    const projectName = opts.name || basename(projectDir);
+
+    log.title(`agent-orchestrator init  v${KIT_VERSION}`);
+    log.info(`Project: ${projectName}`);
+    log.info(`Profile: ${opts.profile}`);
+    log.info(`Language: ${opts.lang}`);
+
+    const templateDir = join(KIT_ROOT, 'templates');
+    const profileDir = join(KIT_ROOT, 'profiles', opts.profile);
+    const vars = { PROJECT_NAME: projectName, LANG: opts.lang, KIT_VERSION };
+
+    log.title('Installing .agents/');
+    copyDir(join(templateDir, '.agents'), join(projectDir, '.agents'), { overwrite: opts.force });
+    if (existsSync(join(profileDir, '.agents'))) {
+      copyDir(join(profileDir, '.agents'), join(projectDir, '.agents'), { overwrite: opts.force });
+    }
+
+    log.title('Installing scripts/');
+    copyDir(join(templateDir, 'scripts'), join(projectDir, 'scripts'), { overwrite: opts.force });
+    try {
+      execSync(`chmod +x ${join(projectDir, 'scripts', 'sync-local-agent-skills.sh')}`);
+    } catch {}
+
+    log.title('Installing root files');
+    for (const f of ['AGENTS.md', 'CLAUDE.md']) {
+      const src = resolveTemplate(f, opts.profile);
+      const dest = join(projectDir, f);
+      if (!opts.force && existsSync(dest)) {
+        log.warn(`skip (exists): ${f}`);
+        continue;
+      }
+      if (existsSync(src)) {
+        copyFileSync(src, dest);
+        applyPlaceholders(dest, vars);
+        log.ok(f);
+      }
+    }
+
+    const orchSrc = resolveTemplate('orchestrator.yaml', opts.profile);
+    const orchDest = join(projectDir, '.agents', 'orchestrator.yaml');
+    if (!opts.force && existsSync(orchDest)) {
+      log.warn('skip (exists): .agents/orchestrator.yaml');
+    } else if (existsSync(orchSrc)) {
+      copyFileSync(orchSrc, orchDest);
+      applyPlaceholders(orchDest, vars);
+      log.ok('.agents/orchestrator.yaml');
+    }
+
+    log.title('Updating .gitignore');
+    mergeGitignore(projectDir, ['.cursor', '.cursor/memory.json', '.amp/settings.json']);
+
+    log.title('Done');
+    log.ok(`agent-orchestrator-kit v${KIT_VERSION} installed`);
+    console.log(`
+${pc.bold('Next steps:')}
+  1. Review ${pc.cyan('AGENTS.md')} and ${pc.cyan('.agents/orchestrator.yaml')}
+  2. Sync to your IDE:
+     ${pc.cyan('./scripts/sync-local-agent-skills.sh')}
+  3. Install Memory MCP in .mcp.json (Cursor) / .amp/settings.json (Amp)
+  4. Start your first change:
+     ${pc.cyan('/opsx:explore')}
+`);
+  });
+
+program
+  .command('update')
+  .description('Update kit files without overwriting project overlay (orchestrator.yaml, project-conventions)')
+  .action(() => {
+    const projectDir = process.cwd();
+    const templateDir = join(KIT_ROOT, 'templates');
+
+    log.title(`agent-orchestrator update  v${KIT_VERSION}`);
+
+    const KIT_FILES = [
+      '.agents/commands',
+      '.agents/rules',
+      '.agents/skills/agent-orchestration',
+    ];
+
+    for (const rel of KIT_FILES) {
+      const src = join(templateDir, rel);
+      const dest = join(projectDir, rel);
+      if (existsSync(src)) {
+        copyDir(src, dest, { overwrite: true });
+      }
+    }
+
+    for (const f of ['scripts/sync-local-agent-skills.sh']) {
+      const src = join(templateDir, f);
+      const dest = join(projectDir, f);
+      if (existsSync(src)) {
+        copyFileSync(src, dest);
+        log.ok(f);
+      }
+    }
+
+    log.ok(`Updated to v${KIT_VERSION}`);
+    log.info('Run ./scripts/sync-local-agent-skills.sh to sync to local IDE');
+  });
+
+program
+  .command('sync')
+  .description('Sync .agents/ to local IDE directories (Cursor, Claude Code)')
+  .option('--target <target>', 'cursor | claude | amp | all', 'all')
+  .action((opts) => {
+    const projectDir = process.cwd();
+
+    log.title('agent-orchestrator sync');
+
+    const syncCursor = ['cursor', 'all'].includes(opts.target);
+    const syncClaude = ['claude', 'all'].includes(opts.target);
+
+    if (syncCursor) {
+      log.info('Syncing .agents/ → .cursor/');
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.cursor', 'skills'), { overwrite: true });
+      copyDir(join(projectDir, '.agents', 'rules'), join(projectDir, '.cursor', 'rules'), { overwrite: true });
+
+      const mcpExample = join(projectDir, '.agents', 'mcp.json.example');
+      const mcpDest = join(projectDir, '.mcp.json');
+      if (existsSync(mcpExample) && !existsSync(mcpDest)) {
+        copyFileSync(mcpExample, mcpDest);
+        log.ok('.mcp.json created from example');
+      }
+    }
+
+    if (syncClaude) {
+      log.info('Syncing .agents/ → .claude/');
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.claude', 'skills'), { overwrite: true });
+
+      const claudeMd = join(projectDir, 'CLAUDE.md');
+      const claudeDir = join(projectDir, '.claude');
+      if (existsSync(claudeMd)) {
+        mkdirSync(claudeDir, { recursive: true });
+        copyFileSync(claudeMd, join(claudeDir, 'CLAUDE.md'));
+        log.ok('.claude/CLAUDE.md');
+      }
+    }
+
+    log.ok('Sync complete');
+    log.warn('.cursor/ and .claude/ are local only — not committed to git');
+  });
+
+program.parse();