@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,250 @@
+## Android/Kotlin Component Generation Guide
+
+When the task involves creating an Android UI component (Jetpack Compose), follow this architecture.
+
+### Component Architecture: State / Screen / Content
+
+| File                 | When         | Content                                             |
+| -------------------- | ------------ | --------------------------------------------------- |
+| `{Name}UiState.kt`   | Always       | Data class representing screen/component state      |
+| `{Name}ViewModel.kt` | Screen-level | ViewModel with StateFlow, business logic            |
+| `{Name}Screen.kt`    | Screen-level | Stateful wrapper: collects state, passes to Content |
+| `{Name}Content.kt`   | Always       | Stateless @Composable, receives state + lambdas     |
+| `{Name}Preview.kt`   | Always       | @Preview functions for all meaningful variants      |
+| `{Name}Test.kt`      | Always       | Compose testing + ViewModel tests                   |
+
+### Simple vs Complex Decision
+
+- **Screen-level** (has ViewModel, navigation) -> Full architecture: UiState + ViewModel + Screen + Content
+- **Reusable component** (no ViewModel, receives props) -> Content only, stateless composable
+- **Variant-driven** (e.g. ButtonType enum with 5+ cases) -> Extract to separate component file
+
+### State Pattern
+
+```kotlin
+// UiState: immutable data class
+data class LoginUiState(
+    val email: String = "",
+    val password: String = "",
+    val isLoading: Boolean = false,
+    val error: String? = null
+)
+
+// ViewModel: single StateFlow
+class LoginViewModel @Inject constructor(
+    private val authRepo: AuthRepository
+) : ViewModel() {
+    private val _uiState = MutableStateFlow(LoginUiState())
+    val uiState: StateFlow<LoginUiState> = _uiState.asStateFlow()
+
+    fun onEmailChanged(email: String) {
+        _uiState.update { it.copy(email = email) }
+    }
+}
+
+// Screen: stateful wrapper (never pass ViewModel to children)
+@Composable
+fun LoginScreen(viewModel: LoginViewModel = hiltViewModel()) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    LoginContent(
+        uiState = uiState,
+        onEmailChanged = viewModel::onEmailChanged,
+        onLoginClicked = viewModel::onLogin
+    )
+}
+
+// Content: stateless, testable, previewable
+@Composable
+fun LoginContent(
+    uiState: LoginUiState,
+    onEmailChanged: (String) -> Unit,
+    onLoginClicked: () -> Unit
+) { ... }
+```
+
+### Token Discipline
+
+**Zero magic numbers. Zero hardcoded colors. Zero hardcoded strings.**
+
+| Bad                     | Good                                                       |
+| ----------------------- | ---------------------------------------------------------- |
+| `padding = 16.dp`       | `padding = MaterialTheme.spacing.medium` or named constant |
+| `Color(0xFFE31837)`     | `MaterialTheme.colorScheme.primary`                        |
+| `.fontSize = 14.sp`     | `MaterialTheme.typography.bodyMedium`                      |
+| `"Login"` in composable | `stringResource(R.string.login)`                           |
+
+If the project has no spacing system:
+
+```kotlin
+private object Spacing {
+    val small = 8.dp
+    val medium = 16.dp
+    val large = 24.dp
+}
+```
+
+### Stability for Performance
+
+```kotlin
+// Mark as @Immutable if all fields are val and immutable types
+@Immutable
+data class ButtonConfig(
+    val text: String,
+    val type: ButtonType,
+    val enabled: Boolean = true
+)
+
+// Use remember for expensive computations
+val formattedDate = remember(timestamp) { dateFormatter.format(timestamp) }
+```
+
+### Accessibility
+
+Every interactive element MUST have:
+
+- `contentDescription` for images/icons
+- `semantics { }` block for custom accessibility info
+- `testTag` for UI testing
+- Minimum touch target: **48x48dp** (Material guidelines)
+
+```kotlin
+Icon(
+    imageVector = Icons.Default.Close,
+    contentDescription = stringResource(R.string.close),
+    modifier = Modifier
+        .testTag("close_button")
+        .size(48.dp)
+)
+```
+
+### Preview Best Practices
+
+```kotlin
+@Preview(name = "Default")
+@Preview(name = "Dark Mode", uiMode = Configuration.UI_MODE_NIGHT_YES)
+@Preview(name = "Large Font", fontScale = 2f)
+@Preview(name = "RTL", locale = "ar")
+@Composable
+private fun LoginContentPreview() {
+    AppTheme {
+        LoginContent(
+            uiState = LoginUiState(email = "test@example.com"),
+            onEmailChanged = {},
+            onLoginClicked = {}
+        )
+    }
+}
+```
+
+### Testing
+
+```kotlin
+// Compose UI test
+@get:Rule val composeTestRule = createComposeRule()
+
+@Test
+fun loginButton_displaysCorrectText() {
+    composeTestRule.setContent {
+        LoginContent(uiState = LoginUiState(), ...)
+    }
+    composeTestRule.onNodeWithText("Login").assertIsDisplayed()
+}
+
+// ViewModel test with Turbine
+@Test
+fun onEmailChanged_updatesState() = runTest {
+    val viewModel = LoginViewModel(FakeAuthRepository())
+    viewModel.uiState.test {
+        assertEquals("", awaitItem().email)
+        viewModel.onEmailChanged("test@example.com")
+        assertEquals("test@example.com", awaitItem().email)
+    }
+}
+```
+
+### Build Verification
+
+After implementation:
+
+- `./gradlew assembleDebug` — zero errors
+- `./gradlew testDebugUnitTest` — all tests pass
+- `./gradlew ktlintCheck` — lint clean
+- Previews render in Android Studio
+
+### Component Quality Checklist
+
+1. No magic numbers — all values are theme tokens or named constants
+2. State hoisting — stateful wrapper + stateless content pattern
+3. No ViewModel in child composables — pass state + lambdas
+4. Accessibility — contentDescription, testTag, 48dp touch targets
+5. Preview coverage — default, dark mode, large font, RTL
+6. Tests — Compose UI tests + ViewModel unit tests
+7. Dark mode — correct with MaterialTheme.colorScheme
+8. Strings — all use `stringResource()`, not hardcoded
+9. Stability — `@Immutable`/`@Stable` where appropriate
+10. Build passes — zero errors, lint clean
+
+### Compliance Rules (maps to dev-toolkit MCP audit tools)
+
+These rules ensure your code passes `android_accessibility_audit` and `android_apk_audit` without issues.
+
+#### Accessibility (validated by `android_accessibility_audit`)
+
+| Rule                                             | What Audit Checks          | How to Pass                                                |
+| ------------------------------------------------ | -------------------------- | ---------------------------------------------------------- |
+| Every clickable element has `contentDescription` | Missing on clickable views | `contentDescription = stringResource(R.string.close)`      |
+| Every interactive element has `testTag`          | Missing resource-id        | `Modifier.testTag("button_submit")`                        |
+| Minimum touch target 48x48dp                     | Bounds < 48x48             | `Modifier.size(48.dp)` or `Modifier.defaultMinSize(48.dp)` |
+
+```kotlin
+// This PASSES audit:
+IconButton(
+    onClick = onClose,
+    modifier = Modifier
+        .testTag("button_close")
+        .size(48.dp)
+) {
+    Icon(
+        imageVector = Icons.Default.Close,
+        contentDescription = stringResource(R.string.close)
+    )
+}
+
+// This FAILS audit:
+IconButton(onClick = onClose) {       // no testTag, might be < 48dp
+    Icon(Icons.Default.Close, null)    // contentDescription = null
+}
+```
+
+#### Release Compliance (validated by `android_apk_audit`)
+
+| Rule                      | What Audit Checks              | How to Pass                                            |
+| ------------------------- | ------------------------------ | ------------------------------------------------------ |
+| Target SDK >= 34          | `targetSdkVersion` in manifest | `targetSdk = 34` in build.gradle                       |
+| Not debuggable in release | `android:debuggable=true`      | `debuggable = false` in release buildType (default)    |
+| R8/ProGuard enabled       | Large DEX file count           | `isMinifyEnabled = true` in release buildType          |
+| APK size < 150MB          | APK file size                  | Use App Bundle (.aab), enable R8, shrink resources     |
+| v2+ signing               | Only v1 signature              | Configure `signingConfigs` with v2 signing enabled     |
+| No excessive permissions  | Dangerous permission count     | Audit `AndroidManifest.xml`, remove unused permissions |
+
+```kotlin
+// build.gradle.kts
+android {
+    defaultConfig {
+        targetSdk = 35
+    }
+    buildTypes {
+        release {
+            isMinifyEnabled = true        // R8 enabled
+            isShrinkResources = true      // remove unused resources
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+        }
+    }
+}
+```
+
+```xml
+<!-- AndroidManifest.xml: only declare permissions you actually use -->
+<uses-permission android:name="android.permission.CAMERA" />
+<!-- Remove unused: RECORD_AUDIO, READ_CONTACTS, etc. if not needed -->
+```

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

@@ -0,0 +1,240 @@
+## Audit & Quality Tools Guide
+
+Standalone audit commands — runs directly via Bash, **no MCP server dependency**. These are the same checks that dev-toolkit-mcp provides as MCP tools, but embedded here as pipeline skills.
+
+### Trigger Model
+
+**These audits are on-demand.** They run when:
+
+1. User explicitly requests: `/multi-agent test "accessibility"`, `/multi-agent test "store-ready"`
+2. User asks during Phase 5: "run accessibility audit", "check store compliance"
+3. Pipeline suggests and user confirms: "UI changes detected — want to run accessibility audit?"
+
+**Pipeline never runs audits without user intent.** Phase 4 does code-level review (free, automatic). Phase 5 does device-level audit only when requested.
+
+---
+
+### iOS Accessibility Audit
+
+**When**: Phase 5 — user requests, app is running on simulator
+**What it checks**: Missing labels, small tap targets (<44pt), missing identifiers
+
+**How to run** (requires ui-tree-dumper.swift in project or ~/.claude/scripts/):
+
+```bash
+# 1. Get UI tree from running simulator
+UI_TREE=$(swift "$HOME/.claude/scripts/ui-tree-dumper.swift" 10 2>/dev/null)
+
+# 2. Parse and audit (pipeline does this in-context)
+# The AI reads the JSON output and checks:
+#   - Interactive elements (AXButton, AXLink, AXTextField, AXSwitch, AXSlider)
+#   - Missing: title, description, AND value all null → "Missing accessibility label"
+#   - Missing: identifier null → "Missing accessibility identifier"
+#   - Small: frame.w < 44 OR frame.h < 44 → "Tap target too small"
+```
+
+**Scope filtering**: If only checking a specific screen, filter by identifier prefix:
+
+```
+Only audit elements where identifier starts with "{scope}_"
+Skip elements outside scope — report scanned vs skipped count
+```
+
+**Output format** (AI generates this from parsed tree):
+
+```
+Accessibility Audit:
+  Scope: {scope or "all"}
+  Scanned: {N} interactive elements
+
+  CRITICAL: {N} missing labels
+    - AXButton at (120, 340) — no label, identifier: "btn_close"
+
+  IMPORTANT: {N} small tap targets
+    - AXButton "Submit" — 32x32pt (min 44x44)
+
+  WARNING: {N} missing identifiers
+    - AXTextField at (20, 200) — has label "Email" but no identifier
+```
+
+---
+
+### Android Accessibility Audit
+
+**When**: Phase 5 — user requests, app is running on emulator
+**What it checks**: Missing contentDescription, small touch targets (<48dp), missing resource-id
+
+```bash
+# 1. Dump UI hierarchy
+adb shell uiautomator dump /sdcard/_audit_ui.xml
+adb pull /sdcard/_audit_ui.xml /tmp/_audit_ui.xml
+adb shell rm /sdcard/_audit_ui.xml
+
+# 2. Read XML
+cat /tmp/_audit_ui.xml
+```
+
+**AI parses XML and checks** each `<node>` with `clickable="true"`:
+
+- `content-desc=""` AND `text=""` → "Missing contentDescription"
+- `resource-id=""` → "Missing resource-id"
+- bounds `[x1,y1][x2,y2]` where `(x2-x1) < 48` or `(y2-y1) < 48` → "Touch target too small"
+
+**Scope filtering**: Only audit nodes where `resource-id` contains `{scope}` prefix.
+
+---
+
+### iOS Biometric Test
+
+**When**: Phase 5 — auth flow testing
+
+```bash
+DEVICE_ID=$(xcrun simctl list devices booted -j | python3 -c "import sys,json; devs=json.load(sys.stdin)['devices']; print(next(d['udid'] for ds in devs.values() for d in ds if d['state']=='Booted'))")
+
+# Enroll biometric
+xcrun simctl keychain $DEVICE_ID biometric-enroll --face
+
+# Test success
+xcrun simctl keychain $DEVICE_ID biometric-match --face
+# → Take screenshot, verify success screen
+
+# Test failure
+xcrun simctl keychain $DEVICE_ID biometric-match --face --no-match
+# → Take screenshot, verify error handling
+```
+
+---
+
+### Android Launch Time
+
+**When**: Phase 5 — performance baseline
+
+```bash
+# Force stop first (cold start)
+adb shell am force-stop {package_name}
+
+# Launch with timing
+adb shell am start -W -n {package_name}/.MainActivity 2>&1
+# Output includes:
+#   TotalTime: 487
+#   WaitTime: 501
+```
+
+**Evaluation**:
+
+- < 500ms → excellent
+- 500-1000ms → acceptable
+- 1000-2000ms → warning: "Cold start > 1s"
+- \> 2000ms → important: "Cold start > 2s, likely impacts retention"
+
+---
+
+### iOS Archive Audit (App Store Compliance)
+
+**When**: Phase 6 — release branches only, user confirms
+**Input**: Path to .xcarchive
+
+```bash
+ARCHIVE="/path/to/MyApp.xcarchive"
+APP_DIR=$(find "$ARCHIVE/Products/Applications" -name "*.app" -maxdepth 1 | head -1)
+APP_NAME=$(basename "$APP_DIR")
+BINARY="$APP_DIR/${APP_NAME%.app}"
+
+# 1. Binary size
+stat -f "%z" "$BINARY" 2>/dev/null
+# → > 500MB = warning
+
+# 2. Debug tool leak
+nm "$BINARY" 2>/dev/null | grep -iE "FLEX|Reveal|Stetho|Flipper|CocoaDebug|Pulse" | head -10
+# → Any match = CRITICAL
+
+# 3. Code signing
+codesign -dvv "$APP_DIR" 2>&1
+# → "not signed" = CRITICAL
+
+# 4. Debug entitlements
+codesign -d --entitlements - "$APP_DIR" 2>/dev/null | grep "get-task-allow"
+# → get-task-allow = true → CRITICAL (debug build)
+
+# 5. Info.plist
+plutil -convert json -o - "$APP_DIR/Info.plist" 2>/dev/null
+# Check: CFBundleShortVersionString exists, NSAllowsArbitraryLoads not true
+
+# 6. Privacy manifest
+find "$APP_DIR" -name "PrivacyInfo.xcprivacy" | head -1
+# → Not found = WARNING
+
+# 7. Privacy permission strings
+plutil -convert json -o - "$APP_DIR/Info.plist" 2>/dev/null | python3 -c "
+import sys,json; p=json.load(sys.stdin)
+keys=['NSCameraUsageDescription','NSPhotoLibraryUsageDescription','NSLocationWhenInUseUsageDescription','NSMicrophoneUsageDescription','NSFaceIDUsageDescription']
+for k in keys:
+    if k in p: print(f'  {k}: {p[k]}')
+"
+
+# 8. Embedded frameworks
+ls "$APP_DIR/Frameworks/" 2>/dev/null
+```
+
+**Verdict**:
+
+- Any CRITICAL → "FAIL — must fix before submission"
+- Only WARNING → "WARN — review before submission"
+- All pass → "PASS — ready for App Store"
+
+---
+
+### Android APK Audit (Play Store Compliance)
+
+**When**: Phase 6 — release branches only, user confirms
+**Input**: Path to .apk
+
+```bash
+APK="/path/to/app-release.apk"
+
+# 1. Basic info (requires aapt2 or aapt from Android SDK Build-Tools)
+aapt2 dump badging "$APK" 2>/dev/null
+# Extract: package name, versionName, versionCode, targetSdkVersion, sdkVersion
+# → targetSdk < 34 = WARNING
+
+# 2. Debuggable check
+aapt2 dump badging "$APK" 2>/dev/null | grep "application-debuggable"
+# → Found = CRITICAL
+
+# 3. Permissions
+aapt2 dump badging "$APK" 2>/dev/null | grep "uses-permission"
+# → Count dangerous permissions (CAMERA, CONTACTS, LOCATION, etc.)
+# → > 5 dangerous = WARNING
+
+# 4. Signing
+apksigner verify --print-certs "$APK" 2>&1
+# → "DOES NOT VERIFY" = CRITICAL
+# → Only v1 signature = WARNING
+
+# 5. File size
+stat -f "%z" "$APK" 2>/dev/null
+# → > 150MB = WARNING (suggest App Bundle .aab)
+
+# 6. DEX count (R8/ProGuard check)
+unzip -l "$APK" 2>/dev/null | grep "classes.*\.dex" | wc -l
+# → > 3 DEX files = WARNING (ensure minification enabled)
+```
+
+---
+
+### Integration with Pipeline Phases
+
+| Phase            | What Happens                                        | Method                          |
+| ---------------- | --------------------------------------------------- | ------------------------------- |
+| Phase 4 (Review) | Accessibility check — **code-level only**           | AI reads source code, no device |
+| Phase 5 (Test)   | Accessibility audit — **device-level, on-demand**   | Bash commands above             |
+| Phase 5 (Test)   | Biometric test — **on-demand**                      | `xcrun simctl keychain`         |
+| Phase 5 (Test)   | Launch time — **on-demand**                         | `adb shell am start -W`         |
+| Phase 6 (Commit) | Archive/APK audit — **release branches, on-demand** | Bash commands above             |
+
+### Graceful Degradation
+
+- No Xcode installed → skip iOS audits, log "Xcode not available"
+- No Android SDK → skip Android audits, log "Android SDK not available"
+- No booted simulator → skip accessibility audit, log "No running simulator"
+- Audits are **enhancements**, never blockers for the pipeline flow

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

@@ -0,0 +1,135 @@
+## Backend API Development Guide
+
+When the task involves backend development (Python/FastAPI, Node.js/Express, Go), follow these patterns.
+
+### API Architecture
+
+| Layer                 | Responsibility                     | Example                                  |
+| --------------------- | ---------------------------------- | ---------------------------------------- |
+| **Router/Controller** | HTTP handling, request/response    | `routes/users.py`, `controllers/user.ts` |
+| **Service**           | Business logic, orchestration      | `services/user_service.py`               |
+| **Repository**        | Data access, database queries      | `repositories/user_repo.py`              |
+| **Model/Schema**      | Data shapes, validation            | `models/user.py`, `schemas/user.ts`      |
+| **Middleware**        | Cross-cutting: auth, logging, CORS | `middleware/auth.py`                     |
+
+### Python/FastAPI Pattern
+
+```python
+# schemas/user.py — Pydantic models
+class UserCreate(BaseModel):
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=100)
+
+class UserResponse(BaseModel):
+    id: int
+    email: str
+    name: str
+    model_config = ConfigDict(from_attributes=True)
+
+# services/user_service.py — business logic
+class UserService:
+    def __init__(self, repo: UserRepository):
+        self.repo = repo
+
+    async def create_user(self, data: UserCreate) -> User:
+        existing = await self.repo.get_by_email(data.email)
+        if existing:
+            raise HTTPException(status_code=409, detail="Email already exists")
+        return await self.repo.create(data)
+
+# routes/users.py — HTTP layer
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("/", response_model=UserResponse, status_code=201)
+async def create_user(data: UserCreate, service: UserService = Depends()):
+    return await service.create_user(data)
+```
+
+### Node.js/Express Pattern
+
+```typescript
+// schemas/user.schema.ts — Zod validation
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+});
+
+// services/user.service.ts — business logic
+export class UserService {
+  constructor(private repo: UserRepository) {}
+
+  async createUser(data: CreateUserInput): Promise<User> {
+    const existing = await this.repo.findByEmail(data.email);
+    if (existing) throw new ConflictError("Email already exists");
+    return this.repo.create(data);
+  }
+}
+
+// routes/users.ts — HTTP layer
+router.post("/", validate(createUserSchema), async (req, res) => {
+  const user = await userService.createUser(req.body);
+  res.status(201).json(user);
+});
+```
+
+### Error Handling
+
+```python
+# Structured error responses
+class AppError(Exception):
+    def __init__(self, status_code: int, detail: str, code: str):
+        self.status_code = status_code
+        self.detail = detail
+        self.code = code
+
+# Global error handler
+@app.exception_handler(AppError)
+async def app_error_handler(request, exc):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": exc.code, "detail": exc.detail}
+    )
+```
+
+### Security Checklist
+
+1. Input validation on ALL endpoints (Pydantic/Zod)
+2. Authentication middleware (JWT/OAuth)
+3. Authorization checks per endpoint (role-based)
+4. Rate limiting on public endpoints
+5. CORS properly configured (not `*` in production)
+6. SQL injection prevention (parameterized queries / ORM)
+7. No secrets in code — environment variables
+8. HTTPS only
+9. Request/response logging (without sensitive data)
+10. Error messages don't leak internals
+
+### Testing
+
+```python
+# Unit test — service layer
+async def test_create_user_duplicate_email():
+    repo = FakeUserRepository(existing_emails=["test@example.com"])
+    service = UserService(repo)
+    with pytest.raises(HTTPException, match="409"):
+        await service.create_user(UserCreate(email="test@example.com", name="Test"))
+
+# Integration test — full endpoint
+async def test_create_user_endpoint(client: AsyncClient):
+    response = await client.post("/users/", json={"email": "new@example.com", "name": "New"})
+    assert response.status_code == 201
+    assert response.json()["email"] == "new@example.com"
+```
+
+### Quality Checklist
+
+1. All endpoints have input validation
+2. Service layer separated from HTTP layer
+3. Error responses are structured and consistent
+4. Tests cover happy path + error paths + edge cases
+5. No N+1 queries (check ORM usage)
+6. Pagination on list endpoints
+7. Health check endpoint exists
+8. Environment-based configuration (no hardcoded values)
+9. Logging with correlation IDs
+10. API documentation (OpenAPI/Swagger auto-generated)