From 47a70cc92d2ddc6da5f53814e407997961f1d6ca Mon Sep 17 00:00:00 2001 From: Adam Biggs Date: Thu, 5 Feb 2026 16:55:41 -0800 Subject: [PATCH 1/5] fix: route OpenCode agents to correct .opencode/agent/ directory (#1549) --- tools/cli/installers/lib/ide/platform-codes.yaml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/tools/cli/installers/lib/ide/platform-codes.yaml b/tools/cli/installers/lib/ide/platform-codes.yaml index 2ca32aed5..b329d283c 100644 --- a/tools/cli/installers/lib/ide/platform-codes.yaml +++ b/tools/cli/installers/lib/ide/platform-codes.yaml @@ -124,8 +124,13 @@ platforms: category: ide description: "OpenCode terminal coding assistant" installer: - target_dir: .opencode/command - template_type: opencode + targets: + - target_dir: .opencode/agent + template_type: opencode + artifact_types: [agents] + - target_dir: .opencode/command + template_type: opencode + artifact_types: [workflows, tasks, tools] qwen: name: "QwenCoder" From 2aab028f96b5d1cc800640793ec23ad4f7570f7f Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Thu, 5 Feb 2026 17:57:40 -0700 Subject: [PATCH 2/5] docs: rename brownfield to established projects (#1539) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: rename brownfield to established projects Flatten how-to/brownfield/ subdirectory and replace jargon term "brownfield" with more accessible "established projects" throughout. - brownfield/index.md → established-projects.md - brownfield/quick-fix-in-brownfield.md → quick-fixes.md - brownfield-faq.md → established-projects-faq.md - Update all internal links and references * docs: remove redundant phrase from quick-fixes description * docs: restore natural language in established-projects body --- docs/_STYLE_GUIDE.md | 4 +- docs/explanation/brownfield-faq.md | 55 ------------------- docs/explanation/established-projects-faq.md | 48 ++++++++++++++++ .../index.md => established-projects.md} | 12 ++-- ...ck-fix-in-brownfield.md => quick-fixes.md} | 4 +- docs/reference/workflow-map.md | 2 +- 6 files changed, 57 insertions(+), 68 deletions(-) delete mode 100644 docs/explanation/brownfield-faq.md create mode 100644 docs/explanation/established-projects-faq.md rename docs/how-to/{brownfield/index.md => established-projects.md} (84%) rename docs/how-to/{brownfield/quick-fix-in-brownfield.md => quick-fixes.md} (93%) diff --git a/docs/_STYLE_GUIDE.md b/docs/_STYLE_GUIDE.md index e5fb51ff7..3e78387af 100644 --- a/docs/_STYLE_GUIDE.md +++ b/docs/_STYLE_GUIDE.md @@ -147,7 +147,7 @@ your-project/ | **Concept** | `what-are-agents.md` | | **Feature** | `quick-flow.md` | | **Philosophy** | `why-solutioning-matters.md` | -| **FAQ** | `brownfield-faq.md` | +| **FAQ** | `established-projects-faq.md` | ### General Template @@ -325,7 +325,7 @@ Add italic context at definition start for limited-scope terms: - `*BMad Method/Enterprise.*` - `*Phase N.*` - `*BMGD.*` -- `*Brownfield.*` +- `*Established projects.*` ### Glossary Checklist diff --git a/docs/explanation/brownfield-faq.md b/docs/explanation/brownfield-faq.md deleted file mode 100644 index 1c9b3b822..000000000 --- a/docs/explanation/brownfield-faq.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Brownfield Development FAQ" -description: Common questions about brownfield development in the BMad Method ---- -Quick answers to common questions about brownfield (existing codebase) development in the BMad Method (BMM). - -## Questions - -- [Questions](#questions) - - [What is brownfield vs greenfield?](#what-is-brownfield-vs-greenfield) - - [Do I have to run document-project for brownfield?](#do-i-have-to-run-document-project-for-brownfield) - - [What if I forget to run document-project?](#what-if-i-forget-to-run-document-project) - - [Can I use Quick Spec Flow for brownfield projects?](#can-i-use-quick-spec-flow-for-brownfield-projects) - - [What if my existing code doesn't follow best practices?](#what-if-my-existing-code-doesnt-follow-best-practices) - -### What is brownfield vs greenfield? - -- **Greenfield** — New project, starting from scratch, clean slate -- **Brownfield** — Existing project, working with established codebase and patterns - -### Do I have to run document-project for brownfield? - -Highly recommended, especially if: - -- No existing documentation -- Documentation is outdated -- AI agents need context about existing code - -You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md` or will use other tools or techniques to aid in discovery for the agent to build on an existing system. - -### What if I forget to run document-project? - -Don't worry about it - you can do it at any time. You can even do it during or after a project to help keep docs up to date. - -### Can I use Quick Spec Flow for brownfield projects? - -Yes! Quick Spec Flow works great for brownfield. It will: - -- Auto-detect your existing stack -- Analyze brownfield code patterns -- Detect conventions and ask for confirmation -- Generate context-rich tech-spec that respects existing code - -Perfect for bug fixes and small features in existing codebases. - -### What if my existing code doesn't follow best practices? - -Quick Spec Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide: - -- **Yes** → Maintain consistency with current codebase -- **No** → Establish new standards (document why in tech-spec) - -BMM respects your choice — it won't force modernization, but it will offer it. - -**Have a question not answered here?** Please [open an issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it! diff --git a/docs/explanation/established-projects-faq.md b/docs/explanation/established-projects-faq.md new file mode 100644 index 000000000..e940b4dbb --- /dev/null +++ b/docs/explanation/established-projects-faq.md @@ -0,0 +1,48 @@ +--- +title: "Established Projects FAQ" +description: Common questions about using BMad Method on established projects +--- +Quick answers to common questions about working on established projects with the BMad Method (BMM). + +## Questions + +- [Do I have to run document-project first?](#do-i-have-to-run-document-project-first) +- [What if I forget to run document-project?](#what-if-i-forget-to-run-document-project) +- [Can I use Quick Flow for established projects?](#can-i-use-quick-flow-for-established-projects) +- [What if my existing code doesn't follow best practices?](#what-if-my-existing-code-doesnt-follow-best-practices) + +### Do I have to run document-project first? + +Highly recommended, especially if: + +- No existing documentation +- Documentation is outdated +- AI agents need context about existing code + +You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md` or will use other tools or techniques to aid in discovery for the agent to build on an existing system. + +### What if I forget to run document-project? + +Don't worry about it - you can do it at any time. You can even do it during or after a project to help keep docs up to date. + +### Can I use Quick Flow for established projects? + +Yes! Quick Flow works great for established projects. It will: + +- Auto-detect your existing stack +- Analyze existing code patterns +- Detect conventions and ask for confirmation +- Generate context-rich tech-spec that respects existing code + +Perfect for bug fixes and small features in existing codebases. + +### What if my existing code doesn't follow best practices? + +Quick Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide: + +- **Yes** → Maintain consistency with current codebase +- **No** → Establish new standards (document why in tech-spec) + +BMM respects your choice — it won't force modernization, but it will offer it. + +**Have a question not answered here?** Please [open an issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it! diff --git a/docs/how-to/brownfield/index.md b/docs/how-to/established-projects.md similarity index 84% rename from docs/how-to/brownfield/index.md rename to docs/how-to/established-projects.md index 75bab690b..b756691cc 100644 --- a/docs/how-to/brownfield/index.md +++ b/docs/how-to/established-projects.md @@ -1,15 +1,11 @@ --- -title: "Brownfield Development" +title: "Established Projects" description: How to use BMad Method on existing codebases --- Use BMad Method effectively when working on existing projects and legacy codebases. -## What is Brownfield Development? - -**Brownfield** refers to working on existing projects with established codebases and patterns, as opposed to **greenfield** which means starting from scratch with a clean slate. - -This guide covers the essential workflow for onboarding to brownfield projects with BMad Method. +This guide covers the essential workflow for onboarding to existing projects with BMad Method. :::note[Prerequisites] - BMad Method installed (`npx bmad-method install`) @@ -80,5 +76,5 @@ Pay close attention here to prevent reinventing the wheel or making decisions th ## More Information -- **[Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md)** - Bug fixes and ad-hoc changes -- **[Brownfield FAQ](/docs/explanation/brownfield-faq.md)** - Common questions about brownfield development +- **[Quick Fixes](/docs/how-to/quick-fixes.md)** - Bug fixes and ad-hoc changes +- **[Established Projects FAQ](/docs/explanation/established-projects-faq.md)** - Common questions about working on established projects diff --git a/docs/how-to/brownfield/quick-fix-in-brownfield.md b/docs/how-to/quick-fixes.md similarity index 93% rename from docs/how-to/brownfield/quick-fix-in-brownfield.md rename to docs/how-to/quick-fixes.md index 9dc430f11..5b6cfe35c 100644 --- a/docs/how-to/brownfield/quick-fix-in-brownfield.md +++ b/docs/how-to/quick-fixes.md @@ -1,6 +1,6 @@ --- -title: "How to Make Quick Fixes in Brownfield Projects" -description: How to make quick fixes and ad-hoc changes in brownfield projects +title: "Quick Fixes" +description: How to make quick fixes and ad-hoc changes --- Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full BMad method or Quick Flow. diff --git a/docs/reference/workflow-map.md b/docs/reference/workflow-map.md index 1425c4698..0df3d3ec8 100644 --- a/docs/reference/workflow-map.md +++ b/docs/reference/workflow-map.md @@ -73,7 +73,7 @@ Skip phases 1-3 for small, well-understood work. Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without this structure, agents make inconsistent decisions. -For brownfield projects, `document-project` creates or updates `project-context.md` - what exists in the codebase and the rules all implementation workflows must observe. Run it just before Phase 4, and again when something significant changes - structure, architecture, or those rules. You can also edit `project-context.md` by hand. +For established projects, `document-project` creates or updates `project-context.md` - what exists in the codebase and the rules all implementation workflows must observe. Run it just before Phase 4, and again when something significant changes - structure, architecture, or those rules. You can also edit `project-context.md` by hand. All implementation workflows load `project-context.md` if it exists. Additional context per workflow: From 311b237d854792b2e3619f8d77fc246ca76c6649 Mon Sep 17 00:00:00 2001 From: Davor Racic Date: Fri, 6 Feb 2026 02:00:52 +0100 Subject: [PATCH 3/5] fix: trim activation header to avoid YAML formatting issues in kilo installer (#1537) * fix: trim activation header to avoid YAML formatting issues in kilo installer * refactor: convert kilo installer to use YAML object serialization and add workflow support - Replace string concatenation with yaml.parse/stringify for proper YAML handling - Add workflow command generation and export to .kilocode/workflows/ - Implement clearBmadWorkflows to remove old BMAD workflow files - Convert createModeEntry to createModeObject returning structured objects - Update cleanup to use YAML parsing for proper mode filtering - Update installCustomAgentLauncher to use object-based config * fix: add task and tool command generation to kilo installer --------- Co-authored-by: Brian --- tools/cli/installers/lib/ide/kilo.js | 238 +++++++++++++++------------ 1 file changed, 130 insertions(+), 108 deletions(-) diff --git a/tools/cli/installers/lib/ide/kilo.js b/tools/cli/installers/lib/ide/kilo.js index 45e380218..52fd17c90 100644 --- a/tools/cli/installers/lib/ide/kilo.js +++ b/tools/cli/installers/lib/ide/kilo.js @@ -1,7 +1,10 @@ const path = require('node:path'); const { BaseIdeSetup } = require('./_base-ide'); const chalk = require('chalk'); +const yaml = require('yaml'); const { AgentCommandGenerator } = require('./shared/agent-command-generator'); +const { WorkflowCommandGenerator } = require('./shared/workflow-command-generator'); +const { TaskToolCommandGenerator } = require('./shared/task-tool-command-generator'); /** * KiloCode IDE setup handler @@ -22,76 +25,94 @@ class KiloSetup extends BaseIdeSetup { async setup(projectDir, bmadDir, options = {}) { console.log(chalk.cyan(`Setting up ${this.name}...`)); - // Check for existing .kilocodemodes file + // Clean up any old BMAD installation first + await this.cleanup(projectDir); + + // Load existing config (may contain non-BMAD modes and other settings) const kiloModesPath = path.join(projectDir, this.configFile); - let existingModes = []; - let existingContent = ''; + let config = {}; if (await this.pathExists(kiloModesPath)) { - existingContent = await this.readFile(kiloModesPath); - // Parse existing modes - const modeMatches = existingContent.matchAll(/- slug: ([\w-]+)/g); - for (const match of modeMatches) { - existingModes.push(match[1]); + const existingContent = await this.readFile(kiloModesPath); + try { + config = yaml.parse(existingContent) || {}; + } catch { + // If parsing fails, start fresh but warn user + console.log(chalk.yellow('Warning: Could not parse existing .kilocodemodes, starting fresh')); + config = {}; } - console.log(chalk.yellow(`Found existing .kilocodemodes file with ${existingModes.length} modes`)); + } + + // Ensure customModes array exists + if (!Array.isArray(config.customModes)) { + config.customModes = []; } // Generate agent launchers const agentGen = new AgentCommandGenerator(this.bmadFolderName); const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []); - // Create modes content - let newModesContent = ''; + // Create mode objects and add to config let addedCount = 0; - let skippedCount = 0; for (const artifact of agentArtifacts) { - const slug = `bmad-${artifact.module}-${artifact.name}`; - - // Skip if already exists - if (existingModes.includes(slug)) { - console.log(chalk.dim(` Skipping ${slug} - already exists`)); - skippedCount++; - continue; - } - - const modeEntry = await this.createModeEntry(artifact, projectDir); - - newModesContent += modeEntry; + const modeObject = await this.createModeObject(artifact, projectDir); + config.customModes.push(modeObject); addedCount++; } - // Build final content - let finalContent = ''; - if (existingContent) { - finalContent = existingContent.trim() + '\n' + newModesContent; - } else { - finalContent = 'customModes:\n' + newModesContent; - } - - // Write .kilocodemodes file + // Write .kilocodemodes file with proper YAML structure + const finalContent = yaml.stringify(config, { lineWidth: 0 }); await this.writeFile(kiloModesPath, finalContent); + // Generate workflow commands + const workflowGenerator = new WorkflowCommandGenerator(this.bmadFolderName); + const { artifacts: workflowArtifacts } = await workflowGenerator.collectWorkflowArtifacts(bmadDir); + + // Write to .kilocode/workflows/ directory + const workflowsDir = path.join(projectDir, '.kilocode', 'workflows'); + await this.ensureDir(workflowsDir); + + // Clear old BMAD workflows before writing new ones + await this.clearBmadWorkflows(workflowsDir); + + // Write workflow files + const workflowCount = await workflowGenerator.writeDashArtifacts(workflowsDir, workflowArtifacts); + + // Generate task and tool commands + const taskToolGen = new TaskToolCommandGenerator(this.bmadFolderName); + const { artifacts: taskToolArtifacts, counts: taskToolCounts } = await taskToolGen.collectTaskToolArtifacts(bmadDir); + + // Write task/tool files to workflows directory (same location as workflows) + await taskToolGen.writeDashArtifacts(workflowsDir, taskToolArtifacts); + const taskCount = taskToolCounts.tasks || 0; + const toolCount = taskToolCounts.tools || 0; + console.log(chalk.green(`✓ ${this.name} configured:`)); console.log(chalk.dim(` - ${addedCount} modes added`)); - if (skippedCount > 0) { - console.log(chalk.dim(` - ${skippedCount} modes skipped (already exist)`)); - } + console.log(chalk.dim(` - ${workflowCount} workflows exported`)); + console.log(chalk.dim(` - ${taskCount} tasks exported`)); + console.log(chalk.dim(` - ${toolCount} tools exported`)); console.log(chalk.dim(` - Configuration file: ${this.configFile}`)); + console.log(chalk.dim(` - Workflows directory: .kilocode/workflows/`)); console.log(chalk.dim('\n Modes will be available when you open this project in KiloCode')); return { success: true, modes: addedCount, - skipped: skippedCount, + workflows: workflowCount, + tasks: taskCount, + tools: toolCount, }; } /** - * Create a mode entry for an agent + * Create a mode object for an agent + * @param {Object} artifact - Agent artifact + * @param {string} projectDir - Project directory + * @returns {Object} Mode object for YAML serialization */ - async createModeEntry(artifact, projectDir) { + async createModeObject(artifact, projectDir) { // Extract metadata from launcher content const titleMatch = artifact.content.match(/title="([^"]+)"/); const title = titleMatch ? titleMatch[1] : this.formatTitle(artifact.name); @@ -102,8 +123,8 @@ class KiloSetup extends BaseIdeSetup { const whenToUseMatch = artifact.content.match(/whenToUse="([^"]+)"/); const whenToUse = whenToUseMatch ? whenToUseMatch[1] : `Use for ${title} tasks`; - // Get the activation header from central template - const activationHeader = await this.getAgentCommandHeader(); + // Get the activation header from central template (trim to avoid YAML formatting issues) + const activationHeader = (await this.getAgentCommandHeader()).trim(); const roleDefinitionMatch = artifact.content.match(/roleDefinition="([^"]+)"/); const roleDefinition = roleDefinitionMatch @@ -113,22 +134,15 @@ class KiloSetup extends BaseIdeSetup { // Get relative path const relativePath = path.relative(projectDir, artifact.sourcePath).replaceAll('\\', '/'); - // Build mode entry (KiloCode uses same schema as Roo) - const slug = `bmad-${artifact.module}-${artifact.name}`; - let modeEntry = ` - slug: ${slug}\n`; - modeEntry += ` name: '${icon} ${title}'\n`; - modeEntry += ` roleDefinition: ${roleDefinition}\n`; - modeEntry += ` whenToUse: ${whenToUse}\n`; - modeEntry += ` customInstructions: |\n`; - modeEntry += ` ${activationHeader} Read the full YAML from ${relativePath} start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode\n`; - modeEntry += ` groups:\n`; - modeEntry += ` - read\n`; - modeEntry += ` - edit\n`; - modeEntry += ` - browser\n`; - modeEntry += ` - command\n`; - modeEntry += ` - mcp\n`; - - return modeEntry; + // Build mode object (KiloCode uses same schema as Roo) + return { + slug: `bmad-${artifact.module}-${artifact.name}`, + name: `${icon} ${title}`, + roleDefinition: roleDefinition, + whenToUse: whenToUse, + customInstructions: `${activationHeader} Read the full YAML from ${relativePath} start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode\n`, + groups: ['read', 'edit', 'browser', 'command', 'mcp'], + }; } /** @@ -141,6 +155,22 @@ class KiloSetup extends BaseIdeSetup { .join(' '); } + /** + * Clear old BMAD workflow files from workflows directory + * @param {string} workflowsDir - Workflows directory path + */ + async clearBmadWorkflows(workflowsDir) { + const fs = require('fs-extra'); + if (!(await fs.pathExists(workflowsDir))) return; + + const entries = await fs.readdir(workflowsDir); + for (const entry of entries) { + if (entry.startsWith('bmad-') && entry.endsWith('.md')) { + await fs.remove(path.join(workflowsDir, entry)); + } + } + } + /** * Cleanup KiloCode configuration */ @@ -151,28 +181,29 @@ class KiloSetup extends BaseIdeSetup { if (await fs.pathExists(kiloModesPath)) { const content = await fs.readFile(kiloModesPath, 'utf8'); - // Remove BMAD modes only - const lines = content.split('\n'); - const filteredLines = []; - let skipMode = false; - let removedCount = 0; + try { + const config = yaml.parse(content) || {}; - for (const line of lines) { - if (/^\s*- slug: bmad-/.test(line)) { - skipMode = true; - removedCount++; - } else if (skipMode && /^\s*- slug: /.test(line)) { - skipMode = false; - } + if (Array.isArray(config.customModes)) { + const originalCount = config.customModes.length; + // Remove BMAD modes only (keep non-BMAD modes) + config.customModes = config.customModes.filter((mode) => !mode.slug || !mode.slug.startsWith('bmad-')); + const removedCount = originalCount - config.customModes.length; - if (!skipMode) { - filteredLines.push(line); + if (removedCount > 0) { + await fs.writeFile(kiloModesPath, yaml.stringify(config, { lineWidth: 0 })); + console.log(chalk.dim(`Removed ${removedCount} BMAD modes from .kilocodemodes`)); + } } + } catch { + // If parsing fails, leave file as-is + console.log(chalk.yellow('Warning: Could not parse .kilocodemodes for cleanup')); } - - await fs.writeFile(kiloModesPath, filteredLines.join('\n')); - console.log(chalk.dim(`Removed ${removedCount} BMAD modes from .kilocodemodes`)); } + + // Clean up workflow files + const workflowsDir = path.join(projectDir, '.kilocode', 'workflows'); + await this.clearBmadWorkflows(workflowsDir); } /** @@ -185,31 +216,28 @@ class KiloSetup extends BaseIdeSetup { */ async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) { const kilocodemodesPath = path.join(projectDir, this.configFile); - let existingContent = ''; + let config = {}; // Read existing .kilocodemodes file if (await this.pathExists(kilocodemodesPath)) { - existingContent = await this.readFile(kilocodemodesPath); + const existingContent = await this.readFile(kilocodemodesPath); + try { + config = yaml.parse(existingContent) || {}; + } catch { + config = {}; + } } - // Create custom agent mode entry + // Ensure customModes array exists + if (!Array.isArray(config.customModes)) { + config.customModes = []; + } + + // Create custom agent mode object const slug = `bmad-custom-${agentName.toLowerCase()}`; - const modeEntry = ` - slug: ${slug} - name: 'BMAD Custom: ${agentName}' - description: | - Custom BMAD agent: ${agentName} - - **⚠️ IMPORTANT**: Run @${agentPath} first to load the complete agent! - - This is a launcher for the custom BMAD agent "${agentName}". The agent will follow the persona and instructions from the main agent file. - prompt: | - @${agentPath} - always: false - permissions: all -`; // Check if mode already exists - if (existingContent.includes(slug)) { + if (config.customModes.some((mode) => mode.slug === slug)) { return { ide: 'kilo', path: this.configFile, @@ -219,24 +247,18 @@ class KiloSetup extends BaseIdeSetup { }; } - // Build final content - let finalContent = ''; - if (existingContent) { - // Find customModes section or add it - if (existingContent.includes('customModes:')) { - // Append to existing customModes - finalContent = existingContent + modeEntry; - } else { - // Add customModes section - finalContent = existingContent.trim() + '\n\ncustomModes:\n' + modeEntry; - } - } else { - // Create new .kilocodemodes file with customModes - finalContent = 'customModes:\n' + modeEntry; - } + // Add custom mode object + config.customModes.push({ + slug: slug, + name: `BMAD Custom: ${agentName}`, + description: `Custom BMAD agent: ${agentName}\n\n**⚠️ IMPORTANT**: Run @${agentPath} first to load the complete agent!\n\nThis is a launcher for the custom BMAD agent "${agentName}". The agent will follow the persona and instructions from the main agent file.\n`, + prompt: `@${agentPath}\n`, + always: false, + permissions: 'all', + }); - // Write .kilocodemodes file - await this.writeFile(kilocodemodesPath, finalContent); + // Write .kilocodemodes file with proper YAML structure + await this.writeFile(kilocodemodesPath, yaml.stringify(config, { lineWidth: 0 })); return { ide: 'kilo', From 420e720242ab601e6b3ff37c06b7fa8a2df068cf Mon Sep 17 00:00:00 2001 From: Michael Pursifull Date: Thu, 5 Feb 2026 19:04:31 -0600 Subject: [PATCH 4/5] fix: bmad-help reads project docs and respects communication_language (#1535) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix: bmad-help agent reads project docs and respects communication_language The help task fabricated tech stack information instead of reading actual project documentation (#1460) and ignored communication_language config (#1457). Three changes: 1. Step 2 now also extracts communication_language and project_knowledge from the active module's config.yaml 2. New step 3 scans project_knowledge path for documentation and uses discovered facts as grounding context, with anti-hallucination guard 3. Step 7 enforces {communication_language} in all output Chose inline config resolution over workflow.yaml conversion to match existing core task patterns (index-docs, shard-doc). Fixes #1460 Relates to #1457 * fix: clarify config extraction wording in help task Remove "active module" reference from step 2 — config extraction happens during the all-modules scan, before module detection in step 4. Changed to "each scanned module's config" to match the existing iteration pattern. Addresses CodeRabbit review feedback on PR #1535. --------- Co-authored-by: Brian --- src/core/tasks/help.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/core/tasks/help.md b/src/core/tasks/help.md index 4e060ea1f..c3c3fab11 100644 --- a/src/core/tasks/help.md +++ b/src/core/tasks/help.md @@ -54,13 +54,15 @@ Determine what was just completed: 1. **Load catalog** — Load `{project-root}/_bmad/_config/bmad-help.csv` -2. **Resolve output locations** — Scan each folder under `_bmad/` (except `_config`) for `config.yaml`. For each workflow row, resolve its `output-location` variables against that module's config so artifact paths can be searched. +2. **Resolve output locations and config** — Scan each folder under `_bmad/` (except `_config`) for `config.yaml`. For each workflow row, resolve its `output-location` variables against that module's config so artifact paths can be searched. Also extract `communication_language` and `project_knowledge` from each scanned module's config. -3. **Detect active module** — Use MODULE DETECTION above +3. **Ground in project knowledge** — If `project_knowledge` resolves to an existing path, read available documentation files (architecture docs, project overview, tech stack references) for grounding context. Use discovered project facts when composing any project-specific output. Never fabricate project-specific details — if documentation is unavailable, state so. -4. **Analyze input** — Task may provide a workflow name/code, conversational phrase, or nothing. Infer what was just completed using INPUT ANALYSIS above. +4. **Detect active module** — Use MODULE DETECTION above -5. **Present recommendations** — Show next steps based on: +5. **Analyze input** — Task may provide a workflow name/code, conversational phrase, or nothing. Infer what was just completed using INPUT ANALYSIS above. + +6. **Present recommendations** — Show next steps based on: - Completed workflows detected - Phase/sequence ordering (ROUTING RULES) - Artifact presence @@ -74,9 +76,10 @@ Determine what was just completed: - **Agent** title and display name from the CSV (e.g., "🎨 Alex (Designer)") - Brief **description** -6. **Additional guidance to convey**: +7. **Additional guidance to convey**: + - Present all output in `{communication_language}` - Run each workflow in a **fresh context window** - For **validation workflows**: recommend using a different high-quality LLM if available - For conversational requests: match the user's tone while presenting clearly -7. Return to the calling process after presenting recommendations. +8. Return to the calling process after presenting recommendations. From 068a9dc45aa23e697264e912cf30ae170e586158 Mon Sep 17 00:00:00 2001 From: Drickon <41375613+Drickon@users.noreply.github.com> Date: Thu, 5 Feb 2026 19:06:26 -0600 Subject: [PATCH 5/5] fix: remove --prefer-offline flag to prevent stale cache errors (#1531) The --prefer-offline flag causes npm to use cached package metadata, which can be stale and fail to resolve recently published versions. Also updates deprecated --production flag to --omit=dev. Fixes #1438 --- tools/cli/installers/lib/modules/manager.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index f06f5483c..c55dae838 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -417,7 +417,7 @@ class ModuleManager { if (needsDependencyInstall || wasNewClone || nodeModulesMissing) { const installSpinner = ora(`Installing dependencies for ${moduleInfo.name}...`).start(); try { - execSync('npm install --production --no-audit --no-fund --prefer-offline --no-progress --legacy-peer-deps', { + execSync('npm install --omit=dev --no-audit --no-fund --no-progress --legacy-peer-deps', { cwd: moduleCacheDir, stdio: 'pipe', timeout: 120_000, // 2 minute timeout @@ -442,7 +442,7 @@ class ModuleManager { if (packageJsonNewer) { const installSpinner = ora(`Installing dependencies for ${moduleInfo.name}...`).start(); try { - execSync('npm install --production --no-audit --no-fund --prefer-offline --no-progress --legacy-peer-deps', { + execSync('npm install --omit=dev --no-audit --no-fund --no-progress --legacy-peer-deps', { cwd: moduleCacheDir, stdio: 'pipe', timeout: 120_000, // 2 minute timeout