agent-orchestrator-kit 0.1.0 → 0.1.2

package/README.md

@@ -75,30 +75,47 @@ This copies `.agents/` to your local IDE directories (not committed to git).
 
 ```
 your-project/
-├── AGENTS.md                          # Amp Code + universal pipeline manifest
-├── CLAUDE.md                          # Claude Code context
+├── AGENTS.md
+├── CLAUDE.md
+├── .github/workflows/agent-verify.yml   # CI: openspec validate + lint + build
 ├── .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
+│   ├── orchestrator.yaml
+│   ├── mcp.json.example                 # Cursor MCP template
+│   ├── amp.settings.json.example        # Amp MCP template
+│   ├── commands/                        # 6 /opsx:* commands
+│   ├── rules/                           # 3 auto-applied rules
 │   └── skills/
-│       └── agent-orchestration/
-│           └── SKILL.md
-└── scripts/
-    └── sync-local-agent-skills.sh
-```
-
-Git-committed: `.agents/` + `AGENTS.md` + `CLAUDE.md` + `scripts/`
+│       ├── agent-orchestration/         # Pipeline orchestration
+│       ├── openspec-howto/
+│       ├── openspec-explore/
+│       ├── openspec-propose/
+│       ├── openspec-apply-change/
+│       ├── openspec-archive-change/
+│       ├── openspec-sync-specs/
+│       └── spec-workflow-openspec/
+└── scripts/sync-local-agent-skills.sh
+```
+
+### Included in kit
+
+| Category | Contents |
+|----------|----------|
+| 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 |
+| CI | `agent-verify.yml` (openspec validate, lint, build, test) |
+| MCP templates | Memory MCP for Cursor and Amp |
+
+### Not included (install separately)
+
+| What | How |
+|------|-----|
+| OpenSpec CLI | `npm i -D @fission-ai/openspec && npx openspec init` |
+| Stack skills (Vue, etc.) | `npx vue-cursor-skills install` for vue3 profile |
+| Project conventions | Create `.agents/project-conventions/SKILL.md` manually |
+| Domain specs | Live in `openspec/specs/` per project |
+
+Git-committed: `.agents/` + `AGENTS.md` + `CLAUDE.md` + `scripts/` + `.github/`
 Local only (not committed): `.cursor/` `.claude/` `.amp/`
 
 ## IDE Integration
@@ -109,20 +126,14 @@ 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`:
+3. Copy Amp MCP config (on first sync):
 
-```json
-{
-  "amp.mcpServers": {
-    "memory": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-memory"],
-      "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
-    }
-  }
-}
+```bash
+cp .agents/amp.settings.json.example .amp/settings.json
 ```
 
+Or run `./scripts/sync-local-agent-skills.sh` — it creates `.amp/settings.json` automatically.
+
 4. Use commands directly:
 
 ```
@@ -158,7 +169,7 @@ Switch modes in Amp CLI: `Ctrl+O` → `mode`.
 - Project level: `.claude/CLAUDE.md` (synced from `CLAUDE.md`)
 - Personal (optional): `~/.claude/CLAUDE.md` for preferences
 
-**Claude Code subagent config** (in skill frontmatter):
+**Claude Code subagent config** (optional, in skill frontmatter):
 
 ```yaml
 ---
@@ -169,7 +180,7 @@ allowed-tools: Read, Bash
 ---
 ```
 
-The kit pre-configures Explore skills to use `context: fork` + `agent: Explore` for clean context isolation.
+You can add `context: fork` to explore/review skills for isolated subagent sessions.
 
 ### Cursor
 
@@ -271,11 +282,13 @@ npm run lint    # must pass
 
 ### Role 5: Verifier — CI (automatic)
 
+Installed at `.github/workflows/agent-verify.yml`:
+
 ```yaml
-# .github/workflows/agent-verify.yml (generated by kit)
 - run: npx openspec validate --all --strict
-- run: npm run lint
-- run: npm run build
+- run: npm run lint --if-present
+- run: npm run build --if-present
+- run: npm test --if-present
 ```
 
 Blocks merge if any gate fails.
@@ -329,11 +342,11 @@ npx agent-orchestrator-kit update
 
 ## 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 |
+| Profile | Stack | Extra (separate install) |
+|---------|-------|--------------------------|
+| `generic` | Any | Orchestration + OpenSpec skills only |
+| `vue3` | Vue 3 + Vite | + `npx vue-cursor-skills install` |
+| `node` | Node.js | + your JS skills as needed |
 
 For `vue3`, after kit init also run:
 
@@ -441,6 +454,23 @@ openspec/                # Committed — spec-driven workflow
   changes/               # Active work
 ```
 
+## Changelog
+
+### 0.1.2
+- Fix CLI: executable bit on `bin/agent-orchestrator.js` (`agent-orchestrator: not found`)
+- Add `agent-orchestrator-kit` bin alias (matches package name for npx)
+
+### 0.1.1
+- Added all OpenSpec skills (`openspec-*`, `spec-workflow-openspec`)
+- Added CI workflow template `.github/workflows/agent-verify.yml`
+- Added `.agents/amp.settings.json.example` for Amp Code MCP
+- `update` command now refreshes all kit-managed skills and CI
+- Sync script auto-creates `.amp/settings.json` from example
+- Removed unused `prompts` dependency
+
+### 0.1.0
+- Initial release: orchestration pipeline, `/opsx:*` commands, IDE sync
+
 ## License
 
 MIT © [Maksim Shevyakov](https://github.com/makshc2)

package/bin/agent-orchestrator.js

@@ -10,6 +10,25 @@ 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 KIT_SKILL_DIRS = [
+  'agent-orchestration',
+  'openspec-howto',
+  'openspec-explore',
+  'openspec-propose',
+  'openspec-apply-change',
+  'openspec-archive-change',
+  'openspec-sync-specs',
+  'spec-workflow-openspec',
+];
+
+const KIT_MANAGED_PATHS = [
+  '.agents/commands',
+  '.agents/rules',
+  ...KIT_SKILL_DIRS.map((s) => `.agents/skills/${s}`),
+  '.github/workflows/agent-verify.yml',
+  'scripts/sync-local-agent-skills.sh',
+];
+
 const log = {
   info: (msg) => console.log(pc.cyan('  →'), msg),
   ok: (msg) => console.log(pc.green('  ✓'), msg),
@@ -107,6 +126,19 @@ program
       execSync(`chmod +x ${join(projectDir, 'scripts', 'sync-local-agent-skills.sh')}`);
     } catch {}
 
+    log.title('Installing CI workflow');
+    const githubWorkflow = join(templateDir, '.github', 'workflows', 'agent-verify.yml');
+    const githubDest = join(projectDir, '.github', 'workflows', 'agent-verify.yml');
+    if (existsSync(githubWorkflow)) {
+      if (!opts.force && existsSync(githubDest)) {
+        log.warn('skip (exists): .github/workflows/agent-verify.yml');
+      } else {
+        mkdirSync(dirname(githubDest), { recursive: true });
+        copyFileSync(githubWorkflow, githubDest);
+        log.ok('.github/workflows/agent-verify.yml');
+      }
+    }
+
     log.title('Installing root files');
     for (const f of ['AGENTS.md', 'CLAUDE.md']) {
       const src = resolveTemplate(f, opts.profile);
@@ -142,7 +174,7 @@ ${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)
+  3. Copy MCP config: .mcp.json (Cursor) / .amp/settings.json (Amp) from *.example files
   4. Start your first change:
      ${pc.cyan('/opsx:explore')}
 `);
@@ -157,26 +189,16 @@ program
 
     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) {
+    for (const rel of KIT_MANAGED_PATHS) {
       const src = join(templateDir, rel);
       const dest = join(projectDir, rel);
-      if (existsSync(src)) {
+      if (!existsSync(src)) continue;
+      if (statSync(src).isDirectory()) {
         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)) {
+      } else {
+        mkdirSync(dirname(dest), { recursive: true });
         copyFileSync(src, dest);
-        log.ok(f);
+        log.ok(rel);
       }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven pipeline with OpenSpec integration",
   "keywords": [
     "ai-agent",
@@ -24,7 +24,8 @@
   },
   "type": "module",
   "bin": {
-    "agent-orchestrator": "./bin/agent-orchestrator.js"
+    "agent-orchestrator-kit": "bin/agent-orchestrator.js",
+    "agent-orchestrator": "bin/agent-orchestrator.js"
   },
   "files": [
     "bin/",
@@ -38,11 +39,11 @@
   },
   "dependencies": {
     "commander": "^12.0.0",
-    "picocolors": "^1.0.0",
-    "prompts": "^2.4.2"
+    "picocolors": "^1.0.0"
   },
   "scripts": {
-    "test": "node --test",
+    "prepack": "chmod +x bin/agent-orchestrator.js",
+    "test": "node --test test/*.test.js",
     "link": "npm link"
   }
 }

package/templates/.agents/amp.settings.json.example

@@ -0,0 +1,11 @@
+{
+  "amp.mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "env": {
+        "MEMORY_FILE_PATH": ".cursor/memory.json"
+      }
+    }
+  }
+}

package/templates/.agents/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

package/templates/.agents/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
+   ```bash
+   mkdir -p "<planningHome.changesDir>/archive"
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move `changeRoot` to the archive directory
+
+   ```bash
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting