# Install Model

`pi-bmad-flow` is a thin overlay. It should not replace either `pi` or BMAD.

## Recommended install order

1. Install upstream `pi`
2. Install official BMAD into the project
3. Install `pi-bmad-flow` project-locally

```bash
npm install -g @mariozechner/pi-coding-agent
cd /path/to/project
npx bmad-method install
pi install -l /absolute/path/to/pi-bmad-flow
```

## BMAD installer choices

Use the official BMAD installer and keep your existing module selection:

- `BMad Core Module`
- `BMad Method Agile-AI Driven-Development`
- `BMad Builder`
- `BMad Creative Intelligence Suite`
- `Test Architect`
- `Whiteport Design Studio`

That gives you the official artifact model under `_bmad/` and `_bmad-output/`. `pi-bmad-flow` reads that structure and adds orchestration on top.

## Why this install shape is correct

- Upstream `pi` stays updateable without maintaining a fork.
- Official BMAD stays updateable without maintaining a fork.
- Your custom behavior lives in one overlay package that can evolve independently.
- If BMAD changes, the overlay can adapt at the routing layer instead of forcing a reinstall strategy rewrite.

## Day-to-day usage

Inside a BMAD project:

```bash
pi
```

Then use:

- `/bmad-status`
- `/bmad-next`
- `/bmad-start`
- `/bmad-review`
- `/bmad-gate`

`/bmad-start` should be the normal entry into implementation. It creates a dedicated Pi story session, attaches lean or full packet guidance, and keeps the planning session clean.

## Distribution model for your version

Your install story should become:

1. User installs upstream `pi`
2. User runs official BMAD installer with the module set you standardize
3. User installs your overlay package

Later, you can wrap this with a bootstrap script, but the bootstrap should still execute the same three layers under the hood. Do not hard-fork BMAD unless upstream compatibility stops mattering.