project-iris 0.5.1 → 0.6.0

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/construction/bolt-start.md

@@ -184,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:
@@ -306,7 +522,7 @@ For the current stage, follow the bolt type definition:
 **Required artifacts are defined by the bolt type definition file.**
 
 Each bolt type specifies its own stages and required artifacts. Refer to:
-`templates/construction/bolt-types/{bolt_type}.md`
+`.iris/aidlc/templates/construction/bolt-types/{bolt_type}.md`
 
 **If the bolt type definition specifies an artifact for a stage, you MUST create it.**
 

package/flows/aidlc/skills/inception/story-create.md

@@ -148,6 +148,121 @@ Organize stories for bolt planning:
 - **Should**: Important but not blocking (Error handling, validation)
 - **Could**: Nice to have (Advanced features, optimizations)
 
+### 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 formats:
+- Design file: https://www.figma.com/design/{file-id}/{name}?node-id={node-id}&t={token}
+- Make file: https://www.figma.com/make/{file-id}/{name}?p=f&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.
+
 ### 4b. Validate FR-to-Story Coverage (CRITICAL - HARD GATE)
 
 **⛔ HARD GATE**: Before creating story files, validate that ALL assigned FRs have stories.

package/flows/aidlc/templates/construction/ui-patterns.md

@@ -1,6 +1,35 @@
 # UI Design Guide
 
-You are building UI for a project without a designer. Your goal is to create polished, professional interfaces that users love. Think like a designer, not a developer.
+You are building UI for a project. Your goal is to create polished, professional interfaces that users love. Think like a designer, not a developer.
+
+---
+
+## Figma Design Integration
+
+**If a story has `figma_frames` (array of Figma URLs), use Figma MCP to fetch design specs and interaction flows.**
+
+### When Figma Frames Exist
+
+1. **Fetch ALL frames first** via Figma MCP before writing any code
+2. **Extract design specs** from each frame:
+   - Colors (exact hex values, opacity)
+   - Typography (font family, size, weight, line height)
+   - Spacing (padding, margins, gaps)
+   - Border radius, shadows, effects
+   - Component dimensions and states
+3. **Extract interaction flows** (prototype connections):
+   - Navigation actions (which button goes where)
+   - Overlay triggers (modals, bottom sheets, tooltips)
+   - State changes and toggle behaviors
+   - Scroll and gesture behaviors
+4. **Build an interaction map** showing the complete flow between screens
+5. **Match the design exactly** - Figma specs override the guidelines below
+6. **Implement all interactions** as defined in Figma's prototype connections
+7. **Document deviations** - if you must deviate, explain why in code comments
+
+### When No Figma Frames Exist
+
+Follow the guidelines in this document to create professional UI without a designer.
 
 ---
 

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

@@ -16,6 +16,8 @@ priority: must|should|could
 created: {YYYY-MM-DDTHH:MM:SSZ}
 assigned_bolt: null
 implemented: false
+figma_frames: []  # Optional: Array of Figma frame URLs (design specs extracted via MCP)
+interaction_flows: []  # Optional: Manual flow definition (only if Figma has no prototype connections)
 ---
 ```
 
@@ -38,6 +40,71 @@ implemented: false
 - [ ] **Given** {precondition}, **When** {action}, **Then** {expected outcome}
 - [ ] **Given** {precondition}, **When** {action}, **Then** {expected outcome}
 
+## Figma Frames
+
+{Optional: List Figma frame URLs for screens in this story.}
+
+**Figma URLs:**
+
+- {figma-frame-url-1}
+- {figma-frame-url-2}
+
+**Supported 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}`
+
+**What the Construction Agent extracts via Figma MCP:**
+
+1. **Design specs** (always available): colors, typography, spacing, components
+2. **Prototype connections** (if defined in Figma): navigation flows, overlays, transitions
+
+---
+
+## Interaction Flows (Optional - Only if Figma has no prototype)
+
+{If your Figma file has prototype connections defined, skip this section - flows are extracted automatically.}
+
+{If your Figma has designs but NO prototype connections, define interactions manually here:}
+
+```yaml
+interaction_flows:
+  - screen: {screen-name}
+    interactions:
+      - element: "{Button/Link text}"
+        action: navigate | overlay | close | submit
+        target: {destination-screen-name}
+      - element: "{Another element}"
+        action: overlay
+        target: {modal-or-bottomsheet-name}
+```
+
+**Action types:**
+
+- `navigate` - Go to another screen (replaces current)
+- `overlay` - Open modal, bottom sheet, tooltip, dropdown
+- `close` - Close current overlay / go back
+- `submit` - Form submission (may navigate on success/failure)
+
+**Example:**
+
+```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
+      - element: "Login button"
+        action: submit
+        target: dashboard  # on success
+```
+
+{If no Figma design exists at all, describe the expected screens and interactions in the Technical Notes section.}
+
 ## Technical Notes
 
 {Implementation hints, constraints, or considerations}
@@ -45,9 +112,11 @@ implemented: false
 ## Dependencies
 
 ### Requires
+
 - {Other stories this depends on, or "None"}
 
 ### Enables
+
 - {Stories that depend on this, or "None"}
 
 ## Edge Cases
@@ -60,6 +129,7 @@ implemented: false
 ## Out of Scope
 
 - {What this story does NOT cover}
+
 ```
 
 ---
@@ -99,6 +169,9 @@ priority: must
 created: 2024-12-05T10:00:00Z
 assigned_bolt: 001-auth-service
 implemented: false
+figma_frames:
+  - https://www.figma.com/design/{file-id}/{file-name}?node-id={node-id-1}&t={token}
+  - https://www.figma.com/design/{file-id}/{file-name}?node-id={node-id-2}&t={token}
 ---
 ```
 

package/lib/InstallerFactory.js

@@ -11,25 +11,29 @@ const CodexInstaller = require('./installers/CodexInstaller');
 const OpenCodeInstaller = require('./installers/OpenCodeInstaller');
 
 class InstallerFactory {
+    static _installers = null;
+
     static getInstallers() {
-        return [
-            new ClaudeInstaller(),
-            new CursorInstaller(),
-            new CopilotInstaller(),
-            new AntigravityInstaller(),
-            new WindsurfInstaller(),
-            new ClineInstaller(),
-            new RooInstaller(),
-            new KiroInstaller(),
-            new GeminiInstaller(),
-            new CodexInstaller(),
-            new OpenCodeInstaller()
-        ];
+        if (!this._installers) {
+            this._installers = [
+                new ClaudeInstaller(),
+                new CursorInstaller(),
+                new CopilotInstaller(),
+                new AntigravityInstaller(),
+                new WindsurfInstaller(),
+                new ClineInstaller(),
+                new RooInstaller(),
+                new KiroInstaller(),
+                new GeminiInstaller(),
+                new CodexInstaller(),
+                new OpenCodeInstaller()
+            ];
+        }
+        return this._installers;
     }
 
     static getInstaller(key) {
-        const installers = this.getInstallers();
-        return installers.find(i => i.key === key);
+        return this.getInstallers().find(i => i.key === key);
     }
 }
 

package/lib/analytics/env-detector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Type declarations for env-detector module
+ */
+
+/**
+ * Detect the user's shell/terminal environment
+ * @returns Shell name (zsh, bash, powershell, cmd, fish, etc.) or 'unknown'
+ */
+export function detectShell(): string;
+
+/**
+ * Check if telemetry is disabled via environment variables or CLI flag
+ * @param options - Optional overrides
+ * @returns True if telemetry should be disabled
+ */
+export function isTelemetryDisabled(options?: { noTelemetryFlag?: boolean }): boolean;

package/lib/analytics/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Type declarations for analytics index module
+ */
+
+import tracker = require('./tracker');
+export = tracker;

package/lib/analytics/machine-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Type declarations for machine-id module
+ */
+
+/**
+ * Generate a stable machine identifier
+ * @returns SHA-256 hash of salted hostname (64 hex characters)
+ */
+export function getMachineId(): string;

package/lib/analytics/tracker.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Type declarations for tracker module
+ */
+
+interface InitOptions {
+  noTelemetry?: boolean;
+}
+
+interface AnalyticsTracker {
+  /**
+   * Initialize the analytics tracker
+   * @param options - Initialization options
+   * @returns True if analytics is enabled
+   */
+  init(options?: InitOptions): boolean;
+
+  /**
+   * Track an event (fire-and-forget)
+   * @param eventName - Name of the event
+   * @param properties - Additional event properties
+   * @param waitForDelivery - Wait for event to be sent
+   * @returns Resolves when event is sent (if waitForDelivery is true)
+   */
+  track(eventName: string, properties?: Record<string, unknown>, waitForDelivery?: boolean): Promise<void> | undefined;
+
+  /**
+   * Track installer_started event
+   * @returns Resolves when event is sent
+   */
+  trackInstallerStarted(): Promise<void>;
+
+  /**
+   * Track ides_confirmed event
+   * @param ides - Array of selected IDE keys
+   * @returns Resolves when event is sent
+   */
+  trackIdesConfirmed(ides: string[]): Promise<void>;
+
+  /**
+   * Track flow_selected event
+   * @param flow - Flow key
+   * @returns Resolves when event is sent
+   */
+  trackFlowSelected(flow: string): Promise<void>;
+
+  /**
+   * Track installation_completed event
+   * @param ide - IDE key
+   * @param flow - Flow key
+   * @param durationMs - Installation duration in milliseconds
+   * @param filesCreated - Number of files created
+   */
+  trackInstallationCompleted(ide: string, flow: string, durationMs: number, filesCreated: number): void;
+
+  /**
+   * Track installation_failed event
+   * @param ide - IDE key
+   * @param errorCategory - Error category
+   * @param flow - Flow key (optional)
+   */
+  trackInstallationFailed(ide: string, errorCategory: string, flow?: string): void;
+
+  /**
+   * Check if analytics is enabled
+   */
+  isEnabled(): boolean;
+}
+
+declare const tracker: AnalyticsTracker;
+export = tracker;

package/lib/installer.js

@@ -6,6 +6,7 @@ const CLIUtils = require('./cli-utils');
 const InstallerFactory = require('./InstallerFactory');
 const { FLOWS } = require('./constants');
 const analytics = require('./analytics');
+const mcpManager = require('./mcp');
 
 // Use theme from CLIUtils for consistent styling
 const { theme } = CLIUtils;
@@ -108,6 +109,29 @@ async function installClaudeMd() {
   return true;
 }
 
+/**
+ * Configure Figma MCP for Claude Code
+ */
+async function configureFigmaMCP() {
+  const figmaProvider = mcpManager.getProvider('figma');
+
+  console.log(theme.dim('  Checking for Claude Code CLI...'));
+
+  const result = await figmaProvider.configureForClaudeCode();
+
+  if (result.success) {
+    if (result.alreadyExists) {
+      CLIUtils.displayStatus('', 'Figma MCP: already configured', 'info');
+    } else {
+      CLIUtils.displayStatus('', 'Figma MCP: configured', 'success');
+    }
+    console.log('');
+    console.log(theme.dim('  Tip: Run /mcp in Claude Code to authenticate with Figma'));
+  } else {
+    CLIUtils.displayStatus('', `Figma MCP: ${result.message}`, 'warning');
+  }
+}
+
 async function install() {
   // Initialize analytics (respects opt-out env vars)
   analytics.init();
@@ -187,9 +211,13 @@ async function install() {
   // Track flow selection (await to ensure delivery before potential cancel)
   await analytics.trackFlowSelected(selectedFlow);
 
+  // Determine total steps (5 if Claude selected for MCP option, otherwise 4)
+  const hasClaude = selectedToolKeys.includes('claude');
+  const totalSteps = hasClaude ? 5 : 4;
+
   // Step 4: Install flow files
   console.log('');
-  CLIUtils.displayStep(4, 4, `Installing ${FLOWS[selectedFlow].name} flow...`);
+  CLIUtils.displayStep(4, totalSteps, `Installing ${FLOWS[selectedFlow].name} flow...`);
 
   try {
     const filesCreated = await installFlow(selectedFlow, selectedToolKeys);
@@ -197,6 +225,25 @@ async function install() {
     // Install CLAUDE.md with quality guidelines
     await installClaudeMd();
 
+    // Step 5: MCP Integrations (only if Claude is selected)
+    if (hasClaude) {
+      console.log('');
+      CLIUtils.displayStep(5, totalSteps, 'MCP Integrations (Optional)');
+
+      const { configureFigma } = await prompts({
+        type: 'confirm',
+        name: 'configureFigma',
+        message: 'Configure Figma MCP? (enables AI to read Figma designs)',
+        initial: false
+      });
+
+      if (configureFigma) {
+        await configureFigmaMCP();
+      } else {
+        console.log(theme.dim('  Skipped MCP configuration'));
+      }
+    }
+
     // Track successful installation for each tool
     const durationMs = Date.now() - installStartTime;
     for (const toolKey of selectedToolKeys) {

package/lib/mcp/FigmaMCPProvider.js

@@ -0,0 +1,70 @@
+/**
+ * Figma MCP Provider
+ *
+ * Configures Figma MCP server for Claude Code.
+ */
+
+const { execSync } = require('child_process');
+const { FIGMA_MCP } = require('./constants');
+
+class FigmaMCPProvider {
+    constructor() {
+        this.name = 'figma';
+        this.config = FIGMA_MCP;
+    }
+
+    /**
+     * Check if Claude Code CLI is available in PATH
+     * @returns {boolean}
+     */
+    isClaudeCodeAvailable() {
+        try {
+            const cmd = process.platform === 'win32' ? 'where claude' : 'which claude';
+            execSync(cmd, { stdio: 'ignore' });
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Configure Figma MCP for Claude Code using CLI
+     * @returns {Promise<{success: boolean, message: string, alreadyExists?: boolean}>}
+     */
+    async configureForClaudeCode() {
+        if (!this.isClaudeCodeAvailable()) {
+            return {
+                success: false,
+                message: 'Claude Code CLI not found in PATH'
+            };
+        }
+
+        try {
+            const cmd = `claude mcp add ${this.config.name} --transport ${this.config.transport} --url ${this.config.url}`;
+            execSync(cmd, { stdio: 'pipe' });
+
+            return {
+                success: true,
+                message: 'Figma MCP configured for Claude Code'
+            };
+        } catch (error) {
+            const errorMessage = error.stderr ? error.stderr.toString() : error.message;
+
+            // Check if already exists
+            if (errorMessage.includes('already') || errorMessage.includes('exists')) {
+                return {
+                    success: true,
+                    message: 'Figma MCP already configured',
+                    alreadyExists: true
+                };
+            }
+
+            return {
+                success: false,
+                message: `Failed to configure: ${errorMessage.trim()}`
+            };
+        }
+    }
+}
+
+module.exports = FigmaMCPProvider;

package/lib/mcp/constants.js

@@ -0,0 +1,15 @@
+/**
+ * MCP Configuration Constants
+ */
+
+// Figma MCP server configuration
+const FIGMA_MCP = {
+    name: 'figma',
+    url: 'https://mcp.figma.com/mcp',
+    transport: 'http',
+    description: 'Figma design collaboration tool'
+};
+
+module.exports = {
+    FIGMA_MCP
+};

package/lib/mcp/index.js

@@ -0,0 +1,35 @@
+/**
+ * MCP Manager
+ *
+ * Coordinates MCP server configuration providers.
+ */
+
+const FigmaMCPProvider = require('./FigmaMCPProvider');
+
+class MCPManager {
+    constructor() {
+        this.providers = {
+            figma: new FigmaMCPProvider()
+        };
+    }
+
+    /**
+     * Get a specific MCP provider by name
+     * @param {string} name - Provider name (e.g., 'figma')
+     * @returns {FigmaMCPProvider|undefined}
+     */
+    getProvider(name) {
+        return this.providers[name];
+    }
+
+    /**
+     * Get list of available MCP provider names
+     * @returns {string[]}
+     */
+    getAvailableProviders() {
+        return Object.keys(this.providers);
+    }
+}
+
+// Export singleton instance
+module.exports = new MCPManager();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-iris",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {
@@ -56,6 +56,7 @@
   },
   "devDependencies": {
     "@semantic-release/git": "^10.0.1",
+    "@types/fs-extra": "^11.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.10.2",
     "glob": "^13.0.0",

package/scripts/bolt-complete.js

@@ -128,57 +128,18 @@
 
 const fs = require('fs-extra');
 const path = require('path');
-const yaml = require('js-yaml');
-
-// Theme colors for output
-const colors = {
-    reset: '\x1b[0m',
-    green: '\x1b[32m',
-    red: '\x1b[31m',
-    yellow: '\x1b[33m',
-    blue: '\x1b[34m',
-    dim: '\x1b[90m',
-    bright: '\x1b[1m'
-};
+const {
+    colors,
+    extractFrontmatter,
+    updateFrontmatter,
+    getTimestamp
+} = require('./lib/frontmatter-utils');
 
 // Memory bank paths (relative to project root)
 const MEMORY_BANK_DIR = 'memory-bank';
 const BOLTS_DIR = path.join(MEMORY_BANK_DIR, 'bolts');
 const INTENTS_DIR = path.join(MEMORY_BANK_DIR, 'intents');
 
-/**
- * Extract frontmatter from a markdown file
- */
-function extractFrontmatter(content) {
-    const match = content.match(/^---\n([\s\S]+?)\n---/);
-    if (!match) return null;
-
-    try {
-        return yaml.load(match[1]);
-    } catch (error) {
-        console.error(`${colors.red}Error parsing YAML frontmatter:${colors.reset}`, error.message);
-        return null;
-    }
-}
-
-/**
- * Update frontmatter in a markdown file
- */
-function updateFrontmatter(content, newFrontmatter) {
-    const match = content.match(/^---\n([\s\S]+?)\n---/);
-    if (!match) return null;
-
-    const newYaml = yaml.dump(newFrontmatter, {
-        lineWidth: -1,
-        noRefs: true,
-        quotingType: '"',
-        forceQuotes: false,
-        sortKeys: false
-    }).trim();
-
-    return `---\n${newYaml}\n---${content.slice(match[0].length)}`;
-}
-
 /**
  * Check off all acceptance criteria checkboxes in markdown content
  * Converts "- [ ]" to "- [x]" in the Acceptance Criteria section
@@ -223,16 +184,6 @@ function checkAcceptanceCriteria(content) {
     };
 }
 
-/**
- * Format timestamp as ISO 8601
- * Format: YYYY-MM-DDTHH:MM:SSZ (no milliseconds, per memory-bank.yaml convention)
- */
-function getTimestamp() {
-    const date = new Date();
-    // Format to ISO 8601 without milliseconds
-    return date.toISOString().replace(/\.\d+Z$/, 'Z');
-}
-
 /**
  * Read a bolt file and extract metadata
  */
@@ -658,7 +609,8 @@ async function boltMarkComplete(boltId, lastStage) {
 
 // CLI entry point
 const boltId = process.argv[2];
-const lastStage = process.argv['--last-stage'] || null;
+const lastStageIndex = process.argv.indexOf('--last-stage');
+const lastStage = lastStageIndex !== -1 ? process.argv[lastStageIndex + 1] : null;
 
 if (!boltId) {
     console.error(`${colors.red}Error:${colors.reset} Bolt ID required`);

package/scripts/lib/frontmatter-utils.js

@@ -0,0 +1,75 @@
+/**
+ * Shared Frontmatter Utilities
+ *
+ * Common functions for parsing and updating YAML frontmatter in markdown files.
+ * Used by bolt-complete.js and status-integrity.js scripts.
+ */
+
+const yaml = require('js-yaml');
+
+// Theme colors for CLI output
+const colors = {
+    reset: '\x1b[0m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    dim: '\x1b[90m',
+    bright: '\x1b[1m'
+};
+
+/**
+ * Extract frontmatter from a markdown file
+ * @param {string} content - Markdown file content
+ * @returns {object|null} Parsed frontmatter object or null if invalid
+ */
+function extractFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]+?)\n---/);
+    if (!match) return null;
+
+    try {
+        return yaml.load(match[1]);
+    } catch (error) {
+        console.error(`${colors.red}Error parsing YAML frontmatter:${colors.reset}`, error.message);
+        return null;
+    }
+}
+
+/**
+ * Update frontmatter in a markdown file
+ * @param {string} content - Original markdown content
+ * @param {object} newFrontmatter - New frontmatter object
+ * @returns {string|null} Updated content or null if failed
+ */
+function updateFrontmatter(content, newFrontmatter) {
+    const match = content.match(/^---\n([\s\S]+?)\n---/);
+    if (!match) return null;
+
+    const newYaml = yaml.dump(newFrontmatter, {
+        lineWidth: -1,
+        noRefs: true,
+        quotingType: '"',
+        forceQuotes: false,
+        sortKeys: false
+    }).trim();
+
+    return `---\n${newYaml}\n---${content.slice(match[0].length)}`;
+}
+
+/**
+ * Format timestamp as ISO 8601
+ * Format: YYYY-MM-DDTHH:MM:SSZ (no milliseconds, per memory-bank.yaml convention)
+ * @returns {string} ISO 8601 formatted timestamp
+ */
+function getTimestamp() {
+    const date = new Date();
+    // Format to ISO 8601 without milliseconds
+    return date.toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+module.exports = {
+    colors,
+    extractFrontmatter,
+    updateFrontmatter,
+    getTimestamp
+};

package/scripts/status-integrity.js

@@ -15,18 +15,11 @@
 
 const fs = require('fs-extra');
 const path = require('path');
-const yaml = require('js-yaml');
-
-// Theme colors for output
-const colors = {
-    reset: '\x1b[0m',
-    green: '\x1b[32m',
-    red: '\x1b[31m',
-    yellow: '\x1b[33m',
-    blue: '\x1b[34m',
-    dim: '\x1b[90m',
-    bright: '\x1b[1m'
-};
+const {
+    colors,
+    extractFrontmatter,
+    updateFrontmatter
+} = require('./lib/frontmatter-utils');
 
 // Memory bank paths (relative to project root)
 const MEMORY_BANK_DIR = 'memory-bank';
@@ -34,49 +27,6 @@ const BOLTS_DIR = path.join(MEMORY_BANK_DIR, 'bolts');
 const INTENTS_DIR = path.join(MEMORY_BANK_DIR, 'intents');
 const MAINTENANCE_LOG = path.join(MEMORY_BANK_DIR, 'maintenance-log.md');
 
-/**
- * Extract frontmatter from a markdown file
- */
-function extractFrontmatter(content) {
-    const match = content.match(/^---\n([\s\S]+?)\n---/);
-    if (!match) return null;
-
-    try {
-        return yaml.load(match[1]);
-    } catch (error) {
-        console.error(`${colors.red}Error parsing YAML frontmatter:${colors.reset}`, error.message);
-        return null;
-    }
-}
-
-/**
- * Update frontmatter in a markdown file
- */
-function updateFrontmatter(content, newFrontmatter) {
-    const match = content.match(/^---\n([\s\S]+?)\n---/);
-    if (!match) return null;
-
-    const newYaml = yaml.dump(newFrontmatter, {
-        lineWidth: -1,
-        noRefs: true,
-        quotingType: '"',
-        forceQuotes: false,
-        sortKeys: false
-    }).trim();
-
-    return `---\n${newYaml}\n---${content.slice(match[0].length)}`;
-}
-
-/**
- * Format timestamp as ISO 8601
- * Format: YYYY-MM-DDTHH:MM:SSZ (no milliseconds, per memory-bank.yaml convention)
- */
-function getTimestamp() {
-    const date = new Date();
-    // Format to ISO 8601 without milliseconds
-    return date.toISOString().replace(/\.\d+Z$/, 'Z');
-}
-
 /**
  * Read a bolt file and extract metadata
  */