@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/multi-agent/refs/progress-contract.md

@@ -0,0 +1,155 @@
+# Progress Line Contract
+
+> **TLDR** — Every non-trivial pipeline action emits an inline "I'm doing X right now" line so the user always knows what's happening. Immediate flush, no batching. One line per action, standard shape. Autopilot prefers verbose. Low overhead. Mirrored in telemetry as `progress.step` events.
+
+This contract is consumed by every phase (0–7) and every imported skill (figma-ios, figma-android). It is enforced by `smoke-progress-contract.sh` — any phase doc that drops the contract marker or diverges from the line shape fails CI.
+
+---
+
+## Why
+
+Today pipeline users see a phase banner (`→ Phase 3: Dev`) and then silence for 30 s–3 min while subagents churn. Users lose trust, hit ⌃C, or retry identical work. A single-line "current action" fixes it without adding noise: you see exactly what is happening, where, and for how long.
+
+## Line shape
+
+```
+    → <verb> <object>[ <target>]
+```
+
+- **4-space indent**, same as subphase indent elsewhere.
+- `→` arrow, single space.
+- **verb** — lowercase present participle or imperative, one word: `fetching`, `reading`, `running`, `writing`, `posting`, `waiting`, `dispatching`, `retrying`, `building`, `committing`, `checking`.
+- **object** — what is being acted on: file basename, API endpoint last segment, subagent name, command, smoke name.
+- **target** — optional, human-readable scope: repo name, ticket ID, URL host.
+
+### Examples
+
+```
+    → fetching Jira issue ABC-12345
+    → reading LoginView.swift
+    → dispatching explore agent repo-map
+    → running xcodebuild -scheme Components
+    → posting review to Jira comment ABC-12345
+    → retrying push origin (attempt 2/5)
+    → committing squashed WIP to bugfix/ABC-12345
+    → writing wiki FigmaComponents/Core/Button
+    → checking smoke smoke-push-retry
+```
+
+### Forbidden
+
+- **No** ANSI color inside the line (runtimes may not render it).
+- **No** emoji in the verb slot (they collide with the phase banner glyphs).
+- **No** payload ≥ 120 chars — truncate target with an ellipsis before shipping.
+- **No** hostnames, tokens, PATs, stderr blobs — emit as `…` and attach detail via telemetry, not the line.
+- **No** buffered flushes. `stdout` is flushed inside the same call that produces the line.
+
+---
+
+## When to emit
+
+Emit a progress line **at least** at every one of these moments:
+
+### Phase 0 (Init)
+- parse input, classify, token lookup per service, repo scan, worktree create (per repo in multi-repo), identity bind, state file write.
+
+### Phase 1 (Analysis)
+- explore-agent start, explore-agent finish, analyst synthesis start, analysis.json write.
+
+### Phase 2 (Planning)
+- plan draft start, plan render, user-approval prompt.
+- **v5.3.0 Plan Approval Gate (normal mode only — skipped for `--dev`, `autopilot`, `--dev autopilot`):**
+  - `clarification-ask` per round — orchestrator writes structured questions when Phase 1 flagged ambiguity (missing acceptance criteria, no Figma/endpoint link, vague language, parent-story scope drift)
+  - `clarification-answer` per round — user reply captured into `state.phases["2"].clarificationAnswers`
+  - `plan-edit-request` per free-text edit — user-supplied revision instruction captured into `state.phases["2"].planEditRequests`
+  - `plan-approved` — terminal success, writes `state.phases["2"].planApprovedAt`
+  - `plan-aborted` — terminal failure (user typed `iptal`/`no`), sets `state.status = "paused"`
+
+### Phase 3 (Dev — non-component)
+- every TDD cycle step: read-target, write-test, run-test RED, write-code, run-test GREEN, run-build, wip-commit.
+
+### Phase 3 (Component — figma-to-component subphases)
+- subphase dispatch, Figma API call, token mapping, file write per artifact, build step, REVIEW.md gate.
+
+### Phase 4 (Review)
+- deterministic-gate per gate, reviewer dispatch per reviewer, reviewer finish per reviewer, triage start, triage verdict render, fix dispatch.
+
+### Phase 5 (User Test)
+- local-test prompt render; user-answer capture; if local-test selected: repo checkout, build instructions print.
+
+### Phase 6 (Commit & PR)
+- squash per repo, commit per repo, push per repo (each retry attempt), PR body generate (humanizer call), PR create per repo, Jira comment post.
+
+### Phase 7 (Report)
+- humanizer summary, wiki write (if enabled), Jira comment post (if enabled), Confluence publish (if enabled), metrics rollup, summary render.
+
+### Sync / Setup / Utility commands
+- file discovery, Keychain lookup, config read/write, prompt render.
+
+---
+
+## Verbosity
+
+Controlled by `prefs.global.settings.progressVerbosity`. Enum:
+
+| Value | Emits | Default for |
+|---|---|---|
+| `quiet` | Phase banners + terminal prompts only | CI runs, automated tests |
+| `normal` | Banners + the "when to emit" list above | interactive users (default) |
+| `verbose` | Banners + everything in `normal` + sub-agent internal actions, file-level reads, schema validations, retry internals | autopilot (forced), debugging |
+
+**Autopilot rule:** When `mode: "autopilot"` is set in agent state, progressVerbosity is forced to `verbose` regardless of the preference — rationale: user isn't watching live, so the log must be audit-grade.
+
+---
+
+## Telemetry
+
+Every emitted progress line also writes one `metrics.jsonl` event:
+
+```json
+{
+  "ts": "2026-04-16T17:22:04Z",
+  "event": "progress.step",
+  "taskId": "T-0042",
+  "phase": "phase-3-dev",
+  "step": "run-test RED",
+  "ms": 2318,
+  "ok": true
+}
+```
+
+`ms` captures the elapsed time since the previous `progress.step` in the same phase. `ok: false` flags the step that immediately preceded a phase fail (used by `token-budget-report.mjs` to localise slow or failing steps).
+
+Overhead: ~40 bytes / line + one millisecond clock read. Negligible vs. any of the actions being measured.
+
+### Token telemetry forwarding
+
+Every phase that dispatches a billable LLM agent MUST forward the call's token totals to the tracker so the agent-log Cost Breakdown stays complete. The single canonical call shape is:
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> <event> \
+  model=<opus|sonnet|haiku|gpt-5.4> \
+  tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
+```
+
+`LOG_METRIC_FORWARD_TO_TRACKER=1` mirrors the same `tokens_in` / `tokens_out` / `model` into `phase-tracker.sh` so the JSONL metrics line and the tracker's per-phase accumulator stay in sync from one call site. The forward path is best-effort — if the tracker is missing or its file is unwritable, the JSONL write still succeeds. Without the flag the line is purely analytic and the cost block stays empty for that phase.
+
+This contract is enforced by `smoke-agent-log-cost.sh` (forwarder unit test) and `smoke-tracker-contract.sh` (Phase 4 reviewer/triage emission).
+
+---
+
+## Phase adoption marker
+
+Every phase doc under `refs/phases/` must contain the marker line exactly once:
+
+```
+<!-- progress-contract: applied -->
+```
+
+The smoke scans all phase docs for this marker. A missing marker means the phase hasn't adopted the contract yet and fails CI. Adding the marker commits the phase to the contract — any PR that removes it must also remove the phase's progress emissions (no silent regression).
+
+---
+
+## Cross-CLI parity
+
+The progress line shape and the `progress.step` event schema are part of the cross-CLI contract. Both Claude Code and Copilot CLI implementations emit identical bytes on the same action — the shape is **not** wrapped in CLI-specific prelude or color codes. `smoke-cross-cli-behavior.sh` includes a progress-line parity check.

package/pipeline/commands/multi-agent/refs/rules.md

@@ -0,0 +1,189 @@
+# Multi-Agent Pipeline — Global Rules
+
+> **TLDR** — Non-negotiable rules that apply to every phase, every mode, every action. Read once, enforce everywhere. If code / a commit / a PR body violates any rule below, stop and fix before proceeding.
+
+## Language Application (read this FIRST in every run)
+
+The pipeline has two language axes. Both MUST be applied from the very first turn, before any status text is rendered.
+
+| Axis | Source | Used for |
+|---|---|---|
+| `prefs.global.outputLanguage` (default `"en"`) | Read at Phase 0 Step 0 | All assistant-authored conversational text: status updates, findings, phase headers in chat, summaries, error explanations, audit reports, picker `question` + `description` text, anything the user reads outside the structural UI chrome. |
+| `prefs.global.promptLanguage` (locked to `"en"`) | Hard-coded `"en"` | `AskUserQuestion` `label` (button text) + `header` (chip), CLI host error UI, internal contract identifiers. |
+
+### Per-field language matrix (canonical)
+
+This is the single source of truth. When a contributor or model is unsure where a string lives, look here first.
+
+| Field / surface                              | Language                          |
+|---                                           |---                                |
+| Assistant chat replies (any phase)           | `outputLanguage`                  |
+| Phase headers in chat                        | `outputLanguage`                  |
+| Phase tracker render labels                  | English (script chrome)           |
+| `AskUserQuestion.question`                   | `outputLanguage`                  |
+| `AskUserQuestion.options[].description`      | `outputLanguage`                  |
+| `AskUserQuestion.options[].label`            | English (UI button contract)      |
+| `AskUserQuestion.header`                     | English (≤12-char chip)           |
+| Confirmation prompt body (e.g. push y/n)     | `outputLanguage`                  |
+| GitHub issue comment body                    | `outputLanguage`                  |
+| Wiki / Confluence page body                  | `outputLanguage`                  |
+| Jira comment body (cross-link + summary)     | `outputLanguage`                  |
+| PR description body                          | `outputLanguage`                  |
+| Commit subject + body                        | English (git convention)          |
+| Branch name                                  | English (`feature/…`)             |
+| PR title prefix (`feat:`, `fix:`, …)         | English (Conventional Commits)    |
+| Code identifiers, file paths, log lines      | English (interop)                 |
+| `agent-state.json` values                    | English (machine-readable)        |
+| `agent-log.md` entries                       | English (audit trail consistency) |
+| Reviewer / triage system prompts             | English (model contract)          |
+
+**Required steps**
+
+1. At the very start of every run (Phase 0 Step 0, before any status output), call `jq -r '.global.outputLanguage // "en"'` on `$HOME/.claude/multi-agent-preferences.json`. Cache as `OUTPUT_LANG` for the session.
+2. Render every assistant-authored line in `OUTPUT_LANG`. If the user types Turkish but `outputLanguage="en"` is set, follow the pref but suggest `/multi-agent:language tr` once.
+3. `AskUserQuestion` `label` and `header` stay English regardless of `OUTPUT_LANG` (UI contract). `question` and `description` follow `OUTPUT_LANG` — the user reads them as conversational copy, not as button affordances.
+4. Always English regardless of either axis: commit messages, PR titles, branch names, code identifiers, agent-state.json values, agent-log.md, reviewer/triage system prompts.
+
+**Failure mode this prevents.** Entering `/multi-agent:dev`, `/multi-agent:autopilot`, `/multi-agent:local`, etc. and switching the assistant's conversational text or picker question copy to English while `outputLanguage="tr"` is set. The user sees a half-English half-Turkish dialogue, flagged as a pipeline bug, not a stylistic choice.
+
+## Code & Commit Rules
+
+- **NEVER** put "Copilot", "AI", "generated by", or similar attribution in code, comments, commit messages, PR descriptions, or issue comments. The pipeline is a tool — it writes on behalf of the configured Git identity, not as itself.
+- **NEVER** commit without passing build (all gates in Phase 4 Step 1 must be green).
+- **NEVER** commit without passing review (at least one AI reviewer must return `approved: true` with no blocking findings).
+- **NEVER** skip tests. Every public method, every error path, every edge case.
+- **Follow existing code style and conventions.** Read neighbor files before writing new ones — match naming, structure, import order.
+- **Use design tokens, no magic numbers.** `16` → `.Spacing.spacing16`. `#E31837` → `Color.Primary.primary`. `.font(.system(size: 14))` → `.typographyStyle(.body1)`.
+
+## Swift-Specific Rules
+
+- **Xcode header on new Swift files:**
+  ```swift
+  //
+  //  {FileName}.swift
+  //  {ModuleName}
+  //
+  //  Created by {identity.name} on {DD.MM.YYYY}.
+  //
+  ```
+- No force unwraps (`!`) except IBOutlets. No force casts (`as!`) — use `as?` with `guard`.
+- No `print()` — use `os_log` or `Logger`.
+
+## Commit Format
+
+| Scenario                    | Format                                      |
+| --------------------------- | ------------------------------------------- |
+| Has Jira ID                 | `{type}({scope}): description [{jiraId}]`   |
+| No Jira (GitHub issue only) | `{type}({scope}): description [#{shortId}]` |
+| Free-text task (no tracker) | `{type}({scope}): description`              |
+
+- **Types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `style`, `perf`
+- **Max first-line length**: 72 chars
+- **Body** for "why", not "what"
+- **Git author**: identity selected in Phase 0, from preferences file (not Keychain, not git global config)
+
+## Branch Naming
+
+- `feature/{jiraId}-{short-description}` for features
+- `bugfix/{jiraId}-{short-description}` for fixes
+- `hotfix/{description}` for emergency patches (no tracker required)
+- `release/{version}` for release branches
+
+## External System Outputs (PR descriptions, Jira comments, GitHub issue bodies)
+
+**formatting contract (required)** — violating these produces unreadable output and is the single most common regression:
+
+1. **Real newlines, never literal `\n`.** Shell strings like `"line1\nline2"` get saved verbatim by Bitbucket / Jira REST APIs — they render as literal `\n`, not line breaks.
+
+   ✅ **Correct pattern** (heredoc → rawfile → data-binary):
+
+   ```bash
+   cat > /tmp/body.md <<'EOF'
+   ## Summary
+
+   - bullet 1
+   - bullet 2
+   EOF
+
+   jq -n --rawfile body /tmp/body.md '{description: $body}' > /tmp/payload.json
+
+   curl -s -X POST -H "Content-Type: application/json" \
+     --data-binary @/tmp/payload.json \
+     "$API_URL"
+   ```
+
+   ❌ **Wrong**: `-d '{"description": "## Summary\n- bullet"}'` → renders literal `\n`.
+
+2. **Never use HTML entities** in titles, commit messages, task subjects, or body text: `&amp;`, `&lt;`, `&quot;`, `&#39;` are NOT decoded by Bitbucket / Jira / GitHub. They appear literally. Use plain `&`, `<`, `"`, `'`.
+
+3. **Never hand-concatenate JSON** for bodies with special characters. Use `jq` (which escapes correctly) or `jq --rawfile` (which preserves bytes exactly).
+
+4. **Terminal output, log lines, and `echo`/`printf` calls** also use real newlines — never `\n` literals. For multi-line messages, prefer heredoc.
+
+## Issue Management
+
+- **NEVER auto-close** GitHub issues or Jira tickets. Closure requires team review (configurable, typically 4 approvals).
+- PR body: use `Ref: #N`, `Related: #N`, or `See: {jiraId}` — NEVER `Closes #N`, `Fixes #N`, `Resolves #N` (GitHub auto-closes on merge).
+- Jira auto-close keywords forbidden for the same reason.
+
+## Reviewers (Every PR)
+
+- **Default reviewers are required** on every PR.
+  - **Bitbucket**: fetch from default-reviewers REST endpoint, filter out PR author, include in payload (empty `reviewers: []` means "no reviewers" — a regression, not a default).
+  - **GitHub**: rely on CODEOWNERS + branch protection required reviewers; fall back to `prefs.projects[{p}].githubDefaultReviewers` if none configured.
+- **Every Bitbucket PUT must include** `reviewers`, `fromRef`, `toRef`, `draft` — missing fields wipe the existing values (Bitbucket treats omission as empty).
+
+## Build Queue
+
+- All `xcodebuild` / `xcodebuild test` calls acquire `/tmp/claude-xcodebuild.lock` before running. Parallel Xcode builds corrupt DerivedData and simulator state.
+- Each worktree uses its own `-derivedDataPath "{worktreePath}/.DerivedData"` to prevent cross-contamination.
+- Lock auto-releases; stale locks (>15min) get force-cleaned.
+- Non-Xcode builds (Gradle, npm, Python) don't need the lock — they handle their own concurrency.
+
+## Retry Discipline
+
+- **3-iteration hard kill** on any retry loop (build fix, review fix, mutation verify). On the 4th failure, pause and ask the user. No exceptions.
+- **Reflection prompt before retry**: "What failed? What specific change fixes it? Am I repeating the same approach?"
+- **Never blindly retry** the identical action — diagnose the root cause first.
+
+## Secrets & Sensitive Files
+
+- **NEVER commit** secrets, tokens, keys, certificates, `.env` files, `Pods/`, `.build/`, `DerivedData/`, `.worktrees/`, or `agent-log.md` / `agent-state.json`.
+- Stage files by name (`git add path/to/file.swift`) — never `git add -A` or `git add .` (accidentally includes sensitive files and agent artifacts).
+- Secret scan runs as Phase 4 Gate 4 — if any hit, fix immediately before proceeding.
+
+## Provider CLI Invocations
+
+Provider tools that print failed argv on retry leak credentials into the conversation transcript. Every Vercel call from the pipeline (Phase 6 deploy hooks, Phase 7 site updates, manual `vercel deploy` shells) MUST go through the wrapper:
+
+```bash
+# CORRECT — token via env var, output redacted automatically. Token resolution
+# goes through the cross-platform credential helper so the same snippet works
+# on macOS / Linux / Windows installs:
+VERCEL_TOKEN="$(~/.claude/lib/credential-store.sh get mmerterden_Vercel_Access_Token)" \
+  bash $HOME/.claude/scripts/vercel-deploy.sh deploy --prod
+
+# Health check before deploy:
+bash $HOME/.claude/scripts/vercel-deploy.sh doctor
+```
+
+**Forbidden:**
+
+```bash
+# Vercel CLI prints argv on retry → token leaks to transcript.
+vercel deploy --token=vcp_…
+vercel deploy --token "$VERCEL_TOKEN"
+```
+
+The wrapper at `pipeline/lib/vercel-deploy.sh` (installed to `~/.claude/scripts/vercel-deploy.sh` and `~/.copilot/scripts/vercel-deploy.sh`) refuses any `--token=` argv input, runs the CLI with `VERCEL_TOKEN` env, and pipes every stdout/stderr line through a redact filter that scrubs `vcp_…`, `Bearer …`, and JSON-body token shapes. Regression gate: `smoke-vercel-deploy-redact.sh` (12 assertions).
+
+Same rule applies to any future provider wrapper (e.g. `cloudflare-deploy.sh`, `npm-publish.sh`) — never pass tokens via argv when the underlying CLI may echo argv on failure.
+
+## Subagent Contract
+
+- Every subagent (Explore, code-reviewer, architect, dev task) returns **structured JSON**, not prose:
+  ```json
+  {"status": "complete", "findings": [...], "files_changed": [...], "blocking": false}
+  ```
+- Subagents receive **minimum viable context** — diff + relevant files, never the whole repo.
+- Subagents never write state, never post to external systems — the orchestrator owns side effects.

package/pipeline/commands/multi-agent/refs/swiftui-guide.md

@@ -0,0 +1,254 @@
+## SwiftUI Component Generation Guide (Generic)
+
+When the task involves creating a SwiftUI component (any project), follow this architecture.
+These practices come from the battle-tested Figma-to-SwiftUI pipeline — apply them in every iOS project.
+
+### Component Architecture: Configuration / View / Modifiers
+
+| 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                  |
+
+### Simple vs Complex Decision
+
+- **<=3 properties** -> Simple: all props in View directly, no Configuration struct
+- **>3 properties** -> Complex: separate Configuration struct + Modifiers extension
+- **Variant-driven** (e.g. style enum with 5+ cases) -> Always Complex, even if few props
+
+### Configuration Purity Rules
+
+Configuration is a **pure value type** — zero side effects, zero view logic:
+
+```swift
+// Configuration: VALUES ONLY
+struct ButtonConfiguration {
+    var title: String = ""
+    var style: ButtonStyle = .primary
+    var size: ButtonSize = .medium
+    var isEnabled: Bool = true
+    var leadingIcon: Image? = nil
+}
+```
+
+**What should NOT be in Configuration:**
+
+- `@Binding`, `@State`, `@ObservedObject` — these belong in View
+- Closures (`onTap: () -> Void`) — these belong in View
+- `@ViewBuilder` content — View
+- Computed properties — logic stays in View
+- Any protocol conformance except `Equatable`, `Hashable`, `Sendable`
+
+### Fluent 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)
+    }
+}
+// Usage: ButtonView().title("OK").style(.secondary)
+```
+
+### Token Discipline
+
+**Zero magic numbers. Zero raw colors. Zero raw fonts.**
+
+| Bad                            | Good                                             |
+| ------------------------------ | ------------------------------------------------ |
+| `padding: 16`                  | `.padding(.Spacing.spacing16)` or named constant |
+| `Color(hex: "#E31837")`        | `Color.Primary.primary` or semantic token        |
+| `.font(.system(size: 14))`     | `.typographyStyle(.body1)` or project typography |
+| `cornerRadius: 8`              | `.Radius.radius8` or named constant              |
+| `frame(width: 44, height: 44)` | `.Size.size44` or `minTapTarget` constant        |
+
+If the project has no design token system, create named constants at file scope:
+
+```swift
+private enum Layout {
+    static let horizontalPadding: CGFloat = 16
+    static let cornerRadius: CGFloat = 8
+    static let iconSize: CGFloat = 24
+}
+```
+
+### Variant-Driven Implementation
+
+When a component has variants (style, size, state), derive ALL visual differences from the variant enum:
+
+```swift
+enum ButtonStyle {
+    case primary, secondary, ghost
+
+    var backgroundColor: Color {
+        switch self {
+        case .primary: return .Primary.primary
+        case .secondary: return .Surface.surfaceSecondary
+        case .ghost: return .clear
+        }
+    }
+}
+```
+
+**Never use `if/else` chains in the View body for variant styling** — push it into the enum or configuration.
+
+### Nested Component Handling
+
+If the design contains sub-components (e.g. a Card with an inner Badge):
+
+1. Check if the sub-component already exists in the project — **reuse it**
+2. If not, decide: inline (simple, <3 props) or extract (reusable, complex)
+3. Pass sub-component configuration through parent: `CardConfiguration.badgeConfig: BadgeConfiguration?`
+
+### Accessibility Requirements
+
+Every interactive element MUST have:
+
+- `accessibilityLabel` — what it is (e.g. "Submit button")
+- `accessibilityHint` — what it does (e.g. "Submits the form") — only if not obvious from label
+- `accessibilityIdentifier` — for UI testing (e.g. `"button_submit"`)
+- Correct traits: `.isButton`, `.isHeader`, `.isSelected`, `.isToggle`
+- Minimum tap target: **44x44pt** (Apple HIG)
+
+```swift
+Button(action: onTap) { ... }
+    .accessibilityLabel(configuration.accessibilityLabel)
+    .accessibilityIdentifier(TestingIdentifiers.submitButton)
+```
+
+### Preview Best Practices
+
+Previews must show **all meaningful variants**, not just the default:
+
+```swift
+#Preview("Default") { ButtonView() }
+#Preview("Secondary") { ButtonView().style(.secondary) }
+#Preview("Disabled") { ButtonView().disabled(true) }
+#Preview("With Icon") { ButtonView().leadingIcon(Image(systemName: "star")) }
+#Preview("RTL") { ButtonView().environment(\.layoutDirection, .rightToLeft) }
+#Preview("Dark Mode") { ButtonView().preferredColorScheme(.dark) }
+#Preview("Large Text") { ButtonView().dynamicTypeSize(.xxxLarge) }
+```
+
+### 3-Layer Test Strategy
+
+| Layer      | Tool           | Validates                                             | Priority                |
+| ---------- | -------------- | ----------------------------------------------------- | ----------------------- |
+| Structural | ViewInspector  | Hierarchy, subview existence, applied modifiers       | P0 — always             |
+| Visual     | Snapshot Tests | Pixel render: light/dark, RTL/LTR, Dynamic Type       | P1 — complex components |
+| Behavioral | Unit Tests     | State changes, closure calls, configuration mutations | P0 — always             |
+
+**Test naming:** `test_{scenario}_{expected}` or `test_{whatItDoes}`
+
+```swift
+// ViewInspector — structure
+func test_hasTitle() throws {
+    let sut = ButtonView(configuration: .init(title: "OK"))
+    let text = try sut.inspect().find(text: "OK")
+    XCTAssertNotNil(text)
+}
+
+// Unit — configuration mutation via modifier
+func test_titleModifier_updatesConfiguration() {
+    let sut = ButtonView().title("Submit")
+    XCTAssertEqual(sut.configuration.title, "Submit")
+}
+
+// Snapshot — visual regression
+func test_snapshot_light_primary() {
+    assertSnapshot(of: ButtonView(configuration: .init(title: "OK")),
+                   as: .image(layout: .device(config: .iPhone13)))
+}
+```
+
+### Build Verification
+
+After implementation, **always run build before considering complete**:
+
+- Fix all compiler errors
+- Fix all warnings in the component files
+- Ensure previews render without crash
+
+### Component Quality Checklist
+
+Before marking a component as done:
+
+1. No magic numbers — all values are tokens or named constants
+2. Configuration purity — no side-effects, closures, or view logic in Config
+3. Modifier chain works — each modifier returns a new View with updated config
+4. Accessibility — labels, hints, identifiers, traits, 44pt tap targets
+5. Preview coverage — all meaningful variants, dark mode, RTL, Dynamic Type
+6. Tests — structural (ViewInspector) + behavioral (Unit), snapshot if complex
+7. Dark mode — correct in both color schemes
+8. Dynamic Type — text scales without layout breaking
+9. RTL — leading/trailing used, layout mirrors correctly
+10. Variant exhaustiveness — all enum cases handled, no default catch-all
+11. Build passes — zero errors, zero warnings on component files
+12. Self-documenting — code is clear without comments, MARK sections organized
+
+### Compliance Rules (maps to dev-toolkit MCP audit tools)
+
+These rules ensure your code passes `ios_accessibility_audit` and `ios_app_store_audit` without issues. Follow them during development — don't wait for audit to catch problems.
+
+#### Accessibility (validated by `ios_accessibility_audit`)
+
+| Rule                                                    | What Audit Checks                                        | How to Pass                                 |
+| ------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------- |
+| Every interactive element has `accessibilityLabel`      | Missing label on Button, Link, TextField, Toggle, Slider | `.accessibilityLabel("Submit order")`       |
+| Every interactive element has `accessibilityIdentifier` | Missing identifier                                       | `.accessibilityIdentifier("button_submit")` |
+| Minimum tap target 44x44pt                              | Frame size < 44x44                                       | `.frame(minWidth: 44, minHeight: 44)`       |
+| Correct traits                                          | Not checked by tool, but best practice                   | `.accessibilityAddTraits(.isButton)`        |
+
+```swift
+// This PASSES audit:
+Button(action: onTap) {
+    Image(systemName: "xmark")
+}
+.accessibilityLabel("Close")
+.accessibilityIdentifier("button_close")
+.frame(minWidth: 44, minHeight: 44)
+
+// This FAILS audit:
+Button(action: onTap) {     // no label
+    Image(systemName: "xmark")  // no identifier
+}                               // no min frame
+```
+
+#### Release Compliance (validated by `ios_app_store_audit`)
+
+| Rule                             | What Audit Checks                                 | How to Pass                                                              |
+| -------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
+| No debug tools in release        | FLEX, Reveal, CocoaDebug, Pulse symbols in binary | `#if DEBUG` around debug imports, never link debug frameworks in Release |
+| ATS enforced                     | `NSAllowsArbitraryLoads = true` in Info.plist     | Remove ATS exception or add justification per domain                     |
+| Privacy manifest present         | Missing `PrivacyInfo.xcprivacy`                   | Add manifest, declare Required Reason APIs                               |
+| Privacy strings for permissions  | Missing `NS*UsageDescription` keys                | Add all needed `NSCameraUsageDescription` etc. in Info.plist             |
+| No debug entitlements in release | `get-task-allow = true`                           | Use Release/Distribution profile, not Debug                              |
+| Bundle version set               | Missing `CFBundleShortVersionString`              | Always set in Info.plist or build settings                               |
+
+```swift
+// Debug tools: guard with #if DEBUG
+#if DEBUG
+import FLEX
+#endif
+
+// App startup:
+#if DEBUG
+FLEXManager.shared.showExplorer()
+#endif
+```
+
+### Figma URL Given
+
+If user provides a Figma URL, use Figma MCP tools (get_design_context, get_screenshot) to fetch design data, map to project tokens, and apply Configuration/View/Modifiers pattern.
+
+For figma project specifically: multi-agent reads `.instructions/figma/` SKILL.md files for the full 8-phase pipeline.