project-iris 0.6.4 → 0.6.6

package/flows/aidlc/memory-bank.yaml

@@ -71,9 +71,7 @@ naming:
       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}"
+        format: "https://www.figma.com/design/{file-id}/{file-name}?node-id={node-id}&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:

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

@@ -190,10 +190,9 @@ This is not a hard requirement - use judgment on which principles apply to the c
 
 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:**
+**Supported Figma URL format:**
 
 - 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:**
 
@@ -383,23 +382,166 @@ After determining flows (from any source), build the interaction map:
 
 ### 4c-4. Design-First Implementation Rule
 
+**⛔ HARD GATE - UI FIDELITY ENFORCEMENT**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  UI FIDELITY - NON-NEGOTIABLE                               │
+│                                                              │
+│  ⛔ FORBIDDEN: Approximating colors (use exact hex values)  │
+│  ⛔ FORBIDDEN: Guessing spacing (use exact px/rem values)   │
+│  ⛔ FORBIDDEN: Substituting fonts (use exact font family)   │
+│  ⛔ FORBIDDEN: Changing layout structure from Figma         │
+│  ⛔ FORBIDDEN: Adding/removing elements not in design       │
+│                                                              │
+│  The implementation MUST be pixel-perfect to the Figma.     │
+│  If deviation is required, STOP and ask the user first.     │
+└─────────────────────────────────────────────────────────────┘
+```
+
 When a story has `figma_frames`:
 
-1. **Fetch ALL frames FIRST** before writing any UI code
+1. **Fetch ALL frames for THIS story 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
+3. **Extract EXACT values** from Figma MCP response:
+   - Colors: Use exact hex values (e.g., `#1A1A1A`, not "dark gray")
+   - Spacing: Use exact pixel/rem values (e.g., `16px`, not "some padding")
+   - Typography: Use exact font-family, font-size, font-weight, line-height
+   - Border radius: Use exact values (e.g., `8px`, not "rounded")
+   - Shadows: Use exact shadow values from design
+4. **Match the design exactly** - 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
+6. **If you MUST deviate** from design:
+   - STOP and ask the user first
+   - Document the deviation and reason in code comments
+   - Get explicit approval before proceeding
 
-**When NO `figma_frames` exists:**
+**Post-Implementation Fidelity Check:**
 
-Fall back to ui-patterns.md guidelines (Step 4b). The agent should generate UI based on:
+After implementing UI code, verify against Figma:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FIDELITY CHECKLIST                                          │
+│                                                              │
+│  □ Colors match exactly (compare hex values)                │
+│  □ Spacing matches exactly (padding, margin, gap)           │
+│  □ Typography matches exactly (font, size, weight)          │
+│  □ Layout structure matches (flexbox/grid arrangement)      │
+│  □ Component hierarchy matches (nesting, order)             │
+│  □ Interactive states implemented (hover, focus, active)    │
+│  □ Responsive behavior matches (if defined in Figma)        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 4c-5. When NO `figma_frames` Exists (Story-Level Collection)
+
+**⛔ HARD GATE - DO NOT SKIP FOR UI STORIES**
+
+If a story has UI signals (detected in Step 4b) but NO `figma_frames` in frontmatter:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  UI STORY WITHOUT FIGMA FRAMES                              │
+│                                                              │
+│  Story: {story-id} - {title}                                │
+│  UI Detected: {signal found}                                │
+│  Figma Frames: Not defined in story frontmatter             │
+│                                                              │
+│  Would you like to provide Figma design for THIS story?     │
+│                                                              │
+│  1 - Yes, I'll provide Figma frame URL(s) for this story   │
+│  2 - No, continue without Figma (use ui-patterns.md)       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**If user selects "Yes":**
+
+```text
+Please provide Figma frame URL(s) for story: {story-id}
+
+⚠️  IMPORTANT: Only provide frames relevant to THIS story's scope:
+    {list acceptance criteria titles from story}
+
+Supported format:
+- Design file: https://www.figma.com/design/{file-id}/{name}?node-id={node-id}&t={token}
+
+Enter URL(s) (one per line, empty line to finish):
+```
+
+**After collecting URLs:**
+
+1. Update the story file's `figma_frames` frontmatter with provided URLs
+2. Proceed with Figma MCP integration (Step 4c-1 onwards)
+
+**If user selects "No":**
+
+Fall back to ui-patterns.md guidelines (Step 4b). 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
 
+### 4c-6. Figma Scope Enforcement (CRITICAL)
+
+**⛔ HARD GATE - STORY SCOPE BOUNDARY**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FIGMA SCOPE ENFORCEMENT - NON-NEGOTIABLE                   │
+│                                                              │
+│  ⛔ FORBIDDEN: Implementing screens beyond current story    │
+│  ⛔ FORBIDDEN: Building "all screens" from a Figma file     │
+│  ⛔ FORBIDDEN: Assuming Figma file scope = story scope      │
+│                                                              │
+│  Each story has its own scope. Figma frames provided for a  │
+│  story ONLY apply to that story's acceptance criteria.      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**When user provides a Figma URL:**
+
+**Step 1: Check if URL has multiple distinct screens/frames**
+
+**Step 2: If multiple screens detected**, ask user to map them:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  MULTIPLE SCREENS DETECTED                                   │
+│                                                              │
+│  The Figma URL contains {n} distinct screens/frames.        │
+│  Current story: {story-id} - {title}                        │
+│                                                              │
+│  Which screen(s) apply to THIS story?                       │
+│                                                              │
+│  Detected frames:                                            │
+│  1. {frame-name-1} (node-id: {id})                          │
+│  2. {frame-name-2} (node-id: {id})                          │
+│  3. {frame-name-3} (node-id: {id})                          │
+│  ...                                                         │
+│                                                              │
+│  Enter frame numbers for this story (e.g., "1, 2"):         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Step 3: Only implement the selected frames** for current story
+
+**Step 4: Other frames belong to other stories** - do NOT implement them now
+
+**Scope Validation Before Implementation:**
+
+Before writing any UI code, verify:
+
+```text
+Story: {story-id}
+Acceptance Criteria: {list from story file}
+Figma Frames Selected: {list selected frames}
+
+✓ All selected frames relate to this story's acceptance criteria
+✓ No frames selected that belong to other stories
+✓ Scope is bounded to THIS story only
+```
+
 ### 5. Determine Current Stage
 
 Based on bolt state:
@@ -863,9 +1005,28 @@ After running the command, verify the changes were applied correctly:
 
 ---
 
-## Update Construction Log
+## Update Construction Log (HARD GATE)
+
+**⛔ HARD GATE - CONSTRUCTION LOG UPDATES REQUIRED**
 
-**IMPORTANT**: Update the construction log at key execution points.
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  CONSTRUCTION LOG - NON-NEGOTIABLE                          │
+│                                                              │
+│  You MUST update the construction log at these points:       │
+│  1. On first bolt start → Create log using template         │
+│  2. On bolt start → Add "started" entry                     │
+│  3. On stage completion → Add "stage-complete" entry        │
+│  4. On bolt completion → Add "completed" entry              │
+│                                                              │
+│  ⛔ FORBIDDEN: Starting bolt work without log entry         │
+│  ⛔ FORBIDDEN: Completing stage without log entry           │
+│  ⛔ FORBIDDEN: Completing bolt without log entry            │
+│                                                              │
+│  The construction log provides audit trail for the unit.    │
+│  No log entry = no evidence the work happened.              │
+└─────────────────────────────────────────────────────────────┘
+```
 
 ### Location
 

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

@@ -182,9 +182,8 @@ Organize stories for bolt planning:
 Please provide Figma frame URLs for this story.
 You can provide multiple URLs (one per screen/component).
 
-Supported formats:
+Supported format:
 - 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):
 ```

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

@@ -8,14 +8,29 @@ You are building UI for a project. Your goal is to create polished, professional
 
 **If a story has `figma_frames` (array of Figma URLs), use Figma MCP to fetch design specs and interaction flows.**
 
+### CRITICAL: Pixel-Perfect Implementation Required
+
+When Figma designs exist, your implementation MUST match the design exactly. This is non-negotiable.
+
+**FORBIDDEN:**
+
+- Approximating colors ("dark gray" instead of `#1A1A1A`)
+- Guessing spacing ("some padding" instead of `16px`)
+- Substituting fonts (using system font instead of specified font)
+- Changing layout structure from what Figma shows
+- Adding or removing elements not in the design
+
+**If you must deviate from the design, STOP and ask the user first.**
+
 ### 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
+1. **Fetch ALL frames for THIS story first** via Figma MCP before writing any code
+2. **Extract EXACT design specs** from each frame:
+   - Colors: Use exact hex values (e.g., `#1A1A1A`, not "dark")
+   - Typography: Exact font-family, font-size, font-weight, line-height
+   - Spacing: Exact pixel/rem values (e.g., `16px`, not "medium")
+   - Border radius: Exact values (e.g., `8px`)
+   - Shadows: Exact shadow values from design
    - Component dimensions and states
 3. **Extract interaction flows** (prototype connections):
    - Navigation actions (which button goes where)
@@ -25,7 +40,7 @@ You are building UI for a project. Your goal is to create polished, professional
 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
+7. **Verify fidelity** - After implementation, compare against Figma and fix any differences
 
 ### When No Figma Frames Exist
 

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

@@ -49,10 +49,9 @@ interaction_flows: []  # Optional: Manual flow definition (only if Figma has no
 - {figma-frame-url-1}
 - {figma-frame-url-2}
 
-**Supported URL formats:**
+**Supported URL format:**
 
 - 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:**
 

package/lib/installer.js

@@ -2,6 +2,7 @@ const fs = require('fs-extra');
 const path = require('path');
 const prompts = require('prompts');
 const yaml = require('js-yaml');
+const { execSync } = require('child_process');
 const CLIUtils = require('./cli-utils');
 const InstallerFactory = require('./InstallerFactory');
 const { FLOWS } = require('./constants');
@@ -350,10 +351,27 @@ async function installFlow(flowKey, toolKeys) {
   if (await fs.pathExists(sourceScriptsDir)) {
     await fs.copy(sourceScriptsDir, scriptsDir);
     CLIUtils.displayStatus('', 'Installed local scripts', 'success');
+
+    // Install script dependencies (fs-extra, js-yaml)
+    // Scripts require these npm packages to function
+    const scriptsPackageJson = path.join(scriptsDir, 'package.json');
+    if (await fs.pathExists(scriptsPackageJson)) {
+      console.log(theme.dim('  Installing script dependencies...'));
+      try {
+        execSync('npm install --production --silent', {
+          cwd: scriptsDir,
+          stdio: 'pipe'
+        });
+        CLIUtils.displayStatus('', 'Installed script dependencies', 'success');
+      } catch (npmError) {
+        // Non-fatal: warn user but continue installation
+        console.log(theme.warning('  Warning: Could not install script dependencies automatically'));
+        console.log(theme.dim(`  Run: cd ${scriptsDir} && npm install`));
+      }
+    }
   }
 
   // Note: Scripts are invoked directly via relative path (e.g., node .iris/scripts/bolt-complete.js)
-  // No npm scripts added to package.json to avoid dependency on package.json for execution
 
   // NOTE: memory-bank/ is NOT created during installation
   // It will be created when user runs project-init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-iris",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "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": {

package/scripts/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "iris-scripts",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Helper scripts for iris AI-DLC workflow",
+  "scripts": {
+    "bolt-complete": "node bolt-complete.js",
+    "status-integrity": "node status-integrity.js",
+    "artifact-validator": "node artifact-validator.js"
+  },
+  "dependencies": {
+    "fs-extra": "^11.1.1",
+    "js-yaml": "^4.1.0"
+  }
+}