@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.0

package/pipeline/multi-agent-refs/ios-coding-standard/plan.md

@@ -0,0 +1,71 @@
+# ios-coding-standard: plan contents
+
+Read by `/multi-agent:ios-coding-standard` before writing the Phase 4 plan. The
+plan contains, in order:
+
+1. **Coverage ledger**  -  total targets · audited · skipped with reasons. Not 100% accounted for
+   means the plan is not deliverable.
+2. **Summary**  -  counts by severity and source, resolved vocabulary, branch to create.
+3. **Sensitive-data inventory** (Phase 2d)  -  first, because it is the highest-risk content.
+4. **Screen × role matrix** `[STRUCT-02]`  -  screens as rows, manifest roles as columns, cells
+   `✓ / missing / misplaced`. The structural map a newcomer reads first.
+5. **Type placement table** `[STRUCT-05]`  -  type · location · consumer count · correct tier ·
+   move required. Paired with the nested-type list `[STRUCT-01]`: owner · nested type · kind ·
+   reference count · verdict.
+6. **Visibility report** `[VIS-01, VIS-02]`  -  over-exposed declarations per file, non-final
+   classes with no subclass.
+7. **Boundary report** `[MOD-*]`  -  import graph (allowed vs forbidden, with coupling depth) ·
+   manifest graph (declared vs legal for the role, plus dead edges) · **removability delta**
+   ("removing X touches N files: ...") · inbound test (tests compile with no sibling present).
+8. **Testability seam report** `[TEST-*]`  -  types reaching for the environment, logic requiring a
+   view to execute, doubles whose signatures have drifted.
+9. **Change-cost probe** `[FLEX-*]`  -  pick two plausible upcoming changes (a new variant of an
+   existing screen; a new field on a shared entity) and state what each costs in files today.
+10. **Findings table**  -  rule ID · `file:line` · current state · proposed fix · severity · source ·
+    onboarding impact.
+11. **Per-file work**  -  grouped per file, blocking → important → suggestion; within a severity,
+    highest onboarding impact first.
+12. **Behaviour-preservation guard**  -  splitting files, adding MARKs, extracting extensions and
+    moving types must not change behaviour. Anything requiring a behaviour change (a missing
+    analytics event, a wrong result type, a timezone fix, a storage migration) goes in a
+    **separate group**, reviewed and tested on its own, never inside a mechanical split commit.
+13. **Tooling delegation & the ratchet**  -  the section that decides whether any of this survives.
+    - Classify each applied rule by its registry `enforcement`. For every `lint` / `format` /
+      `scan` rule, state the concrete mechanism and whether that toolchain exists in the repo
+      (`LintToolchain`). **When it does not exist, saying so is a finding**, ranked above most
+      individual violations it would have caught.
+    - Recommend **baseline-and-ratchet, never big-bang**: grandfather existing violations, surface
+      only new ones, drain the backlog behind a green build. Order the plan the same way  -  stop
+      the bleeding, then clean up.
+    - Custom lint rule identifiers **are** the registry IDs (`sec_01_no_plaintext_persistence`,
+      `mod_01_no_sibling_import`) so a violation points straight at the rule entry.
+    - **Linting is local-only by decision**  -  the skill's `references/lint-local.sh` with `references/swiftlint.draft.yml`, config
+      and baseline kept outside the repository; no committed config, no build phase, no CI job.
+      State this honestly in the plan rather than describing a gate that does not exist: a
+      pre-PR habit catches less than a wall, so the residual risk is real and belongs in the
+      report. Adopting it project-wide remains an open decision  -  record it as one so it stays
+      visible instead of quietly lapsing.
+    - Never imply the audit substitutes for the linter, or the linter for a gate. The audit finds
+      the debt once; the linter keeps a developer honest; only a gate stops it returning.
+14. **Numeric exit criteria**  -  target and today's measured value side by side: lint violations
+    per 1k lines (<1) · public-surface ratio, public declarations ÷ externally consumed symbols
+    (≈1) · forbidden cross-module imports (0) · removability delta · files over threshold and
+    files >120 lines with no sectioning (0) · screens missing a manifest role (0) · escape-hatch
+    count `[CONC-03]` (flat or falling) · exception-marker count (flat or falling) · dead code (0)
+    · screens with logic and no mirrored tests (0) · unclassified sensitive symbols (0).
+15. **Exception ledger**  -  every `// standard:exception(<ID>)` in the module: rule · reason ·
+    expiry · expired yes/no.
+16. **Open Questions**  -  Phase 2b dimensions with no majority, and unclassifiable symbols.
+17. **Suggested commit slicing**  -  one commit per file-group / concern.
+18. **Scope guard**  -  only this module is touched; definition of done is the module's own
+    verification path.
+
+## Onboarding summary
+
+Then write a **separate one-page onboarding summary** beside the plan, aimed at a developer
+joining next week rather than at whoever does the remediation: the ten always/never lines
+specialised to this module, the screen file manifest, the placement ladder, the sensitive-data
+classes in play, and the verification command. Nobody learns a codebase from a 40-finding audit -
+this page is the actual deliverable, and the audit is how you earn the right to write it
+accurately. Derive it from `references/STANDARD.md section 0`, do not re-invent it.
+

package/pipeline/multi-agent-refs/ios-coding-standard/resolve-and-scan.md

@@ -0,0 +1,135 @@
+# ios-coding-standard: resolve and scan detail
+
+<!-- toc -->
+- [Phase 2](#phase-2)
+- [Phase 3](#phase-3)
+- [Verification reality](#verification-reality)
+<!-- /toc -->
+
+Read by `/multi-agent:ios-coding-standard` at the start of Phase 2 and again
+before Phase 3. The rules themselves live in the `ai-ios-toolkit:ios-coding-standard`
+skill (`references/rules.yml`); this file is procedure only.
+
+## Phase 2
+
+Module roles from Phase 1 decide which dependency edges are legal: **feature** ·
+**core/common** · **seam** (cross-module contracts/bridges/navigation) ·
+**composition root** (legitimately knows every module).
+
+### 2a. The registry is the standard  -  in-module prose docs are NOT consulted
+
+The skill's `references/rules.yml` (+ a project `modules/<Module>.yml` overlay) is the single
+source of truth. Module prose docs are being retired so there is one place a rule can live;
+consulting them re-creates the split this command exists to remove. If such a file exists and
+contradicts the registry, that is a finding against the file, not against the code.
+
+The only in-repo inputs are **code and manifests**: sources, tests, `Package.swift`, `Info.plist`,
+the specs the generator reads, and the module registry from Phase 1.
+
+### 2b. Per-module overlay, then inference
+
+1. **`modules/<Module>.yml`** beside the project's own config carries what code cannot state: the vocabulary
+   bindings, the module's role, prohibitions that currently have **zero** instances, deliberate
+   carve-outs, name locks, and the real verification command. Registry-backed, so its findings may
+   be `blocking`.
+   *Why prohibitions need to be written down:* inference reads dominant patterns, and a rule
+   obeyed everywhere has no counter-example to infer from. A ban at 100% compliance is invisible
+   to a scan  -  it survives only if the overlay states it.
+2. **Repo-level rules** (root `CLAUDE.md`, contributing docs) apply to every module.
+3. **The module's own dominant pattern is its de-facto convention.** Count variants per dimension;
+   the minority instances are the finding. Internal consistency beats conformity to a sibling.
+4. No majority (even split, single instance) → not a finding. Record an Open Question.
+
+Findings from step 3 are tagged `inferred` and capped at **suggestion**. Only registry- or
+overlay-backed rules may be `blocking`.
+
+**When the overlay is missing**, generate a draft from code evidence, print it for confirmation,
+and mark every slot it could not derive  -  a frozen UI target, a name lock, a carve-out and an
+operational constraint all look like ordinary code from the outside. Do not guess them; list them
+as Open Questions.
+
+### 2c. Vocabulary
+
+Bind each slot to a real symbol by grepping the module, then the reference module. **An unbound
+slot disables its rules**  -  never invent a name, never import a sibling's.
+
+`HandlerName` · `EventParam` · `CoordinatorType` · `ResultType` / `ErrorType` / `ErrorFactory` ·
+`DIResolver` / `DIConfigurator` · `RequestModelSuffix` / `ResponseModelSuffix` / `TransportSuffix` ·
+`MapperShape` · `SafeEnumProtocol` / `UnknownCase` · `CopySurface` · `AnalyticsSurface` ·
+`A11yIdentifierSource` · `GeneratedServiceRoot` · `SharedComponentsDir` / `SharedEntitiesDir` ·
+`MicroComponentLibrary` · `FrozenUITarget` · `DesignTokenNamespaces` · `CalendarDayHelper` ·
+`LoggerAPI` · `FileHeaderShape` · `ScreenRoot` · `ScreenRoleSuffixes` · `AsyncStyle` ·
+`CompositionRoot` · `SeamLayer` · `ModuleEntrySurface` · `ConcurrencyPosture` · `LintToolchain` ·
+`CredentialStore` (the module's Keychain wrapper, if any).
+
+Print the resolved table before scanning so a wrong binding is caught early.
+
+### 2d. Sensitive-data inventory  -  required before any SEC rule runs
+
+The `SEC-*` rules are written against the **data classes** in `references/rules.yml →
+sensitive_data_classes`, never against one module's field names. Resolve the module's concrete
+instances of each class: grep entities, request/response models, storage calls and analytics
+events for the values the module actually handles, and map each to its class.
+
+Produce the inventory as a table  -  **class · concrete symbols · where it enters · required
+lifetime (transient / survives-restart / survives-reinstall) · where it is actually stored ·
+where it is logged · where it leaves (network, analytics, pasteboard, another module)**.
+
+The **lifetime column is the one that decides SEC-01**, and it is filled by walking
+`references/rules.yml → persistence_decision`, not by looking at what the code currently does. Compare it
+against the storage column and report both mismatches:
+- required transient but persisted anywhere (including the Keychain) → **over-persistence**;
+- required to survive a restart but stored outside the Keychain → **under-protection**.
+
+Then generate the SEC lint patterns *from this inventory*, so the checks match this module's real
+vocabulary. A class with no instance here yields no finding; a symbol you cannot classify, or one
+whose required lifetime nobody can state, is an Open Question, not a silent pass.
+
+This table is a deliverable in its own right, independent of whether any violation is found.
+
+
+## Phase 3
+
+### Coverage gate  -  on disk, not in memory
+
+Before scanning, write `.<module>-audit-coverage.tsv` to the scratch dir: one row per target
+(every screen under `ScreenRoot`, every shared component, every entity, every file in every
+target) with columns `path · status · rules-applied`. Mark rows as you go.
+
+- Each target is **audited** or **explicitly skipped with a reason** (generated, fixture,
+  vendored). No third state.
+- **The run is incomplete while any row is unmarked**  -  and the file, not a claim, is the proof.
+  Chunk the module if it is too large for one pass; the checklist survives a context reset.
+- No sampling. A partial audit reported as complete certifies the unscanned screens as clean.
+
+### Grep hygiene
+
+Registry `mechanism` patterns are line-based and match doc comments. Filter
+`^[[:space:]]*//`  -  BSD grep does not understand `\s`, so a `\s*//` filter silently lets `/// ...`
+through  -  then open each surviving hit and confirm it is real code. Report pre-filter and
+post-verification counts separately; a table padded with comment matches destroys trust.
+
+### Judgement rules need evidence, not assertion
+
+For any rule marked `enforcement: judgement`, a finding must carry the measurement its `check`
+names  -  a reference count, a call-site count, a consumer count, a file list. **No count, no
+finding.** This is what keeps a subjective rule from becoming an opinion.
+
+Every judgement rule has a worked ✗/✓ pair in `EXAMPLES.md`, keyed by ID. Cite it in the finding's
+proposed fix rather than re-describing the shape  -  the developer applying the fix should be
+reading the same picture the audit used.
+
+### Module-specific overrides
+
+The module's own docs win over the registry, including where they contradict a sibling module.
+Never apply one module's dialect to another. List every override honoured, so the reader sees why
+a registry rule was not raised.
+
+## Verification reality
+
+Verification reality is per-module - establish it, do not assume it. Some
+targets cannot be compiled from the CLI (asset symbol generation, UIKit-dependent
+packages, a dependency failing earlier in the graph); there, verification is
+Xcode and a manifest dump validates the manifest only. Never trust a piped
+build's exit code - a pipe reports the tail's status. Record the module's actual
+verification command in the plan.

package/pipeline/multi-agent-refs/jira/picker-detail.md

@@ -0,0 +1,71 @@
+# jira picker: list format and maturity detail
+
+Read by `/multi-agent:jira` when rendering the issue list (step 3/4), when the
+maturity check (step 3.5/4) returns a description or blocker case, and when
+writing the picker state file.
+
+## Issue list format
+
+Priority badge prefix, status suffix:
+
+```
+[3/4] Pick issue (24 found, priority-sorted):
+  > [Blocker] PROJ-12345  -  Login crash on iOS 17           (In Progress)
+    [Critical] PROJ-12340  -  Payment fails for refunds       (In Review)
+    [High]    PROJ-12338  -  Dark mode polish                 (To Do)
+    [Medium]  PROJ-12330  -  Add empty state                  (To Do)
+    [ - ]       PROJ-12300  -  Refactor LoginViewModel          (To Do)
+```
+
+## Maturity shape
+
+`~/.claude/lib/issue-fetcher.sh` returns:
+
+```jsonc
+"maturity": {
+  "score":    0..100,
+  "blockers": ["status_closed", "already_resolved", "description_empty"],
+  "warnings": ["short_description", "no_repro_steps", "no_acceptance_criteria", "description_empty_parent_available"],
+  "summary":  "..."
+}
+```
+
+## Empty description and the parent candidate
+
+Development sub-tasks are often filed with no description of their own, with
+the real requirements on the parent issue. Before scoring, `issue-fetcher.sh`
+fetches the issue's `parent` (single hop, no chasing the parent's parent). If
+the issue's own description is empty and the parent's is not, it does **not**
+auto-substitute - it exposes `descriptor.parentKey` +
+`descriptor.parentDescription` as a candidate and adds
+`description_empty_parent_available` to `warnings` (not `blockers`) instead of
+the plain `description_empty` blocker. If the parent is also empty or
+unreachable, `description_empty` still blocks.
+
+## Picker state file
+
+`/tmp/multi-agent-picker-{taskId}.json`, read by `multi-repo-pipeline.sh bridge`:
+
+```json
+{
+  "taskId":"PROJ-12345-{timestamp}",
+  "shortId":<int>,
+  "branch":"<feature|bugfix>/PROJ-12345",
+  "baseBranch":"develop",
+  "issueRef":{...},
+  "primary":{"name":"...","cloneUrl":"...","provider":"github|bitbucket"},
+  "extras":[{...}],
+  "worktreeRoot":"~/.worktrees/PROJ-12345-{timestamp}",
+  "commitType":"<feat|fix>",
+  "identity":{"name":"...","email":"..."}
+}
+```
+
+## Blocker follow-up detail
+
+An edit is a reason to re-check, never proof the gap closed - the check re-runs
+on the new content, and only a DIFFERENT gap set ever earns a second comment.
+Read the item's existing comments FIRST and derive the prior ask from the newest
+one of ours (`priorFromComments`): a scan is a new run with a fresh state file,
+so state alone would make every scan a first ask. Full contract:
+`features/maturity-followup.md`.

package/pipeline/multi-agent-refs/orchestrator/copilot-pipeline.md

@@ -0,0 +1,88 @@
+# Copilot CLI orchestrator - project detection, routing and phase summaries
+
+Detail behind the Copilot CLI orchestrator skill (`skills/shared/core/multi-agent/SKILL.md`). The skill keeps the routing skeleton, the hard rules and the gates; this file carries the project table, the full routing rows and the per-phase routing summaries. Each phase's specification is `$HOME/.claude/multi-agent-refs/phases/phase-N-<name>.md`; where a summary here and a phase ref disagree, the phase ref wins.
+
+## Project detection
+
+Detect the project from cwd FIRST, then validate the 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 the user gives the wrong format for the project, warn:
+
+- my-ios-app + GitHub URL: "This project expects a Jira ID + branch. Example: multi-agent \"PROJ-12345\" \"feature/PROJ-12345-desc\""
+- my-figma-app + Jira: "This project expects a GitHub Issue URL. Example: multi-agent \"https://github.com/my-org/my-figma-app/issues/316\""
+
+## Input types
+
+Five types, matching the `commands/multi-agent/SKILL.md` dispatcher 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 rows
+
+| Input Pattern | Action |
+|---------------|--------|
+| `"PROJ-XXX" "branch"` | my-app only: Jira ID + branch name, auto-assigned incremental ID |
+| `"https://github.com/..."` | figma only: parse the issue, extract Jira from title/body, auto-create the branch |
+| `status` | Show all tasks with ID, phase, status |
+| `log [id]` | Show agent-log.md for the task (latest if no id) |
+| `resume [id]` | Resume a paused/failed task from the last successful phase |
+| `kill [id]` | Stop the task, delete worktree + branch + logs; asks to confirm first |
+| `clear-logs` | Superseded: redirect only |
+| `purge` | Delete ALL worktrees, branches, logs, state, counter: full reset |
+| `review` | Skip phases 0-3, review the current diff only |
+| `autopilot` flag | Add to any pipeline command: skip user confirmations except destructive ops |
+| No args / `help` | Usage guide |
+
+Every task gets an auto-incremented short ID (`#1`, `#2`), stored in `agent-state.json`.
+
+## Autopilot matrix
+
+`multi-agent "PROJ-12345" "feature/PROJ-12345-desc" autopilot` skips interactive confirmations and runs end-to-end.
+
+| Phase | Normal | Autopilot |
+|-------|--------|-----------|
+| Phase 1 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop; the user replies `onayla` / `iptal` / free-text | Gate skip: log the plan, go straight to Phase 2 |
+| Phase 3 (User test) | "Want to test it?" then wait | Skip, straight to Phase 4 |
+| Phase 4 (Commit) | "Want to commit?" then wait | Automatic commit + push |
+| Phase 4 (PR) | "Want to open a PR?" then wait | Automatically create the PR |
+
+`"autopilot": true` is added to `agent-state.json` and survives a resume.
+
+## Persona models
+
+| Persona | `preferredModel` |
+|---|---|
+| `explorer` | `sonnet` |
+| `code-reviewer` | `fable` (Reviewer 1; Phase 3 sets Reviewer 2 `opus`, Reviewer 3 `sonnet`) |
+| `security-auditor` | `opus` |
+| `ios-architect` / `android-architect` / `backend-architect` | `fable` |
+
+Each persona file carries its own `modelRationale`. Observability: emit a `phase.agent.dispatch` OTel span with `{persona, resolved_model, override_source}` when `MULTI_AGENT_OTEL_SPANS=1` (see `phase-tracker.sh`).
+
+## Phase summaries
+
+**Phase 1: Plan.** Two halves, one approval gate. 1a Analysis (`explorer`, Sonnet): parallel explore agents scan related files, patterns and impact areas, then log `Phase 1: Plan (analysis) - {N} files identified`. 1b Planning (Fable): task breakdown into todos with dependencies, `ios-architect` review for structural changes, an approach per todo, then the Plan Approval Gate (`phases/phase-1-plan.md` Step 5). 5a clarification runs only when the description is ambiguous (vague acceptance, UI task without Figma, API task without an endpoint contract, `ambiguityScore >= 2`, parent-story scope drift), max 2 rounds, then a "best-effort" banner. 5b approval loop: `onayla` / `iptal` / free-text edit; an edit makes Fable revise and re-render, no iteration cap. Persist `clarificationRounds`, `clarificationQuestions`, `clarificationAnswers`, `planIterations`, `planApprovedAt`, `planEditRequests` to `state.phases["1"]`.
+
+**Phase 2: Dev (Sonnet).** Per todo in dependency order: mark `in_progress`, TDD (failing test, verify RED, minimal code, verify GREEN, refactor), build via a task agent, on failure fix and rebuild (max 3, `retryCount` in `agent-state.json`), mark `done`, log `Phase 2: {todo-id} - Test ok, Build ok`.
+
+**Phase 3: Review (parallel + triage).** Step 0 diff risk scoring is advisory: `node $HOME/.claude/scripts/diff-risk-score.mjs --base "$BASE_BRANCH" --top 5`, injected as `${PRIORITY_FILES}`; off when `prefs.global.diffRiskAdvisory = false`. Reviewers by host: Claude Code runs `claude-fable-5-1` (security + architecture), `claude-opus-5-5` (edge cases), `claude-sonnet-5-5` (quality); Copilot CLI runs `gpt-5.4`, `claude-opus-4.7`, `claude-sonnet-4.6` (no Fable). Triage is one top-tier pass (`claude-fable-5-1` on Claude Code, `claude-opus-4.7` on Copilot CLI). Blocking findings go back to Phase 2 (max 3 iterations), important ones are fixed and re-reviewed, suggestions applied when reasonable.
+
+**Phase 4: Commit & PR.** Per-project steps and the GitHub issue body update: `orchestrator/phase-4-5-projects.md`.
+
+**Phase 5: Report.** Finalize `agent-log.md` with: timeline table (phase, agent, model, duration, status, detail), agent activity report, token estimate, per-phase time distribution, review iterations, files changed (`git diff --stat`), review consensus, and test scenarios in Turkish for Jira (precondition, steps, expected result). Then print a compact terminal summary: task id and status, total time, agent calls, files changed, commit and PR, the wiki page when one was pushed, and the path to the full report under `~/.claude/logs/multi-agent/{project}/{task-id}/agent-log.md`. Log `Phase 5: Report complete`. The wiki + Figma screenshot step runs only for a component implementation with a GitHub issue: `orchestrator/phase-4-5-projects.md`.
+
+**Localization scope.** Phase labels are English on every host. Reviewer-count qualifiers such as `(parallel + triage)` stay English. Out of scope for localization (always English, per `prefs.schema.json`): reviewer and triage system prompts, commit messages, PR titles and bodies, Jira comments, wiki content and log payloads inside `agent-log.md`.

package/pipeline/multi-agent-refs/orchestrator/dispatcher.md

@@ -2,6 +2,7 @@
 
 <!-- toc -->
 - [Canonical invocation](#canonical-invocation)
+- [Routing and loading tables](#routing-and-loading-tables)
 - [Routing detail](#routing-detail)
 - [Agent definitions](#agent-definitions)
 - [jira Command](#jira-command)
@@ -12,7 +13,7 @@
 - [Global Paths](#global-paths)
 <!-- /toc -->
 
-> Loaded by `commands/multi-agent/SKILL.md` (the `/multi-agent` dispatcher). The SKILL keeps the routing tables, the loading table and the rules; this file carries the per-CLI invocation table, the agent definitions, the `jira` / `issue` / Direct-ID step lists, the Interactive Launcher prompts, the status table and the global paths. Read the matching section before routing one of those inputs.
+> Loaded by `commands/multi-agent/SKILL.md` (the `/multi-agent` dispatcher). The SKILL keeps a compact routing table and the rules; this file carries the full routing and loading tables, the per-CLI invocation table, the agent definitions, the `jira` / `issue` / Direct-ID step lists, the Interactive Launcher prompts, the status table and the global paths. Read the matching section before routing one of those inputs.
 
 ## Canonical invocation
 
@@ -33,6 +34,100 @@ The space-form (`multi-agent <subcommand>`) is still routed by this dispatcher
 for backward compatibility, but the colon (Claude) / dash (Copilot) forms are
 the canonical invocations and the only forms surfaced in autocomplete.
 
+## Routing and loading tables
+
+The full tables behind the dispatcher's compact routing table. Route first, then `Read` only the file the routed action needs.
+
+### Routing
+
+| Input Pattern | Action |
+|---------------|--------|
+| `#N`, `316` | GitHub Issue #  -  parse, select project, start pipeline |
+| `https://github.com/.../issues/N` | GitHub Issue URL  -  fetch, auto-detect or ask project |
+| `https://{JIRA_HOST}/browse/{JIRA_KEY}-XXXXX` | Jira URL  -  fetch, select project, start pipeline |
+| `{JIRA_KEY}-XXXXX` | Jira ID  -  fetch, select project, start pipeline |
+| Free-text | Bug/feature description  -  select project, start pipeline |
+| `jira` | 4-step picker (hesap → proje → issue → dev-context)  -  `commands/multi-agent/jira/SKILL.md` delegate |
+| `issue` | 4-step picker (hesap → repo → issue → dev-context)  -  `commands/multi-agent/issue/SKILL.md` delegate |
+| `status` | List all tasks (scan `$HOME/.claude/logs/multi-agent/`) |
+| `log [id]` | Show task log |
+| `resume [id]` | Resume paused task |
+| `kill [id]` | Delete worktree (logs preserved). Confirm first |
+| `clear-logs` | **Superseded  -  redirect, do not run.** Say so and route to `prune-logs`. It targeted `.worktrees/PROJ-*/agent-log.md`, a path nothing has written to since logs moved to `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`; running it would report deleting nothing as success. |
+| `purge` | Worktree + logs + counter  -  full reset (double confirm) |
+| `review [#N\|repo#N\|PR-url\|branch]` | Parallel review of a PR or branch diff; with no input (interactive) lists open GitHub + Bitbucket PRs to multi-select. Posts per-finding inline comments + approve/needs-work on PRs. No worktree. |
+| `review-jira [KEY\|url]` | Grade a Jira issue's readiness for the pipeline (scope / AC / repro / design / API / stack), then post the gaps as a Jira comment. Read-only on code. |
+| `review-issue [#N\|repo#N\|url]` | Grade a GitHub issue's readiness for the pipeline, then post the gaps as an issue comment. Read-only on code. |
+| `analysis ["<feature>"]` | Standalone feature-spec analysis; stops after the document. No worktree, no commits, no dev chain. |
+| `complaint-analysis ["<run-name>"] [--file <path>] [<jira-id\|confluence-url> ...]` | Customer-complaint triage to a report and a verdict; read-only on code. No worktree, commits or dev chain. |
+| `build-optimize` | iOS-only Xcode build performance wrapper; recommend-first plan. Fail-fast on non-iOS stacks. |
+| `channels [PR-url\|#N\|Jira-url\|Jira-id] [--channels pr,jira,confluence,wiki] [--content normal,test,auto-diff,note] [--message "..."]` | Post the task report to multi-select channels with multi-select content; Phase 5 delegates here, also post-hoc. No worktree. |
+| `create-jira ["desc"] [figma-url] [swagger-url]` | Create a standards-compliant Jira issue (Task / Bug / Story) with full draft preview + explicit approval before create. No worktree, no commits. |
+| `test` or `test [args]` | UI Bug Hunter  -  screenshot + tap + analyze on booted simulator via MCP (read `$HOME/.claude/commands/sim-test.md`). `/multi-agent:test` also resolves here via the `commands/multi-agent/test/SKILL.md` delegate. |
+| `test-dark-mode` · `test-accessibility` · `test-dynamic-type` · `test-screenshots [locale]` | Fixed-scenario aliases for the four parameterless / single-parameter `test` scenarios, so the tag autocompletes instead of having to be quoted. Each delegates to the same `sim-test.md` with its scenario pinned; behaviour is identical to the quoted form, which is not deprecated. |
+| `store-ready [repo] [--archive=\|--ipa=\|--aab=\|--apk=] [--skip-sweep]` | Pre-submission store readiness for a built package, iOS and Android, local-only. Validates only, never ships a build. |
+| `manual-test [#id]` | Phase 5 standalone Manual Test  -  checks out the task branch, prints Xcode / SourceTree hints, waits for user verdict (`ok` / `fix: ...`). |
+| `design-check [scope]` | Mock-mode vs Figma design audit (iOS / Android, local-only) with a coverage gate. No commits, no CI. |
+| `stack [ios\|android\|backend\|mobile\|all]` | Swap skills for next conversation. No arg = show current stack. |
+| `language [en\|tr]` | Show or set the assistant `outputLanguage` (explanations and chat replies). `promptLanguage` is locked to `en` and is not toggleable. No arg = show current `outputLanguage`. With `en` or `tr` = set and persist `outputLanguage`. Commits and branch names stay English; PR, Jira and wiki bodies follow it. |
+| `setup` | Keychain token + Git Identity onboarding |
+| `autopilot` | Skip user confirmations, auto commit/PR |
+| No args / `help` | Show usage guide |
+
+### Loading
+
+`commands/multi-agent/{cmd}/SKILL.md` files are invocable actions (each its own `/multi-agent:<name>` slash command); `$HOME/.claude/multi-agent-refs/**` are internal references read by the dispatcher, never invoked directly, and live outside `commands/` so they never appear in slash-command autocomplete.
+
+| Route | File to Read |
+|-------|-------------|
+| Pipeline task (any input type) | `$HOME/.claude/multi-agent-refs/phases.md` + `$HOME/.claude/multi-agent-refs/_account-picker.md` + `_repo-picker.md` + `_dev-context.md` |
+| `jira` | `$HOME/.claude/commands/multi-agent/jira/SKILL.md` (4-step picker) |
+| `issue` | `$HOME/.claude/commands/multi-agent/issue/SKILL.md` (4-step picker) |
+| Direct ID (`{JIRA_KEY}-N`, `#N`, gh URL, repo#N, free-text) | `$HOME/.claude/multi-agent-refs/_input-parser.md` → `_account-picker.md` → `lib/issue-fetcher.sh` (maturity check) → `_dev-context.md` |
+| `setup` | `$HOME/.claude/commands/multi-agent/setup/SKILL.md` |
+| `help` | `$HOME/.claude/commands/multi-agent/help/SKILL.md` |
+| `channels` | `$HOME/.claude/commands/multi-agent/channels/SKILL.md` |
+| `sync` | `$HOME/.claude/commands/multi-agent/sync/SKILL.md` |
+| `clear-logs` | Handled inline  -  redirect to `prune-logs`, see the routing note |
+| `review` | `$HOME/.claude/commands/multi-agent/review/SKILL.md` |
+| `review-jira` | `$HOME/.claude/commands/multi-agent/review-jira/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/readiness-review.md`) |
+| `review-issue` | `$HOME/.claude/commands/multi-agent/review-issue/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/readiness-review.md`) |
+| `analysis` | `$HOME/.claude/commands/multi-agent/analysis/SKILL.md` |
+| `complaint-analysis` | `$HOME/.claude/commands/multi-agent/complaint-analysis/SKILL.md` |
+| `build-optimize` | `$HOME/.claude/commands/multi-agent/build-optimize/SKILL.md` |
+| `create-jira` | `$HOME/.claude/commands/multi-agent/create-jira/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/generate-issue.md`) |
+| `stack` | `$HOME/.claude/commands/multi-agent/stack/SKILL.md` |
+| `language` | Handled inline  -  set/show outputLanguage in preferences |
+| SwiftUI component task (iOS) | `$HOME/.claude/multi-agent-refs/swiftui-guide.md` |
+| Jetpack Compose task (Android) | `$HOME/.claude/multi-agent-refs/android-guide.md` |
+| Backend API task | `$HOME/.claude/multi-agent-refs/backend-guide.md` |
+| Web component task | `$HOME/.claude/multi-agent-refs/web-guide.md` |
+| Phase 1 or Phase 5 (knowledge) | `$HOME/.claude/multi-agent-refs/knowledge.md` |
+| Token lookup needed | `$HOME/.claude/multi-agent-refs/keychain.md` |
+| Audit tools (Phase 3) | `$HOME/.claude/multi-agent-refs/audit-guide.md` |
+| `test` | `$HOME/.claude/commands/sim-test.md` (colon-form `/multi-agent:test` uses the delegate at `commands/multi-agent/test/SKILL.md`) |
+| `test-dark-mode` · `test-accessibility` · `test-dynamic-type` · `test-screenshots` | `$HOME/.claude/commands/sim-test.md`, scenario pinned by the command name (delegates at `commands/multi-agent/test-*/SKILL.md`) |
+| `manual-test` | `$HOME/.claude/commands/multi-agent/manual-test/SKILL.md` |
+| `design-check` | `$HOME/.claude/commands/multi-agent/design-check/SKILL.md` |
+
+**Modifier flag** (`autopilot`) and **ops** (`status`, `log`, `resume`, `kill`, `purge`, `review`) are parsed inline by this file  -  no separate spec files, they compose with the pipeline or do one-shot work.
+
+Guide selection (auto, from the Phase 1 detected stack):
+- iOS detected -> load `swiftui-guide.md`
+- Android detected -> load `android-guide.md`
+- Python/Node.js/Go detected -> load `backend-guide.md`
+- React/Vue/Next.js detected -> load `web-guide.md`
+- Multiple stacks -> load all relevant guides
+
+### Lib scripts
+
+Under `~/.claude/lib/`:
+- `account-resolver.sh`  -  keychain account inventory
+- `issue-fetcher.sh`  -  Jira/GitHub fetch + maturity scoring
+- `repo-cache.sh`  -  TTL-cached repo list
+- `submodule-detector.sh`  -  `.gitmodules` parse → dev-context suggestions
+- `multi-repo-pipeline.sh`  -  worktree/branch/commit/PR orchestration
+
 ## Routing detail
 
 The full action descriptions for the routing rows the dispatcher keeps short.