439 lines
15 KiB
Markdown
439 lines
15 KiB
Markdown
# Context Synchronizer
|
|
|
|
## Real-time Context Sharing for Claude Code Integration
|
|
|
|
The Context Synchronizer maintains shared awareness across all BMAD personas within Claude Code, ensuring consistent understanding of project state, decisions, and development progress.
|
|
|
|
### Context Structure for Claude Code
|
|
|
|
#### Comprehensive Project Context
|
|
```yaml
|
|
project_context:
|
|
metadata:
|
|
project_id: "{uuid}"
|
|
project_name: "{descriptive-name}"
|
|
project_type: "web-app|api-service|mobile-app|library|cli-tool"
|
|
tech_stack: ["typescript", "react", "nodejs", "mongodb"]
|
|
phase: "discovery|design|implementation|testing|deployment"
|
|
created_timestamp: "{iso-8601}"
|
|
last_updated: "{iso-8601}"
|
|
|
|
claude_code_state:
|
|
active_session: "{session-id}"
|
|
workspace_path: "{absolute-path}"
|
|
open_files: ["{file-paths}"]
|
|
recent_tools_used: [
|
|
{
|
|
"tool": "Read",
|
|
"target": "src/components/Auth.tsx",
|
|
"timestamp": "{iso-8601}"
|
|
}
|
|
]
|
|
current_todos: [
|
|
{
|
|
"id": "todo-123",
|
|
"content": "Implement user authentication",
|
|
"status": "in_progress",
|
|
"assigned_persona": "security"
|
|
}
|
|
]
|
|
git_context:
|
|
current_branch: "feature/auth-implementation"
|
|
uncommitted_changes: ["src/auth/", "tests/auth/"]
|
|
last_commit: "abc123: Add user login component"
|
|
|
|
decisions:
|
|
- id: "{uuid}"
|
|
timestamp: "{iso-8601}"
|
|
decision: "Use JWT for authentication"
|
|
made_by: "security"
|
|
rationale: "Stateless, scalable, industry standard"
|
|
impact: ["api-design", "frontend-auth", "security-model"]
|
|
supporting_personas: ["architect", "dev"]
|
|
|
|
artifacts:
|
|
- id: "{uuid}"
|
|
type: "architecture-document"
|
|
path: "docs/system-architecture.md"
|
|
version: "v1.2"
|
|
last_modified_by: "architect"
|
|
last_modified: "{iso-8601}"
|
|
status: "approved"
|
|
reviewers: ["security", "qa", "pm"]
|
|
|
|
active_tasks:
|
|
- id: "{uuid}"
|
|
description: "Implement OAuth2 integration"
|
|
assigned_to: ["security", "dev"]
|
|
status: "in_progress"
|
|
dependencies: ["user-model-design"]
|
|
estimated_effort: "8 hours"
|
|
actual_effort: "6 hours"
|
|
blockers: []
|
|
|
|
knowledge_state:
|
|
learned_patterns: [
|
|
{
|
|
"pattern": "secure-api-authentication",
|
|
"confidence": 0.95,
|
|
"applications": 3,
|
|
"success_rate": 1.0
|
|
}
|
|
]
|
|
avoided_anti_patterns: [
|
|
{
|
|
"anti_pattern": "password-in-url",
|
|
"prevention_count": 2,
|
|
"last_prevented": "{iso-8601}"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Context Synchronization Protocol
|
|
|
|
#### Real-time Context Updates
|
|
```python
|
|
async def synchronize_context_with_claude_code():
|
|
"""
|
|
Maintain real-time synchronization between BMAD context and Claude Code state
|
|
"""
|
|
# Monitor Claude Code tool usage
|
|
tool_monitor = await start_tool_usage_monitor()
|
|
|
|
# Monitor file system changes
|
|
file_monitor = await start_file_system_monitor()
|
|
|
|
# Monitor git state changes
|
|
git_monitor = await start_git_state_monitor()
|
|
|
|
# Monitor todo list changes
|
|
todo_monitor = await start_todo_monitor()
|
|
|
|
async def update_context_from_claude_code():
|
|
while True:
|
|
# Detect Claude Code state changes
|
|
state_changes = await detect_claude_code_changes([
|
|
tool_monitor,
|
|
file_monitor,
|
|
git_monitor,
|
|
todo_monitor
|
|
])
|
|
|
|
if state_changes:
|
|
# Update global context
|
|
updated_context = await update_global_context(state_changes)
|
|
|
|
# Broadcast updates to all personas
|
|
await broadcast_context_update(updated_context, state_changes)
|
|
|
|
# Store context snapshot for recovery
|
|
await store_context_snapshot(updated_context)
|
|
|
|
await asyncio.sleep(0.1) # 100ms polling interval
|
|
|
|
# Start continuous synchronization
|
|
await update_context_from_claude_code()
|
|
|
|
async def sync_decision_with_context(decision_data):
|
|
"""
|
|
Synchronize persona decisions with global context
|
|
"""
|
|
# Validate decision against current context
|
|
validation_result = await validate_decision_against_context(
|
|
decision_data,
|
|
get_current_context()
|
|
)
|
|
|
|
if validation_result.conflicts:
|
|
# Handle decision conflicts
|
|
conflict_resolution = await resolve_decision_conflicts(
|
|
decision_data,
|
|
validation_result.conflicts
|
|
)
|
|
|
|
if conflict_resolution.requires_consultation:
|
|
# Escalate to multi-persona consultation
|
|
consultation_result = await initiate_consultation(
|
|
conflict_resolution.stakeholders,
|
|
decision_data
|
|
)
|
|
decision_data = consultation_result.resolved_decision
|
|
|
|
# Update global context with validated decision
|
|
updated_context = await add_decision_to_context(decision_data)
|
|
|
|
# Notify affected personas
|
|
affected_personas = identify_affected_personas(decision_data)
|
|
await notify_personas_of_decision(affected_personas, decision_data)
|
|
|
|
# Update Claude Code todos if decision creates new tasks
|
|
if decision_data.creates_tasks:
|
|
await update_claude_todos_from_decision(decision_data)
|
|
|
|
return updated_context
|
|
```
|
|
|
|
#### Context Conflict Resolution
|
|
```yaml
|
|
conflict_resolution:
|
|
decision_conflicts:
|
|
detection:
|
|
- contradictory_decisions: "Two personas make opposing choices"
|
|
- constraint_violations: "Decision violates established constraints"
|
|
- dependency_conflicts: "Decision affects dependent components"
|
|
|
|
resolution_strategies:
|
|
- expertise_hierarchy: "Defer to domain expert"
|
|
- stakeholder_consultation: "Get input from affected parties"
|
|
- evidence_based_resolution: "Use data to resolve conflict"
|
|
- compromise_solution: "Find middle ground approach"
|
|
|
|
resource_conflicts:
|
|
detection:
|
|
- concurrent_file_edits: "Multiple personas editing same file"
|
|
- tool_usage_conflicts: "Competing tool access needs"
|
|
- timeline_conflicts: "Overlapping delivery schedules"
|
|
|
|
resolution_mechanisms:
|
|
- priority_based_scheduling: "High priority work gets precedence"
|
|
- collaborative_editing: "Coordinate simultaneous work"
|
|
- resource_pooling: "Share resources effectively"
|
|
- sequential_processing: "Order conflicting operations"
|
|
```
|
|
|
|
### Context-Aware Tool Enhancement
|
|
|
|
#### Smart Tool Selection Based on Context
|
|
```python
|
|
async def enhance_claude_tools_with_context(tool_request, current_context):
|
|
"""
|
|
Enhance Claude Code tool usage with BMAD context awareness
|
|
"""
|
|
enhanced_request = {
|
|
'original_request': tool_request,
|
|
'context_enhancement': {},
|
|
'recommendations': []
|
|
}
|
|
|
|
# Enhance Read operations with context
|
|
if tool_request.tool == 'Read':
|
|
file_context = await get_file_context(
|
|
tool_request.target_file,
|
|
current_context
|
|
)
|
|
|
|
enhanced_request['context_enhancement'] = {
|
|
'file_history': file_context.modification_history,
|
|
'related_decisions': file_context.related_decisions,
|
|
'persona_annotations': file_context.persona_comments,
|
|
'known_patterns': file_context.identified_patterns
|
|
}
|
|
|
|
enhanced_request['recommendations'] = [
|
|
f"File last modified by {file_context.last_modifier}",
|
|
f"Related to decisions: {file_context.related_decisions}",
|
|
f"Known patterns: {file_context.identified_patterns}"
|
|
]
|
|
|
|
# Enhance Write operations with context
|
|
elif tool_request.tool == 'Write':
|
|
write_context = await get_write_context(
|
|
tool_request.target_file,
|
|
current_context
|
|
)
|
|
|
|
enhanced_request['context_enhancement'] = {
|
|
'affected_components': write_context.impact_analysis,
|
|
'required_approvals': write_context.approval_requirements,
|
|
'testing_implications': write_context.testing_needs,
|
|
'documentation_updates': write_context.doc_updates_needed
|
|
}
|
|
|
|
# Automatically create todos for related tasks
|
|
if write_context.creates_follow_up_tasks:
|
|
follow_up_todos = await create_follow_up_todos(write_context)
|
|
enhanced_request['auto_generated_todos'] = follow_up_todos
|
|
|
|
# Enhance Grep operations with pattern intelligence
|
|
elif tool_request.tool == 'Grep':
|
|
pattern_context = await get_pattern_context(
|
|
tool_request.search_pattern,
|
|
current_context
|
|
)
|
|
|
|
enhanced_request['context_enhancement'] = {
|
|
'related_patterns': pattern_context.similar_patterns,
|
|
'anti_patterns': pattern_context.anti_patterns_to_avoid,
|
|
'suggested_refinements': pattern_context.search_improvements
|
|
}
|
|
|
|
return enhanced_request
|
|
|
|
async def execute_context_aware_tool_operation(enhanced_request):
|
|
"""
|
|
Execute tool operations with full context awareness
|
|
"""
|
|
# Pre-execution context validation
|
|
validation = await validate_operation_against_context(enhanced_request)
|
|
|
|
if not validation.is_safe:
|
|
return {
|
|
'status': 'blocked',
|
|
'reason': validation.blocking_issues,
|
|
'suggestions': validation.alternative_approaches
|
|
}
|
|
|
|
# Execute with context monitoring
|
|
execution_result = await execute_with_monitoring(enhanced_request)
|
|
|
|
# Post-execution context update
|
|
context_updates = await analyze_execution_impact(
|
|
enhanced_request,
|
|
execution_result
|
|
)
|
|
|
|
# Update global context
|
|
await update_context_with_execution_results(context_updates)
|
|
|
|
# Generate insights for future operations
|
|
insights = await extract_insights_from_execution(
|
|
enhanced_request,
|
|
execution_result,
|
|
context_updates
|
|
)
|
|
|
|
return {
|
|
'execution_result': execution_result,
|
|
'context_updates': context_updates,
|
|
'learned_insights': insights,
|
|
'status': 'completed'
|
|
}
|
|
```
|
|
|
|
### Context Persistence and Recovery
|
|
|
|
#### Context State Management
|
|
```yaml
|
|
persistence_strategy:
|
|
real_time_snapshots:
|
|
frequency: "every_significant_change"
|
|
triggers:
|
|
- decision_made: "New decision recorded"
|
|
- artifact_updated: "File modified or created"
|
|
- task_status_change: "Todo status updated"
|
|
- tool_usage: "Significant Claude Code tool operation"
|
|
|
|
recovery_mechanisms:
|
|
context_corruption:
|
|
- rollback_to_snapshot: "Restore last known good state"
|
|
- partial_reconstruction: "Rebuild from available data"
|
|
- guided_recovery: "Ask user to confirm reconstructed state"
|
|
|
|
session_interruption:
|
|
- auto_save_state: "Continuous state preservation"
|
|
- session_restoration: "Resume exactly where left off"
|
|
- context_continuity: "Maintain persona awareness across sessions"
|
|
```
|
|
|
|
#### Cross-Session Context Continuity
|
|
```python
|
|
async def restore_context_across_sessions(project_path):
|
|
"""
|
|
Restore full context when returning to a project
|
|
"""
|
|
# Load persisted context
|
|
stored_context = await load_stored_context(project_path)
|
|
|
|
# Analyze current state vs stored state
|
|
current_state = await analyze_current_project_state(project_path)
|
|
state_diff = await compare_states(stored_context, current_state)
|
|
|
|
if state_diff.has_changes:
|
|
# Context reconstruction needed
|
|
reconstruction_plan = await create_reconstruction_plan(state_diff)
|
|
|
|
# Apply automatic updates
|
|
auto_updates = await apply_automatic_updates(reconstruction_plan)
|
|
|
|
# Identify items needing manual review
|
|
manual_review_items = reconstruction_plan.manual_review_needed
|
|
|
|
if manual_review_items:
|
|
# Present changes to user for confirmation
|
|
user_confirmations = await request_user_confirmations(
|
|
manual_review_items
|
|
)
|
|
await apply_user_confirmations(user_confirmations)
|
|
|
|
# Restore persona states
|
|
await restore_persona_states(stored_context.persona_states)
|
|
|
|
# Re-establish tool monitoring
|
|
await restart_context_synchronization()
|
|
|
|
return {
|
|
'context_restored': True,
|
|
'automatic_updates': auto_updates,
|
|
'manual_confirmations': len(manual_review_items) if manual_review_items else 0,
|
|
'session_continuity': 'established'
|
|
}
|
|
```
|
|
|
|
### Context-Driven Recommendations
|
|
|
|
#### Intelligent Suggestions Based on Context
|
|
```python
|
|
async def generate_context_driven_recommendations():
|
|
"""
|
|
Generate intelligent recommendations based on current project context
|
|
"""
|
|
current_context = await get_current_context()
|
|
|
|
recommendations = {
|
|
'immediate_actions': [],
|
|
'optimization_opportunities': [],
|
|
'risk_mitigations': [],
|
|
'learning_applications': []
|
|
}
|
|
|
|
# Analyze for immediate action opportunities
|
|
if current_context.has_pending_decisions:
|
|
for decision in current_context.pending_decisions:
|
|
recommendation = await generate_decision_recommendation(decision)
|
|
recommendations['immediate_actions'].append(recommendation)
|
|
|
|
# Identify optimization opportunities
|
|
optimization_analysis = await analyze_optimization_opportunities(current_context)
|
|
recommendations['optimization_opportunities'] = optimization_analysis
|
|
|
|
# Assess risks and suggest mitigations
|
|
risk_analysis = await assess_context_risks(current_context)
|
|
recommendations['risk_mitigations'] = generate_risk_mitigations(risk_analysis)
|
|
|
|
# Suggest applying learned patterns
|
|
applicable_learning = await identify_applicable_learning(current_context)
|
|
recommendations['learning_applications'] = applicable_learning
|
|
|
|
return recommendations
|
|
```
|
|
|
|
### Claude Code Integration Commands
|
|
|
|
```bash
|
|
# Context management commands
|
|
bmad context status --detailed
|
|
bmad context sync --force
|
|
bmad context restore --from-snapshot "2024-01-15T10:30:00Z"
|
|
|
|
# Context-aware operations
|
|
bmad context analyze --risks --opportunities
|
|
bmad context recommend --based-on "current-state"
|
|
bmad context validate --against-decisions
|
|
|
|
# Context sharing and collaboration
|
|
bmad context share --with-persona "architect" --scope "security-decisions"
|
|
bmad context merge --from-session "uuid" --resolve-conflicts
|
|
bmad context broadcast --update "new-security-requirements"
|
|
```
|
|
|
|
This Context Synchronizer transforms Claude Code into a context-aware development environment where every action is informed by the full project context, enabling more intelligent decision-making and seamless collaboration between AI personas. |