feat: add multi-agent orchestration workflow with dispec-driven schema

.changeset/multiagent-workflow.md

@@ -0,0 +1,12 @@
+---
+"@fission-ai/openspec": minor
+---
+
+Add multi-agent orchestration workflow with dispec-driven schema
+
+- New `dispec-driven` schema for distributing work across multiple AI agents
+- `/opsx:multiagent` workflow: plans and distributes a change into agent-assignable tasks
+- `/opsx:multiagent-apply` workflow: orchestrates a Claude Code agent team to implement tasks in parallel
+- New artifact types: `dependencies.md` (dependency analysis) and `distribution.md` (agent work packages)
+- Schema templates for all new artifact types
+- Support for GitHub-based npm dependency installation in `build.js`

openspec/changes/add-multiagent-apply-workflow/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: dispec-driven
+created: 2026-03-01

openspec/changes/add-multiagent-apply-workflow/dependencies.md

@@ -0,0 +1,108 @@
+## Dependency Matrix
+
+| Task ID | Depends On | Type | Reason |
+|---------|-----------|------|--------|
+| 1.1 | — | — | No dependencies, new file |
+| 1.2 | 1.1 | FS | Needs the file created in 1.1 |
+| 1.3 | 1.1 | FS | Needs the file created in 1.1 |
+| 2.1 | 1.1 | FS | Needs the export functions to exist |
+| 2.2 | 1.1 | FS | Needs the template functions to register |
+| 2.3 | 1.1 | FS | Needs the template functions to register |
+| 2.4 | — | — | Independent constant update |
+| 3.1 | — | — | Independent file edit |
+| 3.2 | — | — | Independent file edit |
+| 3.3 | — | — | Independent file edit |
+| 4.1 | — | — | Independent template file edit |
+| 5.1 | — | — | Independent schema file edit |
+| 5.2 | — | — | Independent schema file edit, same file as 5.1 |
+| 6.1 | — | — | Independent constant update |
+| 6.2 | — | — | Independent constant update |
+| 7.1 | 1.1, 1.2, 1.3 | FS | Tests the new skill template |
+| 7.2 | 1.1, 1.2, 1.3 | FS | Tests the new command template |
+| 7.3 | 2.1, 2.2, 2.3 | FS | Tests parity including new entry |
+| 7.4 | 2.4 | FS | Tests ALL_WORKFLOWS includes new entry |
+| 7.5 | 2.2, 2.3 | FS | Tests template count with new entry |
+| 7.6 | — | — | Regression check, no dependencies |
+| 7.7 | 3.1, 3.2 | FS | Verifies TodoWrite removal |
+
+## Critical Path
+
+```
+1.1 → 1.2 → 7.1
+          → 7.2
+1.1 → 2.1 → 7.3
+     2.2 →
+     2.3 →
+```
+
+The longest chain is: **1.1 → 1.2/1.3 → 7.1/7.2** (3 steps).
+
+Overall critical path duration is short since most tasks are independent edits.
+
+## Parallel Execution Waves
+
+### Wave 1 (no dependencies)
+- 1.1 Create multiagent-apply.ts file
+- 2.4 Add to ALL_WORKFLOWS
+- 3.1 Fix TodoWrite in skill template
+- 3.2 Fix TodoWrite in command template
+- 3.3 Update output section reference
+- 4.1 Update distribution.md template
+- 5.1 Update distribution artifact instruction
+- 5.2 Update apply.instruction
+- 6.1 Add to tool-detection
+- 6.2 Add to init
+- 7.6 Regression check on dispec-driven tests
+
+### Wave 2 (depends on Wave 1)
+- 1.2 Write skill instructions prompt (depends on 1.1)
+- 1.3 Write command template content (depends on 1.1)
+- 2.1 Export from skill-templates.ts (depends on 1.1)
+- 2.2 Register in getSkillTemplates (depends on 1.1)
+- 2.3 Register in getCommandTemplates (depends on 1.1)
+- 7.4 Test ALL_WORKFLOWS (depends on 2.4)
+- 7.7 Verify TodoWrite removed (depends on 3.1, 3.2)
+
+### Wave 3 (depends on Wave 2)
+- 7.1 Test skill template (depends on 1.2, 1.3)
+- 7.2 Test command template (depends on 1.2, 1.3)
+- 7.3 Test parity (depends on 2.1, 2.2, 2.3)
+- 7.5 Test template count (depends on 2.2, 2.3)
+
+## Float / Slack
+
+| Task ID | Float | Notes |
+|---------|-------|-------|
+| 2.4 | High | Independent of critical path, can be done anytime in Wave 1 |
+| 3.1–3.3 | High | Independent edits, no downstream blockers except 7.7 |
+| 4.1 | High | Independent template edit, no downstream blockers |
+| 5.1–5.2 | High | Independent schema edits, no downstream blockers |
+| 6.1–6.2 | High | Independent constant updates, no downstream blockers |
+| 7.6 | High | Regression check, can run anytime |
+
+## Text DAG
+
+```
+Wave 1                    Wave 2                    Wave 3
+──────                    ──────                    ──────
+
+[1.1] ──────────────────→ [1.2] ──────────────────→ [7.1]
+         │                [1.3] ──────────────────→ [7.2]
+         │
+         ├──────────────→ [2.1] ──┐
+         ├──────────────→ [2.2] ──┼──────────────→ [7.3]
+         └──────────────→ [2.3] ──┘               [7.5]
+
+[2.4] ──────────────────→ [7.4]
+
+[3.1] ──┐
+[3.2] ──┼──────────────→ [7.7]
+[3.3]   │
+
+[4.1]
+[5.1]
+[5.2]
+[6.1]
+[6.2]
+[7.6]
+```

openspec/changes/add-multiagent-apply-workflow/design.md

@@ -0,0 +1,91 @@
+## Context
+
+The `dispec-driven` schema produces six artifacts: proposal → specs → design → tasks → dependencies → distribution. The first four are shared with `spec-driven`; the last two (`dependencies.md`, `distribution.md`) are unique to multi-agent execution. The existing `/opsx:apply` skill reads `tasks.md` and works through tasks sequentially with a single agent. There is no apply variant that leverages the distribution plan to orchestrate a Claude Code agent team.
+
+Claude Code provides team coordination primitives: `TeamCreate` (creates a team + shared task list), `Agent` (spawns teammates with `team_name`), `TaskCreate`/`TaskUpdate`/`TaskList` (shared task list), and `SendMessage` (inter-agent communication). Teammates can be isolated via `isolation: "worktree"` on the Agent tool call.
+
+The `/opsx:multiagent` skill currently references `TodoWrite` (deprecated) and the distribution template's "Claude Code Team Setup" section uses pseudo-bash comments instead of describing real tool calls.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create an `/opsx:multiagent-apply` skill that bridges the distribution plan to Claude Code team execution
+- Update `/opsx:multiagent` to use correct Claude Code primitives (`TaskCreate`/`TaskUpdate` instead of `TodoWrite`)
+- Update the `distribution.md` template to produce actionable team setup instructions
+- Update the `dispec-driven` schema's `apply.instruction` to describe multi-agent execution
+
+**Non-Goals:**
+- Changing the `spec-driven` schema or its apply workflow
+- Adding a programmatic API for team orchestration (this is skill/prompt-level orchestration)
+- Auto-merging worktree branches (agents produce branches; the user merges)
+- Supporting non-Claude-Code agent runtimes
+
+## Decisions
+
+### 1. Skill-level orchestration, not programmatic
+
+**Decision:** The multiagent-apply workflow is implemented as a skill template (prompt instructions) that guides the AI agent through team setup, not as TypeScript code that calls Claude Code APIs directly.
+
+**Rationale:** OpenSpec skills are prompt-driven — they instruct the AI agent what tools to call. This matches the existing pattern (`/opsx:apply`, `/opsx:propose`, etc.) and doesn't require OpenSpec to have a programmatic dependency on Claude Code's internal APIs. The skill text tells the agent: "call TeamCreate with these params, then call Agent for each teammate."
+
+**Alternative considered:** A TypeScript orchestrator that programmatically calls Claude Code APIs. Rejected because OpenSpec is tool-agnostic and should not couple to Claude Code's runtime.
+
+### 2. One skill per concern: multiagent-apply is separate from apply
+
+**Decision:** Create `/opsx:multiagent-apply` as a new skill rather than adding multi-agent logic to the existing `/opsx:apply`.
+
+**Rationale:** The apply skill is already complex. Multi-agent adds team creation, task list population, teammate spawning, progress monitoring, and shutdown — fundamentally different from sequential task execution. Keeping them separate avoids conditional branching in the apply prompt and lets each skill be focused.
+
+**Alternative considered:** Adding a `--multiagent` flag to `/opsx:apply`. Rejected because it would make the apply prompt too long and hard to maintain.
+
+### 3. Worktree isolation for all teammates
+
+**Decision:** All spawned teammates use `isolation: "worktree"` to get an isolated copy of the repository.
+
+**Rationale:** Multiple agents writing to the same repo simultaneously causes conflicts. Worktrees give each agent a private branch. After completion, the user (or the team lead agent) can merge branches. This aligns with how Claude Code's Agent tool is designed to work in team scenarios.
+
+### 4. Task list as the coordination mechanism
+
+**Decision:** Use Claude Code's `TaskCreate`/`TaskUpdate`/`TaskList` tools as the shared coordination layer between agents, not file-based coordination.
+
+**Rationale:** Claude Code's task list is purpose-built for multi-agent coordination — it supports ownership, status tracking, and dependency relationships (`blockedBy`/`addBlocks`). Writing a custom file-based tracker would duplicate this functionality.
+
+### 5. Distribution template uses descriptive instructions, not tool-call JSON
+
+**Decision:** The "Claude Code Team Setup" section in `distribution.md` describes team setup in natural language with parameter listings, not raw JSON tool calls.
+
+**Rationale:** The distribution.md is a planning document read by both humans and AI. Raw JSON would be harder for humans to review. The `/opsx:multiagent-apply` skill is responsible for translating the plan into actual tool calls.
+
+## Risks / Trade-offs
+
+**[Worktree merge conflicts]** → Agents work on isolated branches, but merging may produce conflicts. Mitigation: the distribution plan enforces file ownership isolation (one agent per file). The skill warns if isolation is violated.
+
+**[Token cost scaling]** → N agents ≈ N× token cost. Mitigation: the skill displays an explicit cost warning and asks for confirmation before spawning. The distribution artifact already includes a cost warning section.
+
+**[Cross-agent sync latency]** → If agent A blocks agent B, B idles until A completes the blocking task. Mitigation: the dependency analysis minimizes cross-agent dependencies; the distribution plan groups dependent tasks into the same agent where possible.
+
+**[Skill prompt length]** → The multiagent-apply skill prompt is necessarily longer than simpler skills. Mitigation: structure the prompt with clear numbered steps and keep orchestration logic in the skill, not in the schema instruction.
+
+## Migration Plan
+
+No migration needed — this adds new capabilities without changing existing ones. The `/opsx:apply` skill continues to work unchanged for single-agent and `spec-driven` workflows. Users opt into multi-agent execution by using `/opsx:multiagent` (planning) followed by `/opsx:multiagent-apply` (execution).
+
+The `TodoWrite` → `TaskCreate`/`TaskUpdate` fix in `/opsx:multiagent` is backward-compatible since `TodoWrite` was already non-functional in current Claude Code.
+
+## Parallelism Considerations
+
+Three independent workstreams:
+
+1. **New skill template** (`multiagent-apply.ts`): The new `/opsx:multiagent-apply` skill and command templates. No dependencies on the other two workstreams — can be built first or in parallel.
+
+2. **Template fixes** (`multiagent.ts` + `distribution.md`): Update the existing `/opsx:multiagent` skill to fix `TodoWrite` references and update the distribution template's team setup section. Independent of workstream 1.
+
+3. **Schema instruction update** (`schema.yaml`): Update `dispec-driven`'s `apply.instruction` and `distribution` artifact instruction. Depends on workstream 1 being defined (needs to reference the new skill name) but can be written in parallel once the skill name is agreed (`/opsx:multiagent-apply`).
+
+**Serialization point:** Tests should be written after all three workstreams are complete, as they may need to verify the integration between the skill, template, and schema.
+
+## Open Questions
+
+1. **Should the team lead agent remain active for monitoring, or hand off to the user?** Current design: the skill acts as team lead, monitors progress via `TaskList`, and sends `shutdown_request` when done. Alternative: create the team and return immediately, letting the user monitor.
+
+2. **Should multiagent-apply automatically merge worktree branches?** Current design: no — agents produce branches, user merges. This is safer but adds a manual step.

openspec/changes/add-multiagent-apply-workflow/distribution.md

@@ -0,0 +1,172 @@
+## Configuration
+
+- **Agent count**: 3
+- **Total tasks**: 22
+- **Tasks per agent**: ~7
+
+## Token Cost Warning
+
+> **Multi-agent execution scales token costs.** Each agent maintains its own context window.
+> With 3 agents, expect roughly 3× the token usage of a single-agent run.
+> Estimated cost multiplier: **3×**
+
+## Feasibility Assessment
+
+3 agents is feasible. The dependency graph shows three natural clusters:
+
+1. **New skill creation** (tasks 1.x, 2.x) — all centered on the new `multiagent-apply.ts` file and its registration
+2. **Existing template fixes** (tasks 3.x, 4.x, 5.x, 6.x) — edits to existing files, fully independent of cluster 1
+3. **Tests** (tasks 7.x) — depends on both clusters completing first
+
+With 3 agents, cross-agent dependencies are minimal: only the test agent needs to wait for the other two.
+
+## Agent Assignments
+
+### Agent 1: new-skill
+
+**Focus:** Create the new `/opsx:multiagent-apply` skill template and register it in the system.
+
+**Tasks:**
+- 1.1 Create `multiagent-apply.ts` file
+- 1.2 Write skill instructions prompt
+- 1.3 Write command template content
+- 2.1 Export from `skill-templates.ts`
+- 2.2 Register in `getSkillTemplates()`
+- 2.3 Register in `getCommandTemplates()`
+- 2.4 Add `'multiagent-apply'` to `ALL_WORKFLOWS`
+
+**File ownership:**
+- `src/core/templates/workflows/multiagent-apply.ts` (create)
+- `src/core/templates/skill-templates.ts` (edit)
+- `src/core/shared/skill-generation.ts` (edit)
+- `src/core/profiles.ts` (edit)
+
+**Execution order:**
+1.1 → 1.2 → 1.3 → 2.1 → 2.2 → 2.3 → 2.4
+
+**Cross-agent dependencies:**
+- None. This agent works independently.
+
+### Agent 2: template-fixes
+
+**Focus:** Fix the existing multiagent skill, distribution template, schema instructions, and tool detection.
+
+**Tasks:**
+- 3.1 Fix TodoWrite in skill template
+- 3.2 Fix TodoWrite in command template
+- 3.3 Update output section to reference `/opsx:multiagent-apply`
+- 4.1 Update distribution.md template team setup section
+- 5.1 Update distribution artifact instruction in schema.yaml
+- 5.2 Update apply.instruction in schema.yaml
+- 6.1 Add to tool-detection.ts
+- 6.2 Add to init.ts
+
+**File ownership:**
+- `src/core/templates/workflows/multiagent.ts` (edit)
+- `schemas/dispec-driven/templates/distribution.md` (edit)
+- `schemas/dispec-driven/schema.yaml` (edit)
+- `src/core/shared/tool-detection.ts` (edit)
+- `src/core/init.ts` (edit)
+
+**Execution order:**
+3.1 → 3.2 → 3.3 → 4.1 → 5.1 → 5.2 → 6.1 → 6.2
+
+**Cross-agent dependencies:**
+- None. This agent works independently.
+
+### Agent 3: tests
+
+**Focus:** Write and update all tests, verify integration.
+
+**Tasks:**
+- 7.1 Test `getOpsxMultiagentApplySkillTemplate()`
+- 7.2 Test `getOpsxMultiagentApplyCommandTemplate()`
+- 7.3 Update parity test
+- 7.4 Test ALL_WORKFLOWS includes `'multiagent-apply'`
+- 7.5 Update skill-generation test counts
+- 7.6 Regression check dispec-driven tests
+- 7.7 Verify TodoWrite removal
+
+**File ownership:**
+- `test/core/templates/multiagent-apply.test.ts` (create)
+- `test/core/templates/skill-templates-parity.test.ts` (edit)
+- `test/core/profiles.test.ts` (edit)
+- `test/core/shared/skill-generation.test.ts` (edit)
+- `test/core/artifact-graph/dispec-driven.test.ts` (read-only)
+
+**Execution order:**
+7.6 (can start immediately) → wait for Agent 1 and Agent 2 → 7.1 → 7.2 → 7.3 → 7.4 → 7.5 → 7.7
+
+**Cross-agent dependencies:**
+- 7.1, 7.2 blocked by Agent 1 completing tasks 1.1–1.3
+- 7.3, 7.5 blocked by Agent 1 completing tasks 2.1–2.3
+- 7.4 blocked by Agent 1 completing task 2.4
+- 7.7 blocked by Agent 2 completing tasks 3.1–3.2
+
+## File Ownership Isolation
+
+| File | Owner Agent | Notes |
+|------|-------------|-------|
+| `src/core/templates/workflows/multiagent-apply.ts` | new-skill | New file, exclusive |
+| `src/core/templates/skill-templates.ts` | new-skill | Add export line |
+| `src/core/shared/skill-generation.ts` | new-skill | Add entries to arrays |
+| `src/core/profiles.ts` | new-skill | Add to ALL_WORKFLOWS |
+| `src/core/templates/workflows/multiagent.ts` | template-fixes | Edit existing content |
+| `schemas/dispec-driven/templates/distribution.md` | template-fixes | Edit template |
+| `schemas/dispec-driven/schema.yaml` | template-fixes | Edit instructions |
+| `src/core/shared/tool-detection.ts` | template-fixes | Add workflow entry |
+| `src/core/init.ts` | template-fixes | Add workflow entry |
+| `test/core/templates/multiagent-apply.test.ts` | tests | New file, exclusive |
+| `test/core/templates/skill-templates-parity.test.ts` | tests | Edit assertions |
+| `test/core/profiles.test.ts` | tests | Edit assertions |
+| `test/core/shared/skill-generation.test.ts` | tests | Edit assertions |
+
+No file ownership conflicts detected. Each file is owned by exactly one agent.
+
+## Cross-Agent Dependencies
+
+| Waiting Agent | Blocked Task | Depends On | Owning Agent |
+|---------------|-------------|------------|--------------|
+| tests | 7.1 | 1.1, 1.2, 1.3 | new-skill |
+| tests | 7.2 | 1.1, 1.2, 1.3 | new-skill |
+| tests | 7.3 | 2.1, 2.2, 2.3 | new-skill |
+| tests | 7.4 | 2.4 | new-skill |
+| tests | 7.5 | 2.2, 2.3 | new-skill |
+| tests | 7.7 | 3.1, 3.2 | template-fixes |
+
+The tests agent is the only one with cross-agent dependencies. Agents "new-skill" and "template-fixes" are fully independent of each other.
+
+## Claude Code Team Setup
+
+To execute this plan, use `/opsx:multiagent-apply` on the `add-multiagent-apply-workflow` change.
+
+Alternatively, set up the team manually:
+
+**1. Create the team:**
+
+Use `TeamCreate` with:
+- `team_name`: `"add-multiagent-apply-workflow"`
+- `description`: `"Add /opsx:multiagent-apply skill and fix existing multiagent workflow"`
+
+**2. Create tasks in the shared task list:**
+
+Use `TaskCreate` for each of the 22 tasks from `tasks.md`. Include the task description as `subject`, the `Files:` annotation as `description`, and a present-continuous `activeForm` (e.g., "Creating multiagent-apply.ts").
+
+After all tasks are created, use `TaskUpdate` with `addBlockedBy` to set up dependency relationships, and `TaskUpdate` with `owner` to pre-assign tasks to agents per the assignment cards above.
+
+**3. Spawn teammates:**
+
+Use the `Agent` tool three times, once per agent:
+
+- Agent: `name: "new-skill"`, `team_name: "add-multiagent-apply-workflow"`, `subagent_type: "general-purpose"`, `isolation: "worktree"`
+  - Prompt: Assign tasks 1.1–1.3, 2.1–2.4. Include file ownership list and execution order.
+
+- Agent: `name: "template-fixes"`, `team_name: "add-multiagent-apply-workflow"`, `subagent_type: "general-purpose"`, `isolation: "worktree"`
+  - Prompt: Assign tasks 3.1–3.3, 4.1, 5.1–5.2, 6.1–6.2. Include file ownership list and execution order.
+
+- Agent: `name: "tests"`, `team_name: "add-multiagent-apply-workflow"`, `subagent_type: "general-purpose"`, `isolation: "worktree"`
+  - Prompt: Assign tasks 7.1–7.7. Note cross-agent dependencies: start with 7.6 (no deps), then wait for new-skill and template-fixes to complete before running remaining tests.
+
+**4. Monitor and shutdown:**
+
+Use `TaskList` to monitor progress. When all tasks are completed, send `shutdown_request` to each teammate via `SendMessage`.