@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/multi-agent/refs/phases/log-format.md

@@ -0,0 +1,89 @@
+## Log File Format (Detailed)
+
+> **TLDR** — Canonical shape of `agent-log.md`: header block (task id, branch, status), Timeline table (phase by phase), Agent Activity Report (calls + duration per agent), ASCII phase-duration distribution, Review Iterations, Files Changed (`git diff --stat`), Review Consensus, Cost Breakdown, and Test Scenarios. Every pipeline run must produce this file at the global log path.
+
+Create at `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-log.md`:
+
+```markdown
+# {task-id} — {Task Title}
+
+**Branch**: {branch-name}
+**Project**: {project}
+**Started**: {YYYY-MM-DD HH:mm}
+**Finished**: {YYYY-MM-DD HH:mm}
+**Total Duration**: {Xm Ys}
+**Status**: In Progress | Complete | Paused | Failed
+
+## Timeline
+
+| #   | Phase | Agent | Model | Duration | Tokens (in/out) | Status | Detail |
+| --- | ----- | ----- | ----- | -------- | --------------- | ------ | ------ |
+
+> `Tokens (in/out)` is sourced from `phase-tracker.sh tokens` accumulators. Empty cell renders as `—` when no telemetry was captured for that row.
+
+## Agent Activity Report
+
+| Agent         | Calls  | Duration   | Model(s)     |
+| ------------- | ------ | ---------- | ------------ |
+| explore       | 3      | 12s        | haiku        |
+| code-reviewer | 2      | 37s        | opus, sonnet |
+| task (build)  | 4      | 2m 15s     | sonnet       |
+| **TOTAL**     | **10** | **3m 04s** |              |
+
+## Phase Duration Distribution
+
+Phase 0: Init ████░░░░░░░░░░░░ 5s
+Phase 1: Analysis ██████░░░░░░░░░░ 12s
+Phase 2: Planning █████░░░░░░░░░░░ 8s
+Phase 3: Dev ████████████████ 2m 35s
+Phase 4: Review ████████░░░░░░░░ 37s
+Phase 5: Test ██░░░░░░░░░░░░░░ (user wait)
+Phase 6: Commit ██░░░░░░░░░░░░░░ 3s
+Phase 7: Report █░░░░░░░░░░░░░░░ 2s
+
+## Review Iterations
+
+| Iteration | Blocking | Important | Suggestion | Decision |
+| --------- | -------- | --------- | ---------- | -------- |
+
+## Files Changed
+
+(git diff --stat output)
+
+## Review Consensus
+
+## Cost Breakdown
+
+(emit by Phase 7 via `pipeline/scripts/render-agent-log-cost.sh <task-id>`. Renders unconditionally on every run. If the renderer exits 2 (no tracker data + no OTel spans), Phase 7 omits this section without failing the run.)
+
+| Phase | Model | Tokens in | Tokens out | Est. USD |
+| ----- | ----- | --------- | ---------- | -------- |
+
+## Test Scenarios (Jira)
+
+(User perspective: Precondition -> Steps -> Expected result)
+```
+
+### Cost Breakdown — emission contract
+
+Phase 7 MUST attempt to render the Cost Breakdown section as part of the agent-log compose step:
+
+```bash
+COST_BLOCK=$(bash pipeline/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
+  printf '%s\n' "$COST_BLOCK" >> "$AGENT_LOG"
+```
+
+Emission is best-effort — exit 2 (no data) is silently skipped. Never fail the pipeline on a missing cost block. The renderer reuses `cost-table.json` so any `cost-table` price update flows through to both PR-body and agent-log surfaces.
+
+### Tokens telemetry — phase responsibility
+
+Every phase that dispatches a billable LLM agent MUST forward its token totals to the tracker. The minimal contract (already enforced via `smoke-tracker-contract.sh` for Phase 4):
+
+```bash
+pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> <event> \
+  model=<opus|sonnet|haiku|gpt-5.4> tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> tokens \
+  model=<...> tokens_in=$IN tokens_out=$OUT
+```
+
+Setting `LOG_METRIC_FORWARD_TO_TRACKER=1` makes `log-metric.sh` mirror the same `tokens_in`/`tokens_out` into `phase-tracker.sh tokens <phase> <in> <out>` — so JSONL metrics and tracker accumulators stay in sync from a single call site. Without this flag the JSONL line is written but the tracker is not updated; that mode is reserved for one-off analytics events that should not affect the cost block.

package/pipeline/commands/multi-agent/refs/phases/modes.md

@@ -0,0 +1,156 @@
+> **TLDR** — Three orthogonal modifier flags that can combine freely:
+>
+> - `autopilot` → skips confirmations (Plan, Test, Commit, PR prompts), still fails safe on review blockers and build retries.
+> - `--dev` → strips to Init → Dev(Opus self-contained) → Commit → Report. No Phase 1/2/4/5.
+> - `--local` → no worktree, works directly in `$PROJECT_ROOT` on a local branch.
+>
+> Combined: `--dev --local autopilot` = fastest, least-friction path.
+
+## Autopilot Mode
+
+Autopilot mode skips interactive confirmations and runs the pipeline end-to-end autonomously.
+
+**Activation**: Add `autopilot` flag to any pipeline command:
+
+```
+/multi-agent "PROJ-12345" autopilot
+/multi-agent "https://{JIRA_HOST}/browse/PROJ-12345" autopilot
+/multi-agent "https://github.com/.../issues/316" autopilot
+/multi-agent "#316" autopilot
+/multi-agent "LoginView dark mode fix" autopilot
+```
+
+**What changes in autopilot:**
+
+| Phase               | Normal                                                  | Autopilot                                   |
+| ------------------- | ------------------------------------------------------- | ------------------------------------------- |
+| Phase 2 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop — user: approve/abort/free-text edit | **Gate skip** — log the plan, proceed directly to Phase 3 (autopilot contract: zero interaction) |
+| Phase 5 (User Test) | "Want to test?" -> wait                                 | Skip -> proceed directly to Phase 6         |
+| Phase 6 (Commit)    | "Want to commit?" -> wait                               | Auto commit + push                          |
+| Phase 6 (PR)        | "Want to open a PR?" -> wait                            | Auto create PR                              |
+| **Phase 7 (Channels)**  | Multi-select kanal + content menu                   | **STILL PAUSES** — see "Phase 7 autopilot exception" below |
+
+**What NEVER skips (even in autopilot):**
+
+- Phase 4 Review -> if blocking finding, returns to Phase 3, auto fix + rebuild (safety)
+- Kill/Purge confirmations -> destructive operations always ask
+- Build fail -> auto fix + rebuild (max 3 retries). After 3 retries still failing -> pause, ask user
+- **Phase 7 channels dispatch** -> always pauses for multi-select. Rationale: Jira/Confluence are externally visible; silently posting wrong-tone content leaks team-visible artifacts. See below.
+
+**State tracking**: `agent-state.json` gets `"autopilot": true`. Autopilot continues on resume as well.
+
+### Phase 7 autopilot exception
+
+The generic "zero-interaction" contract covers Phases 0-6 only. Phase 7 channels dispatch is the **single exception**:
+
+- ALL modes (`autopilot`, `--dev autopilot`, `--local autopilot`) pause at the channels multi-select menu.
+- Menu pre-ticks from `prefs.global.reportChannels` + `prefs.global.reportContent` — user can accept with one keypress if prefs are stable.
+- **30-minute timeout** — if user does not respond, session ends cleanly:
+  - External delivery aborted (no silent apply — prevents accidental Jira comments / Confluence pages).
+  - Internal capture (`agent-log.md`, telemetry, knowledge base) STILL runs.
+  - State persisted as `{phase: 7, waitingFor: "user-channels-choice", channelsTimeout: true}`.
+  - Resume: `/multi-agent:resume <task-id>` re-opens menu with same inputs.
+- Post-hoc `/multi-agent:channels <task>` never times out — user invoked it explicitly.
+
+Full contract: `refs/phases/phase-7-report.md` (Autopilot pause contract) + `commands/multi-agent/channels.md`.
+
+---
+
+## Dev-Only Mode (`--dev`)
+
+Dev-only mode strips the pipeline to minimum: no deep analysis, no planning phase, no multi-model review, no user test. The **Opus** dev agent directly analyzes the task scope and implements.
+
+**Activation**: Append `--dev` to any pipeline command:
+
+```
+/multi-agent "PROJ-12345" --dev
+/multi-agent "https://{JIRA_HOST}/browse/PROJ-12345" --dev
+/multi-agent "https://github.com/.../issues/316" --dev
+/multi-agent "#316" --dev
+/multi-agent "LoginView dark mode fix" --dev
+/multi-agent "PROJ-12345" --dev autopilot
+```
+
+**Pipeline in dev-only mode:**
+
+```
+Phase 0: Init -> Phase 3: Dev (self-contained) -> Phase 6: Commit -> Phase 7: Report
+```
+
+**What changes in dev-only:**
+
+| Phase               | Normal                                          | Dev-Only                                                                           |
+| ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Phase 0 (Init)      | Full setup                                      | Same — worktree, branch, state                                                     |
+| Phase 1 (Analysis)  | Parallel Explore agents                         | **SKIP**                                                                           |
+| Phase 2 (Planning)  | TaskCreate + architecture review + **Plan Approval Gate** (clarification max 2 rounds + approval loop) | **SKIP** (plan gate not applicable — fast path) |
+| Phase 3 (Dev)       | Follows Phase 2 plan, TDD cycle (Sonnet)        | **Self-contained** (Opus): agent scans relevant files, implements with TDD, builds |
+| Phase 4 (Review)    | Parallel review + Opus triage (Claude: 2-model / Copilot: 3-model) | **SKIP**                                                                           |
+| Phase 5 (User Test) | Ask user to test                                | **SKIP**                                                                           |
+| Phase 6 (Commit)    | Commit + PR                                     | Same — still asks (unless autopilot)                                               |
+| Phase 7 (Report)    | Full report + channels multi-select             | Simplified — no review/analysis sections, BUT **channels menu still pauses** |
+
+**Phase 3 in dev-only mode (self-contained):**
+
+The **Opus** agent receives the task description (from Jira, GitHub issue, or free-text) and:
+
+1. Quickly scans relevant files in the codebase (lightweight, not full Explore)
+2. Implements the change following TDD cycle (test -> code -> build)
+3. Runs build verification (max 3 retries on failure)
+
+No separate task breakdown — the agent handles scope autonomously.
+
+**State tracking**: `agent-state.json` gets `"onlyDevelop": true`. Phases 1, 2, 4, 5 are marked `"skipped"` instead of `"pending"`.
+
+**Combinable with autopilot**: `--dev autopilot` = fastest path. Init -> Dev -> auto-commit -> auto-PR -> Report. Zero user interaction (except build failures after 3 retries).
+
+---
+
+## Local Mode (`--local`)
+
+Local mode skips worktree creation — works directly on a local branch in the project root. Useful for single-task workflows or when worktrees cause issues.
+
+**Activation**: Append `--local` to any pipeline command:
+
+```
+/multi-agent "PROJ-12345" --local
+/multi-agent "#316" --local
+/multi-agent "LoginView dark mode fix" --local --dev
+/multi-agent "PROJ-12345" --local autopilot
+```
+
+**What changes in local mode:**
+
+| Phase          | Normal (worktree)                                | Local                                                          |
+| -------------- | ------------------------------------------------ | -------------------------------------------------------------- |
+| Phase 0 Step 8 | Creates worktree at `.worktrees/{id}/`           | `git checkout -b {branch}` directly in `$PROJECT_ROOT`         |
+| Phase 3        | Works in worktree path                           | Works in `$PROJECT_ROOT`                                       |
+| Phase 5        | WIP commit -> remove worktree -> checkout branch | No worktree removal — code already in place, just build & test |
+| Phase 6        | Commit in worktree, push                         | Commit in project root, push                                   |
+| All paths      | `{worktreePath}` references                      | All paths use `$PROJECT_ROOT` directly                         |
+
+**Phase 0 Step 8 in local mode:**
+
+```bash
+# Instead of creating worktree:
+git -C $PROJECT_ROOT fetch origin
+git -C $PROJECT_ROOT checkout -b {branch} origin/{baseBranch}
+git -C $PROJECT_ROOT config user.name "{identity.name}"
+git -C $PROJECT_ROOT config user.email "{identity.email}"
+```
+
+**Phase 5 in local mode:**
+
+- No worktree to remove — user tests directly in project
+- No WIP commit needed (code is already on the branch in PROJECT_ROOT)
+- "fix" goes back to Phase 3 in same directory
+
+**State tracking**: `agent-state.json` gets `"localMode": true`, `"worktreePath": null`. All path references resolve to `$PROJECT_ROOT`.
+
+**Limitations:**
+
+- Cannot run parallel tasks on same project (no worktree isolation)
+- Uncommitted changes in PROJECT_ROOT may conflict — pipeline warns if dirty
+- Build queue lock still applies for xcodebuild
+
+**Combinable**: `--local --dev autopilot` = simplest path with no worktree overhead.

package/pipeline/commands/multi-agent/refs/phases/operations.md

@@ -0,0 +1,91 @@
+> **TLDR** — Pipeline operational primitives:
+>
+> - **Task IDs** auto-increment from `$HOME/.claude/logs/multi-agent/{project}/.counter` (persistent).
+> - **Kill/Purge/Clear-logs** require explicit user confirm; destructive ops never chain.
+> - **Resume** re-enters at `currentPhase + 1`; always re-runs Phase 7 for knowledge capture.
+> - **3-iteration hard kill**: any retry loop stops after 3 attempts and hands off to the user.
+> - Subagents return JSON (not prose), get only the diff + relevant files, and must reflect before each retry.
+
+## Task ID System
+
+Every task gets an auto-incremented short ID. Counter stored at `$HOME/.claude/logs/multi-agent/{project}/.counter` (persists across sessions).
+
+```
+/multi-agent "PROJ-12345"
+-> Task #1 started — PROJ-12345
+```
+
+---
+
+## Kill Logic
+
+1. Find task by short ID (#2) or Jira ID (PROJ-67890)
+2. Confirm with user: "PROJ-67890 (Task #2) will be deleted: worktree and branch. Logs will be preserved. Are you sure?"
+3. `git worktree remove .worktrees/{jiraId} --force`
+4. `git branch -D {branch-name}`
+5. Remote branch delete ONLY if user explicitly confirms
+6. Logs are preserved in `$HOME/.claude/logs/multi-agent/{project}/{task-id}/` — not deleted with worktree
+7. Log: "Task #2 killed (logs preserved at global path)"
+
+---
+
+## Clear Logs
+
+1. Confirm with user
+2. Scan global log directory: `$HOME/.claude/logs/multi-agent/`
+3. Delete all `agent-log.md` and `agent-state.json` files across all projects
+4. **Do NOT reset counter** (`$HOME/.claude/logs/multi-agent/{project}/.counter`) — prevents ID collision
+5. Confirm count deleted
+
+---
+
+## Purge (Full Reset)
+
+1. First confirm: list what will be deleted
+2. Second confirm: "Type 'purge' to continue"
+3. Remove all worktrees, branches, logs, counter
+4. Do NOT delete remote branches without explicit user approval
+
+---
+
+## Resume Logic
+
+1. Find state file: `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-state.json`
+2. Read `agent-log.md` for previous findings
+3. Resume from `currentPhase + 1`
+4. **Always run Phase 7** on resume completion — ensures knowledge capture even if task was paused mid-pipeline
+5. Log: "Resumed {jiraId} from Phase {N}"
+
+---
+
+## Phase Pipeline
+
+Run phases sequentially. Log every step to `agent-log.md`.
+If any phase fails, mark task as `paused` and stop — user can `resume` later.
+Update `agent-state.json` at EVERY phase transition.
+
+### Pipeline Best Practices
+
+**Subagent return format**: Instruct every subagent to return structured JSON, not prose:
+
+```
+{"status": "complete", "findings": [...], "files_changed": [...], "blocking": false}
+```
+
+This keeps orchestrator context lean and enables programmatic routing.
+
+**Context discipline**: Send subagents ONLY what they need — the diff + relevant files, not the whole repo context. High signal-to-noise ratio > large context.
+
+**Retry reflection**: Before each retry, force reflection: "What failed? What specific change fixes it? Am I repeating the same approach?" — prevents infinite loops on broken strategies.
+
+**Semantic revert**: Track which files each phase produces in `agent-state.json`. If Phase 5 (testing) fails, revert only Phase 4 (implementation) outputs, not Phase 2 (artifacts):
+
+```json
+"phases": {
+  "4": { "status": "done", "files": ["ButtonView.swift", "ButtonConfiguration.swift"] }
+}
+```
+
+**Proactive compaction**: If conversation context exceeds ~60%, dump progress to `agent-log.md` and summarize state before continuing. Don't wait for auto-compaction at 83% — it's lossy.
+
+**3-iteration hard kill**: Any retry loop (build fix, review fix) MUST stop after 3 attempts. On 4th failure -> pause, ask user. No exceptions.