teamspec 3.2.0 → 4.0.0

package/lib/prompt-generator.js

@@ -1,321 +1,174 @@
 /**
- * TeamSpec Copilot Command Generator
+ * TeamSpec Copilot Prompt Generator
  * 
  * Generates GitHub Copilot prompt files for all TeamSpec commands.
+ * Commands and roles are loaded from registry.yml to ensure consistency.
+ * 
+ * Prompts are kept minimal and reference agent files for detailed guidance.
+ * 
  * Usage: teamspec generate-prompts
+ * Version: 4.0
  */
 
 const fs = require('fs');
 const path = require('path');
+const { loadRegistry, getCommandsFromRegistry } = require('./structure-loader');
+
+// =============================================================================
+// ROLE EXTRACTION FROM REGISTRY
+// =============================================================================
 
-// Command definitions from agent system
-const COMMANDS = {
-    ba: {
-        name: 'Business Analyst',
-        commands: [
-            {
-                name: 'project',
-                description: 'Create project structure',
-                prompt: `Execute project creation workflow:
-1. Gather project information (name, ID, stakeholders, goals)
-2. Create project folder structure in projects/{id}/
-3. Generate project.yml with metadata
-4. Create README.md
-5. Initialize folders: features/, stories/backlog/, stories/ready-to-refine/, stories/ready-for-development/, adr/, decisions/, dev-plans/, qa/test-cases/, epics/, sprints/
-6. Create features-index.md and story-ledger.md
-Wait for user confirmation before creating files.`
-            },
-            {
-                name: 'epic',
-                description: 'Define an epic',
-                prompt: `Execute epic creation workflow:
-1. Identify epic scope and goal
-2. Link to project
-3. Break down into candidate features
-4. Create epic file in epics/ folder
-Wait for user confirmation before creating files.`
-            },
-            {
-                name: 'feature',
-                description: 'Create feature file',
-                prompt: `Execute feature creation workflow:
-1. Gather feature requirements (purpose, value, scope)
-2. Define personas/actors
-3. Create feature file in features/ folder using F-XXX-name.md format
-4. Update features-index.md
-Ensure feature is implementation-agnostic.
-Wait for user confirmation before creating files.`
-            },
-            {
-                name: 'decision',
-                description: 'Log business decision',
-                prompt: `Log a business decision:
-1. Capture decision context
-2. Document options considered
-3. Record rationale
-4. Link to affected features
-5. Create decision file in decisions/ folder using DECISION-XXX-name.md format`
-            },
-            {
-                name: 'analysis',
-                description: 'Create business analysis document',
-                prompt: `Create a business analysis document to describe business processes:
-
-1. **Understand the business domain** - Ask about:
-   - What business problem needs to be analyzed?
-   - Who are the stakeholders?
-   - What business processes are involved?
-
-2. **Document Current State (As-Is)**
-   - How do users solve the problem today?
-   - What are the pain points?
-   - What processes exist?
-
-3. **Define Future State (To-Be)**
-   - What will the improved workflow look like?
-   - What business rules apply?
-   - What are the success metrics?
-
-4. **Create business analysis document** using templates/business-analysis-template.md
-   - Place in analysis/ folder (create if needed)
-   - Name format: BA-XXX-description.md
-
-5. **Link to related artifacts**
-   - Identify candidate features that will come from this analysis
-   - Note decisions that need to be made
-   - Identify risks and constraints
-
-⚠️ This is a PLANNING artifact - Feature Canon becomes Source of Truth after features are created.`
-            }
-        ]
-    },
-    fa: {
-        name: 'Functional Analyst',
-        commands: [
-            {
-                name: 'story',
-                description: 'Create a new story',
-                prompt: `Create a story as a DELTA to the Feature Canon:
-1. Identify the linked feature (REQUIRED)
-2. Document BEFORE state (reference Canon)
-3. Document AFTER state (the delta)
-4. Write testable Acceptance Criteria
-5. Mark impact type (Adds/Changes/Fixes/Removes)
-6. Create story in stories/backlog/ using S-XXX-name.md format
-NEVER create a story without a feature link.`
-            },
-            {
-                name: 'slice',
-                description: 'Slice feature into stories',
-                prompt: `Slice a feature into implementable stories:
-1. Read the Feature Canon entry
-2. Identify discrete behavior changes
-3. Create story deltas for each change
-4. Ensure each story is independently deliverable
-5. Link all stories to the feature
-Create files in stories/backlog/`
-            },
-            {
-                name: 'refine',
-                description: 'Move story to ready-to-refine',
-                prompt: `Refine a story for development:
-1. Verify feature link exists
-2. Check Before/After delta is clear
-3. Validate ACs are testable
-4. Move file from stories/backlog/ to stories/ready-to-refine/`
-            },
-            {
-                name: 'sync',
-                description: 'Update Feature Canon after story completion',
-                prompt: `CRITICAL: Canon sync workflow:
-1. Identify completed story
-2. Check impact type (Adds/Changes Behavior?)
-3. Update Feature Canon sections in features/
-4. Add Change Log entry with story reference
-5. Update story-ledger.md
-6. Verify DoD checkbox is checked
-A story CANNOT be Done until Canon is synchronized.`
-            }
-        ]
-    },
-    arch: {
-        name: 'Solution Architect',
-        commands: [
-            {
-                name: 'adr',
-                description: 'Create Architecture Decision Record',
-                prompt: `Create an ADR:
-1. Identify technical decision
-2. Document context and options
-3. Record decision and rationale
-4. Link to affected features
-5. Create ADR file in adr/ folder using ADR-XXX-name.md format`
-            }
-        ]
-    },
-    dev: {
-        name: 'Developer',
-        commands: [
-            {
-                name: 'plan',
-                description: 'Create development plan',
-                prompt: `Create a development plan:
-1. Read the story and linked feature
-2. Break down into implementation tasks
-3. Estimate effort for each task
-4. Identify dependencies and risks
-5. Create dev plan in dev-plans/ using story-XXX-tasks.md format`
-            },
-            {
-                name: 'implement',
-                description: 'Execute implementation',
-                prompt: `Execute implementation:
-1. Load dev plan
-2. Work through tasks sequentially
-3. Update task completion status
-4. Create/modify code files
-5. Track actual vs estimated effort`
-            },
-            {
-                name: 'ready',
-                description: 'Move story to ready-for-development',
-                prompt: `Move story to ready-for-development:
-1. Verify dev plan exists
-2. Check DoR criteria
-3. Move file from stories/ready-to-refine/ to stories/ready-for-development/`
-            }
-        ]
-    },
-    qa: {
-        name: 'QA Engineer',
-        commands: [
-            {
-                name: 'test',
-                description: 'Design test cases',
-                prompt: `Design test cases:
-1. Read feature specification
-2. Identify test scenarios
-3. Write test cases with steps and expected results
-4. Create test file in qa/test-cases/ using F-XXX-test-cases.md format`
-            },
-            {
-                name: 'bug',
-                description: 'File bug report',
-                prompt: `File a bug report:
-1. Capture bug details
-2. Document reproduction steps
-3. Classify severity
-4. Link to affected feature
-5. Create bug file in bugs/ folder`
-            },
-            {
-                name: 'dor-check',
-                description: 'Validate Definition of Ready',
-                prompt: `Check Definition of Ready:
-1. Verify feature link exists
-2. Check Before/After delta is clear
-3. Validate ACs are testable
-4. Confirm no TBD/placeholder content
-5. Check estimate is assigned
-Report any gaps.`
-            }
-        ]
-    },
-    sm: {
-        name: 'Scrum Master',
-        commands: [
-            {
-                name: 'sprint-create',
-                description: 'Create new sprint',
-                prompt: `Create new sprint:
-1. Determine sprint number
-2. Create sprint folder: sprints/sprint-N/
-3. Create sprint-goal.md
-4. Update active-sprint.md`
-            },
-            {
-                name: 'sprint-plan',
-                description: 'Plan sprint backlog',
-                prompt: `Plan sprint backlog:
-1. Review ready-for-development stories
-2. Calculate team capacity
-3. Select stories for sprint
-4. Move story files to sprints/sprint-N/
-5. Update sprint-goal.md`
-            },
-            {
-                name: 'sprint-status',
-                description: 'Sprint status report',
-                prompt: `Generate sprint status:
-1. Count stories by status
-2. Calculate burndown
-3. Identify blockers
-4. Report health metrics`
-            }
-        ]
-    },
-    utility: {
-        name: 'Utility',
-        commands: [
-            {
-                name: 'fix',
-                description: 'Auto-fix linter errors',
-                prompt: `Auto-fix TeamSpec linter errors:
-1. Run \`teamspec lint\` to identify errors
-2. Review the linter output
-3. Apply fixes for each error category
-4. Re-run linter to verify fixes
-
-Supports: TS-PROJ, TS-FEAT, TS-STORY, TS-ADR, TS-DEVPLAN, TS-DOD, TS-NAMING rules.`
-            }
-        ]
+/**
+ * Extract roles from registry.yml
+ * @param {Object} registry - Parsed registry object
+ * @returns {Object} - Roles keyed by role ID
+ */
+function extractRoles(registry) {
+    const roles = {};
+
+    if (registry?.roles) {
+        for (const [roleId, roleData] of Object.entries(registry.roles)) {
+            roles[roleId] = {
+                id: roleId,
+                name: roleData.name || roleId,
+                agent: `AGENT_${roleId}`,
+                owns: roleData.owns || [],
+                creates: roleData.creates || [],
+                commands: roleData.commands || []
+            };
+        }
     }
-};
+
+    return roles;
+}
 
 /**
- * Map role codes to agent file names
+ * Get role info from registry roles
+ * @param {Object} roles - Extracted roles
+ * @param {string} roleKey - Role key (e.g., 'PO', 'BA')
+ * @returns {Object} - Role info with defaults
  */
-const ROLE_TO_AGENT = {
-    ba: 'AGENT_BA',
-    fa: 'AGENT_FA',
-    arch: 'AGENT_SA',  // Solution Architect
-    dev: 'AGENT_DEV',
-    qa: 'AGENT_QA',
-    sm: 'AGENT_SM',
-    utility: 'AGENT_FIX'
-};
+function getRoleInfo(roles, roleKey) {
+    const key = roleKey?.toUpperCase();
+    return roles[key] || {
+        id: key || 'ANY',
+        name: 'TeamSpec',
+        agent: 'AGENT_BOOTSTRAP',
+        owns: [],
+        creates: [],
+        commands: []
+    };
+}
+
+// =============================================================================
+// COMMAND EXTRACTION FROM REGISTRY
+// =============================================================================
 
 /**
- * Generate GitHub Copilot prompt file in VS Code format
- * Creates minimal prompts that link to the full agent files
- * VS Code automatically includes linked Markdown files as context
+ * Group commands by role
+ * @param {Array} commands - Commands from registry
+ * @returns {Object} - Commands grouped by role
  */
-function generatePromptFile(role, command, outputDir) {
-    // Utility commands use just the command name (e.g., fix.prompt.md, ts:fix)
-    // Other roles use role-command pattern (e.g., ba-project.prompt.md, ts:ba-project)
-    const isUtility = role === 'utility';
-    const filename = isUtility ? `${command.name}.prompt.md` : `${role}-${command.name}.prompt.md`;
+function groupCommandsByRole(commands) {
+    const byRole = {};
+
+    for (const cmd of commands) {
+        if (cmd.status === 'REMOVED') continue;
+
+        const role = cmd.role || 'Any';
+        if (!byRole[role]) byRole[role] = [];
+        byRole[role].push(cmd);
+    }
+
+    return byRole;
+}
+
+// =============================================================================
+// PROMPT FILE GENERATION
+// =============================================================================
+
+/**
+ * Sanitize a string for use in filenames
+ */
+function sanitizeFilename(str) {
+    return str
+        .replace(/<[^>]+>/g, '')      // Remove angle bracket patterns like <role>
+        .replace(/[\\/:*?"<>|]/g, '') // Remove Windows-invalid chars
+        .replace(/\s+/g, '-')         // Replace spaces with dashes
+        .replace(/-+/g, '-')          // Collapse multiple dashes
+        .replace(/^-|-$/g, '');       // Remove leading/trailing dashes
+}
+
+/**
+ * Parse command invocation to extract role and action
+ * @param {string} invocation - Command invocation (e.g., "ts:po product")
+ * @returns {Object|null} - Parsed command parts or null if invalid
+ */
+function parseInvocation(invocation) {
+    const match = invocation.match(/^ts:(\w+)(?:\s+(.+))?$/);
+    if (!match) return null;
+
+    const [, roleOrCmd, action] = match;
+
+    // Skip commands with placeholders
+    if (action && action.includes('<')) return null;
+
+    return { roleOrCmd, action };
+}
+
+/**
+ * Generate a clean, minimal GitHub Copilot prompt file
+ * The prompt references the agent file for detailed guidance.
+ */
+function generatePromptFile(command, outputDir, roles) {
+    const parsed = parseInvocation(command.invocation);
+    if (!parsed) return null;
+
+    const { roleOrCmd, action } = parsed;
+    const role = getRoleInfo(roles, roleOrCmd);
+
+    // Determine filename
+    let filename, commandName;
+    if (action) {
+        const sanitizedAction = sanitizeFilename(action);
+        filename = `${roleOrCmd}-${sanitizedAction}.prompt.md`;
+        commandName = `ts:${roleOrCmd} ${action}`;
+    } else {
+        filename = `${roleOrCmd}.prompt.md`;
+        commandName = `ts:${roleOrCmd}`;
+    }
+
     const filepath = path.join(outputDir, filename);
-    const commandName = isUtility ? `ts:${command.name}` : `ts:${role}-${command.name}`;
-    const agentFile = ROLE_TO_AGENT[role] || `AGENT_${role.toUpperCase()}`;
 
-    // Create minimal prompt that links to the agent file
-    // VS Code will include the linked file as context automatically
+    // Build clean, minimal prompt content
     const content = `---
-name: "${commandName}"
-description: "TeamSpec ${COMMANDS[role].name}: ${command.description}"
-agent: "agent"
+name: "ts:${filename.replace('.prompt.md', '').replace(/-/g, ' ')}"
+description: "${command.purpose || `${role.name} command`}"
 ---
 
-# ${command.description}
+# ${command.purpose || `${role.name} - ${action || roleOrCmd}`}
 
-Execute the **${command.name}** workflow as a **${COMMANDS[role].name}**.
+You are acting as **${role.name}**.
 
-See full role instructions: [${agentFile}.md](../../.teamspec/agents/${agentFile}.md)
+## Command
 
-## Quick Reference
+\`${commandName}\`
 
-${command.prompt}
+## Agent Instructions
+
+See full role instructions and command details in:
+- [${role.agent}.md](../../.teamspec/agents/${role.agent}.md)
+
+${command.output ? `## Output
+
+${command.output}
+` : ''}
+${command.precondition ? `## Precondition
+
+${command.precondition}
+` : ''}
+---
+*Command from registry.yml - TeamSpec 4.0*
 `;
 
     fs.writeFileSync(filepath, content, 'utf-8');
@@ -323,32 +176,86 @@ ${command.prompt}
 }
 
 /**
- * Generate all prompt files
+ * Generate all prompt files from registry
  */
 function generateAllPrompts(targetDir = process.cwd()) {
     const outputDir = path.join(targetDir, '.github', 'prompts');
 
     // Create output directory
-    if (!fs.existsSync(outputDir)) {
-        fs.mkdirSync(outputDir, { recursive: true });
-    }
+    fs.mkdirSync(outputDir, { recursive: true });
 
     console.log('🚀 Generating GitHub Copilot prompt files...\n');
 
+    // Load registry and extract data
+    const registry = loadRegistry(targetDir);
+    const roles = extractRoles(registry);
+    const commands = getCommandsFromRegistry(registry);
+    const byRole = groupCommandsByRole(commands);
+
     const generated = [];
+    const generatedByRole = {};
+
+    // Generate prompts for each command
+    for (const command of commands) {
+        if (command.status === 'REMOVED') continue;
 
-    // Generate prompts for each role and command
-    for (const [role, config] of Object.entries(COMMANDS)) {
-        console.log(`📋 ${config.name}:`);
-        for (const command of config.commands) {
-            const filename = generatePromptFile(role, command, outputDir);
+        const filename = generatePromptFile(command, outputDir, roles);
+        if (filename) {
             generated.push(filename);
+
+            // Track by role for summary
+            const role = command.role || 'Any';
+            if (!generatedByRole[role]) generatedByRole[role] = [];
+            generatedByRole[role].push({ filename, command });
+        }
+    }
+
+    // Print summary by role
+    for (const [roleKey, cmds] of Object.entries(generatedByRole)) {
+        const role = getRoleInfo(roles, roleKey);
+        console.log(`📋 ${role.name}:`);
+        for (const { filename } of cmds) {
             console.log(`   ✓ ${filename}`);
         }
     }
 
-    // Generate index file
-    const indexContent = `# TeamSpec Copilot Prompts
+    // Generate README index
+    generateReadme(outputDir, generatedByRole, roles, registry);
+    generated.push('README.md');
+
+    console.log(`\n✅ Generated ${generated.length} files in ${outputDir}`);
+    console.log('\n📖 See .github/prompts/README.md for usage instructions');
+    console.log('💡 In Copilot Chat, type "/" to see available prompts');
+
+    return generated;
+}
+
+/**
+ * Generate README index file
+ */
+function generateReadme(outputDir, byRole, roles, registry) {
+    let pkgVersion = '4.0';
+    try {
+        const pkg = require('../package.json');
+        pkgVersion = pkg.version;
+    } catch (e) {
+        // Use default
+    }
+
+    const rolesSections = Object.entries(byRole).map(([roleKey, cmds]) => {
+        const role = getRoleInfo(roles, roleKey);
+        const cmdList = cmds.map(({ filename, command }) => {
+            return `- \`/${filename.replace('.prompt.md', '')}\` - ${command.purpose || 'Command'}`;
+        }).join('\n');
+
+        return `
+### ${role.name}
+
+${cmdList}
+`;
+    }).join('\n');
+
+    const content = `# TeamSpec Copilot Prompts
 
 These prompt files provide structured guidance for TeamSpec commands in GitHub Copilot Chat.
 
@@ -356,50 +263,125 @@ These prompt files provide structured guidance for TeamSpec commands in GitHub C
 
 In VS Code, type \`/\` in Copilot Chat to see available prompts. Look for prompts starting with \`ts:\`.
 
-Alternatively, run any prompt directly:
-- Press \`Ctrl+Shift+P\` (or \`Cmd+Shift+P\` on Mac)
-- Type "Chat: Run Prompt"
-- Select a TeamSpec prompt
-
 ## Available Commands
 
-${Object.entries(COMMANDS).map(([role, config]) => {
-        const isUtility = role === 'utility';
-        return `
-### ${config.name}
-
-${config.commands.map(cmd => {
-            const cmdName = isUtility ? `ts:${cmd.name}` : `ts:${role}-${cmd.name}`;
-            return `- \`/${cmdName}\` - ${cmd.description}`;
-        }).join('\n')}
-`;
-    }).join('\n')}
+${rolesSections}
 
 ## How It Works
 
 1. Type \`/\` in Copilot Chat to see prompts
-2. Select a \`ts:\` prefixed prompt
-3. Copilot provides role-specific guidance
+2. Select a TeamSpec prompt
+3. Copilot loads role-specific agent instructions
 4. Follow the workflow to create artifacts
 
+## Command Reference
+
+| Command | Role | Purpose |
+|---------|------|---------|
+${Object.values(byRole).flat().map(({ command }) => {
+        const role = getRoleInfo(roles, command.role);
+        return `| \`${command.invocation}\` | ${role.name} | ${command.purpose || '-'} |`;
+    }).join('\n')}
+
 ---
 
-*Generated by TeamSpec CLI v${require('../package.json').version}*
+*Generated by TeamSpec CLI v${pkgVersion}*
+*Source: registry.yml - TeamSpec ${registry?.version || '4.0'}*
 `;
 
-    fs.writeFileSync(path.join(outputDir, 'README.md'), indexContent, 'utf-8');
-    generated.push('README.md');
+    fs.writeFileSync(path.join(outputDir, 'README.md'), content, 'utf-8');
+}
 
-    console.log(`\n✅ Generated ${generated.length} files in ${outputDir}`);
-    console.log('\n📖 See .github/prompts/README.md for usage instructions');
-    console.log('💡 In Copilot Chat, type "/" to see available prompts');
+// =============================================================================
+// BACKWARDS COMPATIBILITY EXPORTS
+// =============================================================================
 
-    return generated;
+/**
+ * Get all commands for external use
+ */
+function getCommands(targetDir = process.cwd()) {
+    const registry = loadRegistry(targetDir);
+    return getCommandsFromRegistry(registry);
+}
+
+/**
+ * Get ROLES object (extracted from registry)
+ * For backwards compatibility with tests
+ */
+function getRolesFromRegistry(targetDir = process.cwd()) {
+    const registry = loadRegistry(targetDir);
+    return extractRoles(registry);
 }
 
+// Legacy ROLES export - now dynamically loaded
+// Kept for backwards compatibility with tests
+const ROLES = (() => {
+    try {
+        const registry = loadRegistry(process.cwd());
+        return extractRoles(registry);
+    } catch (e) {
+        // Fallback for when registry not available
+        return {
+            PO: { id: 'PO', name: 'Product Owner', agent: 'AGENT_PO', owns: [], creates: [], commands: [] },
+            BA: { id: 'BA', name: 'Business Analyst', agent: 'AGENT_BA', owns: [], creates: [], commands: [] },
+            FA: { id: 'FA', name: 'Functional Analyst', agent: 'AGENT_FA', owns: [], creates: [], commands: [] },
+            SA: { id: 'SA', name: 'Solution Architect', agent: 'AGENT_SA', owns: [], creates: [], commands: [] },
+            DEV: { id: 'DEV', name: 'Developer', agent: 'AGENT_DEV', owns: [], creates: [], commands: [] },
+            QA: { id: 'QA', name: 'QA Engineer', agent: 'AGENT_QA', owns: [], creates: [], commands: [] },
+            SM: { id: 'SM', name: 'Scrum Master', agent: 'AGENT_SM', owns: [], creates: [], commands: [] },
+            DES: { id: 'DES', name: 'Designer', agent: 'AGENT_DES', owns: [], creates: [], commands: [] }
+        };
+    }
+})();
+
+// Legacy COMMANDS export - now dynamically built from registry
+// Kept for backwards compatibility with tests
+const COMMANDS = (() => {
+    try {
+        const registry = loadRegistry(process.cwd());
+        const commands = getCommandsFromRegistry(registry);
+        const roles = extractRoles(registry);
+        const byRole = groupCommandsByRole(commands);
+
+        const result = {};
+        for (const [roleKey, cmds] of Object.entries(byRole)) {
+            const role = getRoleInfo(roles, roleKey);
+            const normalizedKey = roleKey.toLowerCase() === 'any' ? 'utility' : roleKey.toLowerCase();
+
+            result[normalizedKey] = {
+                name: role.name,
+                commands: cmds.map(cmd => ({
+                    name: cmd.invocation.replace(/^ts:\w+\s*/, '').trim() || cmd.id.split('.').pop(),
+                    description: cmd.purpose || '',
+                    prompt: ''  // No longer embedding workflow in prompt
+                }))
+            };
+        }
+
+        return result;
+    } catch (e) {
+        // Fallback for when registry not available
+        return {
+            ba: { name: 'Business Analyst', commands: [] },
+            fa: { name: 'Functional Analyst', commands: [] },
+            po: { name: 'Product Owner', commands: [] },
+            sa: { name: 'Solution Architect', commands: [] },
+            dev: { name: 'Developer', commands: [] },
+            qa: { name: 'QA Engineer', commands: [] },
+            sm: { name: 'Scrum Master', commands: [] },
+            utility: { name: 'Utility', commands: [] }
+        };
+    }
+})();
+
 module.exports = {
     generateAllPrompts,
-    COMMANDS
+    getCommands,
+    getRolesFromRegistry,
+    extractRoles,
+    groupCommandsByRole,
+    COMMANDS,
+    ROLES
 };
 
 // CLI execution