@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/multi-agent/refs/channels/pr.md

@@ -0,0 +1,139 @@
+# Channel adapter — PR description
+
+> Detailed contract for the `pr` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here.
+
+The PR adapter rewrites the pull request description with the body assembled in Step 5 of `channels.md`. Default behaviour is **replace**; `--append` opt-in preserves existing content.
+
+## Required body structure
+
+The PR description targets code reviewers — it stays technical. Every adapter run assembles the body from the same fixed set of sections in the same order. Section headings render in `prefs.global.outputLanguage` (the body **text** is bilingual-aware); section keys and order are stable.
+
+| # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
+|---|---|---|---|---|
+| 1 | `summary` | `## Özet` | `## Summary` | always |
+| 2 | `changes` | `## Değişiklikler` | `## Changes` | always |
+| 3 | `architecture` | `## Mimari Kararlar` | `## Architecture Decisions` | when a non-trivial design choice was made |
+| 4 | `verification` | `## Doğrulama` | `## Verification` | always |
+| 5 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
+| 6 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+
+### Section content rules
+
+**`summary`** — 1-3 sentences in `outputLanguage`. The "why" of the change. Past tense, no marketing voice. Code identifiers stay verbatim.
+
+**`changes`** — bullet list, one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". Use the stack's native file extensions / module paths — the example below shows the **shape**, not a stack lock-in:
+
+```markdown
+## Changes
+
+- `<path/to/file.ext>` — <one-line description of what changed>
+- `<path/to/another.ext>` — <one-line description>
+- `<path/to/test.ext>` — <which scenarios were added/updated>
+```
+
+Across stacks the same shape produces, for example: `LoginView.swift — …` (iOS), `LoginScreen.kt — …` (Android), `login-form.tsx — …` (frontend), `auth_service.py — …` (backend). File paths and symbol names are NOT translated — only the trailing description sentence follows `outputLanguage`.
+
+**`architecture`** — only when the change involves a non-trivial decision (new abstraction, pattern change, data flow shift, dependency direction). Format: short paragraph stating the decision and the alternative considered. Skip the section entirely for mechanical refactors / dependency bumps / formatting passes.
+
+**`verification`** — what the reviewer should run to confirm the change works. Commands first, manual steps next. Pick the commands for the project's stack — the pipeline supports iOS (Swift/Xcode), Android (Gradle), frontend (npm/pnpm/yarn), and backend (varies: pytest/jest/go test/etc). Do not hardcode one stack in the body; emit only the commands relevant to the repos touched by this PR.
+
+Skeleton (the adapter fills the body with the actual stack-appropriate lines at write-time; the template lists the shape only):
+
+```markdown
+## Verification
+
+- Build: <stack-appropriate build command>
+- Tests: <stack-appropriate test command, scoped to the touched targets/packages>
+- Lint / type-check: <if the project has one>
+- Manual: <one or more user-facing steps the reviewer can follow without setup>
+```
+
+Multi-repo PRs (one PR per repo) emit verification commands for that repo's stack only — never mix iOS + Android commands into a single PR body.
+
+**`dependencies`** — only when `Package.swift` / `Podfile` / `build.gradle` / `package.json` changed. Each entry: `package@old → new — reason`.
+
+**`related`** — flat list, plain text. Examples:
+
+```markdown
+## Related
+
+- Jira: PROJ-XXXXX
+- Issue: #123
+- Confluence: <page-url> (if work referenced a spec)
+- Figma: <design-url> (if work referenced a design)
+```
+
+Never use `Closes #N`, `Fixes #N`, `Resolves PROJ-X`. Issues require 4-approval close, the auto-close keywords break that contract.
+
+### Assembly order (per run)
+
+```
+1. Read agent-state.json (taskId, contextLinks, identity, language).
+2. Build section bodies in markdown — summary first, then in the table order, skipping conditional sections that don't apply.
+3. Run the assembled body through the `humanizer` skill.
+4. Apply Multi-repo cross-links (## Related PRs prepend when projects.length > 1).
+5. Dispatch per the Behaviour-by-remote table.
+```
+
+## Behaviour by remote
+
+| Remote | API | Reviewer handling |
+|---|---|---|
+| GitHub | `gh pr edit --body-file` | Reviewers are independent of the body — no extra payload required. |
+| Bitbucket | `PUT /rest/api/1.0/projects/{P}/repos/{R}/pull-requests/{id}` | MUST re-send `reviewers`, `fromRef`, `toRef`, `draft`, `version` — server-side defaulting wipes any field that is omitted. |
+
+## Reviewer-preserving Bitbucket payload (required)
+
+```bash
+PR_JSON=$(curl -s -u "$BB_USER:$BB_TOKEN" "$PR_URL")
+REVIEWERS=$(jq '[.reviewers[] | {user: {name: .user.name}, approved, status}]' <<< "$PR_JSON")
+VERSION=$(jq -r '.version' <<< "$PR_JSON")
+TITLE=$(jq -r '.title' <<< "$PR_JSON")
+FROM_REF=$(jq '.fromRef | {id, repository}' <<< "$PR_JSON")
+TO_REF=$(jq '.toRef | {id, repository}' <<< "$PR_JSON")
+DRAFT=$(jq -r '.draft // false' <<< "$PR_JSON")
+
+jq -n --rawfile body /tmp/channels-$TASK_ID-pr.md \
+      --argjson version "$VERSION" --arg title "$TITLE" \
+      --argjson reviewers "$REVIEWERS" \
+      --argjson fromRef "$FROM_REF" --argjson toRef "$TO_REF" \
+      --argjson draft "$DRAFT" \
+      '{version: $version, title: $title, description: $body,
+        reviewers: $reviewers, fromRef: $fromRef, toRef: $toRef, draft: $draft}' \
+  > /tmp/channels-$TASK_ID-pr-payload.json
+
+curl -s -X PUT -u "$BB_USER:$BB_TOKEN" -H "Content-Type: application/json" \
+     --data-binary @/tmp/channels-$TASK_ID-pr-payload.json "$PR_URL"
+```
+
+## Multi-repo cross-links
+
+When `state.projects[].length > 1`, `channels-multi-repo.sh render-pr <state> <body> <repoName>` prepends a `## Related PRs` block:
+
+- The **primary** target's body lists every extra as `Related: <url>`.
+- Each **extra** target's body lists the primary as `Part of: <url>`.
+
+Single-repo tasks return one entry from `channels-multi-repo.sh targets …` with empty `crossLinks`, so the loop is shape-stable.
+
+## Version mismatch handling
+
+The Bitbucket REST API returns `409 Conflict` if `version` is stale. Adapter behaviour:
+
+1. Refetch PR JSON, retry the PUT once with the new `version`.
+2. Second mismatch → fail this adapter, log reason, return `{status: "failed", reason: "version conflict"}`. Other adapters keep running — non-blocking by Step 6 contract.
+
+## Flags that affect this adapter
+
+| Flag | Effect |
+|---|---|
+| `--append` | Body merged with existing description instead of replaced. |
+| `--ready` | If PR is draft, promote to READY after the description PUT succeeds (uses `gh pr ready` / Bitbucket `PUT … {draft: false}` sharing the reviewer-preserving payload). |
+| `--dry-run` | Generated body printed to stdout, no PUT issued. |
+
+## Hard rules (must not regress)
+
+- Real newlines, no HTML entities — heredoc + `jq --rawfile` + `curl --data-binary @file`. Never embed `\n` literally; Bitbucket stores the literal `\n` characters.
+- Section order is fixed: `summary` → `changes` → `architecture` (cond.) → `verification` → `dependencies` (cond.) → `related`. Conditional sections may be omitted but never reordered or inserted between fixed ones.
+- Humanizer pass runs **after** body assembly and **before** dispatch — every body line carries technical, non-AI tone. References at least one symbol/file/line drawn from the diff or pipeline log.
+- Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, branch names, PR titles, commands, type names, and `Closes/Fixes`-style keywords stay verbatim English. The template file (this doc) is English because `promptLanguage="en"` is locked; the body is rendered in the user's language at write-time.
+- No body markers (`<!-- channels:start -->`) — channels does a full replace each run.

package/pipeline/commands/multi-agent/refs/channels/wiki.md

@@ -0,0 +1,66 @@
+# Channel adapter — Wiki
+
+> Detailed contract for the `wiki` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here. Full Case A/Case B handling lives in `refs/wiki-capture.md`.
+
+The Wiki adapter generates component documentation pages — main page, platform sub-pages (iOS / Android), screenshots, and index updates. It is the only channel gated by **task type** (`component` only) and the only one that writes to a separate repo (the wiki repo configured in `figma-config.json`).
+
+## Precondition gate
+
+```
+state.taskType === "component"  AND  figmaConfig.wiki.enabled === true
+```
+
+If both are met → **Case A** (preconditions met) — proceed to scope multi-select.
+Otherwise → **Case B** (preconditions missing) — show the menu from `refs/wiki-capture.md` (setup / skip / disable / manual-note).
+
+In multi-repo tasks, wiki scope is the **primary** repo's `figma-config.wikiRepo` (single repo). Extras are not written to wiki — their PRs link back via the `## Related PRs` block injected by the PR adapter.
+
+## Case A — scope multi-select
+
+```
+Wiki'de ne güncelleyeyim?
+  [x] Ana component sayfası  ({Name}.md — variants, overview, testing IDs, a11y, analytics)
+  [x] iOS sub-page           ({Name}-iOS.md — initializer, usage, Code Connect)
+  [x] Screenshots            (assets/ — Figma LTR+RTL+light+dark + iOS snapshot)
+  [x] Index updates          (_Sidebar.md + ComponentImplementationStatus.md)
+  [ ] Diğer                  (adapter dispatch'i skip et, agent-log'a "manual wiki override" düş)
+```
+
+Defaults reflect `prefs.global.wikiScope` — saved selection from the prior run.
+
+## Adapter dispatch
+
+The selected scope routes to a platform skill:
+
+| Platform | Skill | Notes |
+|---|---|---|
+| iOS / SwiftUI | `pipeline/skills/figma-ios/figma-component-wiki` | Reads `Configuration` + `+Modifiers` from the source, captures Figma screenshots via MCP / REST, runs Snapshot tests for iOS dark/light/RTL. |
+| Android / Compose | `pipeline/skills/figma-android/figma-component-wiki` | Reads Compose composables + previews, runs Paparazzi screenshots if available, otherwise generates from layout inspector. |
+| Generic | `pipeline/skills/figma-common/figma-component-wiki` | Used when `state.platform` is unknown (fallback path — typically a flag). |
+
+Full per-skill contract: `refs/wiki-capture.md`.
+
+## Wiki → Jira auto-link triad
+
+When the adapter writes pages **AND** `state.jiraId` is set **AND** `prefs.global.wikiToJiraComment === true`, the adapter posts a humanizer-passed summary as an additional Jira comment (component name + variant count + wiki URL).
+
+This comment is **independent** of the main `jira` channel comment — both can coexist on the same issue. Full triad contract: `refs/issue-jira-triad.md`.
+
+## Wiki adapter modes (figma-config.wiki.mode)
+
+| Mode | Where pages live | When to choose |
+|---|---|---|
+| `submodule` | Wiki repo cloned under `Wiki/` inside the host project | Internal projects with Bitbucket — wiki repo is a submodule, commits land via PR. |
+| `in-repo` | Pages directly in the host repo (`docs/components/<Name>/…`) | Open-source projects without a separate wiki — Markdown lives in `docs/`. |
+| `github-wiki` | GitHub-managed `<repo>.wiki.git` | GitHub-hosted projects using the built-in Wiki feature. |
+| `separate-repo` | Independent wiki repo cloned to `~/.cache/multi-agent/wiki/<repo>/` | When the wiki repo is not a submodule of the host but lives under the same org. |
+
+Adapter implementation chooses the right git push target + commit message format based on `mode`. All four modes use the same content generation pipeline — only the commit / push step differs.
+
+## Hard rules (must not regress)
+
+- Wiki adapter is the **only** channel allowed to skip silently when its precondition gate fails. PR / Jira / Confluence always run when selected.
+- Per the `figma-pipeline.md` rules, every component wiki page must include a variant matrix, accessibility identifiers, analytics events, and 3-layer test summary.
+- Screenshots cover light/dark + LTR/RTL — wiki adapter refuses to commit if any quadrant is missing.
+- Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, type names, design token names, and wiki markup stay verbatim across languages. The template (this doc) is English because `promptLanguage="en"` is locked.
+- Autopilot always pauses at the channels menu (per `phase-7-report.md` autopilot contract) — even in autopilot mode the user gets to confirm wiki scope.

package/pipeline/commands/multi-agent/refs/component-dispatch.md

@@ -0,0 +1,92 @@
+# Component Dispatch (Phase 3 short-circuit)
+
+> **TLDR** — When `taskType === "component"` (Figma URL in task description or instruction-driven figma workflow), multi-agent Phase 3 **does not run the TDD loop**. It delegates the entire phase to the `figma-to-component` skill and relays its subphases 3.0 – 3.8 via the existing phase-tracker contract. Implementation lives in the skill; multi-agent's job is classification, dispatch, and state report.
+
+This doc is referenced from `refs/phases/phase-3-dev.md`. Keeping it separate lets `phase-3-dev.md` remain tight (it's already the largest phase doc) and gives the orchestrator-report contract a stable URL for both Claude-side and Copilot-side implementations.
+
+## Entry conditions
+
+Phase 3 checks, in order:
+
+1. `agent-state.json` has `taskType: "component"` (set by Phase 0 Step 7).
+2. `agent-state.json` has a non-null `figmaUrl`.
+
+Either missing → log the anomaly to `agent-log.md` ("component dispatch expected but state incomplete"), fall through to the standard TDD path. Never silently skip the Figma work.
+
+## Orchestrator resolution
+
+```
+project.platform  → orchestrator skill
+────────────────────────────────────────────────────────────────
+ios               → pipeline/skills/figma-ios/figma-to-component/
+android           → pipeline/skills/figma-android/figma-to-component/
+web, multi-*      → HALT with clear error (no web target)
+```
+
+If the chosen skill directory is missing, **halt with a user-visible error**. Do not silently fall back to TDD — a component task ran through the bugfix path would produce wrong artefacts and waste review cycles.
+
+## Dispatch call
+
+Emit `→ dispatching figma-to-component <componentName>` via the progress contract, then launch a single agent invocation on the orchestrator skill with:
+
+- `figmaUrl` — primary positional argument
+- `agentState` — the path to `agent-state.json` so the orchestrator enriches `state.phases["3"].subphases[]`
+- `progressVerbosity` — forced to `verbose` when multi-agent runs in `mode: "autopilot"`; otherwise inherits `prefs.global.settings.progressVerbosity`
+- `mode` — `"dev"` for `--dev` runs; `"full"` otherwise
+
+## Subphase contract
+
+The orchestrator writes each of its 8 subphases to `state.phases["3"].subphases[]` as it completes, with the shape:
+
+```json
+{
+  "id": "3.4a",
+  "name": "4A-Configuration",
+  "status": "done",
+  "startedAt": "2026-04-16T18:12:02Z",
+  "endedAt":   "2026-04-16T18:13:47Z",
+  "buildStatus": "green",
+  "testStatus": "green"
+}
+```
+
+Multi-agent's `phase-tracker` reads this array without any component-specific code — the tracker UI renders one row per subphase under the Phase 3 row. No new phase-tracker field is required.
+
+## Multi-repo report
+
+When multi-repo mode is active (`state.projects.length > 1`), the orchestrator reads `state.projects[]` and runs subphases against the correct per-repo worktree:
+
+- Tokens, accessibility metadata, testing identifiers, localisation keys → `repos.common`
+- View / Configuration / Modifiers / Preview → `repos.components`
+- Wiki markdown → `repos.wiki` (if `wiki.mode === submodule` or `separate-repo`) or `repos.components/.wiki/components/` (if `wiki.mode === in-repo`)
+
+Multi-agent does **not** split the component task into per-repo Phase 3 runs — the orchestrator is aware of the repo graph and sequences writes correctly (e.g. token writes to `common` precede component reads in `components`).
+
+## Failure + resume
+
+On orchestrator failure (subphase hits a build/test error that can't auto-fix, or hits retry cap):
+
+1. The orchestrator persists `{subphase, error, buildLog, testLog}` to `state.phases["3"].errors[]`.
+2. Multi-agent increments `state.phases["3"].retryCount`.
+3. Retry re-enters the orchestrator with `phase-<N>` as the argument (the failed subphase), so the skill resumes instead of restarting.
+4. Hard kill at `retryCount === 3` → surface the errors to the user, halt Phase 3. Do not loop indefinitely.
+
+## `--dev` mode behaviour
+
+When multi-agent is invoked with `--dev` (fast path: Init → Dev → Commit → Report), the orchestrator receives `mode: "dev"` and is allowed to elide:
+
+- Subphase 5C (unit tests) — structural + snapshot are still required
+- Subphase 7 (wiki) — can be deferred; Phase 7 in multi-agent will ask the user whether to run it post-commit
+
+Phase 4 reviewer-skipping is **not** Phase 3's concern — Phase 4 decides based on `mode: "dev"` itself.
+
+## Cross-CLI parity
+
+Both Claude Code and Copilot CLI implementations MUST:
+
+- Use the same orchestrator resolution table (ios / android / halt).
+- Emit byte-identical progress lines (`→ dispatching figma-to-component <name>`).
+- Write the same `state.phases["3"].subphases[]` schema.
+- Treat `--dev` the same way (elide 5C + 7 by default, no reviewer skip).
+
+`smoke-cross-cli-behavior.sh` asserts this contract.

package/pipeline/commands/multi-agent/refs/cross-cli-contract.md

@@ -0,0 +1,326 @@
+# Cross-CLI Contract (Claude Code ↔ Copilot CLI)
+
+> **Non-negotiable**. Any change that breaks this contract blocks merge. Validated by `smoke-cross-cli-behavior.sh`.
+
+**Purpose**: every pipeline command must produce identical artifacts (state, logs, outputs) and respect identical placeholder vocabulary regardless of which CLI invokes it. This file is the source of truth for "what must stay the same."
+
+---
+
+## 1. Command Inventory (29 commands)
+
+```
+autopilot, channels, dev, dev-autopilot, dev-local, dev-local-autopilot,
+help, issue, jira, kill, local, local-autopilot, log, manual-test, purge,
+refactor, resume, review, scan, search, setup, stack, status, sync, test, update
+```
+
+Categories:
+
+- **Interactive pickers** (single-purpose, not modes): `jira`, `issue`
+- **Full 8-phase modes**: `autopilot`, `local`, `local-autopilot`
+- **Fast modes** (Init → Dev(Opus) → Commit → Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
+- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `resume`, `review`, `channels`, `scan`, `search`
+- **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`
+
+> **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list — bump the count + table together.
+
+### 1.1 Figma component subphase skills
+
+In addition to the 26 top-level multi-agent commands, the figma-to-component pipeline ships platform-specific skills that multi-agent dispatches from Phase 3 (see `refs/component-dispatch.md`). The structure is **platform-parallel iOS + Android with a shared common pool**:
+
+| Location | Skill count | Purpose |
+|---|---|---|
+| `pipeline/skills/figma-ios/` | 5 | iOS-only Phase 3 sub-skills (SwiftUI-specific) |
+| `pipeline/skills/figma-android/` | 5 | Android-only Phase 3 sub-skills (Jetpack Compose-specific) |
+| `pipeline/skills/figma-common/` | 27 | Platform-agnostic helpers (iterate / commit / wiki setup / MCP auth / performance harness / etc.) |
+
+Both Claude Code and Copilot CLI MUST expose every skill with identical argument shape, identical progress-line emission, and identical state writes. Inventory divergence (skill exists on one side but not the other) is a contract violation and blocks merge.
+
+**iOS and Android parallel set** (same 5 skill names under each platform dir):
+
+| Skill | Scope | iOS path | Android path |
+|---|---|---|---|
+| `figma-to-component` | Orchestrator (3.0–3.8) | `pipeline/skills/figma-ios/figma-to-component/` | `pipeline/skills/figma-android/figma-to-component/` |
+| `figma-component-implement` | 3.4 code gen | `pipeline/skills/figma-ios/figma-component-implement/` | `pipeline/skills/figma-android/figma-component-implement/` |
+| `figma-component-test` | 3.5 tests | `pipeline/skills/figma-ios/figma-component-test/` | `pipeline/skills/figma-android/figma-component-test/` |
+| `figma-component-code-connect` | 3.6 mapping publish | `pipeline/skills/figma-ios/figma-component-code-connect/` | `pipeline/skills/figma-android/figma-component-code-connect/` |
+| `figma-component-wiki` | 3.7 wiki (4 adapters) | `pipeline/skills/figma-ios/figma-component-wiki/` | `pipeline/skills/figma-android/figma-component-wiki/` |
+
+**Common pool** (all 27 skills under `pipeline/skills/figma-common/` — platform-agnostic, dispatched regardless of iOS/Android):
+
+| Skill | Scope |
+|---|---|
+| `figma-component-start` | Issue → branches |
+| `figma-component-confluence-sync` | 7b confluence XHTML |
+| `figma-component-status-update` | Confluence dashboard refresh |
+| `figma-commit` | 14-item review + PR |
+| `figma-iteration-commit` | Iteration/develop commit |
+| `figma-issue` | Issue + Jira auto-create |
+| `figma-iterate` | Auto batch loop |
+| `figma-cli-iterate` | CLI iterate (all phases) |
+| `figma-cli-lean-iterate` | CLI iterate (skip test+wiki) |
+| `figma-cli-iterate-mend` | Re-implement discarded |
+| `figma-cli-skip` | Mark skipped |
+| `figma-fix` | Targeted bug fix |
+| `figma-mend` | Re-implement from scratch |
+| `figma-review` | Interactive review |
+| `figma-validate` | Pre-impl validation |
+| `figma-setup` | Env wizard |
+| `figma-remote-mcp-auth` | Figma MCP OAuth |
+| `figma-ui-patterns` | Pattern index |
+| `figma-utility` | Figma data fetch |
+| `figma-skip` | Skip + update Confluence |
+| `figma-form-integration` | Form protocol adapter |
+| `figma-price-integration` | Price protocol adapter |
+| `performance-start` | Perf-tracked component start |
+| `performance-swiftui` | Perf-optimized pipeline |
+| `performance-tour` | Batch produce components |
+| `performance-review-next` | Interactive batch review |
+| `performance-iteration-commit-all` | Batch validate + push all |
+
+Total figma skill count: **37** (5 iOS + 5 Android + 27 Common).
+
+### 1.2 Store-compliance skills
+
+Two parallel shared/core skills under `pipeline/skills/shared/core/` wrap external tooling for pre-submission store compliance:
+
+| Skill | Path | Tool wrapper | Rules |
+|---|---|---|---|
+| `apple-archive-compliance` | `pipeline/skills/shared/core/apple-archive-compliance/` | `ios_app_store_audit` MCP tool (in `@mmerterden/dev-toolkit-mcp` ≥ v2.4) | 17 (Apple ITMS + App Store Review Guidelines) |
+| `google-play-compliance` | `pipeline/skills/shared/core/google-play-compliance/` | bundletool + aapt2 + apksigner | 21 (4 categories: Technical / Security / Privacy / Hygiene) |
+
+Both skills are wired to 4 consumers: `/multi-agent:test "store-ready"` (primary), Phase 4 Security Auditor (`pipeline/agents/security-auditor.md`), `/multi-agent:review` + SKILL.md counterpart, `/multi-agent:channels` PR-body auto-augmentation. Contract enforced by `smoke-compliance-skills.sh` (46 assertions).
+
+### 1.2 Figma-skill routing from multi-agent
+
+Multi-agent Phase 3 resolves the orchestrator via `figmaConfig.project.platform`:
+
+- `"ios"` → `pipeline/skills/figma-ios/figma-to-component/SKILL.md`
+- `"android"` → `pipeline/skills/figma-android/figma-to-component/SKILL.md`
+- anything else → halt with a clear error
+
+Resolution logic MUST be byte-identical across CLIs. The full routing contract lives in `refs/component-dispatch.md`.
+
+### 1.3 Figma skill frontmatter MUST carry (platform-specific skills only)
+
+- `name` matching the directory name
+- `status: wip-v5` (or `stable`/`deprecated` once released)
+- `sourced-from: upstream/<orig>` or `sourced-from: derived-from/<peer-path>` for platform-specific peers
+- `platform: ios` or `platform: android` when the skill is platform-specific
+
+Enforced by `smoke-figma-skill-import.sh` (iOS), `smoke-figma-android-parity.sh` (Android), `smoke-cross-cli-behavior.sh` (cross-platform inventory parity).
+
+---
+
+## 2. Canonical Placeholder Vocabulary
+
+**Problem we prevent**: same concept referenced with different placeholder names in Claude vs Copilot files (e.g., `{github-username}` vs `{owner}`). Every new command must pull from this table.
+
+### 2.1 Identity / account placeholders
+
+| Placeholder | Meaning | Example real value |
+|---|---|---|
+| `{owner}` | Public GitHub org/user owning the pipeline repo | `mmerterden` |
+| `{npm-scope}` | npm scope for publishing | `@mmerterden` |
+| `${USER}` | Local OS username, used for per-user keychain keys | `alice` |
+| `{author-name}` | Git author name (comes from preferences.identities[].name) | `Full Name` |
+| `{author-email}` | Git author email | `foo@example.com` |
+
+### 2.2 Host / URL placeholders
+
+| Placeholder | Meaning | Example |
+|---|---|---|
+| `{jira-host}` | Jira server hostname | `jira.company.com` |
+| `{bitbucket-host}` | Bitbucket server hostname | `bitbucket.company.com` |
+| `{confluence-host}` | Confluence server hostname | `confluence.company.com` |
+| `{corp-domain}` | Corporate email domain | `company.com` |
+| `{website-host}` | Public website hostname | `company.dev` |
+
+### 2.3 Project name placeholders
+
+Use these specific names (from the Copilot set) — **never invent new ones**. They correspond to realistic example project types.
+
+| Placeholder | Represents |
+|---|---|
+| `my-ios-app` | An iOS native project |
+| `my-figma-app` | A figma-driven SwiftUI component project |
+| `my-ui-components` | A UI component library (cross-platform possible) |
+
+### 2.4 Task / tracker placeholders
+
+| Placeholder | Meaning |
+|---|---|
+| `{JIRA_KEY}` | Jira project key (e.g., `PROJ`, `MOBILE`) |
+| `PROJ-12345` | Example Jira issue (placeholder, always use `PROJ-12345` for examples) |
+| `#N` | GitHub issue number placeholder |
+
+### 2.5 Deprecated placeholders (DO NOT USE)
+
+Legacy names found during the v3.7 audit — replaced per this contract.
+
+| Deprecated | Replace with | Reason |
+|---|---|---|
+| `{github-username}` | `{owner}` | Shorter, consistent with `{owner}` pattern |
+| `{website-repo}` | `website` (literal, since the repo name IS "website" under `{owner}`) | Hardcoding the repo name inside `{owner}` scope is fine |
+| `{your-website}` | `{website-host}` | Match `{*-host}` convention |
+| `mmerterden` (hardcoded in examples) | `{owner}` | Personal handle, public but must be a placeholder in generic docs |
+| `my-project`, `my-figma-project`, `my-mobile-app` | `my-ui-components`, `my-figma-app`, `my-ios-app` | Canonical project names per 2.3 |
+
+---
+
+## 2.6 Intentional structural divergence — `multi-agent.md` vs `multi-agent/SKILL.md`
+
+The top-level orchestrator has two deliberately different shapes on the two CLIs. This is **not drift** — it reflects a real capability gap between the host CLIs, and auditors must not flag it as a parity violation.
+
+| Surface | File | Shape | Why |
+|---|---|---|---|
+| Claude Code (colon-form) | `pipeline/commands/multi-agent.md` | ~300 lines — thin dispatcher that routes to `refs/phases/phase-N-*.md` on demand | Claude Code supports lazy-loaded reference files (`@refs/phases/...`), so only the active phase's docs enter the context window. Saves tokens. |
+| Copilot CLI (dash-form) | `pipeline/skills/shared/core/multi-agent/SKILL.md` | ~830 lines — full inline orchestrator with all 8 phase specs embedded | Copilot CLI loads the whole SKILL.md into context once the skill is dispatched; it doesn't have an equivalent of Claude's ref-file loading pattern. Embedding keeps behavior identical without relying on a feature Copilot lacks. |
+
+**What must stay identical** (byte-level) across the two files:
+
+- Phase canonical labels (Phase 0–7)
+- Input parsing table (Section 5 of this doc)
+- Routing decisions for each input type
+- Placeholder vocabulary (Section 2 of this doc)
+- Mode flag semantics (Section 5 of this doc)
+- Output artifact schemas (Section 6 of this doc)
+
+**What's allowed to differ**:
+
+- File length and section grouping
+- Whether phase docs are inlined vs referenced
+- Language of operational commentary (TR helpers in dash form are OK; key identifiers / commit messages / PR bodies stay English everywhere)
+
+Future changes that break an item in the "stay identical" list must update **both** files in the same commit. `smoke-cross-cli-behavior.sh` enforces the identity-preserving axis (input parsing, routing, output shape); structural differences are left to manual review because enforcing them would require forcing the files to the same shape, which we intentionally don't want.
+
+## 3. Frontmatter Transform Rules (Claude ↔ Copilot)
+
+Each file has a different frontmatter schema. The sync flow transforms between them:
+
+### 3.1 Claude Code — `commands/multi-agent/{cmd}.md`
+
+```yaml
+---
+description: "<one-line purpose>"
+allowed-tools: <comma-separated tool list>
+---
+```
+
+### 3.2 Copilot CLI — `skills/multi-agent-{cmd}/SKILL.md`
+
+```yaml
+---
+name: multi-agent-{cmd}
+description: "<one-line purpose>"
+user-invocable: true
+argument-hint: "<input hint>"
+---
+```
+
+### 3.3 Transform Contract
+
+| Direction | Action |
+|---|---|
+| Claude → Copilot | Add `name`, `user-invocable: true`, `argument-hint`; remove `allowed-tools`; may optionally translate `description` into Turkish (existing pattern) |
+| Copilot → Claude | Remove `name`, `user-invocable`, `argument-hint`; add `allowed-tools` (inferred from command's actual tool calls) |
+
+**Invariant**: the `description` field, after potential translation, must have the same meaning on both sides. Translation is allowed; semantic drift is not.
+
+---
+
+## 4. Progress Signalling Parity
+
+### 4.1 TaskCreate ↔ phase-tracker.sh
+
+| Concept | Claude Code | Copilot CLI |
+|---|---|---|
+| Register a phase | `TaskCreate` tool call with subject/description | `phase-tracker.sh add <N> <name>` |
+| Mark a phase in-progress | `TaskUpdate` → `in_progress` | `phase-tracker.sh update <N> in_progress` |
+| Mark a phase complete | `TaskUpdate` → `completed` | `phase-tracker.sh update <N> completed` |
+| Mark a phase failed | `TaskUpdate` → `completed` + log failure in agent-log | `phase-tracker.sh update <N> failed` |
+| Sub-phase progress | TaskCreate with `addBlockedBy` | `phase-tracker.sh sub <N> <sub> <name> <status>` |
+
+### 4.2 Contract
+
+Every phase boundary MUST call EITHER TaskCreate/Update (Claude) OR `phase-tracker.sh` (Copilot). `phase-tracker.sh` is the cross-CLI source of truth (writes to `~/.claude/logs/multi-agent/<task_id>/tracker-state.json`). Claude Code users get BOTH: TaskCreate tiles AND tracker state.
+
+### 4.3 Banner Parity
+
+`phase-banner.sh` runs on both CLIs. Same output format, no Claude-only or Copilot-only flair.
+
+---
+
+## 5. Argument Parsing Invariants
+
+Given the same user input, both CLIs must produce identical parsed state:
+
+| Input pattern | Parsed as |
+|---|---|
+| `PROJ-12345` (bare Jira ID) | `input.type = "jira-id"`, `input.jiraId = "PROJ-12345"` |
+| `https://{jira-host}/browse/PROJ-12345` | `input.type = "jira-url"`, `input.jiraId = "PROJ-12345"` |
+| `https://github.com/{owner}/{repo}/issues/42` | `input.type = "github-issue-url"`, `input.issueNo = 42`, `input.owner = "{owner}"`, `input.repo = "{repo}"` |
+| `#42` or bare `42` | `input.type = "github-issue-number"`, `input.issueNo = 42` |
+| Any other string | `input.type = "free-text"`, `input.summary = <string>` |
+
+Modifier flags are orthogonal and compose:
+- `autopilot` — skip confirmations
+- `--dev` — init → dev → commit → report only
+- `--local` — no worktree
+- Combinations: `--dev autopilot`, `--dev --local`, etc.
+
+---
+
+## 6. Output Format Expectations
+
+| Artifact | Both CLIs must produce |
+|---|---|
+| `agent-state.json` | Same JSON schema (see `~/.claude/schemas/agent-state.schema.json`); same field names; same values for identical input |
+| `agent-log.md` | Same section order, same phase headers (`📊 Phase 1`, `🧠 Phase 2`, etc.), same timeline columns |
+| PR body | Same template; no CLI-specific headers |
+| Jira comment | Same template; real newlines (no literal `\n`); no HTML entities (no `&amp;` / `&lt;` / `&quot;`) |
+| Commit messages | Format `{type}(scope): description [{JIRA_KEY}-{id}]`; identical on both CLIs (see `~/.claude/rules/git-conventions.md`) |
+
+---
+
+## 7. Platform Guards (macOS / Linux / WSL)
+
+Commands invoked via Copilot CLI may run on Linux or WSL. Claude Code currently macOS-only. Shell code in `pipeline/skills/figma-common/` command files must be portable.
+
+For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` on Copilot installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic — no per-OS branching needed.
+
+| Purpose | Canonical (cross-platform) | Underlying backend (for reference / debugging) |
+|---|---|---|
+| Keychain read | `~/.claude/lib/credential-store.sh get <key>` | macOS: `security find-generic-password -a "$USER" -s <key> -w` · Linux: `secret-tool lookup account "$USER" service <key>` · Windows: PowerShell `Get-StoredCredential` |
+| Keychain write | `~/.claude/lib/credential-store.sh set <key> <value>` (or `keychain.py set <key> -` to stream the secret over stdin) | macOS: `security add-generic-password -a "$USER" -s <key> -w "$VAL"` · Linux: `secret-tool store --label=<key> account "$USER" service <key>` · Windows: `New-StoredCredential` |
+| Clipboard read | — (still needs a per-platform branch — there is no helper) | `pbpaste` (macOS) · `wl-paste` (Wayland) · `xclip -selection clipboard -o` (X11) |
+| Clipboard clear | — | `pbcopy < /dev/null` (macOS) · `printf '' \| wl-copy` (Wayland) · `printf '' \| xclip -selection clipboard` (X11) |
+
+For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; then ...; elif command -v wl-paste ...; elif command -v xclip ...; fi`. A future `pipeline/lib/clipboard.sh` could absorb that pattern; until it exists, keep the inline guard in figma skill bash blocks.
+
+---
+
+## 8. Enforcement
+
+This contract is validated by:
+
+- `smoke-cross-cli-behavior.sh` — asserts all 29 commands behave identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 6-persona agent deployment
+- `smoke-commands-skills-parity.sh` (50 assertions) — enforces colon-form command ↔ dash-form skill directory parity
+- `smoke-compliance-skills.sh` (45 assertions) — enforces store-compliance skill catalog + 4 consumer wiring
+- `smoke-personal-data.sh` — extended in 0.5.5 to treat deprecated placeholders (`{github-username}`, `{your-website}`, `{website-repo}`) as leaks; adds `mmerterden` to public-handle blocklist for generic docs
+- `pre-push-check.sh` — runs both smoke tests before any push that touches `pipeline/skills/figma-common/` commands
+- `sync.md` (Section 2 REPO step) — genericization lookup table MUST match Section 2 of this contract
+
+---
+
+## 9. Change Control
+
+To change anything in this contract:
+
+1. Amend this file with rationale
+2. Update `sync.md` genericization table (if Section 2 changes)
+3. Update `smoke-cross-cli-behavior.sh` fixtures (if Section 5/6 changes)
+4. Run `smoke-cross-cli-behavior.sh` and `smoke-personal-data.sh` locally — both must pass
+5. Announce in pipeline repo `CHANGELOG.md` under `## [Unreleased]` → `### Contract`
+
+No silent changes. No exceptions.