ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/bmad/core/workflows/handoff/instructions.md

9.6 KiB
Raw Blame History

Agent Handoff Workflow Instructions

The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/core/workflows/handoff/workflow.yaml Communicate in {communication_language} throughout the workflow execution

Check if workflow status file exists at: {output_folder}/bmm-workflow-status.md Display error: "⚠️ Workflow status file not found or invalid. Initialize BMAD workflow first." Suggest: Run workflow initialization command or create the file manually EXIT workflow - do not proceed Verify file contains required fields: PROJECT_NAME, CURRENT_PHASE, NEXT_AGENT Display error: "⚠️ Workflow status file is invalid - missing required fields" List missing fields to user EXIT workflow - do not proceed

Proceed to next step if validation passes

Read the complete file: {output_folder}/bmm-workflow-status.md

Extract the following fields:

  • PROJECT_NAME (required)
  • PROJECT_TYPE (optional)
  • PROJECT_LEVEL (optional)
  • FIELD_TYPE (optional)
  • CURRENT_PHASE (required)
  • NEXT_AGENT (required)
  • NEXT_COMMAND (optional - defaults to "Begin next phase")
  • NEXT_ACTION (optional)
  • CURRENT_WORKFLOW (optional)

Store all extracted values for use in subsequent steps

From the workflow status file, locate the "Completed Work" section Extract the most recent entry from the "Completed Work" section This represents what was just completed in the current phase Infer completed work from CURRENT_WORKFLOW field value Use conversation context to understand what you just finished doing Generate summary based on recent work performed in this session

Store completed work summary for handoff memory generation

Run Serena MCP tool: mcp__serena__activate_project Pass current project directory as the project parameter Wait for confirmation that project is activated Display error: "⚠️ Failed to activate Serena project. Ensure Serena MCP is installed and configured." Provide troubleshooting: Check Serena MCP server status and configuration EXIT workflow if Serena is not available Verify all required fields were extracted successfully from workflow status file: - PROJECT_NAME (required) - CURRENT_PHASE (required) - NEXT_AGENT (required) - NEXT_COMMAND (optional - defaults to "Begin next phase") Display warning: "⚠️ Missing required field: [FIELD_NAME]" Continue with placeholder value '[FIELD_NAME]' or cancel? (y/N) EXIT workflow gracefully Use placeholder values for missing fields Proceed to next step with warning noted

Proceed to handoff generation if all required fields are present

Create a comprehensive handoff memory using this exact structure: # [NEXT_AGENT] Agent Handoff - [PROJECT_NAME]

Date: [Current date from {date} variable] From: [CURRENT_PHASE] To: [NEXT_AGENT] Agent Command: [NEXT_COMMAND]

Work Just Completed

[Insert completed work summary from Step 2]

Current Project State

Project: [PROJECT_NAME] Type: [PROJECT_TYPE] ([FIELD_TYPE]) Level: [PROJECT_LEVEL] Current Phase: [CURRENT_PHASE]

Workflow Status: {output_folder}/bmm-workflow-status.md

Note: This handoff complements the BMAD /workflow-status command:

  • /workflow-status: Check current state and next recommended action
  • /handoff: Save detailed context for next agent (status + completion summary + files + success criteria)
  • /handoff-receive: Load handoff and display actionable summary

Your Task

[Insert NEXT_ACTION from workflow status]

Command to run: [NEXT_COMMAND]

Key Context You Need

[Analyze the project and list 3-5 critical things the next agent needs to know]

Examples:

  • Existing codebase structure
  • Key files to review
  • Important technical decisions
  • Constraints or requirements
  • Dependencies or blockers

Files to Review

[List 3-7 important file paths the next agent should read, based on their task]

Examples:

  • Source code files relevant to their work
  • Documentation files
  • Configuration files
  • Test files

Success Criteria

[What "done" looks like for the next agent's task]

Examples:

  • Documents created
  • Stories written
  • Code implemented
  • Tests passing

Next Steps

  1. Load the [NEXT_AGENT] agent
  2. Run [NEXT_COMMAND]
  3. [Any additional context-specific steps]

Ready for: [NEXT_AGENT] agent to execute [NEXT_COMMAND]

Generate the complete handoff memory document following this structure Analyze the current project context to provide meaningful content for each section Focus on actionable information the next agent actually needs Include specific file paths (not vague descriptions) Make success criteria clear and measurable Be concise but comprehensive

Generate memory name using this format: [next-agent]-handoff-YYYY-MM-DD-HHmmss Memory name examples: - architect-handoff-2025-10-19-161530 - dev-handoff-2025-10-20-143000 - sm-handoff-2025-10-20-091545

Use the following naming convention:

  • Extract agent name from NEXT_AGENT field (lowercase)
  • Use current date from {date} variable
  • Use 24-hour format HHmmss for timestamp
  • Ensures unique naming even with multiple handoffs per day

Call Serena MCP tool: mcpserenawrite_memory Parameters:

  • memory_name: [Generated memory name from above]
  • content: [Complete handoff memory document from Step 4]
Display error: "⚠️ Failed to save handoff memory to Serena" Show the generated handoff content to user Suggest manual save or retry Confirm successful save with memory name Proceed to final step Display this formatted message to {user_name}: ✅ Handoff memory saved to Serena: [memory-name]

📋 Copy/paste this prompt for the next session:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Read Serena memory: [memory-name]

Then execute the handoff.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Quick version: /handoff-receive

Replace all placeholders with actual values from the handoff Ensure the prompt is ready to copy/paste for the next session Include both full and quick version (/handoff-receive command)

Confirm to {user_name} in {communication_language}:

Display completion message:

  • Handoff successfully created and saved
  • Memory location in Serena
  • Next session prompt is ready to use
  • Remind about /handoff-receive as the quick option

Workflow execution complete

Important Execution Notes

Timestamp Format

  • Use 24-hour format: HHmmss (e.g., 161530 for 4:15:30 PM)
  • Prevents naming collisions with multiple handoffs per day
  • Enables proper chronological sorting

BMAD Integration

This workflow works seamlessly with:

  • /workflow-status - Provides current state and next action
  • /handoff-receive - Loads and displays the handoff
  • BMAD agents - Standard agent handoff protocol

Error Recovery

If any step fails:

  1. Display clear error message with context
  2. Provide actionable troubleshooting steps
  3. Allow user to retry or cancel gracefully
  4. Never lose generated content (show to user even if save fails)

Version Compatibility

  • Tested with: BMAD v6.x
  • Requires: Serena MCP for memory persistence
  • Compatible with: /workflow-status command (BMAD v6+)