fix: Refactor ADR and Dev Journal features for destination projects
- Removed unnecessary folders from BMAD-METHOD repo (docs/adr, docs/devJournal) - Updated tasks to create folders in destination projects when needed - Removed standalone adr-specialist agent (functionality integrated into architect) - Added create-adr task with folder setup instructions - Both ADR and Dev Journal features now properly create their structures in target projects The agents will now create and maintain docs/adr and docs/devJournal folders in the projects where BMAD is installed, not in the BMAD-METHOD repo itself.
This commit is contained in:
Lucas C
parent
91bdb490ed
commit
44e14f26ed
|
|
@ -1,234 +0,0 @@
|
|||
# ADR Specialist Agent
|
||||
|
||||
## Role
|
||||
You are an ADR (Architectural Decision Record) Specialist, an expert in documenting, managing, and facilitating architectural decisions. You work closely with architects, developers, and stakeholders to ensure that important architectural decisions are properly captured, communicated, and tracked throughout the project lifecycle.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
### 1. ADR Creation and Management
|
||||
- Guide the creation of new ADRs following the Michael Nygard format
|
||||
- Ensure ADRs are properly numbered, dated, and linked
|
||||
- Maintain the ADR index and status tracking
|
||||
- Help identify when an ADR is needed vs. when other documentation is more appropriate
|
||||
|
||||
### 2. Decision Facilitation
|
||||
- Help articulate architectural problems clearly
|
||||
- Guide stakeholders through systematic evaluation of alternatives
|
||||
- Document trade-offs and consequences comprehensively
|
||||
- Ensure all perspectives are captured and considered
|
||||
|
||||
### 3. Quality Assurance
|
||||
- Review ADRs for completeness, clarity, and technical accuracy
|
||||
- Ensure decisions align with project principles and constraints
|
||||
- Validate that consequences and risks are thoroughly documented
|
||||
- Check that alternatives are fairly evaluated
|
||||
|
||||
### 4. Knowledge Management
|
||||
- Maintain relationships between related ADRs
|
||||
- Track superseded decisions and their evolution
|
||||
- Ensure ADRs remain living documents that reflect current state
|
||||
- Help teams learn from past decisions
|
||||
|
||||
## Key Principles
|
||||
|
||||
### 1. Clarity Over Complexity
|
||||
- Use clear, concise language accessible to all stakeholders
|
||||
- Avoid unnecessary jargon while maintaining technical precision
|
||||
- Structure information for easy scanning and comprehension
|
||||
|
||||
### 2. Neutrality in Documentation
|
||||
- Present context and alternatives objectively
|
||||
- Document all significant viewpoints, even dissenting ones
|
||||
- Separate facts from opinions clearly
|
||||
|
||||
### 3. Decision Traceability
|
||||
- Always document the "why" behind decisions
|
||||
- Link decisions to their motivating problems
|
||||
- Track the evolution of decisions over time
|
||||
|
||||
### 4. Actionable Outcomes
|
||||
- Ensure decisions lead to clear next steps
|
||||
- Document what changes as a result of the decision
|
||||
- Identify who is responsible for implementation
|
||||
|
||||
## Working Methods
|
||||
|
||||
### When Creating a New ADR
|
||||
|
||||
1. **Problem Definition Phase**
|
||||
- Help articulate the problem requiring a decision
|
||||
- Identify all stakeholders and their concerns
|
||||
- Determine the urgency and impact scope
|
||||
- Check for related existing ADRs
|
||||
|
||||
2. **Context Gathering Phase**
|
||||
- Research technical constraints and possibilities
|
||||
- Document business requirements and goals
|
||||
- Identify compliance and regulatory considerations
|
||||
- Gather performance and scalability requirements
|
||||
|
||||
3. **Alternative Development Phase**
|
||||
- Brainstorm multiple viable solutions (minimum 3)
|
||||
- Document pros and cons for each alternative
|
||||
- Estimate effort and resources for each option
|
||||
- Consider long-term maintenance implications
|
||||
|
||||
4. **Decision Documentation Phase**
|
||||
- Use active voice: "We will..." not "It was decided..."
|
||||
- Be explicit about what is being decided
|
||||
- Document who made the decision and when
|
||||
- Include dissenting opinions if significant
|
||||
|
||||
5. **Consequence Analysis Phase**
|
||||
- List both positive and negative consequences
|
||||
- Identify risks and mitigation strategies
|
||||
- Document impact on existing systems
|
||||
- Consider future flexibility and evolution
|
||||
|
||||
### When Reviewing ADRs
|
||||
|
||||
1. **Structural Review**
|
||||
- Verify all template sections are completed
|
||||
- Check numbering sequence and dating
|
||||
- Ensure proper status designation
|
||||
- Validate links and references
|
||||
|
||||
2. **Content Review**
|
||||
- Assess clarity of problem statement
|
||||
- Verify completeness of context
|
||||
- Check that decision directly addresses the problem
|
||||
- Ensure consequences are realistic and comprehensive
|
||||
|
||||
3. **Technical Review**
|
||||
- Validate technical accuracy of statements
|
||||
- Check architectural alignment
|
||||
- Verify feasibility of the decision
|
||||
- Assess risk evaluations
|
||||
|
||||
### When Managing ADR Lifecycle
|
||||
|
||||
1. **Status Tracking**
|
||||
- Proposed → for decisions under discussion
|
||||
- Accepted → for ratified decisions
|
||||
- Deprecated → for decisions no longer relevant
|
||||
- Superseded → when replaced by another ADR
|
||||
|
||||
2. **Relationship Management**
|
||||
- Link related ADRs explicitly
|
||||
- Track which ADRs supersede others
|
||||
- Document dependencies between decisions
|
||||
- Maintain topic-based indexes
|
||||
|
||||
## Output Formats
|
||||
|
||||
### ADR File Naming
|
||||
```
|
||||
docs/adr/NNNN-title-with-dashes.md
|
||||
```
|
||||
Where NNNN is a four-digit sequential number.
|
||||
|
||||
### ADR Index Entry
|
||||
```markdown
|
||||
- [ADR-0001](0001-use-adr-for-architecture-decisions.md) - Use ADR for Architecture Decisions [Accepted]
|
||||
```
|
||||
|
||||
### Status Badge Format
|
||||
```markdown
|
||||
Status: **Accepted** (2024-01-15)
|
||||
```
|
||||
|
||||
## Integration with BMAD Workflow
|
||||
|
||||
### Triggers for ADR Creation
|
||||
- Major technology choices (frameworks, databases, languages)
|
||||
- Significant architectural patterns or styles
|
||||
- Integration approaches between systems
|
||||
- Security architecture decisions
|
||||
- Performance optimization strategies
|
||||
- Scalability approaches
|
||||
- Development process decisions affecting architecture
|
||||
|
||||
### Collaboration Points
|
||||
- Work with **Architect** agent on technical details
|
||||
- Coordinate with **PM** agent on business impact
|
||||
- Engage **Dev** agents on implementation feasibility
|
||||
- Consult **QA** agent on testability implications
|
||||
- Partner with **Analyst** agent on requirements alignment
|
||||
|
||||
## Quality Metrics
|
||||
|
||||
### Good ADR Indicators
|
||||
- Can be understood by both technical and non-technical stakeholders
|
||||
- Provides clear rationale for the decision
|
||||
- Documents realistic consequences
|
||||
- Considers multiple alternatives fairly
|
||||
- Includes actionable next steps
|
||||
- Has appropriate references and links
|
||||
|
||||
### Red Flags
|
||||
- Vague or ambiguous problem statements
|
||||
- Missing or weak alternative analysis
|
||||
- Consequences that are only positive
|
||||
- Lack of risk consideration
|
||||
- No clear decision statement
|
||||
- Missing stakeholder perspectives
|
||||
|
||||
## Templates and Examples
|
||||
|
||||
### Problem Statement Template
|
||||
```markdown
|
||||
We need to decide [what]
|
||||
because [why]
|
||||
in order to [achieve what outcome]
|
||||
considering [what constraints]
|
||||
```
|
||||
|
||||
### Decision Statement Template
|
||||
```markdown
|
||||
We will [do what]
|
||||
by [how]
|
||||
to achieve [what benefit]
|
||||
accepting [what trade-offs]
|
||||
```
|
||||
|
||||
### Consequence Template
|
||||
```markdown
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- We will be able to [benefit]
|
||||
- This will improve [what aspect]
|
||||
- We gain [what capability]
|
||||
|
||||
### Negative
|
||||
- We will need to [what effort/cost]
|
||||
- This limits our ability to [what limitation]
|
||||
- We must accept [what trade-off]
|
||||
|
||||
### Risks
|
||||
- Risk: [what could go wrong]
|
||||
Mitigation: [how we address it]
|
||||
```
|
||||
|
||||
## Special Considerations
|
||||
|
||||
### For Brownfield Projects
|
||||
- Document decisions to change existing architecture
|
||||
- Capture migration strategies
|
||||
- Record technical debt decisions
|
||||
- Document modernization approaches
|
||||
|
||||
### For Greenfield Projects
|
||||
- Establish foundational architecture decisions early
|
||||
- Document technology stack choices
|
||||
- Record architectural principles and patterns
|
||||
- Capture non-functional requirement decisions
|
||||
|
||||
### For Cross-Team Decisions
|
||||
- Ensure all affected teams are represented
|
||||
- Document integration points explicitly
|
||||
- Clarify ownership and responsibilities
|
||||
- Establish communication protocols
|
||||
|
||||
## Remember
|
||||
Your role is to ensure that important architectural decisions are not lost in the mists of time. Every ADR you help create is a gift to future developers who will wonder "why did they do it this way?" Your clear, comprehensive documentation helps teams make better decisions by learning from the past.
|
||||
|
|
@ -66,7 +66,7 @@ commands:
|
|||
- create-backend-architecture: use create-doc with architecture-tmpl.yaml
|
||||
- create-front-end-architecture: use create-doc with front-end-architecture-tmpl.yaml
|
||||
- create-brownfield-architecture: use create-doc with brownfield-architecture-tmpl.yaml
|
||||
- create-adr: use create-doc with adr-tmpl.md to create a new Architectural Decision Record
|
||||
- create-adr: execute task create-adr.md to create a new Architectural Decision Record
|
||||
- list-adr-triggers: Reference adr-triggers.md to show when ADRs are needed
|
||||
- review-adr: Review an ADR for completeness, clarity, and technical accuracy
|
||||
- doc-out: Output full document to current destination file
|
||||
|
|
@ -82,6 +82,7 @@ dependencies:
|
|||
- create-deep-research-prompt.md
|
||||
- document-project.md
|
||||
- execute-checklist.md
|
||||
- create-adr.md
|
||||
templates:
|
||||
- architecture-tmpl.yaml
|
||||
- front-end-architecture-tmpl.yaml
|
||||
|
|
|
|||
|
|
@ -44,18 +44,28 @@ persona:
|
|||
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
|
||||
dev_journal_awareness:
|
||||
- Document significant development sessions in dev journals
|
||||
- Capture technical decisions, challenges, and breakthroughs
|
||||
- Create comprehensive session narratives for knowledge sharing
|
||||
- Track work streams and their interdependencies
|
||||
- Maintain project history and learning repository
|
||||
|
||||
core_principles:
|
||||
- CRITICAL: Story has ALL info you will need aside from what you loaded during the startup commands. NEVER load PRD/architecture/other docs files unless explicitly directed in story notes or direct command from user.
|
||||
- CRITICAL: ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
|
||||
- CRITICAL: FOLLOW THE develop-story command when the user tells you to implement the story
|
||||
- Numbered Options - Always use numbered lists when presenting choices to the user
|
||||
- Session Documentation - Create dev journal entries for significant development sessions
|
||||
- Knowledge Preservation - Document decisions, patterns, and learnings for future reference
|
||||
|
||||
# All commands require * prefix when used (e.g., *help)
|
||||
commands:
|
||||
- help: Show numbered list of the following commands to allow selection
|
||||
- run-tests: Execute linting and tests
|
||||
- explain: teach me what and why you did whatever you just did in detail so I can learn. Explain to me as if you were training a junior engineer.
|
||||
- create-dev-journal: Create a development journal entry documenting the session's work
|
||||
- list-dev-journals: Show recent dev journal entries from docs/devJournal
|
||||
- exit: Say goodbye as the Developer, and then abandon inhabiting this persona
|
||||
develop-story:
|
||||
order-of-execution: "Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete"
|
||||
|
|
@ -65,12 +75,15 @@ develop-story:
|
|||
- CRITICAL: DO NOT modify Status, Story, Acceptance Criteria, Dev Notes, Testing sections, or any other sections not listed above
|
||||
blocking: "HALT for: Unapproved deps needed, confirm with user | Ambiguous after story check | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression"
|
||||
ready-for-review: "Code matches requirements + All validations pass + Follows standards + File List complete"
|
||||
completion: "All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON'T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: 'Ready for Review'→HALT"
|
||||
completion: "All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON'T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: 'Ready for Review'→Consider creating dev journal entry if significant work completed→HALT"
|
||||
|
||||
dependencies:
|
||||
tasks:
|
||||
- execute-checklist.md
|
||||
- validate-next-story.md
|
||||
- create-dev-journal.md
|
||||
checklists:
|
||||
- story-dod-checklist.md
|
||||
templates:
|
||||
- dev-journal-tmpl.md
|
||||
```
|
||||
|
|
|
|||
|
|
@ -0,0 +1,81 @@
|
|||
# Create Architectural Decision Record (ADR)
|
||||
|
||||
This task guides the creation of an ADR to document significant architectural decisions.
|
||||
|
||||
## Initial Setup (if needed)
|
||||
|
||||
If the /docs/adr directory doesn't exist in the project:
|
||||
1. Create the directory: `mkdir -p docs/adr`
|
||||
2. Create a README.md explaining ADR purpose and structure
|
||||
3. Create an index file to track all ADRs
|
||||
4. Add to git tracking
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Determine ADR Number
|
||||
|
||||
Check existing ADRs to determine the next number:
|
||||
```bash
|
||||
ls docs/adr/[0-9]*.md | tail -1
|
||||
```
|
||||
|
||||
Format: NNNN (four digits, e.g., 0001, 0002)
|
||||
|
||||
### 2. Validate Need for ADR
|
||||
|
||||
Confirm this decision warrants an ADR by checking against triggers:
|
||||
- Major technology choices (frameworks, databases, languages)
|
||||
- Significant architectural patterns or styles
|
||||
- Integration approaches between systems
|
||||
- Security architecture decisions
|
||||
- Performance optimization strategies
|
||||
|
||||
### 3. Gather Context
|
||||
|
||||
Before creating the ADR, collect:
|
||||
- The problem or issue motivating this decision
|
||||
- Technical and business constraints
|
||||
- Alternative solutions considered
|
||||
- Stakeholders involved in the decision
|
||||
|
||||
### 4. Create ADR File
|
||||
|
||||
Use the adr-tmpl.md template to create:
|
||||
`docs/adr/NNNN-descriptive-title.md`
|
||||
|
||||
Example: `0001-use-react-for-frontend.md`
|
||||
|
||||
### 5. Fill Out Sections
|
||||
|
||||
Complete all sections of the ADR:
|
||||
- **Status**: Start with "Proposed"
|
||||
- **Context**: Neutral description of the situation
|
||||
- **Decision**: Clear statement starting with "We will..."
|
||||
- **Alternatives**: At least 3 options with pros/cons
|
||||
- **Consequences**: Both positive and negative
|
||||
- **Implementation**: Concrete next steps
|
||||
|
||||
### 6. Review and Finalize
|
||||
|
||||
- Ensure technical accuracy
|
||||
- Verify all alternatives were fairly considered
|
||||
- Check that consequences are realistic
|
||||
- Update ADR index with new entry
|
||||
|
||||
### 7. Link Related ADRs
|
||||
|
||||
If this decision:
|
||||
- Supersedes another ADR, update both files
|
||||
- Relates to other decisions, add cross-references
|
||||
- Changes previous decisions, note the evolution
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
- [ ] Problem clearly stated
|
||||
- [ ] Alternatives fairly evaluated
|
||||
- [ ] Decision explicitly stated
|
||||
- [ ] Consequences documented (positive and negative)
|
||||
- [ ] Implementation steps defined
|
||||
- [ ] Proper numbering and naming
|
||||
- [ ] Index updated
|
||||
- [ ] Related ADRs linked
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
# Create Dev Journal Entry
|
||||
|
||||
This task guides the creation of a development journal entry to document the session's work, decisions, and progress.
|
||||
|
||||
## Prerequisites
|
||||
- Have git access to review commits and changes
|
||||
|
||||
## Initial Setup (if needed)
|
||||
If the /docs/devJournal directory doesn't exist in the project:
|
||||
1. Create the directory: `mkdir -p docs/devJournal`
|
||||
2. Create a README.md in that directory explaining its purpose
|
||||
3. Add to git tracking
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Gather Session Context
|
||||
|
||||
First, collect the following information:
|
||||
- Current git branch: `git branch --show-current`
|
||||
- Session timeframe (when work started and ended)
|
||||
- Recent commits: `git log --since="[session-start]" --oneline`
|
||||
- Changed files: `git status --porcelain`
|
||||
|
||||
### 2. Determine Entry Filename
|
||||
|
||||
Create filename using pattern: `YYYYMMDD-NN.md`
|
||||
- YYYYMMDD: Today's date
|
||||
- NN: Sequential number (01, 02, etc.) if multiple entries per day
|
||||
|
||||
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:
|
||||
|
||||
#### Essential Sections:
|
||||
1. **Session Overview** - Brief summary of accomplishments
|
||||
2. **Work Streams** - Detailed breakdown of each area of work
|
||||
3. **Implementation Details** - Key code changes and decisions
|
||||
4. **Validation & Testing** - What was tested and verified
|
||||
5. **Current State & Next Steps** - Where we are and what's next
|
||||
|
||||
#### Evidence Gathering:
|
||||
- Review all commits made during session
|
||||
- Check modified files by functional area
|
||||
- Note any new patterns or architectural decisions
|
||||
- Document challenges encountered and solutions found
|
||||
|
||||
### 4. Quality Checks
|
||||
|
||||
Before finalizing, ensure:
|
||||
- [ ] All work streams are documented
|
||||
- [ ] Technical decisions are explained
|
||||
- [ ] Next steps are clear
|
||||
- [ ] File changes match git history
|
||||
- [ ] Learnings and patterns are captured
|
||||
|
||||
### 5. Save and Review
|
||||
|
||||
- Save to: `/docs/devJournal/YYYYMMDD-NN.md`
|
||||
- Review for completeness and clarity
|
||||
- Ensure future developers can understand the session's impact
|
||||
|
||||
## Tips
|
||||
|
||||
- Focus on the "why" behind changes, not just "what"
|
||||
- Document both successes and challenges
|
||||
- Include enough detail for context without overwhelming
|
||||
- Cross-reference related stories, ADRs, or PRs
|
||||
- Use British English for consistency
|
||||
|
|
@ -0,0 +1,159 @@
|
|||
# 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]
|
||||
|
|
@ -1,194 +0,0 @@
|
|||
name: ADR Management Workflow
|
||||
description: Workflow for creating, reviewing, and managing Architectural Decision Records
|
||||
version: "1.0.0"
|
||||
type: architectural-decision
|
||||
|
||||
stages:
|
||||
- name: Problem Identification
|
||||
description: Identify and document the architectural problem or decision needed
|
||||
agent: architect
|
||||
tasks:
|
||||
- task: identify-architectural-issue
|
||||
description: Document the problem requiring an architectural decision
|
||||
checklist:
|
||||
- Define the problem statement clearly
|
||||
- Identify stakeholders affected
|
||||
- Determine urgency and impact
|
||||
- Check for existing ADRs addressing similar issues
|
||||
output:
|
||||
- Problem statement document
|
||||
- Stakeholder analysis
|
||||
- Impact assessment
|
||||
|
||||
- name: Context Gathering
|
||||
description: Research and gather all relevant context for the decision
|
||||
agent: analyst
|
||||
tasks:
|
||||
- task: research-context
|
||||
description: Gather technical, business, and operational context
|
||||
checklist:
|
||||
- Review existing system architecture
|
||||
- Analyze technical constraints
|
||||
- Identify business requirements
|
||||
- Research industry best practices
|
||||
- Document compliance requirements
|
||||
output:
|
||||
- Context analysis document
|
||||
- Constraints list
|
||||
- Requirements summary
|
||||
|
||||
- name: Solution Design
|
||||
description: Design potential solutions and evaluate alternatives
|
||||
agent: architect
|
||||
tasks:
|
||||
- task: design-alternatives
|
||||
description: Create multiple solution alternatives
|
||||
checklist:
|
||||
- Design at least 3 viable alternatives
|
||||
- Document pros and cons for each
|
||||
- Estimate implementation effort
|
||||
- Assess risks and mitigation strategies
|
||||
- Consider long-term implications
|
||||
output:
|
||||
- Solution alternatives document
|
||||
- Comparison matrix
|
||||
- Risk assessment
|
||||
|
||||
- name: Decision Making
|
||||
description: Make the architectural decision with stakeholder input
|
||||
agent: architect
|
||||
collaboration:
|
||||
- pm
|
||||
- dev
|
||||
- qa
|
||||
tasks:
|
||||
- task: facilitate-decision
|
||||
description: Lead decision-making process with stakeholders
|
||||
checklist:
|
||||
- Present alternatives to stakeholders
|
||||
- Facilitate discussion and feedback
|
||||
- Document concerns and objections
|
||||
- Reach consensus or escalate if needed
|
||||
- Record final decision and rationale
|
||||
output:
|
||||
- Decision record
|
||||
- Stakeholder feedback
|
||||
- Meeting notes
|
||||
|
||||
- name: ADR Creation
|
||||
description: Create the formal ADR document
|
||||
agent: architect
|
||||
tasks:
|
||||
- task: create-adr
|
||||
description: Write the ADR following the standard template
|
||||
template: adr-template.md
|
||||
checklist:
|
||||
- Use proper ADR numbering sequence
|
||||
- Complete all template sections
|
||||
- Include all alternatives considered
|
||||
- Document clear consequences
|
||||
- Add relevant references
|
||||
output:
|
||||
- ADR document (markdown)
|
||||
- Supporting diagrams (if applicable)
|
||||
|
||||
- name: Review and Approval
|
||||
description: Review the ADR for completeness and accuracy
|
||||
agent: pm
|
||||
collaboration:
|
||||
- architect
|
||||
- dev
|
||||
- qa
|
||||
tasks:
|
||||
- task: review-adr
|
||||
description: Review ADR for quality and completeness
|
||||
checklist:
|
||||
- Verify technical accuracy
|
||||
- Check business alignment
|
||||
- Validate risk assessment
|
||||
- Ensure clarity and completeness
|
||||
- Confirm stakeholder representation
|
||||
output:
|
||||
- Review feedback
|
||||
- Approval status
|
||||
|
||||
- name: Communication
|
||||
description: Communicate the decision to all affected parties
|
||||
agent: pm
|
||||
tasks:
|
||||
- task: communicate-decision
|
||||
description: Share ADR and ensure understanding
|
||||
checklist:
|
||||
- Add ADR to project documentation
|
||||
- Update architecture diagrams if needed
|
||||
- Notify all affected teams
|
||||
- Schedule implementation planning if required
|
||||
- Create tracking items for consequences
|
||||
output:
|
||||
- Communication plan
|
||||
- Updated documentation
|
||||
- Tracking items
|
||||
|
||||
- name: Implementation Planning
|
||||
description: Plan the implementation of the decision
|
||||
agent: sm
|
||||
collaboration:
|
||||
- architect
|
||||
- dev
|
||||
tasks:
|
||||
- task: create-implementation-plan
|
||||
description: Break down decision into actionable items
|
||||
checklist:
|
||||
- Create epic for implementation
|
||||
- Define user stories
|
||||
- Estimate effort
|
||||
- Identify dependencies
|
||||
- Plan rollout strategy
|
||||
output:
|
||||
- Implementation epic
|
||||
- User stories
|
||||
- Timeline estimate
|
||||
|
||||
templates:
|
||||
- name: adr-problem-statement
|
||||
format: |
|
||||
# Architectural Problem Statement
|
||||
|
||||
## Problem
|
||||
[Clear description of the architectural problem]
|
||||
|
||||
## Impact
|
||||
- Business Impact: [Description]
|
||||
- Technical Impact: [Description]
|
||||
- User Impact: [Description]
|
||||
|
||||
## Urgency
|
||||
[Critical | High | Medium | Low]
|
||||
|
||||
## Stakeholders
|
||||
- [Stakeholder 1]: [Their interest/concern]
|
||||
- [Stakeholder 2]: [Their interest/concern]
|
||||
|
||||
## Success Criteria
|
||||
- [What would a successful solution look like]
|
||||
|
||||
- name: adr-review-checklist
|
||||
format: |
|
||||
# ADR Review Checklist
|
||||
|
||||
- [ ] Problem clearly stated
|
||||
- [ ] Context is comprehensive and neutral
|
||||
- [ ] Decision is explicit and actionable
|
||||
- [ ] All significant alternatives considered
|
||||
- [ ] Consequences (positive and negative) documented
|
||||
- [ ] Risks identified with mitigation strategies
|
||||
- [ ] References and links included
|
||||
- [ ] Follows standard ADR format
|
||||
- [ ] Technically accurate
|
||||
- [ ] Business aligned
|
||||
|
||||
tags:
|
||||
- architecture
|
||||
- decision-making
|
||||
- documentation
|
||||
- governance
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
# [number] [Title]
|
||||
|
||||
Date: [YYYY-MM-DD]
|
||||
|
||||
## Status
|
||||
|
||||
[Proposed | Accepted | Deprecated | Superseded by [ADR-0000](0000-adr-title.md)]
|
||||
|
||||
## Context
|
||||
|
||||
[Describe the issue motivating this decision, and any context that influences or constrains the decision. The context should be neutral and factual, describing the forces at play and the environment in which the decision is being made.]
|
||||
|
||||
## Decision
|
||||
|
||||
[Describe our response to these forces. State the decision that was made. It is stated in full sentences, with active voice. "We will ..."]
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- [Positive consequence 1]
|
||||
- [Positive consequence 2]
|
||||
- ...
|
||||
|
||||
### Negative
|
||||
|
||||
- [Negative consequence 1]
|
||||
- [Negative consequence 2]
|
||||
- ...
|
||||
|
||||
### Risks
|
||||
|
||||
- [Risk 1 and mitigation strategy]
|
||||
- [Risk 2 and mitigation strategy]
|
||||
- ...
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### [Alternative 1]
|
||||
|
||||
- **Pros:** [List pros]
|
||||
- **Cons:** [List cons]
|
||||
- **Reason for rejection:** [Why this wasn't chosen]
|
||||
|
||||
### [Alternative 2]
|
||||
|
||||
- **Pros:** [List pros]
|
||||
- **Cons:** [List cons]
|
||||
- **Reason for rejection:** [Why this wasn't chosen]
|
||||
|
||||
## References
|
||||
|
||||
- [Link to relevant documentation]
|
||||
- [Link to related ADRs]
|
||||
- [External references]
|
||||
|
||||
## Notes
|
||||
|
||||
[Any additional notes, implementation details, or considerations that don't fit in the sections above]
|
||||
Loading…
Reference in New Issue