gaia-framework 1.58.0 → 1.58.2

package/_gaia/lifecycle/templates/api-documentation-template.md

@@ -0,0 +1,112 @@
+---
+template: 'api-documentation'
+version: 1.0.0
+used_by: ['brownfield-onboarding']
+---
+
+# API Documentation: {product_name}
+
+> **Project:** {project_name}
+> **Date:** {date}
+> **Author:** {agent_name}
+> **Mode:** Brownfield — discovered from codebase scan
+
+## 1. API Overview
+
+{Brief description of the API layer: framework used, routing approach, middleware stack, versioning strategy.}
+
+## 2. OpenAPI Spec Status
+
+| Item | Status |
+|------|--------|
+| Existing OpenAPI/Swagger spec found | {Yes / No} |
+| Spec location | {path or N/A} |
+| Spec version | {OpenAPI 2.0 / 3.0 / 3.1 / N/A} |
+| Validation result | {Valid / Stale — X endpoints missing / N/A} |
+| Generated from code scan | {Yes — needs manual review / No — existing spec used} |
+
+## 3. Swagger/OpenAPI Specification
+
+{If an existing spec was found, include validated/updated version here.}
+{If no spec exists, generate an OpenAPI 3.x spec from route definitions, types/DTOs, and middleware.}
+{Flag generated specs with: "Generated from code scan — needs manual review."}
+
+```yaml
+openapi: 3.0.3
+info:
+  title: "{product_name} API"
+  version: "{api_version}"
+paths:
+  {generated_or_discovered_paths}
+components:
+  schemas:
+    {generated_or_discovered_schemas}
+```
+
+## 4. Endpoint Inventory
+
+| Method | Path | Handler | Auth | Description | Status |
+|--------|------|---------|------|-------------|--------|
+| {GET/POST/...} | {/api/resource} | {handler_name} | {auth_type} | {description} | {Documented / Undocumented} |
+
+## 5. Request/Response Schemas
+
+### 5.1 {Resource Name}
+
+**Request:**
+```json
+{request_schema}
+```
+
+**Response:**
+```json
+{response_schema}
+```
+
+## 6. Authentication & Authorization
+
+| Aspect | Implementation |
+|--------|---------------|
+| Auth strategy | {JWT / OAuth2 / API Key / Session / None} |
+| Token location | {Header / Cookie / Query param} |
+| Role-based access | {Yes — roles listed / No} |
+| Rate limiting | {Yes — config / No} |
+
+## 7. Error Response Format
+
+```json
+{
+  "error": {
+    "code": "{error_code}",
+    "message": "{error_message}",
+    "details": "{additional_context}"
+  }
+}
+```
+
+{Describe the standard error format used across the API. Note any inconsistencies.}
+
+## 8. API Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Middleware
+    participant Router
+    participant Handler
+    participant Database
+
+    Client->>Middleware: HTTP Request
+    Middleware->>Middleware: {Auth / Validation / Logging}
+    Middleware->>Router: Validated Request
+    Router->>Handler: Route Match
+    Handler->>Database: Query/Command
+    Database-->>Handler: Result
+    Handler-->>Client: HTTP Response
+```
+
+## 9. Undocumented Endpoints (Gaps)
+
+| Method | Path | Issue | Recommended Action |
+|--------|------|-------|-------------------|
+| {method} | {path} | {Missing docs / Missing validation / No error handling} | {action} |

package/_gaia/lifecycle/templates/architecture-template.md

@@ -0,0 +1,65 @@
+---
+template: 'architecture'
+version: 1.0.0
+used_by: ['create-architecture']
+---
+
+# Architecture Document: {product_name}
+
+> **Project:** {project_name}
+> **Date:** {date}
+> **Author:** {agent_name}
+
+## 1. System Overview
+
+{High-level description of the system and its purpose.}
+
+## 2. Architecture Decisions
+
+| ID | Decision | Rationale | Status |
+|----|----------|-----------|--------|
+| ADR-01 | {decision} | {why} | Accepted |
+
+## 3. System Components
+
+### 3.1 {Component Name}
+
+- **Responsibility:** {what it does}
+- **Technology:** {stack/framework}
+- **Interfaces:** {APIs or protocols exposed}
+
+## 4. Data Architecture
+
+### Data Model
+
+{Key entities and their relationships.}
+
+### Data Flow
+
+{How data moves through the system.}
+
+## 5. Integration Points
+
+| System | Protocol | Direction | Purpose |
+|--------|----------|-----------|---------|
+| {system} | {REST/gRPC/etc} | {in/out/both} | {purpose} |
+
+## 6. Infrastructure
+
+{Deployment topology, environments, scaling approach.}
+
+## 7. Security Architecture
+
+{Authentication, authorization, data protection approach.}
+
+## 8. Cross-Cutting Concerns
+
+- **Logging:** {approach}
+- **Monitoring:** {approach}
+- **Error handling:** {approach}
+
+## 9. Risks and Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|-----------|-----------|
+| {risk} | {H/M/L} | {H/M/L} | {mitigation} |

package/_gaia/lifecycle/templates/brownfield-architecture-template.md

@@ -0,0 +1,198 @@
+---
+template: 'brownfield-architecture'
+version: 1.0.0
+used_by: ['brownfield-onboarding']
+---
+
+# Architecture Document: {product_name}
+
+> **Project:** {project_name}
+> **Date:** {date}
+> **Author:** {agent_name}
+> **Mode:** Brownfield — as-is discovered, target proposed for gaps
+
+## 1. System Overview
+
+{High-level description of the system: purpose, domain, scale, deployment model. Summarize what was discovered during project scan.}
+
+## 2. Architecture Decisions
+
+| ID | Decision | Rationale | Status | Source |
+|----|----------|-----------|--------|--------|
+| ADR-01 | {decision} | {why} | {Existing / Proposed} | {discovered from code / proposed for gaps} |
+
+## 3. As-Is System Architecture
+
+### System Context (C4 Level 1)
+
+```mermaid
+C4Context
+    title System Context Diagram — {product_name}
+
+    Person(user, "{User Role}", "{User description}")
+    System(system, "{product_name}", "{System description}")
+    System_Ext(ext1, "{External System 1}", "{Description}")
+
+    Rel(user, system, "Uses")
+    Rel(system, ext1, "Calls", "{protocol}")
+```
+
+### Container Diagram (C4 Level 2)
+
+```mermaid
+C4Container
+    title Container Diagram — {product_name}
+
+    Person(user, "{User Role}")
+
+    Container_Boundary(app, "{product_name}") {
+        Container(frontend, "{Frontend}", "{technology}", "{description}")
+        Container(backend, "{Backend}", "{technology}", "{description}")
+        ContainerDb(db, "{Database}", "{technology}", "{description}")
+    }
+
+    System_Ext(ext1, "{External System}")
+
+    Rel(user, frontend, "Uses", "HTTPS")
+    Rel(frontend, backend, "Calls", "{protocol}")
+    Rel(backend, db, "Reads/Writes", "{protocol}")
+    Rel(backend, ext1, "Calls", "{protocol}")
+```
+
+## 4. Key System Flows
+
+{Document 3-5 key flows using Mermaid sequence diagrams. Focus on the most important or complex flows.}
+
+### Flow 1: {Flow Name}
+
+```mermaid
+sequenceDiagram
+    participant {Actor}
+    participant {Component1}
+    participant {Component2}
+    participant {Component3}
+
+    {Actor}->>+{Component1}: {action}
+    {Component1}->>+{Component2}: {action}
+    {Component2}->>+{Component3}: {action}
+    {Component3}-->>-{Component2}: {response}
+    {Component2}-->>-{Component1}: {response}
+    {Component1}-->>-{Actor}: {response}
+```
+
+### Flow 2: {Flow Name}
+
+```mermaid
+sequenceDiagram
+    {sequence_diagram_content}
+```
+
+### Flow 3: {Flow Name}
+
+```mermaid
+sequenceDiagram
+    {sequence_diagram_content}
+```
+
+## 5. Data Architecture
+
+### Current Data Model
+
+{Describe key entities, their relationships, and storage locations.}
+
+| Entity | Storage | Key Fields | Relationships |
+|--------|---------|-----------|---------------|
+| {entity} | {table/collection} | {key fields} | {relations} |
+
+### Data Flow Diagram
+
+```mermaid
+flowchart LR
+    subgraph Input
+        UI[User Interface]
+        API[API Clients]
+        EVT[Event Sources]
+    end
+
+    subgraph Processing
+        SVC["{Service Layer}"]
+    end
+
+    subgraph Storage
+        DB[("Primary DB")]
+        CACHE[("Cache")]
+        SEARCH[("Search Index")]
+    end
+
+    UI --> SVC
+    API --> SVC
+    EVT --> SVC
+    SVC --> DB
+    SVC --> CACHE
+    SVC --> SEARCH
+```
+
+## 6. Integration Architecture
+
+{Cross-reference the detailed documentation:}
+
+- **API layer:** See [API Documentation](api-documentation.md) for full endpoint inventory and OpenAPI spec
+- **Event architecture:** See [Event Catalog](event-catalog.md) for producer/consumer mapping
+- **External dependencies:** See [Dependency Map](dependency-map.md) for service contracts and SLAs
+
+### Integration Summary
+
+| Integration | Type | Protocol | Direction | Documentation |
+|------------|------|----------|-----------|--------------|
+| {integration} | {API / Event / DB / File} | {REST / gRPC / Kafka / etc.} | {In / Out / Both} | {link to detailed doc} |
+
+## 7. Infrastructure & Deployment
+
+| Aspect | Current State |
+|--------|--------------|
+| Hosting | {cloud provider / on-prem / hybrid} |
+| Containerization | {Docker / Kubernetes / none} |
+| CI/CD | {pipeline description} |
+| Environments | {dev / staging / prod} |
+| Scaling model | {horizontal / vertical / fixed} |
+| CDN | {provider or none} |
+
+## 8. Security Architecture
+
+| Layer | Implementation |
+|-------|---------------|
+| Authentication | {mechanism and provider} |
+| Authorization | {RBAC / ABAC / custom} |
+| Data encryption | {at rest / in transit / both / none} |
+| Secrets management | {vault / env vars / config files} |
+| API security | {rate limiting / CORS / CSP} |
+
+## 9. Cross-Cutting Concerns
+
+| Concern | Current Implementation | Gaps |
+|---------|----------------------|------|
+| Logging | {framework / approach} | {gaps if any} |
+| Monitoring | {tools / dashboards} | {gaps if any} |
+| Error handling | {strategy / patterns} | {gaps if any} |
+| Configuration | {env vars / config files / feature flags} | {gaps if any} |
+| Internationalization | {i18n approach or none} | {gaps if any} |
+
+## 10. Target Architecture (Gaps)
+
+{Describe architectural changes needed to close the gaps identified in the PRD.}
+
+### Target vs. As-Is Delta
+
+| Area | As-Is | Target | Change Required |
+|------|-------|--------|----------------|
+| {area} | {current state} | {desired state} | {what needs to change} |
+
+### Migration Strategy
+
+{How to get from as-is to target. Sequence of changes, risk mitigation, rollback plan.}
+
+## 11. Risks and Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|-----------|-----------|
+| {risk} | {High / Medium / Low} | {High / Medium / Low} | {mitigation strategy} |

package/_gaia/lifecycle/templates/brownfield-assessment-template.md

@@ -0,0 +1,78 @@
+---
+template: 'brownfield-assessment'
+version: 1.0.0
+used_by: ['brownfield-onboarding']
+---
+
+# Brownfield Assessment: {product_name}
+
+> **Project:** {project_name}
+> **Date:** {date}
+> **Author:** {agent_name}
+> **Mode:** Brownfield — system assessment and migration planning
+
+## 1. As-Is System Architecture
+
+{High-level description of the current system architecture, including key components, data flows, and integration points.}
+
+### Component Inventory
+
+| Component | Technology | Status | Maintainability |
+|-----------|-----------|--------|-----------------|
+| {component} | {tech stack} | {Active / Legacy / Deprecated} | {High / Medium / Low} |
+
+### Architecture Diagram
+
+{Mermaid C4 Level 1 context diagram of current system}
+
+## 2. Technical Debt Inventory
+
+| Debt Item | Category | Severity | Effort to Resolve | Business Impact |
+|-----------|----------|----------|--------------------|-----------------|
+| {description} | {Code / Architecture / Infrastructure / Testing / Documentation} | {Critical / High / Medium / Low} | {S / M / L / XL} | {What breaks or degrades if not addressed} |
+
+### Debt Severity Summary
+
+| Severity | Count | Recommended Action |
+|----------|-------|--------------------|
+| Critical | {n} | Must resolve before new feature work |
+| High | {n} | Resolve within current quarter |
+| Medium | {n} | Schedule for debt sprint |
+| Low | {n} | Address opportunistically |
+
+## 3. Migration Constraints & Risks
+
+| Constraint | Impact | Mitigation |
+|-----------|--------|------------|
+| {Data migration: schema differences, volume, downtime window} | {What goes wrong if violated} | {Strategy to handle} |
+| {API compatibility: consumers that depend on current contracts} | {Breaking change impact} | {Versioning / adapter strategy} |
+| {Infrastructure: environments, deployment pipeline, secrets} | {What needs to change} | {Phased approach} |
+| {Regulatory: compliance, audit trail, data residency} | {Non-negotiable constraints} | {How to maintain compliance} |
+
+## 4. Coexistence Strategy
+
+{How will new code and legacy code run together during the transition period?}
+
+| Aspect | Strategy | Duration |
+|--------|----------|----------|
+| Routing | {Feature flags / API gateway / URL-based / header-based} | {Until full migration} |
+| Data | {Dual-write / sync / migration batches / shared DB} | {Until cutover} |
+| Auth | {Shared session / token federation / unified IdP} | {Permanent or transitional} |
+| Monitoring | {Unified dashboards / separate but linked} | {Until consolidation} |
+
+## 5. Incremental Adoption Path
+
+| Phase | Scope | Success Criteria | Rollback Plan |
+|-------|-------|-----------------|---------------|
+| 1 | {First migration slice — lowest risk} | {Metrics that confirm success} | {How to revert} |
+| 2 | {Second slice — medium complexity} | {Metrics} | {Revert strategy} |
+| 3 | {Final migration — legacy decommission} | {Metrics} | {Point of no return considerations} |
+
+## 6. Assessment Summary
+
+| Area | Current State | Risk Level | Key Action |
+|------|--------------|------------|------------|
+| Architecture | {summary} | {High / Medium / Low} | {primary recommendation} |
+| Technical Debt | {X critical, Y high items} | {High / Medium / Low} | {debt resolution timeline} |
+| Migration Risk | {summary} | {High / Medium / Low} | {mitigation priority} |
+| Coexistence | {strategy chosen} | {High / Medium / Low} | {implementation approach} |

package/_gaia/lifecycle/templates/brownfield-onboarding-template.md

@@ -0,0 +1,160 @@
+---
+template: 'brownfield-onboarding'
+version: 1.0.0
+used_by: ['brownfield-onboarding']
+---
+
+# Developer Knowledge Base: {product_name}
+
+> **Project:** {project_name}
+> **Date:** {date}
+> **Author:** {agent_name}
+> **Mode:** Brownfield onboarding — complete developer reference
+
+## 1. Quick Start
+
+{Get the project running in 5 minutes.}
+
+### Prerequisites
+
+- {runtime and version}
+- {package manager}
+- {required services: database, cache, etc.}
+
+### Setup
+
+```bash
+# Clone and install
+{clone_command}
+{install_command}
+
+# Configure environment
+{env_setup_steps}
+
+# Start development
+{start_command}
+```
+
+### Verify
+
+```bash
+# Run tests to confirm setup
+{test_command}
+```
+
+## 2. Project Overview
+
+{2-3 paragraph summary of what this project does, who uses it, and its current state.}
+
+**Full documentation:** [Project Documentation](project-documentation.md)
+
+## 3. Architecture Overview
+
+{Summary of the system architecture: components, how they connect, key design decisions.}
+
+**Key architectural patterns:** {list the main patterns: MVC, microservices, event-driven, etc.}
+
+**Full documentation:** [Architecture Document](architecture.md)
+
+## 4. API Reference
+
+{Summary of the API layer: number of endpoints, main resource groups, auth approach.}
+
+| Resource Group | Endpoints | Auth Required |
+|---------------|-----------|---------------|
+| {group} | {count} | {yes/no} |
+
+**Full documentation:** [API Documentation](api-documentation.md)
+
+## 5. UX & Frontend Patterns
+
+{Summary of UI framework, component library, key patterns. Skip this section if no frontend.}
+
+**Full documentation:** [UX Design Assessment](ux-design.md)
+
+## 6. Event Architecture
+
+{Summary of messaging infrastructure: system used, key events, producers/consumers. Skip if no events.}
+
+**Full documentation:** [Event Catalog](event-catalog.md)
+
+## 7. External Dependencies
+
+{Summary of what external services and infrastructure the project depends on.}
+
+**Full documentation:** [Dependency Map](dependency-map.md)
+
+## 8. Code Quality & NFR Baselines
+
+{Summary of current quality state: test coverage, linting, security, performance.}
+
+| Category | Current State | Target |
+|----------|--------------|--------|
+| {category} | {state} | {target} |
+
+**Full documentation:** [NFR Assessment](nfr-assessment.md)
+
+## 9. Brownfield Assessment
+
+{Summary of as-is architecture, technical debt severity, migration constraints, and coexistence strategy.}
+
+**Full documentation:** [Brownfield Assessment](brownfield-assessment.md)
+
+## 10. Gap Analysis & Roadmap
+
+{Summary of identified gaps between current state and desired state. Key priorities.}
+
+**Full documentation:** [Product Requirements (Gaps)](prd.md)
+
+## 11. Stories for Development
+
+{Summary of epics and story count. Current sprint focus.}
+
+| Epic | Stories | Priority |
+|------|---------|----------|
+| {epic_name} | {count} | {P0-P3} |
+
+**Full documentation:** [Epics and Stories](epics-and-stories.md)
+
+## 12. Conventions & Patterns
+
+### Code Conventions
+
+- **Naming:** {conventions for files, functions, variables, components}
+- **File structure:** {how code is organized: by feature, by layer, etc.}
+- **Import order:** {convention if any}
+- **Error handling:** {pattern used}
+
+### Git Conventions
+
+- **Branch naming:** {pattern}
+- **Commit messages:** {format}
+- **PR process:** {description}
+
+### Testing Conventions
+
+- **Test location:** {co-located / separate test dir}
+- **Naming pattern:** {*.test.ts / *.spec.ts / etc.}
+- **Required coverage:** {threshold if configured}
+- **Test types used:** {unit / integration / e2e}
+
+## 13. Key Files & Entry Points
+
+| File | Purpose |
+|------|---------|
+| {main entry point} | {Application bootstrap} |
+| {config file} | {Primary configuration} |
+| {route definitions} | {API/page routing} |
+| {database config} | {Database connection and migrations} |
+| {test config} | {Test framework configuration} |
+| {CI config} | {Build and deploy pipeline} |
+
+## Reading Order for New Developers
+
+1. **Start here** — Read this onboarding document
+2. **Understand the system** — Read [Architecture](architecture.md) for the big picture
+3. **Know the APIs** — Read [API Documentation](api-documentation.md) if working on backend
+4. **Know the UI** — Read [UX Design](ux-design.md) if working on frontend
+5. **Understand quality bar** — Read [NFR Assessment](nfr-assessment.md) for coding standards
+6. **See what's planned** — Read [PRD](prd.md) and [Stories](epics-and-stories.md)
+7. **Pick a story** — Start with a small gap story to learn the codebase

package/_gaia/lifecycle/templates/dependency-map-template.md

@@ -0,0 +1,73 @@
+---
+template: 'dependency-map'
+version: 1.0.0
+used_by: ['brownfield-onboarding']
+---
+
+# Dependency Map: {product_name}
+
+> **Project:** {project_name}
+> **Date:** {date}
+> **Author:** {agent_name}
+> **Mode:** Brownfield — discovered from codebase scan
+
+## 1. External Service Dependencies
+
+| Service | Purpose | Protocol | Auth | Health Check | Error Handling |
+|---------|---------|----------|------|-------------|----------------|
+| {service_name} | {what it provides} | {REST / gRPC / GraphQL} | {API key / OAuth / mTLS} | {endpoint or N/A} | {retry / circuit breaker / fallback} |
+
+## 2. Infrastructure Dependencies
+
+| Component | Technology | Version | Purpose | Configuration |
+|-----------|-----------|---------|---------|---------------|
+| Database | {PostgreSQL / MySQL / MongoDB / etc.} | {version} | {primary data store / cache / etc.} | {config path} |
+| Cache | {Redis / Memcached / etc.} | {version} | {session / query cache / etc.} | {config path} |
+| Search | {Elasticsearch / Solr / etc.} | {version} | {full-text search / analytics} | {config path} |
+| Storage | {S3 / GCS / local / etc.} | {N/A} | {file uploads / static assets} | {config path} |
+
+## 3. Key Library Dependencies
+
+| Library | Version | Current Latest | Purpose | CVE Risk |
+|---------|---------|---------------|---------|----------|
+| {library_name} | {installed_version} | {latest_version} | {ORM / Auth / State mgmt / etc.} | {None / CVE-XXXX-XXXX} |
+
+## 4. Dependency Graph
+
+```mermaid
+flowchart TD
+    subgraph Application
+        APP["{product_name}"]
+    end
+
+    subgraph "External Services"
+        SVC1["{Service 1}"]
+        SVC2["{Service 2}"]
+    end
+
+    subgraph Infrastructure
+        DB[("Database")]
+        CACHE[("Cache")]
+        MQ[("Message Queue")]
+    end
+
+    APP --> SVC1
+    APP --> SVC2
+    APP --> DB
+    APP --> CACHE
+    APP --> MQ
+```
+
+## 5. Contracts & SLAs
+
+| Dependency | Contract Type | SLA | Fallback Strategy |
+|-----------|--------------|-----|-------------------|
+| {dependency_name} | {REST API / Event schema / DB schema} | {uptime / latency target} | {degrade gracefully / fail fast / cached fallback} |
+
+## 6. Risks & Recommendations
+
+| Risk | Severity | Affected Dependency | Recommendation |
+|------|----------|-------------------|----------------|
+| {Version out of date} | {High / Medium / Low} | {dependency} | {upgrade path} |
+| {No health check} | {Medium} | {dependency} | {add circuit breaker} |
+| {Single point of failure} | {High} | {dependency} | {add redundancy} |