agent-orchestrator-kit 0.1.0

package/templates/.agents/skills/agent-orchestration/SKILL.md

@@ -0,0 +1,146 @@
+---
+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,
+  /opsx:apply, /opsx:archive.
+disable-model-invocation: false
+allowed-tools: Bash, Read
+---
+
+# Agent Orchestration
+
+Spec-driven 5-role pipeline. Each role runs in a separate session. Mixing roles in one chat
+is the primary source of wasted tokens and failed implementations.
+
+## Pipeline
+
+```
+explore → propose → review → apply → verify → archive
+```
+
+Read `.agents/orchestrator.yaml` for project-specific config (language, flags, MCP).
+
+## Roles & Commands
+
+| Role | Command | Mode | Model hint | Allowed output |
+|------|---------|------|------------|----------------|
+| Explorer | `/opsx:explore` | read-only | fast | chat only |
+| Architect | `/opsx:propose <name>` | specs-only | strong | `openspec/changes/` |
+| Spec Reviewer | `/opsx:review <name>` | read-only | medium | Approve / Request Changes |
+| Implementer | `/opsx:apply <name>` | code | strong | `src/`, `tasks.md [x]` |
+| Verifier | CI scripts | — | — | exit codes |
+
+## Handoff Protocol
+
+### explore → propose
+Exit Explorer when:
+- Problem is stated in 3–5 sentences
+- 2–3 solution options surfaced with a recommendation
+- kebab-case change name chosen
+- Non-goals listed
+
+Start Architect with:
+```
+/opsx:propose <name>
+
+Context from explore:
+- Problem: ...
+- Approach: ...
+- Non-goals: ...
+- Draft acceptance: ...
+```
+
+### propose → review
+Exit Architect when:
+```bash
+openspec validate <name> --strict --type change  # must pass ✓
+openspec status --change "<name>"                # applyRequires artifacts all done
+```
+
+### review → apply
+Exit Reviewer only when verdict is explicit **APPROVE ✓**.
+If Request Changes — fix artifacts, re-run `/opsx:review`.
+
+### apply → verify
+Exit Implementer when:
+- All `tasks.md` boxes `[x]`
+- `npm run build` (or project build cmd) exits 0
+- `npm run lint` exits 0
+- Commit ready
+
+### verify → archive
+After PR merged + CI green:
+```
+/opsx:archive <name>
+```
+
+## Session Rules
+
+**Start of each session:**
+1. Announce role: "Starting Spec Reviewer session for change: <name>"
+2. Check `openspec list` — confirm max 1 active change
+3. Read `orchestrator.yaml` for project config
+
+**During session:**
+- Stay in role — do not drift into next phase
+- Pause and ask if requirements are unclear
+- Never edit files outside your role's allowed output
+
+**End of each session:**
+- Show progress summary
+- State explicit next step and next role
+- If apply: confirm build/lint status
+
+## Model Selection Guide
+
+| Phase | Use case | Recommended |
+|-------|----------|-------------|
+| explore | Q&A, brainstorm | fast (rush/flash) |
+| propose | Architecture decisions | strong (opus/sonnet) |
+| review | Artifact analysis | medium or strong |
+| apply complex | Multi-file refactor | strong |
+| apply simple | 1–2 file change | medium or fast |
+| fix lint | Mechanical | fast |
+
+## Memory MCP Entities
+
+Store these between sessions (key → value):
+
+| Key | Example value |
+|-----|---------------|
+| `Change:<name>` | `status: spec-approved, tasks: 3/7` |
+| `Decision:<topic>` | `chosen: xlsx over csv, reason: ...` |
+| `Convention:<area>` | `api errors: use ApiError class` |
+| `Handoff:<name>` | `next_role: implementer, session_count: 2` |
+
+At start of new session: read relevant entities to restore context without re-explanation.
+
+## Orchestration Checklist (per change)
+
+- [ ] explore session closed before propose started
+- [ ] `openspec validate --strict` passed before review
+- [ ] explicit **Approve** received before apply
+- [ ] all tasks `[x]` + build OK before PR
+- [ ] `/opsx:archive` run after merge
+
+## Anti-patterns
+
+| Anti-pattern | Impact |
+|-------------|--------|
+| Explore + propose in one chat | Architect has stale exploration context |
+| Apply without review | ~60% chance of rework |
+| 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 |
+| Skip Memory MCP | Every session re-explains domain |
+
+## Metrics (health check per change)
+
+- Sessions: 4–8 (not 1 marathon, not 20 micro-sessions)
+- Apply iterations to PR: ≤ 2
+- Spec review loops: ≤ 1
+- Tasks rework: ≤ 10%
+
+If apply iterations > 2 → problem is in Architect or Reviewer, not Implementer.

package/templates/AGENTS.md

@@ -0,0 +1,81 @@
+# Agent Orchestration — {{PROJECT_NAME}}
+
+> Powered by [agent-orchestrator-kit](https://github.com/makshc2/agent-orchestrator-kit) v{{KIT_VERSION}}
+
+This project uses a **spec-driven, role-separated AI pipeline** built on [OpenSpec](https://github.com/fission-ai/openspec).
+Every feature follows the same cycle regardless of stack or IDE.
+
+## Pipeline
+
+```
+explore → propose → review → apply → verify → archive
+```
+
+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.
+
+## Roles
+
+| Role | Command | Mode | Model hint |
+|------|---------|------|------------|
+| Explorer | `/opsx:explore` | read-only | fast |
+| 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 |
+| Verifier | CI (automatic) | scripts only | — |
+
+## 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.
+- **Archive after every merge** (`/opsx:archive`).
+- **Always run local build/lint** before opening a PR.
+
+## Handoff Gates
+
+| Transition | Gate |
+|------------|------|
+| explore → propose | Decision brief written; change name chosen |
+| propose → review | `openspec validate --strict` passes ✓ |
+| review → apply | Reviewer writes explicit **Approve** |
+| apply → verify | All `tasks.md` checkboxes `[x]`; local build OK |
+| verify → archive | CI green; PR merged |
+
+## Context to Pin per Role
+
+| Role | Attach (`@`) |
+|------|-------------|
+| Explorer | `@openspec/specs/` + relevant `@src/` subtree |
+| Architect | `@openspec/config.yaml` + explore brief |
+| Reviewer | entire `@openspec/changes/<name>/` |
+| Implementer | `@openspec/changes/<name>/tasks.md` |
+
+## Configuration
+
+See `.agents/orchestrator.yaml` for role config, pipeline flags, and MCP baseline.
+
+## Skills & Commands
+
+All skills live in `.agents/skills/` (committed to git).
+Local IDE sync: run `./scripts/sync-local-agent-skills.sh`.
+
+| Skill | When |
+|-------|------|
+| `agent-orchestration` | Pipeline decisions, role selection, handoff |
+| `openspec-howto` | OpenSpec CLI, cycle, naming |
+| `openspec-propose` | Creating change artifacts |
+| `openspec-apply-change` | Implementing tasks |
+| `openspec-archive-change` | Archiving after merge |
+
+## Metrics (track per change)
+
+| Metric | Target |
+|--------|--------|
+| Sessions per change | 4–8 |
+| Apply iterations to PR | ≤ 2 |
+| Spec review loops | ≤ 1 |
+| Tasks rework after apply | ≤ 10% |
+| CI fails on PR | ≤ 1 |
+
+If apply iterations > 2 — fix in Architect/Reviewer, not Implementer.

package/templates/CLAUDE.md

@@ -0,0 +1,49 @@
+# {{PROJECT_NAME}} — Claude Code Context
+
+> agent-orchestrator-kit v{{KIT_VERSION}} | Spec-driven pipeline with OpenSpec
+
+## Project
+
+See `AGENTS.md` for the full orchestration pipeline, roles, and hard rules.
+See `openspec/config.yaml` for stack context and agent language.
+
+## Skills
+
+Project skills live in `.claude/skills/` (synced from `.agents/skills/`).
+Use `/skill-name` or let Claude auto-load based on context.
+
+| Skill | Command | When |
+|-------|---------|------|
+| Agent Orchestration | `/agent-orchestration` | Role selection, pipeline, handoff decisions |
+| OpenSpec Howto | `/openspec-howto` | CLI, cycle, naming |
+| OpenSpec Propose | `/openspec-propose` | Creating change artifacts |
+| OpenSpec Apply | `/openspec-apply-change` | Implementing tasks |
+| OpenSpec Archive | `/openspec-archive-change` | Archiving after merge |
+
+## Pipeline Commands
+
+```
+/opsx:explore   — think through ideas (read-only, no code)
+/opsx:propose   — create change artifacts
+/opsx:review    — spec review (read-only, no code)
+/opsx:apply     — implement tasks
+/opsx:archive   — archive after merge
+```
+
+## 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.
+- No code edits in explore or review mode.
+- After completing apply: run build/lint before declaring done.
+- Use `openspec validate --all --strict` to verify change artifacts.
+
+## File Locations
+
+| What | Where |
+|------|-------|
+| Active changes | `openspec/changes/` |
+| Specs (source of truth) | `openspec/specs/` |
+| Project config | `openspec/config.yaml` |
+| Orchestration config | `.agents/orchestrator.yaml` |
+| Skills | `.claude/skills/` |

package/templates/orchestrator.yaml

@@ -0,0 +1,57 @@
+version: 1
+kit_version: "{{KIT_VERSION}}"
+
+project:
+  name: "{{PROJECT_NAME}}"
+  agent_language: "{{LANG}}"
+
+pipeline:
+  require_spec_review: true
+  max_active_changes: 1
+  archive_after_merge: true
+
+roles:
+  explorer:
+    command: /opsx:explore
+    mode: read-only
+    model_hint: fast
+  architect:
+    command: /opsx:propose
+    mode: specs-only
+    model_hint: strong
+  spec_reviewer:
+    command: /opsx:review
+    mode: read-only
+    model_hint: medium
+  implementer:
+    command: /opsx:apply
+    mode: code
+    model_hint: strong
+  verifier:
+    type: ci
+    gates:
+      - openspec-validate-strict
+      - lint
+      - build
+
+handoff:
+  explore_to_propose: decision_brief
+  propose_to_review: validate_strict
+  review_to_apply: explicit_approve
+  apply_to_verify: all_tasks_checked
+
+memory:
+  enabled: true
+  file: .cursor/memory.json
+
+mcp:
+  baseline:
+    - memory
+  optional:
+    - github
+    - browser
+
+verifier:
+  lint_command: "npm run lint"
+  build_command: "npm run build"
+  test_command: ""

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

@@ -0,0 +1,85 @@
+#!/usr/bin/env sh
+# sync-local-agent-skills.sh
+# Syncs .agents/ (committed) to local IDE directories (not committed)
+# Run after: init, update, adding new skills
+# Works with: Cursor, Claude Code, Amp Code (via VS Code settings)
+
+set -eu
+ROOT="$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+RESET='\033[0m'
+
+ok()   { printf "${GREEN}  ✓${RESET} %s\n" "$1"; }
+info() { printf "${CYAN}  →${RESET} %s\n" "$1"; }
+warn() { printf "${YELLOW}  !${RESET} %s\n" "$1"; }
+
+echo ""
+echo "sync-local-agent-skills"
+echo "-----------------------"
+
+# ── Cursor ─────────────────────────────────────────────────────────────
+echo ""
+info "Syncing → .cursor/ (Cursor)"
+mkdir -p .cursor/skills .cursor/rules
+
+rsync -a --delete .agents/skills/ .cursor/skills/
+ok ".cursor/skills/"
+
+for rule in .agents/rules/*.mdc; do
+  [ -f "$rule" ] && cp "$rule" .cursor/rules/ && ok ".cursor/rules/$(basename "$rule")"
+done
+
+if [ ! -f .mcp.json ] && [ -f .agents/mcp.json.example ]; then
+  cp .agents/mcp.json.example .mcp.json
+  ok ".mcp.json created from example"
+elif [ ! -f .mcp.json ]; then
+  warn ".mcp.json missing — create it manually (see README)"
+fi
+
+# ── Claude Code ────────────────────────────────────────────────────────
+echo ""
+info "Syncing → .claude/ (Claude Code)"
+mkdir -p .claude/skills
+
+rsync -a --delete .agents/skills/ .claude/skills/
+ok ".claude/skills/"
+
+if [ -f CLAUDE.md ]; then
+  cp CLAUDE.md .claude/CLAUDE.md
+  ok ".claude/CLAUDE.md"
+fi
+
+# ── Amp Code ───────────────────────────────────────────────────────────
+echo ""
+info "Amp Code reads .agents/ directly — no sync needed"
+if [ ! -f .amp/settings.json ]; then
+  warn ".amp/settings.json missing — add Memory MCP manually (see README)"
+  warn "  {\"amp.mcpServers\":{\"memory\":{\"command\":\"npx\",\"args\":[\"-y\",\"@modelcontextprotocol/server-memory\"],\"env\":{\"MEMORY_FILE_PATH\":\".cursor/memory.json\"}}}}"
+fi
+
+# ── .gitignore check ───────────────────────────────────────────────────
+echo ""
+info "Checking .gitignore"
+GITIGNORE=".gitignore"
+CHANGED=0
+
+for line in ".cursor" ".cursor/memory.json" ".amp/settings.json" ".claude"; do
+  if ! grep -qF "$line" "$GITIGNORE" 2>/dev/null; then
+    echo "$line" >> "$GITIGNORE"
+    ok "Added '$line' to .gitignore"
+    CHANGED=1
+  fi
+done
+
+[ "$CHANGED" -eq 0 ] && ok ".gitignore OK"
+
+echo ""
+ok "Sync complete"
+echo ""
+printf "  Committed to git: ${CYAN}.agents/${RESET} — skills, rules, commands\n"
+printf "  Local only:       ${YELLOW}.cursor/ .claude/ .amp/${RESET} — IDE runtime\n"
+echo ""