23 KiB

Raw Blame History

Phase 3: Strategic + Tactical Web Unification Migration Strategy

Migration Overview

This document outlines the migration strategy for Phase 3, which will unify strategic planning (BMad) and tactical task management (Task Master) into a single web-based interface through the Directus Task Management Suite.

Current State Analysis

Existing Systems Architecture

Strategic Level (BMad):
┌─────────────────┐
│ BMad Planning   │ → Local files (.bmad-core/)
│ - PRDs          │ → Manual document management
│ - Architecture  │ → CLI-based agent workflows
│ - Research      │ → Scattered planning artifacts
└─────────────────┘

Tactical Level (Task Master):
┌─────────────────┐
│ Task Master CLI │ → Command-line task tracking  
│ - Projects      │ → Local JSON files
│ - Tasks         │ → Individual markdown files
│ - Dependencies  │ → CLI-based management
└─────────────────┘

Integration Layer (Phase 1-2):
┌─────────────────┐
│ Directus Suite  │ → Web-based task management
│ - Task CRUD     │ → Basic task operations
│ - AI Integration│ → Agent context provision
│ - BMad Tracking │ → Workflow step monitoring
└─────────────────┘

Target State Architecture

Unified Web Interface (Phase 3):
┌─────────────────────────────────────────────────────┐
│                Strategic Planning                   │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐   │
│  │ BMad Projects│ │ Planning    │ │ Research    │   │
│  │ & Epics     │ │ Documents   │ │ Analysis    │   │
│  └─────────────┘ └─────────────┘ └─────────────┘   │
├─────────────────────────────────────────────────────┤
│                Tactical Management                  │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐   │
│  │ Task        │ │ Progress    │ │ Team        │   │
│  │ Management  │ │ Tracking    │ │ Collaboration│   │
│  └─────────────┘ └─────────────┘ └─────────────┘   │
└─────────────────────────────────────────────────────┘
                         │
    ┌────────────────────┼────────────────────┐
    │                    │                    │
┌───▼────┐        ┌──────▼──────┐      ┌─────▼─────┐
│ Claude │        │   BMad      │      │ Task      │
│ Agents │        │ Workflows   │      │ Master    │
│        │        │ (Optional)  │      │ (Sync)    │
└────────┘        └─────────────┘      └───────────┘

Migration Strategy

Phase 3A: Strategic Collections Implementation (Weeks 9-10)

New Collections for Strategic Planning

1. BMad Projects Collection

bmad_projects {
  id: uuid (primary key)
  name: string (required, indexed)
  description: text
  bmad_phase: enum ['planning', 'development', 'review', 'complete']
  project_type: enum ['greenfield', 'brownfield', 'maintenance']
  methodology_version: string (e.g., "bmad-v2.0")
  
  -- Strategic metadata
  business_objectives: json
  success_metrics: json
  stakeholders: json
  risk_assessment: json
  
  -- Planning artifacts
  planning_documents: relation (one-to-many with planning_documents)
  research_outputs: json
  architecture_decisions: json
  
  -- Tactical links
  tactical_projects: relation (many-to-many with projects)
  user_stories: relation (computed from linked tactical tasks)
  
  -- Workflow tracking
  methodology_compliance: json
  phase_completion: json
  quality_gates: json
  
  -- Standard fields
  created_by: uuid (foreign key to directus_users.id)
  assigned_pm: uuid (foreign key to directus_users.id, nullable)
  start_date: date (nullable)
  target_completion: date (nullable)
  actual_completion: date (nullable)
  status: enum ['active', 'on_hold', 'completed', 'archived']
  
  created_at: timestamp (auto)
  updated_at: timestamp (auto)
}

2. Planning Documents Collection

planning_documents {
  id: uuid (primary key)
  title: string (required, indexed)
  content: text (rich text/markdown)
  document_type: enum ['prd', 'architecture', 'research', 'validation', 'user_stories', 'implementation_guide']
  
  -- BMad integration
  bmad_project: uuid (foreign key to bmad_projects.id)
  bmad_phase: enum ['pm', 'architect', 'analyst', 'po', 'sm', 'dev']
  bmad_agent: string (agent that created/manages document)
  
  -- Document management
  version: integer (document versioning)
  parent_version: uuid (foreign key to planning_documents.id, nullable)
  status: enum ['draft', 'review', 'approved', 'archived']
  
  -- Content metadata
  word_count: integer (computed)
  estimated_read_time: integer (computed)
  last_reviewed: timestamp (nullable)
  
  -- Collaboration
  created_by: uuid (foreign key to directus_users.id)
  reviewers: json (array of user IDs)
  approval_status: json
  
  -- Integration
  related_tasks: relation (many-to-many with tasks)
  external_refs: json (links to files, repos, etc.)
  
  created_at: timestamp (auto)
  updated_at: timestamp (auto)
}

3. BMad Workflows Collection (Enhanced)

bmad_workflows {
  id: uuid (primary key)
  
  -- Strategic or tactical level
  bmad_project: uuid (foreign key to bmad_projects.id, nullable)
  tactical_task: uuid (foreign key to tasks.id, nullable)
  
  -- Workflow definition
  workflow_type: enum ['strategic_planning', 'epic_breakdown', 'tactical_execution']
  bmad_phase: enum ['pm', 'architect', 'analyst', 'po', 'sm', 'dev', 'qa']
  workflow_step: string
  step_order: integer
  
  -- Status and progress
  step_status: enum ['pending', 'in_progress', 'completed', 'skipped', 'blocked']
  completion_percentage: integer (0-100)
  quality_score: integer (1-10, nullable)
  
  -- Agent integration
  assigned_agent: string (nullable)
  agent_context: json
  automation_rules: json
  
  -- Deliverables and artifacts
  expected_deliverables: json
  actual_deliverables: json
  artifacts_generated: json
  
  -- Time tracking
  estimated_duration: interval (nullable)
  actual_duration: interval (nullable)
  started_at: timestamp (nullable)
  completed_at: timestamp (nullable)
  
  -- Dependencies
  depends_on_steps: relation (many-to-many with bmad_workflows)
  blocks_steps: relation (many-to-many with bmad_workflows)
  
  created_at: timestamp (auto)
  updated_at: timestamp (auto)
}

Migration Process for Strategic Collections

Step 1: Data Migration from BMad Core

// Migration service for existing BMad artifacts
export class BMadMigrationService {
  async migrateBMadProjects(): Promise<void> {
    const bmadProjects = await this.scanBMadDirectory('.bmad-core/');
    
    for (const project of bmadProjects) {
      // Create strategic BMad project
      const bmadProject = await this.directus.createItem('bmad_projects', {
        name: project.name,
        description: project.description,
        bmad_phase: this.determineBMadPhase(project),
        project_type: project.type || 'greenfield',
        methodology_version: 'bmad-v2.0',
        business_objectives: project.objectives,
        planning_documents: [], // Will be linked separately
        status: 'active'
      });
      
      // Migrate planning documents
      await this.migratePlanningDocuments(bmadProject.id, project.documents);
      
      // Link to existing tactical projects
      await this.linkTacticalProjects(bmadProject.id, project.tacticalLinks);
    }
  }
  
  private async migratePlanningDocuments(bmadProjectId: string, documents: any[]): Promise<void> {
    for (const doc of documents) {
      await this.directus.createItem('planning_documents', {
        title: doc.title,
        content: doc.content,
        document_type: this.mapDocumentType(doc.filename),
        bmad_project: bmadProjectId,
        bmad_phase: this.extractBMadPhase(doc),
        version: 1,
        status: 'approved',
        created_by: await this.getCurrentUserId()
      });
    }
  }
  
  private mapDocumentType(filename: string): string {
    const mapping = {
      'prd.md': 'prd',
      'architecture.md': 'architecture', 
      'research.md': 'research',
      'validation.md': 'validation',
      'user-stories.md': 'user_stories',
      'implementation-guides.md': 'implementation_guide'
    };
    
    const type = Object.keys(mapping).find(key => filename.includes(key));
    return type ? mapping[type] : 'prd';
  }
}

Phase 3B: Enhanced Task Schema (Weeks 11-12)

Task Collection Enhancements for Strategic Integration

Enhanced Task Schema:

-- Add strategic-tactical linking fields to existing tasks collection
ALTER TABLE tasks ADD COLUMN strategic_level enum('epic', 'user_story', 'task', 'subtask');
ALTER TABLE tasks ADD COLUMN bmad_project uuid REFERENCES bmad_projects(id);
ALTER TABLE tasks ADD COLUMN parent_user_story uuid REFERENCES tasks(id);
ALTER TABLE tasks ADD COLUMN strategic_importance enum('low', 'medium', 'high', 'critical');
ALTER TABLE tasks ADD COLUMN business_value integer; -- 1-100 scale
ALTER TABLE tasks ADD COLUMN strategic_context json; -- Links to strategic planning artifacts

-- Create strategic-tactical mapping view
CREATE VIEW strategic_tactical_hierarchy AS
SELECT 
  bp.id as bmad_project_id,
  bp.name as strategic_name,
  bp.bmad_phase as strategic_phase,
  p.id as tactical_project_id,
  p.name as tactical_name,
  COUNT(t.id) as tactical_task_count,
  AVG(t.progress_percentage) as tactical_progress
FROM bmad_projects bp
LEFT JOIN projects p ON p.bmad_project = bp.id
LEFT JOIN tasks t ON t.project = p.id
GROUP BY bp.id, p.id;

Migration Process for Enhanced Tasks:

export class TaskEnhancementMigration {
  async enhanceExistingTasks(): Promise<void> {
    // 1. Identify strategic tasks (epics, user stories)
    const strategicTasks = await this.identifyStrategicTasks();
    
    for (const task of strategicTasks) {
      await this.directus.updateItem('tasks', task.id, {
        strategic_level: this.determineStrategicLevel(task),
        strategic_importance: this.calculateStrategicImportance(task),
        business_value: this.calculateBusinessValue(task)
      });
    }
    
    // 2. Link tactical tasks to BMad projects
    await this.linkTasksToBMadProjects();
    
    // 3. Create user story hierarchies
    await this.createUserStoryHierarchies();
  }
  
  private async linkTasksToBMadProjects(): Promise<void> {
    const tacticalProjects = await this.directus.readItems('projects', {
      filter: { repository_url: { _nnull: true } }
    });
    
    for (const project of tacticalProjects.data) {
      // Find matching BMad project based on repository or naming patterns
      const bmadProject = await this.findMatchingBMadProject(project);
      
      if (bmadProject) {
        await this.directus.updateItem('projects', project.id, {
          bmad_project: bmadProject.id
        });
      }
    }
  }
}

Phase 3C: Unified Web Interface (Weeks 13-14)

Strategic Planning Dashboard

Strategic Dashboard Component:

<template>
  <div class="strategic-dashboard">
    <!-- BMad Projects Overview -->
    <div class="bmad-projects-section">
      <h2>Strategic Initiatives</h2>
      <div class="projects-grid">
        <bmad-project-card 
          v-for="project in bmadProjects" 
          :key="project.id"
          :project="project"
          @view-details="viewBMadProject"
        />
      </div>
    </div>
    
    <!-- Strategic to Tactical Flow -->
    <div class="strategic-tactical-flow">
      <h3>Strategic → Tactical Progress</h3>
      <strategic-tactical-timeline 
        :bmad-projects="bmadProjects"
        :tactical-projects="linkedTacticalProjects"
      />
    </div>
    
    <!-- Planning Documents Management -->
    <div class="planning-documents">
      <h3>Planning Artifacts</h3>
      <planning-document-manager 
        :documents="planningDocuments"
        @create-document="createPlanningDocument"
        @update-document="updatePlanningDocument"
      />
    </div>
  </div>
</template>

<script>
export default {
  name: 'StrategicDashboard',
  
  data() {
    return {
      bmadProjects: [],
      linkedTacticalProjects: [],
      planningDocuments: []
    };
  },
  
  async mounted() {
    await this.loadStrategicData();
  },
  
  methods: {
    async loadStrategicData() {
      // Load BMad projects with tactical links
      this.bmadProjects = await this.directusApi.readItems('bmad_projects', {
        fields: [
          '*',
          'tactical_projects.id',
          'tactical_projects.name', 
          'tactical_projects.completion_percentage',
          'planning_documents.id',
          'planning_documents.title',
          'planning_documents.document_type',
          'planning_documents.status'
        ]
      });
      
      // Load planning documents
      this.planningDocuments = await this.directusApi.readItems('planning_documents', {
        filter: { status: { _neq: 'archived' } },
        sort: ['-updated_at']
      });
    },
    
    async viewBMadProject(projectId) {
      this.$router.push(`/strategic/bmad-projects/${projectId}`);
    },
    
    async createPlanningDocument(documentData) {
      const newDoc = await this.directusApi.createItem('planning_documents', documentData);
      this.planningDocuments.unshift(newDoc);
    }
  }
};
</script>

Unified Task Management Interface

Enhanced Task Interface with Strategic Context:

<template>
  <div class="unified-task-interface">
    <!-- Strategic Context Bar -->
    <div class="strategic-context-bar" v-if="task.bmad_project">
      <div class="strategic-info">
        <span class="bmad-project">{{ task.bmad_project.name }}</span>
        <span class="strategic-phase">{{ task.bmad_project.bmad_phase }}</span>
        <span class="business-value">Value: {{ task.business_value || 'N/A' }}</span>
      </div>
      <div class="strategic-actions">
        <button @click="viewStrategicContext">View Strategic Context</button>
        <button @click="linkToUserStory">Link to User Story</button>
      </div>
    </div>
    
    <!-- Standard Task Interface -->
    <div class="task-content">
      <task-detail-form 
        :task="task" 
        :enhanced-fields="strategicFields"
        @update="updateTask"
      />
    </div>
    
    <!-- Strategic Planning Integration -->
    <div class="strategic-integration" v-if="showStrategicIntegration">
      <h4>Strategic Planning Artifacts</h4>
      <div class="related-documents">
        <planning-document-link 
          v-for="doc in relatedPlanningDocs"
          :key="doc.id"
          :document="doc"
        />
      </div>
      
      <div class="bmad-workflow-tracking">
        <bmad-workflow-steps 
          :task-id="task.id"
          :workflow-steps="bmadWorkflowSteps"
          @update-step="updateWorkflowStep"
        />
      </div>
    </div>
  </div>
</template>

<script>
export default {
  name: 'UnifiedTaskInterface',
  
  props: {
    taskId: String
  },
  
  data() {
    return {
      task: null,
      relatedPlanningDocs: [],
      bmadWorkflowSteps: [],
      showStrategicIntegration: false
    };
  },
  
  computed: {
    strategicFields() {
      return [
        'strategic_level',
        'strategic_importance', 
        'business_value',
        'parent_user_story',
        'bmad_project'
      ];
    }
  },
  
  async mounted() {
    await this.loadTaskWithStrategicContext();
  },
  
  methods: {
    async loadTaskWithStrategicContext() {
      this.task = await this.directusApi.readItem('tasks', this.taskId, {
        fields: [
          '*',
          'bmad_project.*',
          'parent_user_story.*',
          'project.*',
          'status.*'
        ]
      });
      
      if (this.task.bmad_project) {
        this.showStrategicIntegration = true;
        await this.loadStrategicContext();
      }
    },
    
    async loadStrategicContext() {
      // Load related planning documents
      this.relatedPlanningDocs = await this.directusApi.readItems('planning_documents', {
        filter: { 
          bmad_project: { _eq: this.task.bmad_project.id }
        }
      });
      
      // Load BMad workflow steps
      this.bmadWorkflowSteps = await this.directusApi.readItems('bmad_workflows', {
        filter: {
          tactical_task: { _eq: this.task.id }
        },
        sort: ['step_order']
      });
    },
    
    async viewStrategicContext() {
      this.$router.push(`/strategic/bmad-projects/${this.task.bmad_project.id}`);
    },
    
    async updateWorkflowStep(stepId, stepData) {
      await this.directusApi.updateItem('bmad_workflows', stepId, stepData);
      await this.loadStrategicContext(); // Refresh workflow steps
    }
  }
};
</script>

Phase 3D: Task Master Integration Evolution (Week 15-16)

Enhanced Task Master Sync for Strategic Context

Strategic Context Sync Service:

export class StrategicTaskMasterSync extends TaskMasterSyncService {
  async syncStrategicContext(): Promise<void> {
    // Sync strategic metadata to Task Master
    const tasksWithStrategicContext = await this.directus.readItems('tasks', {
      filter: {
        _and: [
          { task_master_id: { _nnull: true } },
          { bmad_project: { _nnull: true } }
        ]
      },
      fields: ['*', 'bmad_project.*', 'parent_user_story.*']
    });
    
    for (const task of tasksWithStrategicContext.data) {
      await this.updateTaskMasterWithStrategicContext(task);
    }
  }
  
  private async updateTaskMasterWithStrategicContext(task: any): Promise<void> {
    const strategicMetadata = {
      bmad_project: task.bmad_project?.name,
      strategic_level: task.strategic_level,
      strategic_importance: task.strategic_importance,
      business_value: task.business_value,
      strategic_links: {
        bmad_project_id: task.bmad_project?.id,
        planning_documents: await this.getRelatedPlanningDocuments(task.bmad_project?.id)
      }
    };
    
    await this.executeTaskMasterCommand([
      'update-task',
      '--id', task.task_master_id,
      '--strategic-metadata', JSON.stringify(strategicMetadata)
    ]);
  }
  
  async exportStrategicSummary(bmadProjectId: string): Promise<void> {
    // Export strategic summary for Task Master projects
    const bmadProject = await this.directus.readItem('bmad_projects', bmadProjectId, {
      fields: [
        '*',
        'tactical_projects.*',
        'planning_documents.*'
      ]
    });
    
    const strategicSummary = {
      bmad_project: bmadProject,
      tactical_projects: bmadProject.tactical_projects,
      planning_artifacts: bmadProject.planning_documents,
      task_summary: await this.generateTaskSummary(bmadProjectId)
    };
    
    // Export to Task Master as project documentation
    await this.executeTaskMasterCommand([
      'create-project-doc',
      '--type', 'strategic-summary',
      '--data', JSON.stringify(strategicSummary)
    ]);
  }
}

Migration Timeline & Rollout Strategy

Pre-Migration Phase (Week 8)

Complete Phase 2 implementation and testing
Backup all existing BMad and Task Master data
Create migration testing environment
Document rollback procedures

Migration Execution (Weeks 9-16)

Week 9-10: Strategic Collections

Implement bmad_projects and planning_documents collections
Migrate existing BMad artifacts from .bmad-core/
Test strategic dashboard basic functionality
Validate data migration integrity

Week 11-12: Task Enhancement

Add strategic fields to tasks collection
Migrate existing strategic tasks (epics, user stories)
Link tactical projects to BMad projects
Create strategic-tactical hierarchy views

Week 13-14: Unified Interface

Deploy strategic planning dashboard
Enhanced task interface with strategic context
Integration testing with existing workflows
User acceptance testing with key stakeholders

Week 15-16: Integration & Optimization

Enhanced Task Master sync with strategic context
Performance optimization for unified interface
Documentation and training materials
Production deployment and monitoring

Post-Migration Phase (Week 17+)

Validation & Optimization:

Monitor system performance and user adoption
Collect user feedback and iterate on interface
Fine-tune strategic-tactical workflow integration
Plan future enhancements based on usage patterns

Success Metrics for Phase 3

Technical Success Metrics

100% data migration without loss
<200ms response times for unified interface
99.9% uptime during migration period
All existing integrations continue to function

User Experience Metrics

90% user satisfaction with unified interface
50% reduction in context switching between strategic/tactical views
80% of strategic planning managed through web interface
Team collaboration increased by 60%

Business Value Metrics

Strategic planning cycle time reduced by 40%
Tactical execution tracking accuracy improved by 30%
Decision-making speed increased through better strategic-tactical visibility
Overall development workflow efficiency improved by 75%

Risk Management

High-Risk Areas

Data Migration Complexity: Strategic artifacts span multiple formats and locations
User Workflow Disruption: Significant change to established BMad and Task Master workflows
Performance Impact: Additional collections and relationships may impact response times
Integration Compatibility: Ensuring existing Claude Code agents continue to function

Mitigation Strategies

Extensive Testing: Comprehensive migration testing in staging environment
Phased Rollout: Gradual migration with rollback options at each phase
Performance Monitoring: Proactive monitoring and optimization during migration
Training and Support: Comprehensive documentation and user training programs

This Phase 3 migration strategy provides a clear path for unifying strategic and tactical management while maintaining compatibility with existing systems and workflows. The phased approach ensures minimal disruption while delivering significant value through the unified web interface.

23 KiB Raw Blame History