feat(assistant): add dev-orchestrator skill for parallel task management

[Menendez2004]

Description

Adds the dev-orchestrator skill: detects when a single prompt bundles multiple independent dev tasks and dispatches each as an isolated agent, classifying dependencies so independent tasks fan out in parallel and dependent ones run in order. Includes an opt-in worktree mode that provisions an integration branch off the protected base, runs each task in its own git worktree, validates the combined result, and hands off to agent-pr-creator for the protected-base PR. Also resolves issue-tracker tickets (Linear, Jira, GitHub Issues, Notion) via MCP.

Type of Change

• New Feature (dev-orchestrator skill)
• Bug Fix (worktree/merge script hardening)
• Documentation (worktree-mode reference updates)

Workflow schemas

End-to-end orchestration flow

flowchart TD
  A(["Start<br/>user prompt"]) --> B{"Phase 0?<br/>ticket ref or --ticket"}
  B -->|yes| B1["MCP resolve<br/>prepend envelope"]
  B -->|no| C
  B1 --> C["Phase 1<br/>detect · classify · route"]
  C --> D{"One task<br/>after merge?"}
  D -->|yes| E["Main session<br/>skip 2–4"]
  D -->|2+ tasks| F["Phase 2<br/>Layout A/B/C confirm"]
  F --> G{"User<br/>confirmed?"}
  G -->|edit plan| F
  G -->|go-ahead| H["Phase 3<br/>dispatch agents (M1·M2·M3)"]
  H --> I["Phase 4<br/>Orchestrator Results"]
  I --> J{"Mode 3 +<br/>merge PR path?"}
  J -->|yes| K["Phase 4.5<br/>validate · push · PR"]
  J -->|no| L{"QA gate"}
  K --> L
  L -->|all failed| M["Retry — no QA"]
  L -->|doc-only| N["Skip QA<br/>no testable artifacts"]
  L -->|code-touching ok| Q["Phase 5<br/>qa-orchestrator"]
  Q --> R["Verdict + issue URLs"]

Loading

Phase 1 — pairwise dependency classification

flowchart TD
  P(["Tasks A and B"]) --> Q{"B breaks<br/>without A?"}
  Q -->|yes| R["Hard-chained<br/>→ merge into one task"]
  Q -->|no| S{"Better if<br/>A runs before B?"}
  S -->|yes| T["Soft-sequenced<br/>→ waves"]
  S -->|no| U["Independent<br/>→ single parallel wave"]

Loading

Worktree mode — merge & PR handoff (Mode 3)

flowchart TD
  A["setup-integration-branch.sh<br/>integration branch off protected base"] --> B["setup-worktree.sh<br/>one worktree per task"]
  B --> C["dispatch isolated agent per worktree"]
  C --> D["verify commit<br/>SHA + diff"]
  D --> E["merge-worktree.sh --no-push<br/>merge in DEDICATED integration worktree"]
  E --> F{"merge clean?"}
  F -->|conflict| G["contained in integration worktree<br/>primary checkout untouched"]
  F -->|clean| H{"more waves?"}
  H -->|yes| B
  H -->|no| I["Phase 4.5<br/>validate $INTEGRATION_WORKTREE"]
  I --> J["push integration branch"]
  J --> K["agent-pr-creator<br/>PR: integration → base"]

Loading

What's included

• SKILL.md — five-phase orchestration contract (ticket resolution → task detection → confirmation → dispatch → consolidation → QA).
• References — dispatch-contract.md, worktree-mode.md, ticket-resolution.md, workflow.md, test-plan-obligation.md, dispatch-patterns.md.
• Scripts — setup-integration-branch.sh, setup-worktree.sh, merge-worktree.sh, validate-worktree.sh.
• Distribution — marketplace.json + generated .claude-plugin/ artifacts.

Fixes in this revision (merge/worktree safety)

The previous CI failure (shellcheck SC2015) is resolved, along with several correctness issues found while reviewing the merge and worktree-creation paths:

• CI fix (SC2015): replaced the A && B || true idiom in setup-integration-branch.sh and setup-worktree.sh with explicit if ensure_local_ref …; then …; fi blocks.
• Merge no longer touches the user's checkout: merge-worktree.sh now merges inside a dedicated integration worktree instead of checking the base branch out in the primary worktree. A clean merge leaves the user's HEAD untouched; a conflict is contained in that worktree (not stranded in the user's checkout). The script emits INTEGRATION_WORKTREE=<path> for downstream validate/push.
• Merge runs non-interactively: added --no-edit so --no-ff cannot hang on the commit-message editor.
• Safe branch cleanup: per-task branches are deleted only after an explicit merge-base --is-ancestor check against the base — no blind branch -D that could drop unmerged work.
• Parallel-wave collisions fixed: setup-worktree.sh adds pid + RANDOM entropy to branch names and worktree paths so same-second, same-slug dispatches in a wave no longer collide.
• Validation no longer hangs: validate-worktree.sh sets CI=true for npm test so watch-mode runners (vitest/CRA) run once and exit.
• Docs aligned: worktree-mode.md Phase 4.5 now validates/pushes/PR-creates against $INTEGRATION_WORKTREE.

Verification

• bash -n clean on all four scripts.
• Functional smoke tests: clean merge keeps primary on its original branch; conflict stays contained in the integration worktree; merged feature branch is deleted; base resolution still works for master-only repos; parallel provisions yield unique branches/paths even within the same second.
• ruby scripts/skills_audit.rb → PASS (43/43 skills).
• .claude-plugin/ artifacts regenerated and identical to source.

Breaking Changes

• No

Screenshots / Videos

N/A — no UI changes.