@polymorphism-tech/morph-spec 3.0.1 → 3.2.0

package/src/commands/shard-spec.js

@@ -1,224 +1,224 @@
-/**
- * MORPH-SPEC Document Sharding
- * Splits large spec.md files into manageable shards (BMAD-inspired)
- * Achieves 90% token savings by loading only relevant sections
- */
-
-import fs from 'fs';
-import path from 'path';
-import ora from 'ora';
-import chalk from 'chalk';
-import { logger } from '../utils/logger.js';
-import { ensureDir, writeFile } from '../utils/file-copier.js';
-
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-function parseSpec(specContent) {
-  const sections = [];
-  const lines = specContent.split('\n');
-
-  let currentSection = null;
-  let currentContent = [];
-
-  for (const line of lines) {
-    // Detect level 2 heading (## Heading)
-    if (line.match(/^## /)) {
-      // Save previous section
-      if (currentSection) {
-        sections.push({
-          title: currentSection,
-          slug: toSlug(currentSection),
-          content: currentContent.join('\n').trim(),
-        });
-      }
-
-      // Start new section
-      currentSection = line.replace(/^## /, '').trim();
-      currentContent = [line]; // Include heading in content
-    } else {
-      currentContent.push(line);
-    }
-  }
-
-  // Save last section
-  if (currentSection) {
-    sections.push({
-      title: currentSection,
-      slug: toSlug(currentSection),
-      content: currentContent.join('\n').trim(),
-    });
-  }
-
-  return sections;
-}
-
-function toSlug(title) {
-  return title
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '');
-}
-
-function generateIndex(sections, featureName) {
-  let index = `# ${toTitleCase(featureName)} - Technical Specification\n\n`;
-  index += `> **Sharded Spec:** This spec has been split into sections for optimal token usage\n`;
-  index += `> **BMAD Pattern:** Load only the section you need during implementation\n\n`;
-  index += `---\n\n`;
-  index += `## 📋 Table of Contents\n\n`;
-
-  sections.forEach((section, i) => {
-    index += `${i + 1}. **[${section.title}](${section.slug}.md)**\n`;
-
-    // Add first 100 chars as description
-    const firstLine = section.content.split('\n').find(l => l.trim() && !l.startsWith('#'));
-    const description = firstLine ? firstLine.substring(0, 100) + '...' : 'See section for details';
-    index += `   > ${description}\n\n`;
-  });
-
-  index += `---\n\n`;
-  index += `## 💡 How to Use Sharded Specs\n\n`;
-  index += `### In Planning Phases (1-3)\n`;
-  index += `Load **all sections** to get complete context:\n`;
-  index += `\`\`\`bash\n`;
-  index += `# Read index.md + all section files\n`;
-  index += `\`\`\`\n\n`;
-
-  index += `### In Implementation Phase (4)\n`;
-  index += `Load **only the relevant section** for your current story:\n`;
-  index += `\`\`\`bash\n`;
-  index += `# Example: Working on entity design story\n`;
-  index += `# Read: spec/index.md + spec/entity-design.md (not the other 10 sections!)\n`;
-  index += `\`\`\`\n\n`;
-
-  index += `**Token Savings:** For a 10-section spec (30k tokens), selective loading = **90% savings**\n\n`;
-  index += `---\n\n`;
-  index += `*Generated by MORPH-SPEC Framework - Document Sharding*\n`;
-  index += `*Inspired by BMAD Method: 90% token reduction for large specs*\n`;
-
-  return index;
-}
-
-function toTitleCase(str) {
-  return str
-    .split('-')
-    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ');
-}
-
-function estimateTokens(text) {
-  // Rough estimate: 1 token ≈ 4 characters
-  return Math.ceil(text.length / 4);
-}
-
-// ============================================================================
-// Command Function
-// ============================================================================
-
-export async function shardSpecCommand(feature, options) {
-  logger.header('MORPH-SPEC Document Sharding');
-  logger.dim(`Feature: ${feature}`);
-  logger.blank();
-
-  const spinner = ora('Analyzing spec.md...').start();
-
-  try {
-    // Find spec.md
-    const specPath = path.join(process.cwd(), `.morph/project/outputs/${feature}/spec.md`);
-    if (!fs.existsSync(specPath)) {
-      throw new Error(`Spec not found: ${specPath}`);
-    }
-
-    // Read spec content
-    const specContent = fs.readFileSync(specPath, 'utf-8');
-    const totalTokens = estimateTokens(specContent);
-
-    spinner.info(`Original spec.md: ~${totalTokens.toLocaleString()} tokens`);
-    logger.blank();
-
-    // Parse into sections
-    const sections = parseSpec(specContent);
-
-    if (sections.length < 3) {
-      spinner.warn(`Spec has only ${sections.length} sections - sharding not recommended`);
-      logger.dim('  Sharding is most beneficial for specs with 5+ sections');
-      return;
-    }
-
-    spinner.succeed(`Detected ${sections.length} sections`);
-    logger.blank();
-
-    // Generate index
-    const indexContent = generateIndex(sections, feature);
-
-    // Calculate savings
-    const avgShardTokens = sections.reduce((sum, s) => sum + estimateTokens(s.content), 0) / sections.length;
-    const savingsPercent = Math.round(((totalTokens - avgShardTokens) / totalTokens) * 100);
-
-    logger.header('Token Savings (selective load):');
-    logger.info(`  ${chalk.green(`~${savingsPercent}%`)} reduction`);
-    logger.dim(`  - Full load: ~${totalTokens.toLocaleString()} tokens`);
-    logger.dim(`  - Selective load: ~${Math.round(avgShardTokens).toLocaleString()} tokens (index + 1 shard)`);
-    logger.blank();
-
-    if (options.verbose) {
-      logger.header('Shard Details:');
-      logger.blank();
-      sections.forEach((section, i) => {
-        const tokens = estimateTokens(section.content);
-        logger.dim(`  ${i + 1}. ${section.title}`);
-        logger.dim(`     File: ${section.slug}.md`);
-        logger.dim(`     Tokens: ~${tokens.toLocaleString()}`);
-        logger.blank();
-      });
-    }
-
-    // Output
-    const outputDir = path.join(process.cwd(), `.morph/project/outputs/${feature}/spec`);
-
-    if (options.dryRun) {
-      logger.header('DRY RUN - Would create:');
-      logger.dim(`  ${outputDir}/index.md`);
-      sections.forEach(s => logger.dim(`  ${outputDir}/${s.slug}.md`));
-      logger.blank();
-      logger.success('Run without --dry-run to create files');
-    } else {
-      const createSpinner = ora('Creating sharded spec files...').start();
-
-      // Create directory
-      await ensureDir(outputDir);
-
-      // Write index
-      await writeFile(path.join(outputDir, 'index.md'), indexContent);
-      createSpinner.text = 'Created index.md';
-
-      // Write shards
-      for (const section of sections) {
-        const shardPath = path.join(outputDir, `${section.slug}.md`);
-        await writeFile(shardPath, section.content);
-        createSpinner.text = `Created ${section.slug}.md`;
-      }
-
-      createSpinner.succeed('Sharded spec created!');
-      logger.blank();
-
-      // Archive original spec.md
-      const archivePath = specPath.replace('.md', '.original.md');
-      fs.renameSync(specPath, archivePath);
-      logger.dim('  Archived original: spec.original.md');
-      logger.blank();
-
-      logger.header('Next steps:');
-      logger.dim(`  1. Review sharded spec in .morph/project/outputs/${feature}/spec/`);
-      logger.dim(`  2. Create stories: morph-spec story create ${feature} SR-001`);
-      logger.dim('  3. Stories will auto-load only relevant shards (90% token savings)');
-      logger.blank();
-    }
-
-  } catch (error) {
-    spinner.fail('Sharding failed');
-    logger.error(error.message);
-    process.exit(1);
-  }
-}
+/**
+ * MORPH-SPEC Document Sharding
+ * Splits large spec.md files into manageable shards (BMAD-inspired)
+ * Achieves 90% token savings by loading only relevant sections
+ */
+
+import fs from 'fs';
+import path from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import { logger } from '../utils/logger.js';
+import { ensureDir, writeFile } from '../utils/file-copier.js';
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function parseSpec(specContent) {
+  const sections = [];
+  const lines = specContent.split('\n');
+
+  let currentSection = null;
+  let currentContent = [];
+
+  for (const line of lines) {
+    // Detect level 2 heading (## Heading)
+    if (line.match(/^## /)) {
+      // Save previous section
+      if (currentSection) {
+        sections.push({
+          title: currentSection,
+          slug: toSlug(currentSection),
+          content: currentContent.join('\n').trim(),
+        });
+      }
+
+      // Start new section
+      currentSection = line.replace(/^## /, '').trim();
+      currentContent = [line]; // Include heading in content
+    } else {
+      currentContent.push(line);
+    }
+  }
+
+  // Save last section
+  if (currentSection) {
+    sections.push({
+      title: currentSection,
+      slug: toSlug(currentSection),
+      content: currentContent.join('\n').trim(),
+    });
+  }
+
+  return sections;
+}
+
+function toSlug(title) {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function generateIndex(sections, featureName) {
+  let index = `# ${toTitleCase(featureName)} - Technical Specification\n\n`;
+  index += `> **Sharded Spec:** This spec has been split into sections for optimal token usage\n`;
+  index += `> **BMAD Pattern:** Load only the section you need during implementation\n\n`;
+  index += `---\n\n`;
+  index += `## 📋 Table of Contents\n\n`;
+
+  sections.forEach((section, i) => {
+    index += `${i + 1}. **[${section.title}](${section.slug}.md)**\n`;
+
+    // Add first 100 chars as description
+    const firstLine = section.content.split('\n').find(l => l.trim() && !l.startsWith('#'));
+    const description = firstLine ? firstLine.substring(0, 100) + '...' : 'See section for details';
+    index += `   > ${description}\n\n`;
+  });
+
+  index += `---\n\n`;
+  index += `## 💡 How to Use Sharded Specs\n\n`;
+  index += `### In Planning Phases (1-3)\n`;
+  index += `Load **all sections** to get complete context:\n`;
+  index += `\`\`\`bash\n`;
+  index += `# Read index.md + all section files\n`;
+  index += `\`\`\`\n\n`;
+
+  index += `### In Implementation Phase (4)\n`;
+  index += `Load **only the relevant section** for your current story:\n`;
+  index += `\`\`\`bash\n`;
+  index += `# Example: Working on entity design story\n`;
+  index += `# Read: spec/index.md + spec/entity-design.md (not the other 10 sections!)\n`;
+  index += `\`\`\`\n\n`;
+
+  index += `**Token Savings:** For a 10-section spec (30k tokens), selective loading = **90% savings**\n\n`;
+  index += `---\n\n`;
+  index += `*Generated by MORPH-SPEC Framework - Document Sharding*\n`;
+  index += `*Inspired by BMAD Method: 90% token reduction for large specs*\n`;
+
+  return index;
+}
+
+function toTitleCase(str) {
+  return str
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+function estimateTokens(text) {
+  // Rough estimate: 1 token ≈ 4 characters
+  return Math.ceil(text.length / 4);
+}
+
+// ============================================================================
+// Command Function
+// ============================================================================
+
+export async function shardSpecCommand(feature, options) {
+  logger.header('MORPH-SPEC Document Sharding');
+  logger.dim(`Feature: ${feature}`);
+  logger.blank();
+
+  const spinner = ora('Analyzing spec.md...').start();
+
+  try {
+    // Find spec.md
+    const specPath = path.join(process.cwd(), `.morph/project/outputs/${feature}/spec.md`);
+    if (!fs.existsSync(specPath)) {
+      throw new Error(`Spec not found: ${specPath}`);
+    }
+
+    // Read spec content
+    const specContent = fs.readFileSync(specPath, 'utf-8');
+    const totalTokens = estimateTokens(specContent);
+
+    spinner.info(`Original spec.md: ~${totalTokens.toLocaleString()} tokens`);
+    logger.blank();
+
+    // Parse into sections
+    const sections = parseSpec(specContent);
+
+    if (sections.length < 3) {
+      spinner.warn(`Spec has only ${sections.length} sections - sharding not recommended`);
+      logger.dim('  Sharding is most beneficial for specs with 5+ sections');
+      return;
+    }
+
+    spinner.succeed(`Detected ${sections.length} sections`);
+    logger.blank();
+
+    // Generate index
+    const indexContent = generateIndex(sections, feature);
+
+    // Calculate savings
+    const avgShardTokens = sections.reduce((sum, s) => sum + estimateTokens(s.content), 0) / sections.length;
+    const savingsPercent = Math.round(((totalTokens - avgShardTokens) / totalTokens) * 100);
+
+    logger.header('Token Savings (selective load):');
+    logger.info(`  ${chalk.green(`~${savingsPercent}%`)} reduction`);
+    logger.dim(`  - Full load: ~${totalTokens.toLocaleString()} tokens`);
+    logger.dim(`  - Selective load: ~${Math.round(avgShardTokens).toLocaleString()} tokens (index + 1 shard)`);
+    logger.blank();
+
+    if (options.verbose) {
+      logger.header('Shard Details:');
+      logger.blank();
+      sections.forEach((section, i) => {
+        const tokens = estimateTokens(section.content);
+        logger.dim(`  ${i + 1}. ${section.title}`);
+        logger.dim(`     File: ${section.slug}.md`);
+        logger.dim(`     Tokens: ~${tokens.toLocaleString()}`);
+        logger.blank();
+      });
+    }
+
+    // Output
+    const outputDir = path.join(process.cwd(), `.morph/project/outputs/${feature}/spec`);
+
+    if (options.dryRun) {
+      logger.header('DRY RUN - Would create:');
+      logger.dim(`  ${outputDir}/index.md`);
+      sections.forEach(s => logger.dim(`  ${outputDir}/${s.slug}.md`));
+      logger.blank();
+      logger.success('Run without --dry-run to create files');
+    } else {
+      const createSpinner = ora('Creating sharded spec files...').start();
+
+      // Create directory
+      await ensureDir(outputDir);
+
+      // Write index
+      await writeFile(path.join(outputDir, 'index.md'), indexContent);
+      createSpinner.text = 'Created index.md';
+
+      // Write shards
+      for (const section of sections) {
+        const shardPath = path.join(outputDir, `${section.slug}.md`);
+        await writeFile(shardPath, section.content);
+        createSpinner.text = `Created ${section.slug}.md`;
+      }
+
+      createSpinner.succeed('Sharded spec created!');
+      logger.blank();
+
+      // Archive original spec.md
+      const archivePath = specPath.replace('.md', '.original.md');
+      fs.renameSync(specPath, archivePath);
+      logger.dim('  Archived original: spec.original.md');
+      logger.blank();
+
+      logger.header('Next steps:');
+      logger.dim(`  1. Review sharded spec in .morph/project/outputs/${feature}/spec/`);
+      logger.dim(`  2. Create stories: morph-spec story create ${feature} SR-001`);
+      logger.dim('  3. Stories will auto-load only relevant shards (90% token savings)');
+      logger.blank();
+    }
+
+  } catch (error) {
+    spinner.fail('Sharding failed');
+    logger.error(error.message);
+    process.exit(1);
+  }
+}

package/src/commands/spawn-team.js

@@ -0,0 +1,172 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getFeature } from '../lib/state-manager.js';
+import { orchestrateTeam } from '../lib/team-orchestrator.js';
+
+/**
+ * Spawn Team Command - Generate agent team configurations
+ *
+ * Reads active agents from feature state and generates ready-to-use
+ * Task tool configurations for spawning agent teams.
+ */
+
+const program = new Command();
+
+/**
+ * Spawn team action function
+ */
+export async function spawnTeamCommand(featureName, options = {}) {
+    try {
+      // Get feature state
+      const feature = getFeature(featureName);
+      if (!feature) {
+        console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+        process.exit(1);
+      }
+
+      if (!feature.activeAgents || feature.activeAgents.length === 0) {
+        console.error(chalk.yellow(`\n⚠️  No active agents found for feature: ${featureName}`));
+        console.log(chalk.gray('Run "morph-spec detect-agents" first to identify agents.\n'));
+        process.exit(1);
+      }
+
+      // Determine if multi-domain
+      const domains = new Set();
+      feature.activeAgents.forEach(agentId => {
+        if (agentId.includes('dotnet') || agentId.includes('ef') || agentId.includes('api')) {
+          domains.add('backend');
+        }
+        if (agentId.includes('blazor') || agentId.includes('nextjs') || agentId.includes('ui')) {
+          domains.add('frontend');
+        }
+        if (agentId.includes('azure') || agentId.includes('bicep') || agentId.includes('container')) {
+          domains.add('infrastructure');
+        }
+      });
+
+      const multiDomain = domains.size > 1;
+
+      // Orchestrate team
+      const teamConfig = orchestrateTeam({
+        activeAgents: feature.activeAgents,
+        complexity: options.complexity,
+        estimatedFiles: parseInt(options.estimatedFiles, 10),
+        multiDomain
+      });
+
+      if (options.json) {
+        // Output as JSON for programmatic use
+        console.log(JSON.stringify(teamConfig, null, 2));
+        return;
+      }
+
+      // Pretty output for human reading
+      console.log(chalk.bold(`\n🤖 Agent Team Configuration for: ${featureName}`));
+      console.log('━'.repeat(60));
+
+      console.log(chalk.cyan(`\nShould Spawn Agents: ${teamConfig.useAgentTeams ? chalk.green('YES') : chalk.yellow('NO')}`));
+      console.log(chalk.gray(`Reason: ${teamConfig.useAgentTeams ? 'Meets spawn threshold' : 'Below threshold - implement directly'}`));
+
+      if (!teamConfig.useAgentTeams) {
+        console.log(chalk.yellow('\n⚠️  Team spawning not recommended for this feature.'));
+        console.log(chalk.gray('Implement directly in main session.\n'));
+        return;
+      }
+
+      console.log(chalk.cyan(`\nDisplay Mode: ${teamConfig.displayMode}`));
+      console.log(chalk.cyan(`Total Teammates: ${teamConfig.teamHierarchy.totalTeammates}`));
+
+      // Show team hierarchy
+      console.log(chalk.bold('\nTeam Hierarchy:'));
+      console.log(chalk.green(`  Team Lead: ${teamConfig.teamHierarchy.teamLead}`));
+
+      if (teamConfig.teamHierarchy.squads && teamConfig.teamHierarchy.squads.length > 0) {
+        console.log(chalk.cyan('\n  Squad Leaders:'));
+        teamConfig.teamHierarchy.squads.forEach(squad => {
+          console.log(chalk.cyan(`    • ${squad}`));
+        });
+      }
+
+      if (teamConfig.teamHierarchy.validators && teamConfig.teamHierarchy.validators.length > 0) {
+        console.log(chalk.gray('\n  Validators (run in hooks):'));
+        teamConfig.teamHierarchy.validators.forEach(validator => {
+          console.log(chalk.gray(`    • ${validator}`));
+        });
+      }
+
+      // Show Task tool usage
+      console.log(chalk.bold('\n📝 Task Tool Usage:'));
+      console.log(chalk.gray('\nUse the following pattern to spawn the team:\n'));
+
+      console.log(chalk.cyan('```typescript'));
+      console.log(chalk.white(`{
+  subagent_type: "general-purpose",
+  description: "Implement ${featureName}",
+  prompt: \`You are the Team Lead (${teamConfig.teamHierarchy.teamLead})...
+
+Your Mission: Implement ${featureName}
+
+Your Domain Leaders:
+${teamConfig.teammates
+  .filter(t => t.tier === 2)
+  .map(t => `- ${t.id}: ${t.role}`)
+  .join('\n')}
+
+Your Specialists:
+${teamConfig.teammates
+  .filter(t => t.tier === 3)
+  .map(t => `- ${t.id}: ${t.role}`)
+  .join('\n')}
+
+Standards to follow: [coding.md, architecture.md]
+
+Deliverables: [list specific outputs]
+\`
+}`));
+      console.log(chalk.cyan('```\n'));
+
+      // Show individual teammates
+      console.log(chalk.bold('Individual Teammates:'));
+      teamConfig.teammates.forEach(teammate => {
+        console.log(chalk.cyan(`\n  ${teammate.icon} ${teammate.id} (Tier ${teammate.tier})`));
+        console.log(chalk.gray(`     Role: ${teammate.role}`));
+
+        if (teammate.spawnPrompt && teammate.spawnPrompt.length < 200) {
+          console.log(chalk.gray(`     Prompt: ${teammate.spawnPrompt.substring(0, 100)}...`));
+        }
+      });
+
+      console.log('\n' + '━'.repeat(60));
+      console.log(chalk.green('\n✅ Team configuration generated successfully\n'));
+
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Error generating team configuration: ${error.message}\n`));
+      if (error.stack) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  }
+
+/**
+ * Commander program command
+ */
+program
+  .name('spawn-team')
+  .description('Generate agent team configuration for Task tool spawning')
+  .argument('<feature>', 'Feature name')
+  .option('--json', 'Output as JSON')
+  .option('--complexity <level>', 'Override complexity level (low/medium/high/critical)', 'high')
+  .option('--estimated-files <count>', 'Override estimated file count', '20')
+  .action(spawnTeamCommand);
+
+// Only parse if run directly (not imported as module)
+if (import.meta.url === `file://${process.argv[1]}`) {
+  if (process.argv.length > 2) {
+    program.parse(process.argv);
+  } else {
+    program.help();
+  }
+}
+
+export default program;