From 1676f5189ed057fa2d7facbd6a771fe67cdb6372 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Wed, 6 Aug 2025 00:00:26 -0500 Subject: [PATCH] fix: doc location improvement --- README.md | 12 ++-- dist/agents/dev.txt | 18 +++--- dist/teams/team-all.txt | 18 +++--- dist/teams/team-ide-minimal.txt | 18 +++--- .../enhanced-ide-development-workflow.md | 0 {bmad-core => docs}/user-guide.md | 0 .../working-in-the-brownfield.md | 0 tools/installer/lib/installer.js | 64 ++++++++++++++++++- 8 files changed, 96 insertions(+), 34 deletions(-) rename {bmad-core => docs}/enhanced-ide-development-workflow.md (100%) rename {bmad-core => docs}/user-guide.md (100%) rename {bmad-core => docs}/working-in-the-brownfield.md (100%) diff --git a/README.md b/README.md index 8580fd81..b19e36d3 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Foundations in Agentic Agile Driven Development, known as the Breakthrough Metho This two-phase approach eliminates both **planning inconsistency** and **context loss** - the biggest problems in AI-assisted development. Your Dev agent opens a story file with complete understanding of what to build, how to build it, and why. -**📖 [See the complete workflow in the User Guide](bmad-core/user-guide.md)** - Planning phase, development cycle, and all agent roles +**📖 [See the complete workflow in the User Guide](docs/user-guide.md)** - Planning phase, development cycle, and all agent roles ## Quick Navigation @@ -31,15 +31,15 @@ This two-phase approach eliminates both **planning inconsistency** and **context **Before diving in, review these critical workflow diagrams that explain how BMad works:** -1. **[Planning Workflow (Web UI)](bmad-core/user-guide.md#the-planning-workflow-web-ui)** - How to create PRD and Architecture documents -2. **[Core Development Cycle (IDE)](bmad-core/user-guide.md#the-core-development-cycle-ide)** - How SM, Dev, and QA agents collaborate through story files +1. **[Planning Workflow (Web UI)](docs/user-guide.md#the-planning-workflow-web-ui)** - How to create PRD and Architecture documents +2. **[Core Development Cycle (IDE)](docs/user-guide.md#the-core-development-cycle-ide)** - How SM, Dev, and QA agents collaborate through story files > ⚠️ **These diagrams explain 90% of BMad Method Agentic Agile flow confusion** - Understanding the PRD+Architecture creation and the SM/Dev/QA workflow and how agents pass notes through story files is essential - and also explains why this is NOT taskmaster or just a simple task runner! ### What would you like to do? - **[Install and Build software with Full Stack Agile AI Team](#quick-start)** → Quick Start Instruction -- **[Learn how to use BMad](bmad-core/user-guide.md)** → Complete user guide and walkthrough +- **[Learn how to use BMad](docs/user-guide.md)** → Complete user guide and walkthrough - **[See available AI agents](/bmad-core/agents))** → Specialized roles for your team - **[Explore non-technical uses](#-beyond-software-development---expansion-packs)** → Creative writing, business, wellness, education - **[Create my own AI agents](#creating-your-own-expansion-pack)** → Build agents for your domain @@ -97,7 +97,7 @@ This single command handles: 3. **Upload & configure**: Upload the file and set instructions: "Your critical operating instructions are attached, do not break character as directed" 4. **Start Ideating and Planning**: Start chatting! Type `*help` to see available commands or pick an agent like `*analyst` to start right in on creating a brief. 5. **CRITICAL**: Talk to BMad Orchestrator in the web at ANY TIME (#bmad-orchestrator command) and ask it questions about how this all works! -6. **When to move to the IDE**: Once you have your PRD, Architecture, optional UX and Briefs - its time to switch over to the IDE to shard your docs, and start implementing the actual code! See the [User guide](bmad-core/user-guide.md) for more details +6. **When to move to the IDE**: Once you have your PRD, Architecture, optional UX and Briefs - its time to switch over to the IDE to shard your docs, and start implementing the actual code! See the [User guide](docs/user-guide.md) for more details ### Alternative: Clone and Build @@ -161,7 +161,7 @@ The generated XML file contains all your project's source code in a structured f ### Essential Guides -- 📖 **[User Guide](bmad-core/user-guide.md)** - Complete walkthrough from project inception to completion +- 📖 **[User Guide](docs/user-guide.md)** - Complete walkthrough from project inception to completion - 🏗️ **[Core Architecture](docs/core-architecture.md)** - Technical deep dive and system design - 🚀 **[Expansion Packs Guide](docs/expansion-packs.md)** - Extend BMad to any domain beyond software development diff --git a/dist/agents/dev.txt b/dist/agents/dev.txt index 3bd5d12c..9f66ea96 100644 --- a/dist/agents/dev.txt +++ b/dist/agents/dev.txt @@ -72,15 +72,15 @@ commands: - run-tests: Execute linting and tests - explain: teach me what and why you did whatever you just did in detail so I can learn. Explain to me as if you were training a junior engineer. - exit: Say goodbye as the Developer, and then abandon inhabiting this persona -develop-story: - order-of-execution: Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete - story-file-updates-ONLY: - - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS. - - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status - - CRITICAL: DO NOT modify Status, Story, Acceptance Criteria, Dev Notes, Testing sections, or any other sections not listed above - blocking: 'HALT for: Unapproved deps needed, confirm with user | Ambiguous after story check | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression' - ready-for-review: Code matches requirements + All validations pass + Follows standards + File List complete - completion: 'All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: ''Ready for Review''→HALT' + - develop-story: + - order-of-execution: Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete + - story-file-updates-ONLY: + - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS. + - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status + - CRITICAL: DO NOT modify Status, Story, Acceptance Criteria, Dev Notes, Testing sections, or any other sections not listed above + - blocking: 'HALT for: Unapproved deps needed, confirm with user | Ambiguous after story check | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression' + - ready-for-review: Code matches requirements + All validations pass + Follows standards + File List complete + - completion: 'All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: ''Ready for Review''→HALT' dependencies: tasks: - execute-checklist.md diff --git a/dist/teams/team-all.txt b/dist/teams/team-all.txt index d59edc90..58197992 100644 --- a/dist/teams/team-all.txt +++ b/dist/teams/team-all.txt @@ -352,15 +352,15 @@ commands: - run-tests: Execute linting and tests - explain: teach me what and why you did whatever you just did in detail so I can learn. Explain to me as if you were training a junior engineer. - exit: Say goodbye as the Developer, and then abandon inhabiting this persona -develop-story: - order-of-execution: Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete - story-file-updates-ONLY: - - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS. - - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status - - CRITICAL: DO NOT modify Status, Story, Acceptance Criteria, Dev Notes, Testing sections, or any other sections not listed above - blocking: 'HALT for: Unapproved deps needed, confirm with user | Ambiguous after story check | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression' - ready-for-review: Code matches requirements + All validations pass + Follows standards + File List complete - completion: 'All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: ''Ready for Review''→HALT' + - develop-story: + - order-of-execution: Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete + - story-file-updates-ONLY: + - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS. + - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status + - CRITICAL: DO NOT modify Status, Story, Acceptance Criteria, Dev Notes, Testing sections, or any other sections not listed above + - blocking: 'HALT for: Unapproved deps needed, confirm with user | Ambiguous after story check | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression' + - ready-for-review: Code matches requirements + All validations pass + Follows standards + File List complete + - completion: 'All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: ''Ready for Review''→HALT' dependencies: tasks: - execute-checklist.md diff --git a/dist/teams/team-ide-minimal.txt b/dist/teams/team-ide-minimal.txt index fbcfb3c9..4e7a33fe 100644 --- a/dist/teams/team-ide-minimal.txt +++ b/dist/teams/team-ide-minimal.txt @@ -322,15 +322,15 @@ commands: - run-tests: Execute linting and tests - explain: teach me what and why you did whatever you just did in detail so I can learn. Explain to me as if you were training a junior engineer. - exit: Say goodbye as the Developer, and then abandon inhabiting this persona -develop-story: - order-of-execution: Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete - story-file-updates-ONLY: - - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS. - - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status - - CRITICAL: DO NOT modify Status, Story, Acceptance Criteria, Dev Notes, Testing sections, or any other sections not listed above - blocking: 'HALT for: Unapproved deps needed, confirm with user | Ambiguous after story check | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression' - ready-for-review: Code matches requirements + All validations pass + Follows standards + File List complete - completion: 'All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: ''Ready for Review''→HALT' + - develop-story: + - order-of-execution: Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete + - story-file-updates-ONLY: + - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS. + - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status + - CRITICAL: DO NOT modify Status, Story, Acceptance Criteria, Dev Notes, Testing sections, or any other sections not listed above + - blocking: 'HALT for: Unapproved deps needed, confirm with user | Ambiguous after story check | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression' + - ready-for-review: Code matches requirements + All validations pass + Follows standards + File List complete + - completion: 'All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: ''Ready for Review''→HALT' dependencies: tasks: - execute-checklist.md diff --git a/bmad-core/enhanced-ide-development-workflow.md b/docs/enhanced-ide-development-workflow.md similarity index 100% rename from bmad-core/enhanced-ide-development-workflow.md rename to docs/enhanced-ide-development-workflow.md diff --git a/bmad-core/user-guide.md b/docs/user-guide.md similarity index 100% rename from bmad-core/user-guide.md rename to docs/user-guide.md diff --git a/bmad-core/working-in-the-brownfield.md b/docs/working-in-the-brownfield.md similarity index 100% rename from bmad-core/working-in-the-brownfield.md rename to docs/working-in-the-brownfield.md diff --git a/tools/installer/lib/installer.js b/tools/installer/lib/installer.js index 5e3b6e0e..30ed75ce 100644 --- a/tools/installer/lib/installer.js +++ b/tools/installer/lib/installer.js @@ -237,6 +237,10 @@ class Installer { // Copy common/ items to .bmad-core spinner.text = "Copying common utilities..."; await this.copyCommonItems(installDir, ".bmad-core", spinner); + + // Copy documentation files from docs/ to .bmad-core + spinner.text = "Copying documentation files..."; + await this.copyDocsItems(installDir, ".bmad-core", spinner); // Get list of all files for manifest const foundFiles = await resourceLocator.findFiles("**/*", { @@ -308,6 +312,11 @@ class Installer { spinner.text = "Copying common utilities..."; const commonFiles = await this.copyCommonItems(installDir, ".bmad-core", spinner); files.push(...commonFiles); + + // Copy documentation files from docs/ to .bmad-core + spinner.text = "Copying documentation files..."; + const docFiles = await this.copyDocsItems(installDir, ".bmad-core", spinner); + files.push(...docFiles); } else if (config.installType === "team") { // Team installation spinner.text = `Installing ${config.team} team...`; @@ -353,6 +362,11 @@ class Installer { spinner.text = "Copying common utilities..."; const commonFiles = await this.copyCommonItems(installDir, ".bmad-core", spinner); files.push(...commonFiles); + + // Copy documentation files from docs/ to .bmad-core + spinner.text = "Copying documentation files..."; + const docFiles = await this.copyDocsItems(installDir, ".bmad-core", spinner); + files.push(...docFiles); } else if (config.installType === "expansion-only") { // Expansion-only installation - DO NOT create .bmad-core // Only install expansion packs @@ -896,7 +910,7 @@ class Installer { } // Important notice to read the user guide - console.log(chalk.red.bold("\n📖 IMPORTANT: Please read the user guide installed at .bmad-core/user-guide.md")); + console.log(chalk.red.bold("\n📖 IMPORTANT: Please read the user guide at docs/user-guide.md (also installed at .bmad-core/user-guide.md)")); console.log(chalk.red("This guide contains essential information about the BMad workflow and how to use the agents effectively.")); } @@ -1557,6 +1571,54 @@ class Installer { return copiedFiles; } + async copyDocsItems(installDir, targetSubdir, spinner) { + const fs = require('fs').promises; + const sourceBase = path.dirname(path.dirname(path.dirname(path.dirname(__filename)))); // Go up to project root + const docsPath = path.join(sourceBase, 'docs'); + const targetPath = path.join(installDir, targetSubdir); + const copiedFiles = []; + + // Specific documentation files to copy + const docFiles = [ + 'enhanced-ide-development-workflow.md', + 'user-guide.md', + 'working-in-the-brownfield.md' + ]; + + // Check if docs/ exists + if (!(await fileManager.pathExists(docsPath))) { + console.warn('Warning: docs/ folder not found'); + return copiedFiles; + } + + // Copy specific documentation files from docs/ to target + for (const docFile of docFiles) { + const sourcePath = path.join(docsPath, docFile); + const destPath = path.join(targetPath, docFile); + + // Check if the source file exists + if (await fileManager.pathExists(sourcePath)) { + // Read the file content + const content = await fs.readFile(sourcePath, 'utf8'); + + // Replace {root} with the target subdirectory + const updatedContent = content.replace(/\{root\}/g, targetSubdir); + + // Ensure directory exists + await fileManager.ensureDirectory(path.dirname(destPath)); + + // Write the updated content + await fs.writeFile(destPath, updatedContent, 'utf8'); + copiedFiles.push(path.join(targetSubdir, docFile)); + } + } + + if (copiedFiles.length > 0) { + console.log(chalk.dim(` Added ${copiedFiles.length} documentation files`)); + } + return copiedFiles; + } + async detectExpansionPacks(installDir) { const expansionPacks = {}; const glob = require("glob");