project-iris 0.6.6 → 0.6.8

package/flows/aidlc/skills/construction/refs/story-execution.md

@@ -0,0 +1,167 @@
+# Story-by-Story Execution Pattern
+
+This sub-skill defines the sequential story execution loop for code generation stages.
+
+---
+
+## 7b. Story-by-Story Execution (Code Generation Stages) - HARD GATE
+
+**⛔ HARD GATE - SEQUENTIAL STORY EXECUTION REQUIRED**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY-BY-STORY EXECUTION - NON-NEGOTIABLE                  │
+│                                                              │
+│  ⛔ FORBIDDEN: Implementing multiple stories at once         │
+│  ⛔ FORBIDDEN: Skipping story file reads                     │
+│  ⛔ FORBIDDEN: Not updating stories_progress in bolt file    │
+│                                                              │
+│  You MUST process stories ONE AT A TIME in sequence.         │
+│  Each story requires its own announce → read → implement →   │
+│  update cycle. Batch implementation = broken traceability.   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**For EACH story in bolt's stories array, execute this exact sequence:**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY EXECUTION LOOP (repeat for each story)               │
+│                                                              │
+│  STEP A: Announce start                                      │
+│  Output: "⏳ Story {n}/{total}: {story-id} - {title}"       │
+│                                                              │
+│  STEP B: Read story file (MANDATORY)                         │
+│  Action: Read {intent}/units/{unit}/stories/{story-id}.md   │
+│  Purpose: Extract acceptance criteria for implementation     │
+│                                                              │
+│  STEP C: Implement code for THIS story only                  │
+│  Action: Create/modify code to satisfy acceptance criteria   │
+│  Add traceability: // Story: {story-id}                      │
+│                                                              │
+│  STEP D: Update bolt file stories_progress (MANDATORY)       │
+│  Action: Edit bolt.md to mark story progress                 │
+│                                                              │
+│  STEP E: Update story FILE status (MANDATORY)                │
+│  Action: Edit story file frontmatter                         │
+│  Path: {intent}/units/{unit}/stories/{story-id}.md           │
+│  Update: status: {current} → implemented                     │
+│  ⚠️ This is the STORY FILE, not bolt.md                     │
+│                                                              │
+│  STEP F: Announce completion                                 │
+│  Output: "✅ Story {story-id}: Implemented → `{files}`"     │
+│                                                              │
+│  STEP G: Show updated progress list                          │
+│  Then proceed to next story (back to STEP A)                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Story Progress Display (show after EACH story completion):**
+
+```markdown
+### Story Progress ({completed}/{total})
+
+1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+3. ⏳ **{SSS}-{story-slug}**: In Progress
+4. [ ] **{SSS}-{story-slug}**: Pending
+5. [ ] **{SSS}-{story-slug}**: Pending
+6. [ ] **{SSS}-{story-slug}**: Pending
+```
+
+### 7b-1. Story File Update (HARD GATE)
+
+**⛔ HARD GATE - STORY FILE UPDATE REQUIRED AFTER EACH STORY**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY FILE UPDATE - NON-NEGOTIABLE                          │
+│                                                              │
+│  After implementing code for a story, you MUST:              │
+│  1. Use Edit tool to update the STORY FILE (not bolt.md)     │
+│  2. Change frontmatter: status: {current} → implemented      │
+│  3. Verify the edit was applied                              │
+│                                                              │
+│  Path: {intent}/units/{unit}/stories/{story-id}.md           │
+│                                                              │
+│  ⛔ FORBIDDEN: Moving to next story without updating file    │
+│  ⛔ FORBIDDEN: Only updating bolt.md, not story file         │
+│  ⛔ FORBIDDEN: Batch updating at stage end                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Story status values during code generation:**
+
+- `draft` / `generated` / `approved` → Initial status (varies)
+- `implemented` → After code is written for this story
+
+**Verification Output (after each story file update):**
+
+```text
+✅ Story file updated: {story-id}.md
+   - status: {old-status} → implemented
+```
+
+### 7b-2. Bolt File Update (After Story File)
+
+**Update bolt file after EACH story (not at the end):**
+
+```yaml
+stories_progress:
+  - id: 001-database-init
+    status: complete
+    implemented_at: {timestamp}
+  - id: 002-schema-tables
+    status: complete
+    implemented_at: {timestamp}
+  - id: 003-crud-operations
+    status: in-progress
+  - id: 004-query-helpers
+    status: pending
+```
+
+**Why This Pattern Exists:**
+
+1. **Traceability**: Each piece of code maps to a specific story
+2. **Resumability**: If interrupted, we know exactly where to continue
+3. **Verification**: We can validate that ALL stories were addressed
+4. **Visibility**: User sees clear progress through the work
+5. **Quality**: Reading acceptance criteria prevents missed requirements
+
+## 7c. Final Regression Check (After All Stories Implemented)
+
+**⛔ REQUIRED: After implementing all stories, verify no regressions**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  REGRESSION CHECK - BEFORE STAGE CHECKPOINT                  │
+│                                                              │
+│  After ALL stories are implemented, you MUST verify:         │
+│  1. Re-read acceptance criteria from FIRST story             │
+│  2. Verify the implementation still satisfies those ACs      │
+│  3. Repeat for each story in order                           │
+│  4. Report any regressions found                             │
+│                                                              │
+│  Later stories may have broken earlier implementations.      │
+│  Catch this BEFORE moving to Testing stage.                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Regression Check Output:**
+
+```text
+### Regression Check ({stories_count} stories)
+
+1. ✅ **{story-1}**: All ACs still valid
+2. ✅ **{story-2}**: All ACs still valid
+3. ⚠️ **{story-3}**: AC2 regression - {description} → FIX REQUIRED
+4. ✅ **{story-4}**: All ACs still valid
+
+{If regressions found: Fix before proceeding to checkpoint}
+```
+
+**Why This Check Exists:**
+
+- Story N implementation may modify shared code
+- Changes could invalidate Story 1-N-1 acceptance criteria
+- Catching regressions early prevents cascade failures in Testing stage

package/flows/aidlc/skills/inception/refs/figma-story-refs.md

@@ -0,0 +1,119 @@
+# Figma Reference Collection for Stories
+
+This sub-skill handles collecting Figma frame URLs and interaction flows during story creation.
+
+---
+
+## 4a. Collect Figma References (UI Stories Only)
+
+**For stories that involve UI screens, ask the user for Figma frame URLs.**
+
+**Detection:** Check if the story involves UI by looking for these signals in the user story or acceptance criteria:
+
+- Screen, page, view, layout
+- Form, button, modal, dialog, bottom sheet
+- Navigation, menu, sidebar
+- Component, widget, card, table
+
+**If UI signals detected:**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FIGMA REFERENCE COLLECTION                                  │
+│                                                              │
+│  Story: {story-id} - {title}                                │
+│  UI Detected: {signal found}                                │
+│                                                              │
+│  Do you have Figma designs for this story?                  │
+│                                                              │
+│  1 - Yes, I'll provide Figma frame URLs                     │
+│  2 - No, use ui-patterns.md guidelines                      │
+│  3 - Skip for now (add later)                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**If user selects "Yes":**
+
+```text
+Please provide Figma frame URLs for this story.
+You can provide multiple URLs (one per screen/component).
+
+Supported format:
+- Design file: https://www.figma.com/design/{file-id}/{name}?node-id={node-id}&t={token}
+
+Enter URLs (one per line, empty line to finish):
+```
+
+**Store in story frontmatter:**
+
+```yaml
+figma_frames:
+  - https://www.figma.com/design/xxx/Project?node-id=1:100&t=abc
+  - https://www.figma.com/design/xxx/Project?node-id=1:200&t=abc
+```
+
+**If user selects "No" or "Skip":**
+
+Leave `figma_frames: []` in frontmatter. Construction Agent will use ui-patterns.md guidelines.
+
+**Batch Collection Option:**
+
+If multiple UI stories are being created, offer batch collection:
+
+```text
+I detected {n} stories with UI components. Would you like to:
+
+1 - Provide Figma URLs for each story individually
+2 - Provide a single Figma file URL (I'll ask which frames map to which stories)
+3 - Skip Figma references for all (use ui-patterns.md)
+```
+
+## 4a-2. Collect Interaction Flows (If No Prototype in Figma)
+
+**After collecting Figma URLs, ask about prototype connections:**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  INTERACTION FLOW CHECK                                      │
+│                                                              │
+│  Does your Figma file have prototype connections defined?    │
+│  (Click interactions that link frames together)              │
+│                                                              │
+│  1 - Yes, prototype is set up in Figma                      │
+│  2 - No, I'll define interactions manually                  │
+│  3 - Not sure / I'll handle it during construction          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**If user selects "No" (manual definition):**
+
+```text
+Let's define the interactions for each screen.
+
+For screen: {screen-name} (from Figma frame)
+
+What interactive elements are on this screen?
+(List buttons, links, or other clickable elements)
+
+For each element, I'll ask:
+- What action does it trigger? (navigate, overlay, close, submit)
+- What is the target? (destination screen name)
+```
+
+**Store in story frontmatter:**
+
+```yaml
+interaction_flows:
+  - screen: login-form
+    interactions:
+      - element: "Sign Up button"
+        action: navigate
+        target: registration-form
+      - element: "Forgot Password link"
+        action: overlay
+        target: forgot-password-modal
+```
+
+**If user selects "Yes" or "Not sure":**
+
+Leave `interaction_flows: []` - Construction Agent will extract from Figma or ask during implementation.

package/flows/aidlc/skills/inception/refs/measurement-criteria.md

@@ -0,0 +1,123 @@
+# Measurement Criteria, SLOs, and Trade-offs
+
+This sub-skill covers Steps 4-6 of requirements discovery: SLOs, measurement criteria, and trade-off documentation.
+
+---
+
+## Step 4: Define SLOs
+
+Based on NFR answers, define Service Level Objectives:
+
+```markdown
+## Service Level Objectives (SLOs)
+
+Based on your requirements, here are the proposed SLOs:
+
+### Availability SLO
+- **Indicator**: % of successful requests (non-5xx)
+- **Target**: {X}% over 30-day window
+- **Error Budget**: {Y} minutes/month
+
+### Latency SLO
+- **Indicator**: Response time at p95
+- **Target**: < {X}ms
+- **Scope**: All API endpoints
+
+### Error Rate SLO
+- **Indicator**: % of failed requests
+- **Target**: < {X}%
+- **Window**: 24-hour rolling
+
+Do these SLOs align with your expectations?
+1 - **Yes**: Continue
+2 - **Adjust**: Modify targets
+```
+
+---
+
+## Step 5: Define Measurement Criteria (AI-DLC Requirement)
+
+**Per AI-DLC specification, Measurement Criteria must trace to the business intent.**
+
+Unlike technical SLOs, Measurement Criteria capture business-level success indicators.
+
+```markdown
+## Measurement Criteria
+
+Measurement Criteria trace back to the business intent and help validate whether the feature delivers expected value.
+
+### Business Outcome Metrics
+
+1. **Primary Success Metric**: What single metric best indicates this feature is successful?
+   - Metric: ___
+   - Current baseline (if known): ___
+   - Target: ___
+   - Measurement method: ___
+
+2. **User Adoption Metrics**:
+   - Expected active users: ___
+   - Feature usage frequency: ___
+   - Time to first value: ___
+
+3. **Business Impact Metrics**:
+   - Revenue impact (if applicable): ___
+   - Cost reduction (if applicable): ___
+   - Efficiency gain (if applicable): ___
+
+### Leading Indicators
+What early signals will indicate we're on track?
+- ___
+- ___
+
+### Lagging Indicators
+What will confirm long-term success?
+- ___
+- ___
+
+### Measurement Timeline
+- **Week 1-2**: {Early indicators to monitor}
+- **Month 1**: {Short-term success criteria}
+- **Quarter 1**: {Long-term validation}
+```
+
+**Wait for user input on key metrics.**
+
+**After receiving answers, document in requirements.md:**
+
+```markdown
+## Measurement Criteria
+
+### Primary Success Metric
+- **Metric**: {metric name}
+- **Baseline**: {current state}
+- **Target**: {goal}
+- **Measurement**: {how to measure}
+
+### Business Traceability
+| Metric | Business Goal | FR/NFR Link |
+|--------|---------------|-------------|
+| {Metric 1} | {Which business goal it validates} | FR-1, FR-2 |
+| {Metric 2} | {Which business goal it validates} | NFR-P1 |
+```
+
+---
+
+## Step 6: Document Trade-offs
+
+If requirements conflict, document trade-offs:
+
+```markdown
+## Requirements Trade-offs
+
+I've identified these trade-offs in your requirements:
+
+### Trade-off 1: {e.g., Performance vs Security}
+- **Conflict**: {Description}
+- **Options**:
+  1 - {Option A with implications}
+  2 - {Option B with implications}
+- **Recommendation**: {Your recommendation}
+- **Your decision**: ___
+
+{Repeat for other trade-offs}
+```

package/flows/aidlc/skills/inception/refs/nfr-categories.md

@@ -0,0 +1,144 @@
+# NFR Category Discovery Questions
+
+Walk through each NFR category one at a time with the user. Wait for response after each category before proceeding to the next.
+
+---
+
+## Category 1/5: Performance
+
+```markdown
+## NFR Category 1/5: Performance
+
+1. **Response Time**: What's acceptable for main operations?
+   - 1 - Fast (< 100ms) - Real-time feel
+   - 2 - Standard (< 500ms) - Typical web app
+   - 3 - Tolerant (< 2s) - Complex operations
+   - 4 - Specify custom target
+
+2. **Throughput**: Expected request volume?
+   - Requests per second: ___
+   - Peak vs normal ratio: ___
+
+3. **Latency-sensitive operations**: Any operations needing special attention?
+
+Your answers (or 'skip' if not applicable):
+```
+
+**Wait for response, then continue to next category.**
+
+## Category 2/5: Scalability
+
+```markdown
+## NFR Category 2/5: Scalability
+
+1. **Current Load**:
+   - Expected daily active users: ___
+   - Peak concurrent users: ___
+   - Data volume (records): ___
+
+2. **Growth** (next 12 months):
+   - 1 - Low (< 2x growth)
+   - 2 - Medium (2-5x growth)
+   - 3 - High (5-10x growth)
+   - 4 - Hyper (> 10x growth)
+
+3. **Scaling Strategy**:
+   - 1 - Horizontal (add instances)
+   - 2 - Vertical (larger instances)
+   - 3 - Auto-scaling (dynamic)
+   - 4 - Need recommendation
+
+Your answers:
+```
+
+**Wait for response.**
+
+## Category 3/5: Security
+
+```markdown
+## NFR Category 3/5: Security
+
+1. **Authentication**:
+   - 1 - OAuth 2.0 / OIDC (social/enterprise SSO)
+   - 2 - JWT (stateless tokens)
+   - 3 - Session-based (traditional)
+   - 4 - API Keys (service-to-service)
+   - 5 - None (public access)
+   - 6 - Inherit from project standards
+
+2. **Authorization**:
+   - 1 - RBAC (role-based)
+   - 2 - ABAC (attribute-based)
+   - 3 - Simple (admin/user)
+   - 4 - None needed
+
+3. **Data Sensitivity**:
+   - 1 - Public (no sensitive data)
+   - 2 - Internal (business data)
+   - 3 - Confidential (PII, financial)
+   - 4 - Regulated (HIPAA, PCI-DSS)
+
+4. **Encryption**:
+   - At rest required? (yes/no)
+   - In transit required? (yes/no, default: yes)
+
+Your answers:
+```
+
+**Wait for response.**
+
+## Category 4/5: Reliability
+
+```markdown
+## NFR Category 4/5: Reliability
+
+1. **Availability Target**:
+   - 1 - 99.0% (~3.6 days downtime/year) - Internal tools
+   - 2 - 99.9% (~8.7 hours/year) - Standard apps
+   - 3 - 99.95% (~4.4 hours/year) - Business critical
+   - 4 - 99.99% (~52 min/year) - Mission critical
+
+2. **Recovery**:
+   - RTO (time to recover): ___
+   - RPO (acceptable data loss): ___
+
+3. **Failure Handling**:
+   - Graceful degradation needed? (yes/no)
+   - Which features can degrade?
+
+4. **Backup**:
+   - Frequency: ___
+   - Retention period: ___
+
+Your answers:
+```
+
+**Wait for response.**
+
+## Category 5/5: Compliance
+
+```markdown
+## NFR Category 5/5: Compliance
+
+1. **Regulatory Requirements** (select all that apply):
+   - 1 - GDPR (EU data protection)
+   - 2 - HIPAA (healthcare - US)
+   - 3 - PCI-DSS (payment cards)
+   - 4 - SOC 2 (service controls)
+   - 5 - SOX (financial - US)
+   - 6 - None specific
+   - 7 - Other: ___
+
+2. **Audit Requirements**:
+   - Audit logging needed? (yes/no)
+   - Log retention period: ___
+   - Immutable logs required? (yes/no)
+
+3. **Data Residency**:
+   - Geographic restrictions? (yes/no)
+   - Allowed regions: ___
+
+Your answers:
+```
+
+**Wait for response.**

package/flows/aidlc/skills/inception/refs/risk-categories.md

@@ -0,0 +1,134 @@
+# Risk Category-by-Category Review
+
+Present risks by category for user validation. Wait for response after each category before proceeding.
+
+---
+
+## Category 1/5: Technical Risks
+
+```markdown
+## Technical Risks Review
+
+These risks relate to technology choices, architecture, and implementation:
+
+### RISK-T1: {Title}
+{Full risk details as above}
+
+### RISK-T2: {Title}
+{Full risk details as above}
+
+---
+
+**Validation Questions:**
+1. Are there other technical risks I should consider?
+2. Are the impact/likelihood scores accurate?
+3. Are the mitigation strategies realistic?
+
+### Options
+
+1 - **Approve** - Continue to next category
+2 - **Add risk** - Identify additional technical risks
+3 - **Revise** - Request changes to scores or mitigations
+```
+
+**Wait for response, then continue to next category.**
+
+## Category 2/5: Business Risks
+
+```markdown
+## Business Risks Review
+
+These risks relate to business value, adoption, and market factors:
+
+### RISK-B1: {Title}
+{Full risk details}
+
+---
+
+**Validation Questions:**
+1. Are there business risks I've missed?
+2. Any concerns about the business impact scoring?
+
+### Options
+
+1 - **Approve** - Continue to next category
+2 - **Add risk** - Identify additional business risks
+3 - **Revise** - Request changes to impact scoring
+```
+
+**Wait for response.**
+
+## Category 3/5: Operational Risks
+
+```markdown
+## Operational Risks Review
+
+These risks relate to deployment, monitoring, and support:
+
+### RISK-O1: {Title}
+{Full risk details}
+
+---
+
+**Validation Questions:**
+1. Are deployment/operational risks accurately captured?
+2. Any gaps in the mitigation strategies?
+
+### Options
+
+1 - **Approve** - Continue to next category
+2 - **Add risk** - Identify additional operational risks
+3 - **Revise** - Request changes to mitigations
+```
+
+**Wait for response.**
+
+## Category 4/5: External Risks
+
+```markdown
+## External Risks Review
+
+These risks relate to third-party dependencies and external factors:
+
+### RISK-E1: {Title}
+{Full risk details}
+
+---
+
+**Validation Questions:**
+1. Are all third-party dependencies covered?
+2. Any vendor-specific concerns I should add?
+
+### Options
+
+1 - **Approve** - Continue to next category
+2 - **Add risk** - Identify additional external risks
+3 - **Revise** - Request changes to vendor risks
+```
+
+**Wait for response.**
+
+## Category 5/5: Compliance Risks
+
+```markdown
+## Compliance Risks Review
+
+These risks relate to regulatory, legal, and audit requirements:
+
+### RISK-C1: {Title}
+{Full risk details}
+
+---
+
+**Validation Questions:**
+1. Are regulatory requirements fully addressed?
+2. Any compliance gaps I've missed?
+
+### Options
+
+1 - **Approve** - Proceed to full risk register review
+2 - **Add risk** - Identify additional compliance risks
+3 - **Revise** - Request changes to regulatory coverage
+```
+
+**Wait for response.**