13 KiB

Raw Blame History

BMAD Context Engineering Enhancement - Implementation Plan

📋 Project Overview

Project Name: BMAD Context Engineering Enhancement
Version: 1.0
Start Date: January 2025
Expected Duration: 10 days
Status: Planning Complete - Ready for Implementation
Current Codebase Analysis: ✅ Complete - Ready to execute

🎯 Objectives

Primary Goals

Enhance Agent Intelligence: Implement advanced context engineering capabilities across all BMAD agents
Maintain BMad Method Compliance: Keep dev agents lean while enabling rich context for planning agents
Improve Cross-Agent Collaboration: Enable seamless context sharing and handoffs
Preserve Backward Compatibility: Ensure existing functionality remains intact

Success Criteria

Dev agents remain lean (<2000 tokens, <3 context dependencies)
Planning agents achieve >85% context retrieval accuracy
Cross-agent handoffs succeed 98% of the time
100% BMad Method compliance (natural language, proper markup)

📊 Current State Analysis

Existing Core Configuration Structure

# Current bmad-core/core-config.yaml (26 lines)
version: 4.22.0
markdownExploder: true
prd: {...}
architecture: {...}
customTechnicalDocuments: null
devLoadAlwaysFiles: [...]
devDebugLog: .ai/debug-log.md
devStoryLocation: docs/stories
workflow: {...}

Current Agent Classifications (Verified)

💻 Lean Agent (Current):
└── dev.md (66 lines) - Currently lean with minimal dependencies

📱 Planning Agents (Current):
├── bmad-orchestrator.md (141 lines) - Rich orchestration capabilities
├── pm.md (62 lines) - Product management focused
├── architect.md - System design
├── po.md - Product ownership
├── analyst.md - Business analysis
├── ux-expert.md - User experience
├── qa.md - Quality assurance
└── sm.md - Scrum master

Current Task & Template Structure

Tasks: Located in bmad-core/tasks/ and common/tasks/
Templates: Located in bmad-core/templates/
Utilities: Located in bmad-core/utils/
Dependencies: YAML-defined with dynamic loading

🏗️ Architecture Overview

Agent Classification

📱 Web/Planning Agents (Rich Context - 8000 tokens):
├── bmad-orchestrator.md    # Master orchestrator
├── architect.md            # System design
├── pm.md                   # Product management
├── po.md                   # Product ownership
├── analyst.md              # Business analysis
├── ux-expert.md           # User experience
├── qa.md                  # Quality assurance
└── sm.md                  # Scrum master

💻 Dev Agent (Lean Context - 2000 tokens):
└── dev.md                 # Development implementation

🎭 Hybrid Agent:
└── bmad-master.md         # Adaptive context based on mode

Context Engineering Components

.bmad-core/
├── tasks/
│   ├── context-optimization.md     # Universal: All agents
│   ├── context-handoff.md         # Universal: Agent transitions
│   ├── context-validation.md      # Universal: Security & quality
│   ├── context-retrieval.md       # Rich only: Planning agents
│   └── context-memory-management.md # Rich only: Long-term storage
├── utils/
│   ├── context-compression.md     # Universal: Token optimization
│   ├── context-filtering.md       # Universal: Relevance filtering
│   ├── semantic-search.md         # Rich only: Advanced search
│   └── context-analysis.md        # Rich only: Quality assessment
└── templates/
    ├── context-handoff-tmpl.md    # Agent transition templates
    └── context-summary-tmpl.md    # Context compression templates

📅 Implementation Phases

Phase 1: Foundation (Days 1-4)

Goal: Establish core context engineering infrastructure

1.1 Core Configuration Enhancement ⚡ HIGH PRIORITY

File: bmad-core/core-config.yaml
Current Size: 26 lines (very manageable)
Changes: Add context engineering section (estimated +40 lines)
Features:
- Universal context settings
- Agent-specific token limits (dev: 2000, planning: 8000)
- Context compression ratios (dev: 0.9, planning: 0.7)
- Enabled utilities per agent type
- Performance monitoring configuration

Specific Configuration Addition:

# ADD TO EXISTING core-config.yaml
context_engineering:
  universal:
    enabled: true
    default_compression_ratio: 0.7
    max_context_age_hours: 24
    validation_required: true
    audit_logging: true
  agent_types:
    dev_agents: [dev]
    planning_agents: [bmad-orchestrator, architect, pm, po, analyst, ux-expert, qa, sm]
    hybrid_agents: [bmad-master]
  # ... (full specification in file-modifications-guide.md)

1.2 Universal Context Tasks ⚡ HIGH PRIORITY

Create tasks that all agents can use:

context-optimization.md (NEW FILE)

Purpose: Universal context compression and optimization
Target: All agents (with different parameters)
Size Estimate: ~150 lines
Features: Token management, priority ranking, dynamic trimming

context-handoff.md (NEW FILE)

Purpose: Cross-agent context transfer
Target: All agents
Size Estimate: ~200 lines
Features: Lightweight summaries for dev, full context for planning

context-validation.md (NEW FILE)

Purpose: Security and quality validation
Target: All agents
Size Estimate: ~120 lines
Features: Input validation, access control, audit logging

1.3 Universal Context Utilities ⚡ HIGH PRIORITY

context-compression.md (NEW FILE)

Purpose: Lean utility for token optimization
Target: All agents
Size Estimate: ~100 lines
Features: Aggressive compression, relevance filtering

context-filtering.md (NEW FILE)

Purpose: Relevance-based content filtering
Target: All agents
Size Estimate: ~100 lines
Features: Content scoring, priority-based selection

Phase 2: Agent Enhancement (Days 5-9)

2.1 Dev Agent Enhancement (Lean Context Focus) ⚡ CRITICAL

File: bmad-core/agents/dev.md
Current Size: 66 lines (already lean)
Approach: Minimal context enhancements only
Features:
- Add context-optimization to dependencies
- Add context-compression utility reference
- Implement 2000 token limit enforcement
- Add code-relevance filtering (>95% threshold)
- Ensure minimal dependency footprint (<3 dependencies)

Specific Dev Agent Modifications:

Add to dependencies: context-optimization, context-handoff, context-validation
Add to utils: context-compression, context-filtering
Update core_principles to include context management
Maintain current lean structure (target: <100 lines total)

2.2 Web/Planning Agents Enhancement (Rich Context Focus)

Current Planning Agent Structures:

bmad-orchestrator.md: 141 lines (rich orchestration capabilities)
pm.md: 62 lines (focused product management)
Others: Similar focused structures

Enhancement Strategy for Each:

Add rich context tasks to dependencies
Add semantic search capabilities
Include cross-agent context sharing
Maintain role-specific focus

Specific Enhancements by Agent:

bmad-orchestrator.md (MODIFY EXISTING)

Add: context-retrieval, context-memory-management to dependencies
Add: semantic-search, context-analysis to utils
Include: Cross-session memory management
Feature: Quality metrics tracking integration

architect.md (MODIFY EXISTING)

Add: Technical context retrieval capabilities
Feature: Architecture pattern matching
Include: Design decision context management
Add: Technology context analysis

pm.md (MODIFY EXISTING)

Add: Product context management
Feature: Market research integration
Include: User story context tracking
Add: Requirements traceability

Other Planning Agents (po.md, analyst.md, ux-expert.md, qa.md, sm.md)

Role-specific context retrieval
Domain knowledge integration
Collaboration context awareness
Process context management

2.3 Context Templates Creation

context-handoff-tmpl.md (NEW FILE)

Purpose: Standardized handoff template with BMad markup
Size Estimate: ~80 lines
Features: {{placeholders}} and LLM: instructions

context-summary-tmpl.md (NEW FILE)

Purpose: Context compression template
Size Estimate: ~60 lines
Features: Structured summary generation

Phase 3: Rich Context Features (Days 10-12)

3.1 Rich Context Tasks (Planning Agents Only)

context-retrieval.md (NEW FILE)

Purpose: Semantic search and intelligent retrieval
Target: Web/planning agents only
Size Estimate: ~180 lines
Features: Vector search, relevance scoring, real-time retrieval

context-memory-management.md (NEW FILE)

Purpose: Long-term context storage and recall
Target: Web/planning agents only
Size Estimate: ~150 lines
Features: Persistent memory, context archiving, retrieval optimization

3.2 Rich Context Utilities (Planning Agents Only)

semantic-search.md (NEW FILE)

Purpose: Advanced search capabilities
Target: Web/planning agents only
Size Estimate: ~120 lines
Features: Vector embeddings, similarity matching, contextual search

context-analysis.md (NEW FILE)

Purpose: Context quality assessment
Target: Web/planning agents only
Size Estimate: ~100 lines
Features: Relevance scoring, freshness validation, quality metrics

🔄 BMad Method Compliance

Core Principles Adherence

Dev Agents Must Be Lean ✅
- Strict 2000 token limit enforcement
- Maximum 3 context dependencies
- 0.9 compression ratio targeting
- 95% code relevance threshold
Natural Language First ✅
- 100% markdown format for all new files
- Proper {{placeholder}} and LLM: markup usage
- No code in framework files
- Clear, readable natural language procedures
Small Files, Loaded on Demand ✅
- All new files targeted <50KB (average ~150 lines)
- Dynamic resource loading based on agent needs
- Multiple focused files vs. large branching files
Agent and Task Design ✅
- Clear personas maintained for each agent
- Step-by-step task procedures
- Structured template outputs with embedded generation instructions
- Explicit dependency declarations only for essential components

🚀 Execution Readiness

Phase 1 Immediate Next Actions (Ready to Execute)

Development Setup: ✅ Already on development branch
Commit Strategy: Local commits with detailed documentation, creator approval required for push

Backup Current State: Create backup of core-config.yaml
Core Config Enhancement: Implement context_engineering section in core-config.yaml
Universal Tasks Creation: Create 3 core context tasks
Universal Utils Creation: Create 2 core context utilities
Testing & Documentation: Validate backward compatibility and prepare creator review package

Local Development Strategy

Implementation Approach: Complete Phase 1 fully with local commits
Documentation: Thorough commit messages and implementation summary
Testing: Comprehensive backward compatibility validation
Creator Package: Prepare complete implementation overview for discussion
No Public Push: Maintain all changes locally until creator approval

Risk Mitigation

Backward Compatibility: All changes are additive to existing structure
Incremental Testing: Each phase can be tested independently
Local Development: Safe implementation with local commits only
Creator Review: Comprehensive documentation for approval process
Size Controls: File size monitoring to maintain <50KB targets

Success Validation

Automated token counting for dev agent compliance
Context retrieval accuracy testing for planning agents
Cross-agent handoff success rate monitoring
BMad markup compliance validation
Creator Approval: Present complete implementation for review

📈 Expected Outcomes

After Phase 1 Local Completion:

Core Infrastructure: Context engineering foundation established locally
Documentation: Complete implementation summary for creator review
Testing Results: Backward compatibility validation complete
Creator Package: Ready for discussion and approval

After Creator Approval & Phase 2-3:

Dev Agent: Enhanced but still lean (target: <80 lines, 3 dependencies)
Planning Agents: Rich context capabilities (6-8 dependencies each)
Cross-Agent Workflow: Seamless context transfer and collaboration
Framework Integrity: 100% BMad Method compliance maintained
Performance: <500ms context optimization, >85% retrieval accuracy

Ready to execute Phase 1 locally with creator review preparation ✅

Progress Tracker: `

13 KiB Raw Blame History