brownfield-onboarding git:20260729.d5165d9A

Immutable. This exact content is served forever at /api/v1/blob/178c20f085e7879a.

---
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.
- **Neither iOS nor Android:** that is a normal answer, not a dead end. Read the package manifests —
  `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `pom.xml` — plus `Dockerfile`,
  `Procfile`, and whether there is a UI surface or a binary entry point. `role-activation`'s
  detection table maps what you find to one of the seven product types.
- Record the raw findings; do not guess where you can read. The product type you land on decides
  which specialists ever get spawned, so an ambiguous tree earns one question to the user.

## 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.