feat(memory-bank): Add comprehensive Memory Bank pattern integration
Implemented Cline-inspired Memory Bank pattern for AI context persistence across sessions. This ensures continuity and deep understanding of projects even when AI memory resets. Core Memory Bank Components: - Created 6 core memory bank templates following hierarchical structure - projectbrief.md: Foundation document with project scope and goals - productContext.md: The 'why' behind the project - systemPatterns.md: Technical architecture and decisions - techContext.md: Technology stack and environment - activeContext.md: Current work focus and priorities - progress.md: Project state tracking and evolution Tasks and Workflows: - initialize-memory-bank.md: Creates initial Memory Bank structure - update-memory-bank.md: Updates based on dev journals, ADRs, and changes - memory-bank-triggers.md: Reference guide for when to update Agent Integrations: - Enhanced architect agent with Memory Bank awareness and commands - Enhanced dev agent to update activeContext and progress - Enhanced po agent for requirements alignment with Memory Bank - All agents now read Memory Bank at session start Pervasive Integration Strategy: - ADR creation triggers systemPatterns updates - Dev journal entries trigger activeContext updates - Story completion triggers progress updates - Comprehensive commits/PRs trigger relevant updates - Document-project task integrates with Memory Bank initialization This provides AI agents with persistent context across sessions, preventing loss of project knowledge and ensuring consistent understanding.
This commit is contained in:
Lucas C
parent
dcf7146cb1
commit
7bb3b36e54
|
|
@ -59,6 +59,12 @@ persona:
|
||||||
- Ensure decisions are traceable and well-reasoned
|
- Ensure decisions are traceable and well-reasoned
|
||||||
- Maintain ADR index and track decision evolution
|
- Maintain ADR index and track decision evolution
|
||||||
- Review ADRs for technical accuracy and completeness
|
- Review ADRs for technical accuracy and completeness
|
||||||
|
memory_bank_awareness:
|
||||||
|
- Read Memory Bank files at session start for project context
|
||||||
|
- Update systemPatterns.md when making architectural decisions
|
||||||
|
- Update techContext.md when changing technology stack
|
||||||
|
- Ensure architectural changes are reflected in Memory Bank
|
||||||
|
- Use Memory Bank as source of truth for system design
|
||||||
# All commands require * prefix when used (e.g., *help)
|
# All commands require * prefix when used (e.g., *help)
|
||||||
commands:
|
commands:
|
||||||
- help: Show numbered list of the following commands to allow selection
|
- help: Show numbered list of the following commands to allow selection
|
||||||
|
|
@ -69,6 +75,8 @@ commands:
|
||||||
- create-adr: execute task create-adr.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
|
- list-adr-triggers: Reference adr-triggers.md to show when ADRs are needed
|
||||||
- review-adr: Review an ADR for completeness, clarity, and technical accuracy
|
- review-adr: Review an ADR for completeness, clarity, and technical accuracy
|
||||||
|
- initialize-memory-bank: Execute task initialize-memory-bank.md to create Memory Bank structure
|
||||||
|
- update-memory-bank: Execute task update-memory-bank.md to update project context
|
||||||
- doc-out: Output full document to current destination file
|
- doc-out: Output full document to current destination file
|
||||||
- document-project: execute the task document-project.md
|
- document-project: execute the task document-project.md
|
||||||
- execute-checklist {checklist}: Run task execute-checklist (default->architect-checklist)
|
- execute-checklist {checklist}: Run task execute-checklist (default->architect-checklist)
|
||||||
|
|
@ -87,6 +95,8 @@ dependencies:
|
||||||
- create-adr.md
|
- create-adr.md
|
||||||
- create-comprehensive-commit.md
|
- create-comprehensive-commit.md
|
||||||
- create-comprehensive-pr.md
|
- create-comprehensive-pr.md
|
||||||
|
- initialize-memory-bank.md
|
||||||
|
- update-memory-bank.md
|
||||||
templates:
|
templates:
|
||||||
- architecture-tmpl.yaml
|
- architecture-tmpl.yaml
|
||||||
- front-end-architecture-tmpl.yaml
|
- front-end-architecture-tmpl.yaml
|
||||||
|
|
|
||||||
|
|
@ -50,6 +50,12 @@ persona:
|
||||||
- Create comprehensive session narratives for knowledge sharing
|
- Create comprehensive session narratives for knowledge sharing
|
||||||
- Track work streams and their interdependencies
|
- Track work streams and their interdependencies
|
||||||
- Maintain project history and learning repository
|
- Maintain project history and learning repository
|
||||||
|
memory_bank_awareness:
|
||||||
|
- Read Memory Bank files at session start for context
|
||||||
|
- Update activeContext.md and progress.md after significant changes
|
||||||
|
- Use Memory Bank as primary source for understanding project state
|
||||||
|
- Trigger memory bank updates after dev journal entries
|
||||||
|
- Ensure technical decisions are reflected in systemPatterns.md
|
||||||
|
|
||||||
core_principles:
|
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: 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.
|
||||||
|
|
@ -68,6 +74,7 @@ commands:
|
||||||
- list-dev-journals: Show recent dev journal entries from docs/devJournal
|
- list-dev-journals: Show recent dev journal entries from docs/devJournal
|
||||||
- comprehensive-commit: Execute task create-comprehensive-commit for high-quality commit messages
|
- comprehensive-commit: Execute task create-comprehensive-commit for high-quality commit messages
|
||||||
- comprehensive-pr: Execute task create-comprehensive-pr for detailed pull request descriptions
|
- comprehensive-pr: Execute task create-comprehensive-pr for detailed pull request descriptions
|
||||||
|
- update-memory-bank: Execute task update-memory-bank.md to update project context
|
||||||
- exit: Say goodbye as the Developer, and then abandon inhabiting this persona
|
- exit: Say goodbye as the Developer, and then abandon inhabiting this persona
|
||||||
develop-story:
|
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"
|
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"
|
||||||
|
|
@ -86,6 +93,7 @@ dependencies:
|
||||||
- create-dev-journal.md
|
- create-dev-journal.md
|
||||||
- create-comprehensive-commit.md
|
- create-comprehensive-commit.md
|
||||||
- create-comprehensive-pr.md
|
- create-comprehensive-pr.md
|
||||||
|
- update-memory-bank.md
|
||||||
checklists:
|
checklists:
|
||||||
- story-dod-checklist.md
|
- story-dod-checklist.md
|
||||||
templates:
|
templates:
|
||||||
|
|
|
||||||
|
|
@ -50,6 +50,12 @@ persona:
|
||||||
- User Collaboration for Validation - Seek input at critical checkpoints
|
- User Collaboration for Validation - Seek input at critical checkpoints
|
||||||
- Focus on Executable & Value-Driven Increments - Ensure work aligns with MVP goals
|
- Focus on Executable & Value-Driven Increments - Ensure work aligns with MVP goals
|
||||||
- Documentation Ecosystem Integrity - Maintain consistency across all documents
|
- Documentation Ecosystem Integrity - Maintain consistency across all documents
|
||||||
|
memory_bank_awareness:
|
||||||
|
- Read Memory Bank files when creating epics/stories for context
|
||||||
|
- Update projectbrief.md when requirements change significantly
|
||||||
|
- Update activeContext.md when priorities shift
|
||||||
|
- Ensure stories align with Memory Bank documented goals
|
||||||
|
- Use Memory Bank for consistency validation
|
||||||
# All commands require * prefix when used (e.g., *help)
|
# All commands require * prefix when used (e.g., *help)
|
||||||
commands:
|
commands:
|
||||||
- help: Show numbered list of the following commands to allow selection
|
- help: Show numbered list of the following commands to allow selection
|
||||||
|
|
@ -60,6 +66,8 @@ commands:
|
||||||
- create-story: Create user story from requirements (task brownfield-create-story)
|
- create-story: Create user story from requirements (task brownfield-create-story)
|
||||||
- doc-out: Output full document to current destination file
|
- doc-out: Output full document to current destination file
|
||||||
- validate-story-draft {story}: run the task validate-next-story against the provided story file
|
- validate-story-draft {story}: run the task validate-next-story against the provided story file
|
||||||
|
- initialize-memory-bank: Execute task initialize-memory-bank.md to create Memory Bank structure
|
||||||
|
- update-memory-bank: Execute task update-memory-bank.md to update project context
|
||||||
- yolo: Toggle Yolo Mode off on - on will skip doc section confirmations
|
- yolo: Toggle Yolo Mode off on - on will skip doc section confirmations
|
||||||
- exit: Exit (confirm)
|
- exit: Exit (confirm)
|
||||||
dependencies:
|
dependencies:
|
||||||
|
|
@ -68,6 +76,8 @@ dependencies:
|
||||||
- shard-doc.md
|
- shard-doc.md
|
||||||
- correct-course.md
|
- correct-course.md
|
||||||
- validate-next-story.md
|
- validate-next-story.md
|
||||||
|
- initialize-memory-bank.md
|
||||||
|
- update-memory-bank.md
|
||||||
templates:
|
templates:
|
||||||
- story-tmpl.yaml
|
- story-tmpl.yaml
|
||||||
checklists:
|
checklists:
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,139 @@
|
||||||
|
# Memory Bank Update Triggers
|
||||||
|
|
||||||
|
This reference guide identifies when Memory Bank updates should be performed to maintain AI session continuity.
|
||||||
|
|
||||||
|
## Automatic Triggers (Should Update)
|
||||||
|
|
||||||
|
### Development Activity Triggers
|
||||||
|
|
||||||
|
**Story Completion**
|
||||||
|
- When marking a story as "Ready for Review" or "Complete"
|
||||||
|
- Updates: `progress.md`, `activeContext.md`
|
||||||
|
- Focus: Features completed, current state
|
||||||
|
|
||||||
|
**ADR Creation**
|
||||||
|
- After creating a new Architectural Decision Record
|
||||||
|
- Updates: `systemPatterns.md`, `techContext.md` (if tech changes)
|
||||||
|
- Focus: Architecture decisions and their rationale
|
||||||
|
|
||||||
|
**Dev Journal Entry**
|
||||||
|
- After documenting a significant development session
|
||||||
|
- Updates: `activeContext.md`, `progress.md`
|
||||||
|
- Focus: Recent work, learnings, next steps
|
||||||
|
|
||||||
|
**Sprint/Iteration End**
|
||||||
|
- At the conclusion of each sprint or iteration
|
||||||
|
- Updates: Comprehensive update of all files
|
||||||
|
- Focus: Sprint achievements, velocity, upcoming work
|
||||||
|
|
||||||
|
### Technical Change Triggers
|
||||||
|
|
||||||
|
**Architecture Changes**
|
||||||
|
- Significant changes to system architecture
|
||||||
|
- Updates: `systemPatterns.md`, `activeContext.md`
|
||||||
|
- Focus: New patterns, component relationships
|
||||||
|
|
||||||
|
**Technology Stack Updates**
|
||||||
|
- Adding/removing frameworks, libraries, or tools
|
||||||
|
- Updates: `techContext.md`, `systemPatterns.md`
|
||||||
|
- Focus: Technology choices and constraints
|
||||||
|
|
||||||
|
**API Changes**
|
||||||
|
- Major API additions or modifications
|
||||||
|
- Updates: `systemPatterns.md`, `techContext.md`
|
||||||
|
- Focus: Integration points, API design
|
||||||
|
|
||||||
|
**Infrastructure Changes**
|
||||||
|
- Changes to deployment, hosting, or CI/CD
|
||||||
|
- Updates: `techContext.md`, `systemPatterns.md`
|
||||||
|
- Focus: Infrastructure architecture, deployment process
|
||||||
|
|
||||||
|
### Project Evolution Triggers
|
||||||
|
|
||||||
|
**Requirements Changes**
|
||||||
|
- Significant changes to project scope or goals
|
||||||
|
- Updates: `projectbrief.md`, `productContext.md`
|
||||||
|
- Focus: Updated requirements, success criteria
|
||||||
|
|
||||||
|
**Priority Shifts**
|
||||||
|
- Major reprioritization of features or work
|
||||||
|
- Updates: `activeContext.md`, `projectbrief.md`
|
||||||
|
- Focus: New priorities, adjusted timeline
|
||||||
|
|
||||||
|
**Milestone Achievement**
|
||||||
|
- Reaching major project milestones
|
||||||
|
- Updates: `progress.md`, `activeContext.md`
|
||||||
|
- Focus: Completed milestone, next phase
|
||||||
|
|
||||||
|
**Technical Debt Resolution**
|
||||||
|
- Completing significant refactoring or debt reduction
|
||||||
|
- Updates: `progress.md`, `systemPatterns.md`
|
||||||
|
- Focus: Improvements made, remaining debt
|
||||||
|
|
||||||
|
## Manual Triggers (User Requested)
|
||||||
|
|
||||||
|
### Explicit Request
|
||||||
|
- User says "update memory bank" or similar
|
||||||
|
- Updates: Comprehensive review and update of all files
|
||||||
|
- Focus: Current state across all dimensions
|
||||||
|
|
||||||
|
### Before Major Work
|
||||||
|
- Starting a new epic or major feature
|
||||||
|
- Updates: Ensure all files reflect current state
|
||||||
|
- Focus: Preparation for upcoming work
|
||||||
|
|
||||||
|
### Knowledge Transfer
|
||||||
|
- Onboarding new team members or AI agents
|
||||||
|
- Updates: Comprehensive update with extra clarity
|
||||||
|
- Focus: Complete project understanding
|
||||||
|
|
||||||
|
### Project Pivot
|
||||||
|
- Significant change in project direction
|
||||||
|
- Updates: All files, especially brief and context
|
||||||
|
- Focus: New direction, updated goals
|
||||||
|
|
||||||
|
## Update Strategies
|
||||||
|
|
||||||
|
### Selective Update
|
||||||
|
- Update only affected files
|
||||||
|
- Quick, focused changes
|
||||||
|
- Maintains consistency
|
||||||
|
|
||||||
|
### Comprehensive Update
|
||||||
|
- Review all Memory Bank files
|
||||||
|
- Ensure cross-file consistency
|
||||||
|
- Update based on all recent activities
|
||||||
|
|
||||||
|
### Progressive Update
|
||||||
|
- Update most volatile files frequently (activeContext, progress)
|
||||||
|
- Update stable files less often (projectbrief, productContext)
|
||||||
|
- Balance accuracy with efficiency
|
||||||
|
|
||||||
|
## Quality Indicators
|
||||||
|
|
||||||
|
Signs that Memory Bank needs updating:
|
||||||
|
- Last update >1 week ago
|
||||||
|
- Multiple dev journal entries since last update
|
||||||
|
- Significant commits without Memory Bank updates
|
||||||
|
- Architecture decisions not reflected
|
||||||
|
- Sprint completed without update
|
||||||
|
- AI agent confusion about project state
|
||||||
|
|
||||||
|
## Anti-Patterns to Avoid
|
||||||
|
|
||||||
|
- **Update Fatigue**: Don't update after every small change
|
||||||
|
- **Stale Documentation**: Don't let Memory Bank become outdated
|
||||||
|
- **Inconsistency**: Ensure updates maintain cross-file consistency
|
||||||
|
- **Information Overload**: Keep updates concise and relevant
|
||||||
|
- **Manual Only**: Set up automatic triggers for key events
|
||||||
|
|
||||||
|
## Integration Points
|
||||||
|
|
||||||
|
Memory Bank updates integrate with:
|
||||||
|
- **Dev Journal Creation**: Trigger activeContext update
|
||||||
|
- **ADR Creation**: Trigger systemPatterns update
|
||||||
|
- **Story Completion**: Trigger progress update
|
||||||
|
- **Sprint Planning**: Trigger comprehensive update
|
||||||
|
- **Architecture Changes**: Trigger patterns and tech updates
|
||||||
|
|
||||||
|
Remember: The Memory Bank is the AI's only link to project history after memory reset. Keep it accurate, current, and comprehensive.
|
||||||
|
|
@ -78,4 +78,12 @@ If this decision:
|
||||||
- [ ] Implementation steps defined
|
- [ ] Implementation steps defined
|
||||||
- [ ] Proper numbering and naming
|
- [ ] Proper numbering and naming
|
||||||
- [ ] Index updated
|
- [ ] Index updated
|
||||||
- [ ] Related ADRs linked
|
- [ ] Related ADRs linked
|
||||||
|
|
||||||
|
## Memory Bank Integration
|
||||||
|
|
||||||
|
After creating an ADR:
|
||||||
|
1. Update `docs/memory-bank/systemPatterns.md` with the architectural decision
|
||||||
|
2. If technology stack changed, update `docs/memory-bank/techContext.md`
|
||||||
|
3. Update `docs/memory-bank/activeContext.md` with the decision context
|
||||||
|
4. Consider running `update-memory-bank` task for comprehensive update
|
||||||
|
|
@ -228,4 +228,12 @@ After verification:
|
||||||
- **Multi-Stream Awareness**: Capture all work, not just primary
|
- **Multi-Stream Awareness**: Capture all work, not just primary
|
||||||
- **Future Developer Focus**: Context over implementation details
|
- **Future Developer Focus**: Context over implementation details
|
||||||
- **Comprehensive Coverage**: No significant work left undocumented
|
- **Comprehensive Coverage**: No significant work left undocumented
|
||||||
- **Quality Standards**: Clear, complete, conventional
|
- **Quality Standards**: Clear, complete, conventional
|
||||||
|
|
||||||
|
## Memory Bank Integration
|
||||||
|
|
||||||
|
Consider updating Memory Bank after significant commits:
|
||||||
|
- For feature additions: Update `progress.md` and `activeContext.md`
|
||||||
|
- For architectural changes: Update `systemPatterns.md`
|
||||||
|
- For tech stack changes: Update `techContext.md`
|
||||||
|
- Run `update-memory-bank` task if changes are substantial
|
||||||
|
|
@ -306,4 +306,13 @@ Verify before finalizing:
|
||||||
- **Reviewer Empathy**: Make review process efficient
|
- **Reviewer Empathy**: Make review process efficient
|
||||||
- **Visual Evidence**: Screenshots/GIFs for UI changes
|
- **Visual Evidence**: Screenshots/GIFs for UI changes
|
||||||
- **Reproducible Testing**: Clear, step-by-step instructions
|
- **Reproducible Testing**: Clear, step-by-step instructions
|
||||||
- **Future Reference**: Context for why decisions were made
|
- **Future Reference**: Context for why decisions were made
|
||||||
|
|
||||||
|
## Memory Bank Integration
|
||||||
|
|
||||||
|
After PR is merged:
|
||||||
|
- Major features: Update `progress.md` with completed features
|
||||||
|
- Architecture changes: Update `systemPatterns.md`
|
||||||
|
- Tech updates: Update `techContext.md`
|
||||||
|
- Breaking changes: Update relevant Memory Bank files
|
||||||
|
- Consider comprehensive `update-memory-bank` for significant PRs
|
||||||
|
|
@ -67,4 +67,14 @@ Before finalizing, ensure:
|
||||||
- Document both successes and challenges
|
- Document both successes and challenges
|
||||||
- Include enough detail for context without overwhelming
|
- Include enough detail for context without overwhelming
|
||||||
- Cross-reference related stories, ADRs, or PRs
|
- Cross-reference related stories, ADRs, or PRs
|
||||||
- Use British English for consistency
|
- Use British English for consistency
|
||||||
|
|
||||||
|
## Memory Bank Integration
|
||||||
|
|
||||||
|
After creating a dev journal entry:
|
||||||
|
1. Update `docs/memory-bank/activeContext.md` with current work and decisions
|
||||||
|
2. Update `docs/memory-bank/progress.md` with completed features and status
|
||||||
|
3. If patterns or insights discovered, update `docs/memory-bank/systemPatterns.md`
|
||||||
|
4. Consider running `update-memory-bank` task for comprehensive update
|
||||||
|
|
||||||
|
This ensures AI agents in future sessions have access to session context and learnings.
|
||||||
|
|
@ -332,10 +332,22 @@ Apply the advanced elicitation task after major sections to refine based on user
|
||||||
- Document enables AI agents to navigate and understand the actual codebase
|
- Document enables AI agents to navigate and understand the actual codebase
|
||||||
- Technical constraints and "gotchas" are clearly documented
|
- Technical constraints and "gotchas" are clearly documented
|
||||||
|
|
||||||
|
## Memory Bank Integration
|
||||||
|
|
||||||
|
After documenting a project:
|
||||||
|
1. Consider initializing Memory Bank if not exists (`initialize-memory-bank` task)
|
||||||
|
2. Use the brownfield architecture document to populate:
|
||||||
|
- `projectbrief.md` - Extract project goals and constraints
|
||||||
|
- `systemPatterns.md` - Document architecture and patterns
|
||||||
|
- `techContext.md` - Capture technology stack and environment
|
||||||
|
- `progress.md` - Note current state and technical debt
|
||||||
|
3. This provides AI agents with both detailed architecture docs and quick-reference Memory Bank
|
||||||
|
|
||||||
## Notes
|
## Notes
|
||||||
|
|
||||||
- This task creates ONE document that captures the TRUE state of the system
|
- This task creates ONE document that captures the TRUE state of the system
|
||||||
- References actual files rather than duplicating content when possible
|
- References actual files rather than duplicating content when possible
|
||||||
- Documents technical debt, workarounds, and constraints honestly
|
- Documents technical debt, workarounds, and constraints honestly
|
||||||
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
||||||
- The goal is PRACTICAL documentation for AI agents doing real work
|
- The goal is PRACTICAL documentation for AI agents doing real work
|
||||||
|
- Memory Bank provides quick context; architecture doc provides deep detail
|
||||||
|
|
@ -0,0 +1,165 @@
|
||||||
|
# Initialize Memory Bank
|
||||||
|
|
||||||
|
This task creates and initializes the Memory Bank structure for maintaining context across AI sessions. The Memory Bank ensures continuity and deep understanding of the project even when AI memory resets.
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
The Memory Bank serves as persistent memory for AI agents, containing:
|
||||||
|
- Project foundation and goals
|
||||||
|
- Current work context
|
||||||
|
- System architecture and patterns
|
||||||
|
- Technical decisions and constraints
|
||||||
|
- Progress tracking
|
||||||
|
|
||||||
|
## Initial Setup
|
||||||
|
|
||||||
|
### 1. Create Directory Structure
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p docs/memory-bank
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Determine Initialization Type
|
||||||
|
|
||||||
|
Ask the user:
|
||||||
|
- Is this a new project? → Create from scratch
|
||||||
|
- Is this an existing project? → Analyze and populate
|
||||||
|
- Do you have existing documentation? → Import and adapt
|
||||||
|
|
||||||
|
### 3. Create Core Memory Bank Files
|
||||||
|
|
||||||
|
The Memory Bank consists of 6 core files that build upon each other:
|
||||||
|
|
||||||
|
#### 3.1 Project Brief (`projectbrief.md`)
|
||||||
|
Foundation document - the source of truth for project scope:
|
||||||
|
- Core requirements and goals
|
||||||
|
- Project vision and objectives
|
||||||
|
- Success criteria
|
||||||
|
- Constraints and boundaries
|
||||||
|
|
||||||
|
#### 3.2 Product Context (`productContext.md`)
|
||||||
|
The "why" behind the project:
|
||||||
|
- Problems being solved
|
||||||
|
- User needs and pain points
|
||||||
|
- Expected outcomes
|
||||||
|
- User experience goals
|
||||||
|
|
||||||
|
#### 3.3 System Patterns (`systemPatterns.md`)
|
||||||
|
Technical architecture and decisions:
|
||||||
|
- System architecture overview
|
||||||
|
- Key design patterns
|
||||||
|
- Component relationships
|
||||||
|
- Integration points
|
||||||
|
- Critical implementation paths
|
||||||
|
|
||||||
|
#### 3.4 Tech Context (`techContext.md`)
|
||||||
|
Technology stack and environment:
|
||||||
|
- Languages and frameworks
|
||||||
|
- Development tools
|
||||||
|
- Dependencies and versions
|
||||||
|
- Technical constraints
|
||||||
|
- Build and deployment
|
||||||
|
|
||||||
|
#### 3.5 Active Context (`activeContext.md`)
|
||||||
|
Current work focus:
|
||||||
|
- Active work items
|
||||||
|
- Recent changes
|
||||||
|
- Current decisions
|
||||||
|
- Next priorities
|
||||||
|
- Open questions
|
||||||
|
|
||||||
|
#### 3.6 Progress (`progress.md`)
|
||||||
|
Project state tracking:
|
||||||
|
- Completed features
|
||||||
|
- Work in progress
|
||||||
|
- Known issues
|
||||||
|
- Technical debt
|
||||||
|
- Evolution of decisions
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
### For New Projects
|
||||||
|
|
||||||
|
1. **Gather Project Information**
|
||||||
|
- Interview user about project goals
|
||||||
|
- Understand target users
|
||||||
|
- Define success criteria
|
||||||
|
- Identify constraints
|
||||||
|
|
||||||
|
2. **Create Initial Files**
|
||||||
|
- Start with projectbrief.md
|
||||||
|
- Populate product context
|
||||||
|
- Define initial architecture
|
||||||
|
- Document tech stack
|
||||||
|
- Set initial active context
|
||||||
|
- Initialize progress tracking
|
||||||
|
|
||||||
|
### For Existing Projects
|
||||||
|
|
||||||
|
1. **Analyze Current State**
|
||||||
|
```bash
|
||||||
|
# Review existing documentation
|
||||||
|
- README files
|
||||||
|
- Architecture docs
|
||||||
|
- ADRs
|
||||||
|
- Dev journals
|
||||||
|
- Changelogs
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Extract Key Information**
|
||||||
|
- Project purpose and goals
|
||||||
|
- Current architecture
|
||||||
|
- Technology decisions
|
||||||
|
- Recent work
|
||||||
|
- Known issues
|
||||||
|
|
||||||
|
3. **Populate Memory Bank**
|
||||||
|
- Synthesize findings into 6 core files
|
||||||
|
- Maintain accuracy to reality
|
||||||
|
- Document technical debt
|
||||||
|
- Capture current priorities
|
||||||
|
|
||||||
|
### 4. Validation
|
||||||
|
|
||||||
|
After creating initial files:
|
||||||
|
1. Review with user for accuracy
|
||||||
|
2. Ensure consistency across files
|
||||||
|
3. Verify no critical information missing
|
||||||
|
4. Confirm next steps are clear
|
||||||
|
|
||||||
|
## Templates
|
||||||
|
|
||||||
|
Use the memory bank templates from `bmad-core/templates/memory-bank/`:
|
||||||
|
- `projectbrief-tmpl.md`
|
||||||
|
- `productContext-tmpl.md`
|
||||||
|
- `systemPatterns-tmpl.md`
|
||||||
|
- `techContext-tmpl.md`
|
||||||
|
- `activeContext-tmpl.md`
|
||||||
|
- `progress-tmpl.md`
|
||||||
|
|
||||||
|
## Integration Points
|
||||||
|
|
||||||
|
The Memory Bank integrates with:
|
||||||
|
- **Session Start**: Agents read memory bank first
|
||||||
|
- **Dev Journals**: Update activeContext and progress
|
||||||
|
- **ADRs**: Update systemPatterns with decisions
|
||||||
|
- **Story Completion**: Update progress and activeContext
|
||||||
|
- **Architecture Changes**: Update systemPatterns
|
||||||
|
|
||||||
|
## Quality Checklist
|
||||||
|
|
||||||
|
- [ ] All 6 core files created
|
||||||
|
- [ ] Information is accurate and current
|
||||||
|
- [ ] Files follow hierarchical structure
|
||||||
|
- [ ] No contradictions between files
|
||||||
|
- [ ] Next steps clearly defined
|
||||||
|
- [ ] Technical decisions documented
|
||||||
|
- [ ] Progress accurately reflected
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Memory Bank is the foundation for AI continuity
|
||||||
|
- Must be updated regularly to maintain value
|
||||||
|
- All agents should read before starting work
|
||||||
|
- Updates should be comprehensive but concise
|
||||||
|
- British English for consistency
|
||||||
|
|
@ -0,0 +1,194 @@
|
||||||
|
# Update Memory Bank
|
||||||
|
|
||||||
|
This task updates the Memory Bank documentation based on recent project activities. The Memory Bank ensures AI agents maintain context across sessions by preserving project knowledge in structured files.
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Update the Memory Bank to reflect:
|
||||||
|
- Recent development activities and decisions
|
||||||
|
- Architectural changes and patterns
|
||||||
|
- Technical context updates
|
||||||
|
- Progress and current work state
|
||||||
|
- Lessons learned and insights
|
||||||
|
|
||||||
|
## Data Sources
|
||||||
|
|
||||||
|
The update draws from multiple sources:
|
||||||
|
- **Dev Journal Entries**: Daily development narratives in `docs/devJournal/`
|
||||||
|
- **CHANGELOG.md**: Recent changes and version history
|
||||||
|
- **README Files**: Project documentation updates
|
||||||
|
- **ADRs**: Architectural Decision Records in `docs/adr/`
|
||||||
|
- **Source Code**: Actual implementation changes
|
||||||
|
- **Test Results**: Quality and coverage updates
|
||||||
|
|
||||||
|
## Update Process
|
||||||
|
|
||||||
|
### 1. Gather Recent Changes
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Review dev journals from recent sessions
|
||||||
|
ls -la docs/devJournal/*.md | tail -5
|
||||||
|
|
||||||
|
# Check recent ADRs
|
||||||
|
ls -la docs/adr/*.md | tail -5
|
||||||
|
|
||||||
|
# Review CHANGELOG
|
||||||
|
head -50 CHANGELOG.md
|
||||||
|
|
||||||
|
# Check README updates
|
||||||
|
find . -name "README*.md" -mtime -7
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Analyze Impact
|
||||||
|
|
||||||
|
For each source, identify:
|
||||||
|
- What changed and why
|
||||||
|
- Impact on system architecture
|
||||||
|
- New patterns or conventions
|
||||||
|
- Technical decisions made
|
||||||
|
- Open questions resolved
|
||||||
|
- New dependencies or constraints
|
||||||
|
|
||||||
|
### 3. Update Memory Bank Files
|
||||||
|
|
||||||
|
Update relevant files based on changes:
|
||||||
|
|
||||||
|
#### 3.1 Project Brief (`projectbrief.md`)
|
||||||
|
Update if:
|
||||||
|
- Core requirements changed
|
||||||
|
- Project goals refined
|
||||||
|
- Success criteria modified
|
||||||
|
- New constraints identified
|
||||||
|
|
||||||
|
#### 3.2 Product Context (`productContext.md`)
|
||||||
|
Update if:
|
||||||
|
- User needs clarified
|
||||||
|
- Problem understanding evolved
|
||||||
|
- Expected outcomes changed
|
||||||
|
- UX goals modified
|
||||||
|
|
||||||
|
#### 3.3 System Patterns (`systemPatterns.md`)
|
||||||
|
Update if:
|
||||||
|
- Architecture decisions made (check ADRs)
|
||||||
|
- New design patterns adopted
|
||||||
|
- Component relationships changed
|
||||||
|
- Integration points modified
|
||||||
|
- Critical paths identified
|
||||||
|
|
||||||
|
#### 3.4 Tech Context (`techContext.md`)
|
||||||
|
Update if:
|
||||||
|
- Dependencies added/updated
|
||||||
|
- Tools or frameworks changed
|
||||||
|
- Build process modified
|
||||||
|
- Technical constraints discovered
|
||||||
|
- Environment changes
|
||||||
|
|
||||||
|
#### 3.5 Active Context (`activeContext.md`)
|
||||||
|
ALWAYS update with:
|
||||||
|
- Current work items
|
||||||
|
- Recent completions
|
||||||
|
- Active decisions
|
||||||
|
- Next priorities
|
||||||
|
- Open questions
|
||||||
|
- Important patterns discovered
|
||||||
|
- Learnings from dev journals
|
||||||
|
|
||||||
|
#### 3.6 Progress (`progress.md`)
|
||||||
|
Update with:
|
||||||
|
- Features completed
|
||||||
|
- Work in progress status
|
||||||
|
- Issues discovered/resolved
|
||||||
|
- Technical debt changes
|
||||||
|
- Decision evolution
|
||||||
|
|
||||||
|
### 4. Validation
|
||||||
|
|
||||||
|
After updates:
|
||||||
|
1. **Cross-Reference Check**: Ensure consistency across all files
|
||||||
|
2. **Accuracy Verification**: Confirm updates match source material
|
||||||
|
3. **Completeness Review**: No critical information omitted
|
||||||
|
4. **Clarity Assessment**: Clear for future AI sessions
|
||||||
|
|
||||||
|
### 5. Update Guidelines
|
||||||
|
|
||||||
|
- **Be Concise**: Capture essence without excessive detail
|
||||||
|
- **Be Comprehensive**: Include all significant changes
|
||||||
|
- **Be Accurate**: Reflect actual state, not aspirations
|
||||||
|
- **Maintain Consistency**: Align with existing memory bank content
|
||||||
|
- **Use British English**: For consistency across documentation
|
||||||
|
|
||||||
|
## Selective vs Comprehensive Updates
|
||||||
|
|
||||||
|
### Selective Update
|
||||||
|
Triggered by specific events:
|
||||||
|
- Story completion → Update progress and activeContext
|
||||||
|
- ADR creation → Update systemPatterns
|
||||||
|
- Major decision → Update relevant sections
|
||||||
|
- Architecture change → Update systemPatterns and techContext
|
||||||
|
|
||||||
|
### Comprehensive Update
|
||||||
|
Triggered by:
|
||||||
|
- End of sprint/iteration
|
||||||
|
- Major milestone reached
|
||||||
|
- Explicit user request
|
||||||
|
- Significant project pivot
|
||||||
|
- Before major feature work
|
||||||
|
|
||||||
|
## Quality Checklist
|
||||||
|
|
||||||
|
- [ ] All recent dev journals reviewed
|
||||||
|
- [ ] ADRs incorporated into systemPatterns
|
||||||
|
- [ ] CHANGELOG reflected in progress
|
||||||
|
- [ ] Active work items current
|
||||||
|
- [ ] Technical decisions documented
|
||||||
|
- [ ] No contradictions between files
|
||||||
|
- [ ] Next steps clearly defined
|
||||||
|
- [ ] British English used throughout
|
||||||
|
|
||||||
|
## Integration Points
|
||||||
|
|
||||||
|
This task integrates with:
|
||||||
|
- **Dev Journal Creation**: Triggers selective activeContext update
|
||||||
|
- **ADR Creation**: Triggers systemPatterns update
|
||||||
|
- **Story Completion**: Triggers progress update
|
||||||
|
- **Sprint End**: Triggers comprehensive update
|
||||||
|
- **Architecture Changes**: Triggers multiple file updates
|
||||||
|
|
||||||
|
## Example Update Flow
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
Start[Gather Sources] --> Analyze[Analyze Changes]
|
||||||
|
Analyze --> Categorize[Categorize by Impact]
|
||||||
|
|
||||||
|
Categorize --> Brief{Project Brief?}
|
||||||
|
Categorize --> Product{Product Context?}
|
||||||
|
Categorize --> System{System Patterns?}
|
||||||
|
Categorize --> Tech{Tech Context?}
|
||||||
|
Categorize --> Active[Active Context]
|
||||||
|
Categorize --> Progress[Progress]
|
||||||
|
|
||||||
|
Brief -->|If changed| UpdateBrief[Update projectbrief.md]
|
||||||
|
Product -->|If changed| UpdateProduct[Update productContext.md]
|
||||||
|
System -->|If changed| UpdateSystem[Update systemPatterns.md]
|
||||||
|
Tech -->|If changed| UpdateTech[Update techContext.md]
|
||||||
|
Active --> UpdateActive[Update activeContext.md]
|
||||||
|
Progress --> UpdateProgress[Update progress.md]
|
||||||
|
|
||||||
|
UpdateBrief --> Validate
|
||||||
|
UpdateProduct --> Validate
|
||||||
|
UpdateSystem --> Validate
|
||||||
|
UpdateTech --> Validate
|
||||||
|
UpdateActive --> Validate
|
||||||
|
UpdateProgress --> Validate
|
||||||
|
|
||||||
|
Validate[Validate Consistency] --> Complete[Update Complete]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Memory Bank is critical for AI session continuity
|
||||||
|
- Updates should capture reality, not ideals
|
||||||
|
- Focus on information that helps future sessions
|
||||||
|
- Balance detail with conciseness
|
||||||
|
- Remember: This is the AI's only link to past work after memory reset
|
||||||
|
|
@ -0,0 +1,159 @@
|
||||||
|
# Active Context
|
||||||
|
|
||||||
|
*Current work focus, recent changes, and immediate priorities*
|
||||||
|
|
||||||
|
## Current Sprint/Iteration
|
||||||
|
|
||||||
|
**Sprint**: [Name/Number]
|
||||||
|
**Duration**: [Start Date] - [End Date]
|
||||||
|
**Theme**: [Main focus of this sprint]
|
||||||
|
**Status**: [On Track/At Risk/Blocked]
|
||||||
|
|
||||||
|
## Active Work Items
|
||||||
|
|
||||||
|
### In Progress
|
||||||
|
| Item | Type | Assignee | Status | Notes |
|
||||||
|
|------|------|----------|--------|-------|
|
||||||
|
| [ID: Title] | Story/Bug/Task | [Who] | [% complete] | [Current state] |
|
||||||
|
| [ID: Title] | Story/Bug/Task | [Who] | [% complete] | [Blockers] |
|
||||||
|
|
||||||
|
### Up Next (Priority Order)
|
||||||
|
1. **[ID: Title]** - [Brief description]
|
||||||
|
- Dependencies: [What needs to complete first]
|
||||||
|
- Estimate: [Size/effort]
|
||||||
|
|
||||||
|
2. **[ID: Title]** - [Brief description]
|
||||||
|
- Ready to start: [Yes/No - why]
|
||||||
|
|
||||||
|
### Recently Completed
|
||||||
|
| Item | Completed | Key Changes |
|
||||||
|
|------|-----------|-------------|
|
||||||
|
| [ID: Title] | [Date] | [What was done] |
|
||||||
|
| [ID: Title] | [Date] | [Impact/changes] |
|
||||||
|
|
||||||
|
## Recent Decisions
|
||||||
|
|
||||||
|
### Decision 1: [Title]
|
||||||
|
- **Date**: [When decided]
|
||||||
|
- **Context**: [Why needed]
|
||||||
|
- **Choice**: [What was decided]
|
||||||
|
- **Impact**: [What changes]
|
||||||
|
- **ADR**: [Link if documented]
|
||||||
|
|
||||||
|
### Decision 2: [Title]
|
||||||
|
- **Date**: [When decided]
|
||||||
|
- **Choice**: [What was decided]
|
||||||
|
- **Rationale**: [Key reasoning]
|
||||||
|
|
||||||
|
## Current Technical Focus
|
||||||
|
|
||||||
|
### Active Development Areas
|
||||||
|
- **Module/Component**: [What's being worked on]
|
||||||
|
- Changes: [What's changing]
|
||||||
|
- Approach: [How we're doing it]
|
||||||
|
- Progress: [Current state]
|
||||||
|
|
||||||
|
### Refactoring/Tech Debt
|
||||||
|
- **Area**: [What's being improved]
|
||||||
|
- Reason: [Why now]
|
||||||
|
- Scope: [What's included]
|
||||||
|
- Status: [Progress]
|
||||||
|
|
||||||
|
## Important Patterns & Preferences
|
||||||
|
|
||||||
|
### Coding Patterns
|
||||||
|
- **Pattern 1**: [Description]
|
||||||
|
- Example: [Where to see it]
|
||||||
|
- When to use: [Guidance]
|
||||||
|
|
||||||
|
- **Pattern 2**: [Description]
|
||||||
|
- Rationale: [Why this way]
|
||||||
|
|
||||||
|
### Team Preferences
|
||||||
|
- **Code Style**: [Key preferences beyond standards]
|
||||||
|
- **PR Process**: [How we handle reviews]
|
||||||
|
- **Communication**: [How we coordinate]
|
||||||
|
- **Documentation**: [What we document when]
|
||||||
|
|
||||||
|
## Recent Learnings & Insights
|
||||||
|
|
||||||
|
### Technical Discoveries
|
||||||
|
1. **Learning**: [What we learned]
|
||||||
|
- Context: [How we discovered it]
|
||||||
|
- Application: [How it affects our approach]
|
||||||
|
|
||||||
|
2. **Insight**: [What we realized]
|
||||||
|
- Impact: [What changes as a result]
|
||||||
|
|
||||||
|
### Process Improvements
|
||||||
|
- **What Changed**: [Process adjustment]
|
||||||
|
- **Why**: [Problem it solves]
|
||||||
|
- **Result**: [Impact so far]
|
||||||
|
|
||||||
|
## Open Questions & Investigations
|
||||||
|
|
||||||
|
### Technical Questions
|
||||||
|
1. **Question**: [What we need to figure out]
|
||||||
|
- Context: [Why it matters]
|
||||||
|
- Options: [Possible approaches]
|
||||||
|
- Timeline: [When we need answers]
|
||||||
|
|
||||||
|
2. **Investigation**: [What we're researching]
|
||||||
|
- Purpose: [Why we're looking into it]
|
||||||
|
- Progress: [What we've found so far]
|
||||||
|
|
||||||
|
### Product Questions
|
||||||
|
- **Clarification Needed**: [What's unclear]
|
||||||
|
- Impact: [What's blocked]
|
||||||
|
- Who to ask: [Stakeholder]
|
||||||
|
|
||||||
|
## Blockers & Risks
|
||||||
|
|
||||||
|
### Current Blockers
|
||||||
|
| Blocker | Impact | Owner | ETA |
|
||||||
|
|---------|--------|-------|-----|
|
||||||
|
| [Description] | [What can't proceed] | [Who's resolving] | [Expected resolution] |
|
||||||
|
|
||||||
|
### Active Risks
|
||||||
|
| Risk | Probability | Impact | Mitigation |
|
||||||
|
|------|-------------|--------|------------|
|
||||||
|
| [Description] | High/Med/Low | High/Med/Low | [What we're doing] |
|
||||||
|
|
||||||
|
## Environment & Tool Updates
|
||||||
|
|
||||||
|
### Recent Changes
|
||||||
|
- **Tool/Version Update**: [What changed]
|
||||||
|
- Date: [When]
|
||||||
|
- Impact: [How it affects development]
|
||||||
|
- Action: [What developers need to do]
|
||||||
|
|
||||||
|
### Pending Updates
|
||||||
|
- **Planned Change**: [What will change]
|
||||||
|
- Timeline: [When]
|
||||||
|
- Preparation: [What to do beforehand]
|
||||||
|
|
||||||
|
## Next Session Priorities
|
||||||
|
|
||||||
|
### Immediate Next Steps
|
||||||
|
1. [Specific task to tackle first]
|
||||||
|
2. [Second priority if first is blocked]
|
||||||
|
3. [Third priority or investigation]
|
||||||
|
|
||||||
|
### Context for Next Session
|
||||||
|
- **Where we left off**: [Current state]
|
||||||
|
- **Key files**: [Important files to review]
|
||||||
|
- **Gotchas**: [Things to remember]
|
||||||
|
- **Dependencies**: [What to check first]
|
||||||
|
|
||||||
|
## Communication Log
|
||||||
|
|
||||||
|
### Recent Important Messages
|
||||||
|
- **Date**: [Message summary or decision]
|
||||||
|
- **Date**: [Key communication]
|
||||||
|
|
||||||
|
### Pending Communications
|
||||||
|
- **Need to inform**: [Who about what]
|
||||||
|
- **Awaiting response**: [What we're waiting for]
|
||||||
|
|
||||||
|
---
|
||||||
|
*This document is the most frequently updated. It represents the current state and immediate context needed to continue work effectively.*
|
||||||
|
|
@ -0,0 +1,121 @@
|
||||||
|
# Product Context
|
||||||
|
|
||||||
|
*The "why" behind the project - problems, solutions, and user experience*
|
||||||
|
|
||||||
|
## Problem Statement
|
||||||
|
|
||||||
|
### Core Problem
|
||||||
|
[Clear description of the main problem this project solves]
|
||||||
|
|
||||||
|
### Current State
|
||||||
|
- **How it's done today**: [Current approach/workarounds]
|
||||||
|
- **Pain points**: [Specific issues users face]
|
||||||
|
- **Impact**: [Cost/consequences of not solving]
|
||||||
|
|
||||||
|
### Root Causes
|
||||||
|
1. [Underlying cause 1]
|
||||||
|
2. [Underlying cause 2]
|
||||||
|
3. [Underlying cause 3]
|
||||||
|
|
||||||
|
## Solution Approach
|
||||||
|
|
||||||
|
### Our Solution
|
||||||
|
[High-level description of how we're solving the problem]
|
||||||
|
|
||||||
|
### Why This Approach
|
||||||
|
- [Reason 1 - why this solution fits]
|
||||||
|
- [Reason 2 - advantages over alternatives]
|
||||||
|
- [Reason 3 - alignment with constraints]
|
||||||
|
|
||||||
|
### Key Innovations
|
||||||
|
- [What's new/different about our approach]
|
||||||
|
- [Unique value propositions]
|
||||||
|
|
||||||
|
## User Experience Vision
|
||||||
|
|
||||||
|
### User Journey
|
||||||
|
1. **Discovery**: [How users find/access the solution]
|
||||||
|
2. **Onboarding**: [Initial user experience]
|
||||||
|
3. **Core Usage**: [Primary interaction patterns]
|
||||||
|
4. **Value Realization**: [When/how users see benefits]
|
||||||
|
|
||||||
|
### Design Principles
|
||||||
|
- **Principle 1**: [Description and rationale]
|
||||||
|
- **Principle 2**: [Description and rationale]
|
||||||
|
- **Principle 3**: [Description and rationale]
|
||||||
|
|
||||||
|
### Success Metrics
|
||||||
|
- **User Satisfaction**: [How measured]
|
||||||
|
- **Adoption Rate**: [Target metrics]
|
||||||
|
- **Task Completion**: [Efficiency gains]
|
||||||
|
|
||||||
|
## Expected Outcomes
|
||||||
|
|
||||||
|
### Short-term (3 months)
|
||||||
|
- [Immediate benefit 1]
|
||||||
|
- [Immediate benefit 2]
|
||||||
|
- [Quick win]
|
||||||
|
|
||||||
|
### Medium-term (6-12 months)
|
||||||
|
- [Broader impact 1]
|
||||||
|
- [Broader impact 2]
|
||||||
|
- [Growth indicator]
|
||||||
|
|
||||||
|
### Long-term (1+ years)
|
||||||
|
- [Strategic outcome 1]
|
||||||
|
- [Strategic outcome 2]
|
||||||
|
- [Market position]
|
||||||
|
|
||||||
|
## User Personas
|
||||||
|
|
||||||
|
### Primary Persona: [Name]
|
||||||
|
- **Role**: [Job title/function]
|
||||||
|
- **Goals**: [What they want to achieve]
|
||||||
|
- **Frustrations**: [Current pain points]
|
||||||
|
- **Needs**: [What would help them succeed]
|
||||||
|
- **Technical Level**: [Expertise level]
|
||||||
|
|
||||||
|
### Secondary Persona: [Name]
|
||||||
|
- **Role**: [Job title/function]
|
||||||
|
- **Goals**: [What they want to achieve]
|
||||||
|
- **Needs**: [What would help them succeed]
|
||||||
|
|
||||||
|
## Competitive Landscape
|
||||||
|
|
||||||
|
### Existing Solutions
|
||||||
|
| Solution | Strengths | Weaknesses | Our Differentiation |
|
||||||
|
|----------|-----------|------------|-------------------|
|
||||||
|
| [Name] | [What they do well] | [Gaps] | [How we're better] |
|
||||||
|
| [Name] | [What they do well] | [Gaps] | [How we're better] |
|
||||||
|
|
||||||
|
### Market Opportunity
|
||||||
|
[Why now is the right time for this solution]
|
||||||
|
|
||||||
|
## Assumptions and Risks
|
||||||
|
|
||||||
|
### Key Assumptions
|
||||||
|
1. [Assumption about users/market]
|
||||||
|
2. [Assumption about technology]
|
||||||
|
3. [Assumption about adoption]
|
||||||
|
|
||||||
|
### Validation Plans
|
||||||
|
- [How we'll test assumption 1]
|
||||||
|
- [How we'll test assumption 2]
|
||||||
|
- [How we'll test assumption 3]
|
||||||
|
|
||||||
|
## Integration with Ecosystem
|
||||||
|
|
||||||
|
### Upstream Dependencies
|
||||||
|
- [Systems/processes that feed into ours]
|
||||||
|
- [Data sources required]
|
||||||
|
|
||||||
|
### Downstream Impact
|
||||||
|
- [Systems/processes affected by our solution]
|
||||||
|
- [Expected changes in workflows]
|
||||||
|
|
||||||
|
### Partner Integrations
|
||||||
|
- [Third-party services/APIs]
|
||||||
|
- [Collaboration requirements]
|
||||||
|
|
||||||
|
---
|
||||||
|
*This document explains why the project exists and what success looks like from a user perspective.*
|
||||||
|
|
@ -0,0 +1,167 @@
|
||||||
|
# Progress
|
||||||
|
|
||||||
|
*Project state tracking - what's done, what's in progress, known issues, and evolution*
|
||||||
|
|
||||||
|
## Project Status Overview
|
||||||
|
|
||||||
|
**Overall Completion**: [X%]
|
||||||
|
**Phase**: [Current phase name]
|
||||||
|
**Health**: [Green/Yellow/Red]
|
||||||
|
**Last Updated**: [Date]
|
||||||
|
|
||||||
|
## Feature Completion Status
|
||||||
|
|
||||||
|
### Completed Features
|
||||||
|
| Feature | Version | Completed | Key Capabilities |
|
||||||
|
|---------|---------|-----------|------------------|
|
||||||
|
| [Feature Name] | v1.0 | [Date] | [What it does] |
|
||||||
|
| [Feature Name] | v1.0 | [Date] | [Core functionality] |
|
||||||
|
| [Feature Name] | v2.0 | [Date] | [Enhanced capabilities] |
|
||||||
|
|
||||||
|
### In Progress Features
|
||||||
|
| Feature | Progress | Target | Status | Notes |
|
||||||
|
|---------|----------|--------|--------|--------|
|
||||||
|
| [Feature Name] | 75% | [Date] | On Track | [Current focus] |
|
||||||
|
| [Feature Name] | 40% | [Date] | At Risk | [Blocker/issue] |
|
||||||
|
| [Feature Name] | 10% | [Date] | Planning | [Next steps] |
|
||||||
|
|
||||||
|
### Upcoming Features
|
||||||
|
| Feature | Priority | Planned Start | Dependencies |
|
||||||
|
|---------|----------|---------------|--------------|
|
||||||
|
| [Feature Name] | High | [Date] | [What must complete first] |
|
||||||
|
| [Feature Name] | Medium | [Quarter] | [Prerequisites] |
|
||||||
|
| [Feature Name] | Low | [TBD] | [Considerations] |
|
||||||
|
|
||||||
|
## Sprint/Iteration History
|
||||||
|
|
||||||
|
### Recent Sprints
|
||||||
|
| Sprint | Duration | Completed | Velocity | Key Achievements |
|
||||||
|
|--------|----------|-----------|----------|------------------|
|
||||||
|
| [Sprint N] | [Dates] | 8/10 stories | 34 pts | [Major accomplishments] |
|
||||||
|
| [Sprint N-1] | [Dates] | 10/10 stories | 42 pts | [What was delivered] |
|
||||||
|
| [Sprint N-2] | [Dates] | 7/8 stories | 28 pts | [Highlights] |
|
||||||
|
|
||||||
|
### Velocity Trend
|
||||||
|
- **Average Velocity**: [X points/sprint]
|
||||||
|
- **Trend**: [Increasing/Stable/Decreasing]
|
||||||
|
- **Factors**: [What's affecting velocity]
|
||||||
|
|
||||||
|
## Quality Metrics
|
||||||
|
|
||||||
|
### Test Coverage
|
||||||
|
| Type | Coverage | Target | Status |
|
||||||
|
|------|----------|--------|--------|
|
||||||
|
| Unit Tests | [X%] | 80% | [Met/Below] |
|
||||||
|
| Integration | [X%] | 70% | [Status] |
|
||||||
|
| E2E | [X%] | 60% | [Status] |
|
||||||
|
|
||||||
|
### Code Quality
|
||||||
|
- **Technical Debt**: [High/Medium/Low]
|
||||||
|
- **Code Coverage**: [X%]
|
||||||
|
- **Complexity**: [Metrics]
|
||||||
|
- **Standards Compliance**: [Status]
|
||||||
|
|
||||||
|
## Known Issues & Bugs
|
||||||
|
|
||||||
|
### Critical Issues
|
||||||
|
| Issue | Impact | Workaround | Fix ETA |
|
||||||
|
|-------|--------|------------|---------|
|
||||||
|
| [Description] | [User impact] | [Temporary solution] | [Date/Sprint] |
|
||||||
|
|
||||||
|
### Major Issues
|
||||||
|
| Issue | Component | Status | Assigned |
|
||||||
|
|-------|-----------|--------|----------|
|
||||||
|
| [Bug description] | [Module] | In Progress | [Developer] |
|
||||||
|
| [Bug description] | [Module] | Backlog | [Unassigned] |
|
||||||
|
|
||||||
|
### Technical Debt Registry
|
||||||
|
| Debt Item | Impact | Effort | Priority | Plan |
|
||||||
|
|-----------|--------|--------|----------|------|
|
||||||
|
| [Legacy code area] | High | Large | P1 | [Refactor in Q2] |
|
||||||
|
| [Outdated library] | Medium | Medium | P2 | [Update next sprint] |
|
||||||
|
| [Code duplication] | Low | Small | P3 | [As time permits] |
|
||||||
|
|
||||||
|
## Evolution of Key Decisions
|
||||||
|
|
||||||
|
### Architecture Evolution
|
||||||
|
| Version | Change | Rationale | Impact |
|
||||||
|
|---------|--------|-----------|---------|
|
||||||
|
| v1.0 | Monolithic | Speed to market | Simple deployment |
|
||||||
|
| v2.0 | Modular monolith | Maintainability | Better separation |
|
||||||
|
| v3.0 | [Planned] Services | Scalability | Independent scaling |
|
||||||
|
|
||||||
|
### Technology Changes
|
||||||
|
| Date | From | To | Reason | Status |
|
||||||
|
|------|------|-----|--------|--------|
|
||||||
|
| [Date] | [Old tech] | [New tech] | [Why changed] | Complete |
|
||||||
|
| [Date] | [Old version] | [New version] | [Security/features] | In Progress |
|
||||||
|
|
||||||
|
### Process Evolution
|
||||||
|
| Change | When | Why | Result |
|
||||||
|
|--------|------|-----|--------|
|
||||||
|
| [Process change] | [Date] | [Problem solved] | [Improvement] |
|
||||||
|
| [New practice] | [Date] | [Need addressed] | [Impact] |
|
||||||
|
|
||||||
|
## Release History
|
||||||
|
|
||||||
|
### Recent Releases
|
||||||
|
| Version | Date | Major Changes | Breaking Changes |
|
||||||
|
|---------|------|---------------|------------------|
|
||||||
|
| v2.3.0 | [Date] | [Feature list] | None |
|
||||||
|
| v2.2.0 | [Date] | [Features/fixes] | [API change] |
|
||||||
|
| v2.1.0 | [Date] | [What shipped] | None |
|
||||||
|
|
||||||
|
### Upcoming Releases
|
||||||
|
| Version | Target Date | Planned Features | Risks |
|
||||||
|
|---------|-------------|------------------|--------|
|
||||||
|
| v2.4.0 | [Date] | [What's planned] | [Dependencies] |
|
||||||
|
| v3.0.0 | [Quarter] | [Major changes] | [Migration needs] |
|
||||||
|
|
||||||
|
## Performance Trends
|
||||||
|
|
||||||
|
### System Performance
|
||||||
|
| Metric | Current | Target | Trend | Notes |
|
||||||
|
|--------|---------|--------|--------|-------|
|
||||||
|
| Response Time | [Xms] | <200ms | ↓ Improving | [Recent optimizations] |
|
||||||
|
| Throughput | [X rps] | >1000 rps | → Stable | [At capacity] |
|
||||||
|
| Error Rate | [X%] | <0.1% | ↓ Improving | [Recent fixes] |
|
||||||
|
|
||||||
|
### User Metrics
|
||||||
|
| Metric | Current | Last Month | Trend |
|
||||||
|
|--------|---------|------------|--------|
|
||||||
|
| Active Users | [Number] | [Number] | ↑ [X%] |
|
||||||
|
| Feature Adoption | [X%] | [X%] | ↑ Growing |
|
||||||
|
| User Satisfaction | [Score] | [Score] | → Stable |
|
||||||
|
|
||||||
|
## Lessons Learned
|
||||||
|
|
||||||
|
### What's Working Well
|
||||||
|
1. **Practice/Decision**: [What we did]
|
||||||
|
- Result: [Positive outcome]
|
||||||
|
- Continue: [Why we'll keep doing it]
|
||||||
|
|
||||||
|
2. **Technology Choice**: [What we chose]
|
||||||
|
- Benefit: [How it helps]
|
||||||
|
|
||||||
|
### What Needs Improvement
|
||||||
|
1. **Challenge**: [What's not working]
|
||||||
|
- Impact: [Problems it causes]
|
||||||
|
- Plan: [How we'll address it]
|
||||||
|
|
||||||
|
2. **Process Gap**: [What's missing]
|
||||||
|
- Next Step: [Improvement plan]
|
||||||
|
|
||||||
|
## Risk Register
|
||||||
|
|
||||||
|
### Mitigated Risks
|
||||||
|
| Risk | Mitigation | Result |
|
||||||
|
|------|------------|--------|
|
||||||
|
| [Past risk] | [What we did] | [Outcome] |
|
||||||
|
|
||||||
|
### Active Risks
|
||||||
|
| Risk | Probability | Impact | Mitigation Plan |
|
||||||
|
|------|-------------|--------|-----------------|
|
||||||
|
| [Current risk] | High/Med/Low | High/Med/Low | [Plan to address] |
|
||||||
|
|
||||||
|
---
|
||||||
|
*This document tracks project progress and evolution. It provides historical context and current status for planning and decision-making.*
|
||||||
|
|
@ -0,0 +1,108 @@
|
||||||
|
# Project Brief
|
||||||
|
|
||||||
|
*Foundation document - the source of truth for project scope*
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
**Project Name**: [Project Name]
|
||||||
|
**Version**: 1.0
|
||||||
|
**Last Updated**: [Date]
|
||||||
|
**Status**: [Active/Planning/On Hold]
|
||||||
|
|
||||||
|
## Core Purpose
|
||||||
|
|
||||||
|
[One paragraph describing what this project is and why it exists]
|
||||||
|
|
||||||
|
## Goals and Objectives
|
||||||
|
|
||||||
|
### Primary Goals
|
||||||
|
1. [Main goal 1]
|
||||||
|
2. [Main goal 2]
|
||||||
|
3. [Main goal 3]
|
||||||
|
|
||||||
|
### Success Criteria
|
||||||
|
- [ ] [Measurable criterion 1]
|
||||||
|
- [ ] [Measurable criterion 2]
|
||||||
|
- [ ] [Measurable criterion 3]
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
### In Scope
|
||||||
|
- [What this project will deliver]
|
||||||
|
- [Core features/capabilities]
|
||||||
|
- [Target platforms/environments]
|
||||||
|
|
||||||
|
### Out of Scope
|
||||||
|
- [What this project will NOT deliver]
|
||||||
|
- [Features explicitly excluded]
|
||||||
|
- [Deferred items]
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
|
||||||
|
### Technical Constraints
|
||||||
|
- [Technology limitations]
|
||||||
|
- [Platform requirements]
|
||||||
|
- [Integration constraints]
|
||||||
|
|
||||||
|
### Business Constraints
|
||||||
|
- [Timeline requirements]
|
||||||
|
- [Budget limitations]
|
||||||
|
- [Resource availability]
|
||||||
|
|
||||||
|
### Regulatory/Compliance
|
||||||
|
- [Legal requirements]
|
||||||
|
- [Security standards]
|
||||||
|
- [Industry regulations]
|
||||||
|
|
||||||
|
## Target Users
|
||||||
|
|
||||||
|
### Primary Users
|
||||||
|
- **User Type**: [Description]
|
||||||
|
- **Needs**: [What they need from this system]
|
||||||
|
- **Volume**: [Expected number of users]
|
||||||
|
|
||||||
|
### Secondary Users
|
||||||
|
- **User Type**: [Description]
|
||||||
|
- **Needs**: [What they need from this system]
|
||||||
|
|
||||||
|
## Key Requirements
|
||||||
|
|
||||||
|
### Functional Requirements
|
||||||
|
1. [Core functionality 1]
|
||||||
|
2. [Core functionality 2]
|
||||||
|
3. [Core functionality 3]
|
||||||
|
|
||||||
|
### Non-Functional Requirements
|
||||||
|
- **Performance**: [Targets]
|
||||||
|
- **Security**: [Requirements]
|
||||||
|
- **Scalability**: [Expectations]
|
||||||
|
- **Reliability**: [Uptime/availability]
|
||||||
|
|
||||||
|
## Timeline
|
||||||
|
|
||||||
|
### Major Milestones
|
||||||
|
| Milestone | Target Date | Description |
|
||||||
|
|-----------|-------------|-------------|
|
||||||
|
| [Name] | [Date] | [What will be delivered] |
|
||||||
|
| [Name] | [Date] | [What will be delivered] |
|
||||||
|
|
||||||
|
### Current Phase
|
||||||
|
[Description of current project phase]
|
||||||
|
|
||||||
|
## Stakeholders
|
||||||
|
|
||||||
|
### Primary Stakeholders
|
||||||
|
- **[Role]**: [Name/Team] - [Interest/Influence]
|
||||||
|
- **[Role]**: [Name/Team] - [Interest/Influence]
|
||||||
|
|
||||||
|
### Key Decision Makers
|
||||||
|
- **[Role]**: [Name] - [Decisions they make]
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [Link to detailed requirements]
|
||||||
|
- [Link to design documents]
|
||||||
|
- [Link to related projects]
|
||||||
|
|
||||||
|
---
|
||||||
|
*This document defines the project foundation. All other memory bank files build upon this brief.*
|
||||||
|
|
@ -0,0 +1,175 @@
|
||||||
|
# System Patterns
|
||||||
|
|
||||||
|
*Technical architecture, design patterns, and critical implementation decisions*
|
||||||
|
|
||||||
|
## System Architecture Overview
|
||||||
|
|
||||||
|
### High-Level Architecture
|
||||||
|
```
|
||||||
|
[ASCII or text diagram showing major components and relationships]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Architectural Style
|
||||||
|
- **Pattern**: [e.g., Microservices, Monolith, Serverless]
|
||||||
|
- **Rationale**: [Why this architecture was chosen]
|
||||||
|
- **Trade-offs**: [What we gain vs. what we sacrifice]
|
||||||
|
|
||||||
|
## Core Components
|
||||||
|
|
||||||
|
### Component 1: [Name]
|
||||||
|
- **Purpose**: [What it does]
|
||||||
|
- **Responsibilities**: [Key functions]
|
||||||
|
- **Technology**: [Implementation details]
|
||||||
|
- **Interfaces**: [How others interact with it]
|
||||||
|
- **Location**: [Where to find the code]
|
||||||
|
|
||||||
|
### Component 2: [Name]
|
||||||
|
- **Purpose**: [What it does]
|
||||||
|
- **Responsibilities**: [Key functions]
|
||||||
|
- **Technology**: [Implementation details]
|
||||||
|
- **Interfaces**: [How others interact with it]
|
||||||
|
- **Location**: [Where to find the code]
|
||||||
|
|
||||||
|
## Design Patterns
|
||||||
|
|
||||||
|
### Pattern 1: [Pattern Name]
|
||||||
|
- **Where Used**: [Components/modules using this pattern]
|
||||||
|
- **Implementation**: [How it's implemented]
|
||||||
|
- **Benefits**: [Why we use it]
|
||||||
|
- **Example**: [Code location or snippet]
|
||||||
|
|
||||||
|
### Pattern 2: [Pattern Name]
|
||||||
|
- **Where Used**: [Components/modules using this pattern]
|
||||||
|
- **Implementation**: [How it's implemented]
|
||||||
|
- **Benefits**: [Why we use it]
|
||||||
|
|
||||||
|
## Data Architecture
|
||||||
|
|
||||||
|
### Data Flow
|
||||||
|
```
|
||||||
|
[Diagram showing how data moves through the system]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Storage Strategy
|
||||||
|
| Data Type | Storage | Rationale | Retention |
|
||||||
|
|-----------|---------|-----------|-----------|
|
||||||
|
| [Type] | [Where stored] | [Why] | [How long] |
|
||||||
|
| [Type] | [Where stored] | [Why] | [How long] |
|
||||||
|
|
||||||
|
### Data Models
|
||||||
|
- **Core Entities**: [List main domain objects]
|
||||||
|
- **Relationships**: [How entities relate]
|
||||||
|
- **Schemas**: [Location of schema definitions]
|
||||||
|
|
||||||
|
## Integration Architecture
|
||||||
|
|
||||||
|
### Internal Integrations
|
||||||
|
```
|
||||||
|
Service A <--> Service B
|
||||||
|
| |
|
||||||
|
v v
|
||||||
|
Service C <--> Service D
|
||||||
|
```
|
||||||
|
|
||||||
|
### External Integrations
|
||||||
|
| System | Integration Type | Purpose | Critical? |
|
||||||
|
|--------|-----------------|---------|-----------|
|
||||||
|
| [Name] | [REST/GraphQL/etc] | [Why we integrate] | [Yes/No] |
|
||||||
|
| [Name] | [Type] | [Purpose] | [Yes/No] |
|
||||||
|
|
||||||
|
### API Design Principles
|
||||||
|
- [Principle 1: e.g., RESTful conventions]
|
||||||
|
- [Principle 2: e.g., Versioning strategy]
|
||||||
|
- [Principle 3: e.g., Error handling approach]
|
||||||
|
|
||||||
|
## Security Architecture
|
||||||
|
|
||||||
|
### Security Layers
|
||||||
|
1. **Edge Security**: [WAF, DDoS protection]
|
||||||
|
2. **Application Security**: [Authentication, authorization]
|
||||||
|
3. **Data Security**: [Encryption at rest/transit]
|
||||||
|
4. **Infrastructure Security**: [Network isolation, secrets]
|
||||||
|
|
||||||
|
### Authentication & Authorization
|
||||||
|
- **Method**: [JWT, OAuth, SAML, etc.]
|
||||||
|
- **Implementation**: [How it works]
|
||||||
|
- **Authorization Model**: [RBAC, ABAC, etc.]
|
||||||
|
|
||||||
|
## Critical Implementation Paths
|
||||||
|
|
||||||
|
### Path 1: [User Authentication Flow]
|
||||||
|
1. User submits credentials
|
||||||
|
2. [Step 2 with component]
|
||||||
|
3. [Step 3 with component]
|
||||||
|
4. Token returned
|
||||||
|
|
||||||
|
### Path 2: [Core Business Process]
|
||||||
|
1. [Starting point]
|
||||||
|
2. [Processing step]
|
||||||
|
3. [Decision point]
|
||||||
|
4. [Completion]
|
||||||
|
|
||||||
|
## Performance Patterns
|
||||||
|
|
||||||
|
### Caching Strategy
|
||||||
|
- **What's Cached**: [Data types]
|
||||||
|
- **Where**: [Cache locations]
|
||||||
|
- **TTL**: [Expiration strategies]
|
||||||
|
- **Invalidation**: [How cache is cleared]
|
||||||
|
|
||||||
|
### Async Processing
|
||||||
|
- **Queue System**: [Technology used]
|
||||||
|
- **Use Cases**: [What goes async]
|
||||||
|
- **Retry Logic**: [Failure handling]
|
||||||
|
|
||||||
|
## Scalability Patterns
|
||||||
|
|
||||||
|
### Horizontal Scaling
|
||||||
|
- **Stateless Components**: [Which can scale out]
|
||||||
|
- **Load Balancing**: [Strategy]
|
||||||
|
- **Session Management**: [How handled]
|
||||||
|
|
||||||
|
### Vertical Scaling
|
||||||
|
- **Bottlenecks**: [Known limitations]
|
||||||
|
- **Optimization Points**: [Where to focus]
|
||||||
|
|
||||||
|
## Key Technical Decisions
|
||||||
|
|
||||||
|
Reference: See `docs/adr/` for detailed Architectural Decision Records
|
||||||
|
|
||||||
|
### Decision 1: [Title]
|
||||||
|
- **Choice**: [What was decided]
|
||||||
|
- **Rationale**: [Why]
|
||||||
|
- **Impact**: [Consequences]
|
||||||
|
|
||||||
|
### Decision 2: [Title]
|
||||||
|
- **Choice**: [What was decided]
|
||||||
|
- **Rationale**: [Why]
|
||||||
|
- **Impact**: [Consequences]
|
||||||
|
|
||||||
|
## Error Handling Patterns
|
||||||
|
|
||||||
|
### Global Error Strategy
|
||||||
|
- **Logging**: [How errors are logged]
|
||||||
|
- **User Feedback**: [How errors shown to users]
|
||||||
|
- **Recovery**: [Automatic recovery mechanisms]
|
||||||
|
|
||||||
|
### Circuit Breakers
|
||||||
|
- **Protected Services**: [Which integrations]
|
||||||
|
- **Thresholds**: [When circuits open]
|
||||||
|
- **Fallbacks**: [Degraded functionality]
|
||||||
|
|
||||||
|
## Monitoring & Observability
|
||||||
|
|
||||||
|
### Key Metrics
|
||||||
|
- **Business Metrics**: [What we track]
|
||||||
|
- **Technical Metrics**: [Performance indicators]
|
||||||
|
- **SLIs/SLOs**: [Service level indicators/objectives]
|
||||||
|
|
||||||
|
### Logging Strategy
|
||||||
|
- **Log Levels**: [When to use each]
|
||||||
|
- **Structured Logging**: [Format/fields]
|
||||||
|
- **Retention**: [How long kept]
|
||||||
|
|
||||||
|
---
|
||||||
|
*This document captures the technical architecture and implementation patterns. It's updated when architectural decisions are made or patterns change.*
|
||||||
|
|
@ -0,0 +1,187 @@
|
||||||
|
# Tech Context
|
||||||
|
|
||||||
|
*Technology stack, development environment, and technical constraints*
|
||||||
|
|
||||||
|
## Technology Stack
|
||||||
|
|
||||||
|
### Core Technologies
|
||||||
|
| Layer | Technology | Version | Purpose |
|
||||||
|
|-------|------------|---------|---------|
|
||||||
|
| Runtime | [e.g., Node.js] | [Version] | [Why chosen] |
|
||||||
|
| Framework | [e.g., Express] | [Version] | [Main framework] |
|
||||||
|
| Database | [e.g., PostgreSQL] | [Version] | [Data persistence] |
|
||||||
|
| Cache | [e.g., Redis] | [Version] | [Performance] |
|
||||||
|
| Queue | [e.g., RabbitMQ] | [Version] | [Async processing] |
|
||||||
|
|
||||||
|
### Frontend Stack (if applicable)
|
||||||
|
| Technology | Version | Purpose |
|
||||||
|
|------------|---------|---------|
|
||||||
|
| [Framework] | [Version] | [UI framework] |
|
||||||
|
| [State Mgmt] | [Version] | [State management] |
|
||||||
|
| [Build Tool] | [Version] | [Bundling] |
|
||||||
|
| [CSS Solution] | [Version] | [Styling] |
|
||||||
|
|
||||||
|
### Infrastructure
|
||||||
|
| Component | Technology | Purpose |
|
||||||
|
|-----------|------------|---------|
|
||||||
|
| Hosting | [e.g., AWS EC2] | [Where it runs] |
|
||||||
|
| Container | [e.g., Docker] | [Containerization] |
|
||||||
|
| Orchestration | [e.g., K8s] | [Container management] |
|
||||||
|
| CI/CD | [e.g., GitHub Actions] | [Automation] |
|
||||||
|
|
||||||
|
## Development Environment
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
- **OS**: [Supported operating systems]
|
||||||
|
- **Runtime**: [Required versions]
|
||||||
|
- **Tools**: [Required development tools]
|
||||||
|
- **Access**: [Required permissions/accounts]
|
||||||
|
|
||||||
|
### Local Setup
|
||||||
|
```bash
|
||||||
|
# Quick start commands
|
||||||
|
git clone [repository]
|
||||||
|
cd [project]
|
||||||
|
npm install # or equivalent
|
||||||
|
npm run setup
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
| Variable | Purpose | Example | Required |
|
||||||
|
|----------|---------|---------|----------|
|
||||||
|
| `DATABASE_URL` | [Database connection] | `postgres://...` | Yes |
|
||||||
|
| `REDIS_URL` | [Cache connection] | `redis://...` | Yes |
|
||||||
|
| `API_KEY` | [External service] | `sk_...` | No |
|
||||||
|
|
||||||
|
### Development Tools
|
||||||
|
- **IDE**: [Recommended IDE and extensions]
|
||||||
|
- **Debugger**: [How to debug]
|
||||||
|
- **API Testing**: [Postman/Insomnia setup]
|
||||||
|
- **Database Tools**: [GUI clients]
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
### Core Dependencies
|
||||||
|
| Package | Version | Purpose | Critical? |
|
||||||
|
|---------|---------|---------|-----------|
|
||||||
|
| [Name] | [Version] | [What it does] | [Yes/No] |
|
||||||
|
| [Name] | [Version] | [What it does] | [Yes/No] |
|
||||||
|
|
||||||
|
### Development Dependencies
|
||||||
|
| Package | Version | Purpose |
|
||||||
|
|---------|---------|---------|
|
||||||
|
| [Name] | [Version] | [Testing/linting/etc] |
|
||||||
|
| [Name] | [Version] | [Purpose] |
|
||||||
|
|
||||||
|
### Dependency Management
|
||||||
|
- **Update Strategy**: [How/when to update]
|
||||||
|
- **Security Scanning**: [Tools used]
|
||||||
|
- **License Compliance**: [Checks in place]
|
||||||
|
|
||||||
|
## Build & Deployment
|
||||||
|
|
||||||
|
### Build Process
|
||||||
|
```bash
|
||||||
|
# Development build
|
||||||
|
npm run build:dev
|
||||||
|
|
||||||
|
# Production build
|
||||||
|
npm run build:prod
|
||||||
|
|
||||||
|
# What happens during build
|
||||||
|
1. [Step 1]
|
||||||
|
2. [Step 2]
|
||||||
|
3. [Output]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deployment Pipeline
|
||||||
|
1. **Local Development**: [Process]
|
||||||
|
2. **Testing Environment**: [How to deploy]
|
||||||
|
3. **Staging**: [Process and checks]
|
||||||
|
4. **Production**: [Deployment method]
|
||||||
|
|
||||||
|
### Configuration Management
|
||||||
|
- **Development**: [Config location/method]
|
||||||
|
- **Staging**: [Config management]
|
||||||
|
- **Production**: [Secrets handling]
|
||||||
|
|
||||||
|
## Technical Constraints
|
||||||
|
|
||||||
|
### Performance Requirements
|
||||||
|
- **Response Time**: [Target latency]
|
||||||
|
- **Throughput**: [Requests per second]
|
||||||
|
- **Concurrent Users**: [Expected load]
|
||||||
|
- **Data Volume**: [Storage expectations]
|
||||||
|
|
||||||
|
### Browser/Platform Support
|
||||||
|
| Platform | Minimum Version | Notes |
|
||||||
|
|----------|----------------|-------|
|
||||||
|
| Chrome | [Version] | [Full support] |
|
||||||
|
| Firefox | [Version] | [Any limitations] |
|
||||||
|
| Safari | [Version] | [Any limitations] |
|
||||||
|
| Edge | [Version] | [Support level] |
|
||||||
|
| Mobile | [iOS/Android versions] | [Considerations] |
|
||||||
|
|
||||||
|
### API Constraints
|
||||||
|
- **Rate Limits**: [Any throttling]
|
||||||
|
- **Payload Size**: [Maximum sizes]
|
||||||
|
- **Timeout**: [Request timeouts]
|
||||||
|
- **Versioning**: [API version strategy]
|
||||||
|
|
||||||
|
### Security Constraints
|
||||||
|
- **Compliance**: [PCI, HIPAA, GDPR, etc.]
|
||||||
|
- **Encryption**: [Requirements]
|
||||||
|
- **Authentication**: [Requirements]
|
||||||
|
- **Audit**: [Logging requirements]
|
||||||
|
|
||||||
|
## External Services
|
||||||
|
|
||||||
|
### Third-Party APIs
|
||||||
|
| Service | Purpose | Limits | Fallback |
|
||||||
|
|---------|---------|--------|----------|
|
||||||
|
| [Name] | [What we use it for] | [Rate limits] | [If it fails] |
|
||||||
|
| [Name] | [Purpose] | [Quotas] | [Backup plan] |
|
||||||
|
|
||||||
|
### Monitoring Services
|
||||||
|
- **APM**: [Application monitoring tool]
|
||||||
|
- **Logging**: [Log aggregation service]
|
||||||
|
- **Error Tracking**: [Error monitoring]
|
||||||
|
- **Analytics**: [Usage tracking]
|
||||||
|
|
||||||
|
## Testing Infrastructure
|
||||||
|
|
||||||
|
### Test Types
|
||||||
|
| Type | Tool | Location | Command |
|
||||||
|
|------|------|----------|---------|
|
||||||
|
| Unit | [Jest] | `/tests/unit` | `npm test` |
|
||||||
|
| Integration | [Tool] | `/tests/integration` | `npm run test:int` |
|
||||||
|
| E2E | [Tool] | `/tests/e2e` | `npm run test:e2e` |
|
||||||
|
|
||||||
|
### Test Environment
|
||||||
|
- **Database**: [Test DB setup]
|
||||||
|
- **External Services**: [Mocking strategy]
|
||||||
|
- **Test Data**: [Fixtures/factories]
|
||||||
|
|
||||||
|
## Maintenance Considerations
|
||||||
|
|
||||||
|
### Regular Tasks
|
||||||
|
- **Dependency Updates**: [Schedule/process]
|
||||||
|
- **Security Patches**: [Response time]
|
||||||
|
- **Database Maintenance**: [Tasks]
|
||||||
|
- **Log Rotation**: [Policy]
|
||||||
|
|
||||||
|
### Monitoring Alerts
|
||||||
|
| Alert | Threshold | Action |
|
||||||
|
|-------|-----------|--------|
|
||||||
|
| High Error Rate | >1% | [Response] |
|
||||||
|
| Slow Response | >2s | [Investigation] |
|
||||||
|
| Database Connection | Failed | [Escalation] |
|
||||||
|
|
||||||
|
### Known Limitations
|
||||||
|
1. **Limitation 1**: [Description and workaround]
|
||||||
|
2. **Limitation 2**: [Description and impact]
|
||||||
|
3. **Technical Debt**: [Areas needing attention]
|
||||||
|
|
||||||
|
---
|
||||||
|
*This document defines the technical environment and constraints. Update when tools, versions, or constraints change.*
|
||||||
Loading…
Reference in New Issue