@girardmedia/bootspring 2.0.36 → 2.0.37

package/core/planning/stage-planner.js

@@ -0,0 +1,624 @@
+/**
+ * Bootspring Stage Planner
+ *
+ * Stage-aware planning for different project phases:
+ * - Discovery: New projects, pivots, major features
+ * - Definition: Ready to build, defining scope
+ * - Execution: During build, sprint planning
+ * - Iteration: Post-MVP, feedback incorporation
+ * - Scale: Growth phase, technical debt
+ *
+ * @package bootspring
+ * @module core/planning/stage-planner
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Planning stages with their characteristics
+ */
+const PLANNING_STAGES = {
+  discovery: {
+    name: 'Discovery',
+    description: 'Understanding the problem space and opportunity',
+    triggers: ['new project', 'pivot', 'major feature', 'exploration'],
+
+    documents: ['vision', 'audience', 'market', 'competitors'],
+
+    questions: [
+      'What problem does this solve?',
+      'Who experiences this problem?',
+      'Why hasn\'t this been solved before?',
+      'What makes now the right time?',
+      'What is our unique advantage?',
+      'How big is the opportunity?'
+    ],
+
+    activities: [
+      'User research and interviews',
+      'Market analysis',
+      'Competitive landscape review',
+      'Technical feasibility assessment',
+      'Risk identification'
+    ],
+
+    outputs: {
+      vision: 'VISION.md - Core problem, solution, and success metrics',
+      audience: 'AUDIENCE.md - User personas and needs',
+      market: 'MARKET.md - Market size and opportunity',
+      competitors: 'COMPETITORS.md - Competitive analysis'
+    },
+
+    analysisDepth: 'shallow',
+    aiPromptStyle: 'exploratory',
+
+    completionCriteria: [
+      'Problem clearly defined',
+      'Target audience identified',
+      'Market opportunity validated',
+      'Technical feasibility confirmed'
+    ]
+  },
+
+  definition: {
+    name: 'Definition',
+    description: 'Defining what to build and how',
+    triggers: ['vision approved', 'ready to build', 'scope definition'],
+
+    documents: ['prd', 'technical-spec', 'business-model', 'roadmap'],
+
+    questions: [
+      'What is the minimum viable feature set?',
+      'What technology stack fits best?',
+      'How will this make money?',
+      'What are the key milestones?',
+      'What are the critical risks?',
+      'What resources are needed?'
+    ],
+
+    activities: [
+      'Feature prioritization',
+      'Architecture design',
+      'Tech stack selection',
+      'Business model development',
+      'Roadmap creation',
+      'Resource planning'
+    ],
+
+    outputs: {
+      prd: 'PRD.md - Product requirements and user stories',
+      technicalSpec: 'TECHNICAL_SPEC.md - Architecture and tech decisions',
+      businessModel: 'BUSINESS_MODEL.md - Revenue and growth strategy',
+      roadmap: 'ROADMAP.md - Milestones and timeline'
+    },
+
+    analysisDepth: 'deep',
+    aiPromptStyle: 'decisive',
+
+    completionCriteria: [
+      'MVP scope defined',
+      'Architecture documented',
+      'Tech stack chosen',
+      'Roadmap created'
+    ]
+  },
+
+  execution: {
+    name: 'Execution',
+    description: 'Building the product',
+    triggers: ['development started', 'sprint planning', 'active build'],
+
+    documents: ['sprint', 'tasks', 'blockers', 'decisions'],
+
+    questions: [
+      'What should be built this sprint?',
+      'What are the blockers?',
+      'What is the critical path?',
+      'Are we on track for milestones?',
+      'What decisions need to be made?',
+      'What has changed since last sprint?'
+    ],
+
+    activities: [
+      'Sprint planning',
+      'Daily standups',
+      'Code reviews',
+      'Technical decisions',
+      'Blocker resolution',
+      'Progress tracking'
+    ],
+
+    outputs: {
+      sprint: 'SPRINT.md - Current sprint goals and tasks',
+      tasks: 'TASKS.md - Detailed task breakdown',
+      blockers: 'BLOCKERS.md - Current blockers and resolutions',
+      decisions: 'DECISIONS.md - Architectural decision records'
+    },
+
+    analysisDepth: 'focused',
+    aiPromptStyle: 'tactical',
+
+    completionCriteria: [
+      'Sprint goals defined',
+      'Tasks estimated',
+      'Dependencies mapped',
+      'Blockers identified'
+    ]
+  },
+
+  iteration: {
+    name: 'Iteration',
+    description: 'Post-MVP refinement based on feedback',
+    triggers: ['mvp launched', 'feedback received', 'metrics review'],
+
+    documents: ['feedback', 'iteration', 'metrics', 'learnings'],
+
+    questions: [
+      'What feedback are we getting?',
+      'What metrics are we seeing?',
+      'What needs to change?',
+      'What\'s working well?',
+      'What should we double down on?',
+      'What should we cut?'
+    ],
+
+    activities: [
+      'User feedback analysis',
+      'Metrics review',
+      'Feature prioritization update',
+      'Quick wins identification',
+      'Technical debt assessment',
+      'Growth experiments'
+    ],
+
+    outputs: {
+      feedback: 'FEEDBACK.md - User feedback summary',
+      iteration: 'ITERATION.md - Planned changes',
+      metrics: 'METRICS.md - Key performance indicators',
+      learnings: 'LEARNINGS.md - What we\'ve learned'
+    },
+
+    analysisDepth: 'moderate',
+    aiPromptStyle: 'analytical',
+
+    completionCriteria: [
+      'Feedback analyzed',
+      'Metrics baseline established',
+      'Iteration priorities set',
+      'Success criteria updated'
+    ]
+  },
+
+  scale: {
+    name: 'Scale',
+    description: 'Growth phase optimization',
+    triggers: ['growth phase', 'scaling issues', 'team growth'],
+
+    documents: ['scale', 'tech-debt', 'team', 'infrastructure'],
+
+    questions: [
+      'What\'s breaking under load?',
+      'What technical debt exists?',
+      'What team changes are needed?',
+      'What infrastructure updates are required?',
+      'What processes need improvement?',
+      'What are the next growth bottlenecks?'
+    ],
+
+    activities: [
+      'Performance optimization',
+      'Technical debt cleanup',
+      'Team scaling',
+      'Infrastructure planning',
+      'Process improvement',
+      'Documentation update'
+    ],
+
+    outputs: {
+      scale: 'SCALE.md - Scaling strategy',
+      techDebt: 'TECH_DEBT.md - Technical debt backlog',
+      team: 'TEAM.md - Team structure and needs',
+      infrastructure: 'INFRASTRUCTURE.md - Infrastructure plan'
+    },
+
+    analysisDepth: 'comprehensive',
+    aiPromptStyle: 'strategic',
+
+    completionCriteria: [
+      'Scaling bottlenecks identified',
+      'Technical debt cataloged',
+      'Team plan created',
+      'Infrastructure roadmap defined'
+    ]
+  }
+};
+
+/**
+ * Stage Planner class
+ */
+class StagePlanner {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.stateFile = path.join(projectRoot, '.bootspring', 'planning-state.json');
+  }
+
+  /**
+   * Detect current planning stage
+   */
+  async detectStage() {
+    const signals = await this.gatherStageSignals();
+
+    // Score each stage based on signals
+    const scores = {};
+    for (const [stageName, stage] of Object.entries(PLANNING_STAGES)) {
+      scores[stageName] = this.scoreStage(stageName, stage, signals);
+    }
+
+    // Find highest scoring stage
+    let bestStage = 'discovery';
+    let bestScore = 0;
+    for (const [stage, score] of Object.entries(scores)) {
+      if (score > bestScore) {
+        bestScore = score;
+        bestStage = stage;
+      }
+    }
+
+    return {
+      detectedStage: bestStage,
+      confidence: Math.min(bestScore / 10, 1),
+      signals,
+      scores,
+      recommendation: this.getStageRecommendation(bestStage, signals)
+    };
+  }
+
+  /**
+   * Gather signals about project state
+   */
+  async gatherStageSignals() {
+    const signals = {
+      hasVision: false,
+      hasPrd: false,
+      hasCode: false,
+      hasTests: false,
+      hasDeployment: false,
+      hasUsers: false,
+      hasMetrics: false,
+      codebaseSize: 'none',
+      gitHistory: 'none',
+      recentActivity: 'low'
+    };
+
+    try {
+      // Check for preseed documents
+      const preseedDir = path.join(this.projectRoot, '.bootspring', 'preseed');
+      if (fs.existsSync(preseedDir)) {
+        signals.hasVision = fs.existsSync(path.join(preseedDir, 'VISION.md'));
+        signals.hasPrd = fs.existsSync(path.join(preseedDir, 'PRD.md'));
+      }
+
+      // Check for code
+      const srcPaths = ['src', 'app', 'pages', 'lib'];
+      for (const srcPath of srcPaths) {
+        if (fs.existsSync(path.join(this.projectRoot, srcPath))) {
+          signals.hasCode = true;
+          break;
+        }
+      }
+
+      // Check for tests
+      const testPaths = ['__tests__', 'tests', 'test', 'spec'];
+      for (const testPath of testPaths) {
+        if (fs.existsSync(path.join(this.projectRoot, testPath))) {
+          signals.hasTests = true;
+          break;
+        }
+      }
+
+      // Check for deployment config
+      const deployPaths = ['vercel.json', 'fly.toml', 'railway.json', 'Dockerfile', '.github/workflows'];
+      for (const deployPath of deployPaths) {
+        if (fs.existsSync(path.join(this.projectRoot, deployPath))) {
+          signals.hasDeployment = true;
+          break;
+        }
+      }
+
+      // Estimate codebase size
+      const packageJson = path.join(this.projectRoot, 'package.json');
+      if (fs.existsSync(packageJson)) {
+        const pkg = JSON.parse(fs.readFileSync(packageJson, 'utf8'));
+        const depCount = Object.keys(pkg.dependencies || {}).length;
+        if (depCount > 20) signals.codebaseSize = 'large';
+        else if (depCount > 10) signals.codebaseSize = 'medium';
+        else if (depCount > 0) signals.codebaseSize = 'small';
+      }
+
+      // Check git history
+      const gitDir = path.join(this.projectRoot, '.git');
+      if (fs.existsSync(gitDir)) {
+        signals.gitHistory = 'exists';
+      }
+
+    } catch (_err) {
+      // Signal gathering failed, use defaults
+    }
+
+    return signals;
+  }
+
+  /**
+   * Score a stage based on signals
+   */
+  scoreStage(stageName, stage, signals) {
+    let score = 0;
+
+    switch (stageName) {
+      case 'discovery':
+        if (!signals.hasVision) score += 3;
+        if (!signals.hasPrd) score += 2;
+        if (!signals.hasCode || signals.codebaseSize === 'small') score += 2;
+        break;
+
+      case 'definition':
+        if (signals.hasVision && !signals.hasPrd) score += 4;
+        if (!signals.hasCode) score += 2;
+        if (signals.codebaseSize === 'small') score += 1;
+        break;
+
+      case 'execution':
+        if (signals.hasPrd && signals.hasCode) score += 4;
+        if (signals.codebaseSize === 'medium') score += 2;
+        if (signals.recentActivity === 'high') score += 2;
+        break;
+
+      case 'iteration':
+        if (signals.hasDeployment) score += 3;
+        if (signals.hasUsers) score += 3;
+        if (signals.codebaseSize === 'medium' || signals.codebaseSize === 'large') score += 2;
+        break;
+
+      case 'scale':
+        if (signals.hasUsers && signals.hasMetrics) score += 4;
+        if (signals.codebaseSize === 'large') score += 3;
+        if (signals.hasDeployment) score += 2;
+        break;
+    }
+
+    return score;
+  }
+
+  /**
+   * Get recommendation for a stage
+   */
+  getStageRecommendation(stageName, signals) {
+    const stage = PLANNING_STAGES[stageName];
+
+    const missingDocs = [];
+    const preseedDir = path.join(this.projectRoot, '.bootspring', 'preseed');
+
+    for (const doc of stage.documents) {
+      const docPath = path.join(preseedDir, `${doc.toUpperCase()}.md`);
+      if (!fs.existsSync(docPath)) {
+        missingDocs.push(doc);
+      }
+    }
+
+    return {
+      stage: stageName,
+      name: stage.name,
+      description: stage.description,
+      keyQuestions: stage.questions.slice(0, 3),
+      suggestedActivities: stage.activities.slice(0, 3),
+      missingDocuments: missingDocs,
+      nextSteps: this.getNextSteps(stageName, signals, missingDocs)
+    };
+  }
+
+  /**
+   * Get next steps for a stage
+   */
+  getNextSteps(stageName, signals, missingDocs) {
+    const steps = [];
+
+    if (missingDocs.length > 0) {
+      steps.push(`Generate missing documents: ${missingDocs.join(', ')}`);
+      steps.push('Run: bootspring preseed from-codebase --deep');
+    }
+
+    switch (stageName) {
+      case 'discovery':
+        steps.push('Answer the discovery questions');
+        steps.push('Validate problem with potential users');
+        break;
+
+      case 'definition':
+        steps.push('Define MVP feature set');
+        steps.push('Choose technology stack');
+        steps.push('Create initial roadmap');
+        break;
+
+      case 'execution':
+        steps.push('Set up sprint board');
+        steps.push('Break down features into tasks');
+        steps.push('Identify blockers early');
+        break;
+
+      case 'iteration':
+        steps.push('Set up user feedback collection');
+        steps.push('Define key metrics');
+        steps.push('Plan A/B tests');
+        break;
+
+      case 'scale':
+        steps.push('Audit performance bottlenecks');
+        steps.push('Catalog technical debt');
+        steps.push('Plan infrastructure upgrades');
+        break;
+    }
+
+    return steps;
+  }
+
+  /**
+   * Get planning context for a stage
+   */
+  async getStageContext(stageName) {
+    const stage = PLANNING_STAGES[stageName];
+
+    if (!stage) {
+      throw new Error(`Unknown stage: ${stageName}`);
+    }
+
+    return {
+      stage: stageName,
+      ...stage,
+      currentState: await this.gatherStageSignals(),
+      existingDocuments: await this.findExistingDocuments(stage.documents)
+    };
+  }
+
+  /**
+   * Find existing documents for a stage
+   */
+  async findExistingDocuments(documentTypes) {
+    const existing = {};
+    const preseedDir = path.join(this.projectRoot, '.bootspring', 'preseed');
+
+    for (const docType of documentTypes) {
+      const docPath = path.join(preseedDir, `${docType.toUpperCase()}.md`);
+      if (fs.existsSync(docPath)) {
+        existing[docType] = {
+          path: docPath,
+          exists: true,
+          lastModified: fs.statSync(docPath).mtime
+        };
+      } else {
+        existing[docType] = {
+          path: docPath,
+          exists: false
+        };
+      }
+    }
+
+    return existing;
+  }
+
+  /**
+   * Generate stage-appropriate AI prompt
+   */
+  generateAIPrompt(stageName, task) {
+    const stage = PLANNING_STAGES[stageName];
+
+    if (!stage) {
+      return this.generateGenericPrompt(task);
+    }
+
+    const promptStyles = {
+      exploratory: `You are helping with early-stage exploration. Be curious, ask questions, and help discover insights. Focus on understanding the problem space before jumping to solutions.`,
+
+      decisive: `You are helping make key decisions. Be structured, evaluate trade-offs clearly, and provide concrete recommendations. Help choose between options with clear rationale.`,
+
+      tactical: `You are helping with day-to-day execution. Be practical, focus on immediate next steps, and help remove blockers. Keep suggestions actionable and time-bound.`,
+
+      analytical: `You are helping analyze feedback and data. Be objective, look for patterns, and help prioritize based on evidence. Separate signal from noise.`,
+
+      strategic: `You are helping with long-term planning. Think about scalability, sustainability, and team growth. Balance quick wins with foundational investments.`
+    };
+
+    const stylePrompt = promptStyles[stage.aiPromptStyle] || promptStyles.tactical;
+
+    return `${stylePrompt}
+
+Current project stage: ${stage.name}
+Stage description: ${stage.description}
+
+Key questions for this stage:
+${stage.questions.map(q => `- ${q}`).join('\n')}
+
+Task: ${task}
+
+Consider the stage-appropriate depth (${stage.analysisDepth}) and focus on outputs relevant to this stage.`;
+  }
+
+  /**
+   * Generate generic prompt
+   */
+  generateGenericPrompt(task) {
+    return `Help with the following task: ${task}`;
+  }
+
+  /**
+   * Save planning state
+   */
+  async saveState(state) {
+    const dir = path.dirname(this.stateFile);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(this.stateFile, JSON.stringify(state, null, 2));
+  }
+
+  /**
+   * Load planning state
+   */
+  loadState() {
+    if (fs.existsSync(this.stateFile)) {
+      return JSON.parse(fs.readFileSync(this.stateFile, 'utf8'));
+    }
+
+    return {
+      currentStage: null,
+      stageHistory: [],
+      lastUpdated: null
+    };
+  }
+
+  /**
+   * Transition to a new stage
+   */
+  async transitionTo(newStage, reason) {
+    const state = this.loadState();
+
+    if (state.currentStage) {
+      state.stageHistory.push({
+        stage: state.currentStage,
+        exitedAt: new Date().toISOString(),
+        reason
+      });
+    }
+
+    state.currentStage = newStage;
+    state.lastUpdated = new Date().toISOString();
+
+    await this.saveState(state);
+
+    return {
+      previousStage: state.stageHistory[state.stageHistory.length - 1]?.stage,
+      currentStage: newStage,
+      stageInfo: PLANNING_STAGES[newStage],
+      nextSteps: this.getNextSteps(newStage, await this.gatherStageSignals(), [])
+    };
+  }
+
+  /**
+   * Get all stages info
+   */
+  getAllStages() {
+    return Object.entries(PLANNING_STAGES).map(([key, stage]) => ({
+      id: key,
+      name: stage.name,
+      description: stage.description,
+      documents: stage.documents,
+      triggers: stage.triggers
+    }));
+  }
+}
+
+module.exports = {
+  StagePlanner,
+  PLANNING_STAGES
+};