feat: add multi-agent orchestration workflow with dispec-driven schema#790
Open
pformoso-deus-ai wants to merge 7 commits intoFission-AI:mainfrom
Open
feat: add multi-agent orchestration workflow with dispec-driven schema#790pformoso-deus-ai wants to merge 7 commits intoFission-AI:mainfrom
pformoso-deus-ai wants to merge 7 commits intoFission-AI:mainfrom
Conversation
Add a new built-in schema for distributed spec-driven development that extends the standard workflow with dependency analysis and task distribution artifacts, enabling multi-agent parallel execution. New schema (dispec-driven) with 6 artifacts: proposal → specs → design → tasks → dependencies → distribution New /opsx:multiagent slash command drives the end-to-end workflow, including agent count selection and token cost warnings. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a new skill that bridges the dispec-driven distribution plan to Claude Code agent team execution. The skill reads distribution.md and orchestrates TeamCreate, TaskCreate, and Agent spawning with worktree isolation for parallel implementation. Also fixes the existing /opsx:multiagent skill: - Replace deprecated TodoWrite with TaskCreate/TaskUpdate - Update output to reference /opsx:multiagent-apply - Update distribution.md template with real team primitives - Update dispec-driven schema apply instruction for multi-agent flow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…nges Archive fix-opencode-commands-directory and graceful-status-no-changes since both have been implemented and merged. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
npm v11's git dep preparation runs `prepare` before node_modules exist in the temp clone directory. This causes TypeScript compilation to fail. Changes: - build.js: skip build gracefully when node_modules absent, use node directly instead of pnpm for npm compatibility - package.json: add `prepack` hook for pack-phase build, make postinstall non-fatal (|| true) to handle stale CWD after temp dir cleanup Install from GitHub with: npm pack github:user/repo#branch npm install -g ./fission-ai-openspec-1.2.0.tgz Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review infoConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (4)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughThis PR introduces a multi-agent orchestration framework featuring a new dispec-driven schema with six artifacts (proposal, specs, design, tasks, dependencies, distribution) that enables distributed task execution across Claude Code agent teams. It adds two workflows: Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (6)
src/core/profile-sync-drift.ts (1)
14-28: Consider consolidating duplicateWORKFLOW_TO_SKILL_DIRmapping.This constant is duplicated in
src/core/init.ts(lines 63-77). Both files must be kept in sync when adding new workflows. Consider extracting this mapping to a shared location (e.g., a constants file or re-exporting from one module) to ensure consistency and reduce maintenance burden.Note: The typing here (
Record<WorkflowId, string>) is stricter than ininit.ts(Record<string, string>), which provides better compile-time safety.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/profile-sync-drift.ts` around lines 14 - 28, WORKFLOW_TO_SKILL_DIR is duplicated and should be centralized: create a shared constant module (e.g., export WORKFLOW_TO_SKILL_DIR from a new/shared constants file) and import it from both profile-sync-drift and init, preserving the stricter typing Record<WorkflowId, string>; ensure you export the WorkflowId type or import it into the shared module so the mapping uses the same type, replace the local declarations in src/core/profile-sync-drift and src/core/init.ts with imports from the new module, and run type checks to confirm no regressions.test/core/templates/multiagent-apply.test.ts (1)
68-71: Add positive primitive assertions for command content.This test currently only checks exclusion of
TodoWrite; consider also assertingTeamCreate,TaskCreate, andTaskUpdatepresence for stronger regression protection.Suggested test addition
it('should not reference TodoWrite', () => { const template = getOpsxMultiagentApplyCommandTemplate(); expect(template.content).not.toContain('TodoWrite'); }); + + it('should include required team/task primitives', () => { + const template = getOpsxMultiagentApplyCommandTemplate(); + expect(template.content).toContain('TeamCreate'); + expect(template.content).toContain('TaskCreate'); + expect(template.content).toContain('TaskUpdate'); + });🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@test/core/templates/multiagent-apply.test.ts` around lines 68 - 71, The test only asserts that 'TodoWrite' is absent; add positive assertions to also verify the command template includes expected primitives by checking that getOpsxMultiagentApplyCommandTemplate().content contains 'TeamCreate', 'TaskCreate', and 'TaskUpdate'. Update the test (the it block using getOpsxMultiagentApplyCommandTemplate and template.content) to add expect(...).toContain(...) checks for those three symbols to provide stronger regression protection.test/core/shared/skill-generation.test.ts (1)
11-13: Reduce repeated hardcoded template-count literals.Using a shared constant here will make future workflow additions less error-prone.
Refactor example
+const EXPECTED_TEMPLATE_COUNT = 13; + describe('skill-generation', () => { describe('getSkillTemplates', () => { it('should return all 13 skill templates', () => { const templates = getSkillTemplates(); - expect(templates).toHaveLength(13); + expect(templates).toHaveLength(EXPECTED_TEMPLATE_COUNT); }); @@ describe('getCommandTemplates', () => { it('should return all 13 command templates', () => { const templates = getCommandTemplates(); - expect(templates).toHaveLength(13); + expect(templates).toHaveLength(EXPECTED_TEMPLATE_COUNT); }); @@ describe('getCommandContents', () => { it('should return all 13 command contents', () => { const contents = getCommandContents(); - expect(contents).toHaveLength(13); + expect(contents).toHaveLength(EXPECTED_TEMPLATE_COUNT); });Also applies to: 93-95, 149-151
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@test/core/shared/skill-generation.test.ts` around lines 11 - 13, The tests in skill-generation.test.ts use repeated hardcoded numbers (e.g., expect(...).toHaveLength(13)) making future changes brittle; update the tests to reference a shared constant instead: either export the templates array or a SKILL_TEMPLATES_COUNT (or SKILL_TEMPLATES.length) from the module that implements getSkillTemplates() and replace hardcoded literals in the tests (all occurrences around the getSkillTemplates checks) with that exported value so the assertions derive from the single source of truth.src/core/templates/workflows/multiagent-apply.ts (1)
47-51: Make file-ownership conflict detection an explicit preflight step.Guardrails require conflict handling, but the step-by-step flow should explicitly perform that check before
TeamCreate.Instruction-flow tweak
Extract from `distribution.md`: - Agent count and names - Each agent's assigned task IDs, file ownership, execution order - Cross-agent dependency table + - Validate no overlapping writable file ownership across agents + + If conflicts exist: + - Warn the user with the conflicting files/agents + - Ask whether to proceed or reassign + - Stop before `TeamCreate` if user does not approveAlso applies to: 134-141
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/templates/workflows/multiagent-apply.ts` around lines 47 - 51, Add an explicit preflight step that runs file-ownership conflict detection and resolves/blocks conflicts before invoking TeamCreate in the multi-agent apply workflow; locate the sequence around TeamCreate in multiagent-apply.ts and insert a guarded "FileOwnershipPreflight" (or similar) action that reads the extracted distribution info (agent count/names, assigned task IDs, file ownership, execution order, cross-agent dependency table) and fails fast or surfaces conflicts to the caller, and apply the same insertion/guarding logic where the flow duplicates at the other spot referenced (the block corresponding to lines 134-141) so file-ownership conflicts are always checked prior to TeamCreate.schemas/dispec-driven/schema.yaml (1)
3-3: Update the schema description to reflect parallelspecs/designdependencies.Current text implies strict sequencing, but the declared graph allows
specsanddesignin parallel afterproposal. Consider wording likeproposal → (specs + design) → tasks → dependencies → distribution.📝 Suggested edit
-description: Distributed spec-driven workflow - proposal → specs → design → tasks → dependencies → distribution +description: Distributed spec-driven workflow - proposal → (specs + design) → tasks → dependencies → distributionBased on learnings: In the OpenSpec spec-driven schema,
specsanddesignartifacts are parallel dependencies that both depend only onproposal.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@schemas/dispec-driven/schema.yaml` at line 3, Update the "description" field in the schema (the line currently reading "Distributed spec-driven workflow - proposal → specs → design → tasks → dependencies → distribution") to reflect that "specs" and "design" are parallel dependencies of "proposal" (e.g., change to "Distributed spec-driven workflow - proposal → (specs + design) → tasks → dependencies → distribution"); locate the description key in the schema.yaml and replace the sequencing text so it explicitly shows specs and design as parallel artifacts that both depend only on proposal.src/core/templates/workflows/multiagent.ts (1)
13-126: Extract a single shared body constant to prevent skill/command drift.The instruction text is duplicated across
instructionsandcontent; this is brittle and conflicts with the shared-body intent.♻️ Refactor sketch
+const MULTIAGENT_BODY = `Plan and distribute a change across multiple AI agents for parallel execution. +... +`; + export function getOpsxMultiagentSkillTemplate(): SkillTemplate { return { name: 'openspec-multiagent', description: 'Plan and distribute a change across multiple AI agents for parallel execution. Use when the user wants to break down a complex change into tasks that can be worked on simultaneously by a team of agents.', - instructions: `Plan and distribute a change across multiple AI agents for parallel execution. -...`, + instructions: MULTIAGENT_BODY, license: 'MIT', compatibility: 'Requires openspec CLI.', metadata: { author: 'openspec', version: '1.0' }, }; } @@ export function getOpsxMultiagentCommandTemplate(): CommandTemplate { return { @@ - content: `Plan and distribute a change across multiple AI agents for parallel execution. -...` + content: MULTIAGENT_BODY }; }Also applies to: 139-252
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/templates/workflows/multiagent.ts` around lines 13 - 126, The instructions and content fields (the multi-agent workflow text duplicated in the template's instructions and content properties) should be consolidated into a single shared constant and referenced from both places to avoid drift; create a constant (e.g., SHARED_WORKFLOW_BODY or MULTIAGENT_SHARED_BODY) containing the full instruction text, replace the duplicated literal strings used for the "instructions" and "content" properties in the exported template object with references to that constant, and ensure any future edits update only the constant; update symbols: the template's instructions property, content property, and the exported object (the multiagent template definition) to use the new shared constant.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/changes/add-multiagent-apply-workflow/dependencies.md`:
- Around line 98-100: The Text DAG shows task 3.3 connected to the path toward
7.7, which conflicts with the Dependency Matrix that lists 7.7 as depending only
on 3.1 and 3.2; update the DAG so task 3.3 ("Update output section reference")
is not shown as feeding into 7.7, or alternatively update the Dependency Matrix
to include 3.3 if it truly is a dependency; make the change consistently in the
Text DAG visualization and the Dependency Matrix entries (referencing tasks 3.3
and 7.7 and the Dependency Matrix row currently mentioning 7.7) so both
representations match.
In `@openspec/changes/add-multiagent-apply-workflow/distribution.md`:
- Around line 102-104: The dependency for Task 7.5 is inconsistent between the
two sections: one lists it as blocked by tasks 2.1–2.3 while the other lists
2.2–2.3; update both occurrences so they match (choose the correct dependency
set, e.g., 2.1–2.3) to ensure the `TaskUpdate addBlockedBy` wiring is generated
consistently for Task 7.5 and likewise make the same correction in the other
affected occurrence referenced in the doc.
In `@schemas/dispec-driven/templates/dependencies.md`:
- Around line 30-37: The fenced code block containing the ASCII dependency graph
(the triple-backtick block starting at the comment's ASCII representation) lacks
a language tag and triggers MD040; update that fence to include a language tag
(e.g., "text") so the block becomes a typed fenced code block (```text ... ```),
leaving the ASCII content unchanged.
In `@schemas/dispec-driven/templates/distribution.md`:
- Around line 21-48: The template hard-codes two agent cards ("Agent 1:" and
"Agent 2:") so plans for 3–5 agents are incomplete; change distribution.md to
render a repeatable agent card block instead of duplicated static headings by
replacing the two fixed sections with a single templated/repeatable block that
iterates over an agents collection and emits the headings and placeholders
("**Tasks:**", "**File ownership:**", "**Execution order:**", "**Cross-agent
dependencies:**") for each agent; ensure the iteration uses the repo's
templating syntax (e.g., the existing template engine/variable name for agents)
and includes an index or agent.name to label each card (e.g., "Agent {{index}}:"
or "Agent {{agent.name}}:") so any N agents are supported.
In `@src/core/templates/workflows/multiagent.ts`:
- Around line 77-86: The AskUserQuestion handling for the distribution artifact
currently only special-cases selecting 1 agent; update the prompt parsing logic
that handles the agent-count response (the AskUserQuestion handling for the
distribution artifact and the identical block used later around the multi-agent
selection) to explicitly validate the numeric choice: if the user selects 1 keep
the existing /opsx:propose suggestion, if they select a value outside the
allowed 2..5 range (including >5) return a clear message recommending the valid
range (e.g., "Please choose between 2 and 5 agents; 3 is recommended") and
reprompt the AskUserQuestion rather than proceeding, and only accept/continue
when a valid 2,3,4 or 5 selection is made; apply this validation change to both
the first distribution prompt handler and the duplicate block later in the file.
---
Nitpick comments:
In `@schemas/dispec-driven/schema.yaml`:
- Line 3: Update the "description" field in the schema (the line currently
reading "Distributed spec-driven workflow - proposal → specs → design → tasks →
dependencies → distribution") to reflect that "specs" and "design" are parallel
dependencies of "proposal" (e.g., change to "Distributed spec-driven workflow -
proposal → (specs + design) → tasks → dependencies → distribution"); locate the
description key in the schema.yaml and replace the sequencing text so it
explicitly shows specs and design as parallel artifacts that both depend only on
proposal.
In `@src/core/profile-sync-drift.ts`:
- Around line 14-28: WORKFLOW_TO_SKILL_DIR is duplicated and should be
centralized: create a shared constant module (e.g., export WORKFLOW_TO_SKILL_DIR
from a new/shared constants file) and import it from both profile-sync-drift and
init, preserving the stricter typing Record<WorkflowId, string>; ensure you
export the WorkflowId type or import it into the shared module so the mapping
uses the same type, replace the local declarations in
src/core/profile-sync-drift and src/core/init.ts with imports from the new
module, and run type checks to confirm no regressions.
In `@src/core/templates/workflows/multiagent-apply.ts`:
- Around line 47-51: Add an explicit preflight step that runs file-ownership
conflict detection and resolves/blocks conflicts before invoking TeamCreate in
the multi-agent apply workflow; locate the sequence around TeamCreate in
multiagent-apply.ts and insert a guarded "FileOwnershipPreflight" (or similar)
action that reads the extracted distribution info (agent count/names, assigned
task IDs, file ownership, execution order, cross-agent dependency table) and
fails fast or surfaces conflicts to the caller, and apply the same
insertion/guarding logic where the flow duplicates at the other spot referenced
(the block corresponding to lines 134-141) so file-ownership conflicts are
always checked prior to TeamCreate.
In `@src/core/templates/workflows/multiagent.ts`:
- Around line 13-126: The instructions and content fields (the multi-agent
workflow text duplicated in the template's instructions and content properties)
should be consolidated into a single shared constant and referenced from both
places to avoid drift; create a constant (e.g., SHARED_WORKFLOW_BODY or
MULTIAGENT_SHARED_BODY) containing the full instruction text, replace the
duplicated literal strings used for the "instructions" and "content" properties
in the exported template object with references to that constant, and ensure any
future edits update only the constant; update symbols: the template's
instructions property, content property, and the exported object (the multiagent
template definition) to use the new shared constant.
In `@test/core/shared/skill-generation.test.ts`:
- Around line 11-13: The tests in skill-generation.test.ts use repeated
hardcoded numbers (e.g., expect(...).toHaveLength(13)) making future changes
brittle; update the tests to reference a shared constant instead: either export
the templates array or a SKILL_TEMPLATES_COUNT (or SKILL_TEMPLATES.length) from
the module that implements getSkillTemplates() and replace hardcoded literals in
the tests (all occurrences around the getSkillTemplates checks) with that
exported value so the assertions derive from the single source of truth.
In `@test/core/templates/multiagent-apply.test.ts`:
- Around line 68-71: The test only asserts that 'TodoWrite' is absent; add
positive assertions to also verify the command template includes expected
primitives by checking that getOpsxMultiagentApplyCommandTemplate().content
contains 'TeamCreate', 'TaskCreate', and 'TaskUpdate'. Update the test (the it
block using getOpsxMultiagentApplyCommandTemplate and template.content) to add
expect(...).toContain(...) checks for those three symbols to provide stronger
regression protection.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (42)
.changeset/multiagent-workflow.mdbuild.jsopenspec/changes/add-multiagent-apply-workflow/.openspec.yamlopenspec/changes/add-multiagent-apply-workflow/dependencies.mdopenspec/changes/add-multiagent-apply-workflow/design.mdopenspec/changes/add-multiagent-apply-workflow/distribution.mdopenspec/changes/add-multiagent-apply-workflow/proposal.mdopenspec/changes/add-multiagent-apply-workflow/specs/command-generation/spec.mdopenspec/changes/add-multiagent-apply-workflow/specs/multiagent-apply/spec.mdopenspec/changes/add-multiagent-apply-workflow/tasks.mdopenspec/changes/archive/2025-02-28-fix-opencode-commands-directory/.openspec.yamlopenspec/changes/archive/2025-02-28-fix-opencode-commands-directory/design.mdopenspec/changes/archive/2025-02-28-fix-opencode-commands-directory/proposal.mdopenspec/changes/archive/2025-02-28-fix-opencode-commands-directory/specs/command-generation/spec.mdopenspec/changes/archive/2025-02-28-fix-opencode-commands-directory/tasks.mdopenspec/changes/archive/2025-02-28-graceful-status-no-changes/.openspec.yamlopenspec/changes/archive/2025-02-28-graceful-status-no-changes/design.mdopenspec/changes/archive/2025-02-28-graceful-status-no-changes/proposal.mdopenspec/changes/archive/2025-02-28-graceful-status-no-changes/specs/graceful-status-empty/spec.mdopenspec/changes/archive/2025-02-28-graceful-status-no-changes/tasks.mdpackage.jsonschemas/dispec-driven/schema.yamlschemas/dispec-driven/templates/dependencies.mdschemas/dispec-driven/templates/design.mdschemas/dispec-driven/templates/distribution.mdschemas/dispec-driven/templates/proposal.mdschemas/dispec-driven/templates/spec.mdschemas/dispec-driven/templates/tasks.mdsrc/core/init.tssrc/core/profile-sync-drift.tssrc/core/profiles.tssrc/core/shared/skill-generation.tssrc/core/shared/tool-detection.tssrc/core/templates/skill-templates.tssrc/core/templates/workflows/multiagent-apply.tssrc/core/templates/workflows/multiagent.tstest/core/artifact-graph/dispec-driven.test.tstest/core/profiles.test.tstest/core/shared/skill-generation.test.tstest/core/shared/tool-detection.test.tstest/core/templates/multiagent-apply.test.tstest/core/templates/skill-templates-parity.test.ts
Comment on lines
+98
to
+100
| [3.1] ──┐ | ||
| [3.2] ──┼──────────────→ [7.7] | ||
| [3.3] │ |
Contributor
There was a problem hiding this comment.
Minor inconsistency in Text DAG.
The Text DAG shows task 3.3 connected to the arrow leading to 7.7, but the Dependency Matrix (line 26) specifies that task 7.7 only depends on tasks 3.1 and 3.2 ("Verifies TodoWrite removal"). If 3.3 ("Update output section reference") is not a dependency of 7.7, the DAG visualization may be misleading.
📝 Suggested fix
[3.1] ──┐
-[3.2] ──┼──────────────→ [7.7]
-[3.3] │
+[3.2] ──┴──────────────→ [7.7]
+
+[3.3]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/add-multiagent-apply-workflow/dependencies.md` around lines
98 - 100, The Text DAG shows task 3.3 connected to the path toward 7.7, which
conflicts with the Dependency Matrix that lists 7.7 as depending only on 3.1 and
3.2; update the DAG so task 3.3 ("Update output section reference") is not shown
as feeding into 7.7, or alternatively update the Dependency Matrix to include
3.3 if it truly is a dependency; make the change consistently in the Text DAG
visualization and the Dependency Matrix entries (referencing tasks 3.3 and 7.7
and the Dependency Matrix row currently mentioning 7.7) so both representations
match.
Comment on lines
+102
to
+104
| - 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 |
Contributor
There was a problem hiding this comment.
Align Task 7.5 dependency definitions across sections.
Line 102 says 7.5 is blocked by 2.1–2.3, but Line 134 says 2.2–2.3. Keep this consistent to avoid incorrect TaskUpdate addBlockedBy wiring.
Suggested doc fix
- - 7.3, 7.5 blocked by Agent 1 completing tasks 2.1–2.3
+ - 7.3 blocked by Agent 1 completing tasks 2.1–2.3
+ - 7.5 blocked by Agent 1 completing tasks 2.2–2.3Also applies to: 134-135
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/add-multiagent-apply-workflow/distribution.md` around lines
102 - 104, The dependency for Task 7.5 is inconsistent between the two sections:
one lists it as blocked by tasks 2.1–2.3 while the other lists 2.2–2.3; update
both occurrences so they match (choose the correct dependency set, e.g.,
2.1–2.3) to ensure the `TaskUpdate addBlockedBy` wiring is generated
consistently for Task 7.5 and likewise make the same correction in the other
affected occurrence referenced in the doc.
Comment on lines
+30
to
+37
| ``` | ||
| <!-- ASCII representation of the dependency graph | ||
| Example: | ||
| [1.1] ──→ [2.1] ──→ [3.1] | ||
| ↓ | ||
| [1.2] ──→ [2.2] ──→ [3.2] | ||
| --> | ||
| ``` |
Contributor
There was a problem hiding this comment.
Add a language tag to the fenced block to satisfy markdownlint.
Line 30 currently uses an untyped fence, which triggers MD040.
✏️ Suggested patch
-```
+```text
<!-- ASCII representation of the dependency graph
Example:
[1.1] ──→ [2.1] ──→ [3.1]
↓
[1.2] ──→ [2.2] ──→ [3.2]
--></details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @schemas/dispec-driven/templates/dependencies.md around lines 30 - 37, The
fenced code block containing the ASCII dependency graph (the triple-backtick
block starting at the comment's ASCII representation) lacks a language tag and
triggers MD040; update that fence to include a language tag (e.g., "text") so
the block becomes a typed fenced code block (text ... ), leaving the ASCII
content unchanged.
</details>
<!-- fingerprinting:phantom:poseidon:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
Comment on lines
+21
to
+48
| ### Agent 1: <!-- agent name/focus area --> | ||
|
|
||
| **Tasks:** | ||
| <!-- List assigned task IDs --> | ||
|
|
||
| **File ownership:** | ||
| <!-- Files this agent is responsible for --> | ||
|
|
||
| **Execution order:** | ||
| <!-- Order respecting dependencies --> | ||
|
|
||
| **Cross-agent dependencies:** | ||
| <!-- Tasks from other agents this agent must wait for --> | ||
|
|
||
| ### Agent 2: <!-- agent name/focus area --> | ||
|
|
||
| **Tasks:** | ||
| <!-- List assigned task IDs --> | ||
|
|
||
| **File ownership:** | ||
| <!-- Files this agent is responsible for --> | ||
|
|
||
| **Execution order:** | ||
| <!-- Order respecting dependencies --> | ||
|
|
||
| **Cross-agent dependencies:** | ||
| <!-- Tasks from other agents this agent must wait for --> | ||
|
|
Contributor
There was a problem hiding this comment.
Make assignment cards repeatable for N agents (not fixed to two).
The template currently hard-codes only two agent cards, but the workflow supports larger teams. This causes incomplete plans when users choose 3–5 agents.
♻️ Suggested template refactor
## Agent Assignments
-### Agent 1: <!-- agent name/focus area -->
+<!-- Copy this assignment card once per configured agent (1..N). -->
+### Agent <N>: <!-- agent name/focus area -->
**Tasks:**
<!-- List assigned task IDs -->
**File ownership:**
<!-- Files this agent is responsible for -->
**Execution order:**
<!-- Order respecting dependencies -->
**Cross-agent dependencies:**
<!-- Tasks from other agents this agent must wait for -->
-
-### Agent 2: <!-- agent name/focus area -->
-
-**Tasks:**
-<!-- List assigned task IDs -->
-
-**File ownership:**
-<!-- Files this agent is responsible for -->
-
-**Execution order:**
-<!-- Order respecting dependencies -->
-
-**Cross-agent dependencies:**
-<!-- Tasks from other agents this agent must wait for -->📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### Agent 1: <!-- agent name/focus area --> | |
| **Tasks:** | |
| <!-- List assigned task IDs --> | |
| **File ownership:** | |
| <!-- Files this agent is responsible for --> | |
| **Execution order:** | |
| <!-- Order respecting dependencies --> | |
| **Cross-agent dependencies:** | |
| <!-- Tasks from other agents this agent must wait for --> | |
| ### Agent 2: <!-- agent name/focus area --> | |
| **Tasks:** | |
| <!-- List assigned task IDs --> | |
| **File ownership:** | |
| <!-- Files this agent is responsible for --> | |
| **Execution order:** | |
| <!-- Order respecting dependencies --> | |
| **Cross-agent dependencies:** | |
| <!-- Tasks from other agents this agent must wait for --> | |
| ## Agent Assignments | |
| <!-- Copy this assignment card once per configured agent (1..N). --> | |
| ### Agent <N>: <!-- agent name/focus area --> | |
| **Tasks:** | |
| <!-- List assigned task IDs --> | |
| **File ownership:** | |
| <!-- Files this agent is responsible for --> | |
| **Execution order:** | |
| <!-- Order respecting dependencies --> | |
| **Cross-agent dependencies:** | |
| <!-- Tasks from other agents this agent must wait for --> |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@schemas/dispec-driven/templates/distribution.md` around lines 21 - 48, The
template hard-codes two agent cards ("Agent 1:" and "Agent 2:") so plans for 3–5
agents are incomplete; change distribution.md to render a repeatable agent card
block instead of duplicated static headings by replacing the two fixed sections
with a single templated/repeatable block that iterates over an agents collection
and emits the headings and placeholders ("**Tasks:**", "**File ownership:**",
"**Execution order:**", "**Cross-agent dependencies:**") for each agent; ensure
the iteration uses the repo's templating syntax (e.g., the existing template
engine/variable name for agents) and includes an index or agent.name to label
each card (e.g., "Agent {{index}}:" or "Agent {{agent.name}}:") so any N agents
are supported.
Greptile SummaryAdded multi-agent orchestration workflow for distributing OpenSpec changes across parallel AI agents. Introduces the Key additions:
Implementation quality:
Confidence Score: 5/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
Start([User runs /opsx:multiagent]) --> CreateChange[Create change with dispec-driven schema]
CreateChange --> Proposal[Create proposal.md]
Proposal --> ParallelPhase{Parallel Phase}
ParallelPhase --> Specs[Create specs/]
ParallelPhase --> Design[Create design.md]
Specs --> Tasks[Create tasks.md]
Design --> Tasks
Tasks --> Dependencies[Analyze dependencies.md]
Dependencies --> Distribution[Generate distribution.md<br/>with agent assignments]
Distribution --> Ready{Ready for<br/>implementation?}
Ready -->|Yes| ApplyStart([User runs /opsx:multiagent-apply])
Ready -->|No| Proposal
ApplyStart --> Validate[Validate dispec-driven schema<br/>and distribution complete]
Validate --> TokenWarning[Show token cost warning<br/>N agents = N× cost]
TokenWarning --> Confirm{User<br/>confirms?}
Confirm -->|No| End1([Cancelled])
Confirm -->|Yes| TeamCreate[TeamCreate with change name]
TeamCreate --> TaskCreate[TaskCreate for all tasks<br/>with dependencies]
TaskCreate --> SpawnAgents[Spawn Agent teammates<br/>with worktree isolation]
SpawnAgents --> Monitor[Monitor TaskList<br/>and agent messages]
Monitor --> AllDone{All tasks<br/>complete?}
AllDone -->|No| Monitor
AllDone -->|Yes| Shutdown[Send shutdown_request<br/>to all agents]
Shutdown --> End2([Implementation complete])
Last reviewed commit: a3df4cd |
Collaborator
alfred-openspec
left a comment
alfred-openspec
left a comment
There was a problem hiding this comment.
🔍 Architecture Review — Alfred (OpenSpec maintainer bot)
Thanks for this contribution, @pformoso-deus-ai! This is a well-structured PR with solid architectural thinking. The design doc is particularly well done — it clearly lays out alternatives considered and trade-offs. A few things to address before this can merge:
✅ What looks great
- Natural extension of spec-driven —
dispec-drivenaddsdependencies+distributionon top of the existing 4-artifact chain. The dependency graph (proposal → specs/design parallel → tasks → dependencies → distribution) is correct and well-tested. - Separate skill for multiagent-apply — Right call. These are fundamentally different concerns.
- Shared
MULTIAGENT_APPLY_INSTRUCTIONSconstant in multiagent-apply.ts — Good pattern, avoids skill/command template drift. - Comprehensive tests —
dispec-driven.test.tsvalidates full workflow progression. Parity hashes updated. - Dogfooding — Using dispec-driven schema for its own change artifacts. 🎯
- Not in CORE_WORKFLOWS — Correctly experimental, won't affect new users.
🔴 Should fix before merge
1. Build system changes should be a separate PR (commits 4-5)
The build.js node_modules guard, prepare/prepack/postinstall script changes are fixing a real issue (GitHub git dep installation) but they touch the build pipeline, which is a different review/rollback concern from the feature work. Recommend splitting these into their own PR.
In particular, "postinstall": "node scripts/postinstall.js || true" suppresses all postinstall errors, not just the stale CWD case. If the script has a legitimate failure, this swallows it silently. Consider a more targeted approach.
2. package-lock.json version bump 1.1.1 → 1.2.0
Version should be managed by changesets at release time. Committing the bump in a feature PR will cause merge conflicts with any other in-flight PR.
3. Instruction body duplication in multiagent.ts
The skill instructions and command content are ~120 lines of duplicated text. multiagent-apply.ts already does this right with a shared constant. Extract to const MULTIAGENT_INSTRUCTIONS and reference from both functions — same pattern you used in the apply file.
🟡 Minor suggestions
4. Schema description (line 3 of schema.yaml): Shows proposal → specs → design → tasks → ... but specs and design are actually parallel (both depend only on proposal). Suggest: proposal → (specs + design) → tasks → dependencies → distribution.
5. distribution.md template hardcodes 2 agent cards but the instruction says "Recommend 3-5 agents." Consider making it more generic or adding a note about adding cards for additional agents.
6. Agent count validation: The AskUserQuestion for distribution only handles the "1 agent" case (→ suggest /opsx:propose). No handling for >5 or <2 selections.
Overall
This is a high-quality contribution with genuine architectural thinking. The core schema + workflow design is sound. Address the build system separation and the multiagent.ts body duplication, and this should be good to merge. 🚀
pformoso-deus-ai
added a commit
to pabloformoso/OpenSpec
that referenced
this pull request
Mar 2, 2026
- Extract MULTIAGENT_INSTRUCTIONS shared constant in multiagent.ts to eliminate ~120 lines of duplication between skill and command templates - Fix dispec-driven schema description to reflect parallel artifact flow: proposal → (specs + design) → tasks → dependencies → distribution - Replace hardcoded 2-agent template in distribution.md with a generic repeatable card (recommended 3-5 agents) - Add "2 agents" option and validation for <2 / >5 agent selections - Revert build system changes (build.js guard, package.json scripts, package-lock.json version bump) to be submitted as a separate PR - Update parity test hashes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
3 tasks
- Extract MULTIAGENT_INSTRUCTIONS shared constant in multiagent.ts to eliminate ~120 lines of duplication between skill and command templates - Fix dispec-driven schema description to reflect parallel artifact flow: proposal → (specs + design) → tasks → dependencies → distribution - Replace hardcoded 2-agent template in distribution.md with a generic repeatable card (recommended 3-5 agents) - Add "2 agents" option and validation for <2 / >5 agent selections - Revert build system changes (build.js guard, package.json scripts, package-lock.json version bump) to be submitted as a separate PR - Update parity test hashes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
pformoso-deus-ai
added a commit
to pabloformoso/OpenSpec
that referenced
this pull request
Mar 3, 2026
This reverts commit 9b10d02.
|
I separated the system build to PR 792, and amend this one based on the feedback |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a multi-agent orchestration workflow that enables distributing OpenSpec changes across multiple AI agents for parallel execution.
dispec-drivenschema: Extends the default workflow withdependencies.md(dependency analysis) anddistribution.md(agent work packages) artifacts for planning parallel agent work/opsx:multiagentworkflow: Analyzes a change's tasks and specs, builds a dependency graph, and generates a distribution plan that assigns work packages to agents with clear boundaries/opsx:multiagent-applyworkflow: Orchestrates a Claude Code agent team to implement the distribution plan in parallel, with coordination and conflict resolutionbuild.jsMotivation
Complex changes often have independent task groups that can be worked on simultaneously. This workflow automates the analysis, planning, and execution of parallel agent work — reducing wall-clock time for large changes while maintaining spec coherence.
Related: #435 (Collaboration & Orchestration)
What's included
schemas/dispec-driven/schema.yaml+ 6 templatessrc/core/templates/workflows/multiagent.ts,multiagent-apply.tsinit.ts,profiles.ts,skill-generation.ts,tool-detection.ts,skill-templates.tsdispec-driven.test.ts,multiagent-apply.test.ts, updated parity testsopenspec/changes/add-multiagent-apply-workflow/build.jsTest plan
zsh-installer.test.tsare unrelated — reproducible onupstream/main)dispec-driven.test.tsvalidates schema artifact graph and orderingmultiagent-apply.test.tsvalidates workflow template generation/opsx:multiagenton a change with multiple tasks to verify distribution plan generation/opsx:multiagent-applyto verify agent team orchestration🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
Tests