/gaia-brownfield

What it does

/gaia-brownfield onboards an existing codebase into GAIA. It performs deep project discovery, runs multiple automated scans (documentation gaps, hardcoded values, security posture, integration seams, dead code, and more), assesses non-functional requirements, consolidates all findings into a gap-focused PRD, and generates an architecture document -- giving you a complete GAIA artifact set ready for sprint planning.

When to use it

• You have an existing project with code and want GAIA to understand it and identify gaps.
• You want GAIA-managed artifacts (PRD, architecture, epics) generated from your current codebase rather than from scratch.

For brand-new projects with no code, use /gaia-init instead.

Prerequisites

• Existing codebase (any size, any stack). The target directory should contain source code files for meaningful scan results.
• GAIA plugin installed. The GAIA plugin must be registered in your Claude Code environment.
• Platform support. The GAIA orchestration scripts run on macOS, Linux, and Windows (via WSL2 or Git Bash). The deterministic-tools chain (detect-signals.sh, brownfield orchestrator.sh, validate-platform-stack.sh, the dead-code adapters) is bash-3.2 compatible — macOS users on the system-default /bin/bash 3.2.57 no longer hit the prior silent Tier-0 degradation. Bash 4.0+ is still recommended (longer-form scripts under plugins/gaia/scripts/lib/ still benefit from declare -A / mapfile performance) but is no longer required for the headline Tier-2 scan to function. On macOS, brew install bash brings in a current release; on Windows, prefer WSL2 with the Ubuntu image or Git Bash (which ships bash 4+). The tools the scanners consume (grype, syft, cdxgen, vulture, semgrep) are independent of bash version and can be supplied either via host PATH or via the bundled gaia-tools Docker image (/gaia-config-brownfield → brownfield.tools.runner: docker).
• Optional: a minimal .gaia/config/project-config.yaml. The skill detects a missing config and seeds safe defaults, mkdir -p's the artifact tree, and continues. Prior to this fix, the skill exited 1 at Phase 1 entry on zero-config repos with resolve-config.sh failed: no config path; the documented workaround was to run /gaia-init first to bootstrap a config, then re-invoke brownfield. That workaround is no longer required on the current build.

  Caveat. Zero-config is supported, but the seeded defaults are minimal — they cover only the bare keys the scan loop needs. For full deterministic-tools support (Tier 2 scanners, grype, runner selection) the brownfield.* block is populated by /gaia-config-brownfield, NOT by /gaia-init — /gaia-init's full-phase config does not emit a brownfield top-level section. Recommended sequence on an existing codebase: /gaia-init for the base config, then /gaia-config-brownfield to add the brownfield block, then /gaia-brownfield for the scan loop.

• If a project-config.yaml is present, its schema_version must be 2.0.0 (the project-config.schema.yaml is kept in sync with the JSON schema). Older schemas migrate via /gaia-migrate v1 v2.

Orchestration mode

When /gaia-brownfield starts in subagent mode (Mode A -- the default), the framework emits a one-shot warning to your conversation. The warning text:

────────────────────────────────────────────────────────────────────────────
GAIA orchestration: running in subagent mode (Mode A)

The skill you're invoking belongs to a class (heavy-procedural or
conversational) whose output benefits from cross-step context. Mode A
dispatches each sub-agent in its own forked context, so context may
be lossy between steps — sub-agents return summaries, not full reasoning.

For the full-fidelity experience, enable Mode B (Agent Teams):
  1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment.
  2. Add orchestration.mode: team to .gaia/config/project-config.yaml.

Mode B uses persistent teammates that preserve in-conversation state
across dispatches. See the orchestration contract for details.

This warning is shown once per session.
────────────────────────────────────────────────────────────────────────────

Why Mode B is better for this command

The /gaia-brownfield skill declares orchestration_class: heavy-procedural in its SKILL.md frontmatter. Heavy-procedural skills produce output that benefits from cross-step context -- under Mode A every sub-agent dispatch runs in its own forked context and can only return a summary back to the orchestrator, losing the full reasoning trace of every prior step. Mode B uses persistent teammates that retain in-conversation state across dispatches, so each agent's contribution can build on what was said before instead of receiving only a summary.

How to enable Mode B

Both steps are required. If either is missing, the framework falls back silently to Mode A and the warning fires again on the next session.

Step 1 -- set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your shell rc file to persist across sessions, or set it in Claude Code's settings.json.

Step 2 -- add the YAML block to .gaia/config/project-config.yaml:

orchestration:
  mode: team

One-shot semantics

The warning is emitted once per Claude Code session. A marker file at _memory/checkpoints/orchestration-warning-shown.<session-id> suppresses the warning for the rest of the session. Starting a new session re-emits the warning once.

Caveat. The one-shot contract depends on CLAUDE_SESSION_ID being exported. Without it, the marker falls back to the orchestrator PID, so each fresh shell becomes a new "session" from the dedupe's point of view and the warning re-fires on every command invocation. Operators who see repeat warnings on every command should export CLAUDE_SESSION_ID (any stable per-session value).

How to invoke

/gaia-brownfield

Scans the current directory.

/gaia-brownfield ./my-existing-project

Scans a specific project path.

What it does step by step

1. Deep project discovery Scans the codebase to detect the tech stack, frameworks, capability flags (APIs, events, frontend, infrastructure), and classifies the project type (application, infrastructure, or platform). Also auto-detects configuration signals and drafts a .gaia/config/project-config.yaml if one does not exist. Writes a brownfield assessment and project documentation artifact.
2. Documentation scans Runs parallel scans based on detected capabilities: API documentation, UX assessment, event catalog, and dependency mapping. Each scan produces its own artifact.
3. Deep analysis scans Runs seven parallel scans for gaps the structural analysis misses: doc-code mismatches, hardcoded values, integration seams, runtime behavior, security posture, config contradictions, and dead code. Each produces a gap report.
4. Test execution Runs your existing test suite (auto-detected) and converts failing tests into gap entries. Non-blocking -- test failures do not halt the workflow.
5. Test environment generation If test infrastructure is detected (test runners, CI config, Docker test config, browser matrix), generates a config/test-environment.yaml via the shared manifest generator. If the file already exists, copy-if-absent semantics preserve it byte-identical; the legacy merge / skip / overwrite prompt is no longer surfaced because the canonical generator is non-destructive.
6. NFR assessment Analyzes the codebase for non-functional requirements: code quality, security posture, performance, accessibility, test coverage, and CI/CD maturity. Also generates a performance test plan.
7. Gap consolidation Merges all gap entries from every scan, deduplicates by evidence location, ranks by severity, and produces a single consolidated gap report.
8. PRD generation and review Creates a gap-focused PRD (covering only what needs to be built or fixed, not existing features), runs an adversarial review, and verifies all gap claims against the actual codebase.
9. Architecture and ground-truth bootstrap Generates an architecture document in brownfield mode. Optionally seeds GAIA's internal knowledge base with facts from the assessment.

Inputs

Outputs

Example session

> /gaia-brownfield ./my-api

Phase 1 -- Deep Project Discovery
  Tech stack: Node.js 20, Express 4, PostgreSQL 15
  Capabilities: APIs (yes), Events (no), Frontend (no)
  Project type: application
  Config signals detected: node stack, github-actions CI
    Verdict: PASS -- merged into project-config.yaml

Phase 2 -- Documentation Scans
  API Documenter: 14 endpoints documented, 3 undocumented
  Dependency Mapper: 42 dependencies, 2 critical CVEs

Phase 3 -- Deep Analysis (7 scans)
  | Scan              | Status  | Duration |
  |-------------------|---------|----------|
  | doc-code          | success | 12s      |
  | hardcoded         | success | 9s       |
  | integration-seam  | success | 14s      |
  | runtime-behavior  | success | 11s      |
  | security          | success | 8s       |
  | config-contradict | success | 4s       |
  | dead-code         | success | 11s      |

Phase 7 -- Gap Consolidation
  Raw gaps: 47 | Duplicates removed: 12 | Final: 35
  By severity: 3 critical, 8 high, 14 medium, 10 low

Phase 8 -- PRD generated (brownfield mode, gap-focused)
Phase 9 -- Architecture generated

Done. Run /gaia-create-epics to break the gaps into stories.

What to run next

• /gaia-create-epics -- break the gap-focused PRD into epics and stories.
• /gaia-edit-prd -- refine the generated PRD before creating epics.
• /gaia-threat-model -- create a security threat model from the architecture.

Troubleshooting

A scanner timed out or errored

Individual scan failures do not halt the overall workflow. The scan diagnostic table shows which scans succeeded and which failed. Failed scans produce a partial gap row tagged with the failure reason. Re-run the command to retry, or inspect the specific scan report for details.

"NFR assessment not found" or "Performance test plan not found"

Both artifacts are required. If the test-architect agent was unavailable, stub files are written. Run /gaia-nfr or /gaia-perf-testing to generate the real content.

Detected config drift -- stack detector falls back to project-config.yaml

Phase 1's manifest detector first scans the file system for signal files (package.json, requirements.txt, go.mod, Cargo.toml, etc.). When the canonical signal files are absent -- common for repos that vendor dependencies, mix multiple stacks under a non-standard layout, or ship only compiled binaries -- the detector falls back to stacks[].language from .gaia/config/project-config.yaml as the config-fallback source.

If the detector still misclassifies your project, override by editing the config explicitly via /gaia-config-stack and re-running brownfield. The detector picks up the corrected stacks on the next invocation.

test-environment.yaml already present

Phase 5 uses copy-if-absent semantics: if config/test-environment.yaml already exists, it is preserved byte-identical and the review pause is skipped. To regenerate from scratch, move the existing file aside before re-running brownfield.

I keep seeing the GAIA orchestration warning every time I start this command

The warning is shown once per session, so if it fires again that's a new session -- not a per-skill repeat. If you want to silence it entirely, enable Mode B (full-fidelity orchestration via Agent Teams). Both of these conditions must be true:

• echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS returns 1 (not empty)
• .gaia/config/project-config.yaml contains:

  orchestration:
    mode: team

If either is missing the framework silently uses Mode A and re-emits the warning each session.

Related commands