First 30 Minutes with GAIA (Brownfield) — Onboarding an Existing Codebase

This walkthrough is the brownfield companion to the greenfield First 30 Minutes. Use it when you have an existing codebase you want to bring under GAIA management. Brownfield onboarding inspects what is already there, synthesizes a PRD from observed behavior, runs gap analysis against the synthesized PRD, and produces a backlog you can plan a sprint from.

Overview

The brownfield path collapses Steps 2--7 of the greenfield tutorial (init → brainstorm → product brief → PRD → architecture → epics) into a single /gaia-brownfield invocation with nine phases. The output feeds back into the greenfield lifecycle at /gaia-create-story → /gaia-sprint-plan → /gaia-dev-story, so once Steps 1--11 below complete, you re-join the greenfield walkthrough at its Step 8.

Step 0 -- Install the plugin

Install the GAIA plugin into your Claude Code environment. Refer to the GAIA repository README for platform-specific installation instructions. Once installed, all /gaia-* commands become available in any Claude Code session.

Expected duration: 2 minutes.

Step 1 -- Run /gaia-brownfield on the existing repo

/gaia-brownfield ./my-existing-project

Phase 1 attempts to read .gaia/config/project-config.yaml. If it is absent, the skill now degrades gracefully -- it seeds safe defaults, mkdir -p's the artifact tree, and continues. Users coming from the pre-fix behaviour would have hit a HALT here with resolve-config.sh failed: no config path; on the current build the skill no longer requires a pre-existing config to start.

If you do want better results, supply a minimal .gaia/config/project-config.yaml ahead of time -- the manifest detector uses any declared stack/compliance hints to improve its codebase classification.

Expected duration: 1 minute (skill prelude only).

Step 2 -- Reconcile detected stack vs config

Phase 1 of brownfield runs the manifest detector. The detector first scans the file system for signal files (package.json, requirements.txt, go.mod, etc.). When the canonical signal files are absent -- common for repos that mix multiple stacks, vendored dependencies, or non-standard layouts -- the detector falls back to stacks[].language from .gaia/config/project-config.yaml as the config-fallback source.

Inspect the detected stacks at this step. If the detector misclassified your project, edit project-config.yaml via /gaia-config-stack and re-invoke brownfield; the detector picks up the corrected config on the next run.

Expected duration: 2 minutes (inspection + optional config edit).

Step 2b -- Enable deterministic tools (tier-2 via Docker)

The codebase scan in the next step is far stronger when the deterministic-tools battery is enabled: a Docker runner image (gaia-tools) that bundles the tier-2 scanners -- grype (CVE), syft (SBOM), and the dead-code analysers -- so the gap analysis is tool-verified rather than heuristic. This is opt-in; without it the scan still runs but the CVE/SBOM/dead-code findings are skipped and the gap list is marked heuristic.

Enable it once, before the scan:

  1. Point the brownfield runner at Docker and name the image via /gaia-config-brownfield: set tools.runner: docker and tools.image (the published gaia-tools image tag).
  2. Build or pull the gaia-tools image so the scanners are available to the runner.
  3. Confirm the runner sees tier-2 with /gaia-doctor -- it reports the tier the host can actually reach (tier-2 once the image is present).

If you skip this step, continue to Step 3 -- the scan degrades gracefully to the heuristic gap list and prints a scan-fidelity banner naming the absent tools.

Expected duration: 3--5 minutes (first-time image pull/build), then cached.

Step 3 -- Phase 2: codebase scan and brownfield-arch

Phase 2 walks the source tree and auto-generates a brownfield architecture document covering technology selection, components, data architecture, API design, infrastructure, and security posture -- all reverse-engineered from the codebase. No PRD exists yet; the architecture is descriptive, not prescriptive.

Artifact produced: .gaia/artifacts/planning-artifacts/architecture.md (brownfield mode, descriptive).

Expected duration: 3--5 minutes for a typical repo.

Step 4 -- Phase 3: PRD synthesis from observed behavior

Phase 3 synthesizes a Product Requirements Document by inferring functional requirements from observed behaviour: endpoint surfaces, test fixtures, configuration switches, and feature flags become candidate FRs; non-functional requirements come from the NFR assessment that runs in parallel.

The synthesized PRD is a starting point, not ground truth. Review it and run /gaia-edit-prd to refine wording, merge duplicates, or split overloaded FRs before gap analysis consumes it.

Artifact produced: .gaia/artifacts/planning-artifacts/prd.md (synthesized from observed behaviour).

Expected duration: 3 minutes.

Step 5 -- Phase 4: gap analysis

Phase 4 runs seven parallel scans (doc-code mismatches, hardcoded values, integration seams, runtime behaviour, security posture, config contradictions, dead code) plus an execution pass against the existing test suite. Each scan emits gap entries; Phase 4's consolidator deduplicates by evidence location, ranks by severity, and produces a single gap report.

Artifact produced: .gaia/artifacts/planning-artifacts/consolidated-gaps.md.

Expected duration: 5--10 minutes for the parallel scan battery.

Step 6 -- Phase 5: epics + stories rooted in the gap analysis

Phase 5 breaks the consolidated gap report into epics and stories. Unlike the greenfield path -- where epics derive from PRD scope -- brownfield epics are gap-rooted: each epic groups related gap entries into a deliverable unit. Stories carry acceptance criteria, risk ratings, and dependency links exactly as they do in greenfield.

Artifact produced: .gaia/artifacts/planning-artifacts/epics-and-stories.md.

Expected duration: 3 minutes.

Step 7 -- Phase 6: brownfield assessment

Phase 6 emits the user-facing brownfield assessment: detected tech stack, capabilities, classification (application / infrastructure / platform), compliance posture, and a top-level summary of what brownfield found. The assessment header carries schema_version: 2.0.0 -- this is the wire version the downstream consumers expect. If you see anything else, run /gaia-migrate v1 v2 to align the schema.

Artifact produced: .gaia/artifacts/planning-artifacts/brownfield-assessment.md (schema_version: 2.0.0).

Expected duration: 1 minute.

Step 8 -- Re-run brownfield-arch through /gaia-create-arch

The Phase 2 brownfield architecture is descriptive -- it documents what exists. To get the Review-Findings section (the adversarial review pass that produces actionable architecture-level findings), re-run the brownfield architecture through /gaia-create-arch: 

/gaia-create-arch --from-brownfield

This is a known caveat: brownfield's Phase 2 stops at the descriptive architecture; the Review-Findings layer only writes when /gaia-create-arch ingests the brownfield draft as input.

Expected duration: 3 minutes.

Step 9 -- Phase 7: documentation-site scaffold

Phase 7 scaffolds the local documentation/ directory with the same HTML doc-site shape this site uses: command pages keyed off detected stacks, category pages, a glossary stub, and a lifecycle diagram. The scaffold is a starting point you can edit; regeneration is non-destructive (copy-if-absent semantics).

Artifact produced: documentation/ directory at the project root.

Expected duration: 2 minutes.

Step 10 -- Phase 8: adversarial review + code-verified gates

Phase 8 runs three sub-gates:

  • 8a -- consolidator quality gate. Verifies the consolidated gap report meets schema and rank consistency.
  • 8b -- adversarial review. Critical findings from the adversarial pass downgrade to WARNING under YOLO. The downgrade is intentional -- it keeps the YOLO pipeline forward-moving when an adversarial reviewer is being overcautious -- but you still see the WARNING in the run summary.
  • 8c -- code-verified findings. Findings here are grounded in actual code inspection (not heuristics) and halt unconditionally regardless of YOLO mode. Resolve every 8c finding before continuing.

Expected duration: 5--8 minutes.

Step 11 -- Phase 9: handoff to greenfield lifecycle

Phase 9 emits the handoff message pointing you at the greenfield path. From here you re-join the greenfield walkthrough at Step 8:

  1. /gaia-create-story for each story in the brownfield-generated backlog.
  2. /gaia-sprint-plan to plan the first brownfield sprint.
  3. /gaia-dev-story to implement the first gap-driven story.
  4. /gaia-review-all to run the six-review battery on the implemented story.

The brownfield-specific phases are now behind you; the rest of the loop is identical to the greenfield walkthrough.

Caveats

  • /gaia-init's CI workflow scaffold is a deliberate exit 1 stub until /gaia-ci-setup runs. On a brownfield repo that already has tests asserting CI shape (e.g., a pytest test that checks for actions/setup-python@v5 in the workflow), the stub fails those pre-existing assertions until /gaia-ci-setup replaces the stub with a real workflow. This is intentional fail-loud behaviour documented at ci-scaffold-stub, but expect a brief red window between /gaia-init and /gaia-ci-setup on any repo with CI-shape tests.
  • Zero-config brownfield works, but produces best results with a minimal config. The skill can run on a fresh repo with no .gaia/config/project-config.yaml -- the prelude seeds defaults and continues. However, supplying a minimal config (project shape, declared stacks, compliance regime) before invoking brownfield significantly improves stack detection, suppresses spurious defaults, and produces a more accurate PRD.
  • compliance.ui_present: false suppresses the [web] platforms default. A headless backend project should set compliance.ui_present: false in its config. The same flag suppresses /gaia-create-ux prerequisites (no UX design needed for a headless service) and excludes the E2E tier from the coverage formula (no browser-driven E2E is meaningful without a UI).
  • Detected schema_version must be 2.0.0. The brownfield assessment header carries the schema version; downstream consumers (PRD, epics, test-plan generators) hard-require 2.0.0. Older schemas migrate via /gaia-migrate v1 v2.
  • brownfield-arch is descriptive only. The Phase 2 architecture documents what exists; it does not include the Review-Findings adversarial section. Re-run the brownfield draft through /gaia-create-arch --from-brownfield (Step 8 above) to get the Review-Findings layer.
  • Phase 8b downgrades CRITICAL to WARNING under YOLO; 8c does not. YOLO mode is a "keep moving" lever for adversarial heuristics, not for code-verified findings. If 8c halts, the finding is grounded in actual code -- resolve it.

What to read next