opsx-team-apply

name	opsx-team-apply
description	OpenSpec multi-agent parallel implementation — read tasks.md, analyze dependencies, auto-create team for parallel execution. Use when implementing OpenSpec changes with parallel agents. Triggers on "team apply", "parallel apply", "opsx team", "opsx:team-apply".
version	1.0.0
scope	public

OpenSpec Team Apply

Read the OpenSpec change's tasks.md, analyze file dependencies between task groups, automatically create a team and assign independent task groups to parallel agents for execution.

---

Integrations

upstream:
  - skill: opsx:ff / opsx:continue
    receives: Completed change artifacts (proposal + specs + design + tasks)

downstream:
  - skill: opsx:verify
    produces: Implementation-complete change, ready for verification

---

Out of Scope

• Artifact creation - Use opsx:ff or opsx:continue
• Changes with a single task group - Just use opsx:apply directly
• Cross-change parallelism - Only handles one change at a time

---

When to Use

• Change has 2+ task groups
• Task groups have opportunities for parallel execution
• Want to speed up the implementation process

---

Input

/opsx:team-apply <change-name>

If no change name is specified, use openspec list --json to list available changes.

---

Workflow

1. DETECT     → Detect project type, determine verify commands
2. PARSE      → Read tasks.md + design.md
3. ANALYZE    → Build file conflict matrix
4. PLAN       → Assign execution phases
5. CONFIRM    → User confirms plan
6. EXECUTE    → Create team, dispatch work by phase
7. MONITOR    → Wait for completion, advance phases
8. VERIFY     → Basic verification + suggest opsx:verify

Phase 0: DETECT

Detect project type, determine PROJECT_CHECK, PROJECT_LINT, PROJECT_TEST:

Detection File	Check	Lint	Test
pubspec.yaml	flutter analyze	(same as above)	flutter test
Cargo.toml	cargo check	cargo clippy -- -D warnings	cargo test
package.json	npx tsc --noEmit	npm run lint	npm test
go.mod	go build ./...	golangci-lint run	go test ./...
pyproject.toml	python -m py_compile	ruff check .	pytest

If detection fails, ask the user.

Phase 1: PARSE

Read the change's artifacts:

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

Confirm isComplete: true (all artifacts are ready).

Then read:

• openspec/changes/<name>/tasks.md — Parse task groups
• openspec/changes/<name>/design.md — Parse Impact section to get file mappings
• openspec/changes/<name>/proposal.md — context for agents

Task group parsing rules:

• ## N. <Group Name> → a task group
• - [ ] N.M <description> → a task within the group
• - [x] N.M <description> → completed task (skip)
• Entire group already completed → skip that group

Task classification:

• [auto] (default) — code tasks an agent can handle
• [manual] — requires external environment (testnet deploy, hardware benchmark, manual QA). Keywords: "deploy to", "on testnet", "benchmark on", "connect real wallet". Not assigned to an agent, marked "skip (manual)" in the plan.

Spec scenarios: Read all spec files from openspec/changes/<name>/specs/, match task group-relevant requirements + scenarios, and provide them to the agent prompt.

Phase 2: ANALYZE

Build file conflict matrix:

1. Extract file → [groups] mapping from design.md Impact section (if not granular enough, infer from task descriptions)
2. Build conflict map: which groups touch the same files
3. Find independent sets (groups with no file conflicts can run in parallel)

Phase 3: PLAN

Use graph coloring to assign execution phases. Rules:

• No file conflicts within the same phase
• Smaller groups first (finish faster → unlock more)
• Data dependencies (DB migrations etc.) must be scheduled first
• All conflicts → degrade to fully sequential, suggest /opsx:apply
• [manual] tasks marked as "skip", not scheduled into phases

Phase 4: CONFIRM

Use AskUserQuestion to display phase table (groups, files, agents count, skipped manual tasks) + three options: Execute / Sequential / Adjust.

Phase 5: EXECUTE

1. Create Team

   TeamCreate: team_name = "opsx-<change-name>"
   

2. Create Tasks from task groups

   • Each task group → one Team Task
   • Set blockedBy relationships (Phase 2 blocked by Phase 1)

3. For each phase, spawn agents:

   Prompt template each agent receives:

   You are implementing task group "<group-name>" for the OpenSpec change "<change-name>".
   
   ## Context
   <contents of proposal.md>
   
   ## Design Decisions
   <relevant decisions from design.md>
   
   ## Your Tasks
   <task group's tasks from tasks.md — only [auto] tasks>
   
   ## Spec Requirements & Scenarios
   <matched spec requirements + ALL scenarios for this group>
   IMPORTANT: Implement every scenario listed. Each scenario is a testable condition.
   
   ## Instructions
   1. Read the current source files before making changes
   2. Implement each task in order
   3. After each task, run `<PROJECT_CHECK>` to verify compilation
   4. After all tasks, update or create tests for your changes:
      - New hooks/utilities: add unit tests
      - Modified components: update existing tests
      - Run `<PROJECT_TEST>` on affected test files to verify
   5. Update tasks.md checkboxes: mark your completed tasks as `[x]` in
      `openspec/changes/<change-name>/tasks.md`
   6. When all tasks are done, mark your team task as completed via TaskUpdate
   7. Send a message to lead with a summary of changes made
   
   ## Important
   - Only modify files listed in your task group
   - Do NOT modify files outside your scope
   - If you encounter a blocker, message the lead instead of working around it
   - Verify each spec scenario is covered — don't just implement the requirement title
   

   Agent config: subagent_type: "general-purpose", mode: "bypassPermissions", team_name: "opsx-<change-name>" Model: sonnet (default), opus (complex architectural changes)

Phase 6: MONITOR

Lead agent loop:

1. Wait for all agents in the phase to complete (via messages + TaskList check)
2. Phase gate: After all agents complete, lead runs:

   <PROJECT_CHECK>   # Always run
   <PROJECT_LINT>    # If available
   

3. If there are errors → lead fixes directly (small issues) or notifies the relevant agent to fix
4. Phase gate passes → unblock next phase's tasks → spawn next phase's agents
5. Repeat until all phases complete

Phase gate prevents bad code from spreading. Use TaskList to check progress (no need to actively ping). If a downstream group's dependencies are partially satisfied by some agents, it can start early (but related check/lint must still pass first).

Phase 7: VERIFY

After all phases complete, run the commands determined in the DETECT phase:

<PROJECT_CHECK>
<PROJECT_LINT>   # If available
<PROJECT_TEST>   # If available

If passing:

• Shutdown all agents
• TeamDelete
• Update tasks.md (mark all tasks as [x])
• Suggest: /opsx:verify for full verification

If failing:

• Identify failure cause
• Spawn a fix agent or fix directly in lead (small issues)
• Re-verify

---

Edge Cases

Situation	Handling
Only 1 task group	Suggest using /opsx:apply directly
All groups have file conflicts	Degrade to fully sequential, suggest /opsx:apply
Agent reports blocker	Lead intervenes, decides whether to adjust plan
Check error after phase gate	Stop, fix, then continue
Agent modified files outside scope	Caught in verify phase, require correction
Verification group (pure verification tasks)	Don't spawn agent, lead executes directly
Some tasks already completed ([x])	Skip completed tasks, only assign incomplete ones
Task marked as [manual]	Skip, don't assign agent, mark "skip (manual)" in plan
Agent didn't update tests	Phase gate catches test failures, lead requests fix or fills in
Agent didn't update tasks.md checkboxes	Lead updates in VERIFY phase (but prompt already asks agent to do it)

---

Verification

• All [auto] task group tasks are checked off
• [manual] tasks are marked as skipped in the plan
• <PROJECT_CHECK> passes
• <PROJECT_LINT> zero new warnings (pre-existing acceptable)
• <PROJECT_TEST> no new failures (pre-existing acceptable)
• tasks.md checkboxes updated by agents or lead
• New hooks/utilities have corresponding tests
• Spec scenarios covered one by one (confirmed in verify phase)

---

Safety and Escalation

Situation	Action
Agent wants to modify files outside scope	Block, notify lead
Check error cannot be auto-fixed	Pause, ask user to intervene
Merge conflict between agents	Pause phase, resolve manually
User wants to cancel	Shutdown all agents, TeamDelete