Openspec Multiagent

Plan and distribute a change across multiple AI agents for parallel execution.

I'll create a change with artifacts:

• proposal.md (what & why)
• specs/ (detailed specifications)
• design.md (how, with parallelism considerations)
• tasks.md (implementation steps with file ownership)
• dependencies.md (task dependency analysis)
• distribution.md (agent assignment plan)

When ready to implement, run /opsx-multiagent-apply

Input: The argument after /opsx-multiagent 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 question 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

   openspec new change "<name>" --schema dispec-driven
   

   This creates a scaffolded change at openspec/changes/<name>/ with .openspec.yaml using the dispec-driven schema.

3. Get the artifact build order

   openspec status --change "<name>" --json
   

   Parse the JSON to get:

   • applyRequires: array of artifact IDs needed before implementation (e.g., ["distribution"])
   • artifacts: list of all artifacts with their status and dependencies

4. Create artifacts in sequence until apply-ready

   Use your internal memory or task-tracking capabilities to log tasks and continuously update their statuses to monitor 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:

     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
     • outputPath: Where 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
   • Apply context and rules as constraints - but do NOT copy them into the file
   • Show brief progress: "Created "

   b. For the distribution artifact: If a detailed multi-agent plan exists with 3 recommended agents, proceed without asking. For 1-2 agents with sequential dependencies, propose using /opsx-apply. Only if the task is highly complex (suggesting >4 agents) use the question tool to ask:

   "How many agents do you want to distribute tasks across? (Recommended: 3-5)" With options:

   • "3 agents (Recommended)" - Good balance of parallelism and coordination
   • "4 agents" - More parallelism, moderate coordination
   • "5+ agents" - Maximum parallelism, requires higher coordination overhead

   If the user selects fewer than 3 for a complex task, suggest /opsx-multiagent-apply.

   c. 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

   d. If an artifact requires user input (unclear context):

   • Use question tool to clarify
   • Then continue with creation

5. Show final status

   openspec status --change "<name>"
   

Output

After completing all artifacts, summarize:

• Change name and location
• List of artifacts created with brief descriptions
• Agent assignment summary: Which tasks go to which agent
• What's ready: "All artifacts created! Ready for multi-agent implementation."
• Prompt: "If the task is small or requires sequential execution, run /opsx-apply for a direct implementation; otherwise, run /opsx-multiagent-apply to orchestrate a team of agents for parallel execution."

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