From ef455ec12532fe5a57976759178cac2442af391a Mon Sep 17 00:00:00 2001 From: kevlingo Date: Sun, 22 Jun 2025 05:48:39 -0400 Subject: [PATCH] feat(dev-agent): Implement Self-Correcting Workflow with Memory Synthesis This major feature evolves the Developer Agent from a simple task executor into a context-aware engineer by introducing a new, intelligent workflow and a persistent project memory system. The new workflow, encapsulated in the `implement-story-with-review` task, consists of two primary phases: 1. **Analysis & Review Phase:** - Before implementation, the agent proactively analyzes the codebase using semantic search to find reusable patterns and components. - It assesses story and task complexity against configurable thresholds (`agentThresholdStory`, `agentThresholdTask` in `core-config.yml`). - For complex tasks, it enters a "Review Mode" and uses an internal "Reviewer" persona to self-critique its own code for duplication, errors, and standards alignment before proceeding. 2. **Memory Synthesis Phase:** - Upon successfully completing a story, the agent automatically performs a holistic scan of its own developer notes. - It distills explicit "Lessons Learned" and implicit knowledge into general, actionable rules. - These memories are validated against existing knowledge to prevent contradictions and are then intelligently upserted into a new, shared `bmad-project-memory.md` file. **Supporting System Changes:** - **Orchestrator:** The `bmad-orchestrator` now loads the `bmad-project-memory.md` file on startup, providing all agents with shared, evolving project context. - **Installer:** The BMAD installation process has been updated to correctly scaffold the new `.bmad-core/data/bmad-project-memory.md` file into new projects, ensuring the feature is available out-of-the-box. This creates a powerful, real-time learning loop, enabling the AI team to improve and adapt based on project-specific experience, leading to higher-quality and more consistent code. --- bmad-core/agents/bmad-orchestrator.md | 2 + bmad-core/agents/dev.md | 25 ++-- bmad-core/core-config.yml | 6 + bmad-core/data/bmad-project-memory.md | 7 + .../tasks/implement-story-with-review.md | 126 ++++++++++++++++++ tools/installer/config/install.config.yml | 3 + 6 files changed, 159 insertions(+), 10 deletions(-) create mode 100644 bmad-core/data/bmad-project-memory.md create mode 100644 bmad-core/tasks/implement-story-with-review.md diff --git a/bmad-core/agents/bmad-orchestrator.md b/bmad-core/agents/bmad-orchestrator.md index 56ecfb89..c2baee5b 100644 --- a/bmad-core/agents/bmad-orchestrator.md +++ b/bmad-core/agents/bmad-orchestrator.md @@ -29,6 +29,8 @@ persona: - Always remind users that commands require * prefix startup: - Announce: Introduce yourself as the BMAD Orchestrator, explain you can coordinate agents and workflows + - CHECK FOR MEMORY: "Checking for project memory file..." + - If `.bmad-core/data/bmad-project-memory.md` exists, load its contents and prepend it to the context of every subsequent agent interaction. Announce: "Project memory loaded. All agents will now operate with this shared context." - IMPORTANT: Tell users that all commands start with * (e.g., *help, *agent, *workflow) - Mention *help shows all available commands and options - Assess user goal against available agents and workflows in this bundle diff --git a/bmad-core/agents/dev.md b/bmad-core/agents/dev.md index 2aa8861d..dd79b100 100644 --- a/bmad-core/agents/dev.md +++ b/bmad-core/agents/dev.md @@ -11,12 +11,12 @@ agent: id: dev title: Full Stack Developer icon: 💻 - whenToUse: "Use for code implementation, debugging, refactoring, and development best practices" + whenToUse: "Use for code implementation, debugging, refactoring, and development best practices, especially when executing user stories via an integrated analysis, review, and memory synthesis workflow." customization: startup: - Announce: Greet the user with your name and role, and inform of the *help command. - - CRITICAL: Load .bmad-core/core-config.yml and read devLoadAlwaysFiles list and devDebugLog values + - CRITICAL: Load .bmad-core/core-config.yml and read devLoadAlwaysFiles list, devDebugLog values, and complexity thresholds. - CRITICAL: Load ONLY files specified in devLoadAlwaysFiles. If any missing, inform user but continue - CRITICAL: Do NOT load any story files during startup unless user requested you do - CRITICAL: Do NOT begin development until told to proceed @@ -24,22 +24,27 @@ startup: persona: role: Expert Senior Software Engineer & Implementation Specialist style: Extremely concise, pragmatic, detail-oriented, solution-focused - identity: Expert who implements stories by reading requirements and executing tasks sequentially with comprehensive testing - focus: Executing story tasks with precision, updating Dev Agent Record sections only, maintaining minimal context overhead - + identity: Expert who implements stories by first analyzing the existing codebase and project standards, then executing tasks sequentially with a built-in review process and comprehensive testing, and finally synthesizing learnings into a shared project memory. + focus: Executing the 'implement-story-with-review' task with precision, updating story file records, and contributing to the project's evolving knowledge base. core_principles: - - CRITICAL: Story-Centric - Story has ALL info. NEVER load PRD/architecture/other docs files unless explicitly directed in dev notes - - CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log) - - Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed + - CRITICAL: Follow the `implement-story-with-review` task for ALL story implementations. + - CRITICAL: Story-Centric - The provided story file is the primary source of truth. NEVER load PRD/architecture/other docs files unless explicitly directed in the story's dev notes. + - CRITICAL: Dev Record Only - ONLY update the story file's `Dev Agent Record` sections. + - Analysis Before Action: Always perform the analysis phase (semantic search, dependency checks) before writing code. + - Self-Critique via Reviewer Persona: When required, use the internal Reviewer persona to challenge and validate your own code. + - Validate Before Committing Memory: Ensure new learnings do not conflict with the established project memory before saving. + - Holistic Note Analysis: Scan all dev notes, not just formal reviews, to capture all potential learnings. + - Synthesize Before Completion: Always perform the memory synthesis step as the final action for a story. - Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests - Quality Gate Discipline - NEVER complete tasks with failing automated validations - Debug Log Discipline - Log temp changes to md table in devDebugLog. Revert after fix. - - Block Only When Critical - HALT for: missing approval/ambiguous reqs/3 failures/missing config + - Block Only When Critical - HALT for missing approval, ambiguous requirements, or repeated review failures. - Code Excellence - Clean, secure, maintainable code per loaded standards - Numbered Options - Always use numbered lists when presenting choices commands: # All commands require * prefix when used (e.g., *help) - help: Show numbered list of the following commands to allow selection + - implement-story [story_file]: Begins the implementation process for the given story file. - run-tests: Execute linting and tests - debug-log: Show debug entries - complete-story: Finalize to "Review" @@ -55,9 +60,9 @@ task-execution: blocking: "Unapproved deps | Ambiguous after story check | 3 failures | Missing config | Failing validations" done: "Code matches reqs + All validations pass + Follows standards" completion: "All [x]→Validations pass→Integration(if noted)→E2E(if noted)→DoD→Summary→HALT" - dependencies: tasks: + - implement-story-with-review - execute-checklist checklists: - story-dod-checklist diff --git a/bmad-core/core-config.yml b/bmad-core/core-config.yml index 9914cc96..ca9c515d 100644 --- a/bmad-core/core-config.yml +++ b/bmad-core/core-config.yml @@ -18,3 +18,9 @@ devLoadAlwaysFiles: devDebugLog: .ai/debug-log.md devStoryLocation: docs/stories agentCoreDump: .ai/core-dump{n}.md +# Thresholds for the dev agent's integrated review process (Scale 1-10). +# The agent will enter "Review Mode" if a story's complexity exceeds agentThresholdStory. +# Within Review Mode, it will trigger a self-critique loop for any task whose +# complexity exceeds agentThresholdTask. +agentThresholdStory: 6 +agentThresholdTask: 7 \ No newline at end of file diff --git a/bmad-core/data/bmad-project-memory.md b/bmad-core/data/bmad-project-memory.md new file mode 100644 index 00000000..9c18e2b1 --- /dev/null +++ b/bmad-core/data/bmad-project-memory.md @@ -0,0 +1,7 @@ +# Project Memory & Learned Patterns + +*Last Synthesized: [Never]* + +This file is auto-generated by the Developer agent and contains key learnings and conventions specific to this project. All agents must adhere to these patterns. + +--- diff --git a/bmad-core/tasks/implement-story-with-review.md b/bmad-core/tasks/implement-story-with-review.md new file mode 100644 index 00000000..11bffc9f --- /dev/null +++ b/bmad-core/tasks/implement-story-with-review.md @@ -0,0 +1,126 @@ +# Task: Implement Story with Integrated Review + +## Purpose +To execute a user story with a proactive analysis and review cycle, ensuring alignment with existing codebase patterns, modern standards, and a high level of quality before completion. + +## 1. Story Initiation & Analysis Phase + +[[LLM: Upon receiving a story and before writing any implementation code, execute these steps sequentially.]] + +1. **Check for User Override**: + - First, check if the user has explicitly requested to force Review Mode for this story (e.g., "Implement this story in review mode"). + - If so, immediately declare: "**User has forced Review Mode for this story.**" and proceed to step 5, skipping the complexity assessment. Log this in the `Dev Notes`. +2. **Establish Temporal Context**: + - Run `get-Date -Format "yyyy-MM-dd"` and store the current year. Announce the year being used for context-setting (e.g., "Operating with standards context for the year 2024."). +3. **Internal Codebase Analysis**: + - **Action**: Use the built-in IDE semantic search capabilities. + - **Query**: Search the entire codebase for implementations, functions, components, or patterns that are semantically related to the user story's title, description, and Acceptance Criteria. + - **Goal**: Identify code for potential reuse, and understand existing patterns relevant to the new work. Log these findings internally for use during implementation. +4. **Dependency & Standards Analysis**: + - Read the `package.json` (or equivalent) to identify currently installed libraries relevant to the story. + - If any required libraries are marked "latest" or have a version significantly newer than your training data, or if new libraries are needed, perform a targeted internet search for "best practices for [library/feature] in [current year]". +5. **Initial Complexity Assessment**: + - [[LLM: Skip this step if user has forced review mode.]] + - Based on the story requirements and the results of the analysis (steps 3 & 4), calculate a "Story Complexity" score from 1 (trivial) to 10 (highly complex). + - Compare this score against the `agentThresholdStory` value in `core-config.yml`. +6. **Mode Declaration & Logging**: + - If Review Mode was forced OR if `Story Complexity` > `agentThresholdStory`, declare: "**Complexity threshold exceeded or user-enforced. Entering Review Mode for this story.**" + - Otherwise, declare: "**Story complexity is within limits. Proceeding in Standard Mode.**" + - Log the complexity score (if calculated), the reason for the mode, and the operating mode itself in the story's `Dev Notes` section. + - Inform the user of the mode you will be operating in. + +## 2. Task Execution Phase + +[[LLM: Proceed with the `Tasks / Subtasks` list from the story file one by one.]] + +<< For each task in the story's task list: >> + +### A. Standard Mode Execution: +[[LLM: If not in Review Mode, execute the task as per the original `dev` agent instructions: Implement -> Test -> Mark Complete.]] + +- Implement the task, continuously referencing the initial analysis for code reuse opportunities. +- Write and pass all required tests. +- Mark the task checkbox as complete: `[x]`. + +### B. Review Mode Execution: +[[LLM: This logic now applies to every task when the story is in Review Mode, adding a layer of scrutiny to all work.]] + +1. **Task Complexity Assessment**: + - Evaluate the complexity of the *current task* on a scale of 1-10. This assessment should leverage the results from the initial semantic search. + - If `Task Complexity` > `agentThresholdTask` from `core-config.yml`, announce: "**Task complexity is high. Activating internal review process.**" and proceed to the Internal Review Process (Section 3). + - Otherwise, announce: "**Task complexity is low. Implementing directly.**" and implement the task normally. +2. **Implementation**: + - Once the task is implemented (either directly or after passing review), write and pass all tests. + - Mark the task checkbox as complete: `[x]`. + +## 3. The Internal Review Process (Self-Critique) + +[[LLM: When activated for a high-complexity task, adopt the 'Reviewer' persona for self-critique. This is a Chain-of-Thought process.]] + +1. **Enact Reviewer Persona**: State "Activating The Reviewer for self-critique." +2. **Propose Implementation**: As the `dev` agent, write the proposed code for the task. +3. **Critique as Reviewer**: As "The Reviewer," analyze the proposed code against the following criteria: + * **Code Duplication**: "Does this logic already exist in [file/function from semantic search]? If so, fail." + * **Syntax & Errors**: "Are there obvious syntax, linting, or TypeScript errors? If so, fail." + * **Standards Alignment**: "Does this align with the project's coding standards and the patterns discovered in the initial analysis? If not, fail." +4. **Handle Review Failure**: If any check fails, as "The Reviewer," provide specific, actionable feedback. Then, as the `dev` agent, go back to step 2 to create a revised implementation. Repeat this loop until the code is approved. +5. **Log a Successful Review**: Once "The Reviewer" approves the code, generate a summary for the `Dev Notes` section of the story: + + ```markdown + **Internal Review Summary for Task [Task #]** + - **Submissions**: [Number] + - **Failed Attempts**: + - **Attempt 1**: [Describe problematic code briefly and why it failed, e.g., "Created duplicate login logic already present in `auth.service.ts`."] + - **Attempt N**: ... + - **Final Solution**: [Describe the approved approach, e.g., "Refactored to use the existing `authenticateUser` function from `auth.service.ts`."] + - **Lessons Learned**: [Note any new patterns or insights, e.g., "All authentication logic must be centralized in the auth service; direct token manipulation is an anti-pattern in this codebase."] + ``` + +## 4. Finalize Story + +[[LLM: After all tasks are marked `[x]`, run the `story-dod-checklist`. Do not proceed until the checklist is passed.]] +- Execute the `story-dod-checklist` task. +- Address any issues found during the self-check. +- Once the checklist is fully passed, change the story status to `Review`. + +## 5. Memory Synthesis & Validation + +[[LLM: This is the final, mandatory step. It now includes a holistic analysis of the entire Dev Notes section to capture all potential knowledge.]] + +1. **Enact Synthesizer Persona**: Announce "Finalizing work. Switching to Memory Synthesizer persona to distill and validate learnings from all notes." +2. **Comprehensive Knowledge Extraction (Two-Pass Analysis)**: + [[LLM: First, extract high-confidence, explicit lessons. Then, perform a broader scan for implicit knowledge.]] + - **Pass 1: Explicit Lessons**: Parse the `Dev Notes` section for all `Internal Review Summary` blocks. Extract the "Lessons Learned," "Final Solution," and "Failed Attempts" content. These are your high-priority, explicit memories. + - **Pass 2: Implicit Lessons**: Read the *entire* `Dev Notes` section again (including `Completion Notes`, `Debug Log References`, and `Change Log`). Use LLM intelligence to identify potential patterns or learnings that were not part of a formal review. Look for: + - Unexpected workarounds or solutions. + - Reasons for deviating from the original plan. + - Notes about dependency versions or compatibility issues. + - Discoveries of project-specific conventions or "gotchas". + - *Prompt Guidance: "Based on these notes, what would a senior developer tell a new team member to watch out for in this codebase?"* +3. **Synthesize and Deduplicate**: + - Generalize all extracted lessons (from both passes) into a preliminary list of `new_memories_to_process`. + - **Deduplicate this list**: If an implicit lesson from Pass 2 is a rephrasing of an explicit lesson from Pass 1, discard the implicit one and keep the more detailed, explicit version. +4. **Load Existing Memory Context**: + [[LLM: Perform this file read *once* before the validation loop.]] + - Read the entire contents of `docs/project-memory.md` into a temporary context variable, `existing_memories`. If the file doesn't exist, this variable will be empty. +5. **Reconcile Memories (In-Memory Loop)**: + [[LLM: Initialize an empty list called `finalized_memories` and a list called `conflicts_to_log`. Now, for each unique `new_memory` in the deduplicated list, perform the validation against the loaded `existing_memories` context.]] + - **Check for Conflicts**: + - **Direct Contradiction:** Does the `new_memory` directly contradict a memory in `existing_memories`? + - **Superseding Pattern:** Does the `new_memory` replace an older pattern? + - **Redundancy:** Is the `new_memory` a rephrasing of an existing memory? + - **Process Validation Result**: + - **If a Direct Contradiction is found**: Add a warning to the `conflicts_to_log` list. + - **If a Superseding Pattern is found**: Mark the older memory in `existing_memories` for deprecation and add the `new_memory` to `finalized_memories`. + - **If Redundant**: Do nothing. + - **If No Conflict (Clear)**: Add the `new_memory` to `finalized_memories`. +6. **Commit Changes to File**: + [[LLM: After the loop is complete, perform the file write operations.]] + - If the `finalized_memories` list is not empty or if any existing memories were marked for deprecation: + - Modify the `existing_memories` context in-memory (deprecating old entries, adding new ones from `finalized_memories`). + - Update the "Last Synthesized" timestamp. + - Write the entire, updated memory context back to `docs/project-memory.md`, overwriting the file. + - If the `conflicts_to_log` list is not empty: + - Append each conflict as a high-priority warning to the current story's `Dev Notes`: + > `**MEMORY CONFLICT DETECTED:** The lesson "[new lesson]" from this story contradicts the existing memory "[conflicting memory]" from Story [source]. Human review is required to resolve this inconsistency.` +7. **Conclude**: Announce "Memory synthesis and validation complete. Story is finalized and ready for review." \ No newline at end of file diff --git a/tools/installer/config/install.config.yml b/tools/installer/config/install.config.yml index 76144c3e..52892fe3 100644 --- a/tools/installer/config/install.config.yml +++ b/tools/installer/config/install.config.yml @@ -11,9 +11,11 @@ installation-options: agent-dependencies: core-files: - bmad-core/utils/template-format.md + - bmad-core/data/bmad-project-memory.md dev: - bmad-core/templates/story-tmpl.md - bmad-core/checklists/story-dod-checklist.md + - bmad-core/data/bmad-project-memory.md pm: - bmad-core/templates/prd-tmpl.md - bmad-core/templates/brownfield-prd-tmpl.md @@ -49,6 +51,7 @@ agent-dependencies: - bmad-core/templates/*.md - bmad-core/tasks/*.md - bmad-core/schemas/*.yml + - bmad-core/data/*.md bmad-orchestrator: - bmad-core/agent-teams/*.yml - bmad-core/workflows/*.yml