grimoire-framework 1.0.0

package/.grimoire/product/templates/brownfield-prd-tmpl.yaml

@@ -0,0 +1,280 @@
+template:
+  id: brownfield-prd-template-v2
+  name: Brownfield Enhancement PRD
+  version: 2.0
+  output:
+    format: markdown
+    filename: docs/prd.md
+    title: "{{project_name}} Brownfield Enhancement PRD"
+
+workflow:
+  mode: interactive
+  elicitation: advanced-elicitation
+
+sections:
+  - id: intro-analysis
+    title: Intro Project Analysis and Context
+    instruction: |
+      IMPORTANT - SCOPE ASSESSMENT REQUIRED:
+      
+      This PRD is for SIGNIFICANT enhancements to existing projects that require comprehensive planning and multiple stories. Before proceeding:
+      
+      1. **Assess Enhancement Complexity**: If this is a simple feature addition or bug fix that could be completed in 1-2 focused development sessions, STOP and recommend: "For simpler changes, consider using the brownfield-create-epic or brownfield-create-story task with the Product Owner instead. This full PRD process is designed for substantial enhancements that require architectural planning and multiple coordinated stories."
+      
+      2. **Project Context**: Determine if we're working in an IDE with the project already loaded or if the user needs to provide project information. If project files are available, analyze existing documentation in the docs folder. If insufficient documentation exists, recommend running the document-project task first.
+      
+      3. **Deep Assessment Requirement**: You MUST thoroughly analyze the existing project structure, patterns, and constraints before making ANY suggestions. Every recommendation must be grounded in actual project analysis, not assumptions.
+      
+      Gather comprehensive information about the existing project. This section must be completed before proceeding with requirements.
+      
+      CRITICAL: Throughout this analysis, explicitly confirm your understanding with the user. For every assumption you make about the existing project, ask: "Based on my analysis, I understand that [assumption]. Is this correct?"
+      
+      Do not proceed with any recommendations until the user has validated your understanding of the existing system.
+    sections:
+      - id: existing-project-overview
+        title: Existing Project Overview
+        instruction: Check if document-project analysis was already performed. If yes, reference that output instead of re-analyzing.
+        sections:
+          - id: analysis-source
+            title: Analysis Source
+            instruction: |
+              Indicate one of the following:
+              - Document-project output available at: {{path}}
+              - IDE-based fresh analysis
+              - User-provided information
+          - id: current-state
+            title: Current Project State
+            instruction: |
+              - If document-project output exists: Extract summary from "High Level Architecture" and "Technical Summary" sections
+              - Otherwise: Brief description of what the project currently does and its primary purpose
+      - id: documentation-analysis
+        title: Available Documentation Analysis
+        instruction: |
+          If document-project was run:
+          - Note: "Document-project analysis available - using existing technical documentation"
+          - List key documents created by document-project
+          - Skip the missing documentation check below
+          
+          Otherwise, check for existing documentation:
+        sections:
+          - id: available-docs
+            title: Available Documentation
+            type: checklist
+            items:
+              - Tech Stack Documentation [[LLM: If from document-project, check ✓]]
+              - Source Tree/Architecture [[LLM: If from document-project, check ✓]]
+              - Coding Standards [[LLM: If from document-project, may be partial]]
+              - API Documentation [[LLM: If from document-project, check ✓]]
+              - External API Documentation [[LLM: If from document-project, check ✓]]
+              - UX/UI Guidelines [[LLM: May not be in document-project]]
+              - Technical Debt Documentation [[LLM: If from document-project, check ✓]]
+              - "Other: {{other_docs}}"
+            instruction: |
+              - If document-project was already run: "Using existing project analysis from document-project output."
+              - If critical documentation is missing and no document-project: "I recommend running the document-project task first..."
+      - id: enhancement-scope
+        title: Enhancement Scope Definition
+        instruction: Work with user to clearly define what type of enhancement this is. This is critical for scoping and approach.
+        sections:
+          - id: enhancement-type
+            title: Enhancement Type
+            type: checklist
+            instruction: Determine with user which applies
+            items:
+              - New Feature Addition
+              - Major Feature Modification
+              - Integration with New Systems
+              - Performance/Scalability Improvements
+              - UI/UX Overhaul
+              - Technology Stack Upgrade
+              - Bug Fix and Stability Improvements
+              - "Other: {{other_type}}"
+          - id: enhancement-description
+            title: Enhancement Description
+            instruction: 2-3 sentences describing what the user wants to add or change
+          - id: impact-assessment
+            title: Impact Assessment
+            type: checklist
+            instruction: Assess the scope of impact on existing codebase
+            items:
+              - Minimal Impact (isolated additions)
+              - Moderate Impact (some existing code changes)
+              - Significant Impact (substantial existing code changes)
+              - Major Impact (architectural changes required)
+      - id: goals-context
+        title: Goals and Background Context
+        sections:
+          - id: goals
+            title: Goals
+            type: bullet-list
+            instruction: Bullet list of 1-line desired outcomes this enhancement will deliver if successful
+          - id: background
+            title: Background Context
+            type: paragraphs
+            instruction: 1-2 short paragraphs explaining why this enhancement is needed, what problem it solves, and how it fits with the existing project
+      - id: changelog
+        title: Change Log
+        type: table
+        columns: [Change, Date, Version, Description, Author]
+
+  - id: requirements
+    title: Requirements
+    instruction: |
+      Draft functional and non-functional requirements based on your validated understanding of the existing project. Before presenting requirements, confirm: "These requirements are based on my understanding of your existing system. Please review carefully and confirm they align with your project's reality."
+    elicit: true
+    sections:
+      - id: functional
+        title: Functional
+        type: numbered-list
+        prefix: FR
+        instruction: Each Requirement will be a bullet markdown with identifier starting with FR
+        examples:
+          - "FR1: The existing Todo List will integrate with the new AI duplicate detection service without breaking current functionality."
+      - id: non-functional
+        title: Non Functional
+        type: numbered-list
+        prefix: NFR
+        instruction: Each Requirement will be a bullet markdown with identifier starting with NFR. Include constraints from existing system
+        examples:
+          - "NFR1: Enhancement must maintain existing performance characteristics and not exceed current memory usage by more than 20%."
+      - id: compatibility
+        title: Compatibility Requirements
+        instruction: Critical for brownfield - what must remain compatible
+        type: numbered-list
+        prefix: CR
+        template: "{{requirement}}: {{description}}"
+        items:
+          - id: cr1
+            template: "CR1: {{existing_api_compatibility}}"
+          - id: cr2
+            template: "CR2: {{database_schema_compatibility}}"
+          - id: cr3
+            template: "CR3: {{ui_ux_consistency}}"
+          - id: cr4
+            template: "CR4: {{integration_compatibility}}"
+
+  - id: ui-enhancement-goals
+    title: User Interface Enhancement Goals
+    condition: Enhancement includes UI changes
+    instruction: For UI changes, capture how they will integrate with existing UI patterns and design systems
+    sections:
+      - id: existing-ui-integration
+        title: Integration with Existing UI
+        instruction: Describe how new UI elements will fit with existing design patterns, style guides, and component libraries
+      - id: modified-screens
+        title: Modified/New Screens and Views
+        instruction: List only the screens/views that will be modified or added
+      - id: ui-consistency
+        title: UI Consistency Requirements
+        instruction: Specific requirements for maintaining visual and interaction consistency with existing application
+
+  - id: technical-constraints
+    title: Technical Constraints and Integration Requirements
+    instruction: This section replaces separate architecture documentation. Gather detailed technical constraints from existing project analysis.
+    sections:
+      - id: existing-tech-stack
+        title: Existing Technology Stack
+        instruction: |
+          If document-project output available:
+          - Extract from "Actual Tech Stack" table in High Level Architecture section
+          - Include version numbers and any noted constraints
+          
+          Otherwise, document the current technology stack:
+        template: |
+          **Languages**: {{languages}}
+          **Frameworks**: {{frameworks}}
+          **Database**: {{database}}
+          **Infrastructure**: {{infrastructure}}
+          **External Dependencies**: {{external_dependencies}}
+      - id: integration-approach
+        title: Integration Approach
+        instruction: Define how the enhancement will integrate with existing architecture
+        template: |
+          **Database Integration Strategy**: {{database_integration}}
+          **API Integration Strategy**: {{api_integration}}
+          **Frontend Integration Strategy**: {{frontend_integration}}
+          **Testing Integration Strategy**: {{testing_integration}}
+      - id: code-organization
+        title: Code Organization and Standards
+        instruction: Based on existing project analysis, define how new code will fit existing patterns
+        template: |
+          **File Structure Approach**: {{file_structure}}
+          **Naming Conventions**: {{naming_conventions}}
+          **Coding Standards**: {{coding_standards}}
+          **Documentation Standards**: {{documentation_standards}}
+      - id: deployment-operations
+        title: Deployment and Operations
+        instruction: How the enhancement fits existing deployment pipeline
+        template: |
+          **Build Process Integration**: {{build_integration}}
+          **Deployment Strategy**: {{deployment_strategy}}
+          **Monitoring and Logging**: {{monitoring_logging}}
+          **Configuration Management**: {{config_management}}
+      - id: risk-assessment
+        title: Risk Assessment and Mitigation
+        instruction: |
+          If document-project output available:
+          - Reference "Technical Debt and Known Issues" section
+          - Include "Workarounds and Gotchas" that might impact enhancement
+          - Note any identified constraints from "Critical Technical Debt"
+          
+          Build risk assessment incorporating existing known issues:
+        template: |
+          **Technical Risks**: {{technical_risks}}
+          **Integration Risks**: {{integration_risks}}
+          **Deployment Risks**: {{deployment_risks}}
+          **Mitigation Strategies**: {{mitigation_strategies}}
+
+  - id: epic-structure
+    title: Epic and Story Structure
+    instruction: |
+      For brownfield projects, favor a single comprehensive epic unless the user is clearly requesting multiple unrelated enhancements. Before presenting the epic structure, confirm: "Based on my analysis of your existing project, I believe this enhancement should be structured as [single epic/multiple epics] because [rationale based on actual project analysis]. Does this align with your understanding of the work required?"
+    elicit: true
+    sections:
+      - id: epic-approach
+        title: Epic Approach
+        instruction: Explain the rationale for epic structure - typically single epic for brownfield unless multiple unrelated features
+        template: "**Epic Structure Decision**: {{epic_decision}} with rationale"
+
+  - id: epic-details
+    title: "Epic 1: {{enhancement_title}}"
+    instruction: |
+      Comprehensive epic that delivers the brownfield enhancement while maintaining existing functionality
+      
+      CRITICAL STORY SEQUENCING FOR BROWNFIELD:
+      - Stories must ensure existing functionality remains intact
+      - Each story should include verification that existing features still work
+      - Stories should be sequenced to minimize risk to existing system
+      - Include rollback considerations for each story
+      - Focus on incremental integration rather than big-bang changes
+      - Size stories for AI agent execution in existing codebase context
+      - MANDATORY: Present the complete story sequence and ask: "This story sequence is designed to minimize risk to your existing system. Does this order make sense given your project's architecture and constraints?"
+      - Stories must be logically sequential with clear dependencies identified
+      - Each story must deliver value while maintaining system integrity
+    template: |
+      **Epic Goal**: {{epic_goal}}
+      
+      **Integration Requirements**: {{integration_requirements}}
+    sections:
+      - id: story
+        title: "Story 1.{{story_number}} {{story_title}}"
+        repeatable: true
+        template: |
+          As a {{user_type}},
+          I want {{action}},
+          so that {{benefit}}.
+        sections:
+          - id: acceptance-criteria
+            title: Acceptance Criteria
+            type: numbered-list
+            instruction: Define criteria that include both new functionality and existing system integrity
+            item_template: "{{criterion_number}}: {{criteria}}"
+          - id: integration-verification
+            title: Integration Verification
+            instruction: Specific verification steps to ensure existing functionality remains intact
+            type: numbered-list
+            prefix: IV
+            items:
+              - template: "IV1: {{existing_functionality_verification}}"
+              - template: "IV2: {{integration_point_verification}}"
+              - template: "IV3: {{performance_impact_verification}}" 

package/.grimoire/product/templates/brownfield-risk-report-tmpl.yaml

@@ -0,0 +1,278 @@
+# Brownfield Risk Report Template
+# Story grimoire-DIFF-4.3.2: Template de relatório de risco por fase
+
+template:
+  id: brownfield-risk-report
+  name: Brownfield Migration Risk Report
+  version: "1.0"
+  type: product
+  description: >
+    Template for generating risk assessment reports during brownfield
+    migration phases. Used by @analyst to create executive-level reports.
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                              REPORT STRUCTURE
+# ═══════════════════════════════════════════════════════════════════════════════
+
+sections:
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # EXECUTIVE SUMMARY
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  executive_summary:
+    title: "Executive Summary"
+    content: |
+      ## 📊 Risk Assessment Summary
+
+      **Project:** {{project_name}}
+      **Phase:** {{current_phase}}
+      **Date:** {{report_date}}
+      **Assessor:** @analyst
+
+      ### Overall Risk Level: {{overall_risk_level}}
+
+      | Metric | Value |
+      |--------|-------|
+      | Critical Risks | {{critical_count}} |
+      | High Risks | {{high_count}} |
+      | Medium Risks | {{medium_count}} |
+      | Low Risks | {{low_count}} |
+      | Mitigated | {{mitigated_count}} |
+
+      ### Key Findings
+      {{key_findings}}
+
+      ### Recommended Action
+      {{recommended_action}}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # PHASE-SPECIFIC RISKS
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  phase_risks:
+    title: "Phase-Specific Risk Analysis"
+    phases:
+
+      discovery:
+        name: "Discovery Phase"
+        description: "Initial codebase analysis and documentation"
+        typical_risks:
+          - id: DISC-001
+            name: "Incomplete Documentation"
+            description: "Existing system poorly documented, discovery may miss critical components"
+            probability: medium
+            impact: high
+            mitigation: "Cross-reference with running system, interview stakeholders"
+          - id: DISC-002
+            name: "Hidden Dependencies"
+            description: "Undocumented external services or databases"
+            probability: medium
+            impact: critical
+            mitigation: "Network traffic analysis, env var audit"
+          - id: DISC-003
+            name: "Time Underestimation"
+            description: "Discovery takes longer than 4-8h estimate"
+            probability: low
+            impact: medium
+            mitigation: "Checkpoint after each sub-phase, adjust timeline"
+
+      planning:
+        name: "Planning Phase"
+        description: "PRD and architecture design"
+        typical_risks:
+          - id: PLAN-001
+            name: "Scope Creep"
+            description: "Technical debt resolution expands beyond initial estimate"
+            probability: high
+            impact: medium
+            mitigation: "Fixed scope per phase, explicit out-of-scope list"
+          - id: PLAN-002
+            name: "Architecture Mismatch"
+            description: "Proposed architecture conflicts with existing constraints"
+            probability: medium
+            impact: high
+            mitigation: "Validate with existing code, incremental changes only"
+          - id: PLAN-003
+            name: "Stakeholder Misalignment"
+            description: "Business priorities differ from technical recommendations"
+            probability: medium
+            impact: high
+            mitigation: "Executive report before implementation, explicit tradeoffs"
+
+      migration:
+        name: "Migration Phase"
+        description: "Implementation of changes"
+        typical_risks:
+          - id: MIG-001
+            name: "Breaking Changes"
+            description: "New code breaks existing functionality"
+            probability: medium
+            impact: critical
+            mitigation: "Feature flags, comprehensive test coverage before changes"
+          - id: MIG-002
+            name: "Data Loss"
+            description: "Database migration causes data corruption or loss"
+            probability: low
+            impact: critical
+            mitigation: "Backup before migration, dry-run on staging, rollback script ready"
+          - id: MIG-003
+            name: "Downtime"
+            description: "Migration requires extended system downtime"
+            probability: medium
+            impact: high
+            mitigation: "Zero-downtime migration strategy, maintenance window planning"
+
+      rollout:
+        name: "Rollout Phase"
+        description: "Progressive deployment"
+        typical_risks:
+          - id: ROLL-001
+            name: "Performance Degradation"
+            description: "New code slower than existing implementation"
+            probability: medium
+            impact: high
+            mitigation: "Load testing before rollout, monitoring during rollout"
+          - id: ROLL-002
+            name: "User Disruption"
+            description: "Changed UX confuses existing users"
+            probability: medium
+            impact: medium
+            mitigation: "Gradual rollout (10% → 50% → 100%), feedback collection"
+          - id: ROLL-003
+            name: "Rollback Failure"
+            description: "Unable to revert to previous state"
+            probability: low
+            impact: critical
+            mitigation: "Test rollback before production rollout, checkpoint commits"
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # RISK MATRIX
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  risk_matrix:
+    title: "Risk Assessment Matrix"
+    content: |
+      ## Risk Classification
+
+      | Probability / Impact | Low | Medium | High | Critical |
+      |----------------------|-----|--------|------|----------|
+      | **High** | Medium | High | Critical | Critical |
+      | **Medium** | Low | Medium | High | Critical |
+      | **Low** | Low | Low | Medium | High |
+
+      ### Risk Levels
+
+      - **Critical**: Immediate action required, blocks progress
+      - **High**: Must be mitigated before proceeding to next phase
+      - **Medium**: Should be addressed, can proceed with monitoring
+      - **Low**: Acceptable, document and monitor
+
+      ### Current Phase Risks
+
+      | ID | Risk | Probability | Impact | Level | Status |
+      |----|------|-------------|--------|-------|--------|
+      {{risk_table}}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # MITIGATION PLAN
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  mitigation_plan:
+    title: "Mitigation Plan"
+    content: |
+      ## Mitigation Strategies
+
+      ### Critical & High Risks
+
+      {{critical_mitigations}}
+
+      ### Medium Risks
+
+      {{medium_mitigations}}
+
+      ### Monitoring Plan
+
+      | Risk ID | Metric to Watch | Threshold | Action if Exceeded |
+      |---------|-----------------|-----------|-------------------|
+      {{monitoring_table}}
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # ROLLBACK STRATEGY
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  rollback_strategy:
+    title: "Rollback Strategy"
+    content: |
+      ## Rollback Checkpoints
+
+      ### Phase Checkpoints
+
+      | Phase | Checkpoint | Rollback Command | Recovery Time |
+      |-------|------------|------------------|---------------|
+      | Discovery | Pre-analysis | N/A (read-only) | N/A |
+      | Planning | Pre-PRD | `git checkout {{pre_planning_commit}}` | < 1 min |
+      | Migration | Pre-migration | `git checkout {{pre_migration_commit}}` | < 5 min |
+      | Rollout | Pre-rollout | `git checkout {{pre_rollout_commit}}` | < 5 min |
+
+      ### Database Rollback
+
+      ```bash
+      # If database migration was applied:
+      npm run db:rollback -- --to={{last_good_migration}}
+
+      # If data was modified:
+      # Restore from backup taken at {{backup_timestamp}}
+      ```
+
+      ### Rollback Triggers
+
+      Automatic rollback if:
+      - [ ] Error rate exceeds 5% for 5 minutes
+      - [ ] Response time increases >200% from baseline
+      - [ ] Critical functionality fails health check
+
+      Manual rollback decision by:
+      - [ ] Tech lead approval for partial rollback
+      - [ ] CTO approval for full rollback
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # SIGN-OFF
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  sign_off:
+    title: "Sign-Off"
+    content: |
+      ## Phase Approval
+
+      | Role | Name | Approval | Date |
+      |------|------|----------|------|
+      | Technical Lead | | [ ] Approved | |
+      | Product Owner | | [ ] Approved | |
+      | QA Lead | | [ ] Approved | |
+
+      ### Conditions for Proceeding
+
+      - [ ] All critical risks mitigated
+      - [ ] All high risks have mitigation plan
+      - [ ] Rollback tested and verified
+      - [ ] Stakeholders notified
+
+      ---
+
+      **Report Generated By:** @analyst
+      **Template Version:** 1.0
+      **Story:** grimoire-DIFF-4.3.2
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                              USAGE
+# ═══════════════════════════════════════════════════════════════════════════════
+
+usage:
+  command: "@analyst → *create-doc brownfield-risk-report"
+  output: "docs/reports/BROWNFIELD-RISK-REPORT-{{phase}}.md"
+  triggers:
+    - Before each brownfield phase transition
+    - When new risks are identified
+    - Before stakeholder review meetings
+

package/.grimoire/product/templates/changelog-template.md

@@ -0,0 +1,134 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+-
+
+### Changed
+-
+
+### Deprecated
+-
+
+### Removed
+-
+
+### Fixed
+-
+
+### Security
+-
+
+---
+
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New feature description ([#issue](link))
+- Another new feature
+
+### Changed
+- Description of change
+- Updated dependency X to version Y
+
+### Deprecated
+- Feature X is deprecated and will be removed in vX.X.X
+
+### Removed
+- Removed feature Y (deprecated in vX.X.X)
+
+### Fixed
+- Fixed bug description ([#issue](link))
+- Another bug fix
+
+### Security
+- Fixed security vulnerability in X ([CVE-XXXX-XXXX](link))
+
+---
+
+## Version Template
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New features that were added
+
+### Changed
+- Changes in existing functionality
+
+### Deprecated
+- Features that will be removed in upcoming releases
+
+### Removed
+- Features that were removed
+
+### Fixed
+- Bug fixes
+
+### Security
+- Security vulnerability fixes
+```
+
+---
+
+## Semantic Versioning Guide
+
+- **MAJOR** (X.0.0): Breaking changes that are not backward compatible
+- **MINOR** (0.X.0): New features that are backward compatible
+- **PATCH** (0.0.X): Bug fixes that are backward compatible
+
+### Examples
+
+**MAJOR version bump:**
+- Removing or renaming public API methods
+- Changing function signatures
+- Dropping support for Node.js version
+- Database schema changes that require migration
+
+**MINOR version bump:**
+- Adding new API endpoints
+- Adding new optional parameters
+- New features that don't affect existing code
+- Performance improvements
+
+**PATCH version bump:**
+- Bug fixes
+- Security patches
+- Documentation updates
+- Internal refactoring (no API changes)
+
+---
+
+## Commit Message Convention
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style (formatting, semicolons)
+- `refactor`: Code change (no feature/fix)
+- `perf`: Performance improvement
+- `test`: Adding/updating tests
+- `chore`: Build/auxiliary tool changes
+
+---
+
+[Unreleased]: https://github.com/owner/repo/compare/vX.Y.Z...HEAD
+[X.Y.Z]: https://github.com/owner/repo/compare/vX.Y.W...vX.Y.Z