From 70731dd9a1dbed9c2b088d67f31efaff28d286c4 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 1 Jul 2025 02:12:36 +0000 Subject: [PATCH] refactor: Update JMAD.md with rebranding and new reporting logic This commit updates JMAD.md to: 1. Rebrand "BMad Gem" to "JMAD Gem" throughout the document. References to the original BMad-METHOD and its assets (like team-all.txt and BMad agent personas) are retained for attribution. 2. Modify the information gathering strategy for the JMAD Gem. It's now instructed to: - Request Jules to generate markdown reports in a `docs/jules_reports/` subdirectory for extensive analysis or multiple file content. - Ask the user for direct input (e.g., copy-paste) for simpler queries involving one or two files, to help conserve Jules' daily task limits. 3. Ensure workflow examples and key principles reflect these changes. 4. General review for clarity and consistency. --- JMAD.md | 145 ++++++++++++++++++++++++++++++-------------------------- 1 file changed, 77 insertions(+), 68 deletions(-) diff --git a/JMAD.md b/JMAD.md index 0226d3fe..c5f77843 100644 --- a/JMAD.md +++ b/JMAD.md @@ -2,16 +2,16 @@ ## Overview -JMAD (Jules-Maximized Agile Development) is a methodology that synergizes the planning capabilities of a specialized Google Gemini Gem (the "BMad Gem") with the code execution and repository interaction strengths of Google Jules. This document provides instructions on how to create and utilize this workflow for both greenfield and brownfield projects. +JMAD (Jules-Maximized Agile Development) is a methodology that synergizes the planning capabilities of a specialized Google Gemini Gem (the "JMAD Gem") with the code execution and repository interaction strengths of Google Jules. This document provides instructions on how to create and utilize this workflow for both greenfield and brownfield projects. -The core idea is to use the BMad Gem, configured with the `team-all.txt` prompt bundle from the BMad-METHOD project, to perform comprehensive project planning, requirements gathering, and architecture design. The BMad Gem will be instructed to leverage Jules' ability to directly access and analyze the codebase for diagnostic tasks during the planning phase. The output of this planning phase will be a detailed, step-by-step plan formatted specifically for Jules to execute. +The core idea is to use the JMAD Gem, configured with the `team-all.txt` prompt bundle from the BMad-METHOD project, to perform comprehensive project planning, requirements gathering, and architecture design. The JMAD Gem will be instructed on how to request information: either by asking Jules (via the user) to generate a report, or by asking the user directly for simpler queries. The output of this planning phase will be a detailed, step-by-step plan formatted specifically for Jules to execute. -## I. Creating and Configuring the BMad Gem for JMAD +## I. Creating and Configuring the JMAD Gem -This BMad Gem will be your primary interface for planning and generating the execution plan for Jules. +This JMAD Gem will be your primary interface for planning and generating the execution plan for Jules. 1. **Obtain `team-all.txt`**: - * Clone or download the `bmad-method` repository from [https://github.com/bmadcode/bmad-method](https://github.com/bmadcode/bmad-method). + * Clone or download the `bmad-method` repository from [https://github.com/bmadcode/bmad-method](https://github.com/bmadcode/bmad-method). This is the original source for the agent prompts. * Locate the file `dist/teams/team-all.txt`. This file contains the aggregated prompts for all BMad agents. 2. **Create a New Google Gemini Gem**: @@ -19,8 +19,8 @@ This BMad Gem will be your primary interface for planning and generating the exe * Click on "Create new Gem." 3. **Configure the Gem**: - * **Title**: `BMad Gem for Jules Planning` (or a similar descriptive title). - * **Description**: "A specialized AI assistant for project planning and generating execution plans for Google Jules. It uses the BMad-METHOD's `team-all.txt` and is instructed to request codebase analysis from Jules via the user." + * **Title**: `JMAD Gem for Jules Planning` (or a similar descriptive title). + * **Description**: "A specialized AI assistant for project planning and generating execution plans for Google Jules. It uses the BMad-METHOD's `team-all.txt` as a base and is instructed on how to request codebase analysis: either via Jules reports or direct user input." * **Instructions / Prompt Configuration**: * Copy the entire content of `dist/teams/team-all.txt`. * Paste this content into the Gem's instruction/configuration field. @@ -29,17 +29,26 @@ This BMad Gem will be your primary interface for planning and generating the exe ```text --- JMAD AUGMENTATION --- - **Your Core Objective as BMad Gem for Jules Planning:** + **Your Core Objective as JMAD Gem for Jules Planning:** Your primary goal is to produce a detailed, step-by-step execution plan that Google Jules can implement. This plan will be the final output of your interaction with the user for a given development task (Epic or Story). - **Leveraging Jules for Codebase Interaction:** - You do NOT have direct access to the user's codebase. However, Google Jules DOES. During your planning, analysis, and problem-solving phases, if you need information from the codebase (e.g., to understand existing logic, identify relevant files, assess current state, list directory structures), you MUST instruct the user to ask Jules to perform these actions and relay the complete output back to you. + **Leveraging Jules and User for Codebase Interaction:** + You do NOT have direct access to the user's codebase. Google Jules DOES. You also have the user who can directly inspect code. - **Formatting Instructions for Jules:** - When you need Jules to perform a task, clearly state this. For example: - * "To understand the current structure, please ask Jules to: `ls('src/components/')`" - * "To verify the existing function signature, please ask Jules to read the file `src/utils/auth.py` and look for the `authenticate_user` function." - * "To assess the impact of this change, please ask Jules to grep for all occurrences of `OLD_API_ENDPOINT` in the codebase." + **Information Gathering Strategy (to conserve Jules' daily task limits):** + 1. **For Extensive Analysis/Multiple Files:** If you need a comprehensive report, analysis of multiple files, or complex data extracted from the codebase, instruct the user to ask Jules to perform the necessary actions (e.g., `read_files`, `ls`, `grep`) and then consolidate this information into a new markdown report file. Specify the filename and location, e.g., `docs/jules_reports/report_YYYYMMDD_HHMMSS_task_description.md`. The user will then confirm to you once Jules has created the report, and you can then ask the user to provide you with the content of that report. + * Example: "To analyze the current authentication flow, please ask Jules to read `auth/views.py`, `auth/forms.py`, and `users/models.py`, and then create a report named `docs/jules_reports/auth_flow_analysis_YYYYMMDD.md` summarizing the key functions, models, and their interactions. Once done, please provide me with the content of that report." + + 2. **For Simple Queries (1-2 files or quick checks):** If you only need the content of one or two specific files, or a very simple check, you can ask the user to provide this information directly. The user can copy-paste the content or describe the finding. + * Example: "Please provide the content of `src/utils/helpers.py`." + * Example: "Can you quickly check if the `DEBUG` flag is set to `True` in `settings.py` and tell me?" + + 3. **Relaying Information:** In both cases, the user is responsible for relaying the requested information (either the content of the Jules-generated report or the direct information) back to you. Ensure you receive the *complete* relevant output. + + **Formatting Instructions for Jules (when Jules is involved):** + When you need Jules to perform a task (either for direct output or for report generation), clearly state this. For example: + * "To understand the current structure (for report generation), please ask Jules to: `ls('src/components/')`" + * "To verify the existing function signature (for direct user feedback), please ask Jules to read the file `src/utils/auth.py` and look for the `authenticate_user` function. Then, tell me what you find." **Plan Output Format for Jules:** The final plan you generate for Jules MUST be structured as a series of numbered steps. Each step should be actionable and clear. Use Markdown for formatting. If a step involves code changes, provide the file path and use git-flavored diffs or specify exactly what code to add/modify. @@ -49,16 +58,16 @@ This BMad Gem will be your primary interface for planning and generating the exe Ask Jules: `read_files(['README.md'])` 2. *Create a new file `src/new_module.py` with the following content:* Ask Jules: - *** + ``` create_file_with_block src/new_module.py # Initial content for new_module.py def hello_world(): print("Hello from new_module!") - *** + ``` 3. *Modify the `main.py` file to import and call the new function.* Ask Jules: - *** + ``` replace_with_git_merge_diff main.py <<<<<<< SEARCH @@ -67,8 +76,8 @@ This BMad Gem will be your primary interface for planning and generating the exe # End of current imports from src.new_module import hello_world >>>>>>> REPLACE - *** - *** + ``` + ``` replace_with_git_merge_diff main.py <<<<<<< SEARCH @@ -79,24 +88,24 @@ This BMad Gem will be your primary interface for planning and generating the exe print("Starting application...") hello_world() >>>>>>> REPLACE - *** + ``` 4. *Install necessary dependencies.* Ask Jules: - *** + ``` run_in_bash_session pip install flask-jwt-extended - *** + ``` - **Interaction Flow:** - 1. The user will present a high-level goal (e.g., "Implement user authentication"). - 2. You will use the BMad agents (PM, Architect, Analyst, etc.) to break this down, ask clarifying questions, and formulate a strategy. - 3. If codebase information is needed, explicitly instruct the user to get it via Jules. The user will then paste Jules' complete output back to you. + **Interaction Flow (General):** + 1. The user will present a high-level goal. + 2. You will use the BMad agent personas (PM, Architect, Analyst, etc.) from your base instructions to break this down, ask clarifying questions, and formulate a strategy. + 3. If codebase information is needed, use the "Information Gathering Strategy" above. The user will then provide the requested information (either directly or by relaying a Jules-generated report). 4. Iterate on the plan based on new information. 5. Once the plan is robust, provide the complete, numbered, Jules-executable plan. **Emphasis on Jules' Role:** - Remember, Jules is the "hands" that interact with the code. Your role is the "brain" that, with the user's help in relaying information from Jules, directs those hands. Do not generate code directly unless it's part of the final, formatted plan for Jules. Focus on high-level design, task breakdown, and instructing Jules. - *** + Remember, Jules is the "hands" that interact with the code when complex operations or file manipulations are needed. Your role is the "brain" that, with the user's help in relaying information, directs those hands. For simple information retrieval, the user can act as your direct informant. Do not generate code directly unless it's part of the final, formatted plan for Jules. Focus on high-level design, task breakdown, and instructing Jules or the user. + ``` 4. **Save the Gem.** @@ -104,86 +113,86 @@ This BMad Gem will be your primary interface for planning and generating the exe For projects starting from scratch. -1. **Initiate Planning with the BMad Gem**: - * Open your configured BMad Gem. +1. **Initiate Planning with the JMAD Gem**: + * Open your configured JMAD Gem. * Start with a high-level project description. Example: `"We are starting a new Python Flask application for a blog. It needs user registration, login, post creation, and post viewing. Guide me through planning and generate a Jules execution plan."` - * The Gem will likely activate the PM and Architect agents. + * The Gem will likely activate its PM and Architect personas. 2. **Collaborative Planning & Design**: - * Engage with the Gem's agents (PM, Architect, UX Expert, etc.) to define requirements (PRD), system architecture, and user stories. - * The Gem will guide you through creating necessary documents (conceptually, as it doesn't save files itself). The key output is the *Jules plan*. + * Engage with the Gem's personas (PM, Architect, UX Expert, etc.) to define requirements (PRD), system architecture, and user stories. + * The Gem will guide you through creating necessary documents (conceptually). The key output is the *Jules plan*. 3. **Leverage Jules for Setup Diagnostics (if needed)**: * Although greenfield, you might have questions about the initial environment or want to set up a specific structure. - * Example: If the Gem suggests a directory structure, you might ask Jules to create it or verify parts of it. - * BMad Gem: `"Let's start with a standard Flask structure. User, please ask Jules to create the following directories using appropriate commands: 'app/', 'app/templates/', 'app/static/', 'tests/'."` (Jules would then need specific `create_file_with_block` or `run_in_bash_session mkdir` commands for this). + * Example: If the Gem suggests a directory structure: + * JMAD Gem: `"Let's start with a standard Flask structure. User, please ask Jules to create the following directories using appropriate commands: 'app/', 'app/templates/', 'app/static/', 'tests/'."` (Jules would then need specific `create_file_with_block` or `run_in_bash_session mkdir` commands for this). 4. **Iterative Plan Generation**: * The Gem will break down the project into epics and stories. For each, it will generate a detailed plan. - * The Gem will ask clarifying questions. If information about the (emerging) codebase is needed, it will instruct you to query Jules and for you to relay the output. + * The Gem will ask clarifying questions. If information about the (emerging) codebase is needed, it will instruct you according to the "Information Gathering Strategy" (e.g., ask user directly for simple file content, or ask user to have Jules generate a report for more complex states). 5. **Receive the Jules Execution Plan**: - * Once a significant chunk of planning is done (e.g., for an initial epic or a set of core stories), the BMad Gem will provide a numbered, step-by-step plan formatted for Jules. + * Once a significant chunk of planning is done (e.g., for an initial epic or a set of core stories), the JMAD Gem will provide a numbered, step-by-step plan formatted for Jules. 6. **Execute with Jules**: - * Take the plan generated by the BMad Gem. + * Take the plan generated by the JMAD Gem. * In your Jules interface, provide the instructions step-by-step or in logical chunks. * Provide feedback to Jules if steps fail or need adjustment. 7. **Feedback Loop (Optional but Recommended)**: - * If Jules encounters issues or if the execution reveals flaws in the plan, take this feedback (including any error messages from Jules) back to the BMad Gem. + * If Jules encounters issues or if the execution reveals flaws in the plan, take this feedback (including any error messages from Jules) back to the JMAD Gem. * Example: `"Jules had an issue with step 4 because library X was not installed. The error was 'ModuleNotFoundError: No module named X'. Can we update the plan to include installing library X?"` - * The BMad Gem will then revise the plan. + * The JMAD Gem will then revise the plan. ## III. JMAD Workflow: Brownfield Projects For working on existing codebases. -1. **Initiate Planning with the BMad Gem**: - * Open your configured BMad Gem. +1. **Initiate Planning with the JMAD Gem**: + * Open your configured JMAD Gem. * Clearly state the goal and that it's a brownfield project. Provide context. Example: `"We need to add a two-factor authentication feature to our existing Django e-commerce site. The user model is in 'users/models.py'. I need a plan for Jules to implement this."` 2. **Initial Codebase Analysis (Crucial Step)**: - * The BMad Gem (likely using the Analyst or Architect persona) will immediately recognize the need to understand the existing codebase. - * **This is where Jules is first heavily involved.** - * BMad Gem: `"To start, I need to understand your current authentication setup and user model. Please ask Jules to provide the content of the following files: 'users/models.py', 'settings.py' (especially the AUTHENTICATION_BACKENDS and MIDDLEWARE sections), and any relevant files from your main authentication app (e.g., 'auth/views.py', 'auth/urls.py'). Also, ask Jules to list the directory structure of your authentication app: ls('auth/')`" - * You: Copy these requests to Jules. - * Jules: Executes the `read_files` and `ls` commands. - * You: Paste Jules' **complete output** back into the BMad Gem for analysis. + * The JMAD Gem (likely using its Analyst or Architect persona) will immediately recognize the need to understand the existing codebase. + * **This is where Jules and/or direct user input are first heavily involved.** + * JMAD Gem Example (requesting a Jules report): `"To start, I need a comprehensive overview of your current authentication setup. Please ask Jules to read 'users/models.py', 'settings.py' (focus on AUTHENTICATION_BACKENDS, MIDDLEWARE), relevant files in 'auth/' (like views, urls), and then generate a report at 'docs/jules_reports/initial_auth_analysis_YYYYMMDD.md' summarizing these. Then, provide me with the content of that report."` + * JMAD Gem Example (requesting direct user input for fewer files): `"To start, please provide me with the content of 'users/models.py' and the AUTHENTICATION_BACKENDS section from 'settings.py'."` + * You: Follow the Gem's instructions, using Jules or direct copy-pasting as appropriate. + * You: Relay the **complete requested information** back to the JMAD Gem for analysis. 3. **Iterative Analysis and Planning**: - * The BMad Gem will analyze the provided code and information. - * It will ask further questions, requiring more interaction with Jules. Examples: - * BMad Gem: `"Thanks. Now, please ask Jules to search for all usages of the 'login' function: grep('def login\(request')."` - * BMad Gem: `"What are the fields in the current UserProfile model? Ask Jules to show the class definition from 'users/models.py'."` - * This cycle of the BMad Gem requesting information, you using Jules to get it, and you feeding the **complete output** back to the Gem is key for brownfield projects. + * The JMAD Gem will analyze the provided information. + * It will ask further questions, again using the "Information Gathering Strategy." Examples: + * JMAD Gem (direct query): `"Thanks. Can you quickly grep for all usages of the 'login' function in your auth app and tell me the file and line numbers?"` + * JMAD Gem (Jules report): `"To understand the data flow, please ask Jules to trace calls to 'process_payment' and generate a sequence diagram in 'docs/jules_reports/payment_flow_YYYYMMDD.md'. Then, provide the report content."` + * This cycle of the JMAD Gem requesting information, and you providing it (via Jules-generated reports or directly), is key. 4. **Impact Assessment and Design**: - * Using the codebase information (via Jules), the BMad Gem's Architect and Dev personas will design the new feature, considering integration points, potential conflicts, and necessary refactoring. - * BMad Gem: `"It seems we'll need to modify the User model to add a TOTP secret field. Ask Jules to show the current User model again so I can formulate the exact change."` + * Using the codebase information, the JMAD Gem's Architect and Dev personas will design the new feature. + * JMAD Gem: `"Based on the report, it seems we'll need to modify the User model. To confirm, please provide the exact current User model definition from 'users/models.py'."` 5. **Receive the Jules Execution Plan**: - * Once the analysis and design are robust, the BMad Gem will provide a detailed, step-by-step plan formatted for Jules. This plan will include specific file modifications (using diffs or clear instructions), new file creations, and any necessary commands (e.g., database migrations, dependency installations). + * Once the analysis and design are robust, the JMAD Gem will provide a detailed, step-by-step plan formatted for Jules. 6. **Execute with Jules**: * Take the plan to Jules and execute it. - * The detailed nature of the plan, informed by actual codebase analysis, should lead to smoother execution. 7. **Feedback and Refinement**: - * As with greenfield projects, if Jules encounters issues, feed this **detailed feedback and any error messages** back to the BMad Gem for plan refinement. Brownfield projects may require more iteration due to unforeseen complexities in existing code. - * BMad Gem: `"Jules reported a circular dependency when adding the new import. The error was: 'ImportError: cannot import name X'. Let's re-evaluate the placement. Ask Jules to show the imports in 'users/models.py' and 'orders/models.py'."` + * As with greenfield projects, if Jules encounters issues, feed this **detailed feedback and any error messages** back to the JMAD Gem for plan refinement. + * JMAD Gem: `"Jules reported a circular dependency. The error was: 'ImportError: cannot import name X'. Let's re-evaluate. Ask Jules to generate a report of current imports in 'users/models.py' and 'orders/models.py' at 'docs/jules_reports/import_analysis_YYYYMMDD.md'. Then provide it to me."` ## IV. Key Principles for Effective JMAD -* **Clear Roles**: BMad Gem is the planner and strategist. Jules is the executor and codebase interactor. You are the vital human link relaying information. -* **Explicit Instructions for Jules**: The BMad Gem must be precise in what it needs Jules to do. The user must accurately convey these instructions to Jules. -* **Provide Full Context to Gem**: When relaying information from Jules back to the BMad Gem, provide the complete output from Jules, including any error messages or unexpected results. This ensures the Gem has the maximum possible context for its planning and decision-making. -* **Iterative Refinement**: Expect to go back and forth between the BMad Gem and Jules, especially in brownfield projects. Planning is not a one-shot activity; it evolves with new information. -* **Detailed Jules Plans**: The more detailed and precise the plan from the BMad Gem, the more effectively Jules can execute it. Encourage the Gem to be specific about file paths, function names, and exact code changes. -* **Leverage BMad Personas**: Encourage the Gem to switch between its internal BMad personas (PM, Architect, Dev, QA, etc.) as needed to get the best planning output. For example, after the Architect designs a solution, you might ask the QA persona to consider test cases, which then become part of Jules' plan. -* **User as Verifier**: Always review the plans generated by the BMad Gem before handing them to Jules. You have the ultimate understanding of your project and can catch potential issues or suggest improvements. +* **Clear Roles**: JMAD Gem is the planner/strategist. Jules is the executor/codebase interactor for complex tasks. You are the vital human link, information provider, and verifier. +* **Strategic Information Gathering**: The JMAD Gem should balance asking Jules to create reports (for complexity) with asking the user directly (for simplicity/speed and to manage Jules' limits). +* **Explicit Instructions**: The JMAD Gem must be precise. The user must accurately convey instructions and relay complete information. +* **Provide Full Context to Gem**: Whether it's a Jules-generated report or direct info, provide the JMAD Gem with complete and accurate data. +* **Iterative Refinement**: Planning evolves. Expect back-and-forth. +* **Detailed Jules Plans**: Specific plans from the JMAD Gem lead to better Jules execution. +* **Leverage BMad Personas**: Encourage the Gem to use its BMad-based personas (PM, Architect, etc.) for comprehensive planning. +* **User as Verifier**: Always review JMAD Gem plans before Jules executes them. -By following this JMAD workflow, you can harness the broad planning and multi-agent simulation capabilities of the BMad Gem and the direct code manipulation power of Jules for a highly effective AI-assisted development process. +By following this JMAD workflow, you can harness the broad planning capabilities of the JMAD Gem and the direct code manipulation power of Jules for a highly effective AI-assisted development process. ```