@girardmedia/bootspring 2.4.0 → 2.5.1

package/generators/templates/build-planning.template.js

@@ -1,704 +0,0 @@
-/**
- * Bootspring Build Planning Templates
- *
- * Generates planning artifacts for the autonomous build loop:
- * - MASTER_PLAN.md - Vision + phases + progress tracker
- * - TODO.md - Checkbox list by phase
- * - TASK_QUEUE.md - Ordered tasks with acceptance criteria
- * - CONTEXT.md - Condensed context for AI iterations
- *
- * @package bootspring
- * @module generators/templates/build-planning
- */
-
-const fs = require('fs');
-const path = require('path');
-const DEFAULT_QUEUE_VERSION = '3.0.0';
-
-/**
- * Generate all planning artifacts
- * @param {string} projectRoot - Project root path
- * @param {object} docs - Source documents
- * @param {array} tasks - Extracted tasks
- * @param {object} options - Generation options
- * @returns {object} Generated file paths
- */
-function generateAll(projectRoot, docs, tasks, options = {}) {
-  const planningDir = path.join(projectRoot, 'planning');
-
-  // Ensure planning directory exists
-  if (!fs.existsSync(planningDir)) {
-    fs.mkdirSync(planningDir, { recursive: true });
-  }
-
-  const files = {};
-
-  // Generate MASTER_PLAN.md
-  const masterPlan = generateMasterPlan(docs, tasks, options);
-  const masterPlanPath = path.join(planningDir, 'MASTER_PLAN.md');
-  fs.writeFileSync(masterPlanPath, masterPlan);
-  files.masterPlan = masterPlanPath;
-
-  // Generate TODO.md
-  const todo = generateTodo(tasks, options);
-  const todoPath = path.join(planningDir, 'TODO.md');
-  fs.writeFileSync(todoPath, todo);
-  files.todo = todoPath;
-
-  // Generate TASK_QUEUE.md
-  const queue = generateImplementationQueue(tasks, options);
-  const queuePath = path.join(planningDir, 'TASK_QUEUE.md');
-  fs.writeFileSync(queuePath, queue);
-  files.implementationQueue = queuePath;
-
-  // Generate CONTEXT.md
-  const context = generateContext(docs, tasks, options);
-  const contextPath = path.join(planningDir, 'CONTEXT.md');
-  fs.writeFileSync(contextPath, context);
-  files.context = contextPath;
-
-  // Generate planning/AGENTS.md for AI coding agents
-  const agentsContent = generatePlanningAgents(options);
-  const agentsPath = path.join(planningDir, 'AGENTS.md');
-  fs.writeFileSync(agentsPath, agentsContent);
-  files.agents = agentsPath;
-
-  return files;
-}
-
-/**
- * Generate AGENTS.md for the planning directory
- * Following the open standard for AI coding agents
- */
-function generatePlanningAgents(options = {}) {
-  const projectName = options.projectName || 'Project';
-
-  return `# Planning Directory
-
-You are working on build tasks for ${projectName}. This directory contains build planning files.
-
-## Commands
-
-\`\`\`bash
-bootspring build task    # Show current task
-bootspring build done    # Mark task complete, get next
-bootspring build skip    # Skip current task
-bootspring build status  # View progress
-\`\`\`
-
-## Current Task
-
-Run \`bootspring build task\` to get the current \`in_progress\` task from \`BUILD_STATE.json\`.
-
-## Workflow
-
-1. Run \`bootspring build task\` to identify the current task ID
-2. Read the matching task in \`TODO.md\` for acceptance criteria
-3. Implement in the main codebase (not in this folder)
-4. Ensure acceptance criteria are met
-5. Run quality checks: \`npm run lint && npm run test\`
-6. Commit your changes
-7. Run \`bootspring build done\`
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| \`TODO.md\` | **Source of truth** — task checklist with acceptance criteria |
-| \`BUILD_STATE.json\` | Build state and current task ID (do not edit directly) |
-| \`CONTEXT.md\` | Build context summary |
-
-## Boundaries
-
-**Never:**
-- Edit \`BUILD_STATE.json\` directly
-- Skip quality checks
-- Work on multiple tasks simultaneously
-- Implement tasks in this planning folder
-
-**Always:**
-- Follow acceptance criteria exactly
-- Run tests before marking complete
-- Commit with conventional commit format
-`;
-}
-
-/**
- * Generate MASTER_PLAN.md
- * @param {object} docs - Source documents
- * @param {array} tasks - Extracted tasks
- * @param {object} options - Options
- * @returns {string} MASTER_PLAN.md content
- */
-function generateMasterPlan(docs, tasks, options = {}) {
-  const projectName = options.projectName || 'Project';
-  const phases = groupByPhase(tasks);
-
-  let content = `# ${projectName} - Master Build Plan
-
-> Generated by Bootspring Autonomous Build System
-> Last Updated: ${new Date().toISOString().split('T')[0]}
-
----
-
-## Overview
-
-This master plan guides the autonomous build process from foundation to MVP completion.
-Each phase contains specific tasks that will be executed sequentially by the build loop.
-
----
-
-## Progress Tracker
-
-| Phase | Status | Progress | Tasks |
-|-------|--------|----------|-------|
-`;
-
-  // Add phase progress rows
-  for (const [phaseName, phaseTasks] of Object.entries(phases)) {
-    const completed = phaseTasks.filter(t => t.status === 'completed').length;
-    const total = phaseTasks.length;
-    const percent = total > 0 ? Math.round((completed / total) * 100) : 0;
-    const status = completed === 0 ? 'Pending' :
-      completed === total ? 'Complete' : 'In Progress';
-
-    content += `| ${formatPhaseName(phaseName)} | ${status} | ${percent}% | ${completed}/${total} |\n`;
-  }
-
-  content += `
----
-
-## Phases
-
-`;
-
-  // Add phase details
-  for (const [phaseName, phaseTasks] of Object.entries(phases)) {
-    const icon = phaseName === 'foundation' ? '1' :
-      phaseName === 'mvp' ? '2' :
-        phaseName === 'launch' ? '3' : '4';
-
-    content += `### Phase ${icon}: ${formatPhaseName(phaseName)}
-
-`;
-
-    // Group tasks by source
-    const bySource = {};
-    for (const task of phaseTasks) {
-      const source = task.source || 'Manual';
-      if (!bySource[source]) bySource[source] = [];
-      bySource[source].push(task);
-    }
-
-    for (const [source, sourceTasks] of Object.entries(bySource)) {
-      content += `**From ${source}:**\n`;
-      for (const task of sourceTasks) {
-        const checkbox = task.status === 'completed' ? '[x]' : '[ ]';
-        content += `- ${checkbox} ${task.title}\n`;
-      }
-      content += '\n';
-    }
-
-    content += '---\n\n';
-  }
-
-  // Add exit criteria
-  content += `## MVP Exit Criteria
-
-The build loop will exit when:
-
-1. All MVP phase tasks are completed
-2. Quality gates pass (tests, lint, typecheck)
-3. Core user journeys are functional
-4. No critical bugs remain
-
----
-
-## Build Commands
-
-\`\`\`bash
-# Start the build loop
-bootspring seed build --loop
-
-# Check progress
-bootspring build status
-
-# Pause the build
-bootspring build pause
-
-# Resume building
-bootspring build resume
-
-# View current task
-bootspring build task
-\`\`\`
-
----
-
-*Generated by [Bootspring](https://bootspring.com) Autonomous Build System*
-`;
-
-  return content;
-}
-
-/**
- * Generate TODO.md
- * @param {array} tasks - Extracted tasks
- * @param {object} options - Options
- * @returns {string} TODO.md content
- */
-function generateTodo(tasks, options = {}) {
-  const phases = groupByPhase(tasks);
-  const projectName = options.projectName || 'Project';
-
-  let content = `# ${projectName} - Build Todo
-
-> Single source of truth for autonomous build execution
-> Updated: ${new Date().toISOString().split('T')[0]}
-
----
-
-## Program Status
-
-| Metric | Value |
-|---|---:|
-| Total Tasks | ${tasks.length} |
-| Completed | ${tasks.filter(t => t.status === 'completed').length} |
-| Remaining | ${tasks.filter(t => t.status === 'pending').length} |
-| In Progress | ${tasks.filter(t => t.status === 'in_progress').length} |
-
----
-
-`;
-
-  for (const [phaseName, phaseTasks] of Object.entries(phases)) {
-    const completed = phaseTasks.filter(t => t.status === 'completed').length;
-    const total = phaseTasks.length;
-    const percent = total > 0 ? Math.round((completed / total) * 100) : 0;
-
-    content += `## ${formatPhaseName(phaseName)} (${completed}/${total} — ${percent}%)
-
-`;
-
-    for (const task of phaseTasks) {
-      const checkbox = task.status === 'completed' ? '[x]' : '[ ]';
-      const statusTag = task.status === 'completed' ? ' (`completed`)' :
-        task.status === 'in_progress' ? ' (`in_progress`)' :
-          task.status === 'blocked' ? ' (`blocked`)' :
-            task.status === 'skipped' ? ' (`skipped`)' : '';
-      content += `- ${checkbox} \`${task.id}\` ${task.title}${statusTag}\n`;
-
-      // Source traceability
-      if (task.source) {
-        const sourceStr = task.sourceSection
-          ? `${task.source} (${task.sourceSection})`
-          : task.source;
-        content += `  - **Source:** ${sourceStr}\n`;
-      }
-
-      // Description
-      if (task.description) {
-        content += `  - **Description:** ${task.description}\n`;
-      }
-
-      // Complexity and dependencies
-      if (task.estimatedComplexity && task.estimatedComplexity !== 'medium') {
-        content += `  - **Complexity:** ${task.estimatedComplexity}\n`;
-      }
-      if (task.dependencies && task.dependencies.length > 0) {
-        content += `  - **Dependencies:** ${task.dependencies.join(', ')}\n`;
-      }
-
-      // Acceptance criteria as sub-items (all of them — this is the source of truth)
-      if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
-        for (const criteria of task.acceptanceCriteria) {
-          const subCheckbox = task.status === 'completed' ? '[x]' : '[ ]';
-          content += `  - ${subCheckbox} ${criteria}\n`;
-        }
-      }
-    }
-
-    content += '\n---\n\n';
-  }
-
-  content += `*Updated: ${new Date().toISOString()}*
-`;
-
-  return content;
-}
-
-/**
- * Generate TASK_QUEUE.md
- * @param {array} tasks - Extracted tasks
- * @param {object} options - Options
- * @returns {string} TASK_QUEUE.md content
- */
-function generateImplementationQueue(tasks, options = {}) {
-  const projectName = options.projectName || 'Project';
-  const lastUpdated = options.lastUpdated || new Date().toISOString().split('T')[0];
-  const queueVersion = options.queueVersion || DEFAULT_QUEUE_VERSION;
-
-  let content = `# ${projectName} - Implementation Queue
-
-> Ordered task queue for autonomous execution
-> **Last Updated:** ${lastUpdated}
-> **Current Version:** ${queueVersion}
-
----
-
-## Queue Status
-
-| Position | ID | Task | Phase | Complexity | Status |
-|----------|----|----- |-------|------------|--------|
-`;
-
-  tasks.forEach((task, index) => {
-    const statusIcon = task.status === 'completed' ? 'Done' :
-      task.status === 'in_progress' ? 'Active' :
-        task.status === 'blocked' ? 'Blocked' : 'Pending';
-
-    content += `| ${index + 1} | ${task.id} | ${truncate(task.title, 40)} | ${formatPhaseName(task.phase)} | ${task.estimatedComplexity || 'medium'} | ${statusIcon} |\n`;
-  });
-
-  content += `
----
-
-## Task Details
-
-`;
-
-  for (const task of tasks) {
-    content += `### ${task.id}: ${task.title}
-
-**Phase:** ${formatPhaseName(task.phase)}
-**Source:** ${task.source || 'Manual'} ${task.sourceSection ? `(${task.sourceSection})` : ''}
-**Complexity:** ${task.estimatedComplexity || 'medium'}
-**Status:** ${task.status || 'pending'}
-
-`;
-
-    if (task.description) {
-      content += `**Description:**
-${task.description}
-
-`;
-    }
-
-    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
-      content += `**Acceptance Criteria:**
-${task.acceptanceCriteria.map(c => `- [ ] ${c}`).join('\n')}
-
-`;
-    }
-
-    if (task.dependencies && task.dependencies.length > 0) {
-      content += `**Dependencies:** ${task.dependencies.join(', ')}
-
-`;
-    }
-
-    content += '---\n\n';
-  }
-
-  content += `## Execution Guidelines
-
-1. **One Task at a Time** - Complete each task fully before moving on
-2. **Quality Gates** - Run tests, lint, and typecheck before marking complete
-3. **Commit Per Task** - Create meaningful commits for each completed task
-4. **Update Status** - Run \`bootspring build done\` to mark the current task complete
-5. **Document Changes** - Update CLAUDE.md with new patterns/decisions
-
----
-
-*Generated by Bootspring*
-`;
-
-  return content;
-}
-
-/**
- * Generate CONTEXT.md
- * @param {object} docs - Source documents
- * @param {array} tasks - Extracted tasks
- * @param {object} options - Options
- * @returns {string} CONTEXT.md content
- */
-function generateContext(docs, tasks, options = {}) {
-  const projectName = options.projectName || 'Project';
-  const techStack = options.techStack || extractTechStack(docs);
-
-  let content = `# ${projectName} - Build Context
-
-> Condensed context for AI build iterations
-> Read this file at the start of each build task
-
----
-
-## Project Identity
-
-**Name:** ${projectName}
-${options.tagline ? `**Tagline:** ${options.tagline}` : ''}
-
----
-
-## Tech Stack
-
-| Component | Technology |
-|-----------|------------|
-| Framework | ${techStack.framework || 'Next.js'} |
-| Language | ${techStack.language || 'TypeScript'} |
-| Database | ${techStack.database || 'PostgreSQL'} |
-| ORM | ${techStack.orm || 'Prisma'} |
-| UI | ${techStack.uiLibrary || 'shadcn/ui'} |
-| Styling | ${techStack.styling || 'Tailwind CSS'} |
-| Auth | ${techStack.auth || 'Clerk'} |
-| Hosting | ${techStack.hosting || 'Vercel'} |
-
----
-
-## Current Build Status
-
-**Phase:** ${options.currentPhase || 'MVP'}
-**Tasks Remaining:** ${tasks.filter(t => t.status !== 'completed').length}
-**Tasks Completed:** ${tasks.filter(t => t.status === 'completed').length}
-
----
-
-## Key Decisions
-
-`;
-
-  // Add any decisions from docs
-  if (docs.TECHNICAL_SPEC || docs.technical_spec) {
-    content += `### Architecture
-- Use Server Components by default
-- Prefer Server Actions over API routes for mutations
-- Use Zod for input validation
-- Never expose API keys to client
-
-`;
-  }
-
-  content += `### Code Style
-- TypeScript strict mode enabled
-- ESLint + Prettier for formatting
-- Conventional commits (feat:, fix:, docs:, refactor:)
-- Keep files under 300 lines
-
----
-
-## MVP Features
-
-`;
-
-  // Extract unique MVP features
-  const mvpTasks = tasks.filter(t => t.phase === 'mvp');
-  const uniqueFeatures = [...new Set(mvpTasks.map(t => t.title))].slice(0, 10);
-
-  uniqueFeatures.forEach((feature, i) => {
-    content += `${i + 1}. ${feature}\n`;
-  });
-
-  content += `
----
-
-## File Structure
-
-\`\`\`
-${projectName.toLowerCase().replace(/\s+/g, '-')}/
-├── app/                    # Next.js App Router
-│   ├── (auth)/             # Auth pages
-│   ├── (dashboard)/        # Main dashboard
-│   ├── (marketing)/        # Landing pages
-│   └── api/                # API routes
-├── components/
-│   ├── ui/                 # UI components
-│   └── [feature]/          # Feature components
-├── lib/
-│   ├── db.ts               # Database client
-│   ├── auth.ts             # Auth utilities
-│   └── utils.ts            # Helpers
-├── prisma/
-│   └── schema.prisma       # Database schema
-├── planning/               # Build planning (this folder)
-└── public/                 # Static assets
-\`\`\`
-
----
-
-## Build Loop Rules
-
-When executing a task:
-
-1. **Read CLAUDE.md** - Understand project patterns
-2. **Check BUILD_STATE.json** - Know current task and status
-3. **Implement ONE task** - Focus on the current task only
-4. **Run quality checks** - \`npm run lint && npm run test\`
-5. **Commit changes** - Use conventional commits
-6. **Update status** - Run \`bootspring build done\` to advance the build loop
-
----
-
-## Exit Signals
-
-Output these signals for loop control:
-
-\`\`\`
-<loop-status>TASK_COMPLETE</loop-status>    # Task done successfully
-<loop-status>TASK_BLOCKED</loop-status>     # Cannot complete, needs help
-<loop-status>ALL_COMPLETE</loop-status>     # All MVP tasks done
-EXIT_SIGNAL                                  # Stop the loop
-\`\`\`
-
----
-
-*This context is refreshed at the start of each build iteration*
-`;
-
-  return content;
-}
-
-/**
- * Group tasks by phase
- * @param {array} tasks - Tasks to group
- * @returns {object} Tasks grouped by phase
- */
-function groupByPhase(tasks) {
-  const phases = {
-    foundation: [],
-    mvp: [],
-    launch: [],
-    other: []
-  };
-
-  for (const task of tasks) {
-    const phase = task.phase || 'other';
-    if (phases[phase]) {
-      phases[phase].push(task);
-    } else {
-      phases.other.push(task);
-    }
-  }
-
-  // Remove empty phases
-  for (const [key, value] of Object.entries(phases)) {
-    if (value.length === 0) {
-      delete phases[key];
-    }
-  }
-
-  return phases;
-}
-
-/**
- * Format phase name for display
- * @param {string} phase - Phase name
- * @returns {string} Formatted name
- */
-function formatPhaseName(phase) {
-  if (!phase) return 'Other';
-
-  const names = {
-    foundation: 'Foundation',
-    mvp: 'MVP',
-    launch: 'Launch',
-    other: 'Other'
-  };
-
-  return names[phase] || phase.charAt(0).toUpperCase() + phase.slice(1);
-}
-
-/**
- * Truncate string to max length
- * @param {string} str - String to truncate
- * @param {number} maxLength - Maximum length
- * @returns {string} Truncated string
- */
-function truncate(str, maxLength) {
-  if (!str) return '';
-  if (str.length <= maxLength) return str;
-  return str.slice(0, maxLength - 3) + '...';
-}
-
-/**
- * Extract tech stack from docs
- * @param {object} docs - Source documents
- * @returns {object} Tech stack
- */
-function extractTechStack(docs) {
-  const techDoc = docs.TECHNICAL_SPEC || docs.technical_spec || '';
-  const seedDoc = docs.SEED || docs.seed || '';
-  const allDocs = techDoc + seedDoc;
-
-  const stack = {
-    framework: 'nextjs',
-    language: 'typescript',
-    database: 'postgresql',
-    orm: 'prisma',
-    uiLibrary: 'shadcn',
-    styling: 'tailwind',
-    auth: 'clerk',
-    hosting: 'vercel'
-  };
-
-  // Framework detection
-  if (allDocs.match(/Next\.?js/i)) stack.framework = 'Next.js';
-  else if (allDocs.match(/Remix/i)) stack.framework = 'Remix';
-  else if (allDocs.match(/Nuxt/i)) stack.framework = 'Nuxt';
-
-  // Database
-  if (allDocs.match(/Postgres|PostgreSQL/i)) stack.database = 'PostgreSQL';
-  else if (allDocs.match(/MongoDB/i)) stack.database = 'MongoDB';
-  else if (allDocs.match(/Supabase/i)) stack.database = 'Supabase';
-
-  // Auth
-  if (allDocs.match(/\bClerk\b/i)) stack.auth = 'Clerk';
-  else if (allDocs.match(/NextAuth|Auth\.js/i)) stack.auth = 'NextAuth';
-
-  return stack;
-}
-
-/**
- * Update planning files with current state
- * @param {string} projectRoot - Project root path
- * @param {object} state - Current build state
- */
-function updateFromState(projectRoot, state) {
-  if (!state || !state.implementationQueue) return;
-
-  const tasks = state.implementationQueue;
-  const planningDir = path.join(projectRoot, 'planning');
-
-  // Regenerate TODO.md — the single source of truth
-  const todo = generateTodo(tasks, { projectName: state.projectName });
-  fs.writeFileSync(path.join(planningDir, 'TODO.md'), todo);
-
-  // Legacy: also regenerate TASK_QUEUE.md if it already exists (backward compat)
-  const queuePath = path.join(planningDir, 'TASK_QUEUE.md');
-  if (fs.existsSync(queuePath)) {
-    const existingQueue = fs.readFileSync(queuePath, 'utf-8');
-    const existingVersionMatch = existingQueue.match(/\*\*Current Version:\*\*\s*([^\n]+)/i)
-      || existingQueue.match(/>\s*Current Version:\s*([^\n]+)/i);
-    const queueVersion = existingVersionMatch
-      ? existingVersionMatch[1].trim()
-      : DEFAULT_QUEUE_VERSION;
-
-    const queue = generateImplementationQueue(tasks, {
-      projectName: state.projectName,
-      lastUpdated: new Date().toISOString().split('T')[0],
-      queueVersion
-    });
-    fs.writeFileSync(queuePath, queue);
-  }
-}
-
-module.exports = {
-  generateAll,
-  generateMasterPlan,
-  generateTodo,
-  generateImplementationQueue,
-  generateContext,
-  groupByPhase,
-  formatPhaseName,
-  updateFromState
-};