@mmerterden/multi-agent-pipeline 8.6.2 → 10.2.0

package/pipeline/commands/multi-agent/autopilot.md

@@ -1,9 +1,9 @@
 ---
 description: "Launch any task in autopilot mode: skips every confirmation, runs end-to-end autonomously."
-argument-hint: '"task" — issue URL, Jira ID, free-text, or #id (for resume)'
+argument-hint: '"task"  -  issue URL, Jira ID, free-text, or #id (for resume)'
 ---
 
-# multi-agent autopilot — Autonomous Pipeline
+# multi-agent autopilot  -  Autonomous Pipeline
 
 **Input**: $ARGUMENTS
 
@@ -15,7 +15,7 @@ Run the task end-to-end with no confirmations.
 
 | Phase | Normal | Autopilot |
 |-----|--------|-----------|
-| Phase 2 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop — user confirms / cancels / sends free text | **Gate skipped** — log the plan, jump straight to Phase 3 (autopilot contract: zero interaction) |
+| Phase 2 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop  -  user confirms / cancels / sends free text | **Gate skipped**  -  log the plan, jump straight to Phase 3 (autopilot contract: zero interaction) |
 | Phase 5 (Test) | "Want to test?" → wait | Skip → Phase 6 |
 | Phase 6 (Commit) | "Commit?" → wait | Auto-commit + push |
 | Phase 6 (PR) | "Open PR?" → wait | Auto-create PR |
@@ -44,15 +44,15 @@ Run the task end-to-end with no confirmations.
 
 ## Steps
 
-1. **Parse input** — standard multi-agent input formats
-2. **Set the autopilot flag** — write `"autopilot": true` to `agent-state.json`
-3. **Launch the multi-agent pipeline** — every confirmation is skipped
-4. **On error** — after 3 failed retries, pause and ask the user
+1. **Parse input**  -  standard multi-agent input formats
+2. **Set the autopilot flag**  -  write `"autopilot": true` to `agent-state.json`
+3. **Launch the multi-agent pipeline**  -  every confirmation is skipped
+4. **On error**  -  after 3 failed retries, pause and ask the user
 ## Required: Phase Tracker Contract
 
-**The phase tracker is mandatory** — the agent cannot skip it. Full spec: [`refs/tracker-contract.md`](./refs/tracker-contract.md).
+**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`refs/tracker-contract.md`](./refs/tracker-contract.md).
 
-> **Autopilot mode:** user confirmations are skipped. The tracker is still mandatory — autopilot agent calls cannot skip it; skipping breaks `smoke-tracker-contract.sh`.
+> **Autopilot mode:** user confirmations are skipped. The tracker is still mandatory  -  autopilot agent calls cannot skip it; skipping breaks `smoke-tracker-contract.sh`.
 
 Two channels run in parallel at every phase boundary:
 
@@ -62,7 +62,7 @@ Two channels run in parallel at every phase boundary:
 ```bash
 # Phase 0, very first shell call (every CLI):
 bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
-for p in "0:Init" "1:Analysis" "2:Planning" "3:Dev" "4:Review" "5:Test" "6:Commit" "7:Report"; do
+for p in "0:Init" "1:Analysis" "2:Planning" "3:Dev" "4:Review" "6:Commit" "7:Report"; do
   bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
 done
 bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
@@ -74,38 +74,38 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|fai
 bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
 ```
 
-### Visual channel — Claude Code (native TaskList widget, required)
+### Visual channel  -  Claude Code (native TaskList widget, required)
 
-In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack — this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
+In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number — out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN — register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` § "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ```text
-# Phase 0 startup — register one tile per phase (0..N), capture the taskId, persist it:
-for each phase in 0:Init, 1:Analysis, 2:Planning, 3:Dev, 4:Review, 5:Test, 6:Commit, 7:Report:
+# Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
+for each phase in 0:Init, 1:Analysis, 2:Planning, 3:Dev, 4:Review, 6:Commit, 7:Report:
   TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
     -> returns taskId
   bash $HOME/.claude/scripts/phase-tracker.sh meta <N> tasklist_id "<taskId>"
 
-# Phase entry — flip the tile to in_progress alongside the state update:
+# Phase entry  -  flip the tile to in_progress alongside the state update:
 TaskUpdate({ taskId: <saved>, status: "in_progress" })
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress
 
-# Active sub-step inside a phase — update activeForm so the spinner header reflects what's happening now:
+# Active sub-step inside a phase  -  update activeForm so the spinner header reflects what's happening now:
 TaskUpdate({ taskId: <saved>, activeForm: "Editing TopBarView.swift" })
 
-# Phase exit — flip to completed/failed/skipped on both channels:
+# Phase exit  -  flip to completed/failed/skipped on both channels:
 TaskUpdate({ taskId: <saved>, status: "completed" })
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 ```
 
-`autopilot` mode TaskCreates all 8 phases (no phase is skipped).
+`autopilot` mode does NOT TaskCreate phases 5  -  those are not part of the `autopilot` phase set (`0:Init 1:Analysis 2:Planning 3:Dev 4:Review 6:Commit 7:Report`). Only register tiles for the active set.
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number — out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `refs/tracker-contract.md` § "TaskCreate ordering (strict)".
+**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
-### Visual channel — Copilot CLI / Cursor / Windsurf / plain shell
+### Visual channel  -  Copilot CLI / Cursor / Windsurf / plain shell
 
 These CLIs have no TaskList widget. After every state change the agent calls render, which prints a bordered ANSI card as the last tool result so the user sees an updated phase table:
 
@@ -113,4 +113,4 @@ These CLIs have no TaskList widget. After every state change the agent calls ren
 bash $HOME/.claude/scripts/phase-tracker.sh render
 ```
 
-Do NOT call TaskCreate on these CLIs — the tool does not exist and the call fails.
+Do NOT call TaskCreate on these CLIs  -  the tool does not exist and the call fails.

package/pipeline/commands/multi-agent/build-optimize.md

@@ -0,0 +1,77 @@
+---
+description: "Thin wrapper that dispatches to xcode-build-orchestrator on iOS projects. Benchmarks current Xcode build, runs compilation / project / SPM analyzers, produces a recommend-first optimization plan, and re-benchmarks after the developer approves changes."
+argument-hint: "(none - operates on current repo)"
+---
+
+# multi-agent build-optimize - Xcode Build Performance Wrapper
+
+Wraps the vendored `xcode-build-orchestrator` skill (and its 5 specialist analyzers) so iOS users do not have to remember the orchestrator skill name. Recommend-first: no project files are modified without explicit developer approval. All output lands in `.build-benchmark/` in the current repo.
+
+> **Language**: Per `refs/rules.md` Language Application matrix - instruction prose stays English (this file is read as a system prompt). `AskUserQuestion.label` and `header` stay English. `question` and `description` follow `outputLanguage`. The emitted benchmark plan body (the upstream skill controls it) is English by upstream convention.
+
+## When to use
+
+- Slow clean or incremental Xcode builds (long CompileSwiftSources, SwiftEmitModule, Planning Swift module)
+- Build settings audit before a release branch cut
+- SPM resolution time complaints, plugin overhead suspicions
+- Pre-CI optimization pass when build wall-clock starts dominating PR cycle time
+
+## Pre-check
+
+Before dispatch, fail fast on non-iOS repos. Detect iOS context via the standard markers used by Phase 1 stack detection:
+
+| Marker | Action |
+|--------|--------|
+| `*.xcodeproj` or `*.xcworkspace` in cwd | Proceed to dispatch |
+| `Package.swift` only (SwiftPM lib, no Xcode project) | Proceed; orchestrator handles `xcodebuild -package-path` |
+| Android / Backend / Frontend markers only | Surface a short error: "build-optimize is iOS-only. Detected: <stack>. Use the platform-appropriate perf skill (android-performance / web-performance / etc.) instead." Exit. |
+| No recognizable stack | Surface "no iOS project found in cwd" and exit. |
+
+## Steps
+
+1. **Detect stack** (as above). On non-iOS, exit with the explanatory message.
+
+2. **Identify project + scheme** for the orchestrator:
+   - If both `.xcworkspace` and `.xcodeproj` exist, prefer `.xcodeproj` unless the workspace contains sub-projects required for the build (upstream orchestrator's own rule).
+   - If multiple schemes, AskUserQuestion to pick one (single-select, options derived from `xcodebuild -list -json`).
+   - Configuration default: `Debug` (developers spend most wait time here). Ask to override only if user input suggests Release-focused work.
+   - Destination default: a generic simulator (`platform=iOS Simulator,name=iPhone 16`) unless the project pins a different one.
+
+3. **Dispatch** to `xcode-build-orchestrator` via the Skill tool:
+   ```
+   Skill(skill="xcode-build-orchestrator", args="")
+   ```
+   The orchestrator's Phase 1 (Analyze) runs `xcode-build-benchmark`, the three specialist analyzers, and writes `.build-benchmark/optimization-plan.md`. No project files are modified during Phase 1.
+
+4. **Hand off** the rendered plan path to the user. The user reviews `.build-benchmark/optimization-plan.md`, checks the approval boxes for items they want, and triggers Phase 2 manually (or re-invokes this wrapper with the plan already produced).
+
+5. **Phase 2 (apply + verify)** is initiated by the user. The wrapper does not auto-execute Phase 2 because the upstream contract requires explicit approval via the checkboxes in the plan file. When the user signals "implement the approved items", the wrapper dispatches to `xcode-build-fixer`:
+   ```
+   Skill(skill="xcode-build-fixer", args="")
+   ```
+   The fixer applies only the approved changes and re-benchmarks for wall-clock delta verification.
+
+## Side-effect contract
+
+- Phase 1 (Analyze): writes only inside `.build-benchmark/` in the cwd. No project file edits.
+- Phase 2 (Fix): edits build settings, source files, packages, or scripts the developer approved. Re-benchmarks to verify.
+- Never opens a worktree. Never creates a branch. Never commits. Never opens a PR. Build optimization wins land in the user's normal commit workflow.
+
+## Reusable refs
+
+| Path | Reason |
+|------|--------|
+| `pipeline/skills/shared/external/xcode-build-orchestrator/SKILL.md` | The orchestrator this wrapper dispatches to |
+| `pipeline/skills/shared/external/xcode-build-benchmark/SKILL.md` | Baseline timing |
+| `pipeline/skills/shared/external/xcode-compilation-analyzer/SKILL.md` | Swift compile hotspots |
+| `pipeline/skills/shared/external/xcode-project-analyzer/SKILL.md` | Build settings / script phases / parallelism |
+| `pipeline/skills/shared/external/spm-build-analysis/SKILL.md` | SPM graph + plugins |
+| `pipeline/skills/shared/external/xcode-build-fixer/SKILL.md` | Apply approved fixes + re-benchmark |
+| `pipeline/skills/shared/external/NOTICE-xcode-build-skills.md` | MIT attribution + upstream pin |
+
+## Notes
+
+- The upstream `OPTIMIZATION-CHECKS.md` (in the AvdLee repo) has the full 40+ check catalog. Surface a link from the optimization plan if the user wants to see what was checked vs skipped.
+- Wall-clock build time (not parallel CPU time) is the primary success metric. The orchestrator labels findings as "build time improvements" or "parallel efficiency improvements" accordingly.
+- If `COMPILATION_CACHE_ENABLE_CACHING = YES`, the benchmark auto-includes cached-clean runs (realistic warm-cache developer experience).
+- Variance flag: when a benchmark's min-max spread exceeds 20% of the median, the orchestrator marks the run high-variance and recommends 5+ repetitions before drawing conclusions.