project-iris 0.3.0 → 0.4.0

package/flows/aidlc/context-config.yaml

@@ -22,7 +22,10 @@ agents:
         purpose: "API design conventions"
 
       - path: standards/ux-guide.md
-        purpose: "UI/UX patterns for frontend code"
+        purpose: "Project's UI/UX decisions and design tokens"
+
+      - path: .iris/aidlc/templates/construction/ui-patterns.md
+        purpose: "Design guide for building professional UI (load for any frontend work)"
 
     on_missing_critical:
       action: warn

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

@@ -143,12 +143,43 @@ agents:
     optional_context:
       - path: standards/system-architecture.md
       - path: standards/api-conventions.md
+      - path: standards/ux-guide.md
+      - path: .iris/aidlc/templates/construction/ui-patterns.md
 ```
 
 1. Load all `required_context` files (warn if missing with `critical: true`)
 2. Load `optional_context` files if they exist
 
-**Note**: This is agent-level context. Bolt-type-specific context loading may be added later.
+### 4b. UI Design Context (Conditional Load)
+
+**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`
+- `navigation`, `menu`, `sidebar`, `header`, `footer`
+- `list`, `card`, `table`, `grid` (in UI context)
+
+**If ANY signal is found:**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  UI DESIGN CONTEXT DETECTED                                 │
+│                                                              │
+│  Signal found: {signal} in {unit/story}                     │
+│                                                              │
+│  Action: Read ui-patterns.md for design guidance            │
+│  Path: .iris/aidlc/templates/construction/ui-patterns.md   │
+│                                                              │
+│  Apply these principles where relevant during               │
+│  implementation. Not all principles apply to all tasks.     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Then read the file and keep its principles in mind during code generation.**
+
+This is not a hard requirement - use judgment on which principles apply to the current task.
 
 ### 5. Determine Current Stage
 
@@ -159,9 +190,22 @@ Based on bolt state:
 - **completed** → Inform user bolt is done
 - **blocked** → Show blocker, ask how to resolve
 
-### 6. Update Bolt File on Start (CRITICAL - DO FIRST)
+### 6. Update Bolt File on Start (CRITICAL - HARD GATE)
+
+**⛔ HARD GATE - MUST EXECUTE BEFORE ANY STAGE WORK**
 
-**⚠️ BEFORE any stage work begins, update the bolt file IMMEDIATELY.**
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  BOLT FILE UPDATE - NON-NEGOTIABLE                          │
+│                                                              │
+│  You CANNOT proceed to stage work until you have:           │
+│  1. Used the Edit tool to update bolt.md                    │
+│  2. Verified the edit was applied                           │
+│  3. Shown the user confirmation of the update               │
+│                                                              │
+│  This is a BLOCKING GATE - no exceptions.                   │
+└─────────────────────────────────────────────────────────────┘
+```
 
 When transitioning from `planned` to `in-progress`:
 
@@ -173,11 +217,23 @@ current_stage: {first-stage}  # was: null (e.g., "domain-design")
 ---
 ```
 
-**This is NON-NEGOTIABLE.** The bolt file must reflect that work has begun before any stage activities start. This ensures:
+**Verification Output (REQUIRED):**
+
+After editing, output this confirmation to the user:
+
+```text
+✅ Bolt file updated: {bolt-id}/bolt.md
+   - status: planned → in-progress
+   - started: {timestamp}
+   - current_stage: {stage-name}
+```
+
+**Why This Gate Exists:**
 
 1. Progress is tracked even if execution is interrupted
 2. Other tools/agents see accurate status
 3. Resumption works correctly
+4. **Prevents "Lost in the Middle" bug where updates are skipped**
 
 **Also update construction log** (see "Update Construction Log" section below).
 
@@ -216,26 +272,95 @@ For the current stage, follow the bolt type definition:
    - Use templates if specified by bolt type
    - Place in correct paths per schema
 
-### 7b. Story-by-Story Execution (Code Generation Stages)
+### 7a. Stage Artifact Creation (HARD GATE)
+
+**⛔ HARD GATE - STAGE ARTIFACTS ARE MANDATORY**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  ARTIFACT CREATION - NON-NEGOTIABLE                         │
+│                                                              │
+│  Each stage in the bolt type specifies an artifact.         │
+│  You MUST create it before presenting the checkpoint.       │
+│                                                              │
+│  ⛔ FORBIDDEN: Completing a stage without its artifact      │
+│  ⛔ FORBIDDEN: Skipping artifact because "it's optional"    │
+│  ⛔ FORBIDDEN: Only creating source code without docs       │
+│                                                              │
+│  The artifact documents what was done. No artifact = stage  │
+│  not complete.                                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Artifact Verification (before checkpoint):**
+
+```text
+✅ Stage artifact created: {artifact-path}
+   - Location: memory-bank/bolts/{bolt-id}/{artifact-name}
+   - Template used: {yes/no}
+```
+
+**Common artifacts by bolt type:**
+
+| 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` |
+
+**If bolt type specifies an artifact, you MUST create it.**
+
+### 7b. Story-by-Story Execution (Code Generation Stages) - HARD GATE
 
-**⛔ CRITICAL**: When executing stages that involve code generation (e.g., Stage 4 in DDD bolts), process stories SEQUENTIALLY:
+**⛔ HARD GATE - SEQUENTIAL STORY EXECUTION REQUIRED**
 
 ```text
 ┌─────────────────────────────────────────────────────────────┐
-│  STORY-BY-STORY EXECUTION                                    │
+│  STORY-BY-STORY EXECUTION - NON-NEGOTIABLE                  │
 │                                                              │
-│  For EACH story in bolt's stories array:                     │
-│  1. Announce: "⏳ Story {n}/{total}: {story-id}"             │
-│  2. Read story file for acceptance criteria                  │
-│  3. Implement code for that story                            │
-│  4. Update stories_progress in bolt file                     │
-│  5. Announce: "✅ Story {story-id}: Implemented"             │
+│  ⛔ FORBIDDEN: Implementing multiple stories at once         │
+│  ⛔ FORBIDDEN: Skipping story file reads                     │
+│  ⛔ FORBIDDEN: Not updating stories_progress in bolt file    │
 │                                                              │
-│  DO NOT batch implement - track each story individually!     │
+│  You MUST process stories ONE AT A TIME in sequence.         │
+│  Each story requires its own announce → read → implement →   │
+│  update cycle. Batch implementation = broken traceability.   │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-**Story Progress Display (show after each story)**:
+**For EACH story in bolt's stories array, execute this exact sequence:**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY EXECUTION LOOP (repeat for each story)               │
+│                                                              │
+│  STEP A: Announce start                                      │
+│  Output: "⏳ Story {n}/{total}: {story-id} - {title}"       │
+│                                                              │
+│  STEP B: Read story file (MANDATORY)                         │
+│  Action: Read {intent}/units/{unit}/stories/{story-id}.md   │
+│  Purpose: Extract acceptance criteria for implementation     │
+│                                                              │
+│  STEP C: Implement code for THIS story only                  │
+│  Action: Create/modify code to satisfy acceptance criteria   │
+│  Add traceability: // Story: {story-id}                      │
+│                                                              │
+│  STEP D: Update bolt file stories_progress (MANDATORY)       │
+│  Action: Edit bolt.md to mark story as completed             │
+│                                                              │
+│  STEP E: Announce completion                                 │
+│  Output: "✅ Story {story-id}: Implemented → `{files}`"     │
+│                                                              │
+│  STEP F: Show updated progress list                          │
+│  Then proceed to next story (back to STEP A)                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Story Progress Display (show after EACH story completion):**
 
 ```markdown
 ### Story Progress ({completed}/{total})
@@ -248,7 +373,7 @@ For the current stage, follow the bolt type definition:
 6. [ ] **{SSS}-{story-slug}**: Pending
 ```
 
-**Update bolt file after each story:**
+**Update bolt file after EACH story (not at the end):**
 
 ```yaml
 stories_progress:
@@ -264,10 +389,51 @@ stories_progress:
     status: pending
 ```
 
-This ensures:
-- Clear visibility into which story is being worked on
-- Ability to resume if interrupted
-- Validation that all stories are addressed
+**Why This Pattern Exists:**
+
+1. **Traceability**: Each piece of code maps to a specific story
+2. **Resumability**: If interrupted, we know exactly where to continue
+3. **Verification**: We can validate that ALL stories were addressed
+4. **Visibility**: User sees clear progress through the work
+5. **Quality**: Reading acceptance criteria prevents missed requirements
+
+### 7c. Final Regression Check (After All Stories Implemented)
+
+**⛔ REQUIRED: After implementing all stories, verify no regressions**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  REGRESSION CHECK - BEFORE STAGE CHECKPOINT                  │
+│                                                              │
+│  After ALL stories are implemented, you MUST verify:         │
+│  1. Re-read acceptance criteria from FIRST story             │
+│  2. Verify the implementation still satisfies those ACs      │
+│  3. Repeat for each story in order                           │
+│  4. Report any regressions found                             │
+│                                                              │
+│  Later stories may have broken earlier implementations.      │
+│  Catch this BEFORE moving to Testing stage.                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Regression Check Output:**
+
+```text
+### Regression Check ({stories_count} stories)
+
+1. ✅ **{story-1}**: All ACs still valid
+2. ✅ **{story-2}**: All ACs still valid
+3. ⚠️ **{story-3}**: AC2 regression - {description} → FIX REQUIRED
+4. ✅ **{story-4}**: All ACs still valid
+
+{If regressions found: Fix before proceeding to checkpoint}
+```
+
+**Why This Check Exists:**
+
+- Story N implementation may modify shared code
+- Changes could invalidate Story 1-N-1 acceptance criteria
+- Catching regressions early prevents cascade failures in Testing stage
 
 ### 8. Handle Checkpoints (As Defined by Bolt Type)
 
@@ -310,14 +476,29 @@ If the bolt type specifies automatic validation criteria, follow those rules.
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### 9. Update Bolt File on Stage Completion
+### 9. Update Bolt File on Stage Completion (HARD GATE)
+
+**⛔ HARD GATE - MUST EXECUTE AFTER EACH STAGE**
 
 **Trigger**: After EACH stage completion (not just final stage).
 
-After each stage completion:
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STAGE COMPLETION UPDATE - NON-NEGOTIABLE                   │
+│                                                              │
+│  Before presenting checkpoint to user, you MUST:            │
+│  1. Use Edit tool to update bolt.md with stage completion   │
+│  2. Show verification output to user                        │
+│  3. Only THEN present the checkpoint prompt                 │
+│                                                              │
+│  Stages not recorded in bolt.md = stages not done.          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Required Updates:**
 
 - Add stage to `stages_completed` with timestamp
-- Update `current_stage` to next stage
+- Update `current_stage` to next stage (or null if final)
 
 **⚠️ TIMESTAMP FORMAT**: See `memory-bank.yaml` → `conventions.timestamps`
 
@@ -332,9 +513,18 @@ stages_completed:
 ---
 ```
 
+**Verification Output (REQUIRED):**
+
+```text
+✅ Stage recorded: {stage-name}
+   - stages_completed: [{list of completed stages}]
+   - current_stage: {next-stage-name}
+   - artifact: {artifact-filename}
+```
+
 **If this is the FINAL stage**, proceed to **Step 10** (bolt completion).
 
-**If this is NOT the final stage**, update bolt file and proceed to next stage. Stop here.
+**If this is NOT the final stage**, update bolt file, show verification, then present checkpoint.
 
 ---
 

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-04-implementation-walkthrough-template.md

@@ -0,0 +1,58 @@
+---
+stage: code-generation
+bolt: {bolt-id}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+## Implementation Walkthrough: {unit-name}
+
+### Summary
+
+{2-3 sentence overview of what was built - NO CODE}
+
+### Design Alignment
+
+How the implementation aligns with design documents:
+
+- **Domain Design**: {alignment notes or deviations}
+- **Logical Design**: {alignment notes or deviations}
+
+### Structure Overview
+
+{High-level description of the DDD layers implemented - NO CODE}
+
+### Completed Work
+
+#### Domain Layer
+- [x] `{path/to/file}` - {what this file does}
+
+#### Application Layer
+- [x] `{path/to/file}` - {what this file does}
+
+#### Infrastructure Layer
+- [x] `{path/to/file}` - {what this file does}
+
+#### Presentation Layer
+- [x] `{path/to/file}` - {what this file does}
+
+### Story Traceability
+
+| Story | Files |
+|-------|-------|
+| {story-id} | `{files}` |
+
+### Key Decisions
+
+- **{Decision}**: {Why this approach was chosen}
+
+### Deviations from Design
+
+{Any changes from domain-design or logical-design and why, or "None"}
+
+### Dependencies Added
+
+- [x] `{package}` - {why needed}
+
+### Developer Notes
+
+{Gotchas, tips, or context for future work - keep brief}

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt.md

@@ -33,7 +33,7 @@ Stage 1: Domain Design → Stage 2: Logical Design → Stage 3: ADR Analysis (op
 - ✅/[ ] **1. Domain Design** (Required) → `ddd-01-domain-design.md`
 - ✅/[ ] **2. Logical Design** (Required) → `ddd-02-logical-design.md`
 - ✅/[ ] **3. ADR Analysis** (Optional) → `adr-{n}-{slug}.md` (zero or more)
-- ✅/[ ] **4. Code Generation** (Required) → Source code
+- ✅/[ ] **4. Code Generation** (Required) → Source code + `ddd-04-implementation-walkthrough.md`
 - ✅/[ ] **5. Testing** (Required) → Tests + `ddd-03-test-report.md`
 
 **Rules**:
@@ -386,11 +386,18 @@ Implement CQRS pattern with separate read models for task queries.
 
 **After ALL stories are implemented:**
 
-6 - **Setup project structure**: Verify scaffolding exists
-7 - **Run code quality validation**: Execute linting, type checking, build
+6 - **Run regression check**: Re-verify ALL story acceptance criteria still valid
+7 - **Setup project structure**: Verify scaffolding exists
+8 - **Run code quality validation**: Execute linting, type checking, build
 
-**Artifact**: Source code in unit directory
-**Location**: `src/{unit}/` or as defined in project structure
+**Artifacts**:
+
+- Source code in unit directory: `src/{unit}/` or as defined in project structure
+- `ddd-04-implementation-walkthrough.md`: `memory-bank/bolts/{bolt-id}/ddd-04-implementation-walkthrough.md`
+
+**Template**: `.iris/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-04-implementation-walkthrough-template.md`
+
+**Implementation Walkthrough** documents what was built, any deviations from design, and key decisions made during coding. This is required - do not skip it.
 
 **Project Structure**:
 
@@ -433,6 +440,7 @@ src/{unit}/
 **Completion Criteria**:
 
 - [ ] **All stories implemented in order** (see Story Progress below)
+- [ ] **Regression check passed** - all previous story ACs still valid
 - [ ] All domain models implemented
 - [ ] All use cases implemented
 - [ ] All API endpoints implemented
@@ -459,6 +467,13 @@ src/{unit}/
 5. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
 6. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
 
+### Regression Check ({n}/{n} stories verified)
+
+1. ✅ **{SSS}-{story-slug}**: All ACs still valid
+2. ✅ **{SSS}-{story-slug}**: All ACs still valid
+3. ✅ **{SSS}-{story-slug}**: All ACs still valid
+...
+
 ### Code Generated
 - {n} domain entities
 - {n} use cases
@@ -469,6 +484,7 @@ src/{unit}/
 - ✅ Types: Passed
 - ✅ Build: Passed
 - ✅ Traceability: All files linked to stories
+- ✅ Regression: No story ACs broken
 
 ### Acceptance Criteria Preview
 Each story's ACs will be validated in Stage 5 (Testing).

package/flows/aidlc/templates/construction/bolt-types/simple-construction-bolt.md

@@ -147,6 +147,9 @@ created: {YYYY-MM-DDTHH:MM:SSZ}
 
 **Duration**: Hours (varies by complexity)
 
+**For UI Work** (screens, components, layouts):
+Load `.iris/aidlc/templates/construction/ui-patterns.md` before implementing. This guide helps you build professional UI without a designer.
+
 **Activities**:
 
 1 - **Setup structure**: Create files and folders

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

@@ -0,0 +1,352 @@
+# 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.
+
+---
+
+## Design Mindset
+
+**Before writing any UI code, ask yourself:**
+
+1. What is the user trying to accomplish here?
+2. What's the most important thing on this screen?
+3. What can I remove to make it simpler?
+4. Would a non-technical person understand this instantly?
+
+**Your north star**: If it looks like a template, you've failed. If it feels intentional and crafted, you've succeeded.
+
+---
+
+## Design Tokens (Non-Negotiable)
+
+**Before building screens, define and lock these values:**
+
+- Font family
+- Type scale (use the one in this guide)
+- Primary color
+- Neutral gray scale
+- Border radius
+- Shadow levels
+- Spacing scale
+
+**Once defined:**
+
+- Do not invent new sizes
+- Do not invent new colors
+- Do not invent new radiuses
+- Do not invent new spacing values
+
+**Consistency feels like quality. Inconsistency feels like bugs.**
+
+This prevents "just one more size/color" syndrome. Every deviation from your tokens is a crack in the system.
+
+---
+
+## One Primary Action Rule
+
+**Every screen should answer: "What is the ONE thing the user should do next?"**
+
+- One primary button per screen (ideally)
+- Everything else is secondary, tertiary, or hidden
+- If you need two primary actions, the screen is doing too much
+
+This is product thinking, not just UI. A confused user does nothing.
+
+---
+
+## Decision Hierarchy
+
+**When making UI decisions, prioritize in this order:**
+
+1. **Clarity** - Is it instantly understandable?
+2. **Hierarchy** - Is the important thing obvious?
+3. **Consistency** - Does it match the system?
+4. **Speed** - Is it fast to scan and act on?
+5. **Aesthetics** - Does it look good?
+
+Pretty but confusing is failure. Clear and boring beats clever and unclear.
+
+---
+
+## Visual Hierarchy
+
+**The most important design skill.** Guide the user's eye to what matters.
+
+### Size Creates Importance
+The bigger something is, the more important it appears. Your page title should be the largest text. Secondary info should be smaller and lighter.
+
+### Contrast Draws Attention
+High contrast = look here. Low contrast = secondary. Use bold weight, darker colors, or accent colors for emphasis.
+
+### Whitespace Is Not Empty
+Space around elements gives them importance and breathing room. Cramped UIs feel cheap. Generous spacing feels premium.
+
+**When building a screen:**
+1. Identify the ONE most important element
+2. Make it visually dominant (size, position, contrast)
+3. De-emphasize everything else
+4. Add generous whitespace around important elements
+
+---
+
+## Typography
+
+**Typography alone can make or break your UI.**
+
+### Headlines
+- Bold, confident, short
+- Use sentence case (not ALL CAPS unless it's a label)
+- Leave room to breathe
+
+### Body Text
+- 16px minimum for readability
+- Line height of 1.5-1.7 for paragraphs
+- Keep line length under 70 characters
+
+### The Type Scale
+Don't use random sizes. Pick a scale and stick to it:
+```
+12px - Labels, captions, metadata
+14px - Secondary text, table content
+16px - Body text, form inputs
+18px - Emphasized body, subheadings
+20px - Section headers
+24px - Page titles on mobile
+30px - Page titles on desktop
+36px+ - Hero headlines only
+```
+
+### Font Weight
+- Regular (400) - Body text
+- Medium (500) - Subtle emphasis, navigation
+- Semibold (600) - Headings, buttons
+- Bold (700) - Strong emphasis, hero text
+
+**Never use light (300) weights for UI text.** It's hard to read.
+
+---
+
+## Color
+
+### Less Is More
+Use 2-3 colors maximum:
+- **Primary**: Your brand color. Use sparingly for CTAs and key actions.
+- **Neutral**: Grays for text, borders, backgrounds. This is 80% of your UI.
+- **Semantic**: Red for errors, green for success, yellow for warnings.
+
+### The Gray Trick
+Most "white" backgrounds shouldn't be pure white (#FFFFFF). Use a very light gray (#FAFAFA or #F9FAFB) for large areas. It's easier on the eyes and makes white cards pop.
+
+### Text Colors
+- Primary text: Not pure black. Use #111827 or #1F2937
+- Secondary text: #6B7280 (gray-500)
+- Muted/disabled: #9CA3AF (gray-400)
+
+### Don't Over-Color
+If everything is colorful, nothing stands out. Keep most of your UI neutral and use color only for:
+- Primary actions (buttons, links)
+- Status indicators
+- Errors and alerts
+- Brand moments
+
+---
+
+## Spacing
+
+### The 4px/8px System
+All spacing should be multiples of 4px or 8px:
+- 4px - Minimum gap (icon to label)
+- 8px - Tight spacing (within a component)
+- 16px - Standard spacing (between elements)
+- 24px - Section spacing
+- 32px - Large section gaps
+- 48px+ - Major divisions
+
+### Padding Consistency
+- Buttons: 12px vertical, 16-24px horizontal
+- Cards: 16-24px padding
+- Page content: 24px on mobile, 32-48px on desktop
+- Modals: 24px padding
+
+### Group Related Items
+Elements that belong together should be closer to each other than elements that don't. This creates visual groupings without needing borders.
+
+---
+
+## Layout Principles
+
+### Alignment Creates Order
+Pick an alignment and stick to it. Left-aligned is almost always correct for Western UIs. Don't center long text.
+
+### Limit Line Length
+Long lines of text are hard to read. Keep content areas between 600-800px max width.
+
+### Use a Grid
+12-column grids work for most layouts. On mobile, use full width or simple 2-column splits.
+
+### Z-Pattern for Landing Pages
+Users scan in a Z pattern: top-left → top-right → bottom-left → bottom-right. Place key elements along this path.
+
+### F-Pattern for Content Pages
+Users scan in an F pattern for text-heavy pages. Put important info on the left and in headings.
+
+---
+
+## Components That Feel Right
+
+### Buttons
+- Primary button: Solid background, used for main action (one per screen ideally)
+- Secondary button: Outline or ghost, for secondary actions
+- Destructive button: Red, used only for irreversible actions
+- Make buttons look clickable: slight shadow, hover state, cursor pointer
+
+### Forms
+- One column is usually better than two
+- Label above the input, not beside it
+- Group related fields with a section heading
+- Show validation errors below the field in red
+- Use placeholder text for examples, not labels
+
+### Cards
+- Use subtle shadow, not heavy borders
+- Keep padding consistent
+- Don't put too much in one card
+- Cards should be scannable - bold title, muted description
+
+### Tables
+- Align text left, numbers right
+- Use subtle row borders or alternating backgrounds, not both
+- Make rows hoverable
+- Put actions at the end of the row
+
+### Empty States
+- Never show a blank screen
+- Explain what will be here
+- Provide a clear action to fix the emptiness
+- Add an illustration if appropriate
+
+---
+
+## Mobile First
+
+### Design for the smallest screen first
+If it works on mobile, it will work everywhere. The reverse is not true.
+
+### Touch Targets
+Minimum 44x44px for anything tappable. Fingers are imprecise.
+
+### Thumb Zone
+On mobile, important actions should be reachable by thumb (bottom half of screen).
+
+### Simplify, Don't Shrink
+Don't just make the desktop version smaller. Remove and reorganize for mobile.
+
+---
+
+## The Details That Matter
+
+### Micro-interactions
+- Buttons should have hover and active states
+- Loading states should be smooth, not jarring
+- Transitions should be 150-200ms (fast but noticeable)
+
+### Border Radius
+- Pick one and be consistent: 4px (sharp), 8px (friendly), 12px+ (playful)
+- Don't mix different radiuses randomly
+
+### Shadows
+- Use subtle shadows (shadow-sm) for cards and dropdowns
+- Shadows should be soft and diffused, not harsh
+- Don't put shadows on everything
+
+### Icons
+- Use a consistent icon set (Lucide, Heroicons)
+- Icons should be the same visual weight as text
+- Don't use icons without meaning
+- Always pair icon-only buttons with tooltips
+
+---
+
+## Accessibility (Baseline Rules)
+
+**These are not optional. They are usability under stress.**
+
+- Text contrast must be readable in sunlight
+- Color is never the only indicator (errors, success, status need icons or text too)
+- All interactive elements must be keyboard-focusable
+- Focus states are required (visible ring on focus)
+- Minimum text size: 16px
+- Tap targets: 44x44px minimum
+
+Accessibility is not decoration. It's your product working for everyone.
+
+---
+
+## Common UI Mistakes to Avoid
+
+**Anti-patterns that make UIs feel amateurish:**
+
+- Centered paragraphs of text (hard to read)
+- Too many button styles on one screen
+- Equal visual weight for all elements (nothing stands out)
+- Icons without labels for critical actions
+- Forms split into unnecessary columns
+- Using placeholders instead of labels
+- Overusing borders instead of spacing
+- Multiple font families without reason
+- Inconsistent spacing (16px here, 18px there)
+- Pure black text on pure white backgrounds
+- Tiny click targets on desktop (mobile isn't the only concern)
+- Loading spinners without context ("Loading..." what?)
+
+**If you catch yourself doing any of these, stop and reconsider.**
+
+---
+
+## Before You Ship
+
+### The Squint Test
+Squint at your screen. Can you still tell what's most important? If everything blurs into sameness, your hierarchy is weak.
+
+### The Screenshot Test
+Take a screenshot and look at it on your phone. Does it look like a real product or a developer's side project?
+
+### The Mom Test
+Would your non-technical mom understand what to do on this screen without help?
+
+### Checklist
+- [ ] One clear focal point per screen
+- [ ] Consistent spacing throughout
+- [ ] Type hierarchy is clear (3 sizes max per screen)
+- [ ] Color is used intentionally, not decoratively
+- [ ] Empty states are designed
+- [ ] Loading states are smooth
+- [ ] Works on mobile without horizontal scrolling
+- [ ] All interactive elements have hover/focus states
+- [ ] Adequate color contrast for accessibility
+
+---
+
+## Quick Reference
+
+**When something feels off:**
+- Add more whitespace
+- Reduce the number of font sizes
+- Increase contrast between heading and body
+- Remove a color
+- Align things properly
+
+**When it looks boring:**
+- Don't add more color - add more contrast
+- Don't add decoration - add better typography
+- Don't add borders - use whitespace and shadows
+
+**When it's overwhelming:**
+- Remove elements until it hurts, then add one back
+- Break into smaller screens/steps
+- Hide secondary actions in menus
+- Use progressive disclosure
+
+---
+
+*Great UI is invisible. The user should focus on their task, not your interface. When in doubt, simplify.*

package/package.json

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

package/scripts/bolt-complete.js

@@ -58,6 +58,8 @@
  *   │ 3. If not complete:                                              │
  *   │      status: {current} → complete                                 │
  *   │      implemented: false → true                                    │
+ *   │ 4. Check off acceptance criteria checkboxes:                     │
+ *   │      - [ ] → - [x] (within ## Acceptance Criteria section)       │
  *   │                                                                  │
  *   │ Story search strategy:                                           │
  *   │ - Direct path: {intent}/units/{unit}/stories/{story}.md          │
@@ -106,7 +108,7 @@
  *   │           └── {unit}/
  *   │               ├── unit-brief.md  ← Updated: status (if all bolts complete)
  *   │               └── stories/
- *   │                   ├── 001-{story}.md  ← Updated: status, implemented
+ *   │                   ├── 001-{story}.md  ← Updated: status, implemented, ACs checked
  *   │                   └── ...
  *
  * ┌──────────────────────────────────────────────────────────────────────────┐
@@ -177,6 +179,50 @@ function updateFrontmatter(content, newFrontmatter) {
     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
+ */
+function checkAcceptanceCriteria(content) {
+    // Find the Acceptance Criteria section and check all boxes
+    // Pattern matches: - [ ] at start of line (with optional leading whitespace)
+    // Only within Acceptance Criteria section
+
+    const lines = content.split('\n');
+    let inAcceptanceCriteria = false;
+    let modified = false;
+
+    const updatedLines = lines.map(line => {
+        // Check if we're entering Acceptance Criteria section
+        if (line.match(/^##\s*Acceptance Criteria/i)) {
+            inAcceptanceCriteria = true;
+            return line;
+        }
+
+        // Check if we're leaving (another h2 section)
+        if (inAcceptanceCriteria && line.match(/^##\s+[^#]/)) {
+            inAcceptanceCriteria = false;
+            return line;
+        }
+
+        // If in Acceptance Criteria section, check off unchecked boxes
+        if (inAcceptanceCriteria) {
+            const checkedLine = line.replace(/^(\s*-\s*)\[ \]/, '$1[x]');
+            if (checkedLine !== line) {
+                modified = true;
+            }
+            return checkedLine;
+        }
+
+        return line;
+    });
+
+    return {
+        content: updatedLines.join('\n'),
+        modified
+    };
+}
+
 /**
  * Format timestamp as ISO 8601
  * Format: YYYY-MM-DDTHH:MM:SSZ (no milliseconds, per memory-bank.yaml convention)
@@ -342,28 +388,50 @@ async function updateStories(bolt) {
             continue;
         }
 
-        // Check if already complete
-        if (frontmatter.status === 'complete' && frontmatter.implemented === true) {
+        const alreadyComplete = frontmatter.status === 'complete' && frontmatter.implemented === true;
+
+        // Always check acceptance criteria, even if story is already complete
+        const acResult = checkAcceptanceCriteria(content);
+        const acNeedsUpdate = acResult.modified;
+
+        // Skip only if fully complete AND no AC updates needed
+        if (alreadyComplete && !acNeedsUpdate) {
             console.log(`  ${colors.dim}−${colors.reset} ${storyId} - ${colors.dim}Already complete${colors.reset}`);
             results.skipped++;
             results.details.push({ storyId, status: 'skipped', reason: 'Already complete' });
             continue;
         }
 
-        // Update frontmatter
-        const newFrontmatter = {
-            ...frontmatter,
-            status: 'complete',
-            implemented: true
-        };
+        // Update frontmatter (if not already complete)
+        let newContent;
+        if (alreadyComplete) {
+            // Only update ACs, keep existing frontmatter
+            newContent = acResult.content;
+        } else {
+            // Update both frontmatter and ACs
+            const newFrontmatter = {
+                ...frontmatter,
+                status: 'complete',
+                implemented: true
+            };
+            newContent = updateFrontmatter(content, newFrontmatter);
+            if (newContent) {
+                const acResultUpdated = checkAcceptanceCriteria(newContent);
+                newContent = acResultUpdated.content;
+            }
+        }
 
-        const newContent = updateFrontmatter(content, newFrontmatter);
         if (newContent) {
             await fs.writeFile(storyPath, newContent, 'utf8');
             const oldStatus = frontmatter.status || 'draft';
-            console.log(`  ${colors.green}✓${colors.reset} ${storyId} - ${colors.dim}${oldStatus} → complete${colors.reset}`);
+            const acNote = acNeedsUpdate ? ` ${colors.dim}(ACs checked)${colors.reset}` : '';
+            if (alreadyComplete) {
+                console.log(`  ${colors.green}✓${colors.reset} ${storyId} - ${colors.dim}ACs checked${colors.reset}`);
+            } else {
+                console.log(`  ${colors.green}✓${colors.reset} ${storyId} - ${colors.dim}${oldStatus} → complete${colors.reset}${acNote}`);
+            }
             results.updated++;
-            results.details.push({ storyId, status: 'updated', from: oldStatus, to: 'complete' });
+            results.details.push({ storyId, status: 'updated', from: oldStatus, to: 'complete', acChecked: acNeedsUpdate });
         } else {
             console.log(`  ${colors.red}✗${colors.reset} ${storyId} - ${colors.dim}Failed to update${colors.reset}`);
             results.errors++;