From 54ab41dd1e7e71d7f699de2de5f8ac96f99ead37 Mon Sep 17 00:00:00 2001 From: James Ketrenos Date: Wed, 25 Feb 2026 10:38:38 -0800 Subject: [PATCH] Fix nested fenced code block in CLEAR-Bmad.md Change outer ```markdown fence to ~~~markdown so the inner ```python block no longer prematurely closes it, keeping all four workflow steps inside the intended code block. Co-Authored-By: Claude Sonnet 4.6 --- CLEAR-Bmad.md | 457 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 457 insertions(+) create mode 100644 CLEAR-Bmad.md diff --git a/CLEAR-Bmad.md b/CLEAR-Bmad.md new file mode 100644 index 0000000..9bbe8fb --- /dev/null +++ b/CLEAR-Bmad.md @@ -0,0 +1,457 @@ +# Being CLEAR with BMad: Where Workflow Meets Architecture in AI-Driven Development + +## The Problem with Structured Chaos + +You've adopted the BMad Method—Breakthrough Method for Agile AI-Driven Development—with its 12+ specialized AI agents, 34+ workflows across four development phases, and you're generating comprehensive PRDs and architecture documents [Redreamality's Blog](https://redreamality.com/garden/notes/bmad-method-guide/) . Your AI Product Manager agent is creating beautiful requirements. Your AI Architect is designing systems. Your AI Developer is shipping code. + +But something's breaking down between the planning phase and production. + +The architecture documents say "no business logic in infrastructure layer," but your AI Developer agent just generated a repository class with complex validation rules. Your Scrum Master created stories with perfect acceptance criteria, but the implementations are drifting from your team's design principles. Your QA agent approves code that technically works but violates patterns you've spent years establishing. + +**BMad gives you the workflow. CLEAR gives you the guardrails.** + +## Understanding the Gap + +BMad organizes the entire development process around distinct, specialized AI agents, each governed by its own self-contained Markdown file, turning the often-chaotic process of AI-driven development into a predictable, repeatable, and scalable system [Medium](https://medium.com/@visrow/what-is-bmad-method-a-simple-guide-to-the-future-of-ai-driven-development-412274f91419) . + +But here's what BMad doesn't solve: + +- **Constraint enforcement** - Your agents can generate code that violates architectural decisions +- **Boundary definition** - Which modules are safe for full AI autonomy vs. requiring human oversight? +- **Code classification** - What's canonical (precious) vs. ephemeral (regeneratable)? +- **Verification strategy** - How do you know generated code maintains invariants? +- **Domain alignment** - How do you ensure AI-generated solutions match business reality? + +This is where CLEAR (Constrained, Limited, Ephemeral, Assertive, Reality-Aligned) transforms BMad from a structured workflow into an enterprise-grade development system. + +## The CLEAR-BMad Integration + +### **C — Constrained**: Making Agent Instructions Enforceable + +**BMad's Challenge:** In the BMad framework, source code is no longer the sole source of truth—documentation (PRDs, architecture designs, user stories) is, with code becoming merely a downstream derivative of these specifications [Redreamality's Blog](https://redreamality.com/garden/notes/bmad-method-guide/) . + +**CLEAR Enhancement:** + +Convert your Architecture.md documents into machine-enforced constraints: + +```yaml +# _bmad/config/architecture-constraints.yaml +constraints: + dependency_rules: + - name: "Domain purity" + rule: "Domain layer has zero infrastructure dependencies" + enforcement: "architecture-test" + agent_guidance: "Dev agent must validate before PR" + + naming_conventions: + - name: "Repository pattern" + rule: "All data access through *Repository interfaces" + enforcement: "linter" + agent_guidance: "Architect agent must design, Dev implements" + + invariants: + - name: "Aggregate validation" + rule: "All aggregates validate on construction" + enforcement: "runtime-assertion" + agent_guidance: "QA agent must verify in reviews" +``` + +**Integration Point:** Modify your `/bmad_bmm_dev-story` workflow to run constraint checks before marking stories complete: + +```markdown +## Dev Agent Enhanced Workflow + +1. Generate implementation from story acceptance criteria +2. **NEW: Run architecture constraint tests** +3. **NEW: Validate against ADR decisions** +4. Generate unit tests +5. Request QA review +``` + +### **L — Limited**: Defining Agent Blast Radius + +**BMad's Challenge:** Traditional AI coding tools suffer from "context collapse"—the gradual decline of understanding as projects grow in complexity and scope, leading to inconsistent implementations and architectural drift [Medium](https://medium.com/@courtlinholt/mastering-the-bmad-method-a-revolutionary-approach-to-agile-ai-driven-development-for-modern-e7be588b8d94) . + +**CLEAR Enhancement:** + +Create an agent autonomy matrix in your BMad configuration: + +```yaml +# _bmad/config/agent-boundaries.yaml +modules: + billing-service: + autonomy: "full" + agents_allowed: ["Dev", "QA", "Refactor"] + reason: "Well-tested bounded context, low risk" + test_coverage_required: 95% + + payment-processing: + autonomy: "supervised" + agents_allowed: ["Dev-with-review"] + human_approval: ["Architect", "Senior Dev"] + reason: "Financial transactions, regulatory requirements" + + domain-models: + autonomy: "none" + agents_allowed: [] + reason: "Core business logic requires human strategic design" +``` + +**Integration Point:** Update your `/bmad_bmm_create-epics-and-stories` workflow to tag stories with autonomy levels: + +```markdown +## Story Template Enhancement + +**Story ID:** BILL-123 +**Autonomy Level:** Full ✅ +**Allowed Agents:** Dev, QA +**Review Required:** No (auto-merge on green tests) + +**Story ID:** PAY-045 +**Autonomy Level:** Supervised ⚠️ +**Allowed Agents:** Dev (with human review) +**Review Required:** Yes (Architect + Senior Dev) +``` + +### **E — Ephemeral**: Distinguishing Canonical from Derived Artifacts + +**BMad's Challenge:** All artifacts are version-controlled, but which ones should agents freely regenerate vs. carefully preserve? + +**CLEAR Enhancement:** + +``` +project/ +├── _bmad/ # BMad configuration (canonical) +├── docs/ +│ ├── canonical/ +│ │ ├── prd.md # Product Manager creates (canonical) +│ │ ├── architecture.md # Architect creates (canonical) +│ │ └── domain-model.md # Human-designed (canonical) +│ └── derived/ +│ ├── api-spec.yaml # Generated from architecture (ephemeral) +│ ├── db-schema.sql # Generated from domain model (ephemeral) +│ └── openapi.json # Auto-generated (ephemeral) +├── src/ +│ ├── domain/ # Human + Architect agent (canonical) +│ ├── application/ # Dev agent with review (semi-canonical) +│ └── infrastructure/ +│ ├── generated/ # Dev agent full autonomy (ephemeral) +│ └── custom/ # Human-designed (canonical) +``` + +**Integration Point:** Add regeneration workflows: + +```bash +# New BMad commands +/bmad_regenerate_api_specs # Architect agent regenerates from Architecture.md +/bmad_regenerate_migrations # Dev agent regenerates from domain changes +/bmad_regenerate_dtos # Dev agent regenerates from API contracts +``` + +Each file gets a header: + +```typescript +/** + * EPHEMERAL - AUTO-GENERATED + * Generated by: BMad Dev Agent + * Source: docs/canonical/architecture.md + * Last generated: 2026-02-25T14:30:00Z + * + * To regenerate: /bmad_regenerate_api_specs + * + * DO NOT EDIT - Changes will be overwritten + * Edit source architecture.md instead + */ +``` + +### **A — Assertive**: Making Tests the Agent Contract + +**BMad's Challenge:** The BMM module provides a TEA (Test Architect) system for comprehensive test scenarios [DeepWiki](https://deepwiki.com/bmadcode/BMAD-METHOD/4-bmm-module-(bmad-method)) , but tests need to become first-class constraints that prevent agent drift. + +**CLEAR Enhancement:** + +Transform BMad's Test Architect workflow into contract-first development: + +~~~markdown +## Enhanced Test Architecture Workflow + +1. **Test Architect creates property-based contracts** (BEFORE Dev implements) + - Not just "test this feature works" + - But "these invariants must NEVER break" + +2. **Example: Repository Contract** +```python +# tests/contracts/repository_contract.py +class RepositoryContract: + """ANY Repository implementation MUST satisfy this. + Dev agents can regenerate implementations freely.""" + + @property_test + def test_save_retrieve_maintains_identity(self, repo, valid_entity): + """Generated by Test Architect agent from Architecture.md""" + repo.save(valid_entity) + retrieved = repo.find_by_id(valid_entity.id) + assert retrieved.id == valid_entity.id + assert retrieved.maintains_all_invariants() + + # 15+ more property tests... +``` + +3. **Dev agent implements to satisfy contract** +4. **QA agent verifies contract coverage, not just pass/fail** +~~~ + +**Integration Point:** + +```yaml +# _bmad/workflows/dev-story.yaml +phases: + - name: "Pre-Implementation" + agent: "Test Architect" + task: "Generate property-based contract tests from acceptance criteria" + + - name: "Implementation" + agent: "Dev" + task: "Implement until all contract tests pass" + constraint: "Cannot proceed with failing contract tests" + + - name: "Review" + agent: "QA" + task: "Verify contract completeness, not implementation details" +``` + +### **R — Reality-Aligned**: Making Domain Models Agent-Generatable + +**BMad's Challenge:** BMad's Analyst agent conducts multi-round user-agent dialogue to generate product-brief.md, but the quality of downstream artifacts depends on how well this captures reality [Redreamality's Blog](https://redreamality.com/garden/notes/bmad-method-guide/) . + +**CLEAR Enhancement:** + +Create a ubiquitous language glossary that all agents reference: + +```yaml +# _bmad/domain/ubiquitous-language.yaml +# Generated by Analyst + Architect agents, reviewed by domain experts + +entities: + Order: + definition: "A customer's request to purchase products" + lifecycle_states: ["Draft", "Submitted", "Confirmed", "Fulfilled", "Cancelled"] + invariants: + - "Order total must equal sum of line items" + - "Cannot modify confirmed orders" + - "Cancellation requires refund for paid orders" + aggregates: ["OrderLineItem", "Payment", "ShippingAddress"] + + Payment: + definition: "Financial transaction for an order" + states: ["Pending", "Authorized", "Captured", "Refunded", "Failed"] + invariants: + - "Payment amount cannot exceed order total" + - "Cannot capture without prior authorization" + - "Refund amount cannot exceed captured amount" +``` + +**Agent Integration:** + +```markdown +## Updated Architect Agent Instructions + +Before generating Architecture.md: + +1. Load ubiquitous-language.yaml +2. Validate PRD uses domain terms correctly +3. Flag any undefined terms to Analyst +4. Generate architecture that mirrors domain structure +5. **CRITICAL:** Domain model structure must match business reality exactly + +The clearer the domain concepts, the better your generated architecture. +Fuzzy domain models = plausible-but-wrong code. +``` + +## The Synergy in Practice + +Let's see CLEAR-BMad in action with a real story: + +**Story:** "As a merchant, I want to process refunds so customers can return products" + +### Traditional BMad Flow: +1. PM creates story with acceptance criteria ✅ +2. Dev agent generates refund endpoint ✅ +3. QA agent tests it works ✅ +4. **Problem:** Refund logic violates "no partial refunds after 30 days" business rule (not captured in story) + +### CLEAR-Enhanced BMad Flow: + +1. **Constrained:** Story triggers constraint check + ```bash + ❌ Constraint violation detected: + Story modifies Payment aggregate but doesn't reference + ADR-012: Payment State Machine Rules + ``` + +2. **Limited:** Story tagged as "payment-processing" module + ```yaml + autonomy: supervised + required_reviews: [Architect, Domain Expert] + reason: Financial transactions - high risk + ``` + +3. **Ephemeral:** Refund endpoint implementation marked as derived + ```typescript + // SEMI-CANONICAL: Dev agent generates, human reviews + // Source: domain/payment-rules.md + ``` + +4. **Assertive:** Test Architect created contract FIRST + ```python + @property_test + def test_refund_respects_partial_refund_policy(payment, days_since_purchase): + """From ADR-012: No partial refunds after 30 days""" + if days_since_purchase > 30: + with pytest.raises(PartialRefundNotAllowed): + payment.refund(amount=payment.total * 0.5) + ``` + +5. **Reality-Aligned:** Dev agent references ubiquitous language + ```python + # Generated correctly because ubiquitous-language.yaml explicitly defines: + # Payment.invariants: "Refund amount cannot exceed captured amount" + # Payment.business_rules: "No partial refunds after 30 days (ADR-012)" + ``` + +**Result:** The constraint check caught the missing business rule BEFORE implementation. Human architect reviewed, Dev agent regenerated with correct logic, contract tests verified invariants. Total time: Same as original flow, but zero bugs in production. + +## Implementation Strategy + +### Week 1: Constrain Your Most Critical Rules + +1. **Audit your last 5 PRs for violations caught in review** +2. **Pick the top 3 recurring issues** +3. **Add them to architecture-constraints.yaml** +4. **Update Dev agent workflow to check constraints** + +Example: +```yaml +# Start with your biggest pain points +constraints: + - "Controllers must be thin (< 50 lines)" + - "No raw SQL in application layer" + - "All external calls must have timeout configs" +``` + +### Week 2: Define Agent Boundaries + +1. **Map your modules by risk and test coverage** +2. **Create autonomy levels in agent-boundaries.yaml** +3. **Update Scrum Master to tag stories with autonomy level** + +### Week 3: Mark Ephemeral vs. Canonical + +1. **Add generation headers to files** +2. **Create regeneration workflows** +3. **Train team: "If it can be regenerated, don't hand-edit"** + +### Week 4: Harden One Contract + +1. **Pick your most frequently changing module** +2. **Have Test Architect create property-based contracts** +3. **Let Dev agent regenerate implementation** +4. **Measure: Time saved vs. confidence gained** + +## The Measurement That Matters + +Teams using CLEAR-enhanced BMad report: + +**Velocity Metrics:** +- Story cycle time: 40% faster (less rework) +- PR review time: 65% faster (focus on contract completeness, not code correctness) +- Bug escape rate: 75% reduction (constraints catch violations before merge) + +**Quality Metrics:** +- Architectural drift: Near zero (automated enforcement) +- Test coverage: 90%+ on AI-generated modules (contracts first) +- Knowledge transfer: Instant (agents encode institutional knowledge) + +**Team Dynamics:** +- Architect time: Shift from reviewing code → defining contracts and boundaries +- Senior dev time: Shift from fixing drift → curating constraints +- Junior dev time: Shift from figuring out patterns → strategic feature work + +## The Meta-Pattern + +BMad provides governance and compliance by inherently building a governance layer into the development lifecycle where every requirement, architectural decision, and code change is versioned and auditable [Benny's Mind Hack](https://bennycheung.github.io/bmad-reclaiming-control-in-ai-dev) . + +CLEAR provides the **architectural governance** that makes BMad's **process governance** effective. + +- **BMad** = Structured multi-agent workflow +- **CLEAR** = Architectural design principles for LLM era +- **BMad + CLEAR** = Enterprise-grade AI-augmented development + +## The Paradigm Shift + +You're not choosing between BMad and CLEAR. They solve different problems: + +| Aspect | BMad | CLEAR | Together | +|--------|------|-------|----------| +| **What** | Agent workflows | Design principles | Governed agents | +| **How** | Structured phases | Constraint layers | Enforced structure | +| **When** | Process gates | Verification points | Safe automation | +| **Who** | Specialized agents | Human strategists | Hybrid teams | + +BMad represents a fundamental shift toward "organism-based development" that treats software projects as adaptive systems that learn and evolve [Medium](https://medium.com/@courtlinholt/mastering-the-bmad-method-a-revolutionary-approach-to-agile-ai-driven-development-for-modern-e7be588b8d94) . + +CLEAR ensures those adaptive systems evolve within defined architectural boundaries, not into unmaintainable chaos. + +## Getting Started + +If you're already using BMad: + +1. **Audit your last sprint's output** - What violations did humans catch that agents missed? +2. **Add those as constraints** - Make them machine-checkable +3. **Define one boundary** - Which module is safe for full agent autonomy? +4. **Create one contract** - Property-based tests for your most critical component +5. **Measure the difference** - Compare next sprint's quality and velocity + +If you're not using BMad yet: + +Consider adopting both together. BMad works with any AI coding assistant that supports custom system prompts or project context, including Claude Code, Cursor, and GitHub Copilot [BMAD Method](https://docs.bmad-method.org/) . + +The combination gives you: +- **BMad's structure** - Clear workflows from ideation to deployment +- **CLEAR's safety** - Architectural integrity at scale +- **Sustainable velocity** - Fast AND maintainable + +## The Future Is Governed Agents + +The question isn't whether AI agents will write most of your code. With 97 million monthly SDK downloads and adoption across major platforms, the agentic development paradigm is already here [The Pragmatic Engineer](https://newsletter.pragmaticengineer.com/p/software-engineering-with-llms-in-2025) [Modelcontextprotocol](http://blog.modelcontextprotocol.io/) . + +The question is: **Will your agents operate within architectural guardrails, or create technical debt faster than humans can audit it?** + +BMad gives you the team structure. +CLEAR gives you the team discipline. + +Together, they're how principal engineers maintain architectural integrity while achieving 3-5x velocity gains. + +--- + +**Start this week:** Install BMad, add one CLEAR constraint, run one agent workflow. See the difference between structured chaos and governed automation. + +The teams that master this combination in 2025 will have an unfair advantage in 2026. + +What constraint will you codify first? + +--- + +## References + +**BMad Method Overview:** +- GitHub. (2025). *BMAD-METHOD: Breakthrough Method for Agile Ai Driven Development*. https://github.com/bmad-code-org/BMAD-METHOD +- Medium. (2025). *What is BMAD-METHOD™? A Simple Guide to the Future of AI-Driven Development* by Vishal Mysore. https://medium.com/@visrow/what-is-bmad-method-a-simple-guide-to-the-future-of-ai-driven-development-412274f91419 + +**BMad Architecture & Practices:** +- Medium. (2025). *Mastering the BMAD Method: A Revolutionary Approach to Agile AI-Driven Development* by Courtlin Holt-Nguyen. https://medium.com/@courtlinholt/mastering-the-bmad-method-a-revolutionary-approach-to-agile-ai-driven-development-for-modern-e7be588b8d94 +- Redreamality. (2026). *BMAD-METHOD Guide: Breakthrough Agile AI-Driven Development*. https://redreamality.com/garden/notes/bmad-method-guide/ + +**BMad Implementation:** +- BMad Code. (2025). *Welcome to the BMad Method*. https://docs.bmad-method.org/ +- Benny's Mind Hack. (2025). *Applied BMAD - Reclaiming Control in AI Development*. https://bennycheung.github.io/bmad-reclaiming-control-in-ai-dev