@mmerterden/multi-agent-pipeline 20.0.0 → 20.2.0

package/pipeline/skills/.skills-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "skillCount": 213,
+  "skillCount": 219,
   "entries": [
     {
       "name": "accessibility-compliance-accessibility-audit",
@@ -47,26 +47,48 @@
       "relativePath": "shared/external/alarmkit/SKILL.md"
     },
     {
-      "name": "android_ui_verification",
-      "description": "Automated end-to-end UI testing and verification on an Android Emulator using ADB. Use when an Android build needs driving on an emulator to verify its UI end to end.",
+      "name": "android-architecture",
+      "description": "Design and implement Clean Architecture with multi-module structure on Android. Covers domain/data/presentation layers, Hilt dependency injection with @Module/@Provides/@Binds, UseCase pattern with operator invoke, Repository pattern with Kotlin Flow, and mapper pattern between layers. Use when stru",
       "platform": null,
       "group": "external",
       "plugin": "ai-android-toolkit",
-      "invokeAs": "ai-android-toolkit:android_ui_verification",
+      "invokeAs": "ai-android-toolkit:android-architecture",
       "triggerKeywords": [],
       "triggerPaths": [],
-      "relativePath": "shared/external/android_ui_verification/SKILL.md"
+      "relativePath": "shared/external/android-architecture/SKILL.md"
     },
     {
-      "name": "android-architecture",
-      "description": "Design and implement Clean Architecture with multi-module structure on Android. Covers domain/data/presentation layers, Hilt dependency injection with @Module/@Provides/@Binds, UseCase pattern with operator invoke, Repository pattern with Kotlin Flow, and mapper pattern between layers. Use when stru",
+      "name": "android-build-quality-gates",
+      "description": "Encode Android module and quality rules as build-failing Gradle tasks: layer-dependency checks, coverage floors, a Compose-stability gate, lint-on-diff and screenshot validation. Use when a multi-module app needs enforceable boundaries and quality gates in the build, not in review.",
       "platform": null,
       "group": "external",
       "plugin": "ai-android-toolkit",
-      "invokeAs": "ai-android-toolkit:android-architecture",
+      "invokeAs": "ai-android-toolkit:android-build-quality-gates",
       "triggerKeywords": [],
       "triggerPaths": [],
-      "relativePath": "shared/external/android-architecture/SKILL.md"
+      "relativePath": "shared/external/android-build-quality-gates/SKILL.md"
+    },
+    {
+      "name": "android-datastore",
+      "description": "Typed Jetpack DataStore as the modern SharedPreferences replacement: Preferences and typed stores, serializer-layer encryption, and migration. Use when persisting settings, session or tokens, encrypting key-value state, or migrating off EncryptedSharedPreferences.",
+      "platform": null,
+      "group": "external",
+      "plugin": "ai-android-toolkit",
+      "invokeAs": "ai-android-toolkit:android-datastore",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/android-datastore/SKILL.md"
+    },
+    {
+      "name": "android-design-tokens-codegen",
+      "description": "A single-source JSON to typed-Kotlin codegen pipeline for design tokens, UI-test ids, analytics events and deeplink manifests, run as Gradle tasks with a --check CI freshness gate. Use when a design system or cross-platform app needs one source of truth that generates typed code.",
+      "platform": null,
+      "group": "external",
+      "plugin": "ai-android-toolkit",
+      "invokeAs": "ai-android-toolkit:android-design-tokens-codegen",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/android-design-tokens-codegen/SKILL.md"
     },
     {
       "name": "android-jetpack-compose-expert",
@@ -79,6 +101,17 @@
       "triggerPaths": [],
       "relativePath": "shared/external/android-jetpack-compose-expert/SKILL.md"
     },
+    {
+      "name": "android-mvi-viewmodel",
+      "description": "A reusable generic BaseViewModel<State, Intent, Event> for MVI Compose apps: StateFlow state, one-shot events over a rendezvous Channel, a single intent dispatch, and a use-case executor with shared loading and error routing. Use when building or reviewing an MVI ViewModel base, intent-to-state redu",
+      "platform": null,
+      "group": "external",
+      "plugin": "ai-android-toolkit",
+      "invokeAs": "ai-android-toolkit:android-mvi-viewmodel",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/android-mvi-viewmodel/SKILL.md"
+    },
     {
       "name": "android-performance",
       "description": "Optimize Android app performance with Baseline Profiles for startup, Compose stability annotations (@Stable, @Immutable, strong skipping), recomposition debugging (Layout Inspector, recomposition counts), R8 optimization, LeakCanary memory leak detection, Macrobenchmark startup tracing, Coil image l",
@@ -101,6 +134,17 @@
       "triggerPaths": [],
       "relativePath": "shared/external/android-security/SKILL.md"
     },
+    {
+      "name": "android-ui-verification",
+      "description": "Automated end-to-end UI testing and verification on an Android Emulator using ADB. Use when an Android build needs driving on an emulator to verify its UI end to end.",
+      "platform": null,
+      "group": "external",
+      "plugin": "ai-android-toolkit",
+      "invokeAs": "ai-android-toolkit:android-ui-verification",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/android-ui-verification/SKILL.md"
+    },
     {
       "name": "api-patterns",
       "description": "API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination. Use when choosing between REST, GraphQL and tRPC, or shaping response formats, versioning and pagination.",
@@ -1421,6 +1465,17 @@
       "triggerPaths": [],
       "relativePath": "shared/core/multi-agent-search/SKILL.md"
     },
+    {
+      "name": "multi-agent-security-review",
+      "description": "Run a standalone defensive, static security review of a diff, branch or repo: run-scoped threat model, reviewer-shaped findings joined to OWASP + CWE with CVSS scoring, evidence and before/after fixes, plus an offline dependency inventory. No live target, no payloads. Use when reviewing code for sec",
+      "platform": null,
+      "group": "core",
+      "plugin": null,
+      "invokeAs": "multi-agent-security-review",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-security-review/SKILL.md"
+    },
     {
       "name": "multi-agent-setup",
       "description": "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation. Use when the pipeline is being set up for the first time, or tokens and git identity need onboarding.",
@@ -1784,6 +1839,17 @@
       "triggerPaths": [],
       "relativePath": "shared/external/search-first/SKILL.md"
     },
+    {
+      "name": "security-review",
+      "description": "Run a defensive, static security review of a diff or a repo: build a run-scoped threat model, find vulnerabilities joined to OWASP + CWE with CVSS scoring and evidence, and emit reviewer-shaped findings with before/after fixes. Use when reviewing code for security, auditing a dependency set, prepari",
+      "platform": null,
+      "group": "external",
+      "plugin": "ai-common-toolkit",
+      "invokeAs": "ai-common-toolkit:security-review",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/security-review/SKILL.md"
+    },
     {
       "name": "shareplay-activities",
       "description": "Build shared real-time experiences using GroupActivities and SharePlay. Use when implementing shared media playback, collaborative app features, synchronized game state, or any FaceTime, Messages, AirDrop, or nearby visionOS group activity on iOS, macOS, tvOS, or visionOS.",

package/pipeline/skills/shared/README.md

@@ -2,24 +2,24 @@
 
 Single source of truth for skills delivered to both Claude Code (`~/.claude/skills/`) and Copilot CLI (`~/.copilot/skills/`) by the installer.
 
-**Total:** 213 skills (60 core + 153 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
+**Total:** 219 skills (61 core + 158 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
 
 ## Directory layout
 
-- **`core/`**  -  60 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
-- **`external/`**  -  153 iOS / Android / generic skills imported from the upstream skill library. Mirrors of third-party guidance.
+- **`core/`**  -  61 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
+- **`external/`**  -  158 iOS / Android / generic skills imported from the upstream skill library. Mirrors of third-party guidance.
 - Install destinations (ADR-0009): Claude Code gets NO local copy of `external/` - it loads those skills from the `multi-agent-plugins` marketplace, namespaced (`ai-<stack>-toolkit:<name>`); only the two compliance catalogs from `core/` land in `~/.claude/skills/`. Copilot CLI and Codex CLI receive a flat copy filtered to the enabled stacks. `external/` remains the single authoring source that `build-stack-plugins.mjs` publishes from.
 
 Source layout is logical grouping only  -  skill discovery at runtime is unchanged.
 
 ## Categories
 
-- [Pipeline Orchestration](#pipeline-orchestration)  -  60
+- [Pipeline Orchestration](#pipeline-orchestration)  -  61
 - [iOS / Apple Ecosystem](#ios-apple-ecosystem)  -  90
-- [Android / Kotlin](#android-kotlin)  -  13
+- [Android / Kotlin](#android-kotlin)  -  17
 - [Web](#web)  -  10
 - [Backend / API](#backend-api)  -  11
-- [Cross-cutting](#cross-cutting)  -  29
+- [Cross-cutting](#cross-cutting)  -  30
 
 ## Pipeline Orchestration
 
@@ -71,6 +71,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`multi-agent-save`](./core/multi-agent-save/) | `core` | Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick o |
 | [`multi-agent-scan`](./core/multi-agent-scan/) | `core` | Skill security scan: walks local skill directories against a tiered pattern catalog. Use when local skill directories need checking for unsa |
 | [`multi-agent-search`](./core/multi-agent-search/) | `core` | Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus. Use when s |
+| [`multi-agent-security-review`](./core/multi-agent-security-review/) | `core` | Run a standalone defensive, static security review of a diff, branch or repo: run-scoped threat model, reviewer-shaped findings joined to OW |
 | [`multi-agent-setup`](./core/multi-agent-setup/) | `core` | First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation. Use when the pipeline is being set up f |
 | [`multi-agent-stack`](./core/multi-agent-stack/) | `core` | Select the active stack(s) for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json. Multi-select: pass several |
 | [`multi-agent-status`](./core/multi-agent-status/) | `core` | Show every multi-agent task's ID, phase, branch, and status. Use when asked what is running, or for an overview of every task. |
@@ -185,11 +186,15 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 
 | Skill | Group | Description |
 |-------|-------|-------------|
-| [`android_ui_verification`](./external/android_ui_verification/) | `external` | Automated end-to-end UI testing and verification on an Android Emulator using ADB. Use when an Android build needs driving on an emulator to |
 | [`android-architecture`](./external/android-architecture/) | `external` | Design and implement Clean Architecture with multi-module structure on Android. Covers domain/data/presentation layers, Hilt dependency inje |
+| [`android-build-quality-gates`](./external/android-build-quality-gates/) | `external` | Encode Android module and quality rules as build-failing Gradle tasks: layer-dependency checks, coverage floors, a Compose-stability gate, l |
+| [`android-datastore`](./external/android-datastore/) | `external` | Typed Jetpack DataStore as the modern SharedPreferences replacement: Preferences and typed stores, serializer-layer encryption, and migratio |
+| [`android-design-tokens-codegen`](./external/android-design-tokens-codegen/) | `external` | A single-source JSON to typed-Kotlin codegen pipeline for design tokens, UI-test ids, analytics events and deeplink manifests, run as Gradle |
 | [`android-jetpack-compose-expert`](./external/android-jetpack-compose-expert/) | `external` | Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Desig |
+| [`android-mvi-viewmodel`](./external/android-mvi-viewmodel/) | `external` | A reusable generic BaseViewModel<State, Intent, Event> for MVI Compose apps: StateFlow state, one-shot events over a rendezvous Channel, a s |
 | [`android-performance`](./external/android-performance/) | `external` | Optimize Android app performance with Baseline Profiles for startup, Compose stability annotations (@Stable, @Immutable, strong skipping), r |
 | [`android-security`](./external/android-security/) | `external` | Secure Android apps with ProGuard/R8 obfuscation, OkHttp certificate pinning, BiometricPrompt authentication, EncryptedSharedPreferences, Pl |
+| [`android-ui-verification`](./external/android-ui-verification/) | `external` | Automated end-to-end UI testing and verification on an Android Emulator using ADB. Use when an Android build needs driving on an emulator to |
 | [`compose-components`](./external/compose-components/) | `external` | Build Material 3 UI components and custom composables with Jetpack Compose. Covers TopAppBar, Scaffold, BottomSheet, SnackbarHost, slot-base |
 | [`compose-navigation`](./external/compose-navigation/) | `external` | Implement type-safe navigation in Jetpack Compose using Navigation 2.8+ with @Serializable routes, NavHost, composable<Route>, nested naviga |
 | [`compose-testing`](./external/compose-testing/) | `external` | Test Jetpack Compose UI with createComposeRule, semantic matchers (onNodeWithText, onNodeWithTag, onNodeWithContentDescription), actions (pe |
@@ -255,6 +260,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`localization-reuse-map`](./external/localization-reuse-map/) | `external` | >- |
 | [`pdfkit`](./external/pdfkit/) | `external` | Display and manipulate PDF documents using PDFKit. Use when embedding PDFView to show PDF files, creating or modifying PDFDocument instances |
 | [`search-first`](./external/search-first/) | `external` | \| |
+| [`security-review`](./external/security-review/) | `external` | Run a defensive, static security review of a diff or a repo: build a run-scoped threat model, find vulnerabilities joined to OWASP + CWE wit |
 | [`signal-community`](./external/signal-community/) | `external` | Check whether other people hit the same problem, via Stack Overflow and Hacker News (keyless) plus opt-in Reddit and X. Use when a bug repor |
 | [`skill-creator`](./external/skill-creator/) | `external` | Author and refine skills for a plugin/toolkit efficiently. Use when creating a new skill, trimming or splitting an existing one, writing a s |
 | [`spm-build-analysis`](./external/spm-build-analysis/) | `external` | Analyze Swift Package Manager dependencies, package plugins, module variants, and CI-oriented build overhead that slow Xcode builds. Use whe |

package/pipeline/skills/shared/core/multi-agent/SKILL.md

@@ -422,9 +422,8 @@ Two halves, one phase, one approval gate (Phases 1 and 2 until 19.0.0).
 
 **1a  -  Analysis** (claude-sonnet-5, `explorer` persona)
 1. Launch **explore agents** (parallel) to scan the codebase: related files, existing patterns and conventions, potential impact areas
-2. Optionally launch **security-auditor** agent for pre-check
-3. Summarize findings
-4. Log: `📊 Phase 1: Plan (analysis)  -  {N} files identified, {summary}`
+2. Summarize findings
+3. Log: `📊 Phase 1: Plan (analysis)  -  {N} files identified, {summary}`
 
 **1b  -  Planning** (claude-fable-5)
 1. Create task breakdown → todos with dependencies
@@ -633,7 +632,7 @@ Sub-agents have embedded skills in their `.agent.md` files. Each agent is pre-lo
 |-------|----------------|----------------|
 | **code-reviewer** | Code Review Excellence, Security Audit, Performance Review, TDD Verification, Error Detective | Phase 3: Review |
 | **ios-architect** | Spec-Driven Architecture, Context Management, Multi-Agent Coordination, API Design, Performance Architecture, Design System Governance | Phase 1: Plan |
-| **security-auditor** | iOS Security Deep Dive, App Store Review Gates, Third-Party SDK Risk, Error Detective (Security) | Phase 1: Plan (analysis half, pre-check) + Phase 3: Review |
+| **security-auditor** | iOS Security Deep Dive, App Store Review Gates, Third-Party SDK Risk, Error Detective (Security) | Phase 3: Review |
 
 ### Phase → Agent → Skills Flow
 

package/pipeline/skills/shared/core/multi-agent-scan/SKILL.md

@@ -3,7 +3,7 @@ name: multi-agent-scan
 language: en
 description: "Skill security scan: walks local skill directories against a tiered pattern catalog. Use when local skill directories need checking for unsafe or unexpected content."
 user-invocable: true
-argument-hint: "[--strict] [--target <path>]  -  optional: --strict enables CI failure mode, --target picks a custom directory"
+argument-hint: "[--strict] [--root PATH]  -  optional: --strict enables strict exit codes, --root picks a custom directory"
 ---
 
 # multi-agent-scan
@@ -55,7 +55,7 @@ multi-agent-scan --root ~/.copilot/skills
 ## Integration
 
 - **install.js** pre-deploy hook (automatic, warn-only high-threshold)
-- **CI** `.github/workflows/smoke.yml` step (strict)
+- **Smoke suite** `smoke-skill-scan.sh` runs it in strict mode under `npm test`
 - **Standalone** this skill
 
 Cross-CLI parity: `/multi-agent:scan` on Claude Code, `multi-agent-scan` on Copilot CLI. Same source script, same behavior.

package/pipeline/skills/shared/core/multi-agent-security-review/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: multi-agent-security-review
+language: en
+description: "Run a standalone defensive, static security review of a diff, branch or repo: run-scoped threat model, reviewer-shaped findings joined to OWASP + CWE with CVSS scoring, evidence and before/after fixes, plus an offline dependency inventory. No live target, no payloads. Use when reviewing code for security outside a full pipeline run, auditing dependencies, or preparing a branch for a security sign-off."
+user-invocable: true
+argument-hint: "[#N | repo#N | PR-URL | branch | path]  -  a PR, a local branch, or a path to scope the review. If omitted: the current branch diff against its base."
+---
+
+# multi-agent security-review  -  standalone defensive static review
+
+**Input**: `$ARGUMENTS`
+
+The same security audit Phase 3 runs at Step 2.7, invoked on its own. Defensive and static: reads code, config and dependency manifests; never runs the target, fires a payload, or reaches a live host.
+
+## Scope
+
+Resolve from `$ARGUMENTS`, same shapes as `/multi-agent:review`: `#N` / `repo#N` / PR URL → that PR's diff; a branch → its diff against base; a path → files under it; omitted → the current branch diff. Cap the diff as Phase 3 Step 1.9 does.
+
+## Steps
+
+1. **Threat model** - produce `.pipeline/threat-model.md` (four sections) if absent, else read it; mirror to `state.threatModel`. Contract: `threat-model.md`.
+2. **Method** - load `ai-common-toolkit:security-review` for the OWASP walk (Web/API Top 10 2021, Mobile Top 10 2024) + CWE join. This command orchestrates, it does not re-derive the method.
+3. **Findings** - dispatch the `security-auditor`; it returns a `reviewer-output.schema.json` object whose `findings[]` carry the `security` envelope (`security-finding.schema.json`). Score every vector with the toolkit `security_cvss_score`; validate with `validate-reviewer.mjs` (one rework then halt).
+4. **Dependencies** - run `security_dep_inventory` on the lockfiles; hand the inventory to `ai-analyst-toolkit:evidence-registry` for known CVEs when it is registered. A vulnerable dependency is an `A06:2021` finding with the advisory CWE + CVE. This command contacts nothing itself.
+5. **Report** - write `.pipeline/security-findings.json` and a human summary (count by severity; each blocking/important finding with OWASP id, CWE, CVSS band, evidence, before/after fix). An empty list with `approved: true` is a clean review.
+
+## Boundaries
+
+Inside a run the same audit is Phase 3 Step 2.7 (`features/security-audit.md`), triggered by the `security_path` signal; this is the standalone entry point. Not the `store-ready` device pass, not a secret scanner (`pre-commit-check.sh` covers secrets). No writes to Jira / GitHub / Confluence. Autopilot reviews the current branch, writes the report, opens no PR.

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -32,7 +32,7 @@ Run all steps automatically:
 ```
 Step 0: DOCTOR      node $HOME/.claude/scripts/doctor.mjs  -  exit 2 or 4 STOPS the sync
 Step 1: DETECT      Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 57 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 58 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 57 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
 Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
@@ -228,7 +228,7 @@ When invoked with the `release` argument:
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**57 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**58 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
@@ -239,7 +239,7 @@ language, log, manual-test, model, prune-logs,
 prune-prompts, purge, refactor, resume, review,
 review-analysis, review-issue, review-jira, route-off, route-on,
 route-status, routines, save, scan, search,
-setup, stack, status, steer, store-ready, sync, test, test-accessibility,
+security-review, setup, stack, status, steer, store-ready, sync, test, test-accessibility,
 test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation,
 uninstall, update
 ```

package/pipeline/skills/shared/external/android-architecture/SKILL.md

@@ -12,10 +12,12 @@ and Jetpack libraries from 2024-2025.
 ## Contents
 
 - [Multi-Module Structure](#multi-module-structure)
+- [Feature api/impl Split](#feature-apiimpl-split)
 - [Domain Layer](#domain-layer)
 - [Data Layer](#data-layer)
 - [Presentation Layer](#presentation-layer)
 - [Hilt Dependency Injection](#hilt-dependency-injection)
+- [Cross-Module Navigation Graph Aggregation](#cross-module-navigation-graph-aggregation)
 - [Mapper Pattern](#mapper-pattern)
 - [Do's and Don'ts](#dos-and-donts)
 - [Troubleshooting](#troubleshooting)
@@ -77,6 +79,33 @@ include(":feature:search")
 include(":feature:detail")
 ```
 
+## Feature api/impl Split
+
+For features that navigate to each other, split each one into two modules:
+
+- `:feature:x:api` -- only the cross-feature contract: `@Serializable` route
+  definitions and the entry-param models a caller needs to launch the feature.
+- `:feature:x:impl` -- screens, ViewModels, UI state, and DI wiring.
+
+A feature depends only on the `:api` of the features it navigates to, never
+their `:impl`:
+
+```kotlin
+// feature:home:impl/build.gradle.kts
+dependencies {
+    implementation(project(":feature:home:api"))
+    implementation(project(":feature:detail:api"))   // route + entry params only
+    // NEVER depend on :feature:detail:impl
+}
+```
+
+Because no `impl` module can see another `impl`, they stay mutually invisible,
+compile in parallel, and cannot form dependency cycles. The `:app` module wires
+them together (see
+[Cross-Module Navigation Graph Aggregation](#cross-module-navigation-graph-aggregation)).
+Full module layout and route contract:
+[references/patterns.md#feature-apiimpl-split](references/patterns.md#feature-apiimpl-split).
+
 ## Domain Layer
 
 The domain layer contains business logic with zero Android dependencies. It
@@ -231,6 +260,11 @@ sealed interface HomeUiState {
 }
 ```
 
+For the reusable base ViewModel seam these screen ViewModels extend -- immutable
+state as `StateFlow`, one-shot events, a single intent entry point, and
+centralized use-case execution -- see the `android-mvi-viewmodel` skill. Do not
+reimplement that base class here.
+
 ## Hilt Dependency Injection
 
 ### Application Setup
@@ -324,6 +358,36 @@ abstract class DispatcherModule {
 }
 ```
 
+## Cross-Module Navigation Graph Aggregation
+
+Each `:impl` module contributes its destinations to a shared `Set<NavGraph>` via
+Hilt multibinding; the host registers the whole set into one `NavHost`. The
+`:app` module never depends on any `:impl`.
+
+```kotlin
+fun interface NavGraph {
+    fun NavGraphBuilder.build(navController: NavHostController)
+}
+
+// In each :impl module
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class HomeNavModule {
+    @Binds
+    @IntoSet
+    abstract fun bindHomeNavGraph(impl: HomeNavGraph): NavGraph
+}
+
+// In :app -- register every contributed graph, naming no feature
+NavHost(navController, startDestination = HomeRoute) {
+    navGraphs.forEach { graph -> with(graph) { build(navController) } }
+}
+```
+
+This wires many feature modules into a single `NavHost` without the app module
+depending on every `impl`. Full host injection and per-feature contribution:
+[references/patterns.md#cross-module-navigation-graph-aggregation](references/patterns.md#cross-module-navigation-graph-aggregation).
+
 ## Mapper Pattern
 
 Mappers isolate layer boundaries. Each layer has its own model type.
@@ -372,9 +436,13 @@ class FlightMapper @Inject constructor() {
 - Define a `DispatcherProvider` interface for testable coroutine dispatchers
 - One use case per business operation
 - Use `sealed interface` for UI state to guarantee exhaustive `when` handling
+- Split each feature into `:api` (routes + entry params) and `:impl` (screens, ViewModels, DI)
+- Aggregate feature nav graphs into the host with Hilt `@IntoSet` multibinding
 
 ### Don'ts
 - Do not let feature modules depend on each other directly
+- Do not depend on another feature's `:impl` module -- depend on its `:api` only
+- Do not make the `:app` module reference feature `impl` modules in code
 - Do not put Android framework classes in the domain layer
 - Do not expose `MutableStateFlow` from ViewModels (expose read-only `StateFlow`)
 - Do not inject `Activity` or `Fragment` into ViewModels
@@ -402,6 +470,9 @@ class FlightMapper @Inject constructor() {
 - [ ] UI state is a `sealed interface` with Loading/Success/Error
 - [ ] Hilt modules use `@Binds` for interfaces, `@Provides` for instances
 - [ ] Feature modules do not depend on each other
+- [ ] Each feature is split into `:api` (routes/entry params) and `:impl` (screens/ViewModels/DI)
+- [ ] Feature `impl` modules depend only on other features' `api`, never their `impl`
+- [ ] Feature nav graphs aggregate into the host via Hilt `@IntoSet` multibinding
 - [ ] Mappers separate DTO/Entity/Domain models
 - [ ] Coroutine dispatchers are injectable via `DispatcherProvider`
 - [ ] No `GlobalScope` usage; all coroutines use structured concurrency

package/pipeline/skills/shared/external/android-architecture/references/patterns.md

@@ -0,0 +1,142 @@
+# Android Clean Architecture -- Reference Patterns
+
+Full code for the patterns summarized in `SKILL.md`. Load the section you need
+when implementing that specific structure.
+
+## Contents
+
+- [Feature api/impl Split](#feature-apiimpl-split)
+- [Cross-Module Navigation Graph Aggregation](#cross-module-navigation-graph-aggregation)
+
+## Feature api/impl Split
+
+Split every feature into an `:api` module (the cross-feature contract) and an
+`:impl` module (everything private to the feature).
+
+```
+:feature:home:api             # Serializable routes + entry-param models only
+:feature:home:impl            # Screens, ViewModels, UI state, DI
+:feature:search:api
+:feature:search:impl
+:feature:detail:api
+:feature:detail:impl
+```
+
+### The api module holds only the contract
+
+```kotlin
+// :feature:detail:api
+@Serializable
+data class DetailRoute(val id: String)
+
+@Serializable
+data class DetailEntryParams(val id: String, val source: String)
+```
+
+No screens, no ViewModels, no Compose dependency -- just the route and the
+models a caller needs to launch the feature.
+
+### The impl module holds everything private
+
+```kotlin
+// :feature:detail:impl -- not visible to any other feature
+@HiltViewModel
+class DetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val getDetailUseCase: GetDetailUseCase,
+) : ViewModel() {
+    private val route = savedStateHandle.toRoute<DetailRoute>()
+    // ... state, intents, events
+}
+
+@Composable
+internal fun DetailScreen(viewModel: DetailViewModel = hiltViewModel()) { /* ... */ }
+```
+
+### Dependency direction
+
+```kotlin
+// feature:home:impl/build.gradle.kts
+dependencies {
+    implementation(project(":feature:home:api"))
+    implementation(project(":feature:detail:api"))   // route + entry params only
+    implementation(project(":core:model"))
+    implementation(project(":core:ui"))
+    // NEVER implementation(project(":feature:detail:impl"))
+}
+```
+
+Because no `impl` module can see another `impl`, the graph of feature modules is
+acyclic by construction, the modules compile in parallel, and a caller can only
+couple to a feature through its published route and entry params.
+
+## Cross-Module Navigation Graph Aggregation
+
+Each `:impl` module contributes its destinations to a shared `Set<NavGraph>` via
+Hilt multibinding. The host module (`:app`) injects the full set and registers
+every contribution into one `NavHost`, without depending on any `:impl`.
+
+### The contribution contract
+
+```kotlin
+// :core:ui (or a :core:navigation module)
+fun interface NavGraph {
+    fun NavGraphBuilder.build(navController: NavHostController)
+}
+```
+
+### Each feature contributes its graph
+
+```kotlin
+// :feature:home:impl
+class HomeNavGraph @Inject constructor() : NavGraph {
+    override fun NavGraphBuilder.build(navController: NavHostController) {
+        composable<HomeRoute> {
+            HomeScreen()
+        }
+    }
+}
+
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class HomeNavModule {
+    @Binds
+    @IntoSet
+    abstract fun bindHomeNavGraph(impl: HomeNavGraph): NavGraph
+}
+```
+
+### The host registers the whole set
+
+```kotlin
+// :app
+@Composable
+fun AppNavHost(
+    navGraphs: Set<@JvmSuppressWildcards NavGraph>,
+    navController: NavHostController = rememberNavController(),
+    startDestination: Any = HomeRoute,
+) {
+    NavHost(navController = navController, startDestination = startDestination) {
+        navGraphs.forEach { graph -> with(graph) { build(navController) } }
+    }
+}
+```
+
+Injecting the set into the composable is done with a Hilt entry point or by
+passing it from an `@AndroidEntryPoint` activity:
+
+```kotlin
+@AndroidEntryPoint
+class MainActivity : ComponentActivity() {
+    @Inject lateinit var navGraphs: Set<@JvmSuppressWildcards NavGraph>
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent { AppNavHost(navGraphs = navGraphs) }
+    }
+}
+```
+
+Adding a feature to the app is now: add its `:impl` to the `:app` runtime
+classpath and its `@IntoSet` binding registers automatically. The `:app` module
+never names the feature in code.