project-iris 0.0.16 → 0.0.18

package/flows/aidlc/templates/construction/elevation-dynamic-model-template.md

@@ -0,0 +1,265 @@
+# Dynamic Model Template
+
+Use this template when documenting the dynamic model during code elevation for brownfield projects.
+
+---
+
+## Frontmatter
+
+```yaml
+---
+project: {project-name}
+type: dynamic-model
+scenario: brownfield
+created: {YYYY-MM-DDTHH:MM:SSZ}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+use_cases_count: {N}
+integration_points_count: {N}
+---
+```
+
+---
+
+## Content
+
+```markdown
+# Dynamic Model: {Project Name}
+
+## Overview
+
+- **Use Cases Documented**: {N}
+- **Integration Points Identified**: {N}
+- **Critical Paths Traced**: {N}
+- **Related Static Model**: `memory-bank/elevation/static-model.md`
+
+---
+
+## Significant Use Cases
+
+### Use Case 1: {Name}
+
+**Description**: {Brief description of what this use case accomplishes}
+
+**Trigger**: {What initiates this flow - user action, API call, scheduled job, etc.}
+
+**Actors**:
+- Primary: {e.g., User, Admin, System}
+- Secondary: {e.g., External API, Database}
+
+**Preconditions**:
+- {Condition 1: e.g., User must be authenticated}
+- {Condition 2: e.g., Resource must exist}
+
+**Interaction Sequence**:
+
+```text
+┌──────┐     1. Request      ┌───────────┐     2. Validate     ┌───────────┐
+│ User │────────────────────►│ Controller│────────────────────►│  Service  │
+└──────┘                     └───────────┘                     └───────────┘
+   ▲                                                                 │
+   │                              ┌──────────────────────────────────┘
+   │                              │ 3. Query
+   │                              ▼
+   │                        ┌───────────┐     4. SQL          ┌──────────┐
+   │                        │Repository │────────────────────►│ Database │
+   │                        └───────────┘                     └──────────┘
+   │                              │
+   │                              │ 5. Data
+   │                              ▼
+   │         6. Response    ┌───────────┐
+   └────────────────────────│  Service  │
+                            └───────────┘
+```
+
+**Step-by-Step**:
+
+| Step | Component | Action | Input | Output |
+|------|-----------|--------|-------|--------|
+| 1 | Controller | Receives HTTP request | Request body | Validated DTO |
+| 2 | Service | Validates business rules | DTO | Validated entity |
+| 3 | Repository | Queries database | Entity ID | Entity data |
+| 4 | Service | Applies business logic | Entity | Result |
+| 5 | Controller | Returns response | Result | HTTP response |
+
+**Data Flow**:
+- **Input**: `{data structure, e.g., { userId: string, action: string }}`
+- **Output**: `{data structure, e.g., { success: boolean, data: object }}`
+- **Transformations**: {How data changes through the flow}
+
+**Side Effects**:
+- {Side effect 1: e.g., Database record updated}
+- {Side effect 2: e.g., Event emitted to queue}
+- {Side effect 3: e.g., Audit log created}
+
+**Error Scenarios**:
+| Error | Handled By | Response |
+|-------|------------|----------|
+| Validation failure | Controller | 400 Bad Request |
+| Not found | Service | 404 Not Found |
+| Unauthorized | Middleware | 401 Unauthorized |
+| Server error | Error handler | 500 Internal Error |
+
+---
+
+### Use Case 2: {Name}
+
+**Description**: {Brief description}
+
+**Trigger**: {What initiates this flow}
+
+**Actors**:
+- Primary: {actor}
+- Secondary: {actor}
+
+**Interaction Sequence**:
+
+```text
+{Diagram}
+```
+
+**Step-by-Step**:
+
+| Step | Component | Action | Input | Output |
+|------|-----------|--------|-------|--------|
+| 1 | | | | |
+
+**Data Flow**:
+- **Input**: `{structure}`
+- **Output**: `{structure}`
+
+**Side Effects**:
+- {effects}
+
+---
+
+## Integration Points
+
+### External APIs
+
+| Integration | Protocol | Direction | Endpoint | Purpose |
+|-------------|----------|-----------|----------|---------|
+| {API Name} | REST | Outbound | `{URL}` | {What it's used for} |
+| {API Name} | GraphQL | Outbound | `{URL}` | {What it's used for} |
+
+### Message Queues
+
+| Queue | Protocol | Direction | Events | Purpose |
+|-------|----------|-----------|--------|---------|
+| {Queue} | AMQP | Publish | `{event types}` | {Purpose} |
+| {Queue} | AMQP | Subscribe | `{event types}` | {Purpose} |
+
+### Databases
+
+| Database | Type | Operations | Tables/Collections |
+|----------|------|------------|-------------------|
+| {DB Name} | PostgreSQL | CRUD | `{table list}` |
+| {Cache} | Redis | Read/Write | `{key patterns}` |
+
+### File Storage
+
+| Storage | Type | Operations | Purpose |
+|---------|------|------------|---------|
+| {Storage} | S3 | Upload/Download | {Purpose} |
+
+---
+
+## Critical Paths
+
+### Happy Path: {Primary Flow Name}
+
+The most common successful path through the system:
+
+```text
+Entry → Validation → Processing → Persistence → Response
+```
+
+**Performance Characteristics**:
+- Typical latency: {e.g., < 100ms}
+- Bottlenecks: {e.g., Database query at step 3}
+
+### Error Handling Path
+
+How errors propagate through the system:
+
+```text
+Error occurs → Caught by {component} → Logged → Transformed → Returned to client
+```
+
+**Error Propagation**:
+- Domain errors: Wrapped and returned as business errors
+- Infrastructure errors: Logged, generic error returned
+- Validation errors: Returned immediately with details
+
+### Authentication Flow
+
+How authentication is handled:
+
+```text
+Request → Auth Middleware → Token Validation → User Context → Proceed/Reject
+```
+
+---
+
+## Event Flows
+
+### Events Emitted
+
+| Event | Trigger | Payload | Consumers |
+|-------|---------|---------|-----------|
+| `{event.name}` | {When emitted} | `{payload structure}` | {Who listens} |
+
+### Events Consumed
+
+| Event | Source | Handler | Side Effects |
+|-------|--------|---------|--------------|
+| `{event.name}` | {Source} | `{handler}` | {What happens} |
+
+---
+
+## Async Operations
+
+### Background Jobs
+
+| Job | Trigger | Frequency | Purpose |
+|-----|---------|-----------|---------|
+| {Job name} | {Cron/Event/Manual} | {Schedule} | {What it does} |
+
+### Long-Running Processes
+
+| Process | Duration | Checkpoints | Recovery |
+|---------|----------|-------------|----------|
+| {Process} | {Typical time} | {Checkpoint mechanism} | {How to recover} |
+
+---
+
+## Observations
+
+### Well-Designed Flows
+- {Observation 1: e.g., "Clean error handling in payment flow"}
+- {Observation 2: e.g., "Good separation of concerns in auth"}
+
+### Potential Issues
+- {Issue 1: e.g., "No retry logic for external API calls"}
+- {Issue 2: e.g., "Missing circuit breaker for payment gateway"}
+
+### Recommendations
+- {Recommendation 1: e.g., "Add retry with exponential backoff for API X"}
+- {Recommendation 2: e.g., "Consider caching for frequently accessed data"}
+```
+
+---
+
+## Quality Checklist
+
+Before marking dynamic model complete, verify:
+
+- [ ] All significant use cases documented
+- [ ] Each use case has interaction diagram
+- [ ] Step-by-step breakdown provided
+- [ ] Data flow documented (input/output/transformations)
+- [ ] Side effects identified
+- [ ] Error scenarios covered
+- [ ] Integration points mapped
+- [ ] Critical paths traced
+- [ ] Async operations documented
+- [ ] Observations and recommendations noted

package/flows/aidlc/templates/construction/elevation-static-model-template.md

@@ -0,0 +1,204 @@
+# Static Model Template
+
+Use this template when documenting the static model during code elevation for brownfield projects.
+
+---
+
+## Frontmatter
+
+```yaml
+---
+project: {project-name}
+type: static-model
+scenario: brownfield
+created: {YYYY-MM-DDTHH:MM:SSZ}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+analyzed_paths:
+  - src/
+  - lib/
+components_count: {N}
+relationships_count: {N}
+---
+```
+
+---
+
+## Content
+
+```markdown
+# Static Model: {Project Name}
+
+## Overview
+
+- **Project Type**: {e.g., backend-api, full-stack-web}
+- **Primary Language**: {e.g., TypeScript, Python, Go}
+- **Framework**: {e.g., Next.js, FastAPI, Express}
+- **Components Identified**: {N}
+- **Relationships Mapped**: {N}
+- **Analyzed Paths**: `src/`, `lib/`
+
+---
+
+## Architectural Layers
+
+### Domain Layer
+Components that contain core business logic.
+
+| Component | Location | Responsibility |
+|-----------|----------|----------------|
+| {Component} | `{path}` | {responsibility} |
+
+### Application Layer
+Components that orchestrate domain logic.
+
+| Component | Location | Responsibility |
+|-----------|----------|----------------|
+| {Component} | `{path}` | {responsibility} |
+
+### Infrastructure Layer
+Components that handle external concerns (DB, APIs, etc.).
+
+| Component | Location | Responsibility |
+|-----------|----------|----------------|
+| {Component} | `{path}` | {responsibility} |
+
+### Presentation Layer
+Components that handle user interface (if applicable).
+
+| Component | Location | Responsibility |
+|-----------|----------|----------------|
+| {Component} | `{path}` | {responsibility} |
+
+---
+
+## Components Detail
+
+### {Component 1 Name}
+
+- **Type**: {Class/Module/Service/Repository/Controller/etc.}
+- **Location**: `{file path}`
+- **Layer**: {Domain/Application/Infrastructure/Presentation}
+- **Responsibility**: {Single sentence describing what this component does}
+
+**Key Methods/Functions**:
+- `{method1}({params})`: {What it does, what it returns}
+- `{method2}({params})`: {What it does, what it returns}
+
+**Dependencies**:
+- Depends on: {List of components this depends on}
+- Used by: {List of components that use this}
+
+---
+
+### {Component 2 Name}
+
+- **Type**: {Class/Module/Service/Repository/Controller/etc.}
+- **Location**: `{file path}`
+- **Layer**: {Domain/Application/Infrastructure/Presentation}
+- **Responsibility**: {Single sentence describing what this component does}
+
+**Key Methods/Functions**:
+- `{method1}({params})`: {What it does, what it returns}
+
+**Dependencies**:
+- Depends on: {List}
+- Used by: {List}
+
+---
+
+## Relationships Diagram
+
+```text
+┌─────────────────┐     uses      ┌─────────────────┐
+│   Controller    │──────────────►│    Service      │
+└─────────────────┘               └─────────────────┘
+                                          │
+                                          │ uses
+                                          ▼
+                                  ┌─────────────────┐
+                                  │   Repository    │
+                                  └─────────────────┘
+                                          │
+                                          │ queries
+                                          ▼
+                                  ┌─────────────────┐
+                                  │    Database     │
+                                  └─────────────────┘
+```
+
+---
+
+## Dependency Graph
+
+| Component | Depends On | Used By |
+|-----------|------------|---------|
+| {Component A} | {Component B, Component C} | {Component X} |
+| {Component B} | {External: Database} | {Component A} |
+
+---
+
+## External Dependencies
+
+### Libraries/Packages
+| Package | Purpose | Version |
+|---------|---------|---------|
+| {package} | {what it's used for} | {version} |
+
+### External Services
+| Service | Type | Purpose |
+|---------|------|---------|
+| {Database} | PostgreSQL | Primary data store |
+| {Cache} | Redis | Session/cache storage |
+| {API} | REST | Third-party integration |
+
+---
+
+## Technology Stack (Detected)
+
+- **Runtime**: {Node.js, Python, Go, etc.}
+- **Framework**: {Express, FastAPI, Gin, etc.}
+- **Database Client**: {Prisma, SQLAlchemy, GORM, etc.}
+- **Authentication**: {JWT, OAuth, Session, etc.}
+- **Testing**: {Jest, Pytest, etc.}
+
+---
+
+## Key Observations
+
+### Strengths
+- {Observation 1: e.g., "Clean separation between domain and infrastructure"}
+- {Observation 2: e.g., "Consistent naming conventions"}
+
+### Areas of Concern
+- {Concern 1: e.g., "High coupling in payment module"}
+- {Concern 2: e.g., "Missing abstraction for external APIs"}
+
+### Patterns Identified
+- {Pattern 1: e.g., "Repository pattern for data access"}
+- {Pattern 2: e.g., "Service layer for business logic"}
+
+---
+
+## Recommendations for New Development
+
+When adding new features to this codebase:
+
+1. **Follow existing layer structure**: Place new code in appropriate layer
+2. **Use established patterns**: {e.g., Repository pattern for data access}
+3. **Respect naming conventions**: {e.g., PascalCase for classes, camelCase for functions}
+4. **Maintain dependency direction**: {e.g., Domain should not depend on Infrastructure}
+```
+
+---
+
+## Quality Checklist
+
+Before marking static model complete, verify:
+
+- [ ] All significant components documented
+- [ ] Each component has clear responsibility (single sentence)
+- [ ] Layer assignments are accurate
+- [ ] Relationships between components mapped
+- [ ] External dependencies identified
+- [ ] Technology stack detected
+- [ ] Key observations noted for future development

package/flows/aidlc/templates/inception/prfaq-template.md

@@ -0,0 +1,147 @@
+# PRFAQ Template
+
+Use this template when creating a PRFAQ (Press Release / FAQ) document for an intent.
+
+The PRFAQ format, popularized by Amazon, forces clarity on business value before implementation.
+
+---
+
+## Frontmatter
+
+```yaml
+---
+intent: {NNN}-{intent-name}
+phase: inception
+status: draft|complete
+created: {YYYY-MM-DDTHH:MM:SSZ}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+```
+
+---
+
+## Content
+
+```markdown
+# PRFAQ: {Intent Name}
+
+## Press Release
+
+### Headline
+{Compelling one-line announcement of the feature}
+
+### Subheadline
+{Who benefits and what's the key value proposition}
+
+### Summary Paragraph
+{City, Date} — {Company/Product Name} today announced {feature name}, a {brief description} that enables {target users} to {key benefit}. With this release, users can now {primary capability}, resulting in {measurable outcome or business value}.
+
+### Problem Statement
+{Describe the customer problem this solves. Be specific about the pain points.}
+
+"{Quote from a fictional user describing their frustration with the current state}"
+
+### Solution
+{Describe how the feature solves the problem. Focus on user benefits, not technical details.}
+
+Key capabilities include:
+- **{Capability 1}**: {Benefit to user}
+- **{Capability 2}**: {Benefit to user}
+- **{Capability 3}**: {Benefit to user}
+
+### Customer Quote
+"{Testimonial-style quote from a fictional customer describing how this feature improved their workflow or solved their problem.}"
+
+— {Fictional Customer Name}, {Role} at {Company Type}
+
+### Call to Action
+{How users can get started or learn more. What should they do next?}
+
+---
+
+## Frequently Asked Questions
+
+### Customer FAQ
+
+#### Q1: Who is this feature for?
+**A**: {Describe the primary and secondary user personas}
+
+#### Q2: What problem does this solve?
+**A**: {Explain the core pain point in user terms}
+
+#### Q3: How is this different from {alternative/competitor}?
+**A**: {Differentiation and unique value proposition}
+
+#### Q4: When will this be available?
+**A**: {Target timeline or release phase}
+
+#### Q5: What are the prerequisites or requirements?
+**A**: {Dependencies, account types, technical requirements}
+
+### Technical FAQ
+
+#### Q6: How does this integrate with existing features?
+**A**: {Integration points and compatibility}
+
+#### Q7: What are the performance characteristics?
+**A**: {Response times, throughput, scalability}
+
+#### Q8: What are the security considerations?
+**A**: {Authentication, authorization, data protection}
+
+#### Q9: What are the known limitations?
+**A**: {Scope boundaries, not-supported scenarios}
+
+#### Q10: What's on the roadmap for future iterations?
+**A**: {Planned enhancements, what's explicitly out of scope for now}
+
+---
+
+## Success Metrics
+
+| Metric | Current State | Target | Measurement Method |
+|--------|---------------|--------|-------------------|
+| {Metric 1} | {Baseline} | {Goal} | {How to measure} |
+| {Metric 2} | {Baseline} | {Goal} | {How to measure} |
+| {Metric 3} | {Baseline} | {Goal} | {How to measure} |
+
+---
+
+## Appendix: Internal Notes
+
+### Risks & Mitigations
+{Key risks identified and how they'll be addressed}
+
+### Dependencies
+{External teams, services, or features this depends on}
+
+### Open Questions
+{Unresolved questions that need answers before or during implementation}
+```
+
+---
+
+## PRFAQ Quality Checklist
+
+Before marking PRFAQ as complete, verify:
+
+- [ ] Headline is compelling and clear (< 10 words)
+- [ ] Problem statement describes real user pain
+- [ ] Solution focuses on benefits, not features
+- [ ] Customer quote sounds authentic
+- [ ] FAQ addresses likely questions from users AND technical team
+- [ ] Success metrics are measurable and have baselines
+- [ ] No technical jargon in customer-facing sections
+- [ ] Call to action is clear and actionable
+
+---
+
+## Why PRFAQ?
+
+The PRFAQ format is recommended by AI-DLC because it:
+
+1. **Forces customer-centricity**: Writing the press release first ensures you understand the user value
+2. **Clarifies scope**: The FAQ section surfaces edge cases and boundaries early
+3. **Aligns stakeholders**: Everyone reads the same "future announcement"
+4. **Measures success**: Defining metrics upfront enables validation later
+5. **Reduces rework**: Catching misalignment in a document is cheaper than in code

package/flows/aidlc/templates/inception/requirements-template.md

@@ -88,6 +88,53 @@ Note: All naming is derived from folder names. No prefix field needed.
 
 ---
 
+## Service Level Objectives (SLOs)
+
+| SLO | Indicator | Target | Window |
+|-----|-----------|--------|--------|
+| Availability | % successful requests (non-5xx) | {X}% | 30-day |
+| Latency | Response time at p95 | < {X}ms | Rolling |
+| Error Rate | % failed requests | < {X}% | 24-hour |
+
+---
+
+## Measurement Criteria (AI-DLC Required)
+
+Measurement Criteria trace back to the business intent and validate whether the feature delivers expected value.
+
+### Primary Success Metric
+- **Metric**: {metric name}
+- **Baseline**: {current state, if known}
+- **Target**: {goal}
+- **Measurement Method**: {how to measure}
+
+### Business Outcome Metrics
+| Metric | Current | Target | Timeline |
+|--------|---------|--------|----------|
+| {User adoption metric} | {baseline} | {target} | {when} |
+| {Business impact metric} | {baseline} | {target} | {when} |
+
+### Business Traceability
+| Metric | Business Goal | Linked Requirements |
+|--------|---------------|---------------------|
+| {Metric 1} | {Which business goal it validates} | FR-1, FR-2 |
+| {Metric 2} | {Which business goal it validates} | NFR-P1 |
+
+### Measurement Timeline
+- **Week 1-2**: {Early indicators to monitor}
+- **Month 1**: {Short-term success criteria}
+- **Quarter 1**: {Long-term validation}
+
+---
+
+## Trade-off Decisions
+
+| Trade-off | Options Considered | Decision | Rationale |
+|-----------|-------------------|----------|-----------|
+| {e.g., Performance vs Security} | {Option A, Option B} | {Chosen option} | {Why this choice} |
+
+---
+
 ## Constraints
 
 ### Technical Constraints
@@ -136,9 +183,27 @@ Note: All naming is derived from folder names. No prefix field needed.
 
 Before marking requirements complete, verify:
 
-- [ ] All requirements are testable (measurable, not vague)
-- [ ] Acceptance criteria are binary (pass/fail)
-- [ ] NFRs have specific metrics and targets
-- [ ] Dependencies are identified
-- [ ] Constraints are documented
+### Functional Requirements
+- [ ] All FRs have User Story format (As a..., I want..., So that...)
+- [ ] All FRs have testable Acceptance Criteria (binary pass/fail)
+- [ ] All FRs have Priority assigned (Must/Should/Could)
+- [ ] Dependencies between FRs are identified
+
+### Non-Functional Requirements
+- [ ] All 5 NFR categories addressed (Performance, Scalability, Security, Reliability, Compliance)
+- [ ] Each NFR has specific metrics and targets (not vague)
+- [ ] SLOs defined with indicators, targets, and measurement windows
+
+### Measurement Criteria (AI-DLC Required)
+- [ ] Primary success metric defined with baseline and target
+- [ ] Business traceability documented (metrics → goals → FRs)
+- [ ] Measurement timeline established (leading/lagging indicators)
+
+### Trade-offs
+- [ ] Conflicting requirements identified
+- [ ] Trade-off decisions documented with rationale
+
+### General
+- [ ] Constraints are documented (technical and business)
 - [ ] Assumptions are stated and risks assessed
+- [ ] Open questions have owners and due dates