grimoire-framework 1.0.0

package/.grimoire/development/workflows/brownfield-fullstack.yaml

@@ -0,0 +1,369 @@
+workflow:
+  id: brownfield-fullstack
+  name: Brownfield Full-Stack Enhancement
+  description: >-
+    Agent workflow for enhancing existing full-stack applications with new features,
+    modernization, or significant changes. Handles existing system analysis and safe integration.
+  type: brownfield
+  version: "1.0"
+  project_types:
+    - feature-addition
+    - refactoring
+    - modernization
+    - integration-enhancement
+
+  metadata:
+    elicit: true
+    confirmation_required: true
+
+  phases:
+    - phase_1: Enhancement Classification & Routing
+    - phase_2: Planning & Documentation
+    - phase_3: Document Sharding
+    - phase_4: Development Cycle
+
+  sequence:
+    - phase: 1
+      name: Enhancement Classification & Routing
+
+    - id: analyst-classify-enhancement
+      step: enhancement_classification
+      agent: analyst
+      action: classify enhancement scope
+      duration_estimate: "10-15 min"
+      elicit: true
+      notes: |
+        Determine enhancement complexity to route to appropriate path:
+        - Single story (< 4 hours) → Use brownfield-create-story task
+        - Small feature (1-3 stories) → Use brownfield-create-epic task
+        - Major enhancement (multiple epics) → Continue with full workflow
+
+        Ask user: "Can you describe the enhancement scope? Is this a small fix, a feature addition, or a major enhancement requiring architectural changes?"
+
+    - id: routing-decision
+      step: routing_decision
+      meta: routing
+      duration_estimate: "5 min"
+      condition: based_on_classification
+      routes:
+        single_story:
+          agent: pm
+          uses: brownfield-create-story
+          notes: "Create single story for immediate implementation. Exit workflow after story creation."
+        small_feature:
+          agent: pm
+          uses: brownfield-create-epic
+          notes: "Create focused epic with 1-3 stories. Exit workflow after epic creation."
+        major_enhancement:
+          continue: to_next_step
+          notes: "Continue with comprehensive planning workflow below."
+
+    - phase: 2
+      name: Planning & Documentation
+
+    - id: analyst-check-documentation
+      step: documentation_check
+      agent: analyst
+      action: check existing documentation
+      duration_estimate: "10-20 min"
+      condition: major_enhancement_path
+      notes: |
+        Check if adequate project documentation exists:
+        - Look for existing architecture docs, API specs, coding standards
+        - Assess if documentation is current and comprehensive
+        - If adequate: Skip document-project, proceed to PRD
+        - If inadequate: Run document-project first
+
+    - id: architect-analyze-project
+      step: project_analysis
+      agent: architect
+      action: analyze existing project and use task document-project
+      creates: [brownfield-architecture.md]
+      duration_estimate: "30-60 min"
+      condition: documentation_inadequate
+      notes: "Run document-project to capture current system state, technical debt, and constraints. Pass findings to PRD creation."
+
+    - id: pm-create-prd
+      agent: pm
+      creates: prd.md
+      uses: brownfield-prd-tmpl
+      duration_estimate: "30-60 min"
+      requires: existing_documentation_or_analysis
+      notes: |
+        Creates PRD for major enhancement. If document-project was run, reference its output to avoid re-analysis.
+        If skipped, use existing project documentation.
+        SAVE OUTPUT: Copy final prd.md to your project's docs/ folder.
+
+    - id: pm-architecture-decision
+      step: architecture_decision
+      agent: pm
+      alternative_agent: architect
+      action: determine if architecture document needed
+      duration_estimate: "10-15 min"
+      condition: after_prd_creation
+      notes: |
+        Review PRD to determine if architectural planning is needed:
+        - New architectural patterns → Create architecture doc
+        - New libraries/frameworks → Create architecture doc
+        - Platform/infrastructure changes → Create architecture doc
+        - Following existing patterns → Skip to story creation
+
+    - id: architect-create-architecture
+      agent: architect
+      creates: architecture.md
+      uses: brownfield-architecture-tmpl
+      duration_estimate: "30-60 min"
+      requires: prd.md
+      condition: architecture_changes_needed
+      notes: "Creates architecture ONLY for significant architectural changes. SAVE OUTPUT: Copy final architecture.md to your project's docs/ folder."
+
+    - id: po-validate-artifacts
+      agent: po
+      validates: all_artifacts
+      uses: po-master-checklist
+      duration_estimate: "15-30 min"
+      notes: "Validates all documents for integration safety and completeness. May require updates to any document."
+
+    - id: po-delegate-fixes
+      agent: po
+      action: delegate_fixes
+      delegates_to: [analyst, pm, architect]
+      updates: any_flagged_documents
+      duration_estimate: "15-30 min"
+      condition: po_checklist_issues
+      notes: "If PO finds issues, PO delegates fixes to the relevant agent and re-validates updated documents in docs/ folder."
+
+    - phase: 3
+      name: Document Sharding
+
+    - id: po-shard-documents
+      agent: po
+      action: shard_documents
+      creates: sharded_docs
+      duration_estimate: "15-30 min"
+      requires:  # all validated artifacts must be saved in project docs/ folder
+        - prd.md
+        - architecture.md
+      notes: |
+        Shard documents for IDE development:
+        - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+        - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+        - Creates docs/prd/ and docs/architecture/ folders with sharded content
+
+    - phase: 4
+      name: Development Cycle
+
+    - id: sm-create-story
+      agent: sm
+      action: create_story
+      creates: story.md
+      duration_estimate: "15-30 min"
+      requires: sharded_docs_or_brownfield_docs
+      repeats: for_each_epic_or_enhancement
+      notes: |
+        Story creation cycle:
+        - For sharded PRD: @sm → *create (uses create-next-story)
+        - For brownfield docs: @sm → use create-brownfield-story task
+        - Creates story from available documentation
+        - Story starts in "Draft" status
+        - May require additional context gathering for brownfield
+
+    - id: pm-review-draft-story
+      agent: pm
+      alternative_agent: analyst
+      action: review_draft_story
+      updates: story.md
+      duration_estimate: "10-20 min"
+      requires: story.md
+      optional: true
+      condition: user_wants_story_review
+      notes: |
+        OPTIONAL: Review and approve draft story
+        - NOTE: story-review task coming soon
+        - Review story completeness and alignment
+        - Update story status: Draft → Approved
+
+    - id: dev-implement-story
+      agent: dev
+      action: implement_story
+      creates: implementation_files
+      duration_estimate: "1-4 hours"
+      requires: story.md
+      notes: |
+        Dev Agent (New Chat): @dev
+        - Implements approved story
+        - Updates File List with all changes
+        - Marks story as "Review" when complete
+
+    - id: qa-review-implementation
+      agent: qa
+      action: review_implementation
+      updates: implementation_files
+      duration_estimate: "20-40 min"
+      requires: implementation_files
+      optional: true
+      notes: |
+        OPTIONAL: QA Agent (New Chat): @qa → review-story
+        - Senior dev review with refactoring ability
+        - Fixes small issues directly
+        - Leaves checklist for remaining items
+        - Updates story status (Review → Done or stays Review)
+
+    - id: dev-address-qa-feedback
+      agent: dev
+      action: address_qa_feedback
+      updates: implementation_files
+      requires: implementation_files
+      duration_estimate: "30-60 min"
+      condition: qa_left_unchecked_items
+      notes: |
+        If QA left unchecked items:
+        - Dev Agent (New Chat): Address remaining items
+        - Return to QA for final approval
+
+    - meta: repeat
+      target_steps: [sm-create-story, dev-implement-story, qa-review-implementation]
+      condition: stories_remaining
+      notes: |
+        Repeat story cycle (SM → Dev → QA) for all epic stories
+        Continue until all stories in PRD are complete
+
+    - id: po-epic-retrospective
+      agent: po
+      action: epic_retrospective
+      creates: epic-retrospective.md
+      duration_estimate: "15-30 min"
+      condition: epic_complete
+      optional: true
+      notes: |
+        OPTIONAL: After epic completion
+        - NOTE: epic-retrospective task coming soon
+        - Validate epic was completed correctly
+        - Document learnings and improvements
+
+    - meta: end
+      notes: |
+        All stories implemented and reviewed!
+        Project development phase complete.
+
+        Reference: .grimoire/data/grimoire-kb.md#IDE Development Workflow
+
+  flow_diagram: |
+    ```mermaid
+    graph TD
+        A[Start: Brownfield Enhancement] --> B[analyst: classify enhancement scope]
+        B --> C{Enhancement Size?}
+
+        C -->|Single Story| D[pm: brownfield-create-story]
+        C -->|1-3 Stories| E[pm: brownfield-create-epic]
+        C -->|Major Enhancement| F[analyst: check documentation]
+
+        D --> END1[To Dev Implementation]
+        E --> END2[To Story Creation]
+
+        F --> G{Docs Adequate?}
+        G -->|No| H[architect: document-project]
+        G -->|Yes| I[pm: brownfield PRD]
+        H --> I
+
+        I --> J{Architecture Needed?}
+        J -->|Yes| K[architect: architecture.md]
+        J -->|No| L[po: validate artifacts]
+        K --> L
+
+        L --> M{PO finds issues?}
+        M -->|Yes| N[po: delegate fixes to relevant agent]
+        M -->|No| O[po: shard documents]
+        N --> L
+
+        O --> P[sm: create story]
+        P --> Q{Story Type?}
+        Q -->|Sharded PRD| R[create-next-story]
+        Q -->|Brownfield Docs| S[create-brownfield-story]
+
+        R --> T{Review draft?}
+        S --> T
+        T -->|Yes| U[pm/analyst: review & approve story]
+        T -->|No| V[dev: implement]
+        U --> V
+
+        V --> W{QA review?}
+        W -->|Yes| X[qa: review]
+        W -->|No| Y{More stories?}
+        X --> Z{Issues?}
+        Z -->|Yes| AA[dev: fix]
+        Z -->|No| Y
+        AA --> X
+        Y -->|Yes| P
+        Y -->|No| AB{Retrospective?}
+        AB -->|Yes| AC[po: retrospective]
+        AB -->|No| AD[Complete]
+        AC --> AD
+
+        style AD fill:#90EE90
+        style END1 fill:#90EE90
+        style END2 fill:#90EE90
+        style D fill:#87CEEB
+        style E fill:#87CEEB
+        style I fill:#FFE4B5
+        style K fill:#FFE4B5
+        style O fill:#ADD8E6
+        style P fill:#ADD8E6
+        style V fill:#ADD8E6
+        style U fill:#F0E68C
+        style X fill:#F0E68C
+        style AC fill:#F0E68C
+    ```
+
+  decision_guidance:
+    when_to_use:
+      - Enhancement requires coordinated stories
+      - Architectural changes are needed
+      - Significant integration work required
+      - Risk assessment and mitigation planning necessary
+      - Multiple team members will work on related changes
+
+    when_not_to_use:
+      - New project from scratch (use greenfield-fullstack)
+      - Service-only enhancement (use brownfield-service)
+      - Frontend-only enhancement (use brownfield-ui)
+      - Technical debt assessment only (use brownfield-discovery)
+
+  handoff_prompts:
+    classification_complete: |
+      Enhancement classified as: {{enhancement_type}}
+      {{if single_story}}: Proceeding with brownfield-create-story task for immediate implementation.
+      {{if small_feature}}: Creating focused epic with brownfield-create-epic task.
+      {{if major_enhancement}}: Continuing with comprehensive planning workflow.
+
+    documentation_assessment: |
+      Documentation assessment complete:
+      {{if adequate}}: Existing documentation is sufficient. Proceeding directly to PRD creation.
+      {{if inadequate}}: Running document-project to capture current system state before PRD.
+
+    document_project_to_pm: |
+      Project analysis complete. Key findings documented in:
+      - {{document_list}}
+      Use these findings to inform PRD creation and avoid re-analyzing the same aspects.
+
+    pm_to_architect_decision: |
+      PRD complete and saved as docs/prd.md.
+      Architectural changes identified: {{yes/no}}
+      {{if yes}}: Proceeding to create architecture document for: {{specific_changes}}
+      {{if no}}: No architectural changes needed. Proceeding to validation.
+
+    architect_to_po: "Architecture complete. Save it as docs/architecture.md. Please validate all artifacts for integration safety."
+
+    po_to_sm: |
+      All artifacts validated.
+      Documentation type available: {{sharded_prd / brownfield_docs}}
+      {{if sharded}}: Use standard create-next-story task.
+      {{if brownfield}}: Use create-brownfield-story task to handle varied documentation formats.
+
+    sm_story_creation: |
+      Creating story from {{documentation_type}}.
+      {{if missing_context}}: May need to gather additional context from user during story creation.
+
+    complete: "All planning artifacts validated and development can begin. Stories will be created based on available documentation format."
+
+

package/.grimoire/development/workflows/brownfield-service.yaml

@@ -0,0 +1,246 @@
+workflow:
+  id: brownfield-service
+  name: Brownfield Service/API Enhancement
+  description: >-
+    Agent workflow for enhancing existing backend services and APIs with new features,
+    modernization, or performance improvements. Handles existing system analysis and safe integration.
+  type: brownfield
+  version: "1.0"
+  project_types:
+    - service-modernization
+    - api-enhancement
+    - microservice-extraction
+    - performance-optimization
+    - integration-enhancement
+
+  metadata:
+    elicit: true
+    confirmation_required: true
+
+  phases:
+    - phase_1: Service Analysis & Planning
+    - phase_2: Document Sharding
+    - phase_3: Development Cycle
+
+  sequence:
+    - phase: 1
+      name: Service Analysis & Planning
+      description: "Analyze existing service and create planning artifacts"
+
+    - id: architect-service-analysis
+      step: service_analysis
+      agent: architect
+      action: document-project  # task-reference
+      creates: [project-documentation.md]
+      duration_estimate: "30-60 min"
+      notes: "Review existing service documentation, codebase, performance metrics, and identify integration dependencies."
+
+    - id: pm-create-prd
+      agent: pm
+      creates: prd.md
+      uses: brownfield-prd-tmpl
+      duration_estimate: "30-60 min"
+      requires: existing_service_analysis
+      notes: "Creates comprehensive PRD focused on service enhancement with existing system analysis. SAVE OUTPUT: Copy final prd.md to your project's docs/ folder."
+
+    - id: architect-create-architecture
+      agent: architect
+      creates: architecture.md
+      uses: brownfield-architecture-tmpl
+      duration_estimate: "30-60 min"
+      requires: prd.md
+      notes: "Creates architecture with service integration strategy and API evolution planning. SAVE OUTPUT: Copy final architecture.md to your project's docs/ folder."
+
+    - id: po-validate-artifacts
+      agent: po
+      validates: all_artifacts
+      uses: po-master-checklist
+      duration_estimate: "15-30 min"
+      notes: "Validates all documents for service integration safety and API compatibility. May require updates to any document."
+
+    - id: po-delegate-fixes
+      agent: po
+      action: delegate_fixes
+      delegates_to: [analyst, pm, architect]
+      updates: any_flagged_documents
+      duration_estimate: "15-30 min"
+      condition: po_checklist_issues
+      notes: "If PO finds issues, PO delegates fixes to the relevant agent and re-validates updated documents in docs/ folder."
+
+    - phase: 2
+      name: Document Sharding
+      description: "Break down PRD and architecture into development-ready chunks"
+
+    - id: po-shard-documents
+      agent: po
+      action: shard_documents
+      creates: sharded_docs
+      duration_estimate: "15-30 min"
+      requires:
+        - prd.md
+        - architecture.md
+      notes: |
+        Shard documents for IDE development:
+        - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+        - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+        - Creates docs/prd/ and docs/architecture/ folders with sharded content
+
+    - phase: 3
+      name: Development Cycle
+      description: "Iterative story implementation with QA review"
+
+    - id: sm-create-story
+      agent: sm
+      action: create_story
+      creates: story.md
+      duration_estimate: "15-30 min"
+      requires: sharded_docs
+      repeats: for_each_epic
+      notes: |
+        Story creation cycle:
+        - SM Agent (New Chat): @sm → *create
+        - Creates next story from sharded docs
+        - Story starts in "Draft" status
+
+    - id: pm-review-draft-story
+      agent: pm
+      alternative_agent: analyst
+      action: review_draft_story
+      updates: story.md
+      duration_estimate: "10-20 min"
+      requires: story.md
+      optional: true
+      condition: user_wants_story_review
+      notes: |
+        OPTIONAL: Review and approve draft story
+        - NOTE: story-review task coming soon
+        - Review story completeness and alignment
+        - Update story status: Draft → Approved
+
+    - id: dev-implement-story
+      agent: dev
+      action: implement_story
+      creates: implementation_files
+      duration_estimate: "1-4 hours"
+      requires: story.md
+      notes: |
+        Dev Agent (New Chat): @dev
+        - Implements approved story
+        - Updates File List with all changes
+        - Marks story as "Review" when complete
+
+    - id: qa-review-implementation
+      agent: qa
+      action: review_implementation
+      updates: implementation_files
+      duration_estimate: "20-40 min"
+      requires: implementation_files
+      optional: true
+      notes: |
+        OPTIONAL: QA Agent (New Chat): @qa → review-story
+        - Senior dev review with refactoring ability
+        - Fixes small issues directly
+        - Leaves checklist for remaining items
+        - Updates story status (Review → Done or stays Review)
+
+    - id: dev-address-qa-feedback
+      agent: dev
+      action: address_qa_feedback
+      updates: implementation_files
+      requires: implementation_files
+      duration_estimate: "30-60 min"
+      condition: qa_left_unchecked_items
+      notes: |
+        If QA left unchecked items:
+        - Dev Agent (New Chat): Address remaining items
+        - Return to QA for final approval
+
+    - meta: repeat
+      target_steps: [sm-create-story, pm-review-draft-story, dev-implement-story, qa-review-implementation, dev-address-qa-feedback]
+      condition: stories_remaining
+      notes: |
+        Repeat story cycle (SM → Dev → QA) for all epic stories
+        Continue until all stories in PRD are complete
+
+    - id: po-epic-retrospective
+      agent: po
+      action: epic_retrospective
+      creates: epic-retrospective.md
+      duration_estimate: "15-30 min"
+      condition: epic_complete
+      optional: true
+      notes: |
+        OPTIONAL: After epic completion
+        - NOTE: epic-retrospective task coming soon
+        - Validate epic was completed correctly
+        - Document learnings and improvements
+
+    - meta: end
+      action: project_complete
+      notes: |
+        All stories implemented and reviewed!
+        Project development phase complete.
+        Reference: .grimoire/data/grimoire-kb.md#IDE Development Workflow
+
+  flow_diagram: |
+    ```mermaid
+    graph TD
+        A[Start: Service Enhancement] --> B[architect: analyze existing service]
+        B --> C[pm: prd.md]
+        C --> D[architect: architecture.md]
+        D --> E[po: validate with po-master-checklist]
+        E --> F{PO finds issues?}
+        F -->|Yes| G[po: delegate fixes to relevant agent]
+        F -->|No| H[po: shard documents]
+        G --> E
+
+        H --> I[sm: create story]
+        I --> J{Review draft story?}
+        J -->|Yes| K[pm/analyst: review & approve story]
+        J -->|No| L[dev: implement story]
+        K --> L
+        L --> M{QA review?}
+        M -->|Yes| N[qa: review implementation]
+        M -->|No| O{More stories?}
+        N --> P{QA found issues?}
+        P -->|Yes| Q[dev: address QA feedback]
+        P -->|No| O
+        Q --> N
+        O -->|Yes| I
+        O -->|No| R{Epic retrospective?}
+        R -->|Yes| S[po: epic retrospective]
+        R -->|No| T[Project Complete]
+        S --> T
+
+        style T fill:#90EE90
+        style H fill:#ADD8E6
+        style I fill:#ADD8E6
+        style L fill:#ADD8E6
+        style C fill:#FFE4B5
+        style D fill:#FFE4B5
+        style K fill:#F0E68C
+        style N fill:#F0E68C
+        style S fill:#F0E68C
+    ```
+
+  decision_guidance:
+    when_to_use:
+      - Service enhancement requires coordinated stories
+      - API versioning or breaking changes needed
+      - Database schema changes required
+      - Performance or scalability improvements needed
+      - Multiple integration points affected
+    when_not_to_use:
+      - New service from scratch (use greenfield-service)
+      - Frontend enhancement (use brownfield-ui)
+      - Full-stack enhancement (use brownfield-fullstack)
+      - Comprehensive technical debt audit (use brownfield-discovery)
+
+  handoff_prompts:
+    architect_to_pm: "Service analysis complete. Create comprehensive PRD with service integration strategy."
+    pm_to_architect: "PRD ready. Save it as docs/prd.md, then create the service architecture."
+    architect_to_po: "Architecture complete. Save it as docs/architecture.md. Please validate all artifacts for service integration safety."
+    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
+    complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
+
+