# Workflow Wireframe

This is the Pi-native BMAD operating loop optimized for low token usage, high reliability, and minimal manual routing.

## Operating model

```text
Install Project
  -> official BMAD install
  -> install pi-bmad-flow overlay
  -> start pi

Project Start
  -> /bmad-status
  -> /bmad-next
  -> overlay identifies missing phase artifact

Planning Loop
  -> create PRD
  -> create UX/WDS artifacts
  -> create architecture
  -> create epics and stories
  -> run implementation-readiness gate

Delivery Loop
  -> /bmad-start
  -> overlay selects next ready story
  -> overlay opens a dedicated Pi story session
  -> overlay chooses lean or full packet
  -> BMAD dev workflow executes story inside that story session
  -> /bmad-review
  -> /bmad-gate
  -> story moves forward in sprint-status.yaml

Epic Completion
  -> retrospective
  -> next epic
```

## Human role

You should make fewer routing decisions and more approval decisions.

Your job becomes:

- approve planning outputs
- approve story boundaries
- intervene on ambiguous tradeoffs
- inspect review findings when risk is high

Pi should take over:

- phase detection
- next-step routing
- story pickup
- lean versus full context selection
- story-session setup
- gate selection

## Recommended lane split

Use two planning lanes, but keep one delivery loop.

### Lane A: BMAD core

- `bmad-create-prd`
- `bmad-create-architecture`
- `bmad-create-epics-and-stories`
- `bmad-check-implementation-readiness`

### Lane B: WDS depth

- UX and scenario work
- page specs
- design delivery
- design system artifacts when reusable UI matters

The overlay should treat WDS artifacts as implementation inputs, not parallel decoration. That means UI stories should pull WDS page specs into the packet automatically when present.

## Token minimization strategy

Default to lean packets.

Use full packets only when:

- story is security, auth, billing, migration, infra, or public API related
- project-context is missing or weak
- architecture is still unstable
- story is UI-heavy and depends on multiple WDS artifacts

Lean packet should usually include:

- current story file
- project-context if present
- relevant architecture section
- relevant WDS or UX file only if the story touches UI

Full packet adds:

- PRD context
- prior review or retrospective notes
- additional architecture and WDS support files

## Reliability rules

- Never begin dev without a story file.
- Never start a new story while another is `in-progress`.
- Never skip architecture for medium or large work.
- Never treat WDS outputs as optional for UI-heavy stories.
- Never let operational session metadata become the source of truth over BMAD artifacts.

## Best install experience for your eventual distribution

The cleanest user flow is:

1. `npx bmad-method install`
2. choose your standard BMAD module set
3. `pi install -l your-overlay-package`
4. open `pi`
5. run `/bmad-status`

That keeps installation simple and preserves upstream compatibility.