project-iris 0.5.0 → 0.6.0

package/flows/aidlc/README.md

@@ -127,6 +127,7 @@ src/flows/aidlc/
 **Goal**: Complete planning and design before construction begins
 
 **Activities**:
+
 - Capture intents (high-level goals)
 - Gather requirements (functional and non-functional)
 - Assess risks (technical, business, operational)
@@ -138,6 +139,7 @@ src/flows/aidlc/
 **Command**: `/iris-inception-agent --intent="intent-name"`
 
 **Outputs**:
+
 - PRFAQ document
 - Requirements with measurement criteria
 - Risk assessment
@@ -151,6 +153,7 @@ src/flows/aidlc/
 **Goal**: Build working software through iterative bolt execution
 
 **Activities**:
+
 - Execute bolts through DDD stages:
   1. **Domain Design** - Model business logic using DDD principles
   2. **Logical Design** - Apply NFRs and architectural patterns
@@ -161,6 +164,7 @@ src/flows/aidlc/
 **Command**: `/iris-construction-agent --unit="unit-name"`
 
 **Outputs**:
+
 - Domain design documents
 - Logical design documents
 - Architectural Decision Records (ADRs)
@@ -172,6 +176,7 @@ src/flows/aidlc/
 **Goal**: Deploy and operate the system
 
 **Activities**:
+
 - Build deployment artifacts (containers, functions, bundles)
 - Deploy through environments (Dev → Staging → Production)
 - Verify deployments with health checks
@@ -181,6 +186,7 @@ src/flows/aidlc/
 **Command**: `/iris-operations-agent --unit="unit-name"`
 
 **Outputs**:
+
 - Deployment units
 - Monitoring dashboards
 - Alert configurations
@@ -192,19 +198,24 @@ src/flows/aidlc/
 ## Project Scenarios
 
 ### Greenfield (New Projects)
+
 Starting fresh with no existing code:
+
 1. Initialize project with standards
 2. Begin Inception phase immediately
 3. Build from scratch using AI-DLC methodology
 
 ### Brownfield (Existing Codebases)
+
 Adding features to existing code:
+
 1. Initialize project with standards
 2. **Run code elevation** to analyze existing codebase
 3. AI creates static and dynamic models for context
 4. Begin Inception with full codebase understanding
 
 **Code Elevation Process**:
+
 - **Static Model**: Components, responsibilities, and relationships
 - **Dynamic Model**: How components interact for significant use cases
 
@@ -227,6 +238,7 @@ Intent (feature/capability)
 **Bolts** are time-boxed execution sessions scoped to a **Unit**. A Unit may require multiple Bolts to complete all its Stories.
 
 **Example**:
+
 - **Intent**: User Authentication
   - **Unit**: Auth Service
     - **Story 1**: User Registration
@@ -385,21 +397,27 @@ memory-bank/
 ## Key Principles
 
 ### 1. AI Drives, Human Validates
+
 AI proposes plans, decompositions, and implementations. Humans review and approve at checkpoints.
 
 ### 2. Human Oversight as Loss Function
+
 Validation at each step catches errors early before they cascade downstream.
 
 ### 3. Mob Elaboration
+
 Concentrated rapid planning during Inception. Complete all planning in hours, not weeks.
 
 ### 4. Bolts are Flexible
+
 Bolts take "hours or days" depending on complexity - not fixed-duration like sprints.
 
 ### 5. DDD Focus
+
 Domain-Driven Design principles guide the Construction phase with proper separation of concerns.
 
 ### 6. Persistent Context
+
 Everything is stored in the memory bank so context is never lost between sessions.
 
 ---
@@ -457,18 +475,21 @@ Here's a complete workflow for building a feature:
 ## Tips for Success
 
 ### Planning (Inception)
+
 - Be thorough - it pays off during Construction
 - Document NFRs with measurable criteria
 - Assess risks early with mitigations
 - Group related stories into the same bolt
 
 ### Building (Construction)
+
 - Follow the DDD stages in order
 - Don't skip testing
 - Keep bolts focused (5-8 stories max)
 - Document significant decisions as ADRs
 
 ### Deploying (Operations)
+
 - Always deploy to staging first
 - Run smoke tests after every deployment
 - Setup monitoring from the start

package/flows/aidlc/agents/README.md

@@ -15,9 +15,11 @@ agents/
 ## Agent Overview
 
 ### Master Agent
+
 **Role**: Orchestrator & Navigator
 
 The central entry point that:
+
 - Initializes new projects with standards
 - Analyzes current project state
 - Routes users to the appropriate phase agent
@@ -31,9 +33,11 @@ The central entry point that:
 ---
 
 ### Inception Agent
+
 **Role**: Planning & Design Specialist
 
 Handles the Inception phase:
+
 - Captures intents (high-level goals)
 - Gathers requirements (functional and non-functional)
 - Identifies risks
@@ -49,9 +53,11 @@ Handles the Inception phase:
 ---
 
 ### Construction Agent
+
 **Role**: Builder & Implementer
 
 Handles the Construction phase:
+
 - Executes bolts through DDD stages
 - Guides domain design
 - Creates logical designs
@@ -64,6 +70,7 @@ Handles the Construction phase:
 **Command**: `/iris-construction-agent --unit="unit-name"`
 
 **DDD Bolt Stages**:
+
 1. Domain Design
 2. Logical Design
 3. ADR Analysis (optional)
@@ -73,9 +80,11 @@ Handles the Construction phase:
 ---
 
 ### Operations Agent
+
 **Role**: DevOps Engineer & Deployment Orchestrator
 
 Handles the Operations phase:
+
 - Builds deployment artifacts
 - Deploys through environments (Dev → Staging → Production)
 - Verifies deployments
@@ -120,22 +129,28 @@ Each agent file follows this structure:
 ## Key Principles
 
 ### 1. Agent Independence
+
 Each agent operates independently but can redirect to other agents when appropriate:
+
 - Master → Inception (when ready to plan)
 - Master → Construction (when ready to build)
 - Inception → Construction (when inception complete)
 - Construction → Operations (when construction complete)
 
 ### 2. Human Validation
+
 All agents implement checkpoints where they pause for human approval before proceeding with significant actions.
 
 ### 3. Context Loading
+
 Agents load context from the memory bank at startup:
+
 - Standards (tech-stack, coding-standards)
 - Current phase state
 - Relevant artifacts
 
 ### 4. Consistent Output
+
 All agents follow the same output formatting rules defined in Mandatory Output Rules.
 
 ## Phase Flow

package/flows/aidlc/agents/inception-agent.md

@@ -9,6 +9,7 @@ You are the **Inception Agent** for AI-DLC (AI-Driven Development Life Cycle).
 ### ⛔ CRITICAL: NO ASCII TABLES
 
 **NEVER use ASCII box tables like this - FORBIDDEN:**
+
 ```
 ┌────────┬─────────────────────────────────────┐
 │ Option │            Description              │
@@ -20,6 +21,7 @@ You are the **Inception Agent** for AI-DLC (AI-Driven Development Life Cycle).
 ```
 
 **ALWAYS use numbered list format instead:**
+
 ```
 1 - **Option A** - Some option description
 2 - **Option B** - Another option description
@@ -44,6 +46,7 @@ This applies to ALL questions, options, and choices throughout the entire incept
 When asking clarifying questions with multiple choice options:
 
 **WRONG** - ASCII table:
+
 ```
 ┌────────┬──────────────────────────────────┐
 │ Option │           Description            │
@@ -55,6 +58,7 @@ When asking clarifying questions with multiple choice options:
 ```
 
 **CORRECT** - Numbered list:
+
 ```
 **Content Depth**
 
@@ -66,11 +70,13 @@ When asking clarifying questions with multiple choice options:
 ### Checkpoint Options Format (CRITICAL)
 
 **WRONG** - Open-ended question:
+
 ```
 Do these requirements capture your intent?
 ```
 
 **CORRECT** - Numbered options:
+
 ```
 ### Options
 

package/flows/aidlc/agents/master-agent.md

@@ -99,6 +99,7 @@ No project configuration found. This appears to be a new project.
 ```
 
 **CRITICAL**: When user selects "Initialize project", the `project-init` skill MUST:
+
 1. Ask project type question FIRST (full-stack, backend, frontend, CLI, library)
 2. Then detect/ask scenario (greenfield/brownfield/hybrid)
 3. Save `project.yaml` with BOTH fields before proceeding to standards

package/flows/aidlc/memory-bank.yaml

@@ -67,6 +67,27 @@ naming:
     example: "001-user-signup.md"
     note: "3-digit story number + kebab-case story title"
     full_path_example: "memory-bank/intents/001-user-authentication/units/001-auth-service/stories/001-user-signup.md"
+    optional_fields:
+      figma_frames:
+        description: "Optional array of Figma frame URLs for UI stories"
+        type: "array of URLs"
+        formats:
+          - "https://www.figma.com/design/{file-id}/{file-name}?node-id={node-id}&t={token}"
+          - "https://www.figma.com/make/{file-id}/{file-name}?p=f&t={token}"
+        note: "Construction Agent uses Figma MCP to fetch design specs. Prototype connections extracted if available."
+        collected_by: "Inception Agent during story creation (Step 4a in story-create skill)"
+      interaction_flows:
+        description: "Manual interaction flow definition (fallback when Figma has no prototype)"
+        type: "array of screen interaction definitions"
+        structure: |
+          - screen: {screen-name}
+            interactions:
+              - element: "{Button/Link text}"
+                action: navigate | overlay | close | submit
+                target: {destination-screen}
+        note: "Only needed if Figma file has designs but no prototype connections. Construction Agent uses this to wire navigation."
+        collected_by: "Inception Agent during story creation (Step 4a-2 in story-create skill)"
+        priority: "Figma prototype > interaction_flows > infer from labels > ask user"
 
   bolts:
     format: "{BBB}-{unit-name}/"

package/flows/aidlc/skills/README.md

@@ -83,18 +83,23 @@ Every skill file follows this structure:
 ## Key Principles
 
 ### 1. Mandatory Output Rules
+
 Every skill starts with formatting rules to ensure consistent output:
+
 - Never use ASCII tables (they break at different terminal widths)
 - Always use numbered list format for options
 - Always use status indicators (✅ ⏳ [ ] 🚫)
 
 ### 2. Human Checkpoints
+
 Skills that make significant decisions include checkpoints where the AI pauses for human validation before proceeding.
 
 ### 3. Artifact Creation
+
 Skills that create artifacts reference templates from `../templates/` and follow the schema defined in `../memory-bank.yaml`.
 
 ### 4. Context Loading
+
 Skills load context as defined in `../context-config.yaml` to ensure consistent information access.
 
 ## Adding New Skills

package/flows/aidlc/skills/construction/bolt-list.md

@@ -32,10 +32,12 @@
 When referencing bolt files to the user, ALWAYS show the **bolt ID prominently**, not just "bolt.md":
 
 **WRONG**:
+
 - "Working on bolt.md"
 - "Open bolt.md to see details"
 
 **CORRECT**:
+
 - "Working on **001-extension-foundation**"
 - "Open **001-extension-foundation/bolt.md** to see details"
 
@@ -46,6 +48,7 @@ The bolt ID (directory name like `001-extension-foundation`) is the identifier.
 ## Checkpoints
 
 **Checkpoint 1**: Which bolt to work on?
+
 - Wait for: User selection
 
 ---

package/flows/aidlc/skills/construction/bolt-start.md

@@ -44,11 +44,13 @@
 When referencing bolt files to the user, ALWAYS show the **bolt ID prominently**, not just "bolt.md":
 
 **WRONG**:
+
 - "Working on bolt.md"
 - "Updating bolt.md status"
 - "Approve changes to bolt.md?"
 
 **CORRECT**:
+
 - "Working on **001-extension-foundation**"
 - "Updating **001-extension-foundation** status"
 - "Approve changes to **001-extension-foundation/bolt.md**?"
@@ -155,6 +157,7 @@ agents:
 **Check if UI design guidance may be relevant:**
 
 Scan the bolt's unit name, story titles, and story descriptions for these signals:
+
 - `screen`, `page`, `view`, `layout`
 - `component`, `widget`, `button`, `form`, `modal`, `dialog`
 - `ui`, `ux`, `frontend`, `presentation`
@@ -181,6 +184,222 @@ Scan the bolt's unit name, story titles, and story descriptions for these signal
 
 This is not a hard requirement - use judgment on which principles apply to the current task.
 
+### 4c. Figma Frames (Conditional - Per Story)
+
+**Check each story's `figma_frames` field in frontmatter.**
+
+If a story has `figma_frames` (array of Figma URLs), use Figma MCP to fetch design specs and interaction flows before implementing.
+
+**Supported Figma URL formats:**
+
+- Design file: `https://www.figma.com/design/{file-id}/{file-name}?node-id={node-id}&t={token}`
+- Make file: `https://www.figma.com/make/{file-id}/{file-name}?p=f&t={token}`
+
+**When `figma_frames` is present:**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FIGMA FRAMES DETECTED                                       │
+│                                                              │
+│  Story: {story-id}                                          │
+│  Frames: {count} Figma frame(s)                             │
+│                                                              │
+│  Action: Use Figma MCP to fetch design and flow data        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Figma MCP Integration:**
+
+Use the Figma MCP tool to read design specifications. The MCP server is configured via:
+`claude mcp add figma --transport http --url https://mcp.figma.com/mcp`
+
+### 4c-1. Extract Design Specs (Per Frame)
+
+For EACH Figma frame URL, extract:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  DESIGN SPECS EXTRACTION                                     │
+│                                                              │
+│  For each frame, extract:                                    │
+│                                                              │
+│  1. Layout & Structure                                       │
+│     - Component hierarchy (parent/child relationships)       │
+│     - Spacing values (padding, margins, gaps)                │
+│     - Alignment and positioning                              │
+│                                                              │
+│  2. Visual Styling                                           │
+│     - Colors (exact hex values, opacity)                     │
+│     - Typography (font family, size, weight, line height)    │
+│     - Border radius, shadows, effects                        │
+│                                                              │
+│  3. Component States                                         │
+│     - Default, hover, active, disabled, focus states         │
+│     - Loading states and skeletons                           │
+│     - Error and success states                               │
+│                                                              │
+│  4. Responsive Variants (if defined)                         │
+│     - Mobile, tablet, desktop variations                     │
+│     - Breakpoint-specific layouts                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 4c-2. Extract Interaction Flows
+
+**Figma prototype connections MAY define interaction flows - but many designs don't have them.**
+
+**Step 1: Check for prototype connections via Figma MCP**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  PROTOTYPE CONNECTION CHECK                                  │
+│                                                              │
+│  Query Figma MCP for prototype data on each frame.           │
+│  Prototype connections include:                              │
+│  - Navigation triggers (which element → which frame)         │
+│  - Transition types (push, overlay, swap)                    │
+│  - Overlay settings (dismiss on click outside, etc.)         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Step 2: Determine flow source (in priority order)**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FLOW SOURCE PRIORITY                                        │
+│                                                              │
+│  1. Figma prototype connections (if they exist)              │
+│     → Extract automatically from Figma MCP                   │
+│                                                              │
+│  2. Manual flow definition in story (if provided)            │
+│     → Read from story's `interaction_flows` field            │
+│                                                              │
+│  3. No flow information available                            │
+│     → Ask user OR infer from button labels                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 4c-2a. If Prototype Connections Exist in Figma
+
+Extract interaction data:
+
+- Navigation actions (which element → destination frame)
+- Overlay triggers (modals, bottom sheets, tooltips)
+- Transition types and animations
+- Dismiss behaviors
+
+### 4c-2b. If NO Prototype Connections in Figma
+
+**Check story for manual `interaction_flows` definition:**
+
+```yaml
+# In story frontmatter or body
+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 manual flows exist:** Use them to build the interaction map.
+
+**If NO flows defined anywhere:**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  NO INTERACTION FLOW DEFINED                                 │
+│                                                              │
+│  Story: {story-id}                                          │
+│  Figma frames: {count} (no prototype connections found)     │
+│  Manual flows: Not defined                                   │
+│                                                              │
+│  Options:                                                    │
+│  1 - Define interactions now (I'll ask about each button)   │
+│  2 - Infer from button labels (best guess)                  │
+│  3 - Implement as static screens (no navigation wiring)     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Option 1 - Define interactions:** Ask user about each interactive element:
+
+```text
+I found these interactive elements in the Figma frames:
+- "Sign Up" button
+- "Forgot Password" link
+- "Login" button
+
+For each element, what should happen on click?
+```
+
+**Option 2 - Infer from labels:** Make reasonable assumptions:
+
+- "Submit", "Save", "Login" → form submission
+- "Cancel", "Close", "X" → close/go back
+- "Sign Up", "Register" → navigate to registration
+- "Learn More", "View Details" → navigate to detail screen
+
+**Option 3 - Static screens:** Implement visuals only, user wires navigation later.
+
+### 4c-2c. Output: Interaction Map
+
+After determining flows (from any source), build the interaction map:
+
+```markdown
+### Interaction Map: {story-id}
+
+**Flow Source:** {Figma prototype | Manual definition | Inferred | Static}
+
+#### Screen: {frame-name-1}
+| Element | Action | Target | Type |
+|---------|--------|--------|------|
+| "Sign Up" button | on-click | registration-form | navigate |
+| "Forgot Password" link | on-click | forgot-password-modal | overlay |
+
+#### Navigation Flow
+
+    login-screen
+    ├── "Sign Up" → registration-form
+    ├── "Forgot Password" → forgot-password-modal (overlay)
+    └── "Login" → dashboard (on success)
+```
+
+### 4c-3. If Figma MCP is not available
+
+```text
+⚠️ Figma MCP not configured - cannot fetch design specs
+   Story {story-id} has figma_frames but Figma MCP is unavailable.
+
+   Options:
+   1 - Continue using ui-patterns.md guidelines (design may not match)
+   2 - Stop and configure Figma MCP first
+
+   To configure: Run `claude mcp add figma --transport http --url https://mcp.figma.com/mcp`
+   Then authenticate via `/mcp` in Claude Code.
+```
+
+### 4c-4. Design-First Implementation Rule
+
+When a story has `figma_frames`:
+
+1. **Fetch ALL frames FIRST** before writing any UI code
+2. **Build the interaction map** to understand the complete flow
+3. **Extract exact values** - don't approximate colors, spacing, or typography
+4. **Match the design** - Figma specs override ui-patterns.md defaults
+5. **Implement navigation** - wire up all interactions as defined in Figma
+6. **Note deviations** - if you must deviate from design, document why in code comments
+
+**When NO `figma_frames` exists:**
+
+Fall back to ui-patterns.md guidelines (Step 4b). The agent should generate UI based on:
+
+1. Acceptance criteria in the story
+2. Project's ux-guide.md (component library, styling approach)
+3. ui-patterns.md design principles
+
 ### 5. Determine Current Stage
 
 Based on bolt state:
@@ -300,19 +519,12 @@ For the current stage, follow the bolt type definition:
    - Template used: {yes/no}
 ```
 
-**Common artifacts by bolt type:**
+**Required artifacts are defined by the bolt type definition file.**
 
-| Bolt Type | Stage | Required Artifact |
-|-----------|-------|-------------------|
-| simple-construction | Plan | `implementation-plan.md` |
-| simple-construction | Code Generation | `implementation-walkthrough.md` |
-| simple-construction | Testing | `test-walkthrough.md` |
-| ddd-construction | Domain Design | `ddd-01-domain-design.md` |
-| ddd-construction | Logical Design | `ddd-02-logical-design.md` |
-| ddd-construction | Code Generation | `ddd-04-implementation-walkthrough.md` |
-| ddd-construction | Testing | `ddd-03-test-report.md` |
+Each bolt type specifies its own stages and required artifacts. Refer to:
+`.iris/aidlc/templates/construction/bolt-types/{bolt_type}.md`
 
-**If bolt type specifies an artifact, you MUST create it.**
+**If the bolt type definition specifies an artifact for a stage, you MUST create it.**
 
 ### 7b. Story-by-Story Execution (Code Generation Stages) - HARD GATE
 

package/flows/aidlc/skills/inception/requirements.md

@@ -7,6 +7,7 @@
 ### ⛔ CRITICAL: NO ASCII TABLES
 
 **NEVER use ASCII box tables like this - FORBIDDEN:**
+
 ```
 ┌────────┬─────────────────────────────────────┐
 │ Option │            Description              │
@@ -16,12 +17,14 @@
 ```
 
 **ALWAYS use numbered list format instead:**
+
 ```
 1 - **Option A** - Some option description
 2 - **Option B** - Another option description
 ```
 
 ### General Rules
+
 - 🚫 **NEVER** use ASCII tables (┌─┬─┐ style) for ANY purpose
 - 🚫 **NEVER** use letter options (A, B, C) - always use numbers (1, 2, 3)
 - ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
@@ -33,6 +36,7 @@
 - ⚠️ **ALWAYS** show numbered options at checkpoints - NEVER ask "approve?" without options
 
 ### Functional Requirements Rules
+
 - ✅ **ALWAYS** start with user/goal clarification before listing FRs
 - ✅ **ALWAYS** include User Story format: "As a {user}, I want {action} so that {benefit}"
 - ✅ **ALWAYS** include testable Acceptance Criteria (binary pass/fail)
@@ -40,6 +44,7 @@
 - ✅ **ALWAYS** identify dependencies between FRs
 
 ### Non-Functional Requirements Rules
+
 - ✅ **ALWAYS** walk through ALL 5 NFR categories (Performance, Scalability, Security, Reliability, Compliance)
 - ✅ **ALWAYS** ensure NFRs have measurable metrics (not vague)
 - ✅ **ALWAYS** define SLOs for critical requirements

package/flows/aidlc/skills/inception/review.md

@@ -119,6 +119,7 @@ Intent → Requirements → Units → Stories → Bolts
    - [ ] Bolt dependencies respect story dependencies
 
 **Validation Outcome:**
+
 - ✅ = Complete traceability
 - ⚠️ = Partial traceability (gaps identified)
 - ❌ = Broken traceability (must fix before Construction)