project-iris 0.6.7 → 0.6.9

package/flows/aidlc/skills/construction/refs/bolt-output.md

@@ -0,0 +1,106 @@
+# Bolt Output Templates & Completion Checklist
+
+> Referenced from `bolt-start.md` — Output formatting, post-bolt actions, and completion verification.
+
+---
+
+## Output (Stage Execution)
+
+```markdown
+## Executing Bolt: {bolt-id}
+
+### Current Stage: {stage-name}
+**Type**: {bolt-type}
+**Progress**: Stage {n} of {total}
+
+### 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
+
+### Activities Performed
+1. ✅ {activity 1}
+2. ✅ {activity 2}
+3. ⏳ {activity 3 - in progress}
+
+### Artifacts Created
+- `{path/to/artifact}` - {description}
+
+---
+
+### Checkpoint (if defined by bolt type)
+> "{checkpoint prompt from bolt type definition}"
+```
+
+---
+
+## Output (Bolt Completed)
+
+```markdown
+## Bolt Complete: {bolt-id}
+
+### Summary
+- **Type**: {bolt-type}
+- **Duration**: {time elapsed}
+- **Stages Completed**: {all stages from bolt type}
+
+### Artifacts Produced
+{List artifacts as defined by bolt type}
+
+### Stories Delivered
+- ✅ **{SSS}-{story-slug}**: Complete
+- ✅ **{SSS}-{story-slug}**: Complete
+
+### Actions
+
+1 - **next**: Start next bolt
+2 - **list**: Review all bolts for this unit
+3 - **operations**: Proceed to Operations (if all complete)
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## CRITICAL: Post-Bolt Options (NEVER SKIP)
+
+**After EVERY bolt completion, you MUST present the Actions menu above.**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  BOLT COMPLETED                                              │
+│  → You MUST show the Actions menu (1-next, 2-list, 3-ops)   │
+│  → Do NOT just ask "approve to continue?"                    │
+│  → Let the user CHOOSE their next action                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Failure Mode**: Asking "Ready to proceed to next bolt?" without showing options
+**Correct Behavior**: Always show numbered Actions list and wait for user choice
+
+---
+
+## Bolt Completion Checklist
+
+**Use this checklist to verify all completion tasks are done:**
+
+```text
+□ Bolt file updated:
+  □ status: complete
+  □ completed: {timestamp}
+  □ current_stage: null
+
+□ Stories updated (Step 10):
+  □ Each story in bolt's stories array:
+    □ status: complete
+    □ implemented: true
+
+□ Status cascade checked (Step 11):
+  □ Unit status updated if all bolts complete
+  □ Intent status updated if all units complete
+
+□ Construction log updated:
+  □ "{bolt-id} completed" entry added
+```

package/flows/aidlc/skills/construction/refs/construction-log.md

@@ -0,0 +1,55 @@
+# Construction Log Updates
+
+This sub-skill defines when and how to update the construction log.
+
+---
+
+## Update Construction Log (HARD GATE)
+
+**⛔ HARD GATE - CONSTRUCTION LOG UPDATES REQUIRED**
+
+```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
+
+`{unit-path}/construction-log.md`
+
+### On First Bolt Start
+
+If construction log doesn't exist, create it using template:
+`.iris/aidlc/templates/construction/construction-log-template.md`
+
+### On Bolt Start
+
+```markdown
+- **{ISO-8601-timestamp}**: {bolt-id} started - Stage 1: {stage-name}
+```
+
+### On Stage Completion
+
+```markdown
+- **{ISO-8601-timestamp}**: {bolt-id} stage-complete - {stage-name} → {next-stage}
+```
+
+### On Bolt Completion
+
+```markdown
+- **{ISO-8601-timestamp}**: {bolt-id} completed - All {n} stages done
+```

package/flows/aidlc/skills/construction/refs/figma-integration.md

@@ -0,0 +1,363 @@
+# Figma Design Integration
+
+This sub-skill handles Figma frame extraction, design specs, interaction flows, and scope enforcement for UI stories.
+
+---
+
+## 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 format:**
+
+- Design file: `https://www.figma.com/design/{file-id}/{file-name}?node-id={node-id}&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 --transport http figma 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 --transport http figma https://mcp.figma.com/mcp`
+   Then authenticate via `/mcp` in Claude Code.
+```
+
+### 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 for THIS story FIRST** before writing any UI code
+2. **Build the interaction map** to understand the complete flow
+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. **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
+
+**Post-Implementation Fidelity Check:**
+
+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
+```