pi-bmad-flow

Pi-native orchestration overlay for BMAD.

This package is designed to run on top of:

1. upstream pi
2. official BMAD install targeting pi

It adds a thin control plane for phase routing and story-loop automation.

Install in a BMAD project

Install Pi and BMAD first, then install this package into the project:

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

For early access builds before npm publish, install from git or a local path:

```bash
pi install -l git:github.com/<your-org>/pi-bmad-flow
pi install -l /absolute/path/to/pi-bmad-flow

After install, open pi in the project and run:

/bmad-status

Recommended BMAD modules for this overlay:

• core
• bmm
• cis
• wds
• tea
• bmb

Package docs:

• docs/install-model.md
• docs/workflow-wireframe.md

Publish

From pi-bmad-flow/:

npm run check
npm run smoke:fixture
npm publish --access public

prepublishOnly also runs package validation automatically before publish.

If pi-bmad-flow is already taken on npm, choose another unscoped name in package.json, run npm view <name> to confirm availability, and publish that name instead.

Validate against a project

npm run audit:project -- --project-dir /absolute/path/to/project

Expected project layout

The extension expects standard BMAD folders:

• _bmad/
• _bmad-output/planning-artifacts/
• _bmad-output/implementation-artifacts/

Optional:

• design-artifacts/
• docs/

Commands

• /bmad-next
• /bmad-start
• /bmad-review
• /bmad-gate
• /bmad-status
• /bmad-phase

Included overlay skills

• bmad-epic-pipeline-worktree — autonomous epic runner that uses epics.md, sprint-status.yaml, story_location, and the Pi-native story loop
• bmad-phase-handoff
• bmad-story-full
• bmad-story-lean

Current scope

This overlay keeps BMAD adaptation inside Pi-native runtime features instead of prompt wrappers.

Current behavior:

• BMAD detection
• module detection
• artifact-aware phase detection
• sprint status parsing
• next-step routing
• plain-English BMAD intent routing through Pi input interception
• dedicated story sessions created by /bmad-start
• lean versus full packet selection
• WDS-aware packet assembly for UI stories
• TEA-aware review and gate routing
• BMAD-specific compaction summaries
• lightweight BMAD status widget and footer state
• optional LLM access to deterministic BMAD state through the bmad_orchestrator tool
• deterministic story worktree lifecycle through the bmad_worktree tool
• workflow-aware model and thinking presets for routing, story prep, story start, review, and gates

This package does not replace official BMAD workflows. It reduces routing overhead around them.

Optional model policy override

By default, the overlay uses a GPT-only policy aimed at:

• openai-codex/gpt-5.4-mini for routing and status
• openai-codex/gpt-5.4 for story prep, story start, review, and gates
• thinking level as the main optimization knob

The policy is applied both for overlay commands and for common BMAD workflow inputs such as:

• bmad-create-story
• bmad-dev-story
• bmad-create-prd
• bmad-create-architecture
• bmad-create-epics-and-stories
• bmad-code-review
• bmad-testarch-test-review
• bmad-testarch-trace
• bmad-testarch-nfr

You can override the default preset behavior with:

.pi/bmad/model-policy.json

Shape:

{
  "presets": {
    "routing": {
      "model": "openai-codex/gpt-5.4-mini",
      "thinking": "minimal"
    },
    "story-prep": {
      "model": "openai-codex/gpt-5.4",
      "thinking": "low"
    },
    "story-dev": {
      "model": "openai-codex/gpt-5.4",
      "thinking": "high"
    },
    "story-start-lean": {
      "model": "openai-codex/gpt-5.4",
      "thinking": "medium"
    },
    "story-start-full": {
      "model": "openai-codex/gpt-5.4",
      "thinking": "high"
    },
    "review": {
      "model": "openai-codex/gpt-5.4",
      "thinking": "low"
    },
    "gate-light": {
      "model": "openai-codex/gpt-5.4",
      "thinking": "low"
    },
    "gate-strong": {
      "model": "openai-codex/gpt-5.4",
      "thinking": "medium"
    }
  }
}

If you omit model, the overlay falls back to tier-based matching.

Optional worktree policy override

By default, bmad_worktree finalizes story branches into master.

Override that with:

.pi/bmad/worktree-policy.json

Example:

{
  "defaultTargetBranch": "master"
}