@mmerterden/multi-agent-pipeline 19.1.4 → 20.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "19.1.4",
+  "version": "20.1.0",
   "description": "6-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/agents/code-reviewer.md

@@ -1,9 +1,9 @@
 ---
 name: code-reviewer
-description: "Code reviewer for multi-agent Phase 4  -  security, architecture, quality, performance. Default model is fable (opus is the first fallback); Phase 4 orchestrator overrides to sonnet for Reviewer 3."
+description: "Code reviewer for multi-agent Phase 3  -  security, architecture, quality, performance. Default model is fable (opus is the first fallback); Phase 3 orchestrator overrides to sonnet for Reviewer 3."
 model: fable
 preferredModel: fable
-modelRationale: "Reviewer 1 tier  -  deep security + architecture review runs on opus (top available intelligence tier). Phase 4 orchestrator overrides to sonnet for Reviewer 3 (quality/correctness focus) via CLAUDE_CODE_SUBAGENT_MODEL before dispatch. Copilot CLI adds Reviewer 2 on gpt-5.4 for cross-model diversity."
+modelRationale: "Reviewer 1 tier  -  deep security + architecture review runs on opus (top available intelligence tier). Phase 3 orchestrator overrides to sonnet for Reviewer 3 (quality/correctness focus) via CLAUDE_CODE_SUBAGENT_MODEL before dispatch. Copilot CLI adds Reviewer 2 on gpt-5.4 for cross-model diversity."
 ---
 
 # Code Reviewer Agent

package/pipeline/agents/dev-critic.md

@@ -1,6 +1,6 @@
 ---
 name: dev-critic
-description: "Phase 2.5 evaluator  -  runs after Dev's last edit, before Phase 4. Verifies build/test/checklist gates; returns pass | fix-list. Sonnet by default; Phase 3 orchestrator may override."
+description: "Phase 2.5 evaluator  -  runs after Dev's last edit, before Phase 3. Verifies build/test/checklist gates; returns pass | fix-list. Sonnet by default; Phase 3 orchestrator may override."
 model: sonnet
 preferredModel: sonnet
 modelRationale: "Critic tier  -  deterministic checklist + build/test verification needs reliable JSON output and tool-use, not deep reasoning. Sonnet hits the cost/quality sweet spot. Opus override only when the diff is large (>500 LOC) or touches security-critical paths; orchestrator decides via PHASE_MODEL_OVERRIDE."
@@ -8,9 +8,9 @@ modelRationale: "Critic tier  -  deterministic checklist + build/test verificati
 
 # Dev Critic Agent  -  Phase 2.5
 
-You are the in-loop critic for Phase 2 (Dev). The generator (Sonnet/Opus during Phase 2) has just finished its last edit. **You run BEFORE Phase 4**, on the same worktree, against deterministic criteria that already exist on disk. Your job: catch failures the generator would otherwise send into Phase 4 and waste 2-3 reviewer calls + Fable triage on.
+You are the in-loop critic for Phase 2 (Dev). The generator (Sonnet/Opus during Phase 2) has just finished its last edit. **You run BEFORE Phase 3**, on the same worktree, against deterministic criteria that already exist on disk. Your job: catch failures the generator would otherwise send into Phase 3 and waste 2-3 reviewer calls + Fable triage on.
 
-This is the **evaluator-optimizer pattern** from Anthropic's "Building Effective Agents"  -  the pattern is most effective "when we have clear evaluation criteria, and when iterative refinement provides measurable value." Phase 3 satisfies both: criteria are written in `rules/*.md`, refinement value is measured by Phase 4 fix-cycles avoided.
+This is the **evaluator-optimizer pattern** from Anthropic's "Building Effective Agents"  -  the pattern is most effective "when we have clear evaluation criteria, and when iterative refinement provides measurable value." Phase 2 satisfies both: criteria are written in `rules/*.md`, refinement value is measured by Phase 3 fix-cycles avoided.
 
 ## Inputs
 
@@ -33,7 +33,7 @@ Run ALL of these before scoring the diff. Any failure means **return `pass: fals
 | Build | `xcodebuild -scheme <Scheme> build` (iOS) / `./gradlew assembleDebug` (Android) / `npm run build` (Node) / `python -m build` (Python) | `blocking` |
 | Lint | `swiftlint lint --strict` / `ktlint` / `eslint .` / `ruff check` | `important` (project-pref decides if blocking) |
 | Test | `xcodebuild test` (touched modules only) / `./gradlew test` / `npm test` / `pytest` | `blocking` if existing tests fail; `important` if no test added for a new fn |
-| Secrets | `grep -rE '(sk-[a-zA-Z0-9]{20,}|password\s*=|api[_-]?key\s*=|BEGIN PRIVATE KEY)' <diff-paths>` | `blocking` |
+| Secrets | Run the canonical secret scanner `pre-commit-check.sh` (the one Phase 2 Gate 4 runs, in `.claude/scripts/`), not a private regex. Its providers live in `schemas/secret-patterns.json` and are held in parity with the egress gate by `smoke-secret-parity.sh`; a hand-rolled second list here is how a secret the real gate catches slips past the critic. | `blocking` |
 
 Skip a gate ONLY if its tool isn't installed (xcodebuild on a non-Mac runner, etc.)  -  log `gate.skipped tool=<name> reason=not_installed` and proceed.
 
@@ -140,7 +140,7 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 3 \
   duration_ms=$D tokens_in=$TI tokens_out=$TO
 ```
 
-Phase 5 cost rollup includes critic calls as `phase 3.5` line items so cost summary shows the savings (or surplus) vs running Phase 4 directly.
+Phase 5 cost rollup includes critic calls as `phase 2.5` line items so cost summary shows the savings (or surplus) vs running Phase 3 directly.
 
 ## Rationale citation
 

package/pipeline/agents/security-auditor.md

@@ -1,99 +1,107 @@
 ---
 name: security-auditor
-description: Security specialist  -  analyzes code for vulnerabilities and compliance issues
+description: Security specialist  -  static application security review across mobile, web and backend. Emits reviewer-shaped JSON security findings (CVSS + CWE + evidence + fix) that merge into Phase 3 triage and block Phase 4.
 model: opus
 preferredModel: opus
-modelRationale: "Security reasoning + compliance catalog cross-reference (Apple ITMS, Google Play policy, OWASP)  -  false negatives are expensive; opus (top available tier) keeps the miss rate low on subtle vulnerabilities (auth-flow gaps, cert-pinning bypass, sensitive-data leaks)."
+modelRationale: "Security reasoning + compliance catalog cross-reference (OWASP Web/API Top 10, OWASP Mobile Top 10, Apple ITMS, Google Play policy) plus honest confidence calibration on subtle vulnerabilities (auth-flow gaps, injection sinks, SSRF, cert-pinning bypass, sensitive-data leaks). False negatives are expensive and a wrong severity is worse than silence; opus (top available tier) keeps the miss rate and the miscalibration rate low."
 ---
 
-You are a mobile security auditor specializing in application security.
+You are a static application security auditor. You read code, configuration and dependency manifests and report vulnerabilities. You do NOT run the application, fire payloads, or reach a live target: this is a defensive, read-only review. Everything you claim is grounded in something you can point to in the source.
 
-## Your Focus
+You cover first-party code in whatever stack the diff is in - Swift/Kotlin mobile, TypeScript/JavaScript/Python/Go/Java backends, web front-ends - plus the dependency manifests and secret-bearing configuration around it. You do not assume a mobile app.
 
-- OWASP Mobile Top 10 vulnerabilities
-- Apple App Store Review compliance
-- Google Play Store policy compliance
-- Data protection and encryption
-- Authentication and session management
-- Network security and certificate validation
-- Third-party SDK risk assessment
+## Threat model first
 
-## Audit Categories
+Before findings, establish the run-scoped threat model, four sections, and either write it to `.pipeline/threat-model.md` (standalone `/multi-agent:security-review`) or read the one Phase 3 already produced there. Every finding's severity is calibrated against it.
 
-### Critical (Immediate Fix)
+1. **Attacker.** Who is the realistic adversary for THIS change - an unauthenticated internet caller, an authenticated low-privilege user, a malicious dependency, a co-located app on the device? Name the one that makes this diff interesting.
+2. **Trust boundaries.** Where does untrusted data cross into trusted code in the changed surface - a request body, a deep link, a WebView message, a file the app did not write, an env var an attacker can set?
+3. **Attack surface.** What did this diff actually add or touch - a new endpoint, a new query, a new deserialization, a new permission, a new dependency? A finding outside the touched surface is out of scope unless the diff made it reachable.
+4. **Severity calibration.** State the assumption each severity rests on: "critical assumes this route is unauthenticated in production." That assumption is what a reader disputes instead of the number.
 
-- Hardcoded credentials, API keys, secrets
-- Sensitive data in UserDefaults/SharedPreferences/plain files
-- Missing HTTPS / certificate pinning bypass
-- SQL injection, XSS in WebViews
-- Private API usage
+## What you look for
 
-### High (Fix Before Release)
+Join findings to a standard so they are checkable, not opinion:
 
-- Weak encryption / deprecated algorithms
-- Missing jailbreak/root detection
-- Insecure keychain configuration
-- Debug code in production (print, NSLog, Log.d, FLEX)
-- Missing privacy manifest declarations
+- **Web / API** - OWASP Top 10 2021 (`A01:2021` .. `A10:2021`): broken access control, cryptographic failures, injection (SQL/NoSQL/command/LDAP), insecure design, security misconfiguration, vulnerable & outdated components, identification & auth failures, software & data integrity failures (insecure deserialization, unsigned updates), security logging failures, SSRF.
+- **Mobile** - OWASP Mobile Top 10 2024 (`M1:2024` .. `M10:2024`): improper credential usage, inadequate supply-chain security, insecure auth/authorization, insufficient input/output validation, insecure communication, inadequate privacy controls, insufficient binary protection, security misconfiguration, insecure data storage, insufficient cryptography.
+- **Cross-cutting** - hardcoded credentials/keys/secrets, sensitive data in plaintext stores (UserDefaults / SharedPreferences / localStorage / logs), missing or bypassed TLS and certificate pinning, weak or deprecated crypto, missing authz checks, unsafe deserialization, path traversal, and known-vulnerable dependencies (map to a `cve`).
 
-### Medium (Plan to Fix)
+Each finding gets a specific `CWE-NNN`, an OWASP category id, and a CVSS 3.1 base vector. Compute the score and band from the vector with the toolkit `security_cvss_score` tool rather than by hand, so the number cannot drift from the vector.
 
-- Excessive permissions
-- Missing input validation
-- Weak session management
-- ATS exceptions without justification
+## Evidence and honesty
 
-## Output Format
-
-```
-[SEVERITY] Category: Finding
-  File: path/to/file:line
-  Risk: What could go wrong
-  Fix: How to fix it
-```
-
-## Store-compliance catalog cross-reference
-
-On store-relevant diffs, load the matching compliance skill's rule catalog and cite the ruleID + Apple ITMS / Google Play reference next to your finding. Binary invocation is NOT required at review time  -  the catalog alone is enough to annotate a diff. Full scan runs under `/multi-agent:test "store-ready"`.
+- **Evidence** is what in the code proves the finding, cited by `file:line`. No evidence, no finding.
+- **Counterevidence** is what would disprove it - a guard elsewhere, a framework default, an unreachable path. State it; a blank counterevidence asserts there is none.
+- **Confidence** is `high|medium|low`. Low confidence does not mean stay silent - it means report with the counterevidence and let triage weigh it. Do not inflate a maybe into a certainty, and do not bury a certainty under hedging.
+- Report real, reachable vulnerabilities in the touched surface. A theoretical risk with no path from the threat model's attacker is noted as `suggestion` at most, not `blocking`.
 
-### When to load `pipeline/skills/shared/core/apple-archive-compliance/SKILL.md` (iOS)
+## Severity is derived, not chosen
 
-Trigger on any diff path matching:
+Severity is the reviewer enum `blocking | important | suggestion`, set from the CVSS band so a security blocker blocks Phase 4 exactly like a reviewer blocker:
 
-- `**/Info.plist`
-- `**/PrivacyInfo.xcprivacy`
-- `**/*.entitlements`
-- `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/*App.swift` (purpose strings)
-- `**/project.pbxproj` (Team ID, provisioning, code-signing settings)
+| CVSS band | baseScore | severity |
+| --------- | --------- | -------- |
+| critical  | 9.0-10.0  | blocking |
+| high      | 7.0-8.9   | blocking |
+| medium    | 4.0-6.9   | important |
+| low       | 0.1-3.9   | suggestion |
+| none      | 0.0       | suggestion |
 
-For each flagged line, append: `(apple-archive-compliance / <ruleID>  -  <Apple ref>)`
-Example: new `NSCameraUsageDescription` without justification → `(apple-archive-compliance / info-plist  -  Guideline 5.1.1)`
+A severity that disagrees with the band is the one thing this contract forbids.
 
-### When to load `pipeline/skills/shared/core/google-play-compliance/SKILL.md` (Android)
-
-Trigger on any diff path matching:
-
-- `**/AndroidManifest.xml` (permissions / exported / targetSdkVersion)
-- `**/build.gradle`, `**/build.gradle.kts` (signingConfig / minifyEnabled / targetSdkVersion / native abi filters)
-- `**/proguard-rules.pro`, `**/proguard-android*.txt`
-- `**/network_security_config.xml`
-- `**/gradle/libs.versions.toml` (only when dependency additions map to dangerous-permissions)
-
-For each flagged line, append: `(google-play-compliance / <ruleID>  -  <Play ref>)`
-Example: new `MANAGE_EXTERNAL_STORAGE` permission → `(google-play-compliance / dangerous-permissions  -  Policy  -  Permissions)`
+## Store-compliance catalog cross-reference
 
-### What the catalog gives you
+On store-relevant diffs, load the matching compliance skill's rule catalog and cite the ruleID + platform reference in the finding's `ruleId` and `criteriaSource`. Binary invocation is not required at review time - the catalog alone annotates a diff. Full scan runs under `/multi-agent:test "store-ready"`.
 
-The two SKILL.md files contain tabular rule catalogs:
+- iOS - load `pipeline/skills/shared/core/apple-archive-compliance/SKILL.md` on diffs touching `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/*App.swift`, `**/project.pbxproj`. Set `ruleId` to the catalog rule and `criteriaSource: apple-archive-compliance`.
+- Android - load `pipeline/skills/shared/core/google-play-compliance/SKILL.md` on diffs touching `**/AndroidManifest.xml`, `**/build.gradle`, `**/build.gradle.kts`, `**/proguard-rules.pro`, `**/network_security_config.xml`, `**/gradle/libs.versions.toml`. Set `ruleId` to the catalog rule and `criteriaSource: google-play-compliance`.
 
-- **apple-archive-compliance**  -  18 rules (privacy-manifest, required-reason-api, info-plist, code-signing, embedded-sdk, entitlement, asset-validation, binary-size, team-id-consistency, provisioning-profile, swift-abi, extension-signing, ipv6-compliance, debug-tool-leak, production-hygiene, duplicate-resource, dead-reference, sdk-floor) with ITMS codes + App Store Review Guideline refs.
-- **google-play-compliance**  -  21 rules across Technical / Security / Privacy / Hygiene categories with Play policy refs.
+## Output Format
 
-Cite rule + ref in your Output Format's `Category:` line so the code-reviewer and triage layers inherit the reference text unchanged.
+Emit a single JSON object conforming to `pipeline/schemas/reviewer-output.schema.json`, so your findings merge into the Phase 3 reviewer set at Step 3.0 and reach triage and the Phase 4 gate unchanged. Every element of `findings[]` additionally conforms to `pipeline/schemas/security-finding.schema.json` - the security envelope rides along, and validate-reviewer.mjs (which ignores unknown fields) still passes it.
+
+```json
+{
+  "findings": [
+    {
+      "severity": "blocking",
+      "file": "src/api/users.ts",
+      "line": 42,
+      "issue": "The path parameter id is concatenated into a raw SQL string.",
+      "fix": "Use a parameterized query with a bound id.",
+      "security": {
+        "owaspCategory": "A03:2021 Injection",
+        "cwe": "CWE-89",
+        "cvss": {
+          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
+          "baseScore": 9.8,
+          "band": "critical"
+        },
+        "evidence": "line 42: db.query('... WHERE id=' + req.params.id)",
+        "counterevidence": "None: id reaches the query with no validation between.",
+        "confidence": "high",
+        "confidenceRationale": "The sink and the untrusted source are both in the diff.",
+        "severityChangeConditions": "medium if the route is admin-only behind an auth guard",
+        "remediation": "Bind the id as a query parameter ($1) and pass it in the values array.",
+        "remediationDiff": {
+          "before": "db.query('SELECT * FROM users WHERE id=' + req.params.id)",
+          "after": "db.query('SELECT * FROM users WHERE id=$1', [req.params.id])"
+        },
+        "endpoint": "/api/users/:id",
+        "method": "GET",
+        "fixVerification": "Add a test that sends id=1 OR 1=1 and asserts a single-row result."
+      }
+    }
+  ],
+  "approved": false
+}
+```
 
-## Rules
+Rules for the object:
 
-- Only report real vulnerabilities, not theoretical risks
-- Provide actionable fix suggestions
-- Reference Apple/Google docs or OWASP when relevant
-- For store-compliance findings, always cite the ruleID + policy reference from the catalog  -  don't paraphrase
+- `approved` is `false` if any finding is `blocking`, `true` otherwise.
+- Empty `findings[]` with `approved: true` is the correct output for a clean diff - do not invent findings to look thorough.
+- One weakness per finding. Two weaknesses on one line are two findings.
+- Cite a real `file` and `line` from the tree; never invent a path.
+- Dependency findings (a known-vulnerable package rather than first-party code) carry the `cve`, set `owaspCategory` to `A06:2021`, `cwe` to the advisory's CWE, and `line: 0` on the manifest file.

package/pipeline/commands/figma-to-swiftui.md

@@ -1,5 +1,5 @@
 ---
-description: "Figma URL -> SwiftUI component generation (full 6-phase pipeline with SubPhases)"
+description: "Figma URL -> SwiftUI component generation (full pipeline, Phase 0-8, with SubPhases)"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, WebFetch, TaskCreate, TaskUpdate
 ---
 

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

@@ -6,6 +6,8 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 # Multi-Agent Task Orchestrator
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 > **MUST: Figma MCP is BLOCKING for any task with a Figma reference.** Before any UI synthesis runs in this pipeline (analysis, planning, dev, or rework), call `mcp__claude_ai_Figma__get_design_context` for every referenced frame and use the `CodeConnectSnippet` component name verbatim. Backend-only tasks are exempt. See `$HOME/.claude/multi-agent-refs/rules.md` "User Interaction Discipline" and `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)".
 
 Parse the user input and route to the correct sub-command.
@@ -90,7 +92,6 @@ Lib scripts (`~/.claude/lib/`):
 | `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`. External payloads (commits, PR bodies, Jira) stay English. |
 | `setup` | Keychain token + Git Identity onboarding |
-| `--local` | No worktree  -  works directly on local branch |
 | `autopilot` | Skip user confirmations, auto commit/PR |
 | No args / `help` | Show usage guide |
 
@@ -121,8 +122,6 @@ This command uses lazy loading for token efficiency. Read the relevant sub-file
 | `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` |
-| `local` | `$HOME/.claude/commands/multi-agent/local/SKILL.md` |
-| `local-autopilot` | `$HOME/.claude/commands/multi-agent/local-autopilot/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 prompt language in preferences |
@@ -132,13 +131,13 @@ This command uses lazy loading for token efficiency. Read the relevant sub-file
 | 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 5/6) | `$HOME/.claude/multi-agent-refs/audit-guide.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 flags** (`--local`, `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.
+**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.
 
 **How**: After routing, `Read` the relevant file and follow its instructions. Only load what the current action needs.
 
@@ -228,10 +227,9 @@ Save to `prefs.projects[{project}].branches`.
 
 ### Step 2  -  Mode Selection
 ```
-Pipeline depth (same question Phase 0 Step 7.5 asks):
-  1. Full  (6 phases, Sonnet dev, parallel review + triage  -  CLI-aware reviewer set)
-  2. Short (Init → Dev(Opus) → Review → Test → Commit → Report  -  no analysis/planning)
-Select [1/2]:
+One pipeline, 6 phases, Sonnet dev, parallel review + triage (CLI-aware
+reviewer set). The questions Phase 0 asks are the workspace and autopilot,
+never how much of the pipeline runs.
 ```
 
 ### Step 3  -  Autopilot

package/pipeline/commands/multi-agent/analysis/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[\"<analysis-name>\"] [--no-cache] [--preview-conventions]"
 
 # multi-agent analysis - Feature Spec Analysis (v3)
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 This command is **independent** from the orchestrator's Phase 1 analysis (which is a stack/findings detector inside `/multi-agent`). It produces a stakeholder-ready, platform-agnostic feature-spec document - up to 23 sections, trimmed to whatever the evidence supports - before any implementation starts. Each per-platform file is rendered by projecting concept-layer content onto repo-extracted conventions (Pass B).
 
 **Side-effect contract**: the command may write a local markdown file, post a Confluence page, or update a Jira description - but **never** creates branches, worktrees, commits, or PRs. It stops at the document.

package/pipeline/commands/multi-agent/analysis-jira/SKILL.md

@@ -8,6 +8,8 @@ not-for: create-jira, jira
 
 # multi-agent analysis-jira
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 **Input**: $ARGUMENTS
 
 Reads an analysis document as a work breakdown and creates the tree. It never

package/pipeline/commands/multi-agent/analysis-resolve/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[path/to/analysis/<feature>-<platform>.md] [--autonomous]"
 
 # multi-agent analysis-resolve - Open Question Resolver for Analysis Docs
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Companion command to `/multi-agent:analysis`. Takes an `analysis/<feature>-<platform>.md` (template v3) and walks the user through the open rows of Section 20 (Riskler ve Acik Sorular / Risks and Open Questions) one row at a time, proposing source-labeled answer candidates and merging the chosen answer into the proper body section. The pattern follows a spec-resolver approach (walk the open rows, propose source-labeled answer candidates, merge the chosen answer) adapted to the analysis doc contract.
 
 **Core invariant - read this twice:** the analysis doc is authoritative and forward-looking. The resolver never invents an answer; if no source produces a credible candidate, the only options offered are Defer and Other. Each Section 20 row is its own decision; never blend candidates across rows.

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

@@ -6,6 +6,8 @@ argument-hint: '"task"  -  issue URL, Jira ID, free-text, or #id (for resume)'
 
 # multi-agent autopilot  -  Autonomous Pipeline
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 **Input**: $ARGUMENTS
 
 > **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` renders its `question`, option `label`s and option `description`s in `outputLanguage`; only `header` stays English (<=12-char chip); external payload bodies follow `outputLanguage` too (identifiers, commit messages, branch names stay English). Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".

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

@@ -6,6 +6,8 @@ argument-hint: "(no arguments  -  opens the repo picker)"
 
 # multi-agent autopilot-on  -  continuous mode, on this machine
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Turns on the mode that picks work up without being asked. **No repo is included
 by default and none is ever added implicitly** - you choose, here, every time.
 

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

@@ -34,7 +34,7 @@ not a fault.
 
 When `swiftc` was available at `autopilot-on` time, `~/.claude/autopilot/bin/menubar`
 shows the same thing in the top right, refreshing on its own: one row per item
-with its id, whether it is running Full or Short, the phase as a fraction, the
+with its id, the phase as a fraction, the
 elapsed time and the stack, then the queue, then what is waiting, then the PRs of
 the last day - each one clickable.
 

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

@@ -6,6 +6,8 @@ argument-hint: "(none - operates on current repo)"
 
 # multi-agent build-optimize - Xcode Build Performance Wrapper
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Wraps the vendored `xcode-build-orchestrator` skill (and its 5 specialist analyzers) so iOS users do not have to remember the orchestrator skill name. Recommend-first: no project files are modified without explicit developer approval. All output lands in `.build-benchmark/` in the current repo.
 
 > **Language**: Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix - instruction prose stays English (this file is read as a system prompt). `AskUserQuestion.question`, `.options[].label` and `.options[].description` follow `outputLanguage`; only `header` stays English (<=12-char chip). The emitted benchmark plan body (the upstream skill controls it) is English by upstream convention.

package/pipeline/commands/multi-agent/channels/SKILL.md

@@ -288,7 +288,7 @@ Emitted only when `reportContent.workSummary === true` and at least one of (`age
 - 1 accepted · 0 deferred · 0 rejected · approved=true
 
 #### Phases
-- 0 Init [done] · 1 Analysis [done] · 2 Planning [done] · 3 Dev [done] · 4 Review [done] · 5 Test skipped · 6 Commit [done] · 7 Report active
+- 0 Init [done] · 1 Plan [done] · 2 Dev [done] · 3 Review [done] · 4 Commit [done] · 5 Report active
 ```
 
 **Post-hoc invocation** (task already finished, agent-state.json may be archived): pass `--branch` + `--base-branch` explicitly  -  the script still emits task header + changed-files + phases sections (scope + review outcome are state-dependent and will be absent if state is gone).
@@ -355,7 +355,7 @@ Applying the Jira table to the PR body is the recurring failure of this step: it
 
 Secondary artifacts ride along as one-line intents at the bottom of the preview: Wiki page list, wiki → Jira triad comment (when Wiki is selected and the triad is active per `$HOME/.claude/multi-agent-refs/issue-jira-triad.md`), Board status move (`{from} → {to}`), GitHub issue comment + Progress-flag sync (Phase 5 Step 1.5  -  same gate, see `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md`).
 
-**Then a single AskUserQuestion** (`question`/`label`/`description` in `outputLanguage`; `header` English):
+**Then a single AskUserQuestion** (`picker-contract.md`; `question`/`label`/`description` in `outputLanguage`, `header` English):
 
 | Option | Behavior |
 |---|---|

package/pipeline/commands/multi-agent/create-jira/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[\"<free-text description>\"] [figma-url] [swagger-url]  -  all
 
 # multi-agent create-jira  -  Standards-Compliant Jira Issue Creator
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 **Input**: $ARGUMENTS
 
 Creates exactly one Jira issue, and only after explicit approval. The issue type (Task / Bug / Story) is asked at the start of every run. No branches, no commits, no worktrees, no pipeline chaining. The draft learns the target project's conventions from its recent same-type issues (summary format, labels, components, priority norms, test-scenario style) and offers active-sprint placement when a sprint is running.

package/pipeline/commands/multi-agent/design-check/SKILL.md

@@ -67,7 +67,7 @@ In Claude Code also drive the native TaskList widget: fire all `TaskCreate` call
 
 ## STOP-AND-CONFIRM format
 
-Every Phase 0 / Phase 2 decision uses a native `AskUserQuestion` picker (numbered text menus are forbidden - `feedback_native_picker_ui`). Print a `Step <i>/<n>: <what it decides>` breadcrumb before each picker. Confirmation is required even with a single option; state inheritance from a previous run is FORBIDDEN.
+Every Phase 0 / Phase 2 decision uses a native `AskUserQuestion` picker per `picker-contract.md` (numbered text menus are forbidden). Print a `Step <i>/<n>: <what it decides>` breadcrumb before each picker. Confirmation is required even with a single option; state inheritance from a previous run is FORBIDDEN.
 
 ---
 

package/pipeline/commands/multi-agent/diff-explain/SKILL.md

@@ -12,7 +12,7 @@ Maps the Phase 3 triage output (`accepted` / `deferred` / `rejected`) onto the b
 
 ## When to use it
 
-- Between Phase 4 and Phase 5/6: answers "5 findings  -  which one belongs to which file?"
+- Between Phase 4 and Phase 5: answers "5 findings  -  which one belongs to which file?"
 - Phase 5 reporting: a "review summary with code context" block to embed in the Wiki / Confluence output.
 - Post-hoc audit: for a closed PR, a "what did review flag, and how did the code change" diff.
 

package/pipeline/commands/multi-agent/forget/SKILL.md

@@ -7,6 +7,8 @@ allowed-tools: Bash, Read, AskUserQuestion
 
 # multi-agent forget  -  Remove a Routine
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Delete a routine the user saved via `/multi-agent:save`. Backed by `$HOME/.claude/scripts/routine-registry.mjs`.
 
 ## Steps

package/pipeline/commands/multi-agent/garbage-collect/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[--older-than=<minutes>] [--abandoned [--days=N]] [--yes]  -  dr
 
 # multi-agent garbage-collect  -  Sweep /tmp Scratch
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Each run writes ephemeral scratch under `/tmp`: picker state
 (`multi-agent-picker-*`), PR/review diffs (`multi-agent-review-*`), issue
 progress bodies (`issue-progress-*`), channel payloads (`channels-*`),
@@ -62,7 +64,7 @@ deletes nothing until you confirm.
    residue in the index (`.worktrees/{id}` recorded as a "Subproject commit"
    entry by a pre-guard `git add -A`), and a missing `.worktrees/` line in
    `.git/info/exclude`. Registered, healthy worktrees are NEVER touched  -
-   those belong to `/multi-agent:resume-local` / `/multi-agent:kill`.
+   those belong to `/multi-agent:resume` / `/multi-agent:kill`.
 
    - Output says `nothing to do` -> skip silently, no question.
    - Otherwise surface a second `AskUserQuestion` (in `outputLanguage`):
@@ -81,7 +83,7 @@ deletes nothing until you confirm.
 
    `offload-ref.sh` parks build logs, diffs and test output under
    `.multi-agent/refs/<node_id>.md`. In worktree modes that directory dies with
-   the worktree; in the `--local` modes it lands in the real checkout, and
+   the worktree; when the run chose a local workspace it lands in the real checkout, and
    because it is gitignored it never shows up in `git status`. Only files
    matching the node-id shape are touched  -  anything else in that directory is
    left alone, and files inside the grace window are spared so a sweep cannot