agent-orchestrator-kit 0.1.0

package/templates/.agents/commands/opsx-explore.md

@@ -0,0 +1,172 @@
+---
+name: /opsx-explore
+id: opsx-explore
+category: Workflow
+description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

package/templates/.agents/commands/opsx-propose.md

@@ -0,0 +1,107 @@
+---
+name: /opsx-propose
+id: opsx-propose
+category: Workflow
+description: Propose a new change - create it and generate all artifacts in one step
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

package/templates/.agents/commands/opsx-review.md

@@ -0,0 +1,125 @@
+---
+name: /opsx-review
+id: opsx-review
+category: Workflow
+description: Read-only spec review of an OpenSpec change — approve or request changes before apply
+---
+
+Review an OpenSpec change. Read artifacts, validate structure, output Approve or Request Changes.
+
+**IMPORTANT: This is a read-only mode. You must NEVER edit any file in `src/` or any source code. You may not mark tasks `[x]`. Your only output is a structured review verdict.**
+
+**Input**: Optionally specify a change name (e.g., `/opsx:review add-auth`). If omitted, auto-select if one active change exists, otherwise list and ask.
+
+---
+
+## Steps
+
+### 1. Select the change
+
+If name provided — use it. Otherwise:
+- Run `openspec list --json` to list active changes.
+- Auto-select if only one exists.
+- Ask the user with AskUserQuestion if ambiguous.
+
+Announce: "Reviewing change: **<name>**"
+
+### 2. Validate structure
+
+```bash
+openspec validate <name> --strict --type change
+```
+
+If ✗ — list each error and immediately output **Request Changes** with the validation errors. Stop here.
+
+### 3. Read all artifacts
+
+```bash
+openspec status --change "<name>" --json
+```
+
+Read every file from `artifactPaths`:
+- `proposal.md`
+- `design.md`
+- `tasks.md`
+- all `specs/<domain>/spec.md` files
+
+Also read related `openspec/specs/` domain files to check consistency.
+
+### 4. Review checklist
+
+Evaluate each item. Mark ✓ or ✗:
+
+**Proposal**
+- [ ] Problem statement is clear and specific (not vague)
+- [ ] Non-goals are listed
+- [ ] Acceptance criteria are present and testable (not "should work" — must be verifiable)
+- [ ] Scope matches a ~1–3 day change
+
+**Design**
+- [ ] Approach is concrete (not "we will handle this")
+- [ ] Trade-offs or alternatives mentioned
+- [ ] Does not contradict existing `openspec/specs/` domain specs
+- [ ] No scope creep vs proposal Non-goals
+
+**Tasks**
+- [ ] Each task is ≤ ~2 hours of work
+- [ ] Each task has a clear done condition
+- [ ] Tasks are in logical implementation order
+- [ ] No task requires information not in design/spec
+- [ ] No task says "update X as needed" (must be specific)
+
+**Delta Specs**
+- [ ] Cover all changed/added behavior
+- [ ] ADDED/MODIFIED/REMOVED sections used correctly
+- [ ] No conflicts with main `openspec/specs/`
+
+### 5. Output verdict
+
+#### If all ✓ (or only minor notes):
+
+```
+## Spec Review: APPROVE ✓
+
+**Change:** <name>
+**Reviewed:** proposal.md, design.md, tasks.md, specs/*
+
+### Summary
+<2–3 sentences on what this change does and why it is well-scoped>
+
+### Notes (optional)
+- <minor note if any, not blocking>
+
+**Ready for implementation.** Run `/opsx:apply <name>` to proceed.
+```
+
+#### If any ✗:
+
+```
+## Spec Review: REQUEST CHANGES ✗
+
+**Change:** <name>
+
+### Issues Found
+
+#### Proposal
+- ✗ <issue description> — suggestion: <how to fix>
+
+#### Tasks
+- ✗ Task 3 is too vague: "Update the component" — specify which component and what exact change
+
+### Required Before Apply
+<list only what must be fixed, not cosmetic>
+
+Fix the above, then re-run `/opsx:review <name>`.
+```
+
+---
+
+## Guardrails
+
+- **Never** edit source code, `src/`, or `tasks.md` checkboxes
+- **Never** create new files (only read)
+- **Never** run apply commands
+- Ask for clarification only if a critical artifact is missing or unreadable
+- If proposal is ambiguous on scope, flag as ✗ — do not assume intent

package/templates/.agents/commands/opsx-sync.md

@@ -0,0 +1,143 @@
+---
+name: /opsx-sync
+id: opsx-sync
+category: Workflow
+description: Sync delta specs from a change to main specs
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). 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 changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Resolve change context**
+
+   Run:
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.
+
+3. **Find delta specs**
+
+   Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+4. **For each delta spec, apply changes to main specs**
+
+   For each repo-local capability delta spec path returned by the CLI:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+5. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result

package/templates/.agents/mcp.json.example

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

package/templates/.agents/rules/agent-orchestration.mdc

@@ -0,0 +1,29 @@
+---
+description: Agent orchestration roles and pipeline rules
+alwaysApply: true
+---
+
+# Agent Orchestration Rules
+
+This project uses a spec-driven 5-role pipeline. Read `.agents/orchestrator.yaml` for config.
+
+## Role Commands
+- `/opsx:explore` → read-only thinking, no code
+- `/opsx:propose <name>` → creates `openspec/changes/<name>/` artifacts only
+- `/opsx:review <name>` → read-only spec review, outputs Approve or Request Changes
+- `/opsx:apply <name>` → writes `src/`, marks `tasks.md [x]`
+- `/opsx:archive` → merges delta specs, moves change to archive
+
+## Session Rules
+- One active change at a time
+- Each role = new chat session
+- No code in explore or review sessions
+- No apply without explicit **Approve** from review
+- After apply: build + lint before PR
+- After merge: always run `/opsx:archive`
+
+## Never
+- Mix propose and apply in one session
+- Edit `src/` during explore or review
+- Skip spec review before apply
+- Leave changes un-archived after merge

package/templates/.agents/rules/memory-mcp-autosetup.mdc

@@ -0,0 +1,55 @@
+---
+description: Memory MCP auto-setup for Cursor and Amp
+alwaysApply: true
+---
+
+# Memory MCP Auto-Setup
+
+At session start: check `.mcp.json` (Cursor) and `.amp/settings.json` (Amp).
+If `memory` MCP is absent — add it silently.
+
+## Cursor (.mcp.json)
+
+```json
+"memory": {
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-memory"],
+  "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+}
+```
+
+## Amp (.amp/settings.json)
+
+```json
+"amp.mcpServers": {
+  "memory": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-memory"],
+    "env": { "MEMORY_FILE_PATH": ".cursor/memory.json" }
+  }
+}
+```
+
+## .gitignore
+
+Ensure present (do not duplicate):
+```
+.cursor/memory.json
+.amp/settings.json
+```
+
+## Memory Entity Format
+
+Use these keys for orchestration state:
+
+| Key | Value |
+|-----|-------|
+| `Change:<name>` | status, task progress |
+| `Decision:<topic>` | chosen option + rationale |
+| `Convention:<area>` | project-specific rules |
+| `Handoff:<name>` | next role, session count |
+
+## Rules
+- Do not overwrite existing correct config
+- Do not delete other MCP servers
+- Notify once: "Memory MCP connected."

package/templates/.agents/rules/openspec-workflow.mdc

@@ -0,0 +1,39 @@
+---
+description: OpenSpec /opsx workflow — commands and file locations
+alwaysApply: true
+---
+
+# OpenSpec Workflow (/opsx)
+
+`/opsx:explore`, `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `/opsx:sync`, `/opsx:review` — AI workflow commands, not source code.
+
+## File Locations
+
+| What | Where |
+|------|-------|
+| Commands | `.agents/commands/opsx-*.md` |
+| Skills | `.agents/skills/` |
+| Specs (source of truth) | `openspec/specs/` |
+| Active changes | `openspec/changes/` |
+| Project config | `openspec/config.yaml` |
+| Orchestration config | `.agents/orchestrator.yaml` |
+
+## Command → Skill Mapping
+
+- `/opsx:explore` → skill `openspec-explore` (thinking only)
+- `/opsx:propose <name>` → skill `openspec-propose`
+- `/opsx:review <name>` → command `opsx-review` (read-only)
+- `/opsx:apply` → skill `openspec-apply-change`
+- `/opsx:archive` → skill `openspec-archive-change`
+- `/opsx:sync` → skill `openspec-sync-specs`
+
+## CLI (read-only)
+
+```bash
+openspec list
+openspec validate <name> --strict --type change
+openspec status --change "<name>" --json
+openspec instructions apply --change "<name>" --json
+```
+
+Do NOT search for opsx in `src/` — nothing there.