madcompany

Brownfield development

For an app that already exists. Instead of a PRD, the lead scans the codebase and writes a map the whole team reads before working: the stack, modules, commands, conventions, risky areas and who owns which folders. Then the team ships your changes in small releases.

Plan with: a codebase scan (/mc-scan). BMad's /bmad-project-context can help but isn't needed.

Releases

R1Onboarding

The codebase map, working checks (typecheck, lint, tests) and a first small change, so the team proves it can ship here.

R2+Next change set

A batch of features and fixes you asked for, with screens first if the change is visible.

Steps

  1. Terminal
    npx madcompany init --mode brownfield

    Set up inside your existing repo, then keep npx madcompany hq running

  2. Claude Code
    /mc-scan

    Map the codebase: stack, modules, commands, conventions, owners, services

  3. Claude Code
    /mc-staff

    Pick the team to match the codebase, then restart Claude Code once

  4. HQ
    Inbox → Request a change

    Or just tell the lead what you want changed or fixed

  5. Claude Code
    /mc-plan-release

    R1: onboarding plus a first small change set

  6. Claude Code
    /mc-ui-sprint

    Only if the change is visible

  7. Claude Code
    /mc-start

    The team works; you watch HQ and answer Inbox and Human help

  8. HQ
    Releases → Approve

    Or Request changes

  9. Terminal
    npx madcompany ship R1

    Merge into main and tag; push and deploy are in Human help

What the scan finds

npx madcompany scan (which /mc-scan runs first) looks at the repo without running or changing anything, and never reads .env:

It finds From
Languages, package manager, frameworks package.json, lockfiles, pyproject.toml, go.mod, Cargo.toml…
Check commands for the merge queue scripts like typecheck, lint, test; pytest, go test, cargo test
Workspaces and folders by size workspaces, apps/*, packages/*
Third-party services (for Human help) dependencies like stripe, @supabase/*, @aws-sdk/*, @sentry/*
The env keys the app expects .env.example
CI and docs .github/workflows, README, CLAUDE.md, AGENTS.md

The lead then reads the code that matters and writes docs/design/codebase/overview.md, which appears in HQ → Library → Architecture.

You and the team

You

  • Tell the lead what you want changed or fixed, or use HQ → Inbox → Request a change
  • Provide access the team can't get itself, through Human help: keys, a staging URL, test accounts, a copy of real data
  • Review each release; approve or ask for changes

The team

  • R1 proves it can ship here: working checks, the codebase map and one small real change
  • Follows the existing conventions, and keeps changes in scope
  • Never rewrites working code that isn't part of the ticket; bigger refactors go to you as a question
  • If the checks are already red on the current code, the first ticket fixes that