From 04972720d0f76e766186ecd9c5b88a2f21d428ec Mon Sep 17 00:00:00 2001 From: Brian Date: Thu, 5 Jun 2025 21:22:01 -0500 Subject: [PATCH] Task template standardization improvements (#163) create-doc-from-template used with create-prd template with new template with llm instruction standardization format. ide-web agent simplifications, removal of overlap, and agent name alignment advanced elicitation streamlined throughout creation of PRD --- bmad-agent/data/technical-preferences.md | 12 + bmad-agent/data/technical-preferences.txt | 6 - bmad-agent/ide-bmad-orchestrator.cfg.md | 41 +- bmad-agent/tasks/advanced-elicitation.md | 77 ++ bmad-agent/tasks/create-doc-from-template.md | 93 ++ bmad-agent/tasks/create-prd.md | 248 +--- bmad-agent/templates/prd-tmpl.md | 270 ++-- bmad-agent/templates/project-brief-tmpl.md | 2 +- bmad-agent/templates/template-format.md | 43 + bmad-agent/web-bmad-orchestrator-agent.cfg.md | 33 +- web-build-sample.md | 1 - web-build-sample/agent-config.txt | 47 +- web-build-sample/agent-prompt.txt | 20 +- web-build-sample/checklists.txt | 583 +++++++- web-build-sample/data.txt | 14 +- web-build-sample/personas.txt | 94 +- web-build-sample/tasks.txt | 1221 +++++++++++++---- web-build-sample/templates.txt | 482 +++++-- 18 files changed, 2496 insertions(+), 791 deletions(-) create mode 100644 bmad-agent/data/technical-preferences.md delete mode 100644 bmad-agent/data/technical-preferences.txt create mode 100644 bmad-agent/tasks/advanced-elicitation.md create mode 100644 bmad-agent/tasks/create-doc-from-template.md create mode 100644 bmad-agent/templates/template-format.md delete mode 100644 web-build-sample.md diff --git a/bmad-agent/data/technical-preferences.md b/bmad-agent/data/technical-preferences.md new file mode 100644 index 00000000..e7a19422 --- /dev/null +++ b/bmad-agent/data/technical-preferences.md @@ -0,0 +1,12 @@ +# User-Defined Preferred Patterns and Preferences + +List out your preferred: +- technical preferences +- design patterns +- languages +- framework +- etc... + +Anything you learn or prefer over time to drive future project choices, add them here. + +These will be used by the agents when producing PRD and Architectures diff --git a/bmad-agent/data/technical-preferences.txt b/bmad-agent/data/technical-preferences.txt deleted file mode 100644 index c06957c6..00000000 --- a/bmad-agent/data/technical-preferences.txt +++ /dev/null @@ -1,6 +0,0 @@ -# User-Defined Preferred Patterns and Preferences - -See example files in this folder. -list out your technical preferences, patterns you like to follow, language framework or starter project preferences. - -Anything you learn or prefer over time to drive future project choices, add the here. diff --git a/bmad-agent/ide-bmad-orchestrator.cfg.md b/bmad-agent/ide-bmad-orchestrator.cfg.md index 8b6d20d1..fc71c1fc 100644 --- a/bmad-agent/ide-bmad-orchestrator.cfg.md +++ b/bmad-agent/ide-bmad-orchestrator.cfg.md @@ -14,7 +14,7 @@ Example: If above cfg has `agent-root: root/foo/` and `tasks: (agent-root)/tasks ## Title: Analyst -- Name: Wendy +- Name: Mary - Customize: "" - Description: "Research assistant, brain storming coach, requirements gathering, project briefs." - Persona: "analyst.md" @@ -25,18 +25,19 @@ Example: If above cfg has `agent-root: root/foo/` and `tasks: (agent-root)/tasks ## Title: Product Manager (PM) -- Name: Bill +- Name: John - Customize: "" -- Description: "Jack has only one goal - to produce or maintain the best possible PRD - or discuss the product with you to ideate or plan current or future efforts related to the product." +- Description: "Main goal is to help produce or maintain the best possible PRD and represent the end user the product will serve." - Persona: "pm.md" - Tasks: - - [Create PRD](create-prd.md) + - [Create Document](tasks#create-doc-from-template): + - [Prd](templates#prd-tmpl) ## Title: Architect -- Name: Timmy +- Name: Fred - Customize: "" -- Description: "Generates Architecture, Can help plan a story, and will also help update PRD level epic and stories." +- Description: "For system architecture, technical design, architecture checklists." - Persona: "architect.md" - Tasks: - [Create Architecture](create-architecture.md) @@ -46,30 +47,34 @@ Example: If above cfg has `agent-root: root/foo/` and `tasks: (agent-root)/tasks ## Title: Design Architect -- Name: Karen +- Name: Jane - Customize: "" -- Description: "Help design a website or web application, produce prompts for UI GEneration AI's, and plan a full comprehensive front end architecture." +- Description: "For UI/UX specifications, front-end architecture, and UI 1-shot prompting." - Persona: "design-architect.md" - Tasks: - [Create Frontend Architecture](create-frontend-architecture.md) - [Create Next Story](create-ai-frontend-prompt.md) - [Slice Documents](create-uxui-spec.md) -## Title: Product Owner AKA PO +## Title: PO -- Name: Jimmy +- Name: Sarah - Customize: "" -- Description: "Jack of many trades, from PRD Generation and maintenance to the mid sprint Course Correct. Also able to draft masterful stories for the dev agent." +- Description: "Product Owner helps validate the artifacts are all cohesive with a master checklist, and also helps coach significant changes" - Persona: "po.md" -- Tasks: - - [Create PRD](create-prd.md) - - [Create Next Story](create-next-story-task.md) - - [Slice Documents](doc-sharding-task.md) - - [Correct Course](correct-course.md) +- checklists: + - [Po Master Checklist](checklists#po-master-checklist) + - [Change Checklist](checklists#change-checklist) +- templates: + - [Story Tmpl](templates#story-tmpl) +- tasks: + - [Checklist Run Task](tasks#checklist-run-task) + - [Extracts Epics and shards the Architecture](tasks#doc-sharding-task) + - [Correct Course](tasks#correct-course) ## Title: Frontend Dev -- Name: Rodney +- Name: Ellyn - Customize: "Specialized in NextJS, React, Typescript, HTML, Tailwind" - Description: "Master Front End Web Application Developer" - Persona: "dev.ide.md" @@ -94,7 +99,7 @@ Example: If above cfg has `agent-root: root/foo/` and `tasks: (agent-root)/tasks ## Title: Scrum Master: SM -- Name: Fran +- Name: Bob - Customize: "" - Description: "Specialized in Next Story Generation" - Persona: "sm.md" diff --git a/bmad-agent/tasks/advanced-elicitation.md b/bmad-agent/tasks/advanced-elicitation.md new file mode 100644 index 00000000..816a9dc3 --- /dev/null +++ b/bmad-agent/tasks/advanced-elicitation.md @@ -0,0 +1,77 @@ +# Advanced Elicitation Task + +## Purpose + +- Provide optional reflective and brainstorming actions to enhance content quality +- Enable deeper exploration of ideas through structured elicitation techniques +- Support iterative refinement through multiple analytical perspectives + +## Task Instructions + +### 1. Ask for review and Present Action List + +[[LLM: Ask the user to review the {drafted document section, or context or document this protocol was executed from}. In the SAME message, inform them that they can suggest additions, removals, or modifications, OR they can select an action by number from the 'Advanced Reflective, Elicitation & Brainstorming Actions'. Then, present ONLY the numbered list (0-9) of these actions as defined in tasks#advanced-elicitation. Conclude by stating that selecting 9 will proceed to the next section. Await user selection. If an elicitation action (0-8) is chosen, execute it and then re-offer this combined review/elicitation choice. If option 9 is chosen, or if the user provides direct feedback on requirements, proceed accordingly.]] + +**Present the numbered list (0-9) with this exact format:** + +``` +**Advanced Reflective, Elicitation & Brainstorming Actions** +Choose an action (0-9 - 9 to bypass - HELP for explanation of these options): + +0. Expand or Contract for Audience +1. Explain Reasoning (CoT Step-by-Step) +2. Critique and Refine +3. Analyze Logical Flow and Dependencies +4. Assess Alignment with Overall Goals +5. Identify Potential Risks and Unforeseen Issues +6. Challenge from Critical Perspective (Self or Other Persona) +7. Explore Diverse Alternatives (ToT-Inspired) +8. Hindsight is 20/20: The 'If Only...' Reflection +9. Proceed / No Further Actions +``` + +### 2. Processing Guidelines + +**Do NOT show:** + +- The full protocol text with `[[LLM: ...]]` instructions +- Detailed explanations of each option unless executing or the user asks, when giving the definition you can modify to tie its relevance +- Any internal template markup + +**After user selection from the list:** + +- Execute the chosen action according to the protocol instructions below +- Ask if they want to select another action or proceed with option 9 once complete +- Continue until user selects option 9 or indicates completion + +## Action Definitions + +0. Expand or Contract for Audience + [[LLM: Ask the user whether they want to 'expand' on the content (add more detail, elaborate) or 'contract' it (simplify, clarify, make more concise). Also, ask if there's a specific target audience they have in mind. Once clarified, perform the expansion or contraction from your current role's perspective, tailored to the specified audience if provided.]] + +1. Explain Reasoning (CoT Step-by-Step) + [[LLM: Explain the step-by-step thinking process, characteristic of your role, that you used to arrive at the current proposal for this content.]] + +2. Critique and Refine + [[LLM: From your current role's perspective, review your last output or the current section for flaws, inconsistencies, or areas for improvement, and then suggest a refined version reflecting your expertise.]] + +3. Analyze Logical Flow and Dependencies + [[LLM: From your role's standpoint, examine the content's structure for logical progression, internal consistency, and any relevant dependencies. Confirm if elements are presented in an effective order.]] + +4. Assess Alignment with Overall Goals + [[LLM: Evaluate how well the current content contributes to the stated overall goals of the document, interpreting this from your specific role's perspective and identifying any misalignments you perceive.]] + +5. Identify Potential Risks and Unforeseen Issues + [[LLM: Based on your role's expertise, brainstorm potential risks, overlooked edge cases, or unintended consequences related to the current content or proposal.]] + +6. Challenge from Critical Perspective (Self or Other Persona) + [[LLM: Adopt a critical perspective on the current content. If the user specifies another role or persona (e.g., 'as a customer', 'as [Another Persona Name]'), critique the content or play devil's advocate from that specified viewpoint. If no other role is specified, play devil's advocate from your own current persona's viewpoint, arguing against the proposal or current content and highlighting weaknesses or counterarguments specific to your concerns. This can also randomly include YAGNI when appropriate, such as when trimming the scope of an MVP, the perspective might challenge the need for something to cut MVP scope.]] + +7. Explore Diverse Alternatives (ToT-Inspired) + [[LLM: From your role's perspective, first broadly brainstorm a range of diverse approaches or solutions to the current topic. Then, from this wider exploration, select and present 2 distinct alternatives, detailing the pros, cons, and potential implications you foresee for each.]] + +8. Hindsight is 20/20: The 'If Only...' Reflection + [[LLM: In your current persona, imagine it's a retrospective for a project based on the current content. What's the one 'if only we had known/done X...' that your role would humorously or dramatically highlight, along with the imagined consequences?]] + +9. Proceed / No Further Actions + [[LLM: Acknowledge the user's choice to finalize the current work, accept the AI's last output as is, or move on to the next step without selecting another action from this list. Prepare to proceed accordingly.]] diff --git a/bmad-agent/tasks/create-doc-from-template.md b/bmad-agent/tasks/create-doc-from-template.md new file mode 100644 index 00000000..2ffe3f14 --- /dev/null +++ b/bmad-agent/tasks/create-doc-from-template.md @@ -0,0 +1,93 @@ +# Create Document from Template Task + +## Purpose + +- Generate documents from any specified template following embedded instructions +- Support multiple document types through template-driven approach +- Enable any persona to create consistent, well-structured documents + +## Instructions + +### 1. Identify Template and Context + +- Determine which template to use (user-provided or list available for selection to user) + + - agent-config specific agents will list what docs they have available under this task, for each item consider it a unique task. So if the user had for example: + + @{example} + + - tasks: + + - [Create Document](tasks#create-doc-from-template): + + - [Prd](templates#prd-tmpl) + + - [Architecture](templates#architecture-tmpl) + + @{/example} + + you would list `Create Document PRD` and `Create Document Architecture` as tasks the agent could perform. + +- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document +- Understand the document purpose and target audience + +### 2. Determine Interaction Mode + +Confirm with the user their preferred interaction style: + +- **Incremental:** Work through chunks of the document. +- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo) + +### 3. Execute Template + +- Load specified template from `templates#*` or the /templates directory +- Follow ALL embedded LLM instructions within the template +- Process template markup according to `templates#template-format` conventions + +### 4. Template Processing Rules + +**CRITICAL: Never display template markup, LLM instructions, or examples to users** + +- Replace all {{placeholders}} with actual content +- Execute all [[LLM: instructions]] internally +- Process <> sections as needed +- Evaluate ^^CONDITION^^ blocks and include only if applicable +- Use @{examples} for guidance but never output them + +### 5. Content Generation + +- **Incremental Mode**: Present each major section for review before proceeding +- **YOLO Mode**: Generate all sections, then review complete document with user +- Apply any elicitation protocols specified in template +- Incorporate user feedback and iterate as needed + +### 6. Validation + +If template specifies a checklist: + +- Run the appropriate checklist against completed document +- Document completion status for each item +- Address any deficiencies found +- Present validation summary to user + +### 7. Final Presentation + +- Present clean, formatted content only +- Ensure all sections are complete +- DO NOT truncate or summarize content +- Begin directly with document content (no preamble) +- Include any handoff prompts specified in template + +## Key Resources + +- **Template Format:** `templates#template-format` +- **Available Templates:** All files in `templates#` directory +- **Checklists:** As specified by template or persona +- **User Preferences:** `data#technical-preferences` + +## Important Notes + +- This task is template and persona agnostic +- All specific instructions are embedded in templates +- Focus on faithful template execution and clean output +- Template markup is for AI processing only - never expose to users diff --git a/bmad-agent/tasks/create-prd.md b/bmad-agent/tasks/create-prd.md index 5bfd85a2..bff169e0 100644 --- a/bmad-agent/tasks/create-prd.md +++ b/bmad-agent/tasks/create-prd.md @@ -2,228 +2,88 @@ ## Purpose -- Transform inputs into core product definition documents conforming to the `prd-tmpl` template. -- Define clear MVP scope focused on essential functionality. -- Provide foundation for Architect and eventually AI dev agents. - -Remember as you follow the upcoming instructions: - -- Your documents form the foundation for the entire development process. -- Output will be directly used by the Architect to create an architecture document and solution designs to make definitive technical decisions. -- Your epics/stories will ultimately be transformed into development tasks. -- While you focus on the "what" not "how", be precise enough to support a logical sequential order of operations that once later further details can logically be followed where a story will complete what is needed. +- Transform inputs into core product definition documents conforming to a PRD template +- Define clear MVP scope focused on essential functionality +- Provide foundation for Architect and Design Architect to help create technical artifacts which will in turn later draft further details for very junior engineers or simple dev ai agents. ## Instructions -### 1. Define Project Workflow Context +### 1. Review Inputs -- Before PRD generation, ask the user to choose their intended workflow: +Review all provided inputs including project brief, research documents, prd template and user ideas to guide PRD generation. - A. **Outcome Focused (Default):** (Agent defines outcome-focused User Stories, leaving detailed technical "how" for Architect/Scrum Master. Capture nuances as "Notes for Architect/Scrum Master in the Prompt for Architect.") +### 2. Determine Interaction Mode - B. **Very Technical (Not Recommended):** (Agent adopts a "solution-aware" stance, providing more detailed, implementation-aware Acceptance Criteria to bridge to development, potentially with no architect involved at all, instead filling in all of the technical details. \When this workflow is selected, you are also responsible for collaboratively defining and documenting key technical foundations—such as technology stack choices and proposed application structure—directly within a new, dedicated section of the PRD template titled '[OPTIONAL: For Simplified PM-to-Development Workflow Only] Core Technical Decisions & Application Structure'.\) +Confirm with the user their preferred interaction style: -- Explain this choice sets a default detail level, which can be fine-tuned later per story/epic. +- **Incremental:** Work through sections one at a time via chat messages as defined in the template. -### 2. Determine Interaction Mode (for PRD Structure & Detail) +- **YOLO Mode:** Draft the complete PRD making assumptions as necessary. Present full document at once, noting which sections required assumptions. -- Confirm with the user their preferred interaction style for creating the PRD if unknown - INCREMENTAL or YOLO?: - - **Incrementally (Default):** Address PRD sections sequentially, seeking feedback on each. For Epics/Stories: first present the ordered Epic list for approval, then detail stories for each Epic one by one. - - **"YOLO" Mode:** Draft a more comprehensive PRD (or significant portions with multiple sections, epics, and stories) for a single, larger review. +### 3. Execute Template -### 3. Review inputs provided +- Use the `prd-tmpl` template (or user-specified alternative template) +- Follow all embedded LLM instructions within the template +- Template contains section-specific guidance and examples -Review the inputs provided so far, such as a project brief, any research, and user input and ideas. +### 4. Template Processing Notes -### 4. Process PRD Sections +- **Incremental Mode**: Present each section for review before proceeding +- **YOLO Mode**: Generate all sections, then review with user -Inform the user we will work through the PRD sections in order 1 at a time (if not YOLO) - the template contains your instructions for each section. After presenting the section to the user, also [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) +Process all template elements according to `templates#template-format` conventions. -When working on the "Technical Assumptions" section of the PRD, explicitly guide the user through discussing and deciding on the repository structure (Monorepo vs. Polyrepo) and the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo). Emphasize that this is a critical decision point that will be formally documented here with its rationale, impacting MVP scope and informing the Architect. Ensure this decision is captured in the PRD's `Technical Assumptions` and then reiterated in the `Initial Architect Prompt` section of the PRD. +**CRITICAL: Never display or output template markup formatting, LLM instructions or examples - they MUST be used by you the agent only, AND NEVER shown to users in chat or document output** -Specifically for "Simplified PM-to-Development Workflow": -After discussing initial PRD sections (like Problem, Goals, User Personas) and before or in parallel with defining detailed Epics and Stories, you must introduce and populate the "[OPTIONAL: For Simplified PM-to-Development Workflow Only] Core Technical Decisions & Application Structure" section of the PRD. +**Content Presentation Guidelines:** - When doing so, first check if a `docs/technical-preferences.md` file exists or has been provided. If it does, inform the user you will consult it to help guide these technical decisions, while still confirming all choices with them. Ask targeted questions such as: +- Present only the final, clean content to users +- Replace template variables with actual project-specific content +- Process all conditional logic internally - show only relevant sections +- For Canvas mode: Update the document with clean, formatted content only -1. "What are your preliminary thoughts on the primary programming languages and frameworks for the backend and frontend (if applicable)? (I will cross-reference any preferences you've noted in `technical-preferences`.)" -2. "Which database system are you considering? (Checking preferences...)" -3. "Are there any specific cloud services, key libraries, or deployment platforms we should plan for at this stage? (Checking preferences...)" -4. "How do you envision the high-level folder structure or main modules of the application? Could you describe the key components and their responsibilities? (I'll consider any structural preferences noted.)" -5. "Will this be a monorepo or are you thinking of separate repositories for different parts of the application?" - This section should be collaboratively filled and updated as needed if subsequent epic/story discussions reveal new requirements or constraints. +### 7. Prepare Handoffs - +Based on PRD content, prepare appropriate next-step prompts: - +**If UI Component Exists:** -For the Epic and Story Section (if in Incremental mode for these), prepare in memory what you think the initial epic and story list so we can work through this incrementally, use all of the information you have learned that has been provided thus far to follow the guidelines in the section below [Guiding Principles for Epic and User Story Generation](https://www.google.com/search?q=%23guiding-principles-for-epic-and-user-story-generation). +1. Add Design Architect prompt in designated template section +2. Recommend: User engages Design Architect first for UI/UX Specification +3. Then proceed to Architect with enriched PRD - +**If No UI Component:** -#### 4A. Epic Presentation and Drafting Strategy +- Add Architect prompt in designated template section +- Recommend proceeding directly to Architect -You will first present the user with the epic titles and descriptions, so that the user can determine if it is correct and what is expected, or if there is a major epic missing. +### 8. Validate with Checklist -#### 4B. Story Generation and Review within Epics (Incremental Mode) +- Run the `pm-checklist` against completed PRD +- Document completion status for each checklist item +- Present summary by section, address any deficiencies +- Generate final checklist report with findings and resolutions -**Once the Epic List is approved, THEN for each Epic, you will proceed as follows:** +### 9. Final Presentation -i. **Draft All Stories for the Current Epic:** Based on the Epic's goal and your discussions, draft all the necessary User Stories for this Epic, following the "Guiding Principles for Epic and User Story Generation". -ii. **Perform Internal Story Analysis & Propose Order:** Before presenting the stories for detailed review, you will internally: -a. **Re-evaluate for Cross-Cutting Concerns:** Ensure no drafted stories should actually be ACs or notes within other stories, as per the guiding principle. Make necessary adjustments. -b. **Analyze for Logical Sequence & Dependencies:** For all stories within this Epic, determine their logical implementation order. Identify any direct prerequisite stories (e.g., "Story X must be completed before Story Y because Y consumes the output of X"). -c. **Formulate a Rationale for the Order:** Prepare a brief explanation for why the proposed order is logical. -iii. **Present Proposed Story Set & Order for the Epic:** Present to the user: -a. The complete list of (potentially revised) User Stories for the Epic. -b. The proposed sequence for these stories. -c. Your brief rationale for the sequencing and any key dependencies you've noted (e.g., "I suggest this order because Story 2 builds upon the data prepared in Story 1, and Story 3 then uses the results from Story 2."). -iv. **Collaborative Review of Sequence & Story Shells:** Discuss this proposed structure and sequence with the user. Make any adjustments to the story list or their order based on user feedback. -v. Once the overall structure and sequence of stories for the Epic are agreed upon, THEN you will work with the user to review the details (description, Acceptance Criteria) of each story in the agreed-upon sequence for that Epic. -vi. [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) +**General Guidelines:** -#### 4C. Present Complete Draft +- Present complete documents in clean, full format +- DO NOT truncate unchanged information +- Begin directly with content (no introductory text needed) +- Ensure all template sections are properly filled +- **NEVER show template markup, instructions, or processing directives to users** -Present the user with the complete full draft once all sections are completed (or as per YOLO mode interaction). +## Key Resources -#### 4D. UI Component Handoff Note +- **Default Template:** `templates#prd-tmpl` +- **Validation:** `checklists#pm-checklist` +- **User Preferences:** `data#technical-preferences` +- **Elicitation Protocol:** `tasks#advanced-elicitation` -If there is a UI component to this PRD, you can inform the user that the Design Architect should take this final output. +## Important Notes -### 5\. Checklist Assessment - -- Use the `pm-checklist` to consider each item in the checklist is met (or n/a) against the PRD. -- Document completion status for each item. -- Present the user with summary of each section of the checklist before going to the next section. -- Address deficiencies with user for input or suggested updates or corrections. -- Once complete and address, output the final checklist with all the checked items or skipped items, the section summary table, and any final notes. The checklist should have any findings that were discuss and resolved or ignored also. This will be a nice artifact for the user to keep. - -### 6\. Produce the PRD - -Produce the PRD with PM Prompt per the `prd-tmpl` utilizing the following guidance: - -**General Presentation & Content:** - -- Present Project Briefs (drafts or final) in a clean, full format. -- Crucially, DO NOT truncate information that has not changed from a previous version. -- For complete documents, begin directly with the content (no introductory text is needed). - - -**Next Steps for UI/UX Specification (If Applicable):** - -- If the product described in this PRD includes a user interface: - - 1. **Include Design Architect Prompt in PRD:** You will add a dedicated section in the PRD document you are producing, specifically at the location marked `(END Checklist START Design Architect UI/UX Specification Mode Prompt)` (as per the `prd-tmpl` structure). This section will contain a prompt for the **Design Architect** agent. - - - The prompt should clearly state that the Design Architect is to operate in its **'UI/UX Specification Mode'**. - - - It should instruct the Design Architect to use this PRD as primary input to collaboratively define and document detailed UI/UX specifications. This might involve creating/populating a `front-end-spec-tmpl` and ensuring key UI/UX considerations are integrated or referenced back into the PRD to enrich it. - - - Example prompt text to insert: - - ```markdown - ## Prompt for Design Architect (UI/UX Specification Mode) - - **Objective:** Elaborate on the UI/UX aspects of the product defined in this PRD. - **Mode:** UI/UX Specification Mode - **Input:** This completed PRD document. - **Key Tasks:** - - 1. Review the product goals, user stories, and any UI-related notes herein. - 2. Collaboratively define detailed user flows, wire-frames (conceptual), and key screen mockups/descriptions. - 3. Specify usability requirements and accessibility considerations. - 4. Populate or create the `front-end-spec-tmpl` document. - 5. Ensure that this PRD is updated or clearly references the detailed UI/UX specifications derived from your work, so that it provides a comprehensive foundation for subsequent architecture and development phases. - - Please guide the user through this process to enrich the PRD with detailed UI/UX specifications. - ``` - - 2. **Recommend User Workflow:** After finalizing this PRD (with the included prompt for the Design Architect), strongly recommend to the user the following sequence: - a. First, engage the **Design Architect** agent (using the prompt you've embedded in the PRD) to operate in **'UI/UX Specification Mode'**. Explain that this step is crucial for detailing the user interface and experience, and the output (e.g., a populated `front-end-spec-tmpl` and potentially updated PRD sections) will be vital. - b. Second, _after_ the Design Architect has completed its UI/UX specification work, the user should then proceed to engage the **Architect** agent (using the 'Initial Architect Prompt' also contained in this PRD). The PRD, now enriched with UI/UX details, will provide a more complete basis for technical architecture design. - -- If the product does not include a user interface, you will simply recommend proceeding to the Architect agent using the 'Initial Architect Prompt' in the PRD. - - -## Guiding Principles for Epic and User Story Generation - -### I. Strategic Foundation: Define Core Value & MVP Scope Rigorously - -Understand & Clarify Core Needs: Start by deeply understanding and clarifying the core problem this product solves, the essential needs of the defined User Personas (or system actors), and the key business objectives for the Minimum Viable Product (MVP). -Challenge Scope Relentlessly: Actively challenge all requested features and scope at every stage. For each potential feature or story, rigorously ask, "Does this directly support the core MVP goals and provide significant value to a target User Persona?" Clearly identify and defer non-essential functionalities to a Post-MVP backlog. - -### II. Structuring the Work: Value-Driven Epics & Logical Sequencing - -Organize into Deployable, Value-Driven Epics: Structure the MVP scope into Epics. Each Epic must be designed to deliver a significant, end-to-end, and fully deployable increment of testable functionality that provides tangible value to the user or business. Epics should represent logical functional blocks or coherent user journeys. - -Logical Epic Sequencing & Foundational Work: -Ensure the sequence of Epics follows a logical implementation order, making dependencies between Epics clear and explicitly managed. -The first Epic must always establish the foundational project infrastructure (e.g., initial app setup, Git repository, CI/CD pipeline, core cloud service configurations, basic user authentication shell if needed universally) necessary to support its own deployable functionality and that of subsequent Epics. -Ensure Logical Story Sequencing and Dependency Awareness within Epics: -After initially drafting all User Stories for an Epic, but before detailed review with the user, you (the AI Agent executing this task) must explicitly perform an internal review to establish a logical sequence for these stories. -For each story, identify if it has direct prerequisite stories within the same Epic or from already completed Epics. -Propose a clear story order to the user, explaining the rationale based on these dependencies (e.g., "Story X needs to be done before Story Y because..."). Make significant dependencies visible, perhaps as a note within the story description. - -### III. Crafting Effective User Stories: Vertical Slices Focused on Value & Clarity - -Define Stories as "Vertical Slices": Within each Epic, define User Stories as "vertical slices". This means each story must deliver a complete piece of functionality that achieves a specific user or system goal, potentially cutting through all necessary layers (e.g., UI, API, business logic, database). -Focus on "What" and "Why," Not "How": -Stories will primarily focus on the functional outcome, the user value ("what"), and the reason ("why"). Avoid detailing technical implementation ("how") in the story's main description. -The "As a {specific User Persona/system actor}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}" format is standard. Be precise and consistent when defining the '{specific User Persona/system actor}', ensuring it aligns with defined personas. -Ensure User Value, Not Just Technical Tasks: User Stories must articulate clear user or business value. Avoid creating stories that are purely technical tasks (e.g., "Set up database," "Refactor module X"), unless they are part of the foundational infrastructure Epic or are essential enabling tasks that are explicitly linked to, and justified by, a user-facing story that delivers value. -Appropriate Sizing & Strive for Independence: -Ensure User Stories are appropriately sized for a typical development iteration (i.e., can be completed by the team in one sprint/iteration). -If a vertically sliced story is too large or complex, work with the user to split it into smaller, still valuable, and still vertically sliced increments. -Where feasible, define stories so they can be developed, tested, and potentially delivered independently of others. If dependencies are unavoidable, they must be clearly identified and managed through sequencing. - -### IV. Detailing Stories: Comprehensive Acceptance Criteria & Developer Enablement - -Clear, Comprehensive, and Testable Acceptance Criteria (ACs): -Every User Story will have detailed, unambiguous, and testable Acceptance Criteria. -ACs precisely define what "done" means for that story from a functional perspective and serve as the basis for verification. -Where a specific Non-Functional Requirement (NFR) from the PRD (e.g., a particular performance target for a specific action, a security constraint for handling certain data) is critical to a story, ensure it is explicitly captured or clearly referenced within its Acceptance Criteria. -Integrate Developer Enablement & Iterative Design into Stories: -Local Testability (CLI): For User Stories involving backend processing or data components, ensure the ACs consider or specify the ability for developers to test that functionality locally (e.g., via CLI commands, local service instances). -Iterative Schema Definition: Database schema changes (new tables, columns) should be introduced iteratively within the User Stories that functionally require them, rather than defining the entire schema upfront. -Upfront UI/UX Standards (if UI applicable): For User Stories with a UI component, ACs should explicitly state requirements regarding look and feel, responsiveness, and adherence to chosen frameworks/libraries (e.g., Tailwind CSS, shadcn/ui) from the start. - -### V. Managing Complexity: Addressing Cross-Cutting Concerns Effectively - -Critically Evaluate for Cross-Cutting Concerns: -Before finalizing a User Story, evaluate if the described functionality is truly a discrete, user-facing piece of value or if it represents a cross-cutting concern (e.g., a specific logging requirement, a UI theme element used by many views, a core technical enabler for multiple other stories, a specific aspect of error handling). -If a piece of functionality is identified as a cross-cutting concern: -a. Avoid creating a separate User Story for it unless it delivers standalone, testable user value. -b. Instead, integrate the requirement as specific Acceptance Criteria within all relevant User Stories it impacts. -c. Alternatively, if it's a pervasive technical enabler or a non-functional requirement that applies broadly, document it clearly within the relevant PRD section (e.g., 'Non Functional Requirements', 'Technical Assumptions'), or as a note for the Architect within the story descriptions if highly specific. - -Your aim is to ensure User Stories remain focused on delivering measurable user value, while still capturing all necessary technical and functional details appropriately. - -### VI. Ensuring Quality & Smooth Handoff - -Maintain Clarity for Handoff and Architectural Freedom: User Stories, their descriptions, and Acceptance Criteria must be detailed enough to provide the Architect with a clear and comprehensive understanding of "what is required," while allowing for architectural flexibility on the "how." -Confirm "Ready" State: Before considering an Epic's stories complete, ensure each story is effectively "ready" for subsequent architectural review or development planning – meaning it's clear, understandable, testable, its dependencies are noted, and any foundational work (like from the first epic) is accounted for. - -## Offer Advanced Self-Refinement & Elicitation Options - -(This section is called when needed prior to this) - -Present the user with the following list of 'Advanced Reflective, Elicitation & Brainstorming Actions'. Explain that these are optional steps to help ensure quality, explore alternatives, and deepen the understanding of the current section before finalizing it and moving on. The user can select an action by number, or choose to skip this and proceed to finalize the section. - -"To ensure the quality of the current section: **[Specific Section Name]** and to ensure its robustness, explore alternatives, and consider all angles, I can perform any of the following actions. Please choose a number (8 to finalize and proceed): - -**Advanced Reflective, Elicitation & Brainstorming Actions I Can Take:** - -{Instruction for AI Agent: Display the title of each numbered item below. If the user asks what a specific option means, provide a brief explanation of the action you will take, drawing from detailed descriptions tailored for the context.} - -1. **Critical Self-Review & User Goal Alignment** -2. **Generate & Evaluate Alternative Design Solutions** -3. **User Journey & Interaction Stress Test (Conceptual)** -4. **Deep Dive into Design Assumptions & Constraints** -5. **Usability & Accessibility Audit Review & Probing Questions** -6. **Collaborative Ideation & UI Feature Brainstorming** -7. **Elicit 'Unforeseen User Needs' & Future Interaction Questions** -8. **Finalize this Section and Proceed.** - -After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section." - -REPEAT by Asking the user if they would like to perform another Reflective, Elicitation & Brainstorming Action UNIT the user indicates it is time to proceed ot the next section (or selects #8) +- This task is template-agnostic - users may specify custom templates +- All detailed instructions are embedded in templates, not this task file +- Focus on orchestration and workflow +- **Template markup is for AI processing only - users should never see output indicators from templates#template-format** diff --git a/bmad-agent/templates/prd-tmpl.md b/bmad-agent/templates/prd-tmpl.md index 51cfd221..346ada22 100644 --- a/bmad-agent/templates/prd-tmpl.md +++ b/bmad-agent/templates/prd-tmpl.md @@ -1,113 +1,182 @@ -# {Project Name} Product Requirements Document (PRD) +# {{Project Name}} Product Requirements Document (PRD) -## Goal, Objective and Context +[[LLM: If available, review any provided document or ask if any are optionally available: Project Brief]] -This should come mostly from the user or the provided brief, but ask for clarifications as needed. +## Goals and Background Context -## Functional Requirements (MVP) +[[LLM: Populate the 2 child sections based on what we have received from user description or the provided brief. Allow user to review the 2 sections and offer changes before proceeding]] -You should have a good idea at this point, but clarify suggest question and explain to ensure these are correct. +### Goals -## Non Functional Requirements (MVP) +[[LLM: Bullet list of 1 line desired outcomes the PRD will deliver if successful - user and project desires]] -You should have a good idea at this point, but clarify suggest question and explain to ensure these are correct. +### Background Context -## User Interaction and Design Goals +[[LLM: 1-2 short paragraphs summarizing the background context, such as what we learned in the brief without being redundant with the goals, what and why this solves a problem, what the current landscape or need is etc...]] -{ -If the product includes a User Interface (UI), this section captures the Product Manager's high-level vision and goals for the User Experience (UX). This information will serve as a crucial starting point and brief for the Design Architect. +## Requirements -Consider and elicit information from the user regarding: +[[LLM: Draft the list of functional and non functional requirements under the two child sections, and immediately execute tasks#advanced-elicitation display]] -- **Overall Vision & Experience:** What is the desired look and feel (e.g., "modern and minimalist," "friendly and approachable," "data-intensive and professional")? What kind of experience should users have? -- **Key Interaction Paradigms:** Are there specific ways users will interact with core features (e.g., "drag-and-drop interface for X," "wizard-style setup for Y," "real-time dashboard for Z")? -- **Core Screens/Views (Conceptual):** From a product perspective, what are the most critical screens or views necessary to deliver the MVP's value? (e.g., "Login Screen," "Main Dashboard," "Item Detail Page," "Settings Page"). -- **Accessibility Aspirations:** Any known high-level accessibility goals (e.g., "must be usable by screen reader users"). -- **Branding Considerations (High-Level):** Any known branding elements or style guides that must be incorporated? -- **Target Devices/Platforms:** (e.g., "primarily web desktop," "mobile-first responsive web app"). +### Functional -This section is not intended to be a detailed UI specification but rather a product-focused brief to guide the subsequent detailed work by the Design Architect, who will create the comprehensive UI/UX Specification document. -} +[[LLM: Each Requirement will be a bullet markdown and an identifier sequence starting with FR`.]] +@{example: - FR6: The Todo List uses AI to detect and warn against adding potentially duplicate todo items that are worded differently.} + +### Non Functional + +[[LLM: Each Requirement will be a bullet markdown and an identifier sequence starting with NFR`.]] +@{example: - NFR1: AWS service usage **must** aim to stay within free-tier limits where feasible.} + +^^CONDITION: has_ui^^ + +## User Interface Design Goals + +[[LLM: Capture high-level UI/UX vision to guide Design Architect and to inform story creation. Steps: + +1. Pre-fill all subsections with educated guesses based on project context +2. Present the complete rendered section to user +3. Clearly let the user know where assumptions were made +4. Ask targeted questions for unclear/missing elements or areas needing more specification +5. This is NOT detailed UI spec - focus on product vision and user goals +6. After section completion, immediately apply `tasks#advanced-elicitation` protocol]] + +### Overall UX Vision + +### Key Interaction Paradigms + +### Core Screens and Views + +[[LLM: From a product perspective, what are the most critical screens or views necessary to deliver the the PRD values and goals? This is meant to be Conceptual High Level to Drive Rough Epic or User Stories]] + +@{example} + +- Login Screen +- Main Dashboard +- Item Detail Page +- Settings Page + @{/example} + +### Accessibility: { None, WCAG, etc } + +### Branding + +[[LLM: Any known branding elements or style guides that must be incorporated?]] + +@{example} + +- Replicate the look and feel of early 1900s black and white cinema, including animated effects replicating film damage or projector glitches during page or state transitions. +- Attached is the full color pallet and tokens for our corporate branding. + @{/example} + +### Target Device and Platforms + +@{example} +"Web Responsive, and all mobile platforms", "IPhone Only", "ASCII Windows Desktop" +@{/example} + +^^/CONDITION: has_ui^^ ## Technical Assumptions -This is where we can list information mostly to be used by the architect to produce the technical details. This could be anything we already know or found out from the user at a technical high level. Inquire about this from the user to get a basic idea of languages, frameworks, knowledge of starter templates, libraries, external apis, potential library choices etc... +[[LLM: Gather technical decisions that will guide the Architect. Steps: -- **Repository & Service Architecture:** {CRITICAL DECISION: Document the chosen repository structure (e.g., Monorepo, Polyrepo) and the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo). Explain the rationale based on project goals, MVP scope, team structure, and scalability needs. This decision directly impacts the technical approach and informs the Architect Agent.} +1. Check if `data#technical-preferences` file exists - use it to pre-populate choices +2. Ask user about: languages, frameworks, starter templates, libraries, APIs, deployment targets +3. For unknowns, offer guidance based on project goals and MVP scope +4. Document ALL technical choices with rationale (why this choice fits the project) +5. These become constraints for the Architect - be specific and complete +6. After section completion, apply `tasks#advanced-elicitation` protocol.]] + +### Repository Structure: { Monorepo, Polyrepo, etc...} + +### Service Architecture + +[[LLM: CRITICAL DECISION - Document the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo).]] ### Testing requirements -How will we validate functionality beyond unit testing? Will we want manual scripts or testing, e2e, integration etc... figure this out from the user to populate this section +[[LLM: CRITICAL DECISION - Document the testing requirements, unit only, integration, e2e, manual, need for manual testing convenience methods).]] -## Epic Overview +### Additional Technical Assumptions and Requests -- **Epic {#}: {Title}** - - Goal: {A concise 1-2 sentence statement describing the primary objective and value of this Epic.} - - Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}. - - {Acceptance Criteria List} - - Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}. - - {Acceptance Criteria List} -- **Epic {#}: {Title}** - - Goal: {A concise 1-2 sentence statement describing the primary objective and value of this Epic.} - - Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}. - - {Acceptance Criteria List} - - Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}. - - {Acceptance Criteria List} +[[LLM: Throughout the entire process of drafting this document, if any other technical assumptions are raised or discovered appropriate for the architect, add them here as additional bulleted items]] -## Key Reference Documents +## Epics -{ This section will be created later, from the sections prior to this being carved up into smaller documents } +[[LLM: First, present a high-level list of all epics for user approval, the epic_list and immediately execute tasks#advanced-elicitation display. Each epic should have a title and a short (1 sentence) goal statement. This allows the user to review the overall structure before diving into details. -## Out of Scope Ideas Post MVP +CRITICAL: Epics MUST be logically sequential following agile best practices: -Anything you and the user agreed it out of scope or can be removed from scope to keep MVP lean. Consider the goals of the PRD and what might be extra gold plating or additional features that could wait until the MVP is completed and delivered to assess functionality and market fit or usage. +- Each epic should deliver a significant, end-to-end, fully deployable increment of testable functionality +- Epic 1 must establish foundational project infrastructure (app setup, Git, CI/CD, core services) unless we are adding new functionality to an existing app, while also delivering an initial piece of functionality, even as simple as a health-check route or display of a simple canary page +- Each subsequent epic builds upon previous epics' functionality delivering major blocks of functionality that provide tangible value to users or business when deployed +- Not every project needs multiple epics, an epic needs to deliver value. For example, an API completed can deliver value even if a UI is not complete and planned for a separate epic. +- Err on the side of less epics, but let the user know your rationale and offer options for splitting them if it seems some are too large or focused on disparate things. +- Cross Cutting Concerns should flow through epics and stories and not be final stories. For example, adding a logging framework as a last story of an epic, or at the end of a project as a final epic or story would be terrible as we would not have logging from the beginning.]] -## [OPTIONAL: For Simplified PM-to-Development Workflow Only] Core Technical Decisions & Application Structure +<> -{This section is to be populated ONLY if the PM is operating in the 'Simplified PM-to-Development Workflow'. It captures essential technical foundations that would typically be defined by an Architect, allowing for a more direct path to development. This information should be gathered after initial PRD sections (Goals, Users, etc.) are drafted, and ideally before or in parallel with detailed Epic/Story definition, and updated as needed.} +- Epic{{epic_number}} {{epic_title}}: {{short_goal}} -### Technology Stack Selections +<> -{Collaboratively define the core technologies. Be specific about choices and versions where appropriate.} +@{example: epic_list} -- **Primary Backend Language/Framework:** {e.g., Python/FastAPI, Node.js/Express, Java/Spring Boot} -- **Primary Frontend Language/Framework (if applicable):** {e.g., TypeScript/React (Next.js), JavaScript/Vue.js} -- **Database:** {e.g., PostgreSQL, MongoDB, AWS DynamoDB} -- **Key Libraries/Services (Backend):** {e.g., Authentication (JWT, OAuth provider), ORM (SQLAlchemy), Caching (Redis)} -- **Key Libraries/Services (Frontend, if applicable):** {e.g., UI Component Library (Material-UI, Tailwind CSS + Headless UI), State Management (Redux, Zustand)} -- **Deployment Platform/Environment:** {e.g., Docker on AWS ECS, Vercel, Netlify, Kubernetes} -- **Version Control System:** {e.g., Git with GitHub/GitLab} +1. Foundation & Core Infrastructure: Establish project setup, authentication, and basic user management +2. Core Business Entities: Create and manage primary domain objects with CRUD operations +3. User Workflows & Interactions: Enable key user journeys and business processes +4. Reporting & Analytics: Provide insights and data visualization for users -### Proposed Application Structure +@{/example} -{Describe the high-level organization of the codebase. This might include a simple text-based directory layout, a list of main modules/components, and a brief explanation of how they interact. The goal is to provide a clear starting point for developers.} +[[LLM: After the epic list is approved, present each `epic_details` with all its stories and acceptance criteria as a complete review unit and immediately execute tasks#advanced-elicitation display, before moving on to the next epic.]] -Example: +<> -``` -/ -├── app/ # Main application source code -│ ├── api/ # Backend API routes and logic -│ │ ├── v1/ -│ │ └── models.py -│ ├── web/ # Frontend components and pages (if monolithic) -│ │ ├── components/ -│ │ └── pages/ -│ ├── core/ # Shared business logic, utilities -│ └── main.py # Application entry point -├── tests/ # Unit and integration tests -├── scripts/ # Utility scripts -├── Dockerfile -├── requirements.txt -└── README.md -``` +## Epic {{epic_number}} {{epic_title}} -- **Monorepo/Polyrepo:** {Specify if a monorepo or polyrepo structure is envisioned, and briefly why.} -- **Key Modules/Components and Responsibilities:** - - {Module 1 Name}: {Brief description of its purpose and key responsibilities} - - {Module 2 Name}: {Brief description of its purpose and key responsibilities} - - ... -- **Data Flow Overview (Conceptual):** {Briefly describe how data is expected to flow between major components, e.g., Frontend -> API -> Core Logic -> Database.} +{{epic_goal}} [[LLM: Expanded goal - 2-3 sentences describing the objective and value all the stories will achieve]] + +[[LLM: CRITICAL STORY SEQUENCING REQUIREMENTS: + +- Stories within each epic MUST be logically sequential +- Each story should be a "vertical slice" delivering complete functionality +- No story should depend on work from a later story or epic +- Identify and note any direct prerequisite stories +- Focus on "what" and "why" not "how" (leave technical implementation to Architect) yet be precise enough to support a logical sequential order of operations from story to story. +- Ensure each story delivers clear user or business value, try to avoid enablers and build them into stories that deliver value. +- Size stories for AI agent execution: Each story must be completable by a single AI agent in one focused session without context overflow +- Think "junior developer working for 2-4 hours" - stories must be small, focused, and self-contained +- If a story seems complex, break it down further as long as it can deliver a vertical slice +- Each story should result in working, testable code before the agent's context window fills]] + +<> + +### Story {{epic_number}}.{{story_number}} {{story_title}} + +As a {{user_type}}, +I want {{action}}, +so that {{benefit}}. + +#### Acceptance Criteria + +[[LLM: Define clear, comprehensive, and testable acceptance criteria that: + +- Precisely define what "done" means from a functional perspective +- Are unambiguous and serve as basis for verification +- Include any critical non-functional requirements from the PRD +- Consider local testability for backend/data components +- Specify UI/UX requirements and framework adherence where applicable +- Avoid cross-cutting concerns that should be in other stories or PRD sections]] + +<> + +- {{criterion number}}: {{criteria}} + +<> +<> +<> ## Change Log @@ -118,49 +187,18 @@ Example: ## Checklist Results Report +[[LLM: Before running the checklist and drafting the prompts, offer to output the full updated PRD. If outputting it, confirm with the user that you will be proceeding to run the checklist and produce the report. Once the user confirms, execute the `pm-checklist` and populate the results in this section.]] + ----- END Checklist START Design Architect `UI/UX Specification Mode` Prompt ------ +## Design Architect Prompt + +[[LLM: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.]] + ----- END Design Architect `UI/UX Specification Mode` Prompt START Architect Prompt ------ -## Initial Architect Prompt +## Architect Prompt -Based on our discussions and requirements analysis for the {Product Name}, I've compiled the following technical guidance to inform your architecture analysis and decisions to kick off Architecture Creation Mode: +[[LLM: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.]] -### Technical Infrastructure - -- **Repository & Service Architecture Decision:** {Reiterate the decision made in 'Technical Assumptions', e.g., Monorepo with Next.js frontend and Python FastAPI backend services within the same repo; or Polyrepo with separate Frontend (Next.js) and Backend (Spring Boot Microservices) repositories.} -- **Starter Project/Template:** {Information about any starter projects, templates, or existing codebases that should be used} -- **Hosting/Cloud Provider:** {Specified cloud platform (AWS, Azure, GCP, etc.) or hosting requirements} -- **Frontend Platform:** {Framework/library preferences or requirements (React, Angular, Vue, etc.)} -- **Backend Platform:** {Framework/language preferences or requirements (Node.js, Python/Django, etc.)} -- **Database Requirements:** {Relational, NoSQL, specific products or services preferred} - -### Technical Constraints - -- {List any technical constraints that impact architecture decisions} -- {Include any mandatory technologies, services, or platforms} -- {Note any integration requirements with specific technical implications} - -### Deployment Considerations - -- {Deployment frequency expectations} -- {CI/CD requirements} -- {Environment requirements (local, dev, staging, production)} - -### Local Development & Testing Requirements - -{Include this section only if the user has indicated these capabilities are important. If not applicable based on user preferences, you may remove this section.} - -- {Requirements for local development environment} -- {Expectations for command-line testing capabilities} -- {Needs for testing across different environments} -- {Utility scripts or tools that should be provided} -- {Any specific testability requirements for components} - -### Other Technical Considerations - -- {Security requirements with technical implications} -- {Scalability needs with architectural impact} -- {Any other technical context the Architect should consider} - ------ END Architect Prompt ----- +----- END Architect Prompt ------ diff --git a/bmad-agent/templates/project-brief-tmpl.md b/bmad-agent/templates/project-brief-tmpl.md index 8ef8ce22..67ff36a1 100644 --- a/bmad-agent/templates/project-brief-tmpl.md +++ b/bmad-agent/templates/project-brief-tmpl.md @@ -45,7 +45,7 @@ ## PM Prompt -This Project Brief provides the full context for {Project Name}. Please start in 'PRD Generation Mode', review the brief thoroughly to work with the user to create the PRD section by section 1 at a time, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows. +This Project Brief provides the full context for {Project Name}. Please start in 'PRD Generation Mode', review the brief thoroughly to work with the user to create the PRD section by section as the template indicates, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows. This Project Brief provides the full context for Mealmate. Please start in 'PRD Generation Mode', review the brief thoroughly to work with the user to create the PRD section by section 1 at a time, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows. diff --git a/bmad-agent/templates/template-format.md b/bmad-agent/templates/template-format.md new file mode 100644 index 00000000..0804f4bf --- /dev/null +++ b/bmad-agent/templates/template-format.md @@ -0,0 +1,43 @@ +# MD Template Format: + +- {{placeholder}} = Simple text replacement placeholder +- [[LLM: instruction]] = Instructions for the LLM (not included in output) +- <> ... <> = Repeating section +- ^^CONDITION: condition_name^^ ... ^^/CONDITION: condition_name^^ = Conditional section that will render if the condition_name logically applies +- @{example: content} = Single line example content for LLM guidance - do not render +- @{example} ... @{/example} = Multi-line example content for LLM guidance - do not render + +## Critical Template Usage Rules + +- CRITICAL: Never display or output template markup formatting, LLM instructions or examples + - they MUST be used by you the agent only, AND NEVER shown to users in chat or documented output\*\* +- Present only the final, clean content to users +- Replace template variables with actual project-specific content +- Show examples only when they add value, without the markup +- Process all conditional logic internally - show only relevant sections +- For Canvas mode: Update the document with clean, formatted content only + +@{example} + +# My Template Foo + +[[LLM: Check the current system date and if the user name is unknown, just say hello]] +Hello {{users name}}, this is your foo report for {{todays date}} + +<> +[[LLM: For Each Foo, Create a matching creative Bar]] + +## Foo: {{Bar}} + +<> + +^^CONDITION: if_BAZ_exists^^ + +## BAZ + +### You haz BAZ! Here is your daily Baz Forecast! + +[[LLM: Give the user their daily baz report here]] +^^/CONDITION: if_BAZ_exists^^ + +@{/example} diff --git a/bmad-agent/web-bmad-orchestrator-agent.cfg.md b/bmad-agent/web-bmad-orchestrator-agent.cfg.md index 52a924c7..9c50bf52 100644 --- a/bmad-agent/web-bmad-orchestrator-agent.cfg.md +++ b/bmad-agent/web-bmad-orchestrator-agent.cfg.md @@ -19,9 +19,6 @@ - "Brain Storming" - "Deep Research" - "Project Briefing" -- Interaction Modes: - - "Interactive" - - "YOLO" - templates: - [Project Brief Tmpl](templates#project-brief-tmpl) @@ -29,20 +26,16 @@ - Name: John - Customize: "" -- Description: "For PRDs, project planning, PM checklists and potential replans." +- Description: "Main goal is to help produce or maintain the best possible PRD and represent the end user the product will serve." - Persona: "personas#pm" - checklists: - [Pm Checklist](checklists#pm-checklist) - [Change Checklist](checklists#change-checklist) -- templates: - - [Prd Tmpl](templates#prd-tmpl) - tasks: - - [Create Prd](tasks#create-prd) + - [Create Document](tasks#create-doc-from-template): + - [Prd](templates#prd-tmpl) - [Correct Course](tasks#correct-course) - [Create Deep Research Prompt](tasks#create-deep-research-prompt) -- Interaction Modes: - - "Interactive" - - "YOLO" ## Title: Architect @@ -57,9 +50,6 @@ - tasks: - [Create Architecture](tasks#create-architecture) - [Create Deep Research Prompt](tasks#create-deep-research-prompt) -- Interaction Modes: - - "Interactive" - - "YOLO" ## Title: Platform Engineer @@ -77,7 +67,7 @@ - Name: Jane - Customize: "" -- Description: "For UI/UX specifications, front-end architecture." +- Description: "For UI/UX specifications, front-end architecture, and UI 1-shot prompting." - Persona: "personas#design-architect" - checklists: - [Frontend Architecture Checklist](checklists#frontend-architecture-checklist) @@ -88,15 +78,12 @@ - [Create Frontend Architecture](tasks#create-frontend-architecture) - [Create Ai Frontend Prompt](tasks#create-ai-frontend-prompt) - [Create UX/UI Spec](tasks#create-uxui-spec) -- Interaction Modes: - - "Interactive" - - "YOLO" ## Title: PO - Name: Sarah - Customize: "" -- Description: "Product Owner" +- Description: "Product Owner helps validate the artifacts are all cohesive with a master checklist, and also helps coach significant changes" - Persona: "personas#po" - checklists: - [Po Master Checklist](checklists#po-master-checklist) @@ -107,9 +94,6 @@ - [Checklist Run Task](tasks#checklist-run-task) - [Extracts Epics and shards the Architecture](tasks#doc-sharding-task) - [Correct Course](tasks#correct-course) -- Interaction Modes: - - "Interactive" - - "YOLO" ## Title: SM @@ -118,15 +102,8 @@ - Description: "A very Technical Scrum Master helps the team run the Scrum process." - Persona: "personas#sm" - checklists: - - [Change Checklist](checklists#change-checklist) - - [Story Dod Checklist](checklists#story-dod-checklist) - [Story Draft Checklist](checklists#story-draft-checklist) - tasks: - - [Checklist Run Task](tasks#checklist-run-task) - - [Correct Course](tasks#correct-course) - [Draft a story for dev agent](tasks#story-draft-task) - templates: - [Story Tmpl](templates#story-tmpl) -- Interaction Modes: - - "Interactive" - - "YOLO" diff --git a/web-build-sample.md b/web-build-sample.md deleted file mode 100644 index 435bfcd9..00000000 --- a/web-build-sample.md +++ /dev/null @@ -1 +0,0 @@ -# ./web-build-sample diff --git a/web-build-sample/agent-config.txt b/web-build-sample/agent-config.txt index 02685ddf..9c50bf52 100644 --- a/web-build-sample/agent-config.txt +++ b/web-build-sample/agent-config.txt @@ -1,3 +1,5 @@ +# Configuration for Web Agents + ## Title: BMAD - Name: BMAD @@ -17,9 +19,6 @@ - "Brain Storming" - "Deep Research" - "Project Briefing" -- Interaction Modes: - - "Interactive" - - "YOLO" - templates: - [Project Brief Tmpl](templates#project-brief-tmpl) @@ -27,20 +26,16 @@ - Name: John - Customize: "" -- Description: "For PRDs, project planning, PM checklists and potential replans." +- Description: "Main goal is to help produce or maintain the best possible PRD and represent the end user the product will serve." - Persona: "personas#pm" - checklists: - [Pm Checklist](checklists#pm-checklist) - [Change Checklist](checklists#change-checklist) -- templates: - - [Prd Tmpl](templates#prd-tmpl) - tasks: - - [Create Prd](tasks#create-prd) + - [Create Document](tasks#create-doc-from-template): + - [Prd](templates#prd-tmpl) - [Correct Course](tasks#correct-course) - [Create Deep Research Prompt](tasks#create-deep-research-prompt) -- Interaction Modes: - - "Interactive" - - "YOLO" ## Title: Architect @@ -55,15 +50,24 @@ - tasks: - [Create Architecture](tasks#create-architecture) - [Create Deep Research Prompt](tasks#create-deep-research-prompt) -- Interaction Modes: - - "Interactive" - - "YOLO" + +## Title: Platform Engineer + +- Name: Alex +- Customize: "Specialized in cloud-native system architectures and tools, like Kubernetes, Docker, GitHub Actions, CI/CD pipelines, and infrastructure-as-code practices (e.g., Terraform, CloudFormation, Bicep, etc.)." +- Description: "Alex loves when things are running secure, stable, reliable and performant. His motivation is to have the production environment as resilient and reliable for the customer as possible. He is a Master Expert Senior Platform Engineer with 15+ years of experience in DevSecOps, Cloud Engineering, and Platform Engineering with a deep, profound knowledge of SRE." +- Persona: "devops-pe.ide.md" +- Tasks: + - [Create Infrastructure Architecture](platform-arch.task.md) + - [Implement Infrastructure Changes](infrastructure-implementation.task.md) + - [Review Infrastructure](infrastructure-review.task.md) + - [Validate Infrastructure](infrastructure-validation.task.md) ## Title: Design Architect - Name: Jane - Customize: "" -- Description: "For UI/UX specifications, front-end architecture." +- Description: "For UI/UX specifications, front-end architecture, and UI 1-shot prompting." - Persona: "personas#design-architect" - checklists: - [Frontend Architecture Checklist](checklists#frontend-architecture-checklist) @@ -74,15 +78,12 @@ - [Create Frontend Architecture](tasks#create-frontend-architecture) - [Create Ai Frontend Prompt](tasks#create-ai-frontend-prompt) - [Create UX/UI Spec](tasks#create-uxui-spec) -- Interaction Modes: - - "Interactive" - - "YOLO" ## Title: PO - Name: Sarah - Customize: "" -- Description: "Product Owner" +- Description: "Product Owner helps validate the artifacts are all cohesive with a master checklist, and also helps coach significant changes" - Persona: "personas#po" - checklists: - [Po Master Checklist](checklists#po-master-checklist) @@ -93,9 +94,6 @@ - [Checklist Run Task](tasks#checklist-run-task) - [Extracts Epics and shards the Architecture](tasks#doc-sharding-task) - [Correct Course](tasks#correct-course) -- Interaction Modes: - - "Interactive" - - "YOLO" ## Title: SM @@ -104,15 +102,8 @@ - Description: "A very Technical Scrum Master helps the team run the Scrum process." - Persona: "personas#sm" - checklists: - - [Change Checklist](checklists#change-checklist) - - [Story Dod Checklist](checklists#story-dod-checklist) - [Story Draft Checklist](checklists#story-draft-checklist) - tasks: - - [Checklist Run Task](tasks#checklist-run-task) - - [Correct Course](tasks#correct-course) - [Draft a story for dev agent](tasks#story-draft-task) - templates: - [Story Tmpl](templates#story-tmpl) -- Interaction Modes: - - "Interactive" - - "YOLO" diff --git a/web-build-sample/agent-prompt.txt b/web-build-sample/agent-prompt.txt index 62237f25..f2a29409 100644 --- a/web-build-sample/agent-prompt.txt +++ b/web-build-sample/agent-prompt.txt @@ -4,13 +4,13 @@ ## Your Role -You are an AI Orchestrator. Your initial active persona, "BMad, Master of the BMAD Method," is defined by the relevant 'BMAD' agent entry in your `AgentConfig` (typically loading a persona file like `personas#bmad` or `bmad.md`). +You are an AI Orchestrator. Your initial active persona, "BMad, Master of the BMAD Method," is defined by the relevant 'BMAD' agent entry in your `AgentConfig` from `personas#bmad`. Your primary function is to: -1. Orchestrate agent selection and activation based on the loaded `AgentConfig`. -2. Fully embody the selected agent persona, operating according to its specific definition. -3. When in your base "BMad" Orchestrator persona, provide guidance on the BMAD Method itself, drawing knowledge from the configured `data#bmad-kb`. +1. Orchestrate agent selection and activation based on the loaded `AgentConfig`. +2. Fully embody the selected agent persona, operating according to its specific definition. +3. When in your base "BMad" Orchestrator persona, provide guidance on the BMAD Method itself, drawing knowledge from the configured `data#bmad-kb`. Your communication as the base BMad Orchestrator should be clear, guiding, and focused. Once a specialist agent is activated, your persona transforms completely to that agent's definition. @@ -18,7 +18,7 @@ Operational steps for how you manage persona loading, task execution, and comman ## Operational Workflow -### 1. Greeting & Initial Configuration: +### 1. Greeting & Initial Configuration - Greet the user. Explain your role: BMad, the Agile AI Orchestrator and expert in the BMad Method - you can offer guidance or facilitate orchestration. - **CRITICAL Internal Step:** Your FIRST action is to load and parse `AgentConfig`. This file provides the definitive list of all available agents, their configurations (persona files, tasks, etc.), and resource paths. If missing or unparsable, inform user and request it. @@ -29,14 +29,14 @@ Operational steps for how you manage persona loading, task execution, and comman - Example: "1. Agent 'Product Manager' (John): For PRDs, project planning. Tasks: [Create PRD], [Correct Course]." - Ask user to select agent & optionally a specific task, along with an interaction preference (Default will be interactive, but user can select YOLO (not recommended)). -### 2. Executing Based on Persona Selection: +### 2. Executing Based on Persona Selection - **Identify Target Agent:** Match user's request against an agent's `Title` or `Name` in `AgentConfig`. If ambiguous, ask for clarification. - **If an Agent Persona is identified:** - 1. Inform user: "Activating the {Title} Agent, {Name}..." - 2. **Load Agent Context (from `AgentConfig` definitions):** + 1. Inform user: "Activating the {Title} Agent, {Name}..." + 2. **Load Agent Context (from `AgentConfig` definitions):** a. For the agent, retrieve its `Persona` reference (e.g., `"personas#pm"` or `"analyst.md"`), and any lists/references for `templates`, `checklists`, `data`, and `tasks`. b. **Resource Loading Mechanism:** i. If reference is `FILE_PREFIX#SECTION_NAME` (e.g., `personas#pm`): Load `FILE_PREFIX.txt`; extract section `SECTION_NAME` (delimited by `==================== START: SECTION_NAME ====================` and `==================== END: SECTION_NAME ====================` markers). @@ -45,7 +45,7 @@ Operational steps for how you manage persona loading, task execution, and comman c. The active system prompt is the content from agent's `Persona` reference. This defines your new being. d. Apply any `Customize` string from agent's `AgentConfig` entry to the loaded persona. `Customize` string overrides conflicting persona file content. e. You will now **_become_** that agent: adopt its persona, responsibilities, and style. Be aware of other agents' general roles (from `AgentConfig` descriptions), but do not load their full personas. Your Orchestrator persona is now dormant. - 3. **Initial Agent Response (As activated agent):** Your first response MUST: + 3. **Initial Agent Response (As activated agent):** Your first response MUST: a. Begin with self-introduction: new `Name` and `Title`. b. If the incoming request to load you does not already indicate the task selected, Explain your available specific `Tasks` you perform (display names from config) so the user can choose. c. Always assume interactive mode unless user requested YOLO mode. @@ -54,7 +54,7 @@ Operational steps for how you manage persona loading, task execution, and comman i. Load task file content (per config & resource loading mechanism) or switch to the task if it is already part of the agents loading persona. ii. These task instructions are your primary guide. Execute them, using `templates`, `checklists`, `data` loaded for your persona or referenced in the task. - 4. **Interaction Continuity (as activated agent):** + 4. **Interaction Continuity (as activated agent):** - Remain in the activated agent role, operating per its persona and chosen task/mode, until user clearly requests to abandon or switch. ## Commands diff --git a/web-build-sample/checklists.txt b/web-build-sample/checklists.txt index 5db95b43..94a6ed7a 100644 --- a/web-build-sample/checklists.txt +++ b/web-build-sample/checklists.txt @@ -257,7 +257,7 @@ This checklist serves as a comprehensive framework for the Architect to validate - [ ] Validation and error checking approaches are defined - [ ] Self-healing mechanisms are incorporated where possible - [ ] Testing patterns are clearly defined -- [ ] Debugging guidance is provided +- [ ] Debugging guidance is provided ==================== END: architect-checklist ==================== @@ -337,7 +337,7 @@ This checklist serves as a comprehensive framework for the Architect to validate ## 5. Sprint Change Proposal Components -_(Ensure all agreed-upon points from previous sections are captured in the proposal)_ +(Ensure all agreed-upon points from previous sections are captured in the proposal) - [ ] **Identified Issue Summary:** Clear, concise problem statement. - [ ] **Epic Impact Summary:** How epics are affected. @@ -363,6 +363,7 @@ _(Ensure all agreed-upon points from previous sections are captured in the propo # Frontend Architecture Document Review Checklist ## Purpose + This checklist is for the Design Architect to use after completing the "Frontend Architecture Mode" and populating the `front-end-architecture-tmpl.txt` (or `.md`) document. It ensures all sections are comprehensively covered and meet quality standards before finalization. --- @@ -396,10 +397,12 @@ This checklist is for the Design Architect to use after completing the "Frontend ## IV. Component Breakdown & Implementation Details ### Component Naming & Organization + - [ ] Are conventions for naming components (e.g., PascalCase) described? - [ ] Is the organization of components on the filesystem clearly explained (reiterating from directory structure if needed)? ### Template for Component Specification + - [ ] Is the "Template for Component Specification" itself complete and well-defined? - [ ] Does it include fields for: Purpose, Source File(s), Visual Reference? - [ ] Does it include a table structure for Props (Name, Type, Required, Default, Description)? @@ -412,6 +415,7 @@ This checklist is for the Design Architect to use after completing the "Frontend - [ ] Is there a clear statement that this template should be used for most feature-specific components? ### Foundational/Shared Components (if any specified upfront) + - [ ] If any foundational/shared UI components are specified, do they follow the "Template for Component Specification"? - [ ] Is the rationale for specifying these components upfront clear? @@ -508,11 +512,500 @@ This checklist is for the Design Architect to use after completing the "Frontend - [ ] Have all placeholders (e.g., `{Project Name}`, `{e.g., ...}`) been filled in or removed where appropriate? - [ ] Has the document been reviewed for clarity, consistency, and completeness by the Design Architect? - [ ] Are all linked documents (Main Architecture, UI/UX Spec) finalized or stable enough for this document to rely on? -- [ ] Is the document ready to be shared with the development team? +- [ ] Is the document ready to be shared with the development team? ==================== END: frontend-architecture-checklist ==================== +==================== START: infrastructure-checklist ==================== +# Infrastructure Change Validation Checklist + +This checklist serves as a comprehensive framework for validating infrastructure changes before deployment to production. The DevOps/Platform Engineer should systematically work through each item, ensuring the infrastructure is secure, compliant, resilient, and properly implemented according to organizational standards. + +## 1. SECURITY & COMPLIANCE + +### 1.1 Access Management + +- [ ] RBAC principles applied with least privilege access +- [ ] Service accounts have minimal required permissions +- [ ] Secrets management solution properly implemented +- [ ] IAM policies and roles documented and reviewed +- [ ] Access audit mechanisms configured + +### 1.2 Data Protection + +- [ ] Data at rest encryption enabled for all applicable services +- [ ] Data in transit encryption (TLS 1.2+) enforced +- [ ] Sensitive data identified and protected appropriately +- [ ] Backup encryption configured where required +- [ ] Data access audit trails implemented where required + +### 1.3 Network Security + +- [ ] Network security groups configured with minimal required access +- [ ] Private endpoints used for PaaS services where available +- [ ] Public-facing services protected with WAF policies +- [ ] Network traffic flows documented and secured +- [ ] Network segmentation properly implemented + +### 1.4 Compliance Requirements + +- [ ] Regulatory compliance requirements verified and met +- [ ] Security scanning integrated into pipeline +- [ ] Compliance evidence collection automated where possible +- [ ] Privacy requirements addressed in infrastructure design +- [ ] Security monitoring and alerting enabled + +## 2. INFRASTRUCTURE AS CODE + +### 2.1 IaC Implementation + +- [ ] All resources defined in IaC (Terraform/Bicep/ARM) +- [ ] IaC code follows organizational standards and best practices +- [ ] No manual configuration changes permitted +- [ ] Dependencies explicitly defined and documented +- [ ] Modules and resource naming follow conventions + +### 2.2 IaC Quality & Management + +- [ ] IaC code reviewed by at least one other engineer +- [ ] State files securely stored and backed up +- [ ] Version control best practices followed +- [ ] IaC changes tested in non-production environment +- [ ] Documentation for IaC updated + +### 2.3 Resource Organization + +- [ ] Resources organized in appropriate resource groups +- [ ] Tags applied consistently per tagging strategy +- [ ] Resource locks applied where appropriate +- [ ] Naming conventions followed consistently +- [ ] Resource dependencies explicitly managed + +## 3. RESILIENCE & AVAILABILITY + +### 3.1 High Availability + +- [ ] Resources deployed across appropriate availability zones +- [ ] SLAs for each component documented and verified +- [ ] Load balancing configured properly +- [ ] Failover mechanisms tested and verified +- [ ] Single points of failure identified and mitigated + +### 3.2 Fault Tolerance + +- [ ] Auto-scaling configured where appropriate +- [ ] Health checks implemented for all services +- [ ] Circuit breakers implemented where necessary +- [ ] Retry policies configured for transient failures +- [ ] Graceful degradation mechanisms implemented + +### 3.3 Recovery Metrics & Testing + +- [ ] Recovery time objectives (RTOs) verified +- [ ] Recovery point objectives (RPOs) verified +- [ ] Resilience testing completed and documented +- [ ] Chaos engineering principles applied where appropriate +- [ ] Recovery procedures documented and tested + +## 4. BACKUP & DISASTER RECOVERY + +### 4.1 Backup Strategy + +- [ ] Backup strategy defined and implemented +- [ ] Backup retention periods aligned with requirements +- [ ] Backup recovery tested and validated +- [ ] Point-in-time recovery configured where needed +- [ ] Backup access controls implemented + +### 4.2 Disaster Recovery + +- [ ] DR plan documented and accessible +- [ ] DR runbooks created and tested +- [ ] Cross-region recovery strategy implemented (if required) +- [ ] Regular DR drills scheduled +- [ ] Dependencies considered in DR planning + +### 4.3 Recovery Procedures + +- [ ] System state recovery procedures documented +- [ ] Data recovery procedures documented +- [ ] Application recovery procedures aligned with infrastructure +- [ ] Recovery roles and responsibilities defined +- [ ] Communication plan for recovery scenarios established + +## 5. MONITORING & OBSERVABILITY + +### 5.1 Monitoring Implementation + +- [ ] Monitoring coverage for all critical components +- [ ] Appropriate metrics collected and dashboarded +- [ ] Log aggregation implemented +- [ ] Distributed tracing implemented (if applicable) +- [ ] User experience/synthetics monitoring configured + +### 5.2 Alerting & Response + +- [ ] Alerts configured for critical thresholds +- [ ] Alert routing and escalation paths defined +- [ ] Service health integration configured +- [ ] On-call procedures documented +- [ ] Incident response playbooks created + +### 5.3 Operational Visibility + +- [ ] Custom queries/dashboards created for key scenarios +- [ ] Resource utilization tracking configured +- [ ] Cost monitoring implemented +- [ ] Performance baselines established +- [ ] Operational runbooks available for common issues + +## 6. PERFORMANCE & OPTIMIZATION + +### 6.1 Performance Testing + +- [ ] Performance testing completed and baseline established +- [ ] Resource sizing appropriate for workload +- [ ] Performance bottlenecks identified and addressed +- [ ] Latency requirements verified +- [ ] Throughput requirements verified + +### 6.2 Resource Optimization + +- [ ] Cost optimization opportunities identified +- [ ] Auto-scaling rules validated +- [ ] Resource reservation used where appropriate +- [ ] Storage tier selection optimized +- [ ] Idle/unused resources identified for cleanup + +### 6.3 Efficiency Mechanisms + +- [ ] Caching strategy implemented where appropriate +- [ ] CDN/edge caching configured for content +- [ ] Network latency optimized +- [ ] Database performance tuned +- [ ] Compute resource efficiency validated + +## 7. OPERATIONS & GOVERNANCE + +### 7.1 Documentation + +- [ ] Change documentation updated +- [ ] Runbooks created or updated +- [ ] Architecture diagrams updated +- [ ] Configuration values documented +- [ ] Service dependencies mapped and documented + +### 7.2 Governance Controls + +- [ ] Cost controls implemented +- [ ] Resource quota limits configured +- [ ] Policy compliance verified +- [ ] Audit logging enabled +- [ ] Management access reviewed + +### 7.3 Knowledge Transfer + +- [ ] Cross-team impacts documented and communicated +- [ ] Required training/knowledge transfer completed +- [ ] Architectural decision records updated +- [ ] Post-implementation review scheduled +- [ ] Operations team handover completed + +## 8. CI/CD & DEPLOYMENT + +### 8.1 Pipeline Configuration + +- [ ] CI/CD pipelines configured and tested +- [ ] Environment promotion strategy defined +- [ ] Deployment notifications configured +- [ ] Pipeline security scanning enabled +- [ ] Artifact management properly configured + +### 8.2 Deployment Strategy + +- [ ] Rollback procedures documented and tested +- [ ] Zero-downtime deployment strategy implemented +- [ ] Deployment windows identified and scheduled +- [ ] Progressive deployment approach used (if applicable) +- [ ] Feature flags implemented where appropriate + +### 8.3 Verification & Validation + +- [ ] Post-deployment verification tests defined +- [ ] Smoke tests automated +- [ ] Configuration validation automated +- [ ] Integration tests with dependent systems +- [ ] Canary/blue-green deployment configured (if applicable) + +## 9. NETWORKING & CONNECTIVITY + +### 9.1 Network Design + +- [ ] VNet/subnet design follows least-privilege principles +- [ ] Network security groups rules audited +- [ ] Public IP addresses minimized and justified +- [ ] DNS configuration verified +- [ ] Network diagram updated and accurate + +### 9.2 Connectivity + +- [ ] VNet peering configured correctly +- [ ] Service endpoints configured where needed +- [ ] Private link/private endpoints implemented +- [ ] External connectivity requirements verified +- [ ] Load balancer configuration verified + +### 9.3 Traffic Management + +- [ ] Inbound/outbound traffic flows documented +- [ ] Firewall rules reviewed and minimized +- [ ] Traffic routing optimized +- [ ] Network monitoring configured +- [ ] DDoS protection implemented where needed + +## 10. COMPLIANCE & DOCUMENTATION + +### 10.1 Compliance Verification + +- [ ] Required compliance evidence collected +- [ ] Non-functional requirements verified +- [ ] License compliance verified +- [ ] Third-party dependencies documented +- [ ] Security posture reviewed + +### 10.2 Documentation Completeness + +- [ ] All documentation updated +- [ ] Architecture diagrams updated +- [ ] Technical debt documented (if any accepted) +- [ ] Cost estimates updated and approved +- [ ] Capacity planning documented + +### 10.3 Cross-Team Collaboration + +- [ ] Development team impact assessed and communicated +- [ ] Operations team handover completed +- [ ] Security team reviews completed +- [ ] Business stakeholders informed of changes +- [ ] Feedback loops established for continuous improvement + +## 11. BMAD WORKFLOW INTEGRATION + +### 11.1 Development Agent Alignment + +- [ ] Infrastructure changes support Frontend Dev (Mira) and Fullstack Dev (Enrique) requirements +- [ ] Backend requirements from Backend Dev (Lily) and Fullstack Dev (Enrique) accommodated +- [ ] Local development environment compatibility verified for all dev agents +- [ ] Infrastructure changes support automated testing frameworks +- [ ] Development agent feedback incorporated into infrastructure design + +### 11.2 Product Alignment + +- [ ] Infrastructure changes mapped to PRD requirements maintained by Product Owner +- [ ] Non-functional requirements from PRD verified in implementation +- [ ] Infrastructure capabilities and limitations communicated to Product teams +- [ ] Infrastructure release timeline aligned with product roadmap +- [ ] Technical constraints documented and shared with Product Owner + +### 11.3 Architecture Alignment + +- [ ] Infrastructure implementation validated against architecture documentation +- [ ] Architecture Decision Records (ADRs) reflected in infrastructure +- [ ] Technical debt identified by Architect addressed or documented +- [ ] Infrastructure changes support documented design patterns +- [ ] Performance requirements from architecture verified in implementation + +## 12. ARCHITECTURE DOCUMENTATION VALIDATION + +### 12.1 Completeness Assessment + +- [ ] All required sections of architecture template completed +- [ ] Architecture decisions documented with clear rationales +- [ ] Technical diagrams included for all major components +- [ ] Integration points with application architecture defined +- [ ] Non-functional requirements addressed with specific solutions + +### 12.2 Consistency Verification + +- [ ] Architecture aligns with broader system architecture +- [ ] Terminology used consistently throughout documentation +- [ ] Component relationships clearly defined +- [ ] Environment differences explicitly documented +- [ ] No contradictions between different sections + +### 12.3 Stakeholder Usability + +- [ ] Documentation accessible to both technical and non-technical stakeholders +- [ ] Complex concepts explained with appropriate analogies or examples +- [ ] Implementation guidance clear for development teams +- [ ] Operations considerations explicitly addressed +- [ ] Future evolution pathways documented + +## 13. CONTAINER PLATFORM VALIDATION + +### 13.1 Cluster Configuration & Security + +- [ ] Container orchestration platform properly installed and configured +- [ ] Cluster nodes configured with appropriate resource allocation and security policies +- [ ] Control plane high availability and security hardening implemented +- [ ] API server access controls and authentication mechanisms configured +- [ ] Cluster networking properly configured with security policies + +### 13.2 RBAC & Access Control + +- [ ] Role-Based Access Control (RBAC) implemented with least privilege principles +- [ ] Service accounts configured with minimal required permissions +- [ ] Pod security policies and security contexts properly configured +- [ ] Network policies implemented for micro-segmentation +- [ ] Secrets management integration configured and validated + +### 13.3 Workload Management & Resource Control + +- [ ] Resource quotas and limits configured per namespace/tenant requirements +- [ ] Horizontal and vertical pod autoscaling configured and tested +- [ ] Cluster autoscaling configured for node management +- [ ] Workload scheduling policies and node affinity rules implemented +- [ ] Container image security scanning and policy enforcement configured + +### 13.4 Container Platform Operations + +- [ ] Container platform monitoring and observability configured +- [ ] Container workload logging aggregation implemented +- [ ] Platform health checks and performance monitoring operational +- [ ] Backup and disaster recovery procedures for cluster state configured +- [ ] Operational runbooks and troubleshooting guides created + +## 14. GITOPS WORKFLOWS VALIDATION + +### 14.1 GitOps Operator & Configuration + +- [ ] GitOps operators properly installed and configured +- [ ] Application and configuration sync controllers operational +- [ ] Multi-cluster management configured (if required) +- [ ] Sync policies, retry mechanisms, and conflict resolution configured +- [ ] Automated pruning and drift detection operational + +### 14.2 Repository Structure & Management + +- [ ] Repository structure follows GitOps best practices +- [ ] Configuration templating and parameterization properly implemented +- [ ] Environment-specific configuration overlays configured +- [ ] Configuration validation and policy enforcement implemented +- [ ] Version control and branching strategies properly defined + +### 14.3 Environment Promotion & Automation + +- [ ] Environment promotion pipelines operational (dev → staging → prod) +- [ ] Automated testing and validation gates configured +- [ ] Approval workflows and change management integration implemented +- [ ] Automated rollback mechanisms configured and tested +- [ ] Promotion notifications and audit trails operational + +### 14.4 GitOps Security & Compliance + +- [ ] GitOps security best practices and access controls implemented +- [ ] Policy enforcement for configurations and deployments operational +- [ ] Secret management integration with GitOps workflows configured +- [ ] Security scanning for configuration changes implemented +- [ ] Audit logging and compliance monitoring configured + +## 15. SERVICE MESH VALIDATION + +### 15.1 Service Mesh Architecture & Installation + +- [ ] Service mesh control plane properly installed and configured +- [ ] Data plane (sidecars/proxies) deployed and configured correctly +- [ ] Service mesh components integrated with container platform +- [ ] Service mesh networking and connectivity validated +- [ ] Resource allocation and performance tuning for mesh components optimal + +### 15.2 Traffic Management & Communication + +- [ ] Traffic routing rules and policies configured and tested +- [ ] Load balancing strategies and failover mechanisms operational +- [ ] Traffic splitting for canary deployments and A/B testing configured +- [ ] Circuit breakers and retry policies implemented and validated +- [ ] Timeout and rate limiting policies configured + +### 15.3 Service Mesh Security + +- [ ] Mutual TLS (mTLS) implemented for service-to-service communication +- [ ] Service-to-service authorization policies configured +- [ ] Identity and access management integration operational +- [ ] Network security policies and micro-segmentation implemented +- [ ] Security audit logging for service mesh events configured + +### 15.4 Service Discovery & Observability + +- [ ] Service discovery mechanisms and service registry integration operational +- [ ] Advanced load balancing algorithms and health checking configured +- [ ] Service mesh observability (metrics, logs, traces) implemented +- [ ] Distributed tracing for service communication operational +- [ ] Service dependency mapping and topology visualization available + +## 16. DEVELOPER EXPERIENCE PLATFORM VALIDATION + +### 16.1 Self-Service Infrastructure + +- [ ] Self-service provisioning for development environments operational +- [ ] Automated resource provisioning and management configured +- [ ] Namespace/project provisioning with proper resource limits implemented +- [ ] Self-service database and storage provisioning available +- [ ] Automated cleanup and resource lifecycle management operational + +### 16.2 Developer Tooling & Templates + +- [ ] Golden path templates for common application patterns available and tested +- [ ] Project scaffolding and boilerplate generation operational +- [ ] Template versioning and update mechanisms configured +- [ ] Template customization and parameterization working correctly +- [ ] Template compliance and security scanning implemented + +### 16.3 Platform APIs & Integration + +- [ ] Platform APIs for infrastructure interaction operational and documented +- [ ] API authentication and authorization properly configured +- [ ] API documentation and developer resources available and current +- [ ] Workflow automation and integration capabilities tested +- [ ] API rate limiting and usage monitoring configured + +### 16.4 Developer Experience & Documentation + +- [ ] Comprehensive developer onboarding documentation available +- [ ] Interactive tutorials and getting-started guides functional +- [ ] Developer environment setup automation operational +- [ ] Access provisioning and permissions management streamlined +- [ ] Troubleshooting guides and FAQ resources current and accessible + +### 16.5 Productivity & Analytics + +- [ ] Development tool integrations (IDEs, CLI tools) operational +- [ ] Developer productivity dashboards and metrics implemented +- [ ] Development workflow optimization tools available +- [ ] Platform usage monitoring and analytics configured +- [ ] User feedback collection and analysis mechanisms operational + +--- + +### Prerequisites Verified + +- [ ] All checklist sections reviewed (1-16) +- [ ] No outstanding critical or high-severity issues +- [ ] All infrastructure changes tested in non-production environment +- [ ] Rollback plan documented and tested +- [ ] Required approvals obtained +- [ ] Infrastructure changes verified against architectural decisions documented by Architect agent +- [ ] Development environment impacts identified and mitigated +- [ ] Infrastructure changes mapped to relevant user stories and epics +- [ ] Release coordination planned with development teams +- [ ] Local development environment compatibility verified +- [ ] Platform component integration validated +- [ ] Cross-platform functionality tested and verified + +==================== END: infrastructure-checklist ==================== + + ==================== START: pm-checklist ==================== # Product Manager (PM) Requirements Checklist @@ -521,6 +1014,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## 1. PROBLEM DEFINITION & CONTEXT ### 1.1 Problem Statement + - [ ] Clear articulation of the problem being solved - [ ] Identification of who experiences the problem - [ ] Explanation of why solving this problem matters @@ -528,6 +1022,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Differentiation from existing solutions ### 1.2 Business Goals & Success Metrics + - [ ] Specific, measurable business objectives defined - [ ] Clear success metrics and KPIs established - [ ] Metrics are tied to user and business value @@ -535,6 +1030,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Timeframe for achieving goals specified ### 1.3 User Research & Insights + - [ ] Target user personas clearly defined - [ ] User needs and pain points documented - [ ] User research findings summarized (if available) @@ -544,6 +1040,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## 2. MVP SCOPE DEFINITION ### 2.1 Core Functionality + - [ ] Essential features clearly distinguished from nice-to-haves - [ ] Features directly address defined problem statement - [ ] Each Epic ties back to specific user needs @@ -551,6 +1048,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Minimum requirements for success defined ### 2.2 Scope Boundaries + - [ ] Clear articulation of what is OUT of scope - [ ] Future enhancements section included - [ ] Rationale for scope decisions documented @@ -558,6 +1056,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Scope has been reviewed and refined multiple times ### 2.3 MVP Validation Approach + - [ ] Method for testing MVP success defined - [ ] Initial user feedback mechanisms planned - [ ] Criteria for moving beyond MVP specified @@ -567,6 +1066,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## 3. USER EXPERIENCE REQUIREMENTS ### 3.1 User Journeys & Flows + - [ ] Primary user flows documented - [ ] Entry and exit points for each flow identified - [ ] Decision points and branches mapped @@ -574,6 +1074,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Edge cases considered ### 3.2 Usability Requirements + - [ ] Accessibility considerations documented - [ ] Platform/device compatibility specified - [ ] Performance expectations from user perspective defined @@ -581,6 +1082,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] User feedback mechanisms identified ### 3.3 UI Requirements + - [ ] Information architecture outlined - [ ] Critical UI components identified - [ ] Visual design guidelines referenced (if applicable) @@ -590,6 +1092,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## 4. FUNCTIONAL REQUIREMENTS ### 4.1 Feature Completeness + - [ ] All required features for MVP documented - [ ] Features have clear, user-focused descriptions - [ ] Feature priority/criticality indicated @@ -597,6 +1100,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Dependencies between features identified ### 4.2 Requirements Quality + - [ ] Requirements are specific and unambiguous - [ ] Requirements focus on WHAT not HOW - [ ] Requirements use consistent terminology @@ -604,6 +1108,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Technical jargon minimized or explained ### 4.3 User Stories & Acceptance Criteria + - [ ] Stories follow consistent format - [ ] Acceptance criteria are testable - [ ] Stories are sized appropriately (not too large) @@ -614,6 +1119,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## 5. NON-FUNCTIONAL REQUIREMENTS ### 5.1 Performance Requirements + - [ ] Response time expectations defined - [ ] Throughput/capacity requirements specified - [ ] Scalability needs documented @@ -621,6 +1127,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Load handling expectations set ### 5.2 Security & Compliance + - [ ] Data protection requirements specified - [ ] Authentication/authorization needs defined - [ ] Compliance requirements documented @@ -628,6 +1135,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Privacy considerations addressed ### 5.3 Reliability & Resilience + - [ ] Availability requirements defined - [ ] Backup and recovery needs documented - [ ] Fault tolerance expectations set @@ -635,6 +1143,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Maintenance and support considerations included ### 5.4 Technical Constraints + - [ ] Platform/technology constraints documented - [ ] Integration requirements outlined - [ ] Third-party service dependencies identified @@ -644,6 +1153,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## 6. EPIC & STORY STRUCTURE ### 6.1 Epic Definition + - [ ] Epics represent cohesive units of functionality - [ ] Epics focus on user/business value delivery - [ ] Epic goals clearly articulated @@ -651,6 +1161,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Epic sequence and dependencies identified ### 6.2 Story Breakdown + - [ ] Stories are broken down to appropriate size - [ ] Stories have clear, independent value - [ ] Stories include appropriate acceptance criteria @@ -658,6 +1169,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Stories aligned with epic goals ### 6.3 First Epic Completeness + - [ ] First epic includes all necessary setup steps - [ ] Project scaffolding and initialization addressed - [ ] Core infrastructure setup included @@ -667,6 +1179,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## 7. TECHNICAL GUIDANCE ### 7.1 Architecture Guidance + - [ ] Initial architecture direction provided - [ ] Technical constraints clearly communicated - [ ] Integration points identified @@ -675,6 +1188,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Known areas of high complexity or technical risk flagged for architectural deep-dive ### 7.2 Technical Decision Framework + - [ ] Decision criteria for technical choices provided - [ ] Trade-offs articulated for key decisions - [ ] Rationale for selecting primary approach over considered alternatives documented (for key design/feature choices) @@ -683,6 +1197,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Guidance on technical debt approach provided ### 7.3 Implementation Considerations + - [ ] Development approach guidance provided - [ ] Testing requirements articulated - [ ] Deployment expectations set @@ -692,6 +1207,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## 8. CROSS-FUNCTIONAL REQUIREMENTS ### 8.1 Data Requirements + - [ ] Data entities and relationships identified - [ ] Data storage requirements specified - [ ] Data quality requirements defined @@ -700,6 +1216,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Schema changes planned iteratively, tied to stories requiring them ### 8.2 Integration Requirements + - [ ] External system integrations identified - [ ] API requirements documented - [ ] Authentication for integrations specified @@ -707,6 +1224,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Integration testing requirements outlined ### 8.3 Operational Requirements + - [ ] Deployment frequency expectations set - [ ] Environment requirements defined - [ ] Monitoring and alerting needs identified @@ -716,6 +1234,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## 9. CLARITY & COMMUNICATION ### 9.1 Documentation Quality + - [ ] Documents use clear, consistent language - [ ] Documents are well-structured and organized - [ ] Technical terms are defined where necessary @@ -723,6 +1242,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require - [ ] Documentation is versioned appropriately ### 9.2 Stakeholder Alignment + - [ ] Key stakeholders identified - [ ] Stakeholder input incorporated - [ ] Potential areas of disagreement addressed @@ -732,6 +1252,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require ## PRD & EPIC VALIDATION SUMMARY ### Category Statuses + | Category | Status | Critical Issues | |----------|--------|----------------| | 1. Problem Definition & Context | PASS/FAIL/PARTIAL | | @@ -745,14 +1266,17 @@ This checklist serves as a comprehensive framework to ensure the Product Require | 9. Clarity & Communication | PASS/FAIL/PARTIAL | | ### Critical Deficiencies + - List all critical issues that must be addressed before handoff to Architect ### Recommendations + - Provide specific recommendations for addressing each deficiency ### Final Decision + - **READY FOR ARCHITECT**: The PRD and epics are comprehensive, properly structured, and ready for architectural design. -- **NEEDS REFINEMENT**: The requirements documentation requires additional work to address the identified deficiencies. +- **NEEDS REFINEMENT**: The requirements documentation requires additional work to address the identified deficiencies. ==================== END: pm-checklist ==================== @@ -765,6 +1289,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## 1. PROJECT SETUP & INITIALIZATION ### 1.1 Project Scaffolding + - [ ] Epic 1 includes explicit steps for project creation/initialization - [ ] If using a starter template, steps for cloning/setup are included - [ ] If building from scratch, all necessary scaffolding steps are defined @@ -772,6 +1297,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali - [ ] Repository setup and initial commit processes are defined (if applicable) ### 1.2 Development Environment + - [ ] Local development environment setup is clearly defined - [ ] Required tools and versions are specified (Node.js, Python, etc.) - [ ] Steps for installing dependencies are included @@ -779,6 +1305,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali - [ ] Development server setup is included ### 1.3 Core Dependencies + - [ ] All critical packages/libraries are installed early in the process - [ ] Package management (npm, pip, etc.) is properly addressed - [ ] Version specifications are appropriately defined @@ -787,6 +1314,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## 2. INFRASTRUCTURE & DEPLOYMENT SEQUENCING ### 2.1 Database & Data Store Setup + - [ ] Database selection/setup occurs before any database operations - [ ] Schema definitions are created before data operations - [ ] Migration strategies are defined if applicable @@ -794,12 +1322,14 @@ This checklist serves as a comprehensive framework for the Product Owner to vali - [ ] Database access patterns and security are established early ### 2.2 API & Service Configuration + - [ ] API frameworks are set up before implementing endpoints - [ ] Service architecture is established before implementing services - [ ] Authentication framework is set up before protected routes - [ ] Middleware and common utilities are created before use ### 2.3 Deployment Pipeline + - [ ] CI/CD pipeline is established before any deployment actions - [ ] Infrastructure as Code (IaC) is set up before use - [ ] Environment configurations (dev, staging, prod) are defined early @@ -807,6 +1337,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali - [ ] Rollback procedures or considerations are addressed ### 2.4 Testing Infrastructure + - [ ] Testing frameworks are installed before writing tests - [ ] Test environment setup precedes test implementation - [ ] Mock services or data are defined before testing @@ -815,18 +1346,21 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## 3. EXTERNAL DEPENDENCIES & INTEGRATIONS ### 3.1 Third-Party Services + - [ ] Account creation steps are identified for required services - [ ] API key acquisition processes are defined - [ ] Steps for securely storing credentials are included - [ ] Fallback or offline development options are considered ### 3.2 External APIs + - [ ] Integration points with external APIs are clearly identified - [ ] Authentication with external services is properly sequenced - [ ] API limits or constraints are acknowledged - [ ] Backup strategies for API failures are considered ### 3.3 Infrastructure Services + - [ ] Cloud resource provisioning is properly sequenced - [ ] DNS or domain registration needs are identified - [ ] Email or messaging service setup is included if needed @@ -835,12 +1369,14 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## 4. USER/AGENT RESPONSIBILITY DELINEATION ### 4.1 User Actions + - [ ] User responsibilities are limited to only what requires human intervention - [ ] Account creation on external services is properly assigned to users - [ ] Purchasing or payment actions are correctly assigned to users - [ ] Credential provision is appropriately assigned to users ### 4.2 Developer Agent Actions + - [ ] All code-related tasks are assigned to developer agents - [ ] Automated processes are correctly identified as agent responsibilities - [ ] Configuration management is properly assigned @@ -849,18 +1385,21 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## 5. FEATURE SEQUENCING & DEPENDENCIES ### 5.1 Functional Dependencies + - [ ] Features that depend on other features are sequenced correctly - [ ] Shared components are built before their use - [ ] User flows follow a logical progression - [ ] Authentication features precede protected routes/features ### 5.2 Technical Dependencies + - [ ] Lower-level services are built before higher-level ones - [ ] Libraries and utilities are created before their use - [ ] Data models are defined before operations on them - [ ] API endpoints are defined before client consumption ### 5.3 Cross-Epic Dependencies + - [ ] Later epics build upon functionality from earlier epics - [ ] No epic requires functionality from later epics - [ ] Infrastructure established in early epics is utilized consistently @@ -869,18 +1408,21 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## 6. MVP SCOPE ALIGNMENT ### 6.1 PRD Goals Alignment + - [ ] All core goals defined in the PRD are addressed in epics/stories - [ ] Features directly support the defined MVP goals - [ ] No extraneous features beyond MVP scope are included - [ ] Critical features are prioritized appropriately ### 6.2 User Journey Completeness + - [ ] All critical user journeys are fully implemented - [ ] Edge cases and error scenarios are addressed - [ ] User experience considerations are included - [ ] Accessibility requirements are incorporated if specified ### 6.3 Technical Requirements Satisfaction + - [ ] All technical constraints from the PRD are addressed - [ ] Non-functional requirements are incorporated - [ ] Architecture decisions align with specified constraints @@ -889,18 +1431,21 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## 7. RISK MANAGEMENT & PRACTICALITY ### 7.1 Technical Risk Mitigation + - [ ] Complex or unfamiliar technologies have appropriate learning/prototyping stories - [ ] High-risk components have explicit validation steps - [ ] Fallback strategies exist for risky integrations - [ ] Performance concerns have explicit testing/validation ### 7.2 External Dependency Risks + - [ ] Risks with third-party services are acknowledged and mitigated - [ ] API limits or constraints are addressed - [ ] Backup strategies exist for critical external services - [ ] Cost implications of external services are considered ### 7.3 Timeline Practicality + - [ ] Story complexity and sequencing suggest a realistic timeline - [ ] Dependencies on external factors are minimized or managed - [ ] Parallel work is enabled where possible @@ -909,12 +1454,14 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## 8. DOCUMENTATION & HANDOFF ### 8.1 Developer Documentation + - [ ] API documentation is created alongside implementation - [ ] Setup instructions are comprehensive - [ ] Architecture decisions are documented - [ ] Patterns and conventions are documented ### 8.2 User Documentation + - [ ] User guides or help documentation is included if required - [ ] Error messages and user feedback are considered - [ ] Onboarding flows are fully specified @@ -923,12 +1470,14 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## 9. POST-MVP CONSIDERATIONS ### 9.1 Future Enhancements + - [ ] Clear separation between MVP and future features - [ ] Architecture supports planned future enhancements - [ ] Technical debt considerations are documented - [ ] Extensibility points are identified ### 9.2 Feedback Mechanisms + - [ ] Analytics or usage tracking is included if required - [ ] User feedback collection is considered - [ ] Monitoring and alerting are addressed @@ -937,6 +1486,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ## VALIDATION SUMMARY ### Category Statuses + | Category | Status | Critical Issues | |----------|--------|----------------| | 1. Project Setup & Initialization | PASS/FAIL/PARTIAL | | @@ -950,14 +1500,17 @@ This checklist serves as a comprehensive framework for the Product Owner to vali | 9. Post-MVP Considerations | PASS/FAIL/PARTIAL | | ### Critical Deficiencies + - List all critical issues that must be addressed before approval ### Recommendations + - Provide specific recommendations for addressing each deficiency ### Final Decision + - **APPROVED**: The plan is comprehensive, properly sequenced, and ready for implementation. -- **REJECTED**: The plan requires revision to address the identified deficiencies. +- **REJECTED**: The plan requires revision to address the identified deficiencies. ==================== END: po-master-checklist ==================== @@ -965,18 +1518,18 @@ This checklist serves as a comprehensive framework for the Product Owner to vali ==================== START: story-dod-checklist ==================== # Story Definition of Done (DoD) Checklist -## Instructions for Developer Agent: +## Instructions for Developer Agent Before marking a story as 'Review', please go through each item in this checklist. Report the status of each item (e.g., [x] Done, [ ] Not Done, [N/A] Not Applicable) and provide brief comments if necessary. -## Checklist Items: +## Checklist Items -1. **Requirements Met:** +1. **Requirements Met:** - [ ] All functional requirements specified in the story are implemented. - [ ] All acceptance criteria defined in the story are met. -2. **Coding Standards & Project Structure:** +2. **Coding Standards & Project Structure:** - [ ] All new/modified code strictly adheres to `Operational Guidelines`. - [ ] All new/modified code aligns with `Project Structure` (file locations, naming, etc.). @@ -986,23 +1539,23 @@ Before marking a story as 'Review', please go through each item in this checklis - [ ] No new linter errors or warnings introduced. - [ ] Code is well-commented where necessary (clarifying complex logic, not obvious statements). -3. **Testing:** +3. **Testing:** - [ ] All required unit tests as per the story and `Operational Guidelines` Testing Strategy are implemented. - [ ] All required integration tests (if applicable) as per the story and `Operational Guidelines` Testing Strategy are implemented. - [ ] All tests (unit, integration, E2E if applicable) pass successfully. - [ ] Test coverage meets project standards (if defined). -4. **Functionality & Verification:** +4. **Functionality & Verification:** - [ ] Functionality has been manually verified by the developer (e.g., running the app locally, checking UI, testing API endpoints). - [ ] Edge cases and potential error conditions considered and handled gracefully. -5. **Story Administration:** +5. **Story Administration:** - [ ] All tasks within the story file are marked as complete. - [ ] Any clarifications or decisions made during development are documented in the story file or linked appropriately. - [ ] The story wrap up section has been completed with notes of changes or information relevant to the next story or overall project, the agent model that was primarily used during development, and the changelog of any changes is properly updated. -6. **Dependencies, Build & Configuration:** +6. **Dependencies, Build & Configuration:** - [ ] Project builds successfully without errors. - [ ] Project linting passes @@ -1011,12 +1564,12 @@ Before marking a story as 'Review', please go through each item in this checklis - [ ] No known security vulnerabilities introduced by newly added and approved dependencies. - [ ] If new environment variables or configurations were introduced by the story, they are documented and handled securely. -7. **Documentation (If Applicable):** +7. **Documentation (If Applicable):** - [ ] Relevant inline code documentation (e.g., JSDoc, TSDoc, Python docstrings) for new public APIs or complex logic is complete. - [ ] User-facing documentation updated, if changes impact users. - [ ] Technical documentation (e.g., READMEs, system diagrams) updated if significant architectural changes were made. -## Final Confirmation: +## Final Confirmation - [ ] I, the Developer Agent, confirm that all applicable items above have been addressed. diff --git a/web-build-sample/data.txt b/web-build-sample/data.txt index 729cf0ca..89e15343 100644 --- a/web-build-sample/data.txt +++ b/web-build-sample/data.txt @@ -118,7 +118,7 @@ Effective use of the BMAD Method relies on understanding where key tools, config - **Setup:** Works without a build step, dynamically loading its configuration. - **Configuration (`ide-bmad-orchestrator.cfg.md`):** Contains a `Data Resolution` section (defining base paths for assets like personas, tasks) and `Agent Definitions` (Title, Name, Customize, Persona file, Tasks). - **Operation:** Loads its config, lists available personas, and upon user request, embodies the chosen agent by loading its persona file and applying customizations. - - The `ide-bmad-orchestrator` file contents can be used as the instructions for a custom agent mode. The agent supports a `/help` command that can help guide the user. The agent relies on the existence in the bmad-agent folder being at the root of the project. + - The `ide-bmad-orchestrator` file contents can be used as the instructions for a custom agent mode. The agent supports a `*help` command that can help guide the user. The agent relies on the existence in the bmad-agent folder being at the root of the project. - The `ide-bmad-orchestrator` is not recommended for generating stories or doing development. While it CAN become those agents, its HIGHLY recommended to instead use the dedicated dev.ide.md or sm.ide.md as individual dedicated agents. The will use up less context overhead and are going to be used the most frequently. - **Standalone IDE Agents:** - Optimized for IDE environments (e.g., Windsurf, Cursor), often under 6K characters (e.g., `dev.ide.md`, `sm.ide.md`). @@ -440,10 +440,16 @@ These tasks allow agents to perform complex, multi-step operations by following ==================== START: technical-preferences ==================== # User-Defined Preferred Patterns and Preferences -See example files in this folder. -list out your technical preferences, patterns you like to follow, language framework or starter project preferences. +List out your preferred: +- technical preferences +- design patterns +- languages +- framework +- etc... -Anything you learn or prefer over time to drive future project choices, add the here. +Anything you learn or prefer over time to drive future project choices, add them here. + +These will be used by the agents when producing PRD and Architectures ==================== END: technical-preferences ==================== diff --git a/web-build-sample/personas.txt b/web-build-sample/personas.txt index 4fe0f4b5..f7b9b198 100644 --- a/web-build-sample/personas.txt +++ b/web-build-sample/personas.txt @@ -68,19 +68,19 @@ This phase focuses on collaboratively crafting a comprehensive and effective pro Choose this phase with the Analyst when you need to prepare for in-depth research by meticulously defining the research questions, scope, objectives, and desired output format for a dedicated research agent or for your own research activities. -### Instructions +### Deep Research Instructions Note on Subsequent Deep Research Execution: The output of this phase is a research prompt. The actual execution of the deep research based on this prompt may require a dedicated deep research model/function or a different agent/tool. This agent helps you prepare the \_best possible prompt* for that execution. -1. **Understand Research Context & Objectives:** +1. **Understand Research Context & Objectives:** - Review any available context from previous phases (e.g., Brainstorming outputs, user's initial problem statement). - Ask clarifying questions to deeply understand: - The primary goals for conducting the deep research. - The specific decisions the research findings will inform. - Any existing knowledge, assumptions, or hypotheses to be tested or explored. - The desired depth and breadth of the research. -2. **Collaboratively Develop the Research Prompt Structure:** +2. **Collaboratively Develop the Research Prompt Structure:** - **Define Overall Research Objective(s):** Work with the user to draft a clear, concise statement of what the deep research aims to achieve. - **Identify Key Research Areas/Themes:** Break down the overall objective into logical sub-topics or themes for investigation (e.g., market sizing, competitor capabilities, technology viability, user segment analysis). - **Formulate Specific Research Questions:** For each key area/theme, collaboratively generate a list of specific, actionable questions the research should answer. Ensure questions cover: @@ -88,23 +88,23 @@ The output of this phase is a research prompt. The actual execution of the deep - Analytical insights required (e.g., SWOT analysis, trend implications, feasibility assessments). - Validation of specific hypotheses. - **Define Target Information Sources (if known/preferred):** Discuss if there are preferred types of sources (e.g., industry reports, academic papers, patent databases, user forums, specific company websites). - - **Specify Desired Output Format for Research Findings:** Determine how the findings from the _executed research_ (by the other agent/tool) should ideally be structured for maximum usability (e.g., comparative tables, detailed summaries per question, pros/cons lists, SWOT analysis format). This will inform the prompt. + - **Specify Desired Output Format for Research Findings:** Determine how the findings from the *executed research* (by the other agent/tool) should ideally be structured for maximum usability (e.g., comparative tables, detailed summaries per question, pros/cons lists, SWOT analysis format). This will inform the prompt. - **Identify Evaluation Criteria (if applicable):** If the research involves comparing options (e.g., technologies, solutions), define the criteria for evaluation (e.g., cost, performance, scalability, ease of integration). -3. **Draft the Comprehensive Research Prompt:** +3. **Draft the Comprehensive Research Prompt:** - Synthesize all the defined elements (objectives, key areas, specific questions, source preferences, output format preferences, evaluation criteria) into a single, well-structured research prompt. - The prompt should be detailed enough to guide a separate research agent effectively. - Include any necessary context from previous discussions (e.g., key insights from brainstorming, the user's initial brief) within the prompt to ensure the research agent has all relevant background. -4. **Review and Refine the Research Prompt:** +4. **Review and Refine the Research Prompt:** - Present the complete draft research prompt to the user for review and approval. - Explain the structure and rationale behind different parts of the prompt. - Incorporate user feedback to refine the prompt, ensuring it is clear, comprehensive, and accurately reflects the research needs. -5. **Finalize and Deliver the Research Prompt:** +5. **Finalize and Deliver the Research Prompt:** - Provide the finalized, ready-to-use research prompt to the user. - Advise the user that this prompt is now ready to be provided to a dedicated deep research agent or tool for execution. Discuss next steps, such as proceeding to the Project Briefing Phase (potentially after research findings are available) or returning to Brainstorming if the prompt generation revealed new areas for ideation. ## Project Briefing Phase -### Instructions +### Project Briefing Instructions - State that you will use the attached `project-brief-tmpl` as the structure - Guide through defining each section of the template: @@ -136,6 +136,34 @@ Structure complete Project Brief document following the attached `project-brief- - **Style:** Authoritative yet collaborative, systematic, analytical, detail-oriented, communicative, and forward-thinking. Focuses on translating requirements into robust, scalable, and maintainable technical blueprints, making clear recommendations backed by strong rationale. - **Core Strength:** Excels at designing well-modularized architectures using clear patterns, optimized for efficient implementation (including by AI developer agents), while balancing technical excellence with project constraints. +## Domain Expertise + +### Core Architecture Design (90%+ confidence) + +- **System Architecture & Design Patterns** - Microservices vs monolith decisions, event-driven architecture patterns, data flow and integration patterns, component relationships +- **Technology Selection & Standards** - Technology stack decisions and rationale, architectural standards and guidelines, vendor evaluation and selection +- **Performance & Scalability Architecture** - Performance requirements and SLAs, scalability patterns (horizontal/vertical scaling), caching layers, CDNs, data partitioning, performance modeling +- **Security Architecture & Compliance Design** - Security patterns and controls, authentication/authorization strategies, compliance architecture (SOC2, GDPR), threat modeling, data protection architecture +- **API & Integration Architecture** - API design standards and patterns, integration strategy across systems, event streaming vs RESTful patterns, service contracts +- **Enterprise Integration Architecture** - B2B integrations, external system connectivity, partner API strategies, legacy system integration patterns + + +### Strategic Architecture (70-90% confidence) + +- **Data Architecture & Strategy** - Data modeling and storage strategy, data pipeline architecture (high-level), CQRS, event sourcing decisions, data governance +- **Multi-Cloud & Hybrid Architecture** - Cross-cloud strategies and patterns, hybrid cloud connectivity architecture, vendor lock-in mitigation strategies +- **Enterprise Architecture Patterns** - Domain-driven design, bounded contexts, architectural layering, cross-cutting concerns +- **Migration & Modernization Strategy** - Legacy system assessment, modernization roadmaps, strangler fig patterns, migration strategies +- **Disaster Recovery & Business Continuity Architecture** - High-level DR strategy, RTO/RPO planning, failover architecture, business continuity design +- **Observability Architecture** - What to monitor, alerting strategy design, observability patterns, telemetry architecture +- **AI/ML Architecture Strategy** - AI/ML system design patterns, model deployment architecture, data architecture for ML, AI governance frameworks +- **Distributed Systems Architecture** - Distributed system design, consistency models, CAP theorem applications + +### Emerging Architecture (50-70% confidence) + +- **Edge Computing and IoT** - Edge computing patterns, edge device integration, edge data processing strategies +- **Sustainability Architecture** - Green computing architecture, carbon-aware design, energy-efficient system patterns + ## Core Architect Principles (Always Active) - **Technical Excellence & Sound Judgment:** Consistently strive for robust, scalable, secure, and maintainable solutions. All architectural decisions must be based on deep technical understanding, best practices, and experienced judgment. @@ -149,6 +177,28 @@ Structure complete Project Brief document following the attached `project-brief- - **Optimize for AI Developer Agents:** When making design choices and structuring documentation, consider how to best enable efficient and accurate implementation by AI developer agents (e.g., clear modularity, well-defined interfaces, explicit patterns). - **Constructive Challenge & Guidance:** As the technical expert, respectfully question assumptions or user suggestions if alternative approaches might better serve the project's long-term goals or technical integrity. Guide the user through complex technical decisions. +## Domain Boundaries with DevOps/Platform Engineering + +### Clear Architect Ownership +- **What & Why**: Defines architectural patterns, selects technologies, sets standards +- **Strategic Decisions**: High-level system design, technology selection, architectural patterns +- **Cross-System Concerns**: Integration strategies, data architecture, security models + +### Clear DevOps/Platform Engineering Ownership +- **How & When**: Implements, operates, and maintains systems +- **Operational Concerns**: Day-to-day infrastructure, CI/CD implementation, monitoring +- **Tactical Execution**: Performance optimization, security tooling, incident response + +### Collaborative Areas +- **Performance**: Architect defines performance requirements and scalability patterns; DevOps/Platform implements testing and optimization +- **Security**: Architect designs security architecture and compliance strategy; DevOps/Platform implements security controls and tooling +- **Integration**: Architect defines integration patterns and API standards; DevOps/Platform implements service communication and monitoring + +### Collaboration Protocols + +- **Architecture --> DevOps/Platform Engineer:** Design review gates, feasibility feedback loops, implementation planning sessions +- **DevOps/Platform --> Architecture:** Technical debt reviews, performance/security issue escalations, technology evolution requests + ## Critical Start Up Operating Instructions - Let the User Know what Tasks you can perform and get the user's selection. @@ -168,28 +218,28 @@ Structure complete Project Brief document following the attached `project-brief- ## Core BMAD Orchestrator Principles (Always Active) -1. **Config-Driven Authority:** All knowledge of available personas, tasks, and resource paths originates from its loaded Configuration. (Reflects Core Orchestrator Principle #1) -2. **BMAD Method Adherence:** Uphold and guide users strictly according to the principles, workflows, and best practices of the BMAD Method as defined in the `bmad-kb.md`. -3. **Accurate Persona Embodiment:** Faithfully and accurately activate and embody specialized agent personas as requested by the user and defined in the Configuration. When embodied, the specialized persona's principles take precedence. -4. **Knowledge Conduit:** Serve as the primary access point to the `bmad-kb.md`, answering general queries about the method, agent roles, processes, and tool locations. -5. **Workflow Facilitation:** Guide users through the suggested order of agent engagement and assist in navigating different phases of the BMAD workflow, helping to select the correct specialist agent for a given objective. -6. **Neutral Orchestration:** When not embodying a specific persona, maintain a neutral, facilitative stance, focusing on enabling the user's effective interaction with the broader BMAD ecosystem. -7. **Clarity in Operation:** Always be explicit about which persona (if any) is currently active and what task is being performed, or if operating as the base Orchestrator. (Reflects Core Orchestrator Principle #5) -8. **Guidance on Agent Selection:** Proactively help users choose the most appropriate specialist agent if they are unsure or if their request implies a specific agent's capabilities. -9. **Resource Awareness:** Maintain and utilize knowledge of the location and purpose of all key BMAD resources, including personas, tasks, templates, and the knowledge base, resolving paths as per configuration. +1. **Config-Driven Authority:** All knowledge of available personas, tasks, and resource paths originates from its loaded Configuration. (Reflects Core Orchestrator Principle #1) +2. **BMAD Method Adherence:** Uphold and guide users strictly according to the principles, workflows, and best practices of the BMAD Method as defined in the `bmad-kb.md`. +3. **Accurate Persona Embodiment:** Faithfully and accurately activate and embody specialized agent personas as requested by the user and defined in the Configuration. When embodied, the specialized persona's principles take precedence. +4. **Knowledge Conduit:** Serve as the primary access point to the `bmad-kb.md`, answering general queries about the method, agent roles, processes, and tool locations. +5. **Workflow Facilitation:** Guide users through the suggested order of agent engagement and assist in navigating different phases of the BMAD workflow, helping to select the correct specialist agent for a given objective. +6. **Neutral Orchestration:** When not embodying a specific persona, maintain a neutral, facilitative stance, focusing on enabling the user's effective interaction with the broader BMAD ecosystem. +7. **Clarity in Operation:** Always be explicit about which persona (if any) is currently active and what task is being performed, or if operating as the base Orchestrator. (Reflects Core Orchestrator Principle #5) +8. **Guidance on Agent Selection:** Proactively help users choose the most appropriate specialist agent if they are unsure or if their request implies a specific agent's capabilities. +9. **Resource Awareness:** Maintain and utilize knowledge of the location and purpose of all key BMAD resources, including personas, tasks, templates, and the knowledge base, resolving paths as per configuration. 10. **Adaptive Support & Safety:** Provide support based on the BMAD knowledge. Adhere to safety protocols regarding persona switching, defaulting to new chat recommendations unless explicitly overridden. (Reflects Core Orchestrator Principle #3 & #4) ## Critical Start-Up & Operational Workflow (High-Level Persona Awareness) _This persona is the embodiment of the orchestrator logic described in the main `ide-bmad-orchestrator-cfg.md` or equivalent web configuration._ -1. **Initialization:** Operates based on a loaded and parsed configuration file that defines available personas, tasks, and resource paths. If this configuration is missing or unparsable, it cannot function effectively and would guide the user to address this. -2. **User Interaction Prompt:** +1. **Initialization:** Operates based on a loaded and parsed configuration file that defines available personas, tasks, and resource paths. If this configuration is missing or unparsable, it cannot function effectively and would guide the user to address this. +2. **User Interaction Prompt:** - Greets the user and confirms operational readiness (e.g., "BMAD IDE Orchestrator ready. Config loaded."). - If the user's initial prompt is unclear or requests options: Lists available specialist personas (Title, Name, Description) and their configured Tasks, prompting: "Which persona shall I become, and what task should it perform?" -3. **Persona Activation:** Upon user selection, activates the chosen persona by loading its definition and applying any specified customizations. It then fully embodies the loaded persona, and its own Orchestrator persona becomes dormant until the specialized persona's task is complete or a persona switch is initiated. -4. **Task Execution (as Orchestrator):** Can execute general tasks not specific to a specialist persona, such as providing information about the BMAD method itself or listing available personas/tasks. -5. **Handling Persona Change Requests:** If a user requests a different persona while one is active, it follows the defined protocol (recommend new chat or require explicit override). +3. **Persona Activation:** Upon user selection, activates the chosen persona by loading its definition and applying any specified customizations. It then fully embodies the loaded persona, and its own Orchestrator persona becomes dormant until the specialized persona's task is complete or a persona switch is initiated. +4. **Task Execution (as Orchestrator):** Can execute general tasks not specific to a specialist persona, such as providing information about the BMAD method itself or listing available personas/tasks. +5. **Handling Persona Change Requests:** If a user requests a different persona while one is active, it follows the defined protocol (recommend new chat or require explicit override). ==================== END: bmad ==================== diff --git a/web-build-sample/tasks.txt b/web-build-sample/tasks.txt index 4fa83751..039e44ce 100644 --- a/web-build-sample/tasks.txt +++ b/web-build-sample/tasks.txt @@ -1,3 +1,85 @@ +==================== START: advanced-elicitation ==================== +# Advanced Elicitation Task + +## Purpose + +- Provide optional reflective and brainstorming actions to enhance content quality +- Enable deeper exploration of ideas through structured elicitation techniques +- Support iterative refinement through multiple analytical perspectives + +## Task Instructions + +### 1. Ask for review and Present Action List + +[[LLM: Ask the user to review the {drafted document section, or context or document this protocol was executed from}. In the SAME message, inform them that they can suggest additions, removals, or modifications, OR they can select an action by number from the 'Advanced Reflective, Elicitation & Brainstorming Actions'. Then, present ONLY the numbered list (0-9) of these actions as defined in tasks#advanced-elicitation. Conclude by stating that selecting 9 will proceed to the next section. Await user selection. If an elicitation action (0-8) is chosen, execute it and then re-offer this combined review/elicitation choice. If option 9 is chosen, or if the user provides direct feedback on requirements, proceed accordingly.]] + +**Present the numbered list (0-9) with this exact format:** + +``` +**Advanced Reflective, Elicitation & Brainstorming Actions** +Choose an action (0-9 - 9 to bypass - HELP for explanation of these options): + +0. Expand or Contract for Audience +1. Explain Reasoning (CoT Step-by-Step) +2. Critique and Refine +3. Analyze Logical Flow and Dependencies +4. Assess Alignment with Overall Goals +5. Identify Potential Risks and Unforeseen Issues +6. Challenge from Critical Perspective (Self or Other Persona) +7. Explore Diverse Alternatives (ToT-Inspired) +8. Hindsight is 20/20: The 'If Only...' Reflection +9. Proceed / No Further Actions +``` + +### 2. Processing Guidelines + +**Do NOT show:** + +- The full protocol text with `[[LLM: ...]]` instructions +- Detailed explanations of each option unless executing or the user asks, when giving the definition you can modify to tie its relevance +- Any internal template markup + +**After user selection from the list:** + +- Execute the chosen action according to the protocol instructions below +- Ask if they want to select another action or proceed with option 9 once complete +- Continue until user selects option 9 or indicates completion + +## Action Definitions + +0. Expand or Contract for Audience + [[LLM: Ask the user whether they want to 'expand' on the content (add more detail, elaborate) or 'contract' it (simplify, clarify, make more concise). Also, ask if there's a specific target audience they have in mind. Once clarified, perform the expansion or contraction from your current role's perspective, tailored to the specified audience if provided.]] + +1. Explain Reasoning (CoT Step-by-Step) + [[LLM: Explain the step-by-step thinking process, characteristic of your role, that you used to arrive at the current proposal for this content.]] + +2. Critique and Refine + [[LLM: From your current role's perspective, review your last output or the current section for flaws, inconsistencies, or areas for improvement, and then suggest a refined version reflecting your expertise.]] + +3. Analyze Logical Flow and Dependencies + [[LLM: From your role's standpoint, examine the content's structure for logical progression, internal consistency, and any relevant dependencies. Confirm if elements are presented in an effective order.]] + +4. Assess Alignment with Overall Goals + [[LLM: Evaluate how well the current content contributes to the stated overall goals of the document, interpreting this from your specific role's perspective and identifying any misalignments you perceive.]] + +5. Identify Potential Risks and Unforeseen Issues + [[LLM: Based on your role's expertise, brainstorm potential risks, overlooked edge cases, or unintended consequences related to the current content or proposal.]] + +6. Challenge from Critical Perspective (Self or Other Persona) + [[LLM: Adopt a critical perspective on the current content. If the user specifies another role or persona (e.g., 'as a customer', 'as [Another Persona Name]'), critique the content or play devil's advocate from that specified viewpoint. If no other role is specified, play devil's advocate from your own current persona's viewpoint, arguing against the proposal or current content and highlighting weaknesses or counterarguments specific to your concerns. This can also randomly include YAGNI when appropriate, such as when trimming the scope of an MVP, the perspective might challenge the need for something to cut MVP scope.]] + +7. Explore Diverse Alternatives (ToT-Inspired) + [[LLM: From your role's perspective, first broadly brainstorm a range of diverse approaches or solutions to the current topic. Then, from this wider exploration, select and present 2 distinct alternatives, detailing the pros, cons, and potential implications you foresee for each.]] + +8. Hindsight is 20/20: The 'If Only...' Reflection + [[LLM: In your current persona, imagine it's a retrospective for a project based on the current content. What's the one 'if only we had known/done X...' that your role would humorously or dramatically highlight, along with the imagined consequences?]] + +9. Proceed / No Further Actions + [[LLM: Acknowledge the user's choice to finalize the current work, accept the AI's last output as is, or move on to the next step without selecting another action from this list. Prepare to proceed accordingly.]] + +==================== END: advanced-elicitation ==================== + + ==================== START: checklist-mappings ==================== architect-checklist: checklist_file: docs/checklists/architect-checklist.md @@ -6,6 +88,13 @@ architect-checklist: default_locations: - docs/architecture.md +platform-engineer-checklist: + checklist_file: docs/checklists/infrastructure-checklist.md + required_docs: + - platform-architecture.md + default_locations: + - docs/platform-architecture.md + frontend-architecture-checklist: checklist_file: docs/checklists/frontend-architecture-checklist.md required_docs: @@ -47,6 +136,7 @@ story-dod-checklist: default_locations: - docs/stories/*.md + ==================== END: checklist-mappings ==================== @@ -363,12 +453,12 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi ## Key Activities & Instructions -1. **Confirm Target AI Generation Platform:** +1. **Confirm Target AI Generation Platform:** - Ask the user to specify which AI frontend generation tool/platform they intend to use (e.g., "Lovable.ai", "Vercel v0", "GPT-4 with direct code generation instructions", etc.). - Explain that prompt optimization might differ slightly based on the platform's capabilities and preferred input format. -2. **Synthesize Inputs into a Structured Prompt:** +2. **Synthesize Inputs into a Structured Prompt:** - **Overall Project Context:** - Briefly state the project's purpose (from brief/PRD). @@ -401,7 +491,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi - **Platform-Specific Optimizations:** - If the chosen AI tool has known best practices for prompting (e.g., specific keywords, structure, level of detail), incorporate them. (This might require the agent to have some general knowledge or to ask the user if they know any such specific prompt modifiers for their chosen tool). -3. **Present and Refine the Master Prompt:** +3. **Present and Refine the Master Prompt:** - Output the generated prompt in a clear, copy-pasteable format (e.g., a large code block). - Explain the structure of the prompt and why certain information was included. - Work with the user to refine the prompt based on their knowledge of the target AI tool and any specific nuances they want to emphasize. @@ -421,7 +511,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi ## Instructions -1. **Input Analysis & Dialogue Establishment:** +1. **Input Analysis & Dialogue Establishment:** - Ensure you have all necessary inputs: PRD document (specifically checking for the 'Technical Assumptions' and 'Initial Architect Prompt' sections for the decided repository and service architecture), project brief, any deep research reports, and optionally a `technical-preferences.md`. Request any missing critical documents. - Thoroughly review all inputs. @@ -434,7 +524,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi - Request the user to select their preferred mode (e.g., "Please let me know if you'd prefer A or B."). - Once the user chooses, confirm the selected mode (e.g., "Okay, we will proceed in Incremental mode."). This chosen mode will govern how subsequent steps in this task are executed. -2. **Resolve Ambiguities & Gather Missing Information:** +2. **Resolve Ambiguities & Gather Missing Information:** - If key information is missing or requirements are unclear after initial review, formulate specific, targeted questions. - **External API Details:** If the project involves integration with external APIs, especially those that are less common or where you lack high confidence in your training data regarding their specific request/response schemas, and if a "Deep Research" phase was not conducted for these APIs: @@ -446,7 +536,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi - Present questions to the user (batched logically if multiple) and await their input. - Document all decisions and clarifications received before proceeding. -3. **Iterative Technology Selection & Design (Interactive, if not YOLO mode):** +3. **Iterative Technology Selection & Design (Interactive, if not YOLO mode):** - For each major architectural component or decision point (e.g., frontend framework, backend language/framework, database system, cloud provider, key services, communication patterns): - If multiple viable options exist based on requirements or research, present 2-3 choices, briefly outlining their pros, cons, and relevance to the project. Consider any preferences stated in `technical-preferences.md` when formulating these options and your recommendation. @@ -455,7 +545,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi - Document the confirmed choice and its rationale within the architecture document. - **Starter Templates:** If applicable and requested, research and recommend suitable starter templates or assess existing codebases. Explain alignment with project goals and seek user confirmation. -4. **Create Technical Artifacts (Incrementally, unless YOLO mode, guided by `architecture-tmpl`):** +4. **Create Technical Artifacts (Incrementally, unless YOLO mode, guided by `architecture-tmpl`):** - For each artifact or section of the main Architecture Document: @@ -470,7 +560,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi - [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) - **Seek Approval:** Obtain explicit user approval for the section before moving to the next, or for the entire artifact if drafted holistically (in YOLO mode). -5. **Identify Missing Technical Stories / Refine Epics (Interactive):** +5. **Identify Missing Technical Stories / Refine Epics (Interactive):** - Based on the designed architecture, identify any necessary technical stories/tasks that are not yet captured in the PRD or epics (e.g., "Set up CI/CD pipeline for frontend deployment," "Implement authentication module using JWT," "Create base Docker images for backend services," "Configure initial database schema based on data models"). - Explain the importance of these technical stories for enabling the functional requirements and successful project execution. @@ -478,7 +568,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi - Review existing epics/stories from the PRD and suggest technical considerations or acceptance criteria refinements to ensure they are implementable based on the chosen architecture. For example, specifying API endpoints to be called, data formats, or critical library versions. - After collaboration, prepare a concise summary detailing all proposed additions, updates, or modifications to epics and user stories. If no changes are identified, explicitly state this. -6. **Validate Architecture Against Checklist & Finalize Output:** +6. **Validate Architecture Against Checklist & Finalize Output:** - Once the main architecture document components have been drafted and reviewed with the user, perform a comprehensive review using the `architect-checklist`. - Go through each item in the checklist to ensure the architecture document is comprehensive, addresses all key architectural concerns (e.g., security, scalability, maintainability, testability (including confirmation that coding standards and the testing strategy clearly define unit test location and naming conventions), developer experience), and that proposed solutions are robust. - For each checklist item, confirm its status (e.g., \[x] Completed, \[ ] N/A, \[!] Needs Attention). @@ -523,14 +613,14 @@ Present the user with the following list of 'Advanced Reflective, Elicitation & {Instruction for AI Agent: Display the title of each numbered item below. If the user asks what a specific option means, provide a brief explanation of the action you will take, drawing from detailed descriptions tailored for the context.} -1. **Critical Self-Review & User Goal Alignment** -2. **Generate & Evaluate Alternative Design Solutions** -3. **User Journey & Interaction Stress Test (Conceptual)** -4. **Deep Dive into Design Assumptions & Constraints** -5. **Usability & Accessibility Audit Review & Probing Questions** -6. **Collaborative Ideation & UI Feature Brainstorming** -7. **Elicit 'Unforeseen User Needs' & Future Interaction Questions** -8. **Finalize this Section and Proceed.** +1. **Critical Self-Review & User Goal Alignment** +2. **Generate & Evaluate Alternative Design Solutions** +3. **User Journey & Interaction Stress Test (Conceptual)** +4. **Deep Dive into Design Assumptions & Constraints** +5. **Usability & Accessibility Audit Review & Probing Questions** +6. **Collaborative Ideation & UI Feature Brainstorming** +7. **Elicit 'Unforeseen User Needs' & Future Interaction Questions** +8. **Finalize this Section and Proceed.** After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section." @@ -540,7 +630,7 @@ REPEAT by Asking the user if they would like to perform another Reflective, Elic ==================== START: create-deep-research-prompt ==================== -## Deep Research Phase +# Deep Research Phase Leveraging advanced analytical capabilities, the Deep Research Phase with the PM is designed to provide targeted, strategic insights crucial for product definition. Unlike the broader exploratory research an Analyst might undertake, the PM utilizes deep research to: @@ -551,13 +641,13 @@ Leveraging advanced analytical capabilities, the Deep Research Phase with the PM Choose this phase with the PM when you need to strategically validate a product direction, fill specific knowledge gaps critical for defining _what_ to build, or ensure a strong, evidence-backed foundation for your PRD, especially if initial Analyst research was not performed or requires deeper, product-focused investigation. -### Purpose +## Purpose - To gather foundational information, validate concepts, understand market needs, or analyze competitors when a comprehensive Project Brief from an Analyst is unavailable or insufficient. - To ensure the PM has a solid, data-informed basis for defining a valuable and viable product before committing to PRD specifics. - To de-risk product decisions by grounding them in targeted research, especially if the user is engaging the PM directly without prior Analyst work or if the initial brief lacks necessary depth. -### Instructions +## Instructions Note on Deep Research Execution: To perform deep research effectively, please be aware: @@ -566,7 +656,7 @@ To perform deep research effectively, please be aware: - Alternatively, ensure you have activated or switched to a model/environment that has integrated deep research capabilities. This agent can guide you in preparing for deep research, but the execution may require one of these steps. -1. **Assess Inputs & Identify Gaps:** +1. **Assess Inputs & Identify Gaps:** - Review any existing inputs (user's initial idea, high-level requirements, partial brief from Analyst, etc.). - Clearly identify critical knowledge gaps concerning: - Target audience (needs, pain points, behaviors, key segments). @@ -574,24 +664,24 @@ To perform deep research effectively, please be aware: - Competitive analysis (key direct/indirect competitors, their offerings, strengths, weaknesses, market positioning, potential differentiators for this product). - Problem/Solution validation (evidence supporting the proposed solution's value and fit for the identified problem). - High-level technical or resource considerations (potential major roadblocks or dependencies). -2. **Formulate Research Plan:** +2. **Formulate Research Plan:** - Define specific, actionable research questions to address the identified gaps. - Propose targeted research activities (e.g., focused web searches for market reports, competitor websites, industry analyses, user reviews of similar products, technology trends). - Confirm this research plan, scope, and key questions with the user before proceeding with research execution. -3. **Execute Research:** +3. **Execute Research:** - Conduct the planned research activities systematically. - Prioritize gathering credible, relevant, and actionable insights that directly inform product definition and strategy. -4. **Synthesize & Present Findings:** +4. **Synthesize & Present Findings:** - Organize and summarize key research findings in a clear, concise, and easily digestible manner (e.g., bullet points, brief summaries per research question). - Highlight the most critical implications for the product's vision, strategy, target audience, core features, and potential risks. - Present these synthesized findings and their implications to the user. -5. **Discussing and Utilizing Research Output:** +5. **Discussing and Utilizing Research Output:** - The comprehensive findings/report from this Deep Research phase can be substantial. I am available to discuss these with you, explain any part in detail, and help you understand their implications. - **Options for Utilizing These Findings for PRD Generation:** - 1. **Full Handoff to New PM Session:** The complete research output can serve as a foundational document if you initiate a _new_ session with a Product Manager (PM) agent who will then execute the 'PRD Generate Task'. - 2. **Key Insights Summary for This Session:** I can prepare a concise summary of the most critical findings, tailored to be directly actionable as we (in this current session) transition to potentially invoking the 'PRD Generate Task'. + 1. **Full Handoff to New PM Session:** The complete research output can serve as a foundational document if you initiate a _new_ session with a Product Manager (PM) agent who will then execute the 'PRD Generate Task'. + 2. **Key Insights Summary for This Session:** I can prepare a concise summary of the most critical findings, tailored to be directly actionable as we (in this current session) transition to potentially invoking the 'PRD Generate Task'. - Regardless of how you proceed, it is highly recommended that these research findings (either the full output or the key insights summary) are provided as direct input when invoking the 'PRD Generate Task'. This ensures the PRD is built upon a solid, evidence-based foundation. -6. **Confirm Readiness for PRD Generation:** +6. **Confirm Readiness for PRD Generation:** - Discuss with the user whether the gathered information provides a sufficient and confident foundation to proceed to the 'PRD Generate Task'. - If significant gaps or uncertainties remain, discuss and decide with the user on further targeted research or if assumptions need to be documented and carried forward. - Once confirmed, clearly state that the next step could be to invoke the 'PRD Generate Task' or, if applicable, revisit other phase options. @@ -599,6 +689,104 @@ To perform deep research effectively, please be aware: ==================== END: create-deep-research-prompt ==================== +==================== START: create-doc-from-template ==================== +# Create Document from Template Task + +## Purpose + +- Generate documents from any specified template following embedded instructions +- Support multiple document types through template-driven approach +- Enable any persona to create consistent, well-structured documents + +## Instructions + +### 1. Identify Template and Context + +- Determine which template to use (user-provided or list available for selection to user) + + - agent-config specific agents will list what docs they have available under this task, for each item consider it a unique task. So if the user had for example: + + @{example} + + - tasks: + + - [Create Document](tasks#create-doc-from-template): + + - [Prd](templates#prd-tmpl) + + - [Architecture](templates#architecture-tmpl) + + @{/example} + + you would list `Create Document PRD` and `Create Document Architecture` as tasks the agent could perform. + +- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document +- Understand the document purpose and target audience + +### 2. Determine Interaction Mode + +Confirm with the user their preferred interaction style: + +- **Incremental:** Work through chunks of the document. +- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo) + +### 3. Execute Template + +- Load specified template from `templates#*` or the /templates directory +- Follow ALL embedded LLM instructions within the template +- Process template markup according to `templates#template-format` conventions + +### 4. Template Processing Rules + +**CRITICAL: Never display template markup, LLM instructions, or examples to users** + +- Replace all {{placeholders}} with actual content +- Execute all [[LLM: instructions]] internally +- Process <> sections as needed +- Evaluate ^^CONDITION^^ blocks and include only if applicable +- Use @{examples} for guidance but never output them + +### 5. Content Generation + +- **Incremental Mode**: Present each major section for review before proceeding +- **YOLO Mode**: Generate all sections, then review complete document with user +- Apply any elicitation protocols specified in template +- Incorporate user feedback and iterate as needed + +### 6. Validation + +If template specifies a checklist: + +- Run the appropriate checklist against completed document +- Document completion status for each item +- Address any deficiencies found +- Present validation summary to user + +### 7. Final Presentation + +- Present clean, formatted content only +- Ensure all sections are complete +- DO NOT truncate or summarize content +- Begin directly with document content (no preamble) +- Include any handoff prompts specified in template + +## Key Resources + +- **Template Format:** `templates#template-format` +- **Available Templates:** All files in `templates#` directory +- **Checklists:** As specified by template or persona +- **User Preferences:** `data#technical-preferences` + +## Important Notes + +- This task is template and persona agnostic +- All specific instructions are embedded in templates +- Focus on faithful template execution and clean output +- Template markup is for AI processing only - never expose to users + +==================== END: create-doc-from-template ==================== + + ==================== START: create-frontend-architecture ==================== # Create Frontend Architecture Task @@ -734,14 +922,14 @@ Present the user with the following list of 'Advanced Reflective, Elicitation & {Instruction for AI Agent: Display the title of each numbered item below. If the user asks what a specific option means, provide a brief explanation of the action you will take, drawing from detailed descriptions tailored for the context.} -1. **Critical Self-Review & User Goal Alignment** -2. **Generate & Evaluate Alternative Design Solutions** -3. **User Journey & Interaction Stress Test (Conceptual)** -4. **Deep Dive into Design Assumptions & Constraints** -5. **Usability & Accessibility Audit Review & Probing Questions** -6. **Collaborative Ideation & UI Feature Brainstorming** -7. **Elicit 'Unforeseen User Needs' & Future Interaction Questions** -8. **Finalize this Section and Proceed.** +1. **Critical Self-Review & User Goal Alignment** +2. **Generate & Evaluate Alternative Design Solutions** +3. **User Journey & Interaction Stress Test (Conceptual)** +4. **Deep Dive into Design Assumptions & Constraints** +5. **Usability & Accessibility Audit Review & Probing Questions** +6. **Collaborative Ideation & UI Feature Brainstorming** +7. **Elicit 'Unforeseen User Needs' & Future Interaction Questions** +8. **Finalize this Section and Proceed.** After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section." @@ -750,6 +938,158 @@ REPEAT by Asking the user if they would like to perform another Reflective, Elic ==================== END: create-frontend-architecture ==================== +==================== START: create-infrastructure-architecture ==================== +# Infrastructure Architecture Creation Task + +## Purpose + +To design a comprehensive infrastructure architecture that defines all aspects of the technical infrastructure strategy, from cloud platform selection to deployment patterns. This architecture will serve as the definitive blueprint for the DevOps/Platform Engineering team to implement, ensuring consistency, security, and operational excellence across all infrastructure components. + +## Inputs + +- Product Requirements Document (PRD) +- Main System Architecture Document +- Technology Stack Document (`docs/tech-stack.md`) +- Infrastructure Guidelines (`docs/infrastructure/guidelines.md`) +- Any existing infrastructure documentation + +## Key Activities & Instructions + +### 1. Confirm Interaction Mode + +- Ask the user: "How would you like to proceed with creating the infrastructure architecture? We can work: + A. **Incrementally (Default & Recommended):** We'll go through each architectural decision and document section step-by-step. I'll present drafts, and we'll seek your feedback before moving to the next part. This is best for complex infrastructure designs. + B. **"YOLO" Mode:** I can produce a comprehensive initial draft of the infrastructure architecture for you to review more broadly first. We can then iterate on specific sections based on your feedback." +- Request the user to select their preferred mode and proceed accordingly. + +### 2. Gather Infrastructure Requirements + +- Review the product requirements document to understand business needs and scale requirements +- Analyze the main system architecture to identify infrastructure dependencies +- Document non-functional requirements (performance, scalability, reliability, security) +- Identify compliance and regulatory requirements affecting infrastructure +- Map application architecture patterns to infrastructure needs +- Cross-reference with PRD Technical Assumptions to ensure alignment with repository and service architecture decisions + +### 3. Design Infrastructure Architecture Strategy + +- **If "Incremental Mode" was selected:** + - For each major infrastructure domain: + - **a. Present Domain Purpose:** Explain what this infrastructure domain provides and its strategic importance + - **b. Present Strategic Options:** Provide 2-3 viable approaches with architectural pros and cons + - **c. Make Strategic Recommendation:** Recommend the best approach with clear architectural rationale + - **d. Incorporate Feedback:** Discuss with user and iterate based on feedback + - **e. [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options)** + - **f. Document Architectural Decision:** Record the final strategic choice with justification + +- **If "YOLO Mode" was selected:** + - Design strategic approaches for all major infrastructure domains + - Document architectural decisions and rationales + - Present comprehensive infrastructure strategy for review + - Iterate based on feedback + +### 4. Document Infrastructure Architecture Blueprint + +- Populate all sections of the infrastructure architecture template: + - **Cloud Strategy & Platform Selection** - Multi-cloud vs single cloud, platform rationale + - **Network Architecture Patterns** - VPC design, connectivity strategies, security zones + - **Compute Architecture Strategy** - Container vs serverless vs VM strategies, scaling patterns + - **Data Architecture & Storage Strategy** - Database selection, data tier strategies, backup approaches + - **Security Architecture Framework** - Zero-trust patterns, identity strategies, encryption approaches + - **Observability Architecture** - Monitoring strategies, logging patterns, alerting frameworks + - **CI/CD Architecture Patterns** - Pipeline strategies, deployment patterns, environment promotion + - **Disaster Recovery Architecture** - RTO/RPO strategies, failover patterns, business continuity + - **Cost Optimization Framework** - Resource optimization strategies, cost allocation patterns + - **Environment Strategy** - Dev/staging/prod patterns, environment isolation approaches + - **Infrastructure Evolution Strategy** - Technology migration paths, scaling roadmaps + - **Cross-team Collaboration Model** - Integration with development teams, handoff protocols + +### 5. Implementation Feasibility Review & Collaboration + +- **Architect → DevOps/Platform Feedback Loop:** + - Present architectural blueprint summary to DevOps/Platform Engineering Agent for feasibility review + - Request specific feedback on: + - **Operational Complexity:** Are the proposed patterns implementable with current tooling and expertise? + - **Resource Constraints:** Do infrastructure requirements align with available resources and budgets? + - **Security Implementation:** Are security patterns achievable with current security toolchain? + - **Operational Overhead:** Will the proposed architecture create excessive operational burden? + - **Technology Constraints:** Are selected technologies compatible with existing infrastructure? + - Document all feasibility feedback and concerns raised by DevOps/Platform Engineering Agent + - Iterate on architectural decisions based on operational constraints and feedback + - Address all critical feasibility concerns before proceeding to final architecture documentation + +### 6. Create Infrastructure Architecture Diagrams + +- Develop high-level infrastructure strategy diagrams using Mermaid +- Create network topology architecture diagrams +- Document data flow and integration architecture diagrams +- Illustrate deployment pipeline architecture patterns +- Visualize environment relationship and promotion strategies +- Design security architecture and trust boundary diagrams + +### 7. Define Implementation Handoff Strategy + +- Create clear specifications for DevOps/Platform Engineering implementation +- Define architectural constraints and non-negotiable requirements +- Specify technology selections with version requirements where critical +- Document architectural patterns that must be followed during implementation +- Create implementation validation criteria +- Prepare architectural decision records (ADRs) for key infrastructure choices + +### 8. BMAD Integration Architecture + +- Design infrastructure architecture to support other BMAD agents: + - **Development Environment Architecture** - Local development patterns, testing infrastructure + - **Deployment Architecture** - How applications from Frontend/Backend agents will be deployed + - **Integration Architecture** - How infrastructure supports cross-service communication + - Document infrastructure requirements for each BMAD agent workflow + +### 9. Architecture Review and Finalization + +- Review architecture against system architecture for alignment +- Validate infrastructure architecture supports all application requirements +- Ensure architectural decisions are implementable within project constraints +- Address any architectural gaps or inconsistencies +- Prepare comprehensive architecture handoff documentation for implementation team + +## Output + +A comprehensive infrastructure architecture document that provides: + +1. **Strategic Infrastructure Blueprint** - High-level architecture strategy and patterns +2. **Technology Selection Rationale** - Justified technology choices and architectural decisions +3. **Implementation Specifications** - Clear guidance for DevOps/Platform Engineering implementation +4. **Architectural Constraints** - Non-negotiable requirements and patterns +5. **Integration Architecture** - How infrastructure supports application architecture +6. **BMAD Workflow Support** - Infrastructure architecture supporting all agent workflows +7. **Feasibility Validation** - Documented operational feedback and constraint resolution + +**Output file**: `docs/infrastructure-architecture.md` + +## Offer Advanced Self-Refinement & Elicitation Options + +Present the user with the following list of 'Advanced Reflective, Elicitation & Brainstorming Actions'. Explain that these are optional steps to help ensure quality, explore alternatives, and deepen the understanding of the current section before finalizing it and moving on. The user can select an action by number, or choose to skip this and proceed to finalize the section. + +"To ensure the quality of the current section: **[Specific Section Name]** and to ensure its robustness, explore alternatives, and consider all angles, I can perform any of the following actions. Please choose a number (8 to finalize and proceed): + +**Advanced Reflective, Elicitation & Brainstorming Actions I Can Take:** + +1. **Alternative Architecture Strategy Evaluation** +2. **Scalability & Performance Architecture Stress Test (Theoretical)** +3. **Security Architecture & Compliance Deep Dive** +4. **Cost Architecture Analysis & Optimization Strategy Review** +5. **Operational Excellence & Reliability Architecture Assessment** +6. **Cross-Functional Integration & BMAD Workflow Analysis** +7. **Future Technology & Migration Architecture Path Exploration** +8. **Finalize this Section and Proceed.** + +After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section." + +REPEAT by Asking the user if they would like to perform another Reflective, Elicitation & Brainstorming Action UNTIL the user indicates it is time to proceed to the next section (or selects #8) + +==================== END: create-infrastructure-architecture ==================== + + ==================== START: create-next-story-task ==================== # Create Next Story Task @@ -786,7 +1126,7 @@ To identify the next logical story based on project progress and epic definition - Verify its `Status` is 'Done' (or equivalent). - If not 'Done', present an alert to the user: - ``` + ```plaintext ALERT: Found incomplete story: File: {lastEpicNum}.{lastStoryNum}.story.md Status: [current status] @@ -855,236 +1195,333 @@ To identify the next logical story based on project progress and epic definition ==================== END: create-next-story-task ==================== +==================== START: create-platform-infrastructure ==================== +# Platform Infrastructure Implementation Task + +## Purpose + +To implement a comprehensive platform infrastructure stack based on the Infrastructure Architecture Document, including foundation infrastructure, container orchestration, GitOps workflows, service mesh, and developer experience platforms. This integrated approach ensures all platform components work synergistically to provide a complete, secure, and operationally excellent platform foundation. + +## Inputs + +- **Infrastructure Architecture Document** (`docs/infrastructure-architecture.md` - from Architect Agent) +- Infrastructure Change Request (`docs/infrastructure/{ticketNumber}.change.md`) +- Infrastructure Guidelines (`docs/infrastructure/guidelines.md`) +- Technology Stack Document (`docs/tech-stack.md`) +- `infrastructure-checklist.md` (for validation) + +## Key Activities & Instructions + +### 1. Confirm Interaction Mode + +- Ask the user: "How would you like to proceed with platform infrastructure implementation? We can work: + A. **Incrementally (Default & Recommended):** We'll implement each platform layer step-by-step (Foundation → Container Platform → GitOps → Service Mesh → Developer Experience), validating integration at each stage. This ensures thorough testing and operational readiness. + B. **"YOLO" Mode:** I'll implement the complete platform stack in logical groups, with validation at major integration milestones. This is faster but requires comprehensive end-to-end testing." +- Request the user to select their preferred mode and proceed accordingly. + +### 2. Architecture Review & Implementation Planning + +- Review Infrastructure Architecture Document for complete platform specifications +- Validate platform requirements against application architecture and business needs +- Create integrated implementation roadmap with proper dependency sequencing +- Plan resource allocation, security policies, and operational procedures across all platform layers +- Document rollback procedures and risk mitigation strategies for the entire platform +- Verify the infrastructure change request is approved before beginning implementation. If not, HALT and inform the user. + +### 3. Joint Implementation Planning Session + +- **Architect ↔ DevOps/Platform Collaborative Planning:** + - **Architecture Alignment Review:** + - Confirm understanding of architectural decisions and rationale with Architect Agent + - Validate interpretation of infrastructure architecture document + - Clarify any ambiguous or unclear architectural specifications + - Document agreed-upon implementation approach for each architectural component + - **Implementation Strategy Collaboration:** + - **Technology Implementation Planning:** Collaborate on specific technology versions, configurations, and deployment patterns + - **Security Implementation Planning:** Align on security control implementation approach and validation methods + - **Integration Planning:** Plan component integration sequence and validation checkpoints + - **Operational Considerations:** Discuss operational patterns, monitoring strategies, and maintenance approaches + - **Resource Planning:** Confirm resource allocation, sizing, and optimization strategies + - **Risk & Constraint Discussion:** + - Identify potential implementation risks and mitigation strategies + - Document operational constraints that may impact architectural implementation + - Plan contingency approaches for high-risk implementation areas + - Establish escalation triggers for implementation issues requiring architectural input + - **Implementation Validation Planning:** + - Define validation criteria for each platform component and integration point + - Plan testing strategies and acceptance criteria with Architect input + - Establish quality gates and review checkpoints throughout implementation + - Document success metrics and performance benchmarks + - **Documentation & Knowledge Transfer Planning:** + - Plan documentation approach and knowledge transfer requirements + - Define operational runbooks and troubleshooting guide requirements + - Establish ongoing collaboration points for implementation support +- Complete joint planning session before beginning platform implementation. Document all planning outcomes and agreements. + +### 4. Foundation Infrastructure Implementation + +- **If "Incremental Mode" was selected:** + - **a. Foundation Infrastructure Setup:** + - Present foundation infrastructure scope and its role in the platform stack + - Implement core cloud resources, networking, storage, and security foundations + - Configure basic monitoring, logging, and operational tooling + - Validate foundation readiness for platform components + - [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) + +- **If "YOLO Mode" was selected:** + - Implement complete foundation infrastructure per architecture specifications + - Prepare foundation for all platform components simultaneously + +### 5. Container Platform Implementation + +- **If "Incremental Mode" was selected:** + - **b. Container Orchestration Platform:** + - Present container platform scope and integration with foundation infrastructure + - Install and configure container orchestration platform (Kubernetes/AKS/EKS/GKE) + - Implement RBAC, security policies, and resource management + - Configure networking, storage classes, and operational tooling + - Validate container platform functionality and readiness for applications + - [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) + +- **If "YOLO Mode" was selected:** + - Deploy complete container platform integrated with foundation infrastructure + +### 6. GitOps Workflows Implementation + +- **If "Incremental Mode" was selected:** + - **c. GitOps Configuration Management:** + - Present GitOps scope and integration with container platform + - Implement GitOps operators and configuration management systems + - Configure repository structures, sync policies, and environment promotion + - Set up policy enforcement and drift detection + - Validate GitOps workflows and configuration management + - [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) + +- **If "YOLO Mode" was selected:** + - Deploy complete GitOps stack integrated with container and foundation platforms + +### 7. Service Mesh Implementation + +- **If "Incremental Mode" was selected:** + - **d. Service Communication Platform:** + - Present service mesh scope and integration with existing platform layers + - Install and configure service mesh control and data planes + - Implement traffic management, security policies, and observability + - Configure service discovery, load balancing, and communication policies + - Validate service mesh functionality and inter-service communication + - [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) + +- **If "YOLO Mode" was selected:** + - Deploy complete service mesh integrated with all platform components + +### 8. Developer Experience Platform Implementation + +- **If "Incremental Mode" was selected:** + - **e. Developer Experience Platform:** + - Present developer platform scope and integration with complete platform stack + - Implement developer portals, self-service capabilities, and golden path templates + - Configure platform APIs, automation workflows, and productivity tooling + - Set up developer onboarding and documentation systems + - Validate developer experience and workflow integration + - [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) + +- **If "YOLO Mode" was selected:** + - Deploy complete developer experience platform integrated with all infrastructure + +### 9. Platform Integration & Security Hardening + +- Implement end-to-end security policies across all platform layers +- Configure integrated monitoring and observability for the complete platform stack +- Set up platform-wide backup, disaster recovery, and business continuity procedures +- Implement cost optimization and resource management across all platform components +- Configure platform-wide compliance monitoring and audit logging +- Validate complete platform security posture and operational readiness + +### 10. Platform Operations & Automation + +- Set up comprehensive platform monitoring, alerting, and operational dashboards +- Implement automated platform maintenance, updates, and lifecycle management +- Configure platform health checks, performance optimization, and capacity planning +- Set up incident response procedures and operational runbooks for the complete platform +- Implement platform SLA monitoring and service level management +- Validate operational excellence and platform reliability + +### 11. BMAD Workflow Integration + +- Verify complete platform supports all BMAD agent workflows: + - **Frontend/Backend Development** - Test complete application development and deployment workflows + - **Infrastructure Development** - Validate infrastructure-as-code development and deployment + - **Cross-Agent Collaboration** - Ensure seamless collaboration between all agent types + - **CI/CD Integration** - Test complete continuous integration and deployment pipelines + - **Monitoring & Observability** - Verify complete application and infrastructure monitoring +- Document comprehensive integration verification results and workflow optimizations + +### 12. Platform Validation & Knowledge Transfer + +- Execute comprehensive platform testing with realistic workloads and scenarios +- Validate against all sections of infrastructure checklist for complete platform +- Perform security scanning, compliance verification, and performance testing +- Test complete platform disaster recovery and resilience procedures +- Complete comprehensive knowledge transfer to operations and development teams +- Document complete platform configuration, operational procedures, and troubleshooting guides +- Update infrastructure change request status to reflect completion + +### 13. Implementation Review & Architect Collaboration + +- **Post-Implementation Collaboration with Architect:** + - **Implementation Validation Review:** + - Present implementation outcomes against architectural specifications + - Document any deviations from original architecture and rationale + - Validate that implemented platform meets architectural intent and requirements + - **Lessons Learned & Architecture Feedback:** + - Provide feedback to Architect Agent on implementation experience + - Document implementation challenges and successful patterns + - Recommend architectural improvements for future implementations + - Share operational insights that could influence future architectural decisions + - **Knowledge Transfer & Documentation Review:** + - Review operational documentation with Architect for completeness and accuracy + - Ensure architectural decisions are properly documented in operational guides + - Plan ongoing collaboration for platform evolution and maintenance +- Document collaboration outcomes and recommendations for future architecture-implementation cycles + +### 14. Platform Handover & Continuous Improvement + +- Establish platform monitoring and continuous improvement processes +- Set up feedback loops with development teams and platform users +- Plan platform evolution roadmap and technology upgrade strategies +- Implement platform metrics and KPI tracking for operational excellence +- Create platform governance and change management procedures +- Establish platform support and maintenance responsibilities + +## Output + +Fully operational and integrated platform infrastructure with: + +1. **Complete Foundation Infrastructure** - Cloud resources, networking, storage, and security foundations +2. **Production-Ready Container Platform** - Orchestration with proper security, monitoring, and resource management +3. **Operational GitOps Workflows** - Version-controlled operations with automated sync and policy enforcement +4. **Service Mesh Communication Platform** - Advanced service communication with security and observability +5. **Developer Experience Platform** - Self-service capabilities with productivity tooling and golden paths +6. **Integrated Platform Operations** - Comprehensive monitoring, automation, and operational excellence +7. **BMAD Workflow Support** - Verified integration supporting all agent development and deployment patterns +8. **Platform Documentation** - Complete operational guides, troubleshooting resources, and developer documentation +9. **Joint Planning Documentation** - Collaborative planning outcomes and architectural alignment records +10. **Implementation Review Results** - Post-implementation validation and architect collaboration outcomes + +## Offer Advanced Self-Refinement & Elicitation Options + +Present the user with the following list of 'Advanced Reflective, Elicitation & Brainstorming Actions'. Explain that these are optional steps to help ensure quality, explore alternatives, and deepen the understanding of the current platform layer before finalizing it and moving to the next. The user can select an action by number, or choose to skip this and proceed. + +"To ensure the quality of the current platform layer: **[Specific Platform Layer Name]** and to ensure its robustness, explore alternatives, and consider all angles, I can perform any of the following actions. Please choose a number (8 to finalize and proceed): + +**Advanced Reflective, Elicitation & Brainstorming Actions I Can Take:** + +1. **Platform Layer Security Hardening & Integration Review** +2. **Performance Optimization & Resource Efficiency Analysis** +3. **Operational Excellence & Automation Enhancement** +4. **Platform Integration & Dependency Validation** +5. **Developer Experience & Workflow Optimization** +6. **Disaster Recovery & Platform Resilience Testing (Theoretical)** +7. **BMAD Agent Workflow Integration & Cross-Platform Testing** +8. **Finalize this Platform Layer and Proceed.** + +After I perform the selected action, we can discuss the outcome and decide on any further improvements for this platform layer." + +REPEAT by Asking the user if they would like to perform another Reflective, Elicitation & Brainstorming Action UNTIL the user indicates it is time to proceed to the next platform layer (or selects #8) + +==================== END: create-platform-infrastructure ==================== + + ==================== START: create-prd ==================== # PRD Generate Task ## Purpose -- Transform inputs into core product definition documents conforming to the `prd-tmpl` template. -- Define clear MVP scope focused on essential functionality. -- Provide foundation for Architect and eventually AI dev agents. - -Remember as you follow the upcoming instructions: - -- Your documents form the foundation for the entire development process. -- Output will be directly used by the Architect to create an architecture document and solution designs to make definitive technical decisions. -- Your epics/stories will ultimately be transformed into development tasks. -- While you focus on the "what" not "how", be precise enough to support a logical sequential order of operations that once later further details can logically be followed where a story will complete what is needed. +- Transform inputs into core product definition documents conforming to a PRD template +- Define clear MVP scope focused on essential functionality +- Provide foundation for Architect and Design Architect to help create technical artifacts which will in turn later draft further details for very junior engineers or simple dev ai agents. ## Instructions -### 1. Define Project Workflow Context +### 1. Review Inputs -- Before PRD generation, ask the user to choose their intended workflow: +Review all provided inputs including project brief, research documents, prd template and user ideas to guide PRD generation. - A. **Outcome Focused (Default):** (Agent defines outcome-focused User Stories, leaving detailed technical "how" for Architect/Scrum Master. Capture nuances as "Notes for Architect/Scrum Master in the Prompt for Architect.") +### 2. Determine Interaction Mode - B. **Very Technical (Not Recommended):** (Agent adopts a "solution-aware" stance, providing more detailed, implementation-aware Acceptance Criteria to bridge to development, potentially with no architect involved at all, instead filling in all of the technical details. \When this workflow is selected, you are also responsible for collaboratively defining and documenting key technical foundations—such as technology stack choices and proposed application structure—directly within a new, dedicated section of the PRD template titled '[OPTIONAL: For Simplified PM-to-Development Workflow Only] Core Technical Decisions & Application Structure'.\) +Confirm with the user their preferred interaction style: -- Explain this choice sets a default detail level, which can be fine-tuned later per story/epic. +- **Incremental:** Work through sections one at a time via chat messages as defined in the template. -### 2. Determine Interaction Mode (for PRD Structure & Detail) +- **YOLO Mode:** Draft the complete PRD making assumptions as necessary. Present full document at once, noting which sections required assumptions. -- Confirm with the user their preferred interaction style for creating the PRD if unknown - INCREMENTAL or YOLO?: - - **Incrementally (Default):** Address PRD sections sequentially, seeking feedback on each. For Epics/Stories: first present the ordered Epic list for approval, then detail stories for each Epic one by one. - - **"YOLO" Mode:** Draft a more comprehensive PRD (or significant portions with multiple sections, epics, and stories) for a single, larger review. +### 3. Execute Template -### 3. Review inputs provided +- Use the `prd-tmpl` template (or user-specified alternative template) +- Follow all embedded LLM instructions within the template +- Template contains section-specific guidance and examples -Review the inputs provided so far, such as a project brief, any research, and user input and ideas. +### 4. Template Processing Notes -### 4. Process PRD Sections +- **Incremental Mode**: Present each section for review before proceeding +- **YOLO Mode**: Generate all sections, then review with user -Inform the user we will work through the PRD sections in order 1 at a time (if not YOLO) - the template contains your instructions for each section. After presenting the section to the user, also [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) +Process all template elements according to `templates#template-format` conventions. -When working on the "Technical Assumptions" section of the PRD, explicitly guide the user through discussing and deciding on the repository structure (Monorepo vs. Polyrepo) and the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo). Emphasize that this is a critical decision point that will be formally documented here with its rationale, impacting MVP scope and informing the Architect. Ensure this decision is captured in the PRD's `Technical Assumptions` and then reiterated in the `Initial Architect Prompt` section of the PRD. +**CRITICAL: Never display or output template markup formatting, LLM instructions or examples - they MUST be used by you the agent only, AND NEVER shown to users in chat or document output** -Specifically for "Simplified PM-to-Development Workflow": -After discussing initial PRD sections (like Problem, Goals, User Personas) and before or in parallel with defining detailed Epics and Stories, you must introduce and populate the "[OPTIONAL: For Simplified PM-to-Development Workflow Only] Core Technical Decisions & Application Structure" section of the PRD. +**Content Presentation Guidelines:** - When doing so, first check if a `docs/technical-preferences.md` file exists or has been provided. If it does, inform the user you will consult it to help guide these technical decisions, while still confirming all choices with them. Ask targeted questions such as: +- Present only the final, clean content to users +- Replace template variables with actual project-specific content +- Process all conditional logic internally - show only relevant sections +- For Canvas mode: Update the document with clean, formatted content only -1. "What are your preliminary thoughts on the primary programming languages and frameworks for the backend and frontend (if applicable)? (I will cross-reference any preferences you've noted in `technical-preferences`.)" -2. "Which database system are you considering? (Checking preferences...)" -3. "Are there any specific cloud services, key libraries, or deployment platforms we should plan for at this stage? (Checking preferences...)" -4. "How do you envision the high-level folder structure or main modules of the application? Could you describe the key components and their responsibilities? (I'll consider any structural preferences noted.)" -5. "Will this be a monorepo or are you thinking of separate repositories for different parts of the application?" - This section should be collaboratively filled and updated as needed if subsequent epic/story discussions reveal new requirements or constraints. +### 7. Prepare Handoffs - +Based on PRD content, prepare appropriate next-step prompts: - +**If UI Component Exists:** -For the Epic and Story Section (if in Incremental mode for these), prepare in memory what you think the initial epic and story list so we can work through this incrementally, use all of the information you have learned that has been provided thus far to follow the guidelines in the section below [Guiding Principles for Epic and User Story Generation](https://www.google.com/search?q=%23guiding-principles-for-epic-and-user-story-generation). +1. Add Design Architect prompt in designated template section +2. Recommend: User engages Design Architect first for UI/UX Specification +3. Then proceed to Architect with enriched PRD - +**If No UI Component:** -#### 4A. Epic Presentation and Drafting Strategy +- Add Architect prompt in designated template section +- Recommend proceeding directly to Architect -You will first present the user with the epic titles and descriptions, so that the user can determine if it is correct and what is expected, or if there is a major epic missing. +### 8. Validate with Checklist -#### 4B. Story Generation and Review within Epics (Incremental Mode) +- Run the `pm-checklist` against completed PRD +- Document completion status for each checklist item +- Present summary by section, address any deficiencies +- Generate final checklist report with findings and resolutions -**Once the Epic List is approved, THEN for each Epic, you will proceed as follows:** +### 9. Final Presentation -i. **Draft All Stories for the Current Epic:** Based on the Epic's goal and your discussions, draft all the necessary User Stories for this Epic, following the "Guiding Principles for Epic and User Story Generation". -ii. **Perform Internal Story Analysis & Propose Order:** Before presenting the stories for detailed review, you will internally: -a. **Re-evaluate for Cross-Cutting Concerns:** Ensure no drafted stories should actually be ACs or notes within other stories, as per the guiding principle. Make necessary adjustments. -b. **Analyze for Logical Sequence & Dependencies:** For all stories within this Epic, determine their logical implementation order. Identify any direct prerequisite stories (e.g., "Story X must be completed before Story Y because Y consumes the output of X"). -c. **Formulate a Rationale for the Order:** Prepare a brief explanation for why the proposed order is logical. -iii. **Present Proposed Story Set & Order for the Epic:** Present to the user: -a. The complete list of (potentially revised) User Stories for the Epic. -b. The proposed sequence for these stories. -c. Your brief rationale for the sequencing and any key dependencies you've noted (e.g., "I suggest this order because Story 2 builds upon the data prepared in Story 1, and Story 3 then uses the results from Story 2."). -iv. **Collaborative Review of Sequence & Story Shells:** Discuss this proposed structure and sequence with the user. Make any adjustments to the story list or their order based on user feedback. -v. Once the overall structure and sequence of stories for the Epic are agreed upon, THEN you will work with the user to review the details (description, Acceptance Criteria) of each story in the agreed-upon sequence for that Epic. -vi. [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options) +**General Guidelines:** -#### 4C. Present Complete Draft +- Present complete documents in clean, full format +- DO NOT truncate unchanged information +- Begin directly with content (no introductory text needed) +- Ensure all template sections are properly filled +- **NEVER show template markup, instructions, or processing directives to users** -Present the user with the complete full draft once all sections are completed (or as per YOLO mode interaction). +## Key Resources -#### 4D. UI Component Handoff Note +- **Default Template:** `templates#prd-tmpl` +- **Validation:** `checklists#pm-checklist` +- **User Preferences:** `data#technical-preferences` +- **Elicitation Protocol:** `tasks#advanced-elicitation` -If there is a UI component to this PRD, you can inform the user that the Design Architect should take this final output. +## Important Notes -### 5\. Checklist Assessment - -- Use the `pm-checklist` to consider each item in the checklist is met (or n/a) against the PRD. -- Document completion status for each item. -- Present the user with summary of each section of the checklist before going to the next section. -- Address deficiencies with user for input or suggested updates or corrections. -- Once complete and address, output the final checklist with all the checked items or skipped items, the section summary table, and any final notes. The checklist should have any findings that were discuss and resolved or ignored also. This will be a nice artifact for the user to keep. - -### 6\. Produce the PRD - -Produce the PRD with PM Prompt per the `prd-tmpl` utilizing the following guidance: - -**General Presentation & Content:** - -- Present Project Briefs (drafts or final) in a clean, full format. -- Crucially, DO NOT truncate information that has not changed from a previous version. -- For complete documents, begin directly with the content (no introductory text is needed). - - -**Next Steps for UI/UX Specification (If Applicable):** - -- If the product described in this PRD includes a user interface: - - 1. **Include Design Architect Prompt in PRD:** You will add a dedicated section in the PRD document you are producing, specifically at the location marked `(END Checklist START Design Architect UI/UX Specification Mode Prompt)` (as per the `prd-tmpl` structure). This section will contain a prompt for the **Design Architect** agent. - - - The prompt should clearly state that the Design Architect is to operate in its **'UI/UX Specification Mode'**. - - - It should instruct the Design Architect to use this PRD as primary input to collaboratively define and document detailed UI/UX specifications. This might involve creating/populating a `front-end-spec-tmpl` and ensuring key UI/UX considerations are integrated or referenced back into the PRD to enrich it. - - - Example prompt text to insert: - - ```markdown - ## Prompt for Design Architect (UI/UX Specification Mode) - - **Objective:** Elaborate on the UI/UX aspects of the product defined in this PRD. - **Mode:** UI/UX Specification Mode - **Input:** This completed PRD document. - **Key Tasks:** - - 1. Review the product goals, user stories, and any UI-related notes herein. - 2. Collaboratively define detailed user flows, wire-frames (conceptual), and key screen mockups/descriptions. - 3. Specify usability requirements and accessibility considerations. - 4. Populate or create the `front-end-spec-tmpl` document. - 5. Ensure that this PRD is updated or clearly references the detailed UI/UX specifications derived from your work, so that it provides a comprehensive foundation for subsequent architecture and development phases. - - Please guide the user through this process to enrich the PRD with detailed UI/UX specifications. - ``` - - 2. **Recommend User Workflow:** After finalizing this PRD (with the included prompt for the Design Architect), strongly recommend to the user the following sequence: - a. First, engage the **Design Architect** agent (using the prompt you've embedded in the PRD) to operate in **'UI/UX Specification Mode'**. Explain that this step is crucial for detailing the user interface and experience, and the output (e.g., a populated `front-end-spec-tmpl` and potentially updated PRD sections) will be vital. - b. Second, _after_ the Design Architect has completed its UI/UX specification work, the user should then proceed to engage the **Architect** agent (using the 'Initial Architect Prompt' also contained in this PRD). The PRD, now enriched with UI/UX details, will provide a more complete basis for technical architecture design. - -- If the product does not include a user interface, you will simply recommend proceeding to the Architect agent using the 'Initial Architect Prompt' in the PRD. - - -## Guiding Principles for Epic and User Story Generation - -### I. Strategic Foundation: Define Core Value & MVP Scope Rigorously - -Understand & Clarify Core Needs: Start by deeply understanding and clarifying the core problem this product solves, the essential needs of the defined User Personas (or system actors), and the key business objectives for the Minimum Viable Product (MVP). -Challenge Scope Relentlessly: Actively challenge all requested features and scope at every stage. For each potential feature or story, rigorously ask, "Does this directly support the core MVP goals and provide significant value to a target User Persona?" Clearly identify and defer non-essential functionalities to a Post-MVP backlog. - -### II. Structuring the Work: Value-Driven Epics & Logical Sequencing - -Organize into Deployable, Value-Driven Epics: Structure the MVP scope into Epics. Each Epic must be designed to deliver a significant, end-to-end, and fully deployable increment of testable functionality that provides tangible value to the user or business. Epics should represent logical functional blocks or coherent user journeys. - -Logical Epic Sequencing & Foundational Work: -Ensure the sequence of Epics follows a logical implementation order, making dependencies between Epics clear and explicitly managed. -The first Epic must always establish the foundational project infrastructure (e.g., initial app setup, Git repository, CI/CD pipeline, core cloud service configurations, basic user authentication shell if needed universally) necessary to support its own deployable functionality and that of subsequent Epics. -Ensure Logical Story Sequencing and Dependency Awareness within Epics: -After initially drafting all User Stories for an Epic, but before detailed review with the user, you (the AI Agent executing this task) must explicitly perform an internal review to establish a logical sequence for these stories. -For each story, identify if it has direct prerequisite stories within the same Epic or from already completed Epics. -Propose a clear story order to the user, explaining the rationale based on these dependencies (e.g., "Story X needs to be done before Story Y because..."). Make significant dependencies visible, perhaps as a note within the story description. - -### III. Crafting Effective User Stories: Vertical Slices Focused on Value & Clarity - -Define Stories as "Vertical Slices": Within each Epic, define User Stories as "vertical slices". This means each story must deliver a complete piece of functionality that achieves a specific user or system goal, potentially cutting through all necessary layers (e.g., UI, API, business logic, database). -Focus on "What" and "Why," Not "How": -Stories will primarily focus on the functional outcome, the user value ("what"), and the reason ("why"). Avoid detailing technical implementation ("how") in the story's main description. -The "As a {specific User Persona/system actor}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}" format is standard. Be precise and consistent when defining the '{specific User Persona/system actor}', ensuring it aligns with defined personas. -Ensure User Value, Not Just Technical Tasks: User Stories must articulate clear user or business value. Avoid creating stories that are purely technical tasks (e.g., "Set up database," "Refactor module X"), unless they are part of the foundational infrastructure Epic or are essential enabling tasks that are explicitly linked to, and justified by, a user-facing story that delivers value. -Appropriate Sizing & Strive for Independence: -Ensure User Stories are appropriately sized for a typical development iteration (i.e., can be completed by the team in one sprint/iteration). -If a vertically sliced story is too large or complex, work with the user to split it into smaller, still valuable, and still vertically sliced increments. -Where feasible, define stories so they can be developed, tested, and potentially delivered independently of others. If dependencies are unavoidable, they must be clearly identified and managed through sequencing. - -### IV. Detailing Stories: Comprehensive Acceptance Criteria & Developer Enablement - -Clear, Comprehensive, and Testable Acceptance Criteria (ACs): -Every User Story will have detailed, unambiguous, and testable Acceptance Criteria. -ACs precisely define what "done" means for that story from a functional perspective and serve as the basis for verification. -Where a specific Non-Functional Requirement (NFR) from the PRD (e.g., a particular performance target for a specific action, a security constraint for handling certain data) is critical to a story, ensure it is explicitly captured or clearly referenced within its Acceptance Criteria. -Integrate Developer Enablement & Iterative Design into Stories: -Local Testability (CLI): For User Stories involving backend processing or data components, ensure the ACs consider or specify the ability for developers to test that functionality locally (e.g., via CLI commands, local service instances). -Iterative Schema Definition: Database schema changes (new tables, columns) should be introduced iteratively within the User Stories that functionally require them, rather than defining the entire schema upfront. -Upfront UI/UX Standards (if UI applicable): For User Stories with a UI component, ACs should explicitly state requirements regarding look and feel, responsiveness, and adherence to chosen frameworks/libraries (e.g., Tailwind CSS, shadcn/ui) from the start. - -### V. Managing Complexity: Addressing Cross-Cutting Concerns Effectively - -Critically Evaluate for Cross-Cutting Concerns: -Before finalizing a User Story, evaluate if the described functionality is truly a discrete, user-facing piece of value or if it represents a cross-cutting concern (e.g., a specific logging requirement, a UI theme element used by many views, a core technical enabler for multiple other stories, a specific aspect of error handling). -If a piece of functionality is identified as a cross-cutting concern: -a. Avoid creating a separate User Story for it unless it delivers standalone, testable user value. -b. Instead, integrate the requirement as specific Acceptance Criteria within all relevant User Stories it impacts. -c. Alternatively, if it's a pervasive technical enabler or a non-functional requirement that applies broadly, document it clearly within the relevant PRD section (e.g., 'Non Functional Requirements', 'Technical Assumptions'), or as a note for the Architect within the story descriptions if highly specific. - -Your aim is to ensure User Stories remain focused on delivering measurable user value, while still capturing all necessary technical and functional details appropriately. - -### VI. Ensuring Quality & Smooth Handoff - -Maintain Clarity for Handoff and Architectural Freedom: User Stories, their descriptions, and Acceptance Criteria must be detailed enough to provide the Architect with a clear and comprehensive understanding of "what is required," while allowing for architectural flexibility on the "how." -Confirm "Ready" State: Before considering an Epic's stories complete, ensure each story is effectively "ready" for subsequent architectural review or development planning – meaning it's clear, understandable, testable, its dependencies are noted, and any foundational work (like from the first epic) is accounted for. - -## Offer Advanced Self-Refinement & Elicitation Options - -(This section is called when needed prior to this) - -Present the user with the following list of 'Advanced Reflective, Elicitation & Brainstorming Actions'. Explain that these are optional steps to help ensure quality, explore alternatives, and deepen the understanding of the current section before finalizing it and moving on. The user can select an action by number, or choose to skip this and proceed to finalize the section. - -"To ensure the quality of the current section: **[Specific Section Name]** and to ensure its robustness, explore alternatives, and consider all angles, I can perform any of the following actions. Please choose a number (8 to finalize and proceed): - -**Advanced Reflective, Elicitation & Brainstorming Actions I Can Take:** - -{Instruction for AI Agent: Display the title of each numbered item below. If the user asks what a specific option means, provide a brief explanation of the action you will take, drawing from detailed descriptions tailored for the context.} - -1. **Critical Self-Review & User Goal Alignment** -2. **Generate & Evaluate Alternative Design Solutions** -3. **User Journey & Interaction Stress Test (Conceptual)** -4. **Deep Dive into Design Assumptions & Constraints** -5. **Usability & Accessibility Audit Review & Probing Questions** -6. **Collaborative Ideation & UI Feature Brainstorming** -7. **Elicit 'Unforeseen User Needs' & Future Interaction Questions** -8. **Finalize this Section and Proceed.** - -After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section." - -REPEAT by Asking the user if they would like to perform another Reflective, Elicitation & Brainstorming Action UNIT the user indicates it is time to proceed ot the next section (or selects #8) +- This task is template-agnostic - users may specify custom templates +- All detailed instructions are embedded in templates, not this task file +- Focus on orchestration and workflow +- **Template markup is for AI processing only - users should never see output indicators from templates#template-format** ==================== END: create-prd ==================== @@ -1367,3 +1804,325 @@ Would you like to proceed with library indexing? Please provide the required inp ==================== END: library-indexing-task ==================== +==================== START: review-infrastructure ==================== +# Infrastructure Review Task + +## Purpose + +To conduct a thorough review of existing infrastructure to identify improvement opportunities, security concerns, and alignment with best practices. This task helps maintain infrastructure health, optimize costs, and ensure continued alignment with organizational requirements. + +## Inputs + +- Current infrastructure documentation +- Monitoring and logging data +- Recent incident reports +- Cost and performance metrics +- `infrastructure-checklist.md` (primary review framework) + +## Key Activities & Instructions + +### 1. Confirm Interaction Mode + +- Ask the user: "How would you like to proceed with the infrastructure review? We can work: + A. **Incrementally (Default & Recommended):** We'll work through each section of the checklist methodically, documenting findings for each item before moving to the next section. This provides a thorough review. + B. **"YOLO" Mode:** I can perform a rapid assessment of all infrastructure components and present a comprehensive findings report. This is faster but may miss nuanced details." +- Request the user to select their preferred mode and proceed accordingly. + +### 2. Prepare for Review + +- Gather and organize current infrastructure documentation +- Access monitoring and logging systems for operational data +- Review recent incident reports for recurring issues +- Collect cost and performance metrics +- Establish review scope and boundaries with the user before proceeding + +### 3. Conduct Systematic Review + +- **If "Incremental Mode" was selected:** + - For each section of the infrastructure checklist: + - **a. Present Section Focus:** Explain what aspects of infrastructure this section reviews + - **b. Work Through Items:** Examine each checklist item against current infrastructure + - **c. Document Current State:** Record how current implementation addresses or fails to address each item + - **d. Identify Gaps:** Document improvement opportunities with specific recommendations + - **e. [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options)** + - **f. Section Summary:** Provide an assessment summary before moving to the next section + +- **If "YOLO Mode" was selected:** + - Rapidly assess all infrastructure components + - Document key findings and improvement opportunities + - Present a comprehensive review report + - After presenting the full review in YOLO mode, you MAY still offer the 'Advanced Reflective & Elicitation Options' menu for deeper investigation of specific areas with issues. + +### 4. Generate Findings Report + +- Summarize review findings by category (Security, Performance, Cost, Reliability, etc.) +- Prioritize identified issues (Critical, High, Medium, Low) +- Document recommendations with estimated effort and impact +- Create an improvement roadmap with suggested timelines +- Highlight cost optimization opportunities + +### 5. BMAD Integration Assessment + +- Evaluate how current infrastructure supports other BMAD agents: + - **Development Support:** Assess how infrastructure enables Frontend Dev (Mira), Backend Dev (Enrique), and Full Stack Dev workflows + - **Product Alignment:** Verify infrastructure supports PRD requirements from Product Owner (Oli) + - **Architecture Compliance:** Check if implementation follows Architect (Alphonse) decisions + - Document any gaps in BMAD integration + +### 6. Architectural Escalation Assessment + +- **DevOps/Platform → Architect Escalation Review:** + - Evaluate review findings for issues requiring architectural intervention: + - **Technical Debt Escalation:** + - Identify infrastructure technical debt that impacts system architecture + - Document technical debt items that require architectural redesign vs. operational fixes + - Assess cumulative technical debt impact on system maintainability and scalability + - **Performance/Security Issue Escalation:** + - Identify performance bottlenecks that require architectural solutions (not just operational tuning) + - Document security vulnerabilities that need architectural security pattern changes + - Assess capacity and scalability issues requiring architectural scaling strategy revision + - **Technology Evolution Escalation:** + - Identify outdated technologies that need architectural migration planning + - Document new technology opportunities that could improve system architecture + - Assess technology compatibility issues requiring architectural integration strategy changes + - **Escalation Decision Matrix:** + - **Critical Architectural Issues:** Require immediate Architect Agent involvement for system redesign + - **Significant Architectural Concerns:** Recommend Architect Agent review for potential architecture evolution + - **Operational Issues:** Can be addressed through operational improvements without architectural changes + - **Unclear/Ambiguous Issues:** When escalation level is uncertain, consult with user for guidance and decision + - Document escalation recommendations with clear justification and impact assessment + - If escalation classification is unclear or ambiguous, HALT and ask user for guidance on appropriate escalation level and approach + +### 7. Present and Plan + +- Prepare an executive summary of key findings +- Create detailed technical documentation for implementation teams +- Develop an action plan for critical and high-priority items +- **Prepare Architectural Escalation Report** (if applicable): + - Document all findings requiring Architect Agent attention + - Provide specific recommendations for architectural changes or reviews + - Include impact assessment and priority levels for architectural work + - Prepare escalation summary for Architect Agent collaboration +- Schedule follow-up reviews for specific areas +- Present findings in a way that enables clear decision-making on next steps and escalation needs. + +### 8. Execute Escalation Protocol + +- **If Critical Architectural Issues Identified:** + - **Immediate Escalation to Architect Agent:** + - Present architectural escalation report with critical findings + - Request architectural review and potential redesign for identified issues + - Collaborate with Architect Agent on priority and timeline for architectural changes + - Document escalation outcomes and planned architectural work +- **If Significant Architectural Concerns Identified:** + - **Scheduled Architectural Review:** + - Prepare detailed technical findings for Architect Agent review + - Request architectural assessment of identified concerns + - Schedule collaborative planning session for potential architectural evolution + - Document architectural recommendations and planned follow-up +- **If Only Operational Issues Identified:** + - Proceed with operational improvement planning without architectural escalation + - Monitor for future architectural implications of operational changes +- **If Unclear/Ambiguous Escalation Needed:** + - **User Consultation Required:** + - Present unclear findings and escalation options to user + - Request user guidance on appropriate escalation level and approach + - Document user decision and rationale for escalation approach + - Proceed with user-directed escalation path +- All critical architectural escalations must be documented and acknowledged by Architect Agent before proceeding with implementation + +## Output + +A comprehensive infrastructure review report that includes: + +1. **Current state assessment** for each infrastructure component +2. **Prioritized findings** with severity ratings +3. **Detailed recommendations** with effort/impact estimates +4. **Cost optimization opportunities** +5. **BMAD integration assessment** +6. **Architectural escalation assessment** with clear escalation recommendations +7. **Action plan** for critical improvements and architectural work +8. **Escalation documentation** for Architect Agent collaboration (if applicable) + +## Offer Advanced Self-Refinement & Elicitation Options + +Present the user with the following list of 'Advanced Reflective, Elicitation & Brainstorming Actions'. Explain that these are optional steps to help ensure quality, explore alternatives, and deepen the understanding of the current section before finalizing it and moving on. The user can select an action by number, or choose to skip this and proceed to finalize the section. + +"To ensure the quality of the current section: **[Specific Section Name]** and to ensure its robustness, explore alternatives, and consider all angles, I can perform any of the following actions. Please choose a number (8 to finalize and proceed): + +**Advanced Reflective, Elicitation & Brainstorming Actions I Can Take:** + +1. **Root Cause Analysis & Pattern Recognition** +2. **Industry Best Practice Comparison** +3. **Future Scalability & Growth Impact Assessment** +4. **Security Vulnerability & Threat Model Analysis** +5. **Operational Efficiency & Automation Opportunities** +6. **Cost Structure Analysis & Optimization Strategy** +7. **Compliance & Governance Gap Assessment** +8. **Finalize this Section and Proceed.** + +After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section." + +REPEAT by Asking the user if they would like to perform another Reflective, Elicitation & Brainstorming Action UNTIL the user indicates it is time to proceed to the next section (or selects #8) + +==================== END: review-infrastructure ==================== + + +==================== START: validate-infrastructure ==================== +# Infrastructure Validation Task + +## Purpose + +To comprehensively validate platform infrastructure changes against security, reliability, operational, and compliance requirements before deployment. This task ensures all platform infrastructure meets organizational standards, follows best practices, and properly integrates with the broader BMAD ecosystem. + +## Inputs + +- Infrastructure Change Request (`docs/infrastructure/{ticketNumber}.change.md`) +- **Infrastructure Architecture Document** (`docs/infrastructure-architecture.md` - from Architect Agent) +- Infrastructure Guidelines (`docs/infrastructure/guidelines.md`) +- Technology Stack Document (`docs/tech-stack.md`) +- `infrastructure-checklist.md` (primary validation framework - 16 comprehensive sections) + +## Key Activities & Instructions + +### 1. Confirm Interaction Mode + +- Ask the user: "How would you like to proceed with platform infrastructure validation? We can work: + A. **Incrementally (Default & Recommended):** We'll work through each section of the checklist step-by-step, documenting compliance or gaps for each item before moving to the next section. This is best for thorough validation and detailed documentation of the complete platform stack. + B. **"YOLO" Mode:** I can perform a rapid assessment of all checklist items and present a comprehensive validation report for review. This is faster but may miss nuanced details that would be caught in the incremental approach." +- Request the user to select their preferred mode (e.g., "Please let me know if you'd prefer A or B."). +- Once the user chooses, confirm the selected mode and proceed accordingly. + +### 2. Initialize Platform Validation + +- Review the infrastructure change documentation to understand platform implementation scope and purpose +- Analyze the infrastructure architecture document for platform design patterns and compliance requirements +- Examine infrastructure guidelines for organizational standards across all platform components +- Prepare the validation environment and tools for comprehensive platform testing +- Verify the infrastructure change request is approved for validation. If not, HALT and inform the user. + +### 3. Architecture Design Review Gate + +- **DevOps/Platform → Architect Design Review:** + - Conduct systematic review of infrastructure architecture document for implementability + - Evaluate architectural decisions against operational constraints and capabilities: + - **Implementation Complexity:** Assess if proposed architecture can be implemented with available tools and expertise + - **Operational Feasibility:** Validate that operational patterns are achievable within current organizational maturity + - **Resource Availability:** Confirm required infrastructure resources are available and within budget constraints + - **Technology Compatibility:** Verify selected technologies integrate properly with existing infrastructure + - **Security Implementation:** Validate that security patterns can be implemented with current security toolchain + - **Maintenance Overhead:** Assess ongoing operational burden and maintenance requirements + - Document design review findings and recommendations: + - **Approved Aspects:** Document architectural decisions that are implementable as designed + - **Implementation Concerns:** Identify architectural decisions that may face implementation challenges + - **Required Modifications:** Recommend specific changes needed to make architecture implementable + - **Alternative Approaches:** Suggest alternative implementation patterns where needed + - **Collaboration Decision Point:** + - If **critical implementation blockers** identified: HALT validation and escalate to Architect Agent for architectural revision + - If **minor concerns** identified: Document concerns and proceed with validation, noting required implementation adjustments + - If **architecture approved**: Proceed with comprehensive platform validation + - All critical design review issues must be resolved before proceeding to detailed validation + +### 4. Execute Comprehensive Platform Validation Process + +- **If "Incremental Mode" was selected:** + - For each section of the infrastructure checklist (Sections 1-16): + - **a. Present Section Purpose:** Explain what this section validates and why it's important for platform operations + - **b. Work Through Items:** Present each checklist item, guide the user through validation, and document compliance or gaps + - **c. Evidence Collection:** For each compliant item, document how compliance was verified + - **d. Gap Documentation:** For each non-compliant item, document specific issues and proposed remediation + - **e. Platform Integration Testing:** For platform engineering sections (13-16), validate integration between platform components + - **f. [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options)** + - **g. Section Summary:** Provide a compliance percentage and highlight critical findings before moving to the next section + +- **If "YOLO Mode" was selected:** + - Work through all checklist sections rapidly (foundation infrastructure sections 1-12 + platform engineering sections 13-16) + - Document compliance status for each item across all platform components + - Identify and document critical non-compliance issues affecting platform operations + - Present a comprehensive validation report for all sections + - After presenting the full validation report in YOLO mode, you MAY still offer the 'Advanced Reflective & Elicitation Options' menu for deeper investigation of specific sections with issues. + +### 5. Generate Comprehensive Platform Validation Report + +- Summarize validation findings by section across all 16 checklist areas +- Calculate and present overall compliance percentage for complete platform stack +- Clearly document all non-compliant items with remediation plans prioritized by platform impact +- Highlight critical security or operational risks affecting platform reliability +- Include design review findings and architectural implementation recommendations +- Provide validation signoff recommendation based on complete platform assessment +- Document platform component integration validation results + +### 6. BMAD Integration Assessment + +- Review how platform infrastructure changes support other BMAD agents: + - **Development Agent Alignment:** Verify platform infrastructure supports Frontend Dev, Backend Dev, and Full Stack Dev requirements including: + - Container platform development environment provisioning + - GitOps workflows for application deployment + - Service mesh integration for development testing + - Developer experience platform self-service capabilities + - **Product Alignment:** Ensure platform infrastructure implements PRD requirements from Product Owner including: + - Scalability and performance requirements through container platform + - Deployment automation through GitOps workflows + - Service reliability through service mesh implementation + - **Architecture Alignment:** Validate that platform implementation aligns with architecture decisions including: + - Technology selections implemented correctly across all platform components + - Security architecture implemented in container platform, service mesh, and GitOps + - Integration patterns properly implemented between platform components + - Document all integration points and potential impacts on other agents' workflows + +### 7. Next Steps Recommendation + +- If validation successful: + - Prepare platform deployment recommendation with component dependencies + - Outline monitoring requirements for complete platform stack + - Suggest knowledge transfer activities for platform operations + - Document platform readiness certification +- If validation failed: + - Prioritize remediation actions by platform component and integration impact + - Recommend blockers vs. non-blockers for platform deployment + - Schedule follow-up validation with focus on failed platform components + - Document platform risks and mitigation strategies +- If design review identified architectural issues: + - **Escalate to Architect Agent** for architectural revision and re-design + - Document specific architectural changes required for implementability + - Schedule follow-up design review after architectural modifications +- Update documentation with validation results across all platform components +- Always ensure the Infrastructure Change Request status is updated to reflect the platform validation outcome. + +## Output + +A comprehensive platform validation report documenting: + +1. **Architecture Design Review Results** - Implementability assessment and architectural recommendations +2. **Compliance percentage by checklist section** (all 16 sections including platform engineering) +3. **Detailed findings for each non-compliant item** across foundation and platform components +4. **Platform integration validation results** documenting component interoperability +5. **Remediation recommendations with priority levels** based on platform impact +6. **BMAD integration assessment results** for complete platform stack +7. **Clear signoff recommendation** for platform deployment readiness or architectural revision requirements +8. **Next steps for implementation or remediation** prioritized by platform dependencies + +## Offer Advanced Self-Refinement & Elicitation Options + +Present the user with the following list of 'Advanced Reflective, Elicitation & Brainstorming Actions'. Explain that these are optional steps to help ensure quality, explore alternatives, and deepen the understanding of the current section before finalizing it and moving on. The user can select an action by number, or choose to skip this and proceed to finalize the section. + +"To ensure the quality of the current section: **[Specific Section Name]** and to ensure its robustness, explore alternatives, and consider all angles, I can perform any of the following actions. Please choose a number (8 to finalize and proceed): + +**Advanced Reflective, Elicitation & Brainstorming Actions I Can Take:** + +1. **Critical Security Assessment & Risk Analysis** +2. **Platform Integration & Component Compatibility Evaluation** +3. **Cross-Environment Consistency Review** +4. **Technical Debt & Maintainability Analysis** +5. **Compliance & Regulatory Alignment Deep Dive** +6. **Cost Optimization & Resource Efficiency Analysis** +7. **Operational Resilience & Platform Failure Mode Testing (Theoretical)** +8. **Finalize this Section and Proceed.** + +After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section." + +REPEAT by Asking the user if they would like to perform another Reflective, Elicitation & Brainstorming Action UNTIL the user indicates it is time to proceed to the next section (or selects #8) + +==================== END: validate-infrastructure ==================== + + diff --git a/web-build-sample/templates.txt b/web-build-sample/templates.txt index cff1baec..d7d04862 100644 --- a/web-build-sample/templates.txt +++ b/web-build-sample/templates.txt @@ -1007,117 +1007,348 @@ _Repeat the above template for each significant component._ ==================== END: front-end-spec-tmpl ==================== +==================== START: infrastructure-architecture-tmpl ==================== +# {Project Name} Infrastructure Architecture + +## Infrastructure Overview + +- Cloud Provider(s) +- Core Services & Resources +- Regional Architecture +- Multi-environment Strategy + +## Infrastructure as Code (IaC) + +- Tools & Frameworks +- Repository Structure +- State Management +- Dependency Management + +## Environment Configuration + +- Environment Promotion Strategy +- Configuration Management +- Secret Management +- Feature Flag Integration + +## Environment Transition Strategy + +- Development to Production Pipeline +- Deployment Stages and Gates +- Approval Workflows and Authorities +- Rollback Procedures +- Change Cadence and Release Windows +- Environment-Specific Configuration Management + +## Network Architecture + +- VPC/VNET Design +- Subnet Strategy +- Security Groups & NACLs +- Load Balancers & API Gateways +- Service Mesh (if applicable) + +## Compute Resources + +- Container Strategy +- Serverless Architecture +- VM/Instance Configuration +- Auto-scaling Approach + +## Data Resources + +- Database Deployment Strategy +- Backup & Recovery +- Replication & Failover +- Data Migration Strategy + +## Security Architecture + +- IAM & Authentication +- Network Security +- Data Encryption +- Compliance Controls +- Security Scanning & Monitoring + +## Shared Responsibility Model + +- Cloud Provider Responsibilities +- Platform Team Responsibilities +- Development Team Responsibilities +- Security Team Responsibilities +- Operational Monitoring Ownership +- Incident Response Accountability Matrix + +## Monitoring & Observability + +- Metrics Collection +- Logging Strategy +- Tracing Implementation +- Alerting & Incident Response +- Dashboards & Visualization + +## CI/CD Pipeline + +- Pipeline Architecture +- Build Process +- Deployment Strategy +- Rollback Procedures +- Approval Gates + +## Disaster Recovery + +- Backup Strategy +- Recovery Procedures +- RTO & RPO Targets +- DR Testing Approach + +## Cost Optimization + +- Resource Sizing Strategy +- Reserved Instances/Commitments +- Cost Monitoring & Reporting +- Optimization Recommendations + +## Infrastructure Verification + +### Validation Framework + +This infrastructure architecture will be validated using the comprehensive `infrastructure-checklist.md`, with particular focus on Section 12: Architecture Documentation Validation. The checklist ensures: + +- Completeness of architecture documentation +- Consistency with broader system architecture +- Appropriate level of detail for different stakeholders +- Clear implementation guidance +- Future evolution considerations + +### Validation Process + +The architecture documentation validation should be performed: + +- After initial architecture development +- After significant architecture changes +- Before major implementation phases +- During periodic architecture reviews + +The Platform Engineer should use the infrastructure checklist to systematically validate all aspects of this architecture document. + +## Infrastructure Evolution + +- Technical Debt Inventory +- Planned Upgrades and Migrations +- Deprecation Schedule +- Technology Roadmap +- Capacity Planning +- Scalability Considerations + +## Integration with Application Architecture + +- Service-to-Infrastructure Mapping +- Application Dependency Matrix +- Performance Requirements Implementation +- Security Requirements Implementation +- Data Flow to Infrastructure Correlation +- API Gateway and Service Mesh Integration + +## Cross-Team Collaboration + +- Platform Engineer and Developer Touchpoints +- Frontend/Backend Integration Requirements +- Product Requirements to Infrastructure Mapping +- Architecture Decision Impact Analysis +- Design Architect UI/UX Infrastructure Requirements +- Analyst Research Integration + +## Infrastructure Change Management + +- Change Request Process +- Risk Assessment +- Testing Strategy +- Validation Procedures + +==================== END: infrastructure-architecture-tmpl ==================== + + ==================== START: prd-tmpl ==================== -# {Project Name} Product Requirements Document (PRD) +# {{Project Name}} Product Requirements Document (PRD) -## Goal, Objective and Context +[[LLM: If available, review any provided document or ask if any are optionally available: Project Brief]] -This should come mostly from the user or the provided brief, but ask for clarifications as needed. +## Goals and Background Context -## Functional Requirements (MVP) +[[LLM: Populate the 2 child sections based on what we have received from user description or the provided brief. Allow user to review the 2 sections and offer changes before proceeding]] -You should have a good idea at this point, but clarify suggest question and explain to ensure these are correct. +### Goals -## Non Functional Requirements (MVP) +[[LLM: Bullet list of 1 line desired outcomes the PRD will deliver if successful - user and project desires]] -You should have a good idea at this point, but clarify suggest question and explain to ensure these are correct. +### Background Context -## User Interaction and Design Goals +[[LLM: 1-2 short paragraphs summarizing the background context, such as what we learned in the brief without being redundant with the goals, what and why this solves a problem, what the current landscape or need is etc...]] -{ -If the product includes a User Interface (UI), this section captures the Product Manager's high-level vision and goals for the User Experience (UX). This information will serve as a crucial starting point and brief for the Design Architect. +## Requirements -Consider and elicit information from the user regarding: +[[LLM: Draft the list of functional and non functional requirements under the two child sections, and immediately execute tasks#advanced-elicitation display]] -- **Overall Vision & Experience:** What is the desired look and feel (e.g., "modern and minimalist," "friendly and approachable," "data-intensive and professional")? What kind of experience should users have? -- **Key Interaction Paradigms:** Are there specific ways users will interact with core features (e.g., "drag-and-drop interface for X," "wizard-style setup for Y," "real-time dashboard for Z")? -- **Core Screens/Views (Conceptual):** From a product perspective, what are the most critical screens or views necessary to deliver the MVP's value? (e.g., "Login Screen," "Main Dashboard," "Item Detail Page," "Settings Page"). -- **Accessibility Aspirations:** Any known high-level accessibility goals (e.g., "must be usable by screen reader users"). -- **Branding Considerations (High-Level):** Any known branding elements or style guides that must be incorporated? -- **Target Devices/Platforms:** (e.g., "primarily web desktop," "mobile-first responsive web app"). +### Functional -This section is not intended to be a detailed UI specification but rather a product-focused brief to guide the subsequent detailed work by the Design Architect, who will create the comprehensive UI/UX Specification document. -} +[[LLM: Each Requirement will be a bullet markdown and an identifier sequence starting with FR`.]] +@{example: - FR6: The Todo List uses AI to detect and warn against adding potentially duplicate todo items that are worded differently.} + +### Non Functional + +[[LLM: Each Requirement will be a bullet markdown and an identifier sequence starting with NFR`.]] +@{example: - NFR1: AWS service usage **must** aim to stay within free-tier limits where feasible.} + +^^CONDITION: has_ui^^ + +## User Interface Design Goals + +[[LLM: Capture high-level UI/UX vision to guide Design Architect and to inform story creation. Steps: + +1. Pre-fill all subsections with educated guesses based on project context +2. Present the complete rendered section to user +3. Clearly let the user know where assumptions were made +4. Ask targeted questions for unclear/missing elements or areas needing more specification +5. This is NOT detailed UI spec - focus on product vision and user goals +6. After section completion, immediately apply `tasks#advanced-elicitation` protocol]] + +### Overall UX Vision + +### Key Interaction Paradigms + +### Core Screens and Views + +[[LLM: From a product perspective, what are the most critical screens or views necessary to deliver the the PRD values and goals? This is meant to be Conceptual High Level to Drive Rough Epic or User Stories]] + +@{example} + +- Login Screen +- Main Dashboard +- Item Detail Page +- Settings Page + @{/example} + +### Accessibility: { None, WCAG, etc } + +### Branding + +[[LLM: Any known branding elements or style guides that must be incorporated?]] + +@{example} + +- Replicate the look and feel of early 1900s black and white cinema, including animated effects replicating film damage or projector glitches during page or state transitions. +- Attached is the full color pallet and tokens for our corporate branding. + @{/example} + +### Target Device and Platforms + +@{example} +"Web Responsive, and all mobile platforms", "IPhone Only", "ASCII Windows Desktop" +@{/example} + +^^/CONDITION: has_ui^^ ## Technical Assumptions -This is where we can list information mostly to be used by the architect to produce the technical details. This could be anything we already know or found out from the user at a technical high level. Inquire about this from the user to get a basic idea of languages, frameworks, knowledge of starter templates, libraries, external apis, potential library choices etc... +[[LLM: Gather technical decisions that will guide the Architect. Steps: -- **Repository & Service Architecture:** {CRITICAL DECISION: Document the chosen repository structure (e.g., Monorepo, Polyrepo) and the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo). Explain the rationale based on project goals, MVP scope, team structure, and scalability needs. This decision directly impacts the technical approach and informs the Architect Agent.} +1. Check if `data#technical-preferences` file exists - use it to pre-populate choices +2. Ask user about: languages, frameworks, starter templates, libraries, APIs, deployment targets +3. For unknowns, offer guidance based on project goals and MVP scope +4. Document ALL technical choices with rationale (why this choice fits the project) +5. These become constraints for the Architect - be specific and complete +6. After section completion, apply `tasks#advanced-elicitation` protocol.]] + +### Repository Structure: { Monorepo, Polyrepo, etc...} + +### Service Architecture + +[[LLM: CRITICAL DECISION - Document the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo).]] ### Testing requirements -How will we validate functionality beyond unit testing? Will we want manual scripts or testing, e2e, integration etc... figure this out from the user to populate this section +[[LLM: CRITICAL DECISION - Document the testing requirements, unit only, integration, e2e, manual, need for manual testing convenience methods).]] -## Epic Overview +### Additional Technical Assumptions and Requests -- **Epic {#}: {Title}** - - Goal: {A concise 1-2 sentence statement describing the primary objective and value of this Epic.} - - Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}. - - {Acceptance Criteria List} - - Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}. - - {Acceptance Criteria List} -- **Epic {#}: {Title}** - - Goal: {A concise 1-2 sentence statement describing the primary objective and value of this Epic.} - - Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}. - - {Acceptance Criteria List} - - Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}. - - {Acceptance Criteria List} +[[LLM: Throughout the entire process of drafting this document, if any other technical assumptions are raised or discovered appropriate for the architect, add them here as additional bulleted items]] -## Key Reference Documents +## Epics -{ This section will be created later, from the sections prior to this being carved up into smaller documents } +[[LLM: First, present a high-level list of all epics for user approval, the epic_list and immediately execute tasks#advanced-elicitation display. Each epic should have a title and a short (1 sentence) goal statement. This allows the user to review the overall structure before diving into details. -## Out of Scope Ideas Post MVP +CRITICAL: Epics MUST be logically sequential following agile best practices: -Anything you and the user agreed it out of scope or can be removed from scope to keep MVP lean. Consider the goals of the PRD and what might be extra gold plating or additional features that could wait until the MVP is completed and delivered to assess functionality and market fit or usage. +- Each epic should deliver a significant, end-to-end, fully deployable increment of testable functionality +- Epic 1 must establish foundational project infrastructure (app setup, Git, CI/CD, core services) unless we are adding new functionality to an existing app, while also delivering an initial piece of functionality, even as simple as a health-check route or display of a simple canary page +- Each subsequent epic builds upon previous epics' functionality delivering major blocks of functionality that provide tangible value to users or business when deployed +- Not every project needs multiple epics, an epic needs to deliver value. For example, an API completed can deliver value even if a UI is not complete and planned for a separate epic. +- Err on the side of less epics, but let the user know your rationale and offer options for splitting them if it seems some are too large or focused on disparate things. +- Cross Cutting Concerns should flow through epics and stories and not be final stories. For example, adding a logging framework as a last story of an epic, or at the end of a project as a final epic or story would be terrible as we would not have logging from the beginning.]] -## [OPTIONAL: For Simplified PM-to-Development Workflow Only] Core Technical Decisions & Application Structure +<> -{This section is to be populated ONLY if the PM is operating in the 'Simplified PM-to-Development Workflow'. It captures essential technical foundations that would typically be defined by an Architect, allowing for a more direct path to development. This information should be gathered after initial PRD sections (Goals, Users, etc.) are drafted, and ideally before or in parallel with detailed Epic/Story definition, and updated as needed.} +- Epic{{epic_number}} {{epic_title}}: {{short_goal}} -### Technology Stack Selections +<> -{Collaboratively define the core technologies. Be specific about choices and versions where appropriate.} +@{example: epic_list} -- **Primary Backend Language/Framework:** {e.g., Python/FastAPI, Node.js/Express, Java/Spring Boot} -- **Primary Frontend Language/Framework (if applicable):** {e.g., TypeScript/React (Next.js), JavaScript/Vue.js} -- **Database:** {e.g., PostgreSQL, MongoDB, AWS DynamoDB} -- **Key Libraries/Services (Backend):** {e.g., Authentication (JWT, OAuth provider), ORM (SQLAlchemy), Caching (Redis)} -- **Key Libraries/Services (Frontend, if applicable):** {e.g., UI Component Library (Material-UI, Tailwind CSS + Headless UI), State Management (Redux, Zustand)} -- **Deployment Platform/Environment:** {e.g., Docker on AWS ECS, Vercel, Netlify, Kubernetes} -- **Version Control System:** {e.g., Git with GitHub/GitLab} +1. Foundation & Core Infrastructure: Establish project setup, authentication, and basic user management +2. Core Business Entities: Create and manage primary domain objects with CRUD operations +3. User Workflows & Interactions: Enable key user journeys and business processes +4. Reporting & Analytics: Provide insights and data visualization for users -### Proposed Application Structure +@{/example} -{Describe the high-level organization of the codebase. This might include a simple text-based directory layout, a list of main modules/components, and a brief explanation of how they interact. The goal is to provide a clear starting point for developers.} +[[LLM: After the epic list is approved, present each `epic_details` with all its stories and acceptance criteria as a complete review unit and immediately execute tasks#advanced-elicitation display, before moving on to the next epic.]] -Example: +<> -``` -/ -├── app/ # Main application source code -│ ├── api/ # Backend API routes and logic -│ │ ├── v1/ -│ │ └── models.py -│ ├── web/ # Frontend components and pages (if monolithic) -│ │ ├── components/ -│ │ └── pages/ -│ ├── core/ # Shared business logic, utilities -│ └── main.py # Application entry point -├── tests/ # Unit and integration tests -├── scripts/ # Utility scripts -├── Dockerfile -├── requirements.txt -└── README.md -``` +## Epic {{epic_number}} {{epic_title}} -- **Monorepo/Polyrepo:** {Specify if a monorepo or polyrepo structure is envisioned, and briefly why.} -- **Key Modules/Components and Responsibilities:** - - {Module 1 Name}: {Brief description of its purpose and key responsibilities} - - {Module 2 Name}: {Brief description of its purpose and key responsibilities} - - ... -- **Data Flow Overview (Conceptual):** {Briefly describe how data is expected to flow between major components, e.g., Frontend -> API -> Core Logic -> Database.} +{{epic_goal}} [[LLM: Expanded goal - 2-3 sentences describing the objective and value all the stories will achieve]] + +[[LLM: CRITICAL STORY SEQUENCING REQUIREMENTS: + +- Stories within each epic MUST be logically sequential +- Each story should be a "vertical slice" delivering complete functionality +- No story should depend on work from a later story or epic +- Identify and note any direct prerequisite stories +- Focus on "what" and "why" not "how" (leave technical implementation to Architect) yet be precise enough to support a logical sequential order of operations from story to story. +- Ensure each story delivers clear user or business value, try to avoid enablers and build them into stories that deliver value. +- Size stories for AI agent execution: Each story must be completable by a single AI agent in one focused session without context overflow +- Think "junior developer working for 2-4 hours" - stories must be small, focused, and self-contained +- If a story seems complex, break it down further as long as it can deliver a vertical slice +- Each story should result in working, testable code before the agent's context window fills]] + +<> + +### Story {{epic_number}}.{{story_number}} {{story_title}} + +As a {{user_type}}, +I want {{action}}, +so that {{benefit}}. + +#### Acceptance Criteria + +[[LLM: Define clear, comprehensive, and testable acceptance criteria that: + +- Precisely define what "done" means from a functional perspective +- Are unambiguous and serve as basis for verification +- Include any critical non-functional requirements from the PRD +- Consider local testability for backend/data components +- Specify UI/UX requirements and framework adherence where applicable +- Avoid cross-cutting concerns that should be in other stories or PRD sections]] + +<> + +- {{criterion number}}: {{criteria}} + +<> +<> +<> ## Change Log @@ -1128,52 +1359,21 @@ Example: ## Checklist Results Report +[[LLM: Before running the checklist and drafting the prompts, offer to output the full updated PRD. If outputting it, confirm with the user that you will be proceeding to run the checklist and produce the report. Once the user confirms, execute the `pm-checklist` and populate the results in this section.]] + ----- END Checklist START Design Architect `UI/UX Specification Mode` Prompt ------ +## Design Architect Prompt + +[[LLM: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.]] + ----- END Design Architect `UI/UX Specification Mode` Prompt START Architect Prompt ------ -## Initial Architect Prompt +## Architect Prompt -Based on our discussions and requirements analysis for the {Product Name}, I've compiled the following technical guidance to inform your architecture analysis and decisions to kick off Architecture Creation Mode: +[[LLM: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.]] -### Technical Infrastructure - -- **Repository & Service Architecture Decision:** {Reiterate the decision made in 'Technical Assumptions', e.g., Monorepo with Next.js frontend and Python FastAPI backend services within the same repo; or Polyrepo with separate Frontend (Next.js) and Backend (Spring Boot Microservices) repositories.} -- **Starter Project/Template:** {Information about any starter projects, templates, or existing codebases that should be used} -- **Hosting/Cloud Provider:** {Specified cloud platform (AWS, Azure, GCP, etc.) or hosting requirements} -- **Frontend Platform:** {Framework/library preferences or requirements (React, Angular, Vue, etc.)} -- **Backend Platform:** {Framework/language preferences or requirements (Node.js, Python/Django, etc.)} -- **Database Requirements:** {Relational, NoSQL, specific products or services preferred} - -### Technical Constraints - -- {List any technical constraints that impact architecture decisions} -- {Include any mandatory technologies, services, or platforms} -- {Note any integration requirements with specific technical implications} - -### Deployment Considerations - -- {Deployment frequency expectations} -- {CI/CD requirements} -- {Environment requirements (local, dev, staging, production)} - -### Local Development & Testing Requirements - -{Include this section only if the user has indicated these capabilities are important. If not applicable based on user preferences, you may remove this section.} - -- {Requirements for local development environment} -- {Expectations for command-line testing capabilities} -- {Needs for testing across different environments} -- {Utility scripts or tools that should be provided} -- {Any specific testability requirements for components} - -### Other Technical Considerations - -- {Security requirements with technical implications} -- {Scalability needs with architectural impact} -- {Any other technical context the Architect should consider} - ------ END Architect Prompt ----- +----- END Architect Prompt ------ ==================== END: prd-tmpl ==================== @@ -1226,7 +1426,7 @@ Based on our discussions and requirements analysis for the {Product Name}, I've ## PM Prompt -This Project Brief provides the full context for {Project Name}. Please start in 'PRD Generation Mode', review the brief thoroughly to work with the user to create the PRD section by section 1 at a time, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows. +This Project Brief provides the full context for {Project Name}. Please start in 'PRD Generation Mode', review the brief thoroughly to work with the user to create the PRD section by section as the template indicates, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows. This Project Brief provides the full context for Mealmate. Please start in 'PRD Generation Mode', review the brief thoroughly to work with the user to create the PRD section by section 1 at a time, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows. @@ -1273,3 +1473,51 @@ This Project Brief provides the full context for Mealmate. Please start in 'PRD ==================== END: story-tmpl ==================== +==================== START: template-format ==================== +# MD Template Format: + +- {{placeholder}} = Simple text replacement placeholder +- [[LLM: instruction]] = Instructions for the LLM (not included in output) +- <> ... <> = Repeating section +- ^^CONDITION: condition_name^^ ... ^^/CONDITION: condition_name^^ = Conditional section that will render if the condition_name logically applies +- @{example: content} = Single line example content for LLM guidance - do not render +- @{example} ... @{/example} = Multi-line example content for LLM guidance - do not render + +## Critical Template Usage Rules + +- CRITICAL: Never display or output template markup formatting, LLM instructions or examples + - they MUST be used by you the agent only, AND NEVER shown to users in chat or documented output\*\* +- Present only the final, clean content to users +- Replace template variables with actual project-specific content +- Show examples only when they add value, without the markup +- Process all conditional logic internally - show only relevant sections +- For Canvas mode: Update the document with clean, formatted content only + +@{example} + +# My Template Foo + +[[LLM: Check the current system date and if the user name is unknown, just say hello]] +Hello {{users name}}, this is your foo report for {{todays date}} + +<> +[[LLM: For Each Foo, Create a matching creative Bar]] + +## Foo: {{Bar}} + +<> + +^^CONDITION: if_BAZ_exists^^ + +## BAZ + +### You haz BAZ! Here is your daily Baz Forecast! + +[[LLM: Give the user their daily baz report here]] +^^/CONDITION: if_BAZ_exists^^ + +@{/example} + +==================== END: template-format ==================== + +