Merge branch 'main' into feat/validate-workflow-schema

This commit is contained in:
Brian 2026-02-05 19:07:12 -06:00 committed by GitHub
commit d097b5e82b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 205 additions and 186 deletions

View File

@ -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

View File

@ -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!

View File

@ -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!

View File

@ -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

View File

@ -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.

View File

@ -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:

View File

@ -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.

View File

@ -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,29 +181,30 @@ 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);
}
}
await fs.writeFile(kiloModesPath, filteredLines.join('\n'));
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'));
}
}
// Clean up workflow files
const workflowsDir = path.join(projectDir, '.kilocode', 'workflows');
await this.clearBmadWorkflows(workflowsDir);
}
/**
* Install a custom agent launcher for Kilo
@ -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',

View File

@ -124,8 +124,13 @@ platforms:
category: ide
description: "OpenCode terminal coding assistant"
installer:
target_dir: .opencode/command
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"

View File

@ -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