@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/core/multi-agent/SKILL.md

@@ -0,0 +1,944 @@
+---
+name: multi-agent
+language: tr
+description: "Task orchestrator: runs the full pipeline from a Jira ID or GitHub Issue URL — analysis → plan → TDD development → parallel review (Opus + Sonnet on Claude Code, GPT + Opus + Sonnet on Copilot CLI) → commit → log. Every step is written to agent-log.md."
+user-invocable: true
+argument-hint: '"PROJ-12345" "feature/PROJ-12345-flight-filter" | "https://github.com/.../issues/316" | status | log #1 | resume #1 | kill #1 | clear-logs | purge | review'
+---
+
+Read and follow the instructions in this file's INSTRUCTION.md section below.
+
+---
+
+# Multi-Agent Task Orchestrator
+
+## Project Detection
+
+Detect project from cwd FIRST, then validate input format:
+
+| cwd contains | Project | Accepted Input | Rejected Input |
+|--------------|---------|----------------|----------------|
+| `/my-ios-app` | my-app | `"PROJ-XXX" "branch"` | GitHub Issue URL |
+| `/my-figma-app` | figma | `"https://github.com/.../issues/N"` | Jira ID + branch |
+| Other | generic | Both formats | — |
+
+If user gives wrong format for the project, warn:
+- my-ios-app + GitHub URL → "Bu proje Jira ID + branch bekliyor. Ornek: multi-agent \"PROJ-12345\" \"feature/PROJ-12345-desc\""
+- my-figma-app + Jira → "Bu proje GitHub Issue URL bekliyor. Ornek: multi-agent \"https://github.com/my-org/my-figma-app/issues/316\""
+
+## Input Parsing
+
+Classify user input into one of 5 types (matches the colon-form `multi-agent.md` contract; cross-CLI parity is enforced by `smoke-cross-cli-behavior.sh`):
+
+| # | Pattern | Type | Action |
+|---|---------|------|--------|
+| 1 | `#N` or bare `316` | github-issue-number | Fetch via gh after project selection |
+| 2 | `https://github.com/.../issues/N` | github-issue-url | Extract org/repo/N, fetch via gh |
+| 3 | `https://{JIRA_HOST}/browse/{JIRA_KEY}-XXXXX` | jira-url | Extract ID, fetch via Jira API |
+| 4 | `{JIRA_KEY}-XXXXX` (bare) | jira-id | Fetch via Jira API |
+| 5 | Anything else | free-text | No external fetch |
+
+All types enter the same Phase 0 flow.
+
+## Routing
+
+Parse the user's input and route to the correct sub-command:
+
+| Input Pattern | Action |
+|---------------|--------|
+| `"PROJ-XXX" "branch"` | **my-app only** — Jira ID + branch name → auto-assigned incremental ID |
+| `"https://github.com/..."` | **figma only** — parse issue, extract Jira from title/body, auto-create branch |
+| `status` | Show all tasks with ID, phase, status |
+| `log [id]` | Show agent-log.md for task (latest if no id) |
+| `resume [id]` | Resume paused/failed task from last successful phase |
+| `kill [id]` | Stop task, delete worktree + branch + logs. Asks confirm first |
+| `clear-logs` | Delete all agent-log.md and agent-state.json files, keep worktrees/branches |
+| `purge` | Nuclear cleanup — delete ALL worktrees, branches, logs, state, counter. Full reset |
+| `review` | Skip phases 0-3, review current diff only |
+| `autopilot` flag | Add to any pipeline command — skip user confirmations except destructive ops |
+| No args / `help` | Show usage guide (project-specific) |
+
+---
+
+## 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" "feature/PROJ-12345-desc" autopilot
+multi-agent "https://github.com/.../issues/316" autopilot
+multi-agent "LoginView dark mode fix" autopilot
+```
+
+**What changes in autopilot:**
+
+| Phase | Normal | Autopilot |
+|-------|--------|-----------|
+| Phase 2 (Plan Approval Gate) | Clarification (max 2 tur) + approval loop — kullanıcı `onayla`/`iptal`/serbest metin | **Gate skip** — plan'ı logla, direkt Phase 3'e geç (autopilot sözleşmesi: zero interaction) |
+| Phase 5 (User Test) | "Test etmek ister misin?" → bekle | Skip → direkt Phase 6'ya geç |
+| Phase 6 (Commit) | "Commit atmak ister misin?" → bekle | Otomatik commit + push |
+| Phase 6 (PR) | "PR açmak ister misin?" → bekle | Otomatik PR oluştur |
+
+**What NEVER skips (even in autopilot):**
+- Phase 4 Review → blocking bulgu varsa Phase 3'e döner, fix + rebuild otomatik (güvenlik)
+- Kill/Purge confirmations → destructive operasyonlar her zaman sorar
+- Build fail → fix + rebuild otomatik (max 3 retry). 3 retry sonra hala fail → pause, kullanıcıya sor
+
+**State tracking**: `agent-state.json`'a `"autopilot": true` eklenir. Resume'da da autopilot devam eder.
+
+---
+
+## Task ID System
+
+Every task gets an **auto-incremented short ID** for easy reference:
+
+```
+multi-agent "PROJ-12345" "feature/PROJ-12345-flight-filter"
+→ ✅ Task #1 started — PROJ-12345
+
+multi-agent "PROJ-67890" "feature/PROJ-67890-booking-flow"
+→ ✅ Task #2 started — PROJ-67890
+```
+
+ID is stored in `agent-state.json` and shown in `multi-agent status`:
+
+```
+🤖 Multi-Agent Active Tasks
+
+| ID | Jira | Branch | Phase | Status |
+|----|------|--------|-------|--------|
+| #1 | PROJ-12345 | feature/PROJ-12345-... | 3/7 Dev | ⚡ in progress |
+| #2 | PROJ-67890 | feature/PROJ-67890-... | 1/7 Analysis | 📊 scanning |
+```
+
+ID counter stored at `.worktrees/.multi-agent-counter` (persists across sessions).
+
+---
+
+## Kill Logic
+
+When `multi-agent kill [id]` is called:
+
+1. **Find task**: Look up task by short ID (e.g. `#2`) or Jira ID (e.g. `PROJ-67890`)
+2. **Confirm**: Ask user: `"PROJ-67890 (Task #2) silinecek: worktree, branch, loglar. Emin misin?"`
+3. **Stop agents**: Kill any running background agents for this task
+4. **Delete worktree**: `git worktree remove .worktrees/PROJ-{id} --force`
+5. **Delete branch**: `git branch -D {branch-name}`
+6. **Delete remote branch**: ONLY if user explicitly confirms: "Remote branch'i de silmek istiyor musun?"
+7. **Archive log** (optional): Move `agent-log.md` to `.worktrees/.archive/PROJ-{id}/` before delete
+   - Or delete completely if user says "tamamen sil"
+8. **Update counter**: Mark ID as available (or just skip — IDs are cheap)
+9. **Confirm**: `❌ Task #2 (PROJ-67890) killed — worktree, branch, logs deleted`
+
+---
+
+## Clear Logs
+
+When `multi-agent clear-logs` is called:
+
+1. **Confirm**: `"Tüm task logları silinecek (agent-log.md + agent-state.json). Worktree'ler ve branch'ler kalacak. Emin misin?"`
+2. **Scan**: Find all `.worktrees/PROJ-*/agent-log.md` and `agent-state.json` files
+3. **Delete**: Remove log and state files from each worktree
+4. **Do NOT reset counter**: `.worktrees/.multi-agent-counter` stays intact — prevents ID collision with existing worktrees
+5. **Confirm**:
+   ```
+   🧹 Logs cleared
+   Deleted: {N} agent-log.md + {N} agent-state.json
+   Worktrees & branches: untouched
+   ```
+
+---
+
+## Purge (Full Reset)
+
+When `multi-agent purge` is called:
+
+1. **Confirm**: `"⚠️ DIKKAT: Tüm worktree'ler, branch'ler, loglar ve state silinecek. Bu geri alınamaz. Emin misin?"`
+2. **List**: Show what will be deleted:
+   ```
+   Silinecekler:
+   - .worktrees/PROJ-12345/ (branch: feature/PROJ-12345-...)
+   - .worktrees/PROJ-67890/ (branch: feature/PROJ-67890-...)
+   - .worktrees/.multi-agent-counter
+   Toplam: 2 worktree, 2 branch, 2 log
+   ```
+3. **Second confirm**: `"Devam etmek için 'purge' yaz:"`
+4. **Execute** (for each worktree):
+   - `git worktree remove .worktrees/PROJ-{id} --force`
+   - `git branch -D {branch-name}`
+   - Remote branch delete ONLY if user explicitly confirms: "Remote branch'leri de silmek istiyor musun?"
+5. **Cleanup**: Remove `.worktrees/.multi-agent-counter` and `.worktrees/.archive/`
+6. **Confirm**:
+   ```
+   🔥 Purge complete
+   Deleted: {N} worktrees, {N} branches, {N} logs
+   multi-agent is reset to clean state
+   ```
+
+---
+
+## Resume Logic
+
+When `multi-agent resume [id]` is called:
+
+1. **Find state file**: Scan `.worktrees/PROJ-{id}/agent-state.json`
+   - If no `id` given, find the most recent worktree with `status != "done"`
+2. **Read state**: Parse `agent-state.json` → determine last completed phase
+3. **Restore context**: Read `agent-log.md` for previous findings:
+   - Phase 1 analysis findings → reuse in Phase 2+
+   - Phase 2 plan/todos → reuse in Phase 3+
+   - Phase 3 code changes → already on disk in worktree
+   - Phase 4 review findings → reuse if re-reviewing
+4. **Resume from next phase**: Skip completed phases, start from `currentPhase + 1`
+5. **Log**: `🔄 Resumed PROJ-{id} from Phase {N}`
+
+This works across sessions because:
+- `agent-state.json` → persists phase progress on disk
+- `agent-log.md` → persists findings, analysis, decisions on disk
+- Git worktree → persists code changes on disk
+- All state is file-based, nothing depends on in-memory session
+
+---
+
+## Agent dispatch — per-persona model routing
+
+Every agent persona under `pipeline/agents/*.md` declares a `preferredModel` frontmatter field. The orchestrator MUST honor it on every dispatch, on both Claude Code and Copilot CLI — cross-CLI parity is enforced by `smoke-cross-cli-behavior.sh`.
+
+| Persona | `preferredModel` | Rationale (condensed) |
+|---|---|---|
+| `explorer` | `sonnet` | Scan/pattern work, cost-efficient without quality loss |
+| `code-reviewer` | `opus` | Tier 1 reviewer; Phase 4 overrides Reviewer 3 to `sonnet` |
+| `security-auditor` | `opus` | False-negative cost is high; opus reduces miss rate |
+| `ios-architect` | `opus` | Deep module/protocol/migration reasoning |
+| `android-architect` | `opus` | Gradle modules, Compose stability, Hilt graphs |
+| `backend-architect` | `opus` | API + migration + scaling reasoning |
+
+**Dispatch contract (pseudo-code):**
+
+```bash
+persona_file="$HOME/.claude/agents/${persona}.md"
+pref_model="$(awk '/^preferredModel:/ {print $2; exit}' "$persona_file")"
+override="${PHASE_MODEL_OVERRIDE:-}"   # set by orchestrator per-dispatch (e.g. Phase 4 Reviewer 3 → sonnet)
+resolved_model="${override:-${pref_model:-opus}}"
+
+export CLAUDE_CODE_SUBAGENT_MODEL="$resolved_model"
+# Claude Code honors the env var; Copilot CLI reads the same env + passes as --model flag.
+```
+
+**Precedence:** per-dispatch `PHASE_MODEL_OVERRIDE` > persona `preferredModel` > global default (`opus`).
+
+**Observability:** emit `phase.agent.dispatch` OTel span with `{persona, resolved_model, override_source}` attributes when `MULTI_AGENT_OTEL_SPANS=1` (see `phase-tracker.sh`).
+
+---
+
+## Dynamic skill loading — trigger-based injection (v7.0.0+, opt-in)
+
+**Gated by `prefs.global.dynamicSkillLoading` (default `false`).** When enabled, the orchestrator moves from eager-loading all 192 skills on every session to injecting only the skills that match the current task context. The match signal comes from three sources in descending weight:
+
+1. `trigger-paths` globs in SKILL.md frontmatter vs. Phase 1 touched files (heaviest, +30 max)
+2. `trigger-keywords` in SKILL.md frontmatter vs. task text (mid, +30 max)
+3. `description` keyword overlap with task text (lightest fallback, +15 max)
+4. Platform match vs. Phase 1 detected stack (+10)
+
+**Runtime contract:**
+
+```bash
+# After Phase 1 produces analysis.json with {stack.primary, touchedAreas[].path}
+task_text="$(jq -r '.summary' analysis.json)"
+touched=$(jq -r '.touchedAreas | map(.path) | join(",")' analysis.json)
+stack=$(jq -r '.stack.primary' analysis.json)
+
+matched_skills=$(node pipeline/scripts/match-skills.mjs \
+  "$task_text" \
+  --touched-files "$touched" \
+  --stack "$stack" \
+  --limit 12 \
+  --json)
+
+# Inject only matched skills[] into subagent prompts for Phase 2–4.
+# Skills not in the matched list are not loaded — saves ~10K–30K tokens
+# per subagent dispatch on small tasks.
+```
+
+**Fallback:** if `.skills-index.json` is missing (e.g. fresh checkout before `build-skills-index.mjs` runs), the orchestrator falls back to eager-load exactly as pre-v7.0 — dynamic loading never blocks the happy path.
+
+**--index-only installs:** `node install.js --index-only` writes only the index, not the 192 SKILL.md payloads. Intended for:
+- CI pipelines that fetch skill bodies on demand
+- Disk-constrained users who accept the dynamic-load contract
+
+When `dynamicSkillLoading=true` AND the target install is index-only, subagent prompts must include the matched skills' bodies inline (read from the pipeline source or a cached copy). The orchestrator resolves this by reading `{PIPELINE_SRC}/pipeline/skills/{relativePath}` — the pipeline source repo is always the source of truth; the install dir is a cache.
+
+**Telemetry:** when `MULTI_AGENT_OTEL_SPANS=1`, emit `phase.skills.match` span with `{taskId, matchedCount, topN=[name,score]}` so post-hoc analysis can tune trigger-keywords / trigger-paths in SKILL.md frontmatter.
+
+---
+
+## 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.
+
+### Canonical phase labels (TaskCreate + banner)
+
+Every user-facing phase title — TaskCreate cards, `phase-banner.sh` headers, and any status line rendered to the terminal — MUST come from this table. Labels are always English (`promptLanguage` is locked to `en`):
+
+| # | Label                  |
+|---|------------------------|
+| 0 | Phase 0: Init          |
+| 1 | Phase 1: Analysis      |
+| 2 | Phase 2: Planning      |
+| 3 | Phase 3: Dev           |
+| 4 | Phase 4: Review        |
+| 5 | Phase 5: Test          |
+| 6 | Phase 6: Commit & PR   |
+| 7 | Phase 7: Report        |
+
+**Render rule:**
+
+1. For TaskCreate, use the matching label as the task `subject`.
+2. For terminal banners, call `phase-banner.sh` with the `auto` sentinel and `PHASE_LANG=en` env — or pass the literal label from the table. Never invent a new label.
+3. Reviewer-count qualifiers (e.g. `(parallel + triage)`) stay English — they are technical artifacts, not user copy.
+
+**Out of scope for localization** (always EN, per `prefs.schema.json`): reviewer/triage system prompts, commit messages, PR titles/bodies, Jira comments, wiki content, log payloads inside `agent-log.md` — these are external artifacts consumed by other tools and humans beyond this user.
+
+#### TaskCreate ordering (strict)
+
+All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied (Claude Code path; Copilot CLI does not have a TaskList widget so this rule is Claude-only). The native widget renders by creation order, not by phase-number metadata — out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state file is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN: register the tile in order with default `pending` status, then flip via TaskUpdate when the phase actually short-circuits. Mode-specific phase sets:
+
+- Full pipeline (`multi-agent`, `multi-agent-autopilot`, `multi-agent-local`, `multi-agent-local-autopilot`): 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7
+- `--dev` modes (`multi-agent-dev`, `multi-agent-dev-autopilot`, `multi-agent-dev-local`, `multi-agent-dev-local-autopilot`): 0 → 3 → 5 → 6 → 7 (phases 1/2/4 are NOT TaskCreate'd at all)
+
+Full contract: `refs/tracker-contract.md` § "TaskCreate ordering (strict)".
+
+### Phase 0: Init
+
+> **Contract (strict)** — Phase 0 has **8 sequential interactive steps** defined in `refs/phases/phase-0-init.md`. Do **NOT** short-circuit. Even when input is a Jira ID + branch, Steps 1, 4, 5, 6 (load prefs, multi-repo offer, branch picker, branch name confirm) are REQUIRED UX checkpoints — skipping them breaks component-production flows where base branch is `iteration/develop`, not `develop`, and where multiple repos must be selected.
+>
+> The condensed walkthrough below covers Step 1 (parse) + Step 2 (worktree), but DOES NOT replace the full contract. Read `refs/phases/phase-0-init.md` before every Phase 0 run and execute ALL 8 steps:
+>
+> 1. **Bootstrap tracker** — `pipeline/scripts/phase-tracker.sh init <task-id>` + 8 phase tiles (Step −1)
+> 2. **Load prefs** — read `prefs.global` + `prefs.projects[{name}]`; halt with `/multi-agent:setup` prompt if no keychain mapping (Step 0)
+> 3. **Parse input** — classify + fetch Jira/GitHub issue + extract Figma URL if present (Step 1)
+> 4. **Select project(s) — single OR multi-repo** — present numbered list of repos from `$HOME`. Picker accepts space-separated numbers (`1 3 4`) for multi-select. Component/refactor tasks often span repos (e.g. component repo + consumer app). Surface saved `global.recentGroups` at the top of the list. **Never auto-pick a single repo when the task could touch more than one** — ask the user to confirm single vs multi. (Step 2)
+> 5. **Pick base branch PER REPO** — REQUIRED INTERACTIVE STEP. If one repo selected: run `git ls-remote --heads origin` on that repo, present sorted list (develop* / release/* / main/master first), suggest top of `global.recentBranches[{projectKey}]`. **If multiple repos selected: fire the branch picker separately for each repo** (phase-0-init.md L221: "In multi-repo mode, the prompt fires per-repo"). Users reported this being silently skipped for component work where the correct base is `iteration/develop` — either per-repo prompt missing, or one branch assumed for all repos. Skip only if the user's original input explicitly specified a branch. (Step 3)
+> 6. **Branch name confirm** — `feature/PROJ-{id}-{kebab}` or `bugfix/...` — user confirms or edits. In multi-repo mode the branch name is shared across all selected repos (collision check runs per-repo; any collision applies the suffix to all). (Step 4)
+> 7. **Git identity — per repo** — route via `prefs.global.platformIdentityRouting`; ask if ambiguous. Multi-repo mode resolves identity **per repo independently** (phase-0-init.md L283). (Step 6)
+> 8. **Instruction files + workspace creation — serially per repo** — detect `.instructions/figma/` etc. In multi-repo mode, worktree creation loops per repo serially (phase-0-init.md L308); any failure rolls back previously-created worktrees. Write `agent-state.json` with `state.projects[]` array (scalar `project`/`projectRoot`/`branch` mirror `projects[0]` for back-compat). (Steps 7-8)
+
+**Step 1 — Project detection + input parsing:**
+
+#### my-ios-app (Jira + branch)
+1. Input: `"PROJ-12345" "feature/PROJ-12345-flight-filter"`
+2. Parse directly: `jiraId = PROJ-12345`, `branch = feature/PROJ-12345-flight-filter`
+3. No GitHub interaction needed
+
+#### my-figma-app (GitHub Issue URL)
+1. Input: `"https://github.com/my-org/my-figma-app/issues/316"`
+2. Parse issue via `gh issue view 316 --json title,body,labels,assignees`
+3. Extract Jira ID from issue title or body (pattern: `PROJ-XXXXX`)
+4. Auto-generate branch: `feature/PROJ-{jiraId}-GH{issueNo}-{component-kebab}`
+5. Assign issue to self: `gh issue edit 316 --add-assignee @me`
+6. Move to In Progress: `gh issue edit 316 --add-label "in progress"`
+
+#### generic (any iOS project)
+1. Accept multiple input formats:
+   - **Free-text**: `"LoginView'da dark mode'da buton rengi gorunmuyor, contrast yetersiz"`
+   - **GitHub Issue URL**: parse via `gh issue view`
+   - **Jira ID + branch**: parse directly
+2. If free-text:
+   - Extract task summary from description
+   - Auto-generate branch: `fix/{short-kebab-description}` or `feature/{short-kebab-description}`
+   - Determine type from context: bug description → `fix/`, feature request → `feature/`
+3. No Jira integration needed — task ID is enough for tracking
+
+**Step 2 — Worktree setup (all projects):**
+1. **Fetch latest from remote**: `git fetch origin`
+2. Determine worktree path:
+   - Jira ID var: `.worktrees/PROJ-{id}/`
+   - Jira ID yok (generic): `.worktrees/task-{shortId}/` (e.g. `.worktrees/task-3/`)
+3. Create or switch to git worktree:
+   - If remote branch exists: `git worktree add {worktree-path} origin/{branch} -b {branch}`
+   - If new branch: `git worktree add {worktree-path} -b {branch}`
+   - If worktree already exists: `cd {worktree-path} && git pull origin {branch}`
+4. Set git author (resolved from `prefs.global.identities[]` — routed by `platformIdentityRouting`, see `setup.md`):
+   ```
+   git config user.name  "{identity.name}"
+   git config user.email "{identity.email}"
+   ```
+4. Create log file: `.worktrees/PROJ-{id}/agent-log.md` with header
+5. Create state file: `.worktrees/PROJ-{id}/agent-state.json` with:
+   ```json
+   {
+     "taskId": "PROJ-12345",
+     "branch": "feature/PROJ-12345-flight-filter",
+     "project": "my-ios-app",
+     "currentPhase": 0,
+     "status": "in_progress",
+     "startedAt": "2026-04-07T09:30:00Z",
+     "phases": {
+       "0": { "status": "done", "duration": "5s" },
+       "1": { "status": "pending" },
+       "2": { "status": "pending" },
+       "3": { "status": "pending", "todos": [], "retryCount": 0 },
+       "4": { "status": "pending", "reviewIteration": 0 },
+       "5": { "status": "pending" },
+       "6": { "status": "pending" },
+       "7": { "status": "pending" }
+     },
+     "analysisFindings": [],
+     "planTodos": [],
+     "reviewConsensus": null
+   }
+   ```
+6. Log: `✅ Phase 0: Init complete`
+
+**IMPORTANT**: Update `agent-state.json` at EVERY phase transition. This file is the resume source of truth.
+
+### Phase 1: Analysis (claude-opus-4.6)
+1. Launch **explore agents** (parallel) to scan codebase:
+   - Related files to the task
+   - Existing patterns and conventions
+   - Potential impact areas
+2. Optionally launch **security-auditor** agent for pre-check
+3. Summarize findings
+4. Log: `📊 Phase 1: Analysis — {N} files identified, {summary}`
+
+### Phase 2: Planning (claude-opus-4.6)
+1. Create task breakdown → todos with dependencies
+2. Launch **ios-architect** agent for architecture review (if structural changes)
+3. Determine development approach per todo (new file, modify, refactor)
+4. Log: `🧠 Phase 2: Plan — {N} todos created`
+5. **Plan Approval Gate** (normal mode only — skipped for `--dev`, `autopilot`, `--dev autopilot`). Full flow in `refs/phases/phase-2-planning.md` Step 5:
+   - **5a — Clarification** (conditional, max 2 rounds): if the Jira/issue description is ambiguous (vague acceptance, UI task without Figma, API task without endpoint contract, `ambiguityScore >= 2`, parent-story scope drift), ask structured questions before rendering the plan. User answers → plan regenerated. 2. turda hâlâ net değilse "best-effort" banner'ı ile plan'ı bas.
+   - **5b — Approval loop**: render plan → user: `onayla`/`iptal`/serbest metin. Free-text düzenleme isteği → Opus plan revize eder → tekrar göster. No iteration cap; user controls exit via `onayla` or `iptal`.
+   - Persist `clarificationRounds`, `clarificationQuestions`, `clarificationAnswers`, `planIterations`, `planApprovedAt`, `planEditRequests` to `state.phases["2"]`.
+
+### Phase 3: Dev (claude-sonnet-4.6)
+For each todo (respecting dependency order):
+1. Update todo status: `in_progress`
+2. **TDD cycle**:
+   - Write failing test → verify RED
+   - Write minimal code → verify GREEN
+   - Refactor if needed
+3. Run build: `xcodebuild` via **task agent**
+4. If build fails → fix → rebuild (max 3 attempts, track `retryCount` in `agent-state.json`)
+5. Update todo status: `done`
+6. Log: `⚡ Phase 3: {todo-id} — Test ✅ Build ✅`
+
+### Phase 4: Review (parallel + triage)
+0. **Diff Risk Scoring (advisory, v8.3+)** — before reviewer dispatch run `node pipeline/scripts/diff-risk-score.mjs --base "$BASE_BRANCH" --top 5` and inject the top-N risk-ranked files as a `${PRIORITY_FILES}` block into each reviewer's prompt. Heuristic, deterministic, sub-second, never gates the pipeline. Disabled when `prefs.global.diffRiskAdvisory = false`. Signals: security paths (×3), schema migrations (×4), public API surfaces (×2), no-test-change (×2.5), complexity delta (×1.5), UI-critical paths (×1.5), loc changed (×1).
+1. Launch **code-reviewer** agents in parallel. Reviewer set depends on which CLI is hosting the pipeline:
+   - **Claude Code** (2 reviewers): `claude-opus-4.6` (deep security + architecture) + `claude-sonnet-4.6` (quality + correctness)
+   - **Copilot CLI** (3 reviewers): `gpt-5.4` (edge cases, different perspective) + `claude-opus-4.6` + `claude-sonnet-4.6`
+   - Triage (both CLIs): single `claude-opus-4.6` pass over merged findings
+2. Collect findings, classify:
+   - 🔴 **Blocking** → must fix → back to Phase 3 (max 3 iterations)
+   - 🟡 **Important** → fix and re-review
+   - 🟢 **Suggestion** → apply if reasonable
+3. Log: `🔍 Phase 4: Review — {consensus}`
+
+### Phase 5: Test
+Lets the user physically test the code before opening a PR. The prompt MUST make it explicit that saying yes **removes the worktree and checks the branch out locally** — otherwise the user is hit with an implicit side effect.
+
+0. **Test Gap Report (advisory, v8.3+)** — before the local-checkout prompt run `node pipeline/scripts/test-gap-scan.mjs --base "$BASE_BRANCH" --stack <ios|android|python|node>` to surface public symbols added in this branch that have no paired test. Heuristic, deterministic, sub-second, never gates by default. iOS `*View.swift` / Android `@Composable` symbols default to `important` severity; other public API additions to `suggestion`. Optional gating via `prefs.testGap.blockingThreshold` (loops back to Phase 4 rework when the important+blocking count exceeds the threshold). Disabled when `prefs.testGap.enabled = false`.
+1. **Ask** (in English; `promptLanguage` is locked to `en`):
+   - `Want to check out locally to test? (y/N)`
+     `(yes → worktree is removed and branch is checked out locally for Xcode/manual test · no → stay in worktree and go to Phase 6)`
+   - **No** → go to Phase 6
+   - **Yes** → continue:
+2. **Worktree'yi kaldır ve branch'e geç** (otomatik):
+   ```bash
+   cd {project-root}
+   git worktree remove .worktrees/PROJ-{id}
+   git checkout {branch-name}
+   ```
+3. **Test talimatı ver**:
+   ```
+   🧪 Branch'e geçildi: {branch-name}
+
+   Test için:
+     • SourceTree → commit'leri ve diff'i kontrol et
+     • Xcode → THY.xcworkspace aç → Cmd+B → Cmd+U
+     • Simulatör'de manual test
+
+   ✅ "tamam" → Phase 6'ya geçer
+   ❌ "fix: ..." → worktree tekrar oluşturulur, Phase 3'e döner
+   ```
+4. **Pause and wait**: Kullanıcının yanıtını bekle
+5. **Eğer fix gerekiyorsa**:
+   - Worktree'yi tekrar oluştur: `git worktree add .worktrees/PROJ-{id} {branch-name}`
+   - Phase 3'e dön
+6. Log: `🧪 Phase 5: Test — {result}`
+
+> ⚠️ Commit'ler branch'te yaşar — worktree silmek commit'leri SILMEZ.
+
+### Phase 6: Commit & PR
+
+**Project-specific commit strategy:**
+
+#### my-figma-app
+1. **Sor**: "Commit atmak ister misin?"
+   - **Hayır** → Pause, kullanıcı hazır olunca `resume` ile devam eder
+   - **Evet** → devam et:
+2. `/figma-iteration-commit {ComponentName}` çalıştır
+   - Build doğrulama, test, key sync, code review, submodule commit'leri `iteration/develop`'a, push with rebase-retry, issue housekeeping, auto-unblock dependents — hepsini skill halleder
+   - Manuel commit YAPMA — skill her şeyi yönetir
+3. Log: `📦 Phase 6: figma-iteration-commit — {ComponentName}`
+
+#### my-app / generic
+1. **Sor**: "Commit atmak ister misin?"
+   - **Hayır** → Pause, kullanıcı hazır olunca `resume` ile devam eder
+   - **Evet** → devam et:
+2. Stage changes: `git add` with specific files (NOT `git add -A` — avoid committing .env, credentials, or other sensitive files)
+3. Commit with convention: `{type}({scope}): {description} [PROJ-{id}]`
+   - Author: resolved from `prefs.global.identities[]` (e.g. `Ada Lovelace <ada@example.com>`) — NEVER hardcode.
+4. Push to remote
+5. **Sor**: "Pull Request açmak ister misin?"
+   - **Hayır** → Phase 7'ye geç (sadece commit + push yapılmış olur)
+   - **Evet** → PR oluştur (target: source branch)
+6. **Issue body update** (if GitHub Issue exists):
+   - Fill PR links in issue body: `- **common:** {PR URL}`, `- **uicomponents:** {PR URL}`
+   - Update Progress flags: `Implementation 🟢`, `Testing 🟢`, `Code Connect 🟢`
+   - Use `gh issue edit {issueNo} --body "{updated body}"` — preserve all existing sections
+7. Log: `📦 Phase 6: Commit {sha} — PR #{number}`
+
+### Phase 7 Report Step 2: WIKI + Figma Screenshots (for component tasks with GitHub Issue)
+
+Skip this sub-step if the task is NOT a component implementation (e.g., bug fix, refactor).
+
+**Wiki submodule location**: `~/my-figma-app/TurkishAirlinesPackages/Packages/my-ui-components-wiki`
+
+1. **Determine wiki path** from component location:
+   - `DesignSystemCore/SeatMap/SeatMapAircraftDetails/` → `{wikiRoot}/DesignSystemCore/SeatMap/SeatMapAircraftDetails/`
+   - Pattern: `{wikiRoot}/{category}/{ComponentName}/`
+2. **Create directory**: `mkdir -p {wikiComponentPath}/assets`
+3. **Fetch Figma screenshot** via REST API:
+   ```bash
+   FIGMA_TOKEN=$(~/.copilot/lib/credential-store.sh get "Figma_Access_Token")
+   curl -s "https://api.figma.com/v1/images/{fileKey}?ids={nodeId}&format=png&scale=2" \
+     -H "X-Figma-Token: $FIGMA_TOKEN"
+   # Download the image URL to {wikiComponentPath}/assets/screenshot.png
+   ```
+4. **Generate main wiki page** (`{ComponentName}.md`):
+   - Follow existing wiki convention (see Tooltip.md, FileUploadFileDescription.md as references)
+   - Sections: title, screenshot embed, Figma link, Screen/Section/Size, Overview, Testing Identifiers, Localization Keys, Accessibility, Analytics Events, Sub-Components, Platform Implementations, Changelog
+   - Screenshot embed: `[[/{wikiCategory}/{ComponentName}/assets/screenshot.png|{ComponentName}]]`
+5. **Generate iOS wiki page** (`{ComponentName}-iOS.md`):
+   - Sections: Initializer (with code), Parameters table, Modifiers, Usage examples, Design Tokens table, Testing Identifiers iOS, Code Connect status, Snapshot Tests (with image embeds), Test Coverage, Changelog
+   - Snapshot image embeds use `[[/{wikiCategory}/{ComponentName}/assets/ios_{variant}.png]]` format
+   - Note: actual snapshot images are generated when tests run in CI/locally
+6. **Commit and push wiki**:
+   ```bash
+   cd {wikiRoot}
+   git add {wikiCategory}/{ComponentName}/
+   git commit -m "docs({scope}): add {ComponentName} wiki pages [PROJ-{id}]"
+   git fetch origin && git rebase origin/master
+   git push origin HEAD:master
+   ```
+7. **Update issue Wiki flag**: Set `Wiki` → `🟢` in issue body
+8. Log: `📖 Phase 7 Step 2: Wiki — {ComponentName}.md + {ComponentName}-iOS.md + screenshot`
+
+### Phase 7: Report
+1. Finalize `agent-log.md` with ALL sections:
+   - **Timeline table**: phase, agent, model, duration, status, detail
+   - **Agent Activity Report**: per-agent call count, total duration, models used, skill count
+   - **Token Tahmini**: estimated token usage per agent + total
+   - **Faz Bazlı Süre Dağılımı**: ASCII bar chart showing time per phase
+   - **Review İterasyonları**: blocking/important/suggestion counts per iteration
+   - **Files Changed**: `git diff --stat` output
+   - **Review Consensus**: final 🔴/🟡/🟢 status
+   - **Test Scenarios**: Turkish, for Jira (Ön koşul → Adımlar → Beklenen sonuç)
+2. Print compact summary to terminal:
+   ```
+   ✅ PROJ-{id} complete
+   ⏱️  Total: 3m 18s | Agents: 12 calls | Files: 4 changed
+   📦 Commit: abc1234 | PR: #87
+   📖 Wiki: {ComponentName}.md pushed to wiki master
+   📋 Full report: .worktrees/PROJ-{id}/agent-log.md
+   ```
+3. Log: `📋 Phase 7: Report complete`
+
+---
+
+## Log File Format
+
+Create at `.worktrees/PROJ-{id}/agent-log.md`:
+
+```markdown
+# PROJ-{id} — {Task Title}
+**Branch**: {branch-name}
+**Project**: {my-ios-app | my-figma-app}
+**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)` her satır için `phase-tracker.sh tokens` accumulator'ından beslenir. Token telemetrisi yoksa hücre `—` olarak basılır.
+
+## Agent Activity Report
+
+### Agent Kullanımı
+| Agent | Çağrı Sayısı | Toplam Süre | Model(ler) | Skill Sayısı |
+|-------|-------------|-------------|------------|-------------|
+| explore | 3 | 12s | haiku | 0 |
+| ios-architect | 1 | 8s | opus | 6 |
+| code-reviewer | 3 | 37s | opus, gpt-5.4, sonnet | 5 each |
+| security-auditor | 1 | 6s | sonnet | 4 |
+| task (build) | 4 | 2m 15s | haiku | 0 |
+| **TOPLAM** | **12** | **3m 18s** | | |
+
+### Token Tahmini
+| Kategori | Miktar |
+|----------|--------|
+| Ana agent (orchestrator) | ~{N}K tokens |
+| Alt agent'lar (toplam) | ~{N}K tokens |
+| **Toplam tahmini** | **~{N}K tokens** |
+| Premium request sayısı | ~{N} |
+
+> Token miktarları tahmindir. Kesin kullanım için `/usage` komutunu çalıştırın.
+
+### Faz Bazlı Süre Dağılımı
+```
+Phase 0: Init       ████░░░░░░░░░░░░  5s
+Phase 1: Analysis   ██████░░░░░░░░░░  12s
+Phase 2: Planning   █████░░░░░░░░░░░  8s
+Phase 3: Dev        ████████████████  2m 35s  ← en uzun
+Phase 4: Review     ████████░░░░░░░░  37s
+Phase 5: Test  ██░░░░░░░░░░░░░░  (kullanıcı bekleme)
+Phase 6: Commit     ██░░░░░░░░░░░░░░  3s
+Phase 7: Report    ███░░░░░░░░░░░░░  17s  ← Jira + Wiki + Confluence + Log + Knowledge
+```
+
+### Review İterasyonları
+| Iterasyon | Blocking | Important | Suggestion | Karar |
+|-----------|----------|-----------|------------|-------|
+| R1 | 0 | 1 | 2 | 🟡 fix + re-review |
+| R2 | 0 | 0 | 1 | 🟢 pass |
+
+## Files Changed
+
+## Review Consensus
+
+## Cost Breakdown
+
+(Phase 7'de `pipeline/scripts/render-agent-log-cost.sh <task-id>` ile basılır. Tracker'da token verisi yoksa renderer exit 2 döner ve bu bölüm sessizce atlanır.)
+
+| Phase | Model | Tokens in | Tokens out | Est. USD |
+|-------|-------|-----------|------------|----------|
+
+## Test Scenarios (Jira)
+```
+
+### Cost Breakdown — emit kontratı
+
+Phase 7 agent-log compose adımı bu render'ı her zaman dener:
+
+```bash
+COST_BLOCK=$(bash pipeline/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
+  printf '\n%s\n' "$COST_BLOCK" >> "$AGENT_LOG"
+```
+
+`reportContent.costSummary` ile bağımsız — agent-log her zaman taşır, PR/Jira gövdeleri opt-in. Renderer `cost-table.json`'u kullanır; fiyat güncellemesi tek noktadan iki yüzeye birden akar.
+
+---
+
+## SwiftUI Component Generation Guide (Generic)
+
+When the task involves creating a SwiftUI component (any project, not just figma), follow this architecture:
+
+### Component Architecture: Configuration / View / Modifiers
+
+Every component produces up to 5 files:
+
+| File | When | Content |
+|------|------|---------|
+| `{Name}Configuration.swift` | Complex (>3 props) | Pure value type, all declarative properties |
+| `{Name}View.swift` | Always | SwiftUI view, renders Configuration |
+| `{Name}+Modifiers.swift` | Complex | Fluent modifier API chain |
+| `{Name}Preview.swift` | Always | All meaningful variant previews |
+| `{Name}Tests.swift` | Always | ViewInspector + Unit tests |
+
+### Configuration Purity Rule
+
+Configuration structs hold ONLY declarative, value-type properties:
+
+```swift
+// ✅ CORRECT — pure value type
+struct ButtonConfiguration {
+    var title: String = ""
+    var style: ButtonStyle = .primary
+    var isEnabled: Bool = true
+    var icon: Image? = nil
+}
+
+// ❌ WRONG — these do NOT belong in Configuration
+// Closures → View property
+// @Binding → View property
+// @State → View property
+// AnyView / @ViewBuilder → View generic parameter
+```
+
+### View Implementation
+
+```swift
+struct ButtonView: View {
+    let configuration: ButtonConfiguration
+    private var action: (() -> Void)?  // closure lives in View, not Config
+
+    var body: some View {
+        Button(action: { action?() }) {
+            HStack(spacing: .Spacing.spacing8) {
+                if let icon = configuration.icon { icon }
+                Text(configuration.title)
+                    .typographyStyle(.body1)
+            }
+        }
+        .disabled(!configuration.isEnabled)
+    }
+}
+```
+
+### Modifier Pattern
+
+```swift
+extension ButtonView {
+    func title(_ value: String) -> ButtonView {
+        var config = configuration
+        config.title = value
+        return ButtonView(configuration: config)
+    }
+    func style(_ value: ButtonStyle) -> ButtonView {
+        var config = configuration
+        config.style = value
+        return ButtonView(configuration: config)
+    }
+    func onTap(_ action: @escaping () -> Void) -> ButtonView {
+        var view = self
+        view.action = action
+        return view
+    }
+}
+```
+
+### Simple vs Complex Decision
+
+| Criteria | Simple | Complex |
+|----------|--------|---------|
+| Properties | ≤3 | >3 |
+| Configuration file | No — props in View directly | Yes — separate struct |
+| +Modifiers file | No | Yes |
+| View file | All-in-one | Renders Configuration |
+
+### 3-Layer Test Strategy
+
+| Layer | Tool | What It Validates |
+|-------|------|-------------------|
+| Structural | ViewInspector | Hierarchy, subview existence, applied modifiers |
+| Visual | Snapshot Tests | Pixel-correct render: light/dark, RTL/LTR |
+| Behavioral | Unit Tests | State changes, closures, configuration mutations |
+
+### Component Checklist (Commit Öncesi)
+
+1. Magic number yok — tüm değerler design token veya named constant
+2. Configuration purity — Config'te side-effect veya view mantığı yok
+3. Modifier doğruluğu — fluent API geçerli, paired modifier'lar View'da
+4. Accessibility — her interaktif element'te accessibility label/trait
+5. Preview — tüm anlamlı varyantlar preview'da
+6. Test — structural + unit testler yazıldı
+7. Dark mode — her iki renk şemasında doğru render
+8. Dynamic Type — metin büyük boyutlarda layout kırılmadan ölçekleniyor
+
+### Figma URL Verildiğinde
+
+Eğer kullanıcı bir Figma URL verirse:
+1. Figma MCP tools ile tasarım verisini çek (get_design_context, get_screenshot)
+2. Design'daki renkleri, spacing'leri, typography'yi projenin token sistemine map et
+3. Yukarıdaki Configuration/View/Modifiers pattern'ini uygula
+4. Screenshot'u referans olarak kullan, kopyalama — projenin mevcut component'lerine adapte et
+
+---
+
+## Rules
+
+- ❌ NEVER put "Copilot", "AI", "generated by" in code or commits
+- ❌ NEVER commit without passing build
+- ❌ NEVER commit without passing review
+- ✅ Follow existing code style and conventions
+- ✅ Use design tokens, no magic numbers
+- ✅ Every public method must have tests
+- ✅ Xcode header on new Swift files
+- ✅ Commit message format:
+  - Jira var: `{type}({scope}): description [PROJ-{id}]`
+  - Jira yok (generic): `{type}({scope}): description [#{shortId}]`
+- ✅ Git author: resolved from `prefs.global.identities[]` (e.g. `{identity.name} <{identity.email}>`) — NEVER hardcoded
+
+---
+
+## Skill Injection Strategy
+
+Sub-agents have embedded skills in their `.agent.md` files. Each agent is pre-loaded with domain-specific knowledge:
+
+### Agent ↔ Skill Matrix
+
+| Agent | Embedded Skills | When Activated |
+|-------|----------------|----------------|
+| **code-reviewer** | Code Review Excellence, Security Audit, Performance Review, TDD Verification, Error Detective | Phase 4: Review |
+| **ios-architect** | Spec-Driven Architecture, Context Management, Multi-Agent Coordination, API Design, Performance Architecture, Design System Governance | Phase 2: Planning |
+| **security-auditor** | iOS Security Deep Dive, App Store Review Gates, Third-Party SDK Risk, Error Detective (Security) | Phase 1: Analysis (pre-check) + Phase 4: Review |
+
+### Phase → Agent → Skills Flow
+
+```
+Phase 1: Analysis
+  ├─ explore agents (no skills needed — pure file reading)
+  └─ security-auditor agent
+       └─ Skills: iOS Security Deep Dive, App Store Review Gates, SDK Risk
+
+Phase 2: Planning
+  └─ ios-architect agent
+       └─ Skills: Spec-Driven Architecture, API Design, Performance Architecture
+
+Phase 3: Dev
+  └─ Ana agent (reads copilot-instructions.md directly)
+       └─ TDD, token rules, code style — from global instructions
+
+Phase 4: Review (parallel + triage)
+  Claude Code  (2 parallel):
+    ├─ code-reviewer (claude-opus)   → all 5 review skills
+    └─ code-reviewer (claude-sonnet) → all 5 review skills
+  Copilot CLI  (3 parallel):
+    ├─ code-reviewer (gpt-5.4)       → all 5 review skills
+    ├─ code-reviewer (claude-opus)   → all 5 review skills
+    └─ code-reviewer (claude-sonnet) → all 5 review skills
+  Triage (both): claude-opus over merged findings
+```
+
+### Context-Aware Skill Injection
+
+When calling sub-agents, the ana agent SHOULD add task-specific context to the prompt:
+
+```
+For code-reviewer in Phase 4:
+  "Review this diff for PROJ-{id}. Focus areas based on analysis:
+   - {files changed summary from Phase 1}
+   - {architecture decisions from Phase 2}
+   - {specific risk areas identified}"
+
+For ios-architect in Phase 2:
+  "Evaluate architecture for PROJ-{id}. Context:
+   - {task description from Jira/GitHub}
+   - {affected modules from Phase 1 analysis}
+   - {existing patterns found by explore agents}"
+```
+
+This ensures sub-agents get both their embedded skills AND task-specific context.
+
+---
+
+## Status Display Format
+
+When `multi-agent status` is called, show:
+
+```
+🤖 Multi-Agent Tasks
+
+| ID | Jira | Branch | Phase | Status | Duration |
+|----|------|--------|-------|--------|----------|
+| #1 | PROJ-12345 | feature/PROJ-12345-... | 3/7 Dev | ⚡ todo-2 in progress | 4m |
+| #2 | PROJ-67890 | feature/PROJ-67890-... | 4/7 Review | 🔍 Waiting consensus | 7m |
+| #3 | PROJ-11111 | feature/PROJ-11111-... | 7/7 DONE | ✅ Complete | 12m |
+
+💡 kill #2  |  log #1  |  resume #3
+```
+
+---
+
+## Help Display
+
+When called with no args or `help`, detect project and show relevant usage with pipeline explanation:
+
+First show how it works:
+```
+🤖 How it works (8 phases):
+  0. Init      — Proje tespiti, worktree oluşturma, state dosyası
+  1. Analysis  — Codebase tarama (paralel explore agent'lar, Opus)
+  2. Planning  — Task breakdown, mimari review, kullanıcı onayı
+  3. Dev       — TDD döngüsü: test yaz → kod yaz → build (Sonnet)
+  4. Review    — Paralel review + Opus triage. Reviewer seti CLI'a göre:
+                 • Claude Code → Opus + Sonnet (2 paralel)
+                 • Copilot CLI → GPT-5.4 + Opus + Sonnet (3 paralel)
+  5. Test — Opsiyonel: branch'e geç, Xcode'da manual test
+  6. Commit    — Commit + push + PR + issue body update (PR links + progress flags)
+  7. Report    — Tek mantıksal faz (5 adım):
+                 1) Jira comment (humanizer'dan geçmiş analiz + test senaryoları)
+                 2) Component wiki + Figma screenshot + wiki push (component task'larda)
+                 3) Opsiyonel Confluence sayfa güncellemesi
+                 4) agent-log.md'ye detaylı rapor + Quality & Metrics + telemetri
+                 5) Knowledge capture (architecture, patterns, gotchas) + memory
+
+Her adım agent-log.md'ye loglanır. Herhangi bir fazda hata → pause.
+resume ile kaldığı yerden devam eder.
+```
+
+Then show project-specific usage:
+
+**my-ios-app:**
+```
+🤖 Multi-Agent Task Orchestrator (my-ios-app)
+
+Usage:
+  multi-agent "PROJ-XXX" "branch-name"   → Full pipeline → assigns #ID
+  multi-agent status                        → All tasks with #ID, phase, status
+  multi-agent log [#id]                     → View task log
+  multi-agent resume [#id]                  → Resume paused task
+  multi-agent kill [#id]                    → Stop + delete worktree/branch/logs
+  multi-agent clear-logs                    → Delete all logs, keep worktrees
+  multi-agent purge                         → ⚠️ Full reset: delete everything
+  multi-agent review                        → Review current diff only
+
+Example: multi-agent "PROJ-12345" "feature/PROJ-12345-flight-filter"
+```
+
+**my-figma-app:**
+```
+🤖 Multi-Agent Task Orchestrator (figma)
+
+Usage:
+  multi-agent "github-issue-url"            → Full pipeline from issue
+  multi-agent status                        → All tasks with #ID, phase, status
+  multi-agent log [#id]                     → View task log
+  multi-agent resume [#id]                  → Resume paused task
+  multi-agent kill [#id]                    → Stop + delete worktree/branch/logs
+  multi-agent clear-logs                    → Delete all logs, keep worktrees
+  multi-agent purge                         → ⚠️ Full reset: delete everything
+  multi-agent review                        → Review current diff only
+
+Example: multi-agent "https://github.com/my-org/my-figma-app/issues/316"
+```
+
+**generic (any iOS project):**
+```
+🤖 Multi-Agent Task Orchestrator (generic)
+
+Usage:
+  multi-agent "bug/feature description"     → Full pipeline from free-text
+  multi-agent "github-issue-url"            → Full pipeline from issue
+  multi-agent "PROJ-XXX" "branch-name"   → Full pipeline with Jira
+  multi-agent status                        → All tasks with #ID, phase, status
+  multi-agent log [#id]                     → View task log
+  multi-agent resume [#id]                  → Resume paused task
+  multi-agent kill [#id]                    → Stop + delete worktree/branch/logs
+  multi-agent clear-logs                    → Delete all logs, keep worktrees
+  multi-agent purge                         → ⚠️ Full reset: delete everything
+  multi-agent review                        → Review current diff only
+
+Example: multi-agent "LoginView'da dark mode'da buton rengi gorunmuyor"
+```
+
+Pipeline: Init → Analysis → Planning → Development → Review → User Test → Commit → Wiki → Report
+Each step logged to: .worktrees/{task-id}/agent-log.md