brownfield-onboarding

name	brownfield-onboarding
description	Use when pointing the team at an EXISTING, already-built app instead of a blank project — detects the stack, reverse-engineers the as-built architecture, and classifies remediation work as safe-to-auto-fix vs risky-needs-approval. Triggered by /app-onboard, /app-audit, and by /app-run when it detects a non-empty app directory.

Brownfield onboarding

Greenfield commands generate vision → PRD → architecture → code. For an app that already exists, you go the other way: read the code, snapshot what's there, grade it against the House KB, and plan the gap. This skill is the procedure for the "read and understand" half.

When to use

• /app-onboard (adopt an existing codebase) and /app-audit (grade it) both start here.
• /app-run invokes this when the target directory already contains an app (see Detection).

Step 1 — Detect the app

Scan the target directory (not deeper than ~3 levels) to establish ground truth before any agent reasons about it:

• iOS: *.xcodeproj / *.xcworkspace / Package.swift; read project.yml (XcodeGen), *.xcconfig, Info.plist, Package.resolved. Note Swift version, min iOS target, SwiftUI vs UIKit.
• Android: settings.gradle*, app/build.gradle(.kts), gradle/libs.versions.toml. Note Kotlin/AGP, compileSdk/minSdk/targetSdk, Compose vs XML, the module list.
• Both / signals: existing CLAUDE.md, README, docs/, CI under .github/workflows, google-services.json/GoogleService-Info.plist presence (Firebase), ads/billing SDKs in deps.
• Record the raw findings; do not guess where you can read.

Step 2 — Reverse-engineer the as-built baseline

Produce the docs the team normally writes, but describing what exists, not what's wished for:

• docs/20-architecture.md — the actual stack, module/folder layout, state/persistence/DI/nav patterns in use, backend, CI, signing. Mark anything inferred as (inferred).
• A feature inventory in docs/10-prd.md — the screens/features that exist, derived from the code (navigation graph, view/screen files). Ask the user only for product intent you cannot read.
• CLAUDE.md at the project root if missing — seeded from the as-built architecture + the House KB, pinning the real stack, build/run commands, and canonical type/property names found in the code.

Do not refactor anything in this step. You are taking a photograph, not renovating.

Step 3 — Classify every remediation as Safe or Risky

When /app-audit turns findings into work, tag each one so safe fixes can be automated and risky changes are gated behind a plan + human approval:

Safe (auto-fix, normal code-review gate):

• Accessibility labels / Dynamic Type / touch-target fixes
• Hardcoded color/spacing/font → design-token swaps
• String localization (String(localized:) / strings.xml)
• Missing analytics events; wrapping calls in the existing consent gate
• Lint/detekt/ktlint/SwiftLint fixes, dead-code removal, print/Log.d → logger
• Mechanical correctness: missing transaction.finish(), missing @Index, missing @ForeignKey index

Risky (write a ticket + a short plan, require approval before touching code):

• Any database/schema migration or change to persisted user data
• Architecture refactors — layering, module boundaries, Display-DTO introduction
• Concurrency model changes — removing Combine/@Published, actor isolation rewrites
• Navigation restructure, DI overhaul
• Billing/entitlement logic changes, ad-gating/consent-flow rework
• Anything that changes app behavior a user would notice

Default posture: fix Safe automatically; for Risky, propose and wait. Never silently perform a risky change during an audit.

Step 4 — Hand off

Onboarding hands to /app-audit. Audit writes docs/80-audit.md and a remediation backlog of AUDIT-NNN tickets (each carrying its severity, the violated House KB rule, and Safe/Risky tag), then the normal build loop closes them.

Anti-patterns

• Reasoning about the app from its README alone — read the build files and code; READMEs drift.
• Rewriting code during onboarding/audit "while you're in there" — separate seeing from changing.
• Treating a risky refactor as safe because it's small — risk is about blast radius, not diff size.