@mmerterden/multi-agent-pipeline 14.1.1 → 14.2.2

package/docs/ecosystem.md

@@ -0,0 +1,237 @@
+# Ecosystem: Pipeline × Marketplace Plugins × Dev-Toolkit MCP
+
+This pipeline is not one repo. It's three, each owned separately, each versioned
+separately, wired together at install time and at run time:
+
+| Repo | What it owns | Ships as |
+|---|---|---|
+| **`multi-agent-pipeline`** (this repo) | Orchestration: the 8-phase flow, the 49 slash commands, quality gates, review/triage, cross-CLI parity | npm package (`@mmerterden/multi-agent-pipeline`), installs itself onto Claude Code / Copilot CLI / Codex CLI |
+| **`multi-agent-plugins`** | Stack knowledge: per-platform component/lifecycle skills (iOS, Android, Frontend, Backend) + shared knowledge | Claude Code marketplace, 5 independently-versioned plugins |
+| **`dev-toolkit-mcp`** | The pipeline's hands on devices and browsers: 80 MCP tools across 6 categories (simulator/emulator control, accessibility audit, store compliance, web automation, Figma-vs-mock design audit, an agent-DSL batch runner) | npm package, registered as a standard stdio MCP server on every host |
+
+None of the three depends on the others at the code level. They compose through two
+narrow contracts: the **Skill tool** (pipeline → plugin, at Phase 3) and the **MCP
+protocol** (pipeline skills → dev-toolkit, at Phase 5 / design-check / store-ready).
+Either can be swapped or removed without touching the other two's source.
+
+```mermaid
+graph LR
+    subgraph PIPE ["multi-agent-pipeline (orchestrator)"]
+        direction TB
+        PHASES["8 phases · 49 commands"]
+        GATES["deterministic gates + review triage"]
+    end
+
+    subgraph PLUG ["multi-agent-plugins (stack knowledge)"]
+        direction TB
+        IOSP["ai-ios-engineering-toolkit"]
+        ANDP["ai-android-engineering-toolkit"]
+        FEP["ai-frontend-engineering-toolkit"]
+        BEP["ai-backend-toolkit"]
+        COMP["ai-common-engineering-toolkit"]
+    end
+
+    subgraph DTK ["dev-toolkit-mcp (device/browser hands)"]
+        direction TB
+        DEV["Device Control (58)"]
+        A11Y["Accessibility Audit (2)"]
+        STORE["Store Compliance (5)"]
+        WEB["Web Automation (8)"]
+        DESIGN["Design Audit (6)"]
+        AGENTDSL["Agent DSL (1)"]
+    end
+
+    PHASES -->|"Phase 3: Skill tool<br/>taskType===component"| PLUG
+    PHASES -->|"Phase 5 / design-check /<br/>store-ready: MCP tool calls"| DTK
+    GATES -.->|"Phase 4 Security Auditor"| STORE
+
+    style PIPE fill:#ffd,stroke:#333
+    style PLUG fill:#dfd,stroke:#333
+    style DTK fill:#dff,stroke:#333
+```
+
+---
+
+## 1. Authoring flow: one source of truth, five sync targets
+
+`~/.claude/` on the maintainer's machine is authoritative. Everything else is a
+derived, synced, or independently-shipped artifact. `/multi-agent:sync` is the one
+command that walks all five targets in order, detects which are stale, and updates
+only those:
+
+```mermaid
+graph TD
+    CC["Claude Code<br/>~/.claude/commands/multi-agent/<br/>(source of truth)"]
+
+    CC -->|"Step 2: copy + reformat<br/>49 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
+    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 49 refs<br/>+ 8 agent TOML"]
+    CC -->|"Step 3: genericize<br/>(strip personal data)"| REPO["multi-agent-pipeline repo<br/>pipeline/"]
+    CC -->|"Step 4: version + feature sync"| WEB["Website<br/>projects.ts / i18n.tsx"]
+
+    REPO -->|"Step 3c: build-stack-plugins.mjs<br/>rebuilds knowledge/ from<br/>shared/external"| PLUGREPO["multi-agent-plugins repo<br/>(5 stack plugins)"]
+
+    DTK2["dev-toolkit-mcp repo<br/>(own codebase, own gates,<br/>NOT generated from Claude)"]
+    SYNC3D["Step 3d: detect movement →<br/>gate → commit → publish"]
+    CC -.->|"sync only SHIPS this,<br/>never authors it"| SYNC3D
+    SYNC3D -.-> DTK2
+
+    REPO -->|"npm publish"| NPM["GitHub Packages"]
+    WEB -->|"git push → auto-deploy"| VERCEL["Vercel"]
+    PLUGREPO -->|"git push"| MKT["Claude Code marketplace"]
+    DTK2 -->|"npm publish"| NPM2["GitHub Packages<br/>(private)"]
+
+    style CC fill:#f9f,stroke:#333
+    style DTK2 fill:#dff,stroke:#333,stroke-dasharray: 5 5
+```
+
+**Why `dev-toolkit-mcp` is drawn differently.** The other four targets are *derived*
+from the Claude Code source — sync writes their content. `dev-toolkit-mcp` is not:
+it's a separate codebase developed on its own schedule. Sync's Step 3d only
+*detects* whether it moved (dirty tree, unpushed commits, untagged version), runs
+**its own** gate suite, and ships it — commit, tag, `npm publish`. If the pipeline
+needs a tool that toolkit doesn't have yet, that's a two-repo change: add the tool
+in `dev-toolkit-mcp`, ship it, then bump the minimum version pin back in
+`cross-cli-contract.md` (see §4).
+
+**Also not generated: the plugins' own authored skills.** `build-stack-plugins.mjs`
+only rebuilds each plugin's `knowledge/` folder from `pipeline/skills/shared/external/`.
+The plugins' lifecycle skills — `create-component`, `evolve-component`,
+`figma-utility`, `code-connect`, `branch-and-pr`, `fix-bug`, and the rest — are
+hand-authored *inside* `multi-agent-plugins` and are never touched by sync.
+
+---
+
+## 2. Plugin marketplace build: one authoring source, five versioned artifacts
+
+```mermaid
+graph TD
+    EXT["pipeline/skills/shared/external/<br/>150 skills — single authoring source<br/>(the pipeline's own phases read these too)"]
+
+    EXT -->|"cross-stack skills"| COMMONP["ai-common-engineering-toolkit<br/>10 skills · v0.2.3"]
+    EXT -->|"Apple/Xcode-only"| IOSP["ai-ios-engineering-toolkit<br/>145 skills · v0.6.0"]
+    EXT -->|"Android/Kotlin-only"| ANDP["ai-android-engineering-toolkit<br/>29 skills · v0.1.3"]
+    EXT -->|"backend-only"| BEP["ai-backend-toolkit<br/>32 skills · v0.1.4"]
+    EXT -->|"web/frontend-only"| FEP["ai-frontend-engineering-toolkit<br/>24 skills · v0.1.3"]
+
+    COMMONP --> BUMP{"skill set<br/>changed?"}
+    IOSP --> BUMP
+    ANDP --> BUMP
+    BEP --> BUMP
+    FEP --> BUMP
+    BUMP -->|yes| PATCH["bump that plugin's<br/>patch version"]
+    BUMP -->|no| SKIP["idempotent no-op"]
+
+    PATCH --> CONSUMER["/multi-agent:update<br/>→ claude marketplace update multi-agent-plugins"]
+
+    style EXT fill:#ffd,stroke:#333
+```
+
+A skill counted in more than one platform plugin (a cross-stack knowledge skill
+plus, say, an iOS-specific one) is why the plugins' skill counts sum to more than
+the 150-skill source: `ai-common` skills are vendored into every stack plugin's
+`knowledge/`, not deduplicated across them. Versioning is per-plugin and
+patch-only from this generator — a repo enabling only `ai-ios-engineering-toolkit`
+never pulls an Android-only change.
+
+**Consumption is pull, not push.** A consumer repo enables a stack plugin once
+(`/multi-agent:stack ios`, writing the enabled-plugins list into
+`.claude/settings.json`) and picks up new plugin versions only when it runs
+`/multi-agent:update`, which calls `claude marketplace update multi-agent-plugins`.
+Publishing a new plugin version does not retroactively change anything already
+running in a consumer's session.
+
+---
+
+## 3. Per-host delivery: the same three repos, three different shapes
+
+The three repos land differently on each host, because each host's skill-loading
+behavior is different (see `pipeline/multi-agent-refs/cross-cli-contract.md` for the
+measurements behind this table):
+
+| | Claude Code | Copilot CLI | Codex CLI |
+|---|---|---|---|
+| **Pipeline commands** | 49 slash-command skills, native | 49 skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 49 command specs as reference files — Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
+| **Stack plugins** | Marketplace plugin, loaded natively, resolved by `.claude/settings.json` enabled-list | Enabled plugin's authored skills copied flat into `~/.copilot/skills/`; `knowledge/` **not** re-copied (already delivered via `shared/external`) | Copied as reference files under `~/.codex/multi-agent-refs/skills/`, plugin-prefixed on name clash (e.g. `architecture` → `ai-ios-engineering-toolkit-architecture`) |
+| **Component dispatch (Phase 3)** | Marketplace plugin's `create-component`/`create-screen` skill via the Skill tool | No plugin loader — falls back to local frozen `figma-*` skill copies | Not part of the enforced parity axis; classification + state-shape must match, skill *inventory* does not |
+| **dev-toolkit-mcp** | `claude mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp` | `copilot mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp` | `codex mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp` (skipped with a warning if `codex` isn't on `PATH`) |
+
+`smoke-cross-cli-behavior.sh` and `smoke-codex-install.sh` gate the axes that **do**
+have to match (phase labels, placeholder vocabulary, output schemas, command↔skill
+parity count); the table above marks the axes that are allowed to diverge by design.
+
+---
+
+## 4. Runtime: what actually happens during a task
+
+Two independent hand-offs happen inside a single pipeline run, neither aware of the
+other:
+
+```mermaid
+graph TD
+    START["Task running: Phase 3 (Dev)"]
+    START -->|"taskType !== component"| TDD["Standard TDD loop<br/>(pipeline's own code)"]
+    START -->|"taskType === component<br/>+ figmaUrl present"| VALIDATE["ai-ios-engineering-toolkit:figma-validate<br/>(registry, Code Connect, token compliance)"]
+    VALIDATE -->|pass| DISPATCH["Skill tool →<br/>create-component / create-screen<br/>/ evolve-component (dual-name fallback)"]
+    VALIDATE -->|fail| HALT1["halt Phase 3, surface why"]
+    DISPATCH --> REPORT1["plugin returns build/test status →<br/>dispatch layer writes state.phases['3'].subphases[]"]
+
+    REPORT1 --> P4["Phase 4: Review"]
+    P4 --> P5["Phase 5: Test"]
+
+    P5 -->|"UI bug hunt / manual-test /<br/>design-check / store-ready"| MCP["MCP tool call over stdio<br/>e.g. ios_xcodebuild, design_visual_compare,<br/>ios_app_store_audit"]
+    MCP --> DTKPROC["dev-toolkit-mcp process<br/>(npx @mmerterden/dev-toolkit-mcp)"]
+    DTKPROC -->|"result: screenshot / xcresult ID /<br/>18-rule audit verdict"| P5
+
+    style DISPATCH fill:#dfd,stroke:#333
+    style MCP fill:#dff,stroke:#333
+    style HALT1 fill:#fdd,stroke:#333
+```
+
+**Phase 3 → plugin** is a one-shot delegation: the plugin skill does its own
+lifecycle (test → code → build → wiki) and reports back a coarse
+`component-build` result; the pipeline does not re-implement any of that logic, and
+a plugin failure counts against the pipeline's own retry cap (`retryCount === 3` →
+hard stop, per `component-dispatch.md`).
+
+**Phase 5 (and design-check / store-ready) → dev-toolkit** is a long-lived MCP
+session, not a one-shot call: the same stdio server process answers many tool
+calls across a phase (boot simulator once, then screenshot/tap/screenshot/tap...).
+Several pipeline skills pin a **minimum toolkit version** for a specific tool —
+e.g. `apple-archive-compliance` requires `ios_app_store_audit` from
+`dev-toolkit-mcp ≥ v2.9.0` — enforced in `cross-cli-contract.md` and checked by
+`/multi-agent:sync` Step 3d before any dev-toolkit release ships (a version bump
+that drops or renames a tool a pipeline skill depends on is a **major** bump, by
+that step's own contract).
+
+### dev-toolkit-mcp's 80 tools, by category
+
+| Category | Tools | Primary pipeline consumers |
+|---|---|---|
+| Device Control | 58 | `/multi-agent:test`, `test-dark-mode`, `test-accessibility`, `test-dynamic-type`, `test-screenshots`, `manual-test`, `design-check` |
+| Accessibility Audit | 2 | `test-accessibility` |
+| Store Compliance | 5 | `store-ready`, `testflight-validation`, `apple-archive-compliance` skill, Phase 4 Security Auditor |
+| Web Automation | 8 | frontend-stack UI testing (via `test`) |
+| Design Audit | 6 | `design-check` (mock-mode vs Figma conformance) |
+| Autonomous Agent DSL | 1 | any skill that needs a scripted multi-step device flow in one round trip |
+
+---
+
+## 5. Why the boundary is drawn where it is
+
+- **Pipeline ↔ plugins boundary = Skill tool, one direction.** The pipeline
+  classifies (`taskType`, `componentScope`) and tracks state; it never reads or
+  writes plugin-internal files. This is why a corporate marketplace can ship a
+  same-named plugin (`ai-ios-engineering-toolkit:create-ui-component` vs the public
+  `create-component`) and dispatch still resolves correctly — the dual-name
+  fallback lives in the pipeline, the implementation stays entirely in whichever
+  plugin is enabled.
+- **Pipeline ↔ dev-toolkit boundary = MCP protocol, versioned contract.** The
+  pipeline never shells out to `xcrun simctl` or `adb` directly; every device/browser
+  action is a declared MCP tool call with a minimum-version pin. That's what lets
+  `dev-toolkit-mcp` ship on its own release cadence (its own gates, its own
+  `npm publish`) without a pipeline release, as long as pinned tools keep their
+  contract.
+- **Neither boundary is symmetric.** The pipeline depends on both other repos being
+  present *for specific task types* (component work, UI testing) but functions
+  without either — a non-component bugfix task never touches the plugin marketplace,
+  and a task with no UI-testing step never opens the MCP connection.

package/install/_plugin-skills.mjs

@@ -24,9 +24,12 @@
  * @module install/_plugin-skills
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 import { join } from "path";
 
+/** Uninstall reads this to know exactly which delivered skill dirs are ours to remove. */
+export const PLUGIN_SKILLS_MANIFEST = ".plugin-skills-manifest.json";
+
 import { copyDir, countFiles, ensureDir, ensureRealDir, isDryRun, wipeDir } from "./_common.mjs";
 
 /** Subtrees a plugin authors itself. `knowledge/` is generated, so it is excluded. */
@@ -254,7 +257,18 @@ export function installAuthoredPluginSkills(opts) {
         `clone {owner}/multi-agent-plugins or enable them in Claude Code to deliver their skills`,
     );
   }
-  return { copied, collided, renamed, plugins, missing, selectionSource };
+  // Uninstall has no way to know which of ~100 flat skill dirs came from a
+  // plugin delivery pass rather than the pipeline's own PIPELINE_CORE_SKILL_DIRS
+  // allowlist - it silently left all of them behind. Persist exactly the names
+  // this pass delivered so uninstall can remove precisely those, nothing more.
+  if (!isDryRun()) {
+    try {
+      writeFileSync(join(dest, PLUGIN_SKILLS_MANIFEST), JSON.stringify([...delivered], null, 2) + "\n");
+    } catch {
+      /* best-effort - a missing manifest just means uninstall skips this cleanup */
+    }
+  }
+  return { copied, collided, renamed, plugins, missing, selectionSource, deliveredNames: [...delivered] };
 }
 
 /**

package/install/codex.mjs

@@ -10,7 +10,7 @@
  * name + description into a single prompt block and silently drops entries once
  * that block overflows - measured at install-design time, one 142-skill plugin
  * surfaced only 75 of its skills AND evicted an unrelated user skill. So the
- * pipeline contributes exactly one skill (`multi-agent`) and keeps its 42
+ * pipeline contributes exactly one skill (`multi-agent`) and keeps its
  * sub-command specs as reference files that cost nothing until read. Converting
  * them into peer skills would silently lose pipeline commands.
  *
@@ -230,7 +230,12 @@ function installRouterSkill(pipelineSrc, skillsDir) {
   const dest = join(skillsDir, "multi-agent");
   ensureDir(dest);
   writeFile(join(dest, "SKILL.md"), skill);
-  console.log(`    -> 1 router skill written to ${dest} (42 command specs stay as refs)`);
+
+  const commandsDir = join(pipelineSrc, "commands", "multi-agent");
+  const specCount = existsSync(commandsDir)
+    ? readdirSync(commandsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length
+    : 0;
+  console.log(`    -> 1 router skill written to ${dest} (${specCount} command specs stay as refs)`);
 }
 
 /**
@@ -279,10 +284,10 @@ function installRefs(pipelineSrc, dest) {
   let count = 0;
   if (existsSync(refsSrc)) count += copyTreeRewritten(refsSrc, dest);
 
-  // The 42 sub-command specs. Skip ONLY the top-level dispatcher SKILL.md -
+  // The sub-command specs. Skip ONLY the top-level dispatcher SKILL.md -
   // it already shipped as the router skill. The filter is on the path relative
   // to the copy root, not the basename: every sub-command spec is itself named
-  // SKILL.md, so a basename filter would copy 42 empty directories and leave
+  // SKILL.md, so a basename filter would copy N empty directories and leave
   // the orchestrator with nothing to read.
   if (existsSync(commandsSrc)) {
     count += copyTreeRewritten(commandsSrc, join(dest, "commands"), (rel) => rel !== "SKILL.md");

package/install/templates/copilot-instructions.md

@@ -33,17 +33,20 @@
 - **Fast + Local (multi-agent-dev-local)**: Dev on current branch - no worktree
 - **Fastest + Local (multi-agent-dev-local-autopilot)**: Dev + autopilot, no worktree
 
-## Prompt Language (en/tr)
+## Language axes (en/tr)
 
-The pipeline honors `prefs.global.promptLanguage` (set via `/multi-agent:setup` or
-`/multi-agent:language en|tr`). This controls the language of **interactive prompts
-only** - e.g. the Phase 6 pre-commit local-checkout test prompt, Plan Approval Gate
-questions, multi-repo branch picker labels, and phase-banner.sh banners (when
-PHASE_LANG env is unset, it auto-reads prefs).
+Two prefs, two jobs - the full matrix lives in `multi-agent-refs/rules.md`
+"Language Application" and that file wins on any disagreement:
 
-Default: `en`. Supported: `en`, `tr`. Commit messages, PR bodies, Jira comments,
-and any external-facing payload **always stay in English** regardless of this
-setting - only the user-facing prompts change.
+- `prefs.global.promptLanguage` is **locked to `en`**: every LLM-facing prompt,
+  spec file and instruction stays English.
+- `prefs.global.outputLanguage` (set via `/multi-agent:setup` or
+  `/multi-agent:language en|tr`) drives what humans read: interactive prompts,
+  phase banners, AND the external payload **bodies** - PR description, Jira
+  comment, Confluence/Wiki pages all render in it.
+
+Always English regardless of either pref: commit messages, branch names, PR
+titles, code identifiers, file paths, and `AskUserQuestion` label/header.
 
 When writing TR prompts, use the same keyword/menu numbers as EN (e.g. `[1-4]`)
 so the user's input pattern stays language-agnostic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "14.1.1",
+  "version": "14.2.2",
   "description": "8-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/commands/deploy.md

@@ -43,7 +43,10 @@ Run through the iOS deployment checklist before App Store submission.
 ### 6. Archive & Upload
 
 - [ ] Archive with Release configuration
-- [ ] Run App Store compliance scan: `/archive-guard <archive>` (uses `ios_app_store_audit` MCP tool)
+- [ ] Run pre-submission validation: `/multi-agent:store-ready --archive=<archive>`  -  three gates
+      (static audit, Apple's own `altool --validate-app`, guideline review vs source).
+      `/archive-guard <archive>` is the quick single-gate form when only the static
+      audit is wanted.
 - [ ] Upload via Xcode Organizer or `xcrun altool`
 - [ ] Verify in App Store Connect
 

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

@@ -12,7 +12,7 @@ Parse the user input and route to the correct sub-command.
 
 **Input**: $ARGUMENTS
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` from `$HOME/.claude/multi-agent-preferences.json` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` from `$HOME/.claude/multi-agent-preferences.json` and render every conversational line in it. `AskUserQuestion` `label`/`header` stay English, but its `question` and option `description`s render in `outputLanguage`; external payload bodies follow `outputLanguage` too (identifiers, commit messages, branch names stay English). Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 ## Canonical Invocation (per CLI)
 
@@ -72,7 +72,7 @@ Lib scripts (`~/.claude/lib/`):
 | `log [id]` | Show task log |
 | `resume [id]` | Resume paused task |
 | `kill [id]` | Delete worktree (logs preserved). Confirm first |
-| `clear-logs` | Clean global log directory. Keep counter |
+| `clear-logs` | **Superseded  -  redirect, do not run.** Say so and route to `prune-logs`. It targeted `.worktrees/PROJ-*/agent-log.md`, a path nothing has written to since logs moved to `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`; running it would report deleting nothing as success. |
 | `purge` | Worktree + logs + counter  -  full reset (double confirm) |
 | `review [#N\|repo#N\|PR-url\|branch]` | Parallel review of a PR or branch diff; with no input (interactive) lists open GitHub + Bitbucket PRs to multi-select. Posts per-finding inline comments + approve/needs-work on PRs. No worktree. |
 | `review-jira [KEY\|url]` | Grade a Jira issue's readiness for the pipeline (scope / AC / repro / design / API / stack), then post the gaps as a Jira comment. Read-only on code. |
@@ -82,6 +82,8 @@ Lib scripts (`~/.claude/lib/`):
 | `channels [PR-url\|#N\|Jira-url\|Jira-id] [--channels pr,jira,confluence,wiki] [--content normal,test,auto-diff,note] [--message "..."]` | Post task report to multi-select channels (PR description, Jira comment, Confluence page, Wiki pages) with multi-select content sources. Humanizer pass per-channel. Bitbucket PR updates use reviewer-preserving PUT. Phase 7 delegates to this command; also invocable post-hoc for fixes made outside the pipeline. No worktree. |
 | `create-jira ["desc"] [figma-url] [swagger-url]` | Create a standards-compliant Jira issue: asks the type (**Task** / **Bug** / **Story**), mines the project's recent same-type issues for conventions (summary format, labels, priority, test-scenario style), detects the active sprint, drafts from a standard template with auto-sizing sections (Design Reference / API Contract / Screenshots appear only when their source is given), asks about unknown fields, then full draft preview + explicit approval before create. No worktree, no commits. |
 | `test` or `test [args]` | UI Bug Hunter  -  screenshot + tap + analyze on booted simulator via MCP (read `$HOME/.claude/commands/sim-test.md`). `/multi-agent:test` also resolves here via the `commands/multi-agent/test/SKILL.md` delegate. |
+| `test-dark-mode` · `test-accessibility` · `test-dynamic-type` · `test-screenshots [locale]` | Fixed-scenario aliases for the four parameterless / single-parameter `test` scenarios, so the tag autocompletes instead of having to be quoted. Each delegates to the same `sim-test.md` with its scenario pinned; behaviour is identical to the quoted form, which is not deprecated. |
+| `store-ready [repo] [--archive=\|--ipa=\|--aab=\|--apk=] [--skip-sweep]` | Pre-submission store readiness for a built **package**, iOS and Android, local-only. Three symmetric gates per platform  -  static package audit, the store's own validator, policy review vs repo source  -  plus the running-app sweep as Step A. A skipped gate is never folded into the pass count, and an Android run clears at most 2 of 3 because Play's authoritative check is server-side only. Validates only, never uploads. `testflight-validation` is the iOS-pinned alias; `test "store-ready"` hands off here. |
 | `manual-test [#id]` | Phase 5 standalone Manual Test  -  checks out the task branch, prints Xcode / SourceTree hints, waits for user verdict (`ok` / `fix: ...`). |
 | `design-check [scope]` | Mock-mode vs Figma design audit (iOS / Android, local-only). Pick repo + module → mock-support feasibility gate (halts if unsupported) → **scenario inventory** (every launch arg / scenario case / scenario code / fixture / deep link becomes a countable target with file+line evidence) → scope resolve (empty = module, screen, `screen@variant`, target id, Figma URLs, `--resume`) → worktree Debug build + mock launch → drive EACH target by its own driver, capturing tap-reachable sub-states with it → per-variant pixel + px-spacing + typography + color compare → report (side-by-side + annotated overlay + stacked findings + fix prompt) exported to `~/DesignChecks/` as HTML + PDF (+ Confluence if enabled). **Coverage gate**: a target is audited or skipped with a concrete reason, else the run is reported INCOMPLETE with the missing ids. No commits, no CI. |
 | `stack [ios\|android\|backend\|mobile\|all]` | Swap skills for next conversation. No arg = show current stack. |
@@ -113,7 +115,7 @@ This command uses lazy loading for token efficiency. Read the relevant sub-file
 | `help` | `$HOME/.claude/commands/multi-agent/help/SKILL.md` |
 | `channels` | `$HOME/.claude/commands/multi-agent/channels/SKILL.md` |
 | `sync` | `$HOME/.claude/commands/multi-agent/sync/SKILL.md` |
-| `clear-logs` | Handled inline  -  scan + delete agent-log.md/agent-state.json files |
+| `clear-logs` | Handled inline  -  redirect to `prune-logs`, see the routing note |
 | `review` | `$HOME/.claude/commands/multi-agent/review/SKILL.md` |
 | `review-jira` | `$HOME/.claude/commands/multi-agent/review-jira/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/readiness-review.md`) |
 | `review-issue` | `$HOME/.claude/commands/multi-agent/review-issue/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/readiness-review.md`) |
@@ -136,10 +138,11 @@ This command uses lazy loading for token efficiency. Read the relevant sub-file
 | Token lookup needed | `$HOME/.claude/multi-agent-refs/keychain.md` |
 | Audit tools (Phase 5/6) | `$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** (`--dev`, `--local`, `autopilot`) and **ops** (`status`, `log`, `resume`, `kill`, `clear-logs`, `purge`, `review`) are parsed inline by this file  -  no separate spec files, they compose with the pipeline or do one-shot work.
+**Modifier flags** (`--dev`, `--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.
 
 **How**: After routing, `Read` the relevant file and follow its instructions. Only load what the current action needs.
 
@@ -204,7 +207,7 @@ When the user supplies an ID/URL/free-text:
 2. **Pick account**  -  always asked (autopilot picks default)
 3. **Fetch issue**  -  `lib/issue-fetcher.sh "$INPUT"` (Jira/GitHub fetch + maturity)
 4. **Repo picker**  -  only for `gh-num` (e.g. `316`) when repo is ambiguous, multi-select
-5. **Maturity check**  -  blocker halts (autopilot too), warning prompt/log
+5. **Maturity check**  -  blocker halts (autopilot too), warning prompt/log. For a Jira input specifically, an empty own description with a non-empty parent surfaces as `description_empty_parent_available` (warning, not blocker)  -  ask the tailored parent-description question from `jira/SKILL.md`'s maturity section instead of the generic "Continue?" prompt.
 6. **Dev context**  -  always runs, empty submit allowed
 7. → Interactive Launcher → Phase 0
 

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

@@ -543,7 +543,7 @@ options:
 
 Conditional follow-ups:
 - If `Confluence` selected: ask `header="Parent page"`, free-text via Other for the parent page key or URL. One Confluence page per platform is created under this parent, each titled `<Feature> - <Platform>`.
-- If `Jira` selected: if Step 5 Q4 produced Jira IDs, AskUserQuestion (single-select) to pick which one; otherwise ask via Other. Per Locked decision 9 + design choice "single description with platform separators", the chosen issue receives one combined description body holding all per-platform sections under `## Platform: <X>` headings.
+- If `Jira` selected: if Step 5 Q4 produced Jira IDs, AskUserQuestion (single-select) to pick which one; otherwise ask via Other. Per Locked decision 9 + design choice "single description with platform separators", the chosen issue receives one combined description body holding all per-platform sections under `h2. Platform: <X>` separators (wiki markup  -  the description field does not render Markdown; conversion happens at dispatch, see Phase 4).
 
 Result: `state.analysisSpec.outputs.requested[]`.
 
@@ -565,7 +565,7 @@ Iterate `state.analysisSpec.outputs.requested`. For each target:
 |--------|--------|
 | Local | For each per-platform draft, `cp /tmp/analysis-<feature-slug>-<ts>/<feature>-<platform>.md` into `analysis/<feature>-<platform>.md` in the matching repo's working tree. When multiple repos exist for the same platform, the file is duplicated into each and the dispatch report lists every destination. **No commit.** |
 | Confluence | Re-humanize each per-platform draft with `formal-stakeholder` tone. One Confluence page per platform under the chosen parent, titled `<Feature> - <Platform>`. Cross-link siblings inside each page via `<ac:link><ri:page ri:content-title="<Feature> - <OtherPlatform>"/></ac:link>`. Markdown -> storage XML via `$HOME/.claude/multi-agent-refs/channels/confluence.md`. Re-emit on existing pages uses PUT with version bump. |
-| Jira | Re-humanize the combined body with `informal-technical` tone. Concatenate per-platform drafts under `## Platform: iOS`, `## Platform: Android`, `## Platform: Backend`, `## Platform: Frontend` separators (in the order platforms were selected). PUT the chosen issue's description via `$HOME/.claude/multi-agent-refs/channels/jira.md`. |
+| Jira | Re-humanize the combined body with `informal-technical` tone. Concatenate per-platform drafts under `h2. Platform: iOS`, `h2. Platform: Android`, `h2. Platform: Backend`, `h2. Platform: Frontend` separators (in the order platforms were selected), then run the whole body through the markdown → Jira wiki conversion table in `$HOME/.claude/multi-agent-refs/channels/jira.md`  -  the `description` field renders wiki markup, so raw `##`/`**`/backticks arrive as literal text. Write with `PUT /rest/api/2/issue/{key}` body `{"fields": {"description": <converted body>}}` (`channels/jira.md` documents only the comment POST; the description update is this PUT). Same rawfile + `--data-binary` transport rules. |
 
 **Output capture**: fill `state.analysisSpec.outputs.localPaths[]` (one entry per per-platform-per-repo write), `outputs.confluencePageUrls[]` (one entry per platform), `outputs.jiraIssueKey` (single string).
 

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

@@ -8,7 +8,7 @@ argument-hint: '"task"  -  issue URL, Jira ID, free-text, or #id (for resume)'
 
 **Input**: $ARGUMENTS
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` `label`/`header` stay English, but its `question` and option `description`s render in `outputLanguage`; external payload bodies follow `outputLanguage` too (identifiers, commit messages, branch names stay English). Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 Run the task end-to-end with no confirmations.
 
@@ -49,6 +49,10 @@ Run the task end-to-end with no confirmations.
 2. **Set the autopilot flag**  -  write `"autopilot": true` to `agent-state.json`
 3. **Launch the multi-agent pipeline**  -  every confirmation is skipped
 4. **On error**  -  after 3 failed retries, pause and ask the user
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
+
 ## Required: Phase Tracker Contract
 
 **The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
@@ -72,7 +76,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 
 # After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 ```
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)

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

@@ -138,7 +138,7 @@ Then 3b renders:
 - "Teknik analiz" unselectable if no Phase 2 planning log AND no PR diff available. Reason: `"(no technical source  -  need Phase 2 plan or PR diff)"`.
 - "Auto-diff" unselectable if no PR found. Reason: `"(no PR linked to this target)"`.
 - "Manuel not" always available.
-- "Cost özeti" unselectable if `phase-tracker.sh status <id>` returns no token tallies AND no `otel-spans.jsonl` exists for the task. Reason: `"(no tracker data  -  set MULTI_AGENT_OTEL_SPANS=1 or enable token tracking)"`.
+- "Cost özeti" unselectable if `phase-tracker.sh cost total` prints `-` (no priced token tallies; there is no `status` action) AND no `otel-spans.jsonl` exists for the task. Reason: `"(no tracker data  -  set MULTI_AGENT_OTEL_SPANS=1 or enable token tracking)"`.
 - "Yapılan iş özeti" unselectable if no `agent-state.json` exists for the task (post-hoc call with `--branch` + `--base-branch` flags restores partial availability). Reason: `"(no agent-state.json for {taskId})"`. **Auto-ticked** when Step 3a preview was shown  -  user can still uncheck before confirming the menu.
 
 **Defaults (first run):** PR + Jira ticked, Confluence + Wiki unticked. Content: auto-diff if pipeline log missing; otherwise normal-analiz + test-senaryoları.
@@ -246,7 +246,7 @@ Emitted only when `reportContent.workSummary === true` and at least one of (`age
 2. **Scope delivered**  -  Phase 2 `planTodos[]` / `tasks[]` rendered as `✅` (status=done) or `⏳` (anything else) rows. Task id + title shown; `(deferred  -  rationale)` appended if the task's `status` is `"deferred"`.
 3. **Changed files**  -  `git -C $WORKTREE diff --numstat $baseBranch...HEAD`. Shows `` `path` (+add / -del) `` per row, capped at 20 with a `_... +N more files not shown_` footer when exceeded. Total adds/dels + file count in section header.
 4. **Review outcome**  -  from `reviewConsensus` (pre-v6.1) or `phases["4"].triage`: `{accepted} accepted · {deferred} deferred · {rejected} rejected · approved={bool}`. Hidden entirely when all three buckets are empty (normal for `--dev` / `dev-autopilot` runs that skip Phase 4).
-5. **Phase tick strip**  -  single line from `phase-tracker.json`: `0 Init ✅ · 1 Analysis ✅ · 2 Planning ✅ · 3 Dev ✅ · 4 Review ✅ · 5 Test ⏭ · 6 Commit ✅ · 7 Report ▶`. Marks: `✅` completed · `▶` in_progress · `❌` failed · `⏭` skipped · `·` pending.
+5. **Phase tick strip**  -  single line from the tracker state (`render-work-summary.sh` resolves worktree/artifacts copies, then `$HOME/.claude/logs/multi-agent/{taskId}/tracker-state.json`): `0 Init ✅ · 1 Analysis ✅ · 2 Planning ✅ · 3 Dev ✅ · 4 Review ✅ · 5 Test ⏭ · 6 Commit ✅ · 7 Report ▶`. Marks: `✅` completed · `▶` in_progress · `❌` failed · `⏭` skipped · `·` pending.
 
 **Output template:**
 
@@ -276,7 +276,7 @@ Emitted only when `reportContent.workSummary === true` and at least one of (`age
 
 Emitted only when `reportContent.costSummary === true` and tracker data is available. Source of truth is `phase-tracker.sh`:
 
-1. **Token tallies per phase**  -  read `.worktrees/{taskPath}/phase-tracker.json` (written by `phase-tracker.sh update` / `tokens` actions). If present, each phase row has `{tokens_in, tokens_out}`.
+1. **Token tallies per phase**  -  `render-cost-summary.sh <taskId>` resolves the tracker JSON itself: worktree candidates (`.worktrees/{taskPath}/phase-tracker.json`) first, then the standard location `$HOME/.claude/logs/multi-agent/{taskId}/tracker-state.json` that `phase-tracker.sh` actually writes. Each phase row carries `{tokens_in, tokens_out}`.
 2. **Fallback to OTel spans**  -  if tracker JSON has no token columns but `otel-spans.jsonl` exists (set `MULTI_AGENT_OTEL_SPANS=1` beforehand), aggregate `phase.tokens` spans by phase ID.
 3. **USD estimate**  -  uses a static price table in `$HOME/.claude/scripts/cost-table.json` (model → $/Mtok_in, $/Mtok_out). Missing model → show ` - ` for USD, never block.
 
@@ -310,7 +310,18 @@ Skipped in exactly two cases:
 | Autopilot (`state.autopilot === true` or `MULTI_AGENT_AUTOPILOT=1`) | Explicit consent for side-effect creation  -  posts directly with prefs/flag selections, zero interaction |
 | `--dry-run` | Already prints without posting; a question would be redundant |
 
-**Preview render** (one block per selected channel, final body after humanizer  -  shown in readable Markdown, channel-specific markup conversion happens after approval):
+**Preview render** (one block per selected channel, final body after humanizer  -  shown in readable Markdown, channel-specific markup conversion happens after approval).
+
+Conversion is per-channel and two of the four channels have none. Do not reach for "the" conversion table  -  there is no single one:
+
+| Channel | Conversion after approval | Table |
+|---|---|---|
+| PR description | **none**  -  posted as Markdown, verbatim | GitHub / Bitbucket / GitLab all render Markdown; see `channels/pr.md` "Markup dialect" |
+| GitHub issue comment | **none**  -  posted as Markdown, verbatim |  -  |
+| Jira comment | markdown → Jira wiki markup | `channels/jira.md` "Wiki markup conversion" |
+| Confluence page | markdown → storage format | `channels/confluence.md` "Body conversion" |
+
+Applying the Jira table to the PR body is the recurring failure of this step: it is the only *text* markup table in the doc set, so it reads as the default. It is not. A PR body containing `h2.`, `{{code}}`, or `#`-numbered lists shipped raw wiki markup to a Markdown surface.
 
 ```
 ── PR description  ({repoName} #{prNumber}, replace) ─────────

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

@@ -10,11 +10,11 @@ argument-hint: "[\"<free-text description>\"] [figma-url] [swagger-url]  -  all
 
 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.
 
-> **Language**: instruction prose here is English. AskUserQuestion `question`/`description` and the issue content (summary + description) follow `prefs.global.outputLanguage`  -  an intentional exception to the "external payloads stay English" default, because the issue is authored for the user's team. `label`/`header` stay English.
+> **Language**: instruction prose here is English. AskUserQuestion `question`/`description` and the issue content (summary + description) follow `prefs.global.outputLanguage`, like every other user-facing payload body (`rules.md` matrix). `label`/`header` stay English.
 
 ## Issue types
 
-Type is chosen at step [3/11] via AskUserQuestion (never inferred silently). Each type has a standard template baseline; sections auto-size (see `$HOME/.claude/multi-agent-refs/generate-issue.md` for the full A/C matrix and inclusion rules).
+Type is chosen at step [3/12] via AskUserQuestion (never inferred silently). Each type has a standard template baseline; sections auto-size (see `$HOME/.claude/multi-agent-refs/generate-issue.md` for the full A/C matrix and inclusion rules).
 
 | Type | Always-present sections | Conditional sections (included only when their trigger is present) |
 |---|---|---|
@@ -24,11 +24,11 @@ Type is chosen at step [3/11] via AskUserQuestion (never inferred silently). Eac
 
 ## Flow
 
-Read `$HOME/.claude/multi-agent-refs/generate-issue.md` and execute the 11-step shared flow. Non-negotiables restated:
+Read `$HOME/.claude/multi-agent-refs/generate-issue.md` and execute the 12-step shared flow. Non-negotiables restated:
 
 - Ask the user (AskUserQuestion) for the issue type first, then about every genuinely unknown field  -  component, epic, priority, labels, assignee, sprint vs backlog, required custom fields.
 - A conditional section renders only when its trigger is present (Figma URL, pasted screenshot/log, Swagger URL/contract, real Notes content). No empty placeholder headings; content the user did not supply and mining could not derive is never invented.
-- Step [8/11] full preview + approval gate always runs. `Approve` / `Edit` (loop) / `Cancel`. No bypass exists.
+- Step [9/12] full preview + approval gate always runs. `Approve` / `Edit` (loop) / `Cancel`. No bypass exists.
 
 ## Error paths
 

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

@@ -13,7 +13,7 @@ description-tr: "Hızlı geliştirme modu: Init → Dev (Opus) → Review → Te
 > 2. **`prefs.global.outputLanguage` is user-selectable**  -  applies to (a) every conversational line the agent writes back, and (b) every user-facing external payload: PR description body, Jira comment, Confluence body, Wiki body.
 >
 > Regardless of `outputLanguage`, these stay English (interop / convention):
->   - `AskUserQuestion` labels and descriptions (UI contract)
+>   - `AskUserQuestion` `label` + `header` only (UI contract)  -  the `question` and each option's `description` follow `outputLanguage`; a picker whose question is English on a Turkish run is a bug, not the contract
 >   - Commit message subject/body (git convention)
 >   - Branch names (`feature/`, `bugfix/`, ...)
 >   - Code identifiers, file paths, log lines
@@ -215,6 +215,14 @@ That is the whole list. Phase 0 (Init full picker), Phase 4 (Review), Phase 5 (U
 | Phase 5 User Test | ✅ | ✅ (same) |
 | Phase 7 channels (Jira / Confluence / PR / Wiki) | ✅ | ✅ (same) |
 | Duration | ~10-15 min | ~7-10 min |
+## Intake warnings (`--dev` family)
+
+Two checks belong at the top of every `--dev` run and are specified once in `$HOME/.claude/multi-agent-refs/phases/modes.md` "Intake warnings shared by the whole `--dev` family": an analysis document supplied to a mode that skips Analysis and Planning, and a branch that already carries the work (which wants `/multi-agent:ship`, not a second Dev pass). Read that section rather than reasoning about it from scratch.
+
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
+
 ## Required: Phase Tracker Contract
 
 **The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
@@ -236,7 +244,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 
 # After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 ```
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)
@@ -279,24 +287,3 @@ bash $HOME/.claude/scripts/phase-tracker.sh render
 ```
 
 Do NOT call TaskCreate on these CLIs  -  the tool does not exist and the call fails.
-
-## Analysis doc supplied to a fast mode (warn before starting)
-
-The `--dev` family skips Phase 1 (Analysis) and Phase 2 (Planning) by design. So when
-the input references an analysis document  -  a Confluence URL, a local analysis file,
-or the user says "I ran analysis for this"  -  there is **no phase that turns it into a
-plan**. The doc becomes raw context for one Dev pass, and work comes out ordered by
-whatever the model read first: the bottom of the dependency chain lands, the screen
-wiring does not.
-
-Say so before starting, once, and offer the choice:
-
-```
-This mode skips Analysis and Planning, so the analysis document will not be turned
-into a task breakdown. For analysis-driven screen work, /multi-agent or
-/multi-agent:local run both phases.
-  1. Continue with --dev (doc as context only)
-  2. Switch to the full pipeline
-```
-
-Autopilot picks 1 and logs the warning rather than asking.