Harmonizing Two AI Agent Systems - A Practical Journey

What happens when you have two capable AI agent systems that each excel at different things, but cannot work together? This article documents our journey integrating BMAD’s deterministic workflows and rich agent personas with PAI’s intent-based activation and flexible orchestration. The solution was not to choose one over the other, but to compose them at different layers of the stack, preserving both strengths while creating something more powerful than either alone.

Figure. The challenge of integrating two AI agent systems: BMAD’s structured workflows meet PAI’s natural language activation.

The Problem: Two Good Systems That Do Not Talk

We faced a problem many AI practitioners encounter: two capable systems that each did something well, but could not work together.

BMAD (BMad Method) [3][4] is a structured workflow system with 30 specialized agent personas. Mary the Business Analyst brings systematic requirements elicitation. Winston the Architect provides rigorous system design. Carson the Brainstorming Coach offers 35 creative techniques. Each agent has a rich identity including communication style, principles, and expertise areas. The workflows are deterministic, template-driven, and produce consistent artifacts like PRDs, tech specs, and game design documents.

PAI (Personal AI Infrastructure) [1][2] is a personal AI system built around Claude Code. It uses natural language activation, meaning you say “I need a PRD for…” rather than memorizing explicit commands. It excels at parallel agent execution and flexible model selection, sending grunt work to Haiku and complex reasoning to Opus.

Both systems worked. Neither talked to the other. Using BMAD meant abandoning PAI’s natural invocation. Using PAI meant losing BMAD’s rich personas and validated templates.

The question was not “which system is better?” It was “how do we preserve both strengths?”

The Key Insight: Layered Architecture

The breakthrough came from recognizing that BMAD and PAI operate at different layers of the stack.

Figure. The composition pattern: PAI handles activation and routing, BMAD handles execution with rich personas.

PAI handles activation. When we say “let’s brainstorm ideas for improving onboarding,” PAI’s intent matching recognizes this as a brainstorming request and routes it appropriately.

BMAD handles execution. Once routed, BMAD’s Carson persona takes over with his 35 brainstorming techniques, structured facilitation approach, and energetic communication style.

Both systems contribute what they do best. Neither replaces the other.

This is the composition pattern in practice: different systems operating at different layers, each contributing their strengths without stepping on each other’s capabilities.

The Implementation: BmadBridge

The integration took shape as a PAI skill [5][6] called BmadBridge. Here is what it does:

1. Intent-Based Routing

Instead of memorizing BMAD commands like *prd or *brainstorm, we just talk naturally:

The skill’s USE WHEN triggers handle the pattern matching. No special syntax required.

2. Pre-Extracted Personas

BMAD’s agent files are verbose, containing XML-embedded markdown with activation protocols, menus, and persona definitions. Loading them at runtime was slow and cluttered the context.

The solution: extract just the persona essentials to clean YAML files.

# personas/analyst.yaml
id: analyst
name: Mary
title: Business Analyst
icon: "..."
module: bmm

persona:
  role: "Strategic Business Analyst + Requirements Expert"
  identity: |
    Senior analyst with deep expertise in market research,
    competitive analysis, and requirements elicitation...
  communication_style: |
    Analytical and systematic in approach...
  principles: |
    Every business challenge has underlying root causes...

Now persona loading is instant. The agent’s voice comes through without the overhead.

3. Unified Output Location

BMAD workflows originally scattered outputs across project-specific locations. The integration unified everything:

~/.claude/History/bmad/
├── prd/           # PRD documents
├── tech-spec/     # Technical specifications
├── stories/       # User stories
├── onto/          # Ontology artifacts
└── sar/           # Software archaeology docs

One place to find all structured artifacts, regardless of which workflow created them.

The Agent Roster: 30 Specialists

Why Agent Personas Matter

A generic “assistant” produces generic outputs. But when an agent has a defined identity, communication style, and guiding principles, something interesting happens: the quality of work improves because the agent approaches problems through a consistent, specialized lens.

Consider the difference between asking “an AI” to write a PRD versus asking John, an Investigative Product Strategist who believes that every feature request hides deeper user needs waiting to be uncovered. John does not just fill in template fields. He probes, questions assumptions, and structures requirements around validated user problems. His communication style is direct and evidence-based. His principles guide him to prioritize clarity over completeness.

This is not role-playing for entertainment. Each BMAD agent encodes four elements that shape their work:

When Carson the Brainstorming Coach facilitates ideation, his 35 techniques and energetic style produce different results than a generic “generate ideas” prompt. When Dr. Ada the Software Archaeologist explores legacy code, her systematic excavation approach uncovers patterns that a simple code review would miss.

The integration preserves all 30 personas across 6 modules. Here is what each brings to the table:

Core and Builder Modules (The Orchestrators)

Figure. BMad Master and BMad Builder in their control room, overseeing all agent activities across the BMAD ecosystem. Like the Architect in the Matrix, they orchestrate workflows and build new capabilities.

BMM Module (SDLC Agents)

Figure. The SDLC team gathered in their scrum room: from Mary’s analytical insights to Sally’s user advocacy, each specialist brings distinct expertise to the software development lifecycle.

BMM Module (Game Development Agents)

Figure. The game development specialists in their creative studio: Cloud Dragonborn architects systems, Samus Shepard designs gameplay, and Link Freeman implements with performance precision.

CIS Module (Creative and Innovation)

Figure. The CIS module specialists collaborating in their futuristic innovation lab: Carson energizes ideation, Dr. Quinn analyzes possibilities, Maya shapes designs, Victor strategizes disruption, and Sophia weaves narratives.

SAR Module (Software Archaeology)

Figure. The SAR module specialists excavating a software archaeological site: Dr. Ada examines ancient artifacts, Atlas maps tech hieroglyphics, Morgan curates documentation scrolls, Sage studies glowing relics, Quinn analyzes vintage equipment, and Nova plans the modernization path.

ONTO Module (Ontology Development)

Figure. The ONTO module specialists: six agents who bring formal knowledge engineering, philosophical rigor, and domain expertise to ontology development.

These agents are not interchangeable. Ask Mary to architect a system and you will get analysis, not architecture. Ask Winston to facilitate brainstorming and you will get structured evaluation, not creative exploration. The specialization is the point.

What Actually Works: Test Results

Theory is nice. Does it actually work?

Brainstorming Workflow Test

Request: “Let’s brainstorm”

Result:

• Intent correctly routed to brainstorming workflow
• Carson’s persona loaded from YAML
• 35 techniques displayed for selection
• Interactive facilitation worked as expected
• Carson’s energetic voice came through naturally

PRD Workflow Test

Request: PRD for an APNG frame extractor CLI

Result:

• John’s PM persona loaded correctly
• Template populated with 7 functional requirements, 3 non-functional
• Epic and 6 user stories generated
• Output saved to ~/.claude/History/bmad/prd/
• Yolo mode (skip confirmations) worked when requested

Both workflows produced real, usable artifacts. The integration is not theoretical. It is production-ready.

Lessons Learned

1. Do Not Choose, Compose

The instinct when facing two overlapping systems is to pick one and abandon the other. That is often wrong. The better question: “What does each system do better, and how can they work together?”

BMAD is not better than PAI. PAI is not better than BMAD. Together, they are better than either alone.

2. Personas Have Value

PAI’s original agents were functional but personality-free, just “intern,” “engineer,” “researcher.” They got work done, but interactions felt mechanical.

BMAD’s personas reminded us that agent identity matters. When Carson facilitates a brainstorming session, his enthusiasm and technique mastery create a different experience than a generic “brainstorming agent.” Mary’s systematic analysis feels different from Winston’s architectural thinking.

Personality is not fluff. It shapes how agents approach problems.

3. Pre-Extract for Performance

The temptation with rich configuration files is to load them dynamically. But parsing verbose XML-embedded markdown at runtime is slow and wastes context tokens.

Pre-extracting the essentials (personas to YAML, workflows to routing tables) made the system snappier without losing capability. The full files remain available for edge cases; the extracts handle the common path.

4. Unify Output Locations

Nothing kills workflow adoption faster than not being able to find outputs. BMAD’s original per-project output locations made sense for isolated BMAD usage but created chaos in an integrated system.

One output location (~/.claude/History/bmad/) with clear subdirectories solved this immediately.

The Architecture Pattern

For those facing similar integration challenges, here is the pattern that emerged:

Figure. The general integration pattern: Intent Layer (routing) feeds into Execution Layer (personas and workflows), producing Artifacts stored in unified locations.

This pattern is not BMAD-specific or PAI-specific. It is a general approach to integrating intent-based systems with deterministic workflow systems.

┌─────────────────────────────────────────────────────────┐
│                    INTENT LAYER                         │
│  Natural language → Pattern matching → Route selection  │
└───────────────────────────┬─────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                  EXECUTION LAYER                        │
│  Persona loading → Workflow execution → Template fill   │
└───────────────────────────┬─────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                   ARTIFACT LAYER                        │
│  Unified output → Consistent naming → Easy retrieval    │
└─────────────────────────────────────────────────────────┘

The Manifest Translator Now Exists

The bmad-translator CLI now automates routing table generation, scanning 97 workflows and 30 agents, generating 670 intent triggers automatically.

bmad-translator scan      # Discover workflows + agents
bmad-translator generate  # Generate routing.yaml
bmad-translator validate  # Check if sync needed

Agent-based triggers mean you can now invoke agents by name or role:

• “Talk to Winston” loads Winston (Architect)
• “Ask Dr. Ada” loads Dr. Ada (Software Archaeologist)
• “I need the ontology architect” routes to Alexander

BmadBridge reads from the auto-generated routing.yaml. When BMAD changes, one command regenerates everything.

What Comes Next

Agent Persona Injection represents the ultimate evolution: PAI’s Task tool could accept a persona parameter that loads BMAD agent identities into any subagent type. Mary’s analytical style applied to PAI’s parallel execution. Winston’s architectural rigor combined with PAI’s flexible model selection.

Concluding Remarks

The BMAD-PAI harmonization taught us that good systems are not about replacing each other. They are about finding the right layer for each capability.

PAI excels at natural language activation and flexible agent orchestration. BMAD excels at deterministic workflows and rich agent personas. BmadBridge connects them, preserving both strengths.

The result: we can say “let’s brainstorm ideas for improving user onboarding” and get Carson’s 35-technique brainstorming session. Or “create a PRD for this feature” and get John’s structured product requirements document. Natural invocation, rigorous execution, consistent outputs.

That is the integration in practice: say what you want, get structured results, powered by 30 specialized agents who each bring distinct expertise to the conversation.

References

[1] Daniel Miessler, Building a Personal AI Infrastructure (PAI), Blog, 26 Jul 2025.

[2] Unsupervised Learning, Building Your Own Unified AI Assistant Using Claude Code, video, 4 Sep 2025.

[3] BMad Code, BMAD Method, GitHub.

[4] BMad Code, The BMAD Builder is Here - V6 Alpha: 5 Major Features, video, 6 Oct 2025.

[5] Anthropic, Introducing Claude Skills, Product Blog, 16 Oct 2025.

[6] Simon Willison, Claude Skills are awesome, maybe a bigger deal than MCP, Weblog, 16 Oct 2025.