ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README links to renamed orchestrator config files (#115)

Browse Source 
* docs: update README links to renamed orchestrator config files

## CHANGES

- Update orchestrator link to ide-bmad-orchestrator.md
- Update config link to ide-bmad-orchestrator.cfg.md
- Fix Markdownlint errors in ide-bmad-orchestrator.cfg.md

* docs: update path references from BETA-V3 to bmad-agent in instruction.md

## CHANGES

- Update all BETA-V3 directory references to bmad-agent
- Clarify paths are relative to bmad-agent directory
- Fix markdown formatting for numbered lists
- Update IDE orchestrator configuration path examples
- Correct agent-root path in Data Resolution section
- Remove references to deprecated BETA-V3 structure
This commit is contained in:
Kayvan Sylvan
2025-05-28 17:41:02 -07:00
committed by GitHub
parent 82bdb3ded0
commit ca56866866
3 changed files with 32 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -18,7 +18,7 @@ Here are the more [Setup and Usage Instructions](./docs/instruction.md) for IDE,
Starting with the latest version of the BMad Agents for the BMad Method is very easy - all you need to do is copy `bmad-agent` folder to your project. The dedicated dev and sm that existing in previous versions are still available and are in the `bmad-agent/personas` folder with the .ide.md extension. Copy and paste the contents into your specific IDE's method of configuring a custom agent mode. The dev and sm both are configured for architecture and prd artifacts to be in (project-root)/docs and stories will be generated and developed in/from your (project-root)/docs/stories.
For all other agent use (including the dev and sm) you can set up the [ide orchestrator](bmad-agent/bmad-agent.ide.md) - you can ask the orchestrator bmad to become any agent you have [configured](bmad-agent/bmad-orchestrator.ide.cfg.md).
For all other agent use (including the dev and sm) you can set up the [ide orchestrator](bmad-agent/ide-bmad-orchestrator.md) - you can ask the orchestrator bmad to become any agent you have [configured](bmad-agent/ide-bmad-orchestrator.cfg.md).
[General IDE Custom Mode Setup](./docs/ide-setup.md).

14
bmad-agent/ide-bmad-orchestrator.md
View File

@@ -5,14 +5,14 @@
## Core Orchestrator Principles
1. **Config-Driven Authority:** All knowledge of available personas, tasks, persona files, task files, and global resource paths (for templates, checklists, data) MUST originate from the loaded Config.
2. **Global Resource Path Resolution:** When an active persona executes a task, and that task file (or any other loaded content) references templates, checklists, or data files by filename only, their full paths MUST be resolved using the appropriate base paths defined in the `Data Resolution` section of the Config - assume extension is md if not specified.
3. **Single Active Persona Mandate:** Embody ONLY ONE specialist persona at a time.
4. **Clarity in Operation:** Always be clear about which persona is currently active and what task is being performed.
1. **Config-Driven Authority:** All knowledge of available personas, tasks, persona files, task files, and global resource paths (for templates, checklists, data) MUST originate from the loaded Config.
2. **Global Resource Path Resolution:** When an active persona executes a task, and that task file (or any other loaded content) references templates, checklists, or data files by filename only, their full paths MUST be resolved using the appropriate base paths defined in the `Data Resolution` section of the Config - assume extension is md if not specified.
3. **Single Active Persona Mandate:** Embody ONLY ONE specialist persona at a time.
4. **Clarity in Operation:** Always be clear about which persona is currently active and what task is being performed.
## Critical Start-Up & Operational Workflow
### 1. Initialization & User Interaction Prompt:
### 1. Initialization & User Interaction Prompt
- CRITICAL: Your FIRST action: Load & parse `configFile` (hereafter "Config"). This Config defines ALL available personas, their associated tasks, and resource paths. If Config is missing or unparsable, inform user that you cannot locate the config and can only operate as a BMad Method Advisor (based on the kb data).
Greet the user concisely (e.g., "BMad IDE Orchestrator ready. Config loaded. Select Agent, or I can remain in Advisor mode.").
@@ -20,7 +20,7 @@
- Based on the loaded Config, list available specialist personas by their `Title` (and `Name` if distinct) along with their `Description`. For each persona, list the display names of its configured `Tasks`.
- Ask: "Which persona shall I become, and what task should it perform?" Await user's specific choice.
### 2. Persona Activation & Task Execution:
### 2. Persona Activation & Task Execution
- **A. Activate Persona:**
- From the user's request, identify the target persona by matching against `Title` or `Name` in the Config.
@@ -39,7 +39,7 @@
- **If an "In Memory" task:** Follow as stated internally.
- Upon task completion continue interacting as the active persona.
### 3. Handling Requests for Persona Change (While a Persona is Active):
### 3. Handling Requests for Persona Change (While a Persona is Active)
- If you are currently embodying a specialist persona and the user requests to become a _different_ persona, suggest starting new chat, but let them choose to `Proceed (y/n)?`
- **If user chooses to override:**

48
docs/instruction.md
View File

@@ -31,27 +31,27 @@ The build process is configured via `build-web-agent.cfg.js`. Key parameters inc
- `agent_cfg`: Specifies the path to the md cfg file that defines the agents the Orchestrator can embody.
- Example: `./bmad-agent/web-bmad-orchestrator-agent.cfg.md`
Paths in the configuration file (`build-web-agent.cfg.js`) are relative to the `BETA-V3` directory (where `build-web-agent.cfg.js` and the build script `build-bmad-orchestrator.js` are located).
Paths in the configuration file (`build-web-agent.cfg.js`) are relative to the `bmad-agent` directory (where `build-web-agent.cfg.js` and the build script `build-bmad-orchestrator.js` are located).
### Asset Directory Structure
The script expects a specific structure within the `asset_root` directory:
1. **Subdirectories**: Create subdirectories directly under `asset_root` for each category of assets. Based on the `bmad-agent/` folder, these would be:
1. **Subdirectories**: Create subdirectories directly under `asset_root` for each category of assets. Based on the `bmad-agent/` folder, these would be:
- `checklists/`
- `data/`
- `personas/`
- `tasks/`
- `templates/`
2. **Asset Files**: Place your individual asset files (e.g., `.md`, `.txt`) within these subdirectories.
2. **Asset Files**: Place your individual asset files (e.g., `.md`, `.txt`) within these subdirectories.
- For example, persona definition files would go into `asset_root/personas/`, task files into `asset_root/tasks/`, etc.
3. **Filename Uniqueness**: Within each subdirectory, ensure that all files have unique base names (i.e., the filename without its final extension). For example, having `my-persona.md` and `my-persona.txt` in the _same_ subdirectory (e.g., `personas/`) will cause the script to halt with an error. However, `my-persona.md` and `another-persona.md` is fine.
3. **Filename Uniqueness**: Within each subdirectory, ensure that all files have unique base names (i.e., the filename without its final extension). For example, having `my-persona.md` and `my-persona.txt` in the _same_ subdirectory (e.g., `personas/`) will cause the script to halt with an error. However, `my-persona.md` and `another-persona.md` is fine.
### Running the Build Script
NOTE the build will skip any files with the `.ide.<extension>` - so you can have ide specific agents or files also that do not make sense for the web, such as `dev.ide.md` - or a specific ide `sm.ide.md`.
1. ```cmd
1. ```cmd
node build-web-agent.js
```
@@ -61,11 +61,11 @@ The script will log its progress, including discovered source directories, any i
After running the script, the `build_dir` (e.g., `bmad-agent/build/`) will contain:
1. **Bundled Asset Files**: For each subdirectory processed in `asset_root`, a corresponding `.txt` file will be created in `build_dir`. Each file concatenates the content of all files from its source subdirectory.
1. **Bundled Asset Files**: For each subdirectory processed in `asset_root`, a corresponding `.txt` file will be created in `build_dir`. Each file concatenates the content of all files from its source subdirectory.
- Example: Files from `asset_root/personas/` will be bundled into `build_dir/personas.txt`.
- Each original file's content within the bundle is demarcated by `==================== START: [base_filename] ====================` and `==================== END: [base_filename] ====================`.
2. **`agent-prompt.txt`**: This file is a copy of the bmad orchestrator prompt specified by `orchestrator_agent_prompt` in the configuration.
3. **`agent-config.txt**: This is the key file so the orchestrator knows what agents and tasks are configured, and how to find the specific instructions and tasks for the agent in the compiled build assets
2. **`agent-prompt.txt`**: This file is a copy of the bmad orchestrator prompt specified by `orchestrator_agent_prompt` in the configuration.
3. **`agent-config.txt**: This is the key file so the orchestrator knows what agents and tasks are configured, and how to find the specific instructions and tasks for the agent in the compiled build assets
These bundled files and the agent prompt are then ready to be used by the Agent Orchestrator.
@@ -73,9 +73,9 @@ These bundled files and the agent prompt are then ready to be used by the Agent
The text in agent-prompt.txt gets entered into the window of the main custom web agent instruction set. The other files in the build folder all need to be attached as files for the Gem or GPT.
### Orchestrator Agent Configuration (e.g., `BETA-V3/bmad-agent/web-bmad-orchestrator-agent.cfg.md`)
### Orchestrator Agent Configuration (e.g., `bmad-agent/web-bmad-orchestrator-agent.cfg.md`)
While `build-bmad-orchestrator.js` packages assets, the Orchestrator's core behavior, agent definitions, and personality are defined in a Markdown configuration file. An example is `bmad-agent/web-bmad-orchestrator-agent.cfg.md` (path relative to `BETA-V3/`, specified in `build-web-agent.cfg.js` via `agent_cfg`). This file is key to the Orchestrator's adaptability.
While `build-bmad-orchestrator.js` packages assets, the Orchestrator's core behavior, agent definitions, and personality are defined in a Markdown configuration file. An example is `bmad-agent/web-bmad-orchestrator-agent.cfg.md` (path relative to `bmad-agent/`, specified in `build-web-agent.cfg.js` via `agent_cfg`). This file is key to the Orchestrator's adaptability.
**Key Features and Configurability:**
@@ -113,13 +113,13 @@ While `build-bmad-orchestrator.js` packages assets, the Orchestrator's core beha
**How it Works (Conceptual Flow from `orchestrator-agent.md`):**
1. The Orchestrator (initially BMad) loads and parses the Markdown agent configuration file (e.g., `web-bmad-orchestrator-agent.cfg.md`).
2. When a user request matches an agent's `title`, `name`, `description`, or `classification_label`, the Orchestrator identifies the target agent.
3. It then loads the agent's `persona` and any associated `templates`, `checklists`, `data_sources`, and `tasks` by:
1. The Orchestrator (initially BMad) loads and parses the Markdown agent configuration file (e.g., `web-bmad-orchestrator-agent.cfg.md`).
2. When a user request matches an agent's `title`, `name`, `description`, or `classification_label`, the Orchestrator identifies the target agent.
3. It then loads the agent's `persona` and any associated `templates`, `checklists`, `data_sources`, and `tasks` by:
- Identifying the correct bundled `.txt` file (e.g., `personas.txt` for `personas#pm`).
- Extracting the specific content block (e.g., the `pm` section from `personas.txt`).
4. The `Customize` instructions from the Markdown configuration are applied, potentially modifying the agent's behavior.
5. The Orchestrator then _becomes_ that agent, adopting its complete persona, knowledge, and operational parameters defined in the Markdown configuration and the loaded asset sections.
4. The `Customize` instructions from the Markdown configuration are applied, potentially modifying the agent's behavior.
5. The Orchestrator then _becomes_ that agent, adopting its complete persona, knowledge, and operational parameters defined in the Markdown configuration and the loaded asset sections.
This system makes the Agent Orchestrator highly adaptable. You can easily define new agents, modify existing ones, tweak personalities with the `Customize` field (in the Markdown agent configuration file like `web-bmad-orchestrator-agent.cfg.md`), or change their knowledge base, main prompt, and asset paths (in `build-web-agent.cfg.js` and the corresponding asset files), then re-running the build script if asset content was changed.
@@ -137,8 +137,8 @@ A powerful alternative is the `ide-bmad-orchestrator.md`. This agent provides th
#### How the IDE Orchestrator Works
1. **Configuration (`ide-bmad-orchestrator.cfg.md`):**
The orchestrator's behavior is primarily driven by a Markdown configuration file (e.g., `BETA-V3/bmad-agent/ide-bmad-orchestrator.cfg.md`, the path to which is specified within the `ide-bmad-orchestrator.md` itself). This config file has two main parts:
1. **Configuration (`ide-bmad-orchestrator.cfg.md`):**
The orchestrator's behavior is primarily driven by a Markdown configuration file (e.g., `bmad-agent/ide-bmad-orchestrator.cfg.md`, the path to which is specified within the `ide-bmad-orchestrator.md` itself). This config file has two main parts:
- **Data Resolution:**
Located at the top of the config file, this section defines key-value pairs for base paths. These paths tell the orchestrator where to find different types of asset files (personas, tasks, checklists, templates, data).
@@ -148,7 +148,7 @@ A powerful alternative is the `ide-bmad-orchestrator.md`. This agent provides th
## Data Resolution
agent-root: (project-root)/BETA-V3/bmad-agent
agent-root: (project-root)/bmad-agent
checklists: (agent-root)/checklists
data: (agent-root)/data
personas: (agent-root)/personas
@@ -185,7 +185,7 @@ A powerful alternative is the `ide-bmad-orchestrator.md`. This agent provides th
- [Create Next Story](create-next-story-task.md)
```
2. **Operational Workflow (inside `ide-bmad-orchestrator.md`):**
2. **Operational Workflow (inside `ide-bmad-orchestrator.md`):**
- **Initialization:** Upon activation in your IDE, the `ide-bmad-orchestrator.md` first loads and parses its specified configuration file (`ide-bmad-orchestrator.cfg.md`). If this fails, it will inform you and halt.
- **Greeting & Persona Listing:** It will greet you. If your initial instruction isn't clear or if you ask, it will list the available specialist personas (by `Title`, `Name`, and `Description`) and the `Tasks` each can perform, all derived from the loaded configuration.
- **Persona Activation:** When you request a specific persona (e.g., "Become the Analyst" or "I need Larry to help with research"), the orchestrator:
@@ -201,16 +201,16 @@ A powerful alternative is the `ide-bmad-orchestrator.md`. This agent provides th
#### Usage Instructions for IDE Orchestrator
1. **Set up your configuration (`ide-bmad-orchestrator.cfg.md`):**
- Ensure you have an `ide-bmad-orchestrator.cfg.md` file. You can use the one located in `BETA-V3/bmad-agent/` as a template or starting point.
1. **Set up your configuration (`ide-bmad-orchestrator.cfg.md`):**
- Ensure you have an `ide-bmad-orchestrator.cfg.md` file. You can use the one located in `bmad-agent/` as a template or starting point.
- Verify that the `Data Resolution` paths at the top correctly point to your asset folders (personas, tasks, templates, checklists, data) relative to your project structure.
- Define your desired agents with their `Title`, `Name`, `Customize` instructions, `Persona` file, and `Tasks`. Ensure the referenced persona and task files exist in the locations specified by your `Data Resolution` paths.
2. **Set up your persona and task files:**
2. **Set up your persona and task files:**
- Create the Markdown files for each persona (e.g., `analyst.md`, `po.md`) in your `personas` directory.
- Create the Markdown files for each task (e.g., `create-prd.md`) in your `tasks` directory.
3. **Activate the Orchestrator:**
3. **Activate the Orchestrator:**
- In your IDE (e.g., Cursor), select the `ide-bmad-orchestrator.md` file/agent as your active AI assistant.
4. **Interact with the Orchestrator:**
4. **Interact with the Orchestrator:**
- **Initial Interaction:**
- The orchestrator will greet you and confirm it has loaded its configuration.
- You can ask: "What agents are available?" or "List personas and tasks."