directus-task-management/planning/Phase3-Migration-Strategy.md

# 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**
```sql
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**
```sql
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)**
```sql
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**
```typescript
// 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:**
```sql
-- 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:**
```typescript
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:**
```vue
<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:**
```vue
<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:**
```typescript
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
1. **Data Migration Complexity**: Strategic artifacts span multiple formats and locations
2. **User Workflow Disruption**: Significant change to established BMad and Task Master workflows
3. **Performance Impact**: Additional collections and relationships may impact response times
4. **Integration Compatibility**: Ensuring existing Claude Code agents continue to function

### Mitigation Strategies
1. **Extensive Testing**: Comprehensive migration testing in staging environment
2. **Phased Rollout**: Gradual migration with rollback options at each phase
3. **Performance Monitoring**: Proactive monitoring and optimization during migration
4. **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.