From b6ca88a6080f9decf5b936347d0a06b275c4fb38 Mon Sep 17 00:00:00 2001 From: Lucas C Date: Sun, 20 Jul 2025 18:55:51 +0200 Subject: [PATCH] refactor(templates): Convert dev journal template to YAML format Converted dev-journal-tmpl.md to dev-journal-tmpl.yaml for consistency with BMAD framework template standards and improved functionality. YAML Template Features: - Guided workflow with structured prompting system - Comprehensive sections for session documentation - Template variables for dynamic content generation - Validation rules for required fields - Output configuration for docs/devJournal/ directory - Consistent with other YAML templates in framework Updated References: - dev.md agent updated to use dev-journal-tmpl.yaml - create-dev-journal.md task updated to reference YAML template This completes the conversion of all framework templates to YAML format, ensuring consistency and leveraging the full BMAD template system capabilities. --- bmad-core/agents/dev.md | 2 +- bmad-core/tasks/create-dev-journal.md | 2 +- bmad-core/templates/dev-journal-tmpl.md | 159 ---------- bmad-core/templates/dev-journal-tmpl.yaml | 366 ++++++++++++++++++++++ 4 files changed, 368 insertions(+), 161 deletions(-) delete mode 100644 bmad-core/templates/dev-journal-tmpl.md create mode 100644 bmad-core/templates/dev-journal-tmpl.yaml diff --git a/bmad-core/agents/dev.md b/bmad-core/agents/dev.md index 879cfb73..a64660d0 100644 --- a/bmad-core/agents/dev.md +++ b/bmad-core/agents/dev.md @@ -97,7 +97,7 @@ dependencies: checklists: - story-dod-checklist.md templates: - - dev-journal-tmpl.md + - dev-journal-tmpl.yaml - activeContext-tmpl.yaml - progress-tmpl.yaml ``` diff --git a/bmad-core/tasks/create-dev-journal.md b/bmad-core/tasks/create-dev-journal.md index b4355f19..75bc998a 100644 --- a/bmad-core/tasks/create-dev-journal.md +++ b/bmad-core/tasks/create-dev-journal.md @@ -31,7 +31,7 @@ Check existing entries: `ls docs/devJournal/YYYYMMDD-*.md` ### 3. Create Journal Entry -Use the dev-journal-tmpl.md template to create a comprehensive entry covering: +Use the dev-journal-tmpl.yaml template to create a comprehensive entry covering: #### Essential Sections: 1. **Session Overview** - Brief summary of accomplishments diff --git a/bmad-core/templates/dev-journal-tmpl.md b/bmad-core/templates/dev-journal-tmpl.md deleted file mode 100644 index 21a57096..00000000 --- a/bmad-core/templates/dev-journal-tmpl.md +++ /dev/null @@ -1,159 +0,0 @@ -# Dev Journal Entry: [YYYY-MM-DD-NN] - -**Date:** [YYYY-MM-DD] -**Session Duration:** [Start Time - End Time] -**Branch:** [Current Git Branch] -**Developer:** [Agent Name/Human Developer] -**Session Type:** [Implementation | Bug Fix | Refactoring | Feature Development | Investigation] - -## Session Overview - -[Brief 2-3 sentence summary of what this session accomplished] - -## Context & Starting Point - -### Previous Session Reference -- **Last Entry:** [Link to previous journal entry if applicable] -- **Starting State:** [What was the state of the project at session start] - -### Session Goals -- [Primary objective for this session] -- [Secondary objectives if any] - -## The Journey - -### Initial Problem/Task - -[Describe the initial request, problem, or task that initiated this session. Include any error messages, user stories, or requirements] - -### Investigation & Analysis - -[Detail the exploration process:] -- What was examined first -- Initial hypotheses -- Tools and techniques used -- Dead ends or false starts - -### Work Streams - -#### Stream 1: [Name of Primary Work Stream] -**Type:** [Feature | Fix | Refactor | Documentation] -**Files Affected:** -- [List key files modified] - -**What Changed:** -[Specific changes made] - -**Why It Changed:** -[Problem being solved or improvement being made] - -**How It Changed:** -[Technical approach and patterns used] - -**Impact:** -[What this enables or fixes] - -#### Stream 2: [If applicable - Secondary Work Stream] -[Follow same structure as Stream 1] - -### Key Breakthroughs & Decisions - -1. **[Discovery/Decision Name]** - - **Context:** [What led to this] - - **Insight:** [The key realization] - - **Resolution:** [How it was addressed] - -### Implementation Details - -#### Code Changes -``` -[Summary of significant code changes with brief explanations] -``` - -#### Architecture/Pattern Changes -[Any new patterns introduced or architectural decisions made] - -#### Configuration Updates -[Environment variables, build configs, dependencies added/removed] - -## Validation & Testing - -### Tests Added/Modified -- [List of test files created or updated] -- [Test coverage improvements] - -### Manual Testing Performed -- [User flows tested] -- [Edge cases verified] - -### Validation Results -- [What was confirmed working] -- [Any remaining issues] - -## Documentation Updates - -- **Code Documentation:** [Inline comments, JSDoc, etc.] -- **Project Documentation:** [README, Wiki, API docs updated] -- **Architecture Decisions:** [ADRs created or updated] - -## Git Activity - -### Commits Made -```bash -# List commits with their messages -[commit hash] - [commit message] -``` - -### Files Summary -- **Added:** [count] files -- **Modified:** [count] files -- **Deleted:** [count] files - -## Challenges & Learnings - -### Challenges Encountered -1. [Challenge and how it was overcome] - -### Key Learnings -1. [Technical insight or pattern discovered] -2. [Process improvement identified] - -### Patterns Established -[Any new coding patterns or conventions established during this session] - -## Current State & Next Steps - -### What's Working -- [Completed features or fixes that are now functional] - -### Known Issues -- [Any bugs or limitations discovered but not yet resolved] - -### Technical Debt -- [Any shortcuts taken that need future attention] - -### Immediate Next Steps -1. [Most urgent task for next session] -2. [Secondary priorities] - -### Future Considerations -- [Longer-term improvements or refactoring needs] - -## Session Metrics - -- **Story Tasks Completed:** [X of Y] -- **Tests Written:** [count] -- **Code Coverage:** [if measured] -- **Performance Impact:** [if relevant] - -## Notes for Future Sessions - -[Any important context, gotchas, or reminders for the next developer session] - ---- - -### Cross-References -- **Related Stories:** [Story IDs or links] -- **Related ADRs:** [ADR numbers if applicable] -- **Related PRs:** [Pull request references] -- **External Resources:** [Helpful links or documentation consulted] \ No newline at end of file diff --git a/bmad-core/templates/dev-journal-tmpl.yaml b/bmad-core/templates/dev-journal-tmpl.yaml new file mode 100644 index 00000000..073fabe1 --- /dev/null +++ b/bmad-core/templates/dev-journal-tmpl.yaml @@ -0,0 +1,366 @@ +template: + id: dev-journal-template-v1 + name: Development Journal Entry + version: 1.0 + output: + format: markdown + filename: docs/devJournal/{{journal_filename}}.md + title: "Dev Journal Entry: {{journal_filename}}" + description: | + Template for creating comprehensive development journal entries to document + session work, decisions, and progress for knowledge sharing and continuity. + +workflow: + mode: guided + instruction: | + Document a development session with comprehensive details including work streams, + decisions, challenges, and learnings. Gather context from git history and + session notes before starting. + +sections: + - id: header + title: Session Header + instruction: Capture session metadata and overview + template: | + # Dev Journal Entry: {{journal_filename}} + + **Date:** {{session_date}} + **Session Duration:** {{start_time}} - {{end_time}} + **Branch:** {{git_branch}} + **Developer:** {{developer_name}} + **Session Type:** {{session_type}} + + - id: session-overview + title: Session Overview + instruction: Provide a brief summary of accomplishments + template: | + ## Session Overview + + {{session_summary}} + + - id: context + title: Context & Starting Point + instruction: Document where the session started and objectives + template: | + ## Context & Starting Point + + ### Previous Session Reference + {{#if previous_entry}} + - **Last Entry:** {{previous_entry}} + {{/if}} + - **Starting State:** {{starting_state}} + + ### Session Goals + {{#each session_goals}} + - {{this}} + {{/each}} + + - id: journey + title: The Journey + instruction: Document the detailed work process + template: | + ## The Journey + + ### Initial Problem/Task + + {{initial_problem}} + + ### Investigation & Analysis + + {{investigation_process}} + + - id: work-streams + title: Work Streams + instruction: Detail each major area of work with specific changes + template: | + ### Work Streams + + {{#each work_streams}} + #### Stream {{@index + 1}}: {{this.name}} + **Type:** {{this.type}} + **Files Affected:** + {{#each this.files}} + - {{this}} + {{/each}} + + **What Changed:** + {{this.what_changed}} + + **Why It Changed:** + {{this.why_changed}} + + **How It Changed:** + {{this.how_changed}} + + **Impact:** + {{this.impact}} + + {{/each}} + + - id: breakthroughs + title: Key Breakthroughs & Decisions + instruction: Document significant insights and decisions made + template: | + ### Key Breakthroughs & Decisions + + {{#each breakthroughs}} + {{@index + 1}}. **{{this.name}}** + - **Context:** {{this.context}} + - **Insight:** {{this.insight}} + - **Resolution:** {{this.resolution}} + + {{/each}} + + - id: implementation + title: Implementation Details + instruction: Technical details of what was implemented + template: | + ### Implementation Details + + #### Code Changes + ``` + {{code_changes_summary}} + ``` + + {{#if architecture_changes}} + #### Architecture/Pattern Changes + {{architecture_changes}} + {{/if}} + + {{#if config_updates}} + #### Configuration Updates + {{config_updates}} + {{/if}} + + - id: validation + title: Validation & Testing + instruction: Document testing and validation performed + template: | + ## Validation & Testing + + ### Tests Added/Modified + {{#each tests_modified}} + - {{this}} + {{/each}} + + ### Manual Testing Performed + {{#each manual_testing}} + - {{this}} + {{/each}} + + ### Validation Results + - **Working:** {{validation_working}} + {{#if remaining_issues}} + - **Remaining Issues:** {{remaining_issues}} + {{/if}} + + - id: documentation + title: Documentation Updates + instruction: Document any documentation changes made + template: | + ## Documentation Updates + + - **Code Documentation:** {{code_documentation}} + - **Project Documentation:** {{project_documentation}} + {{#if adr_updates}} + - **Architecture Decisions:** {{adr_updates}} + {{/if}} + + - id: git-activity + title: Git Activity + instruction: Summarize git commits and file changes + template: | + ## Git Activity + + ### Commits Made + ```bash + {{#each commits}} + {{this.hash}} - {{this.message}} + {{/each}} + ``` + + ### Files Summary + - **Added:** {{files_added}} files + - **Modified:** {{files_modified}} files + - **Deleted:** {{files_deleted}} files + + - id: challenges-learnings + title: Challenges & Learnings + instruction: Capture challenges faced and knowledge gained + template: | + ## Challenges & Learnings + + ### Challenges Encountered + {{#each challenges}} + {{@index + 1}}. {{this}} + {{/each}} + + ### Key Learnings + {{#each learnings}} + {{@index + 1}}. {{this}} + {{/each}} + + {{#if patterns_established}} + ### Patterns Established + {{patterns_established}} + {{/if}} + + - id: current-state + title: Current State & Next Steps + instruction: Document current project state and future priorities + template: | + ## Current State & Next Steps + + ### What's Working + {{#each working_features}} + - {{this}} + {{/each}} + + {{#if known_issues}} + ### Known Issues + {{#each known_issues}} + - {{this}} + {{/each}} + {{/if}} + + {{#if technical_debt}} + ### Technical Debt + {{#each technical_debt}} + - {{this}} + {{/each}} + {{/if}} + + ### Immediate Next Steps + {{#each immediate_next_steps}} + {{@index + 1}}. {{this}} + {{/each}} + + {{#if future_considerations}} + ### Future Considerations + {{#each future_considerations}} + - {{this}} + {{/each}} + {{/if}} + + - id: metrics + title: Session Metrics + instruction: Quantify session accomplishments + template: | + ## Session Metrics + + - **Story Tasks Completed:** {{story_tasks_completed}} + - **Tests Written:** {{tests_written}} + {{#if code_coverage}} + - **Code Coverage:** {{code_coverage}} + {{/if}} + {{#if performance_impact}} + - **Performance Impact:** {{performance_impact}} + {{/if}} + + - id: notes + title: Notes for Future Sessions + instruction: Important context for future developers + template: | + ## Notes for Future Sessions + + {{future_session_notes}} + + - id: cross-references + title: Cross-References + instruction: Link to related work and resources + template: | + --- + + ### Cross-References + {{#if related_stories}} + - **Related Stories:** {{related_stories}} + {{/if}} + {{#if related_adrs}} + - **Related ADRs:** {{related_adrs}} + {{/if}} + {{#if related_prs}} + - **Related PRs:** {{related_prs}} + {{/if}} + {{#if external_resources}} + - **External Resources:** {{external_resources}} + {{/if}} + +validation: + required_fields: + - session_date + - git_branch + - developer_name + - session_type + - session_summary + - starting_state + - session_goals + - work_streams + +prompts: + # Session metadata + journal_filename: "Journal filename (YYYYMMDD-NN format)" + session_date: "Session date (YYYY-MM-DD)" + start_time: "Session start time" + end_time: "Session end time" + git_branch: "Git branch worked on" + developer_name: "Developer name (agent or human)" + session_type: "Session type (Implementation, Bug Fix, Refactoring, Feature Development, Investigation)" + + # Session overview + session_summary: "Brief 2-3 sentence summary of session accomplishments" + starting_state: "State of the project at session start" + session_goals: "List session objectives" + previous_entry: "Link to previous journal entry (if applicable)" + + # Work details + initial_problem: "Initial request, problem, or task description" + investigation_process: "Detail exploration process, tools used, dead ends" + work_streams: "List work streams with details (name, type, files, changes, rationale, impact)" + breakthroughs: "Key discoveries and decisions with context and resolution" + + # Implementation + code_changes_summary: "Summary of significant code changes" + architecture_changes: "New patterns or architectural decisions" + config_updates: "Environment variables, build configs, dependencies" + + # Testing + tests_modified: "List test files created or updated" + manual_testing: "User flows and edge cases tested" + validation_working: "What was confirmed working" + remaining_issues: "Any remaining issues" + + # Documentation + code_documentation: "Inline comments, JSDoc updates" + project_documentation: "README, Wiki, API docs updated" + adr_updates: "ADRs created or updated" + + # Git activity + commits: "List commits with hash and message" + files_added: "Number of files added" + files_modified: "Number of files modified" + files_deleted: "Number of files deleted" + + # Learning + challenges: "List challenges and how overcome" + learnings: "Technical insights or patterns discovered" + patterns_established: "New coding patterns or conventions" + + # State and next steps + working_features: "Completed features or fixes that are functional" + known_issues: "Bugs or limitations discovered but not resolved" + technical_debt: "Shortcuts taken that need future attention" + immediate_next_steps: "Most urgent tasks for next session" + future_considerations: "Longer-term improvements or refactoring needs" + + # Metrics + story_tasks_completed: "Number of story tasks completed (X of Y)" + tests_written: "Number of tests written" + code_coverage: "Code coverage percentage (if measured)" + performance_impact: "Performance impact (if relevant)" + + # References + future_session_notes: "Important context, gotchas, or reminders" + related_stories: "Story IDs or links" + related_adrs: "ADR numbers if applicable" + related_prs: "Pull request references" + external_resources: "Helpful links or documentation consulted" \ No newline at end of file