bmad-method 5.1.3 → 6.0.0-alpha.1

package/tools/format-workflow-md.js

@@ -0,0 +1,263 @@
+/**
+ * BMAD Workflow Markdown Formatter
+ *
+ * Formats mixed markdown + XML workflow instruction files with:
+ * - 2-space XML indentation
+ * - Preserved markdown content
+ * - Proper tag nesting
+ * - Consistent formatting
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class WorkflowFormatter {
+  constructor(options = {}) {
+    this.indentSize = options.indentSize || 2;
+    this.preserveMarkdown = options.preserveMarkdown !== false;
+    this.verbose = options.verbose || false;
+  }
+
+  /**
+   * Format a workflow markdown file
+   */
+  format(filePath) {
+    if (this.verbose) {
+      console.log(`Formatting: ${filePath}`);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const formatted = this.formatContent(content);
+
+    // Only write if content changed
+    if (content === formatted) {
+      if (this.verbose) {
+        console.log(`- No changes: ${filePath}`);
+      }
+      return false;
+    } else {
+      fs.writeFileSync(filePath, formatted, 'utf8');
+      if (this.verbose) {
+        console.log(`✓ Formatted: ${filePath}`);
+      }
+      return true;
+    }
+  }
+
+  /**
+   * Format content string with stateful indentation tracking
+   */
+  formatContent(content) {
+    const lines = content.split('\n');
+    const formatted = [];
+    let indentLevel = 0;
+    let inCodeBlock = false;
+    let checkBlockDepth = 0; // Track nested check blocks
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      // Track code blocks (don't format inside them)
+      if (trimmed.startsWith('```')) {
+        if (inCodeBlock) {
+          inCodeBlock = false;
+        } else {
+          inCodeBlock = true;
+        }
+        formatted.push(line);
+        continue;
+      }
+
+      // Don't format inside code blocks
+      if (inCodeBlock) {
+        formatted.push(line);
+        continue;
+      }
+
+      // Handle XML tags
+      if (this.isXMLLine(trimmed)) {
+        const result = this.formatXMLLine(trimmed, indentLevel, checkBlockDepth, i, lines);
+        formatted.push(result.line);
+        indentLevel = result.nextIndent;
+        checkBlockDepth = result.nextCheckDepth;
+      } else if (trimmed === '') {
+        // Preserve blank lines
+        formatted.push('');
+      } else {
+        // Markdown content - preserve as-is but maintain current indent if inside XML
+        formatted.push(line);
+      }
+    }
+
+    return formatted.join('\n');
+  }
+
+  /**
+   * Check if line contains XML tag
+   */
+  isXMLLine(line) {
+    return /^<[a-zA-Z-]+(\s|>|\/)/.test(line) || /^<\/[a-zA-Z-]+>/.test(line);
+  }
+
+  /**
+   * Format a single XML line with context awareness
+   */
+  formatXMLLine(line, currentIndent, checkDepth, lineIndex, allLines) {
+    const trimmed = line.trim();
+    let indent = currentIndent;
+    let nextIndent = currentIndent;
+    let nextCheckDepth = checkDepth;
+
+    // Get the tag name
+    const tagMatch = trimmed.match(/^<\/?([a-zA-Z-]+)/);
+    const tagName = tagMatch ? tagMatch[1] : '';
+
+    // Closing tag - decrease indent before this line
+    if (trimmed.startsWith('</')) {
+      indent = Math.max(0, currentIndent - 1);
+      nextIndent = indent;
+
+      // If closing a step, reset check depth
+      if (tagName === 'step' || tagName === 'workflow') {
+        nextCheckDepth = 0;
+      }
+    }
+    // Self-closing tags (opens and closes on same line)
+    // EXCEPT <check> tags which create logical blocks
+    else if (this.isSelfClosingTag(trimmed) && tagName !== 'check') {
+      // These don't change indent level
+      indent = currentIndent;
+      nextIndent = currentIndent;
+    }
+    // Opening tags
+    else if (trimmed.startsWith('<')) {
+      // Check if this is a <check> tag - these create logical blocks
+      if (tagName === 'check') {
+        indent = currentIndent;
+        // Check tags increase indent for following content
+        nextIndent = currentIndent + 1;
+        nextCheckDepth = checkDepth + 1;
+      }
+      // <action> tags inside check blocks stay at current indent
+      else if (tagName === 'action' && checkDepth > 0) {
+        indent = currentIndent;
+        nextIndent = currentIndent; // Don't increase further
+      }
+      // Other tags close check blocks and return to structural level
+      else if (checkDepth > 0) {
+        // Close all check blocks - return to base structural level
+        indent = Math.max(0, currentIndent - checkDepth);
+        nextIndent = indent + 1;
+        nextCheckDepth = 0;
+      }
+      // Regular opening tags (no check blocks active)
+      else {
+        indent = currentIndent;
+        nextIndent = currentIndent + 1;
+      }
+    }
+
+    const indentStr = ' '.repeat(indent * this.indentSize);
+    return {
+      line: indentStr + trimmed,
+      nextIndent: nextIndent,
+      nextCheckDepth: nextCheckDepth,
+    };
+  }
+
+  /**
+   * Check if tag opens and closes on same line
+   */
+  isSelfClosingTag(line) {
+    // Self-closing with />
+    if (line.endsWith('/>')) {
+      return true;
+    }
+    // Opens and closes on same line: <tag>content</tag>
+    const match = line.match(/^<([a-zA-Z-]+)(\s[^>]*)?>.*<\/\1>$/);
+    return match !== null;
+  }
+
+  /**
+   * Check if tag is a block-level structural tag
+   */
+  isBlockLevelTag(tagName) {
+    return ['step', 'workflow', 'check'].includes(tagName);
+  }
+}
+
+/**
+ * CLI Entry Point
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(`
+BMAD Workflow Markdown Formatter
+
+Usage:
+  node format-workflow-md.js <file-pattern> [options]
+
+Options:
+  --verbose, -v     Verbose output
+  --check, -c       Check formatting without writing (exit 1 if changes needed)
+  --help, -h        Show this help
+
+Examples:
+  node format-workflow-md.js src/**/instructions.md
+  node format-workflow-md.js "src/modules/bmb/**/*.md" --verbose
+  node format-workflow-md.js file.md --check
+`);
+    process.exit(0);
+  }
+
+  const verbose = args.includes('--verbose') || args.includes('-v');
+  const check = args.includes('--check') || args.includes('-c');
+
+  // Remove flags from args
+  const files = args.filter((arg) => !arg.startsWith('-'));
+
+  const formatter = new WorkflowFormatter({ verbose });
+  let hasChanges = false;
+  let formattedCount = 0;
+
+  // Process files
+  for (const pattern of files) {
+    // For now, treat as direct file path
+    // TODO: Add glob support for patterns
+    if (fs.existsSync(pattern)) {
+      const stat = fs.statSync(pattern);
+      if (stat.isFile()) {
+        const changed = formatter.format(pattern);
+        if (changed) {
+          hasChanges = true;
+          formattedCount++;
+        }
+      } else if (stat.isDirectory()) {
+        console.error(`Error: ${pattern} is a directory. Please specify file paths.`);
+      }
+    } else {
+      console.error(`Error: File not found: ${pattern}`);
+    }
+  }
+
+  if (verbose || formattedCount > 0) {
+    console.log(`\nFormatted ${formattedCount} file(s)`);
+  }
+
+  if (check && hasChanges) {
+    console.error('\n❌ Some files need formatting. Run without --check to format.');
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { WorkflowFormatter };

package/tools/platform-codes.yaml

@@ -0,0 +1,133 @@
+# BMAD Platform Codes Configuration
+# Central configuration for all platform/IDE codes used in the BMAD system
+#
+# This file defines the standardized platform codes that are used throughout
+# the installation system to identify different platforms (IDEs, tools, etc.)
+#
+# Format:
+#   code: Platform identifier used internally
+#   name: Display name shown to users
+#   preferred: Whether this platform is shown as a recommended option on install
+#   category: Type of platform (ide, tool, service, etc.)
+
+platforms:
+  # Recommended Platforms
+  claude-code:
+    name: "Claude Code"
+    preferred: true
+    category: cli
+    description: "Anthropic's official CLI for Claude"
+
+  windsurf:
+    name: "Windsurf"
+    preferred: true
+    category: ide
+    description: "AI-powered IDE with cascade flows"
+
+  cursor:
+    name: "Cursor"
+    preferred: true
+    category: ide
+    description: "AI-first code editor"
+
+  # Other IDEs and Tools
+  cline:
+    name: "Cline"
+    preferred: false
+    category: ide
+    description: "AI coding assistant"
+
+  opencode:
+    name: "OpenCode"
+    preferred: false
+    category: ide
+    description: "OpenCode terminal coding assistant"
+
+  auggie:
+    name: "Auggie"
+    preferred: false
+    category: cli
+    description: "AI development tool"
+
+  roo:
+    name: "Roo Cline"
+    preferred: false
+    category: ide
+    description: "Enhanced Cline fork"
+
+  github-copilot:
+    name: "GitHub Copilot"
+    preferred: false
+    category: ide
+    description: "GitHub's AI pair programmer"
+
+  codex:
+    name: "Codex"
+    preferred: false
+    category: cli
+    description: "OpenAI Codex integration"
+
+  qwen:
+    name: "QwenCoder"
+    preferred: false
+    category: ide
+    description: "Qwen AI coding assistant"
+
+  gemini:
+    name: "Gemini CLI"
+    preferred: false
+    category: cli
+    description: "Google's CLI for Gemini"
+
+  iflow:
+    name: "iFlow"
+    preferred: false
+    category: ide
+    description: "AI workflow automation"
+
+  kilo:
+    name: "KiloCoder"
+    preferred: false
+    category: ide
+    description: "AI coding platform"
+
+  crush:
+    name: "Crush"
+    preferred: false
+    category: ide
+    description: "AI development assistant"
+
+  trae:
+    name: "Trae"
+    preferred: false
+    category: ide
+    description: "AI coding tool"
+
+# Platform categories
+categories:
+  ide:
+    name: "Integrated Development Environment"
+    description: "Full-featured code editors with AI assistance"
+
+  cli:
+    name: "Command Line Interface"
+    description: "Terminal-based tools"
+
+  tool:
+    name: "Development Tool"
+    description: "Standalone development utilities"
+
+  service:
+    name: "Cloud Service"
+    description: "Cloud-based development platforms"
+
+  extension:
+    name: "Editor Extension"
+    description: "Plugins for existing editors"
+
+# Naming conventions and rules
+conventions:
+  code_format: "lowercase-kebab-case"
+  name_format: "Title Case"
+  max_code_length: 20
+  allowed_characters: "a-z0-9-"

package/tools/schema/agent.js

@@ -0,0 +1,231 @@
+// Zod schema definition for *.agent.yaml files
+const assert = require('node:assert');
+const { z } = require('zod');
+
+const COMMAND_TARGET_KEYS = ['workflow', 'validate-workflow', 'exec', 'action', 'tmpl', 'data', 'run-workflow'];
+const TRIGGER_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+// Public API ---------------------------------------------------------------
+
+/**
+ * Validate an agent YAML payload against the schema derived from its file location.
+ * Exposed as the single public entry point, so callers do not reach into schema internals.
+ *
+ * @param {string} filePath Path to the agent file (used to infer module scope).
+ * @param {unknown} agentYaml Parsed YAML content.
+ * @returns {import('zod').SafeParseReturnType<unknown, unknown>} SafeParse result.
+ */
+function validateAgentFile(filePath, agentYaml) {
+  const expectedModule = deriveModuleFromPath(filePath);
+  const schema = agentSchema({ module: expectedModule });
+  return schema.safeParse(agentYaml);
+}
+
+module.exports = { validateAgentFile };
+
+// Internal helpers ---------------------------------------------------------
+
+/**
+ * Build a Zod schema for validating a single agent definition.
+ * The schema is generated per call so module-scoped agents can pass their expected
+ * module slug while core agents leave it undefined.
+ *
+ * @param {Object} [options]
+ * @param {string|null|undefined} [options.module] Module slug for module agents; omit or null for core agents.
+ * @returns {import('zod').ZodSchema} Configured Zod schema instance.
+ */
+function agentSchema(options = {}) {
+  const expectedModule = normalizeModuleOption(options.module);
+
+  return (
+    z
+      .object({
+        agent: buildAgentSchema(expectedModule),
+      })
+      .strict()
+      // Refinement: enforce trigger format and uniqueness rules after structural checks.
+      .superRefine((value, ctx) => {
+        const seenTriggers = new Set();
+
+        let index = 0;
+        for (const item of value.agent.menu) {
+          const triggerValue = item.trigger;
+
+          if (!TRIGGER_PATTERN.test(triggerValue)) {
+            ctx.addIssue({
+              code: 'custom',
+              path: ['agent', 'menu', index, 'trigger'],
+              message: 'agent.menu[].trigger must be kebab-case (lowercase words separated by hyphen)',
+            });
+            return;
+          }
+
+          if (seenTriggers.has(triggerValue)) {
+            ctx.addIssue({
+              code: 'custom',
+              path: ['agent', 'menu', index, 'trigger'],
+              message: `agent.menu[].trigger duplicates "${triggerValue}" within the same agent`,
+            });
+            return;
+          }
+
+          seenTriggers.add(triggerValue);
+          index += 1;
+        }
+      })
+  );
+}
+
+/**
+ * Assemble the full agent schema using the module expectation provided by the caller.
+ * @param {string|null} expectedModule Trimmed module slug or null for core agents.
+ */
+function buildAgentSchema(expectedModule) {
+  return z
+    .object({
+      metadata: buildMetadataSchema(expectedModule),
+      persona: buildPersonaSchema(),
+      critical_actions: z.array(createNonEmptyString('agent.critical_actions[]')).optional(),
+      menu: z.array(buildMenuItemSchema()).min(1, { message: 'agent.menu must include at least one entry' }),
+      prompts: z.array(buildPromptSchema()).optional(),
+    })
+    .strict();
+}
+
+/**
+ * Validate metadata shape and cross-check module expectation against caller input.
+ * @param {string|null} expectedModule Trimmed module slug or null when core agent metadata is expected.
+ */
+function buildMetadataSchema(expectedModule) {
+  const schemaShape = {
+    id: createNonEmptyString('agent.metadata.id'),
+    name: createNonEmptyString('agent.metadata.name'),
+    title: createNonEmptyString('agent.metadata.title'),
+    icon: createNonEmptyString('agent.metadata.icon'),
+    module: createNonEmptyString('agent.metadata.module').optional(),
+  };
+
+  return (
+    z
+      .object(schemaShape)
+      .strict()
+      // Refinement: guard presence and correctness of metadata.module.
+      .superRefine((value, ctx) => {
+        const moduleValue = typeof value.module === 'string' ? value.module.trim() : null;
+
+        if (expectedModule && !moduleValue) {
+          ctx.addIssue({
+            code: 'custom',
+            path: ['module'],
+            message: 'module-scoped agents must declare agent.metadata.module',
+          });
+        } else if (!expectedModule && moduleValue) {
+          ctx.addIssue({
+            code: 'custom',
+            path: ['module'],
+            message: 'core agents must not include agent.metadata.module',
+          });
+        } else if (expectedModule && moduleValue !== expectedModule) {
+          ctx.addIssue({
+            code: 'custom',
+            path: ['module'],
+            message: `agent.metadata.module must equal "${expectedModule}"`,
+          });
+        }
+      })
+  );
+}
+
+function buildPersonaSchema() {
+  return z
+    .object({
+      role: createNonEmptyString('agent.persona.role'),
+      identity: createNonEmptyString('agent.persona.identity'),
+      communication_style: createNonEmptyString('agent.persona.communication_style'),
+      principles: z
+        .array(createNonEmptyString('agent.persona.principles[]'))
+        .min(1, { message: 'agent.persona.principles must include at least one entry' }),
+    })
+    .strict();
+}
+
+function buildPromptSchema() {
+  return z
+    .object({
+      id: createNonEmptyString('agent.prompts[].id'),
+      content: z.string().refine((value) => value.trim().length > 0, {
+        message: 'agent.prompts[].content must be a non-empty string',
+      }),
+      description: createNonEmptyString('agent.prompts[].description').optional(),
+    })
+    .strict();
+}
+
+/**
+ * Schema for individual menu entries ensuring they are actionable.
+ */
+function buildMenuItemSchema() {
+  return z
+    .object({
+      trigger: createNonEmptyString('agent.menu[].trigger'),
+      description: createNonEmptyString('agent.menu[].description'),
+      workflow: createNonEmptyString('agent.menu[].workflow').optional(),
+      'validate-workflow': createNonEmptyString('agent.menu[].validate-workflow').optional(),
+      exec: createNonEmptyString('agent.menu[].exec').optional(),
+      action: createNonEmptyString('agent.menu[].action').optional(),
+      tmpl: createNonEmptyString('agent.menu[].tmpl').optional(),
+      data: createNonEmptyString('agent.menu[].data').optional(),
+      'run-workflow': createNonEmptyString('agent.menu[].run-workflow').optional(),
+    })
+    .strict()
+    .superRefine((value, ctx) => {
+      const hasCommandTarget = COMMAND_TARGET_KEYS.some((key) => {
+        const commandValue = value[key];
+        return typeof commandValue === 'string' && commandValue.trim().length > 0;
+      });
+
+      if (!hasCommandTarget) {
+        ctx.addIssue({
+          code: 'custom',
+          message: 'agent.menu[] entries must include at least one command target field',
+        });
+      }
+    });
+}
+
+/**
+ * Derive the expected module slug from a file path residing under src/modules/<module>/agents/.
+ * @param {string} filePath Absolute or relative agent path.
+ * @returns {string|null} Module slug if identifiable, otherwise null.
+ */
+function deriveModuleFromPath(filePath) {
+  assert(filePath, 'validateAgentFile expects filePath to be provided');
+  assert(typeof filePath === 'string', 'validateAgentFile expects filePath to be a string');
+  assert(filePath.startsWith('src/'), 'validateAgentFile expects filePath to start with "src/"');
+
+  const marker = 'src/modules/';
+  if (!filePath.startsWith(marker)) {
+    return null;
+  }
+
+  const remainder = filePath.slice(marker.length);
+  const slashIndex = remainder.indexOf('/');
+  return slashIndex === -1 ? null : remainder.slice(0, slashIndex);
+}
+
+function normalizeModuleOption(moduleOption) {
+  if (typeof moduleOption !== 'string') {
+    return null;
+  }
+
+  const trimmed = moduleOption.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+// Primitive validators -----------------------------------------------------
+
+function createNonEmptyString(label) {
+  return z.string().refine((value) => value.trim().length > 0, {
+    message: `${label} must be a non-empty string`,
+  });
+}