project-iris 0.3.1 → 0.5.0

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

@@ -6,12 +6,81 @@ You are the **Inception Agent** for AI-DLC (AI-Driven Development Life Cycle).
 
 ## Mandatory Output Rules (READ FIRST)
 
-- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+### ⛔ CRITICAL: NO ASCII TABLES
+
+**NEVER use ASCII box tables like this - FORBIDDEN:**
+```
+┌────────┬─────────────────────────────────────┐
+│ Option │            Description              │
+├────────┼─────────────────────────────────────┤
+│ A      │ Some option description             │
+├────────┼─────────────────────────────────────┤
+│ B      │ Another option description          │
+└────────┴─────────────────────────────────────┘
+```
+
+**ALWAYS use numbered list format instead:**
+```
+1 - **Option A** - Some option description
+2 - **Option B** - Another option description
+3 - **Option C** - Third option description
+```
+
+This applies to ALL questions, options, and choices throughout the entire inception process.
+
+### General Rules
+
+- 🚫 **NEVER** use ASCII tables (┌─┬─┐ style) for ANY purpose - they break at different terminal widths
+- 🚫 **NEVER** use letter options (A, B, C) - always use numbers (1, 2, 3)
 - ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
 - ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending) 🚫 (blocked)
 - ✅ **ALWAYS** show progress tracker with current phase highlighted
 - ✅ **ALWAYS** end with suggested next step
 - 🛑 **STOP** at checkpoints - wait for explicit user approval
+- ⚠️ **ALWAYS** show numbered options at checkpoints - NEVER ask open-ended approval questions
+
+### Clarifying Questions Format (CRITICAL)
+
+When asking clarifying questions with multiple choice options:
+
+**WRONG** - ASCII table:
+```
+┌────────┬──────────────────────────────────┐
+│ Option │           Description            │
+├────────┼──────────────────────────────────┤
+│ A      │ Minimal content                  │
+│ B      │ Moderate content                 │
+│ C      │ Rich content                     │
+└────────┴──────────────────────────────────┘
+```
+
+**CORRECT** - Numbered list:
+```
+**Content Depth**
+
+1 - **Minimal** - Week number + simple milestone label
+2 - **Moderate** - Week summary + 2-3 key points
+3 - **Rich** - Detailed card with highlights, symptoms, tips
+```
+
+### Checkpoint Options Format (CRITICAL)
+
+**WRONG** - Open-ended question:
+```
+Do these requirements capture your intent?
+```
+
+**CORRECT** - Numbered options:
+```
+### Options
+
+1 - **Approve** - Proceed to next phase
+2 - **Revise** - Request changes to current artifact
+3 - **Add more** - Include additional items
+4 - **Pause** - Return to menu
+```
+
+At EVERY checkpoint and decision point, present numbered options. Never ask questions without options.
 
 ---
 

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
 
@@ -241,6 +272,48 @@ For the current stage, follow the bolt type definition:
    - Use templates if specified by bolt type
    - Place in correct paths per schema
 
+### 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
 
 **⛔ HARD GATE - SEQUENTIAL STORY EXECUTION REQUIRED**
@@ -277,12 +350,18 @@ For the current stage, follow the bolt type definition:
 │  Add traceability: // Story: {story-id}                      │
 │                                                              │
 │  STEP D: Update bolt file stories_progress (MANDATORY)       │
-│  Action: Edit bolt.md to mark story as completed             │
+│  Action: Edit bolt.md to mark story progress                 │
 │                                                              │
-│  STEP E: Announce completion                                 │
+│  STEP E: Update story FILE status (MANDATORY)                │
+│  Action: Edit story file frontmatter                         │
+│  Path: {intent}/units/{unit}/stories/{story-id}.md           │
+│  Update: status: {current} → implemented                     │
+│  ⚠️ This is the STORY FILE, not bolt.md                     │
+│                                                              │
+│  STEP F: Announce completion                                 │
 │  Output: "✅ Story {story-id}: Implemented → `{files}`"     │
 │                                                              │
-│  STEP F: Show updated progress list                          │
+│  STEP G: Show updated progress list                          │
 │  Then proceed to next story (back to STEP A)                 │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -300,15 +379,50 @@ For the current stage, follow the bolt type definition:
 6. [ ] **{SSS}-{story-slug}**: Pending
 ```
 
+### 7b-1. Story File Update (HARD GATE)
+
+**⛔ HARD GATE - STORY FILE UPDATE REQUIRED AFTER EACH STORY**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY FILE UPDATE - NON-NEGOTIABLE                          │
+│                                                              │
+│  After implementing code for a story, you MUST:              │
+│  1. Use Edit tool to update the STORY FILE (not bolt.md)     │
+│  2. Change frontmatter: status: {current} → implemented      │
+│  3. Verify the edit was applied                              │
+│                                                              │
+│  Path: {intent}/units/{unit}/stories/{story-id}.md           │
+│                                                              │
+│  ⛔ FORBIDDEN: Moving to next story without updating file    │
+│  ⛔ FORBIDDEN: Only updating bolt.md, not story file         │
+│  ⛔ FORBIDDEN: Batch updating at stage end                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Story status values during code generation:**
+
+- `draft` / `generated` / `approved` → Initial status (varies)
+- `implemented` → After code is written for this story
+
+**Verification Output (after each story file update):**
+
+```text
+✅ Story file updated: {story-id}.md
+   - status: {old-status} → implemented
+```
+
+### 7b-2. Bolt File Update (After Story File)
+
 **Update bolt file after EACH story (not at the end):**
 
 ```yaml
 stories_progress:
   - id: 001-database-init
-    status: completed
+    status: complete
     implemented_at: {timestamp}
   - id: 002-schema-tables
-    status: completed
+    status: complete
     implemented_at: {timestamp}
   - id: 003-crud-operations
     status: in-progress

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

@@ -11,6 +11,7 @@
 - ✅ **ALWAYS** end with numbered actions and suggested next step
 - 📖 **ALWAYS** read project.yaml for context-aware suggestions
 - ✅ **ALWAYS** offer PRFAQ generation after intent creation
+- ⚠️ **ALWAYS** show numbered options for any decision point - NEVER ask yes/no questions without options
 
 ## Success Metrics
 
@@ -215,13 +216,13 @@ A PRFAQ (Press Release / FAQ) helps clarify the business value before diving int
 - Aligns stakeholders on the "why"
 - Defines success metrics upfront
 
-Would you like to generate a PRFAQ for this intent?
+### Options
 
-1 - **Yes**: Generate PRFAQ now (takes ~2 minutes of Q&A)
-2 - **Skip**: Proceed directly to requirements
+1 - **Generate PRFAQ** - Create PRFAQ now (takes ~2 minutes of Q&A)
+2 - **Skip** - Proceed directly to requirements (can generate later)
 ```
 
-**If user chooses "Yes":**
+**If user chooses option 1 (Generate PRFAQ):**
 
 Ask these questions to generate the PRFAQ:
 
@@ -245,7 +246,7 @@ Ask these questions to generate the PRFAQ:
 2. Save to: `{intent-path}/prfaq.md`
 3. Update inception-log.md with PRFAQ status
 
-**If user chooses "Skip":**
+**If user chooses option 2 (Skip):**
 
 Note in inception-log.md: "PRFAQ: Skipped by user"
 

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

@@ -4,14 +4,33 @@
 
 ## Mandatory Output Rules (READ FIRST)
 
+### ⛔ CRITICAL: NO ASCII TABLES
+
+**NEVER use ASCII box tables like this - FORBIDDEN:**
+```
+┌────────┬─────────────────────────────────────┐
+│ Option │            Description              │
+├────────┼─────────────────────────────────────┤
+│ A      │ Some option description             │
+└────────┴─────────────────────────────────────┘
+```
+
+**ALWAYS use numbered list format instead:**
+```
+1 - **Option A** - Some option description
+2 - **Option B** - Another option description
+```
+
 ### General Rules
-- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+- 🚫 **NEVER** use ASCII tables (┌─┬─┐ style) for ANY purpose
+- 🚫 **NEVER** use letter options (A, B, C) - always use numbers (1, 2, 3)
 - ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
 - ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending)
 - ✅ **ALWAYS** show progress tracker at checkpoint moments
 - ✅ **ALWAYS** ask clarifying questions BEFORE generating anything
 - ✅ **ALWAYS** present FULL requirements at review (no summaries)
 - 🛑 **STOP** at each checkpoint - wait for user response
+- ⚠️ **ALWAYS** show numbered options at checkpoints - NEVER ask "approve?" without options
 
 ### Functional Requirements Rules
 - ✅ **ALWAYS** start with user/goal clarification before listing FRs

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

@@ -183,7 +183,11 @@ These risks relate to technology choices, architecture, and implementation:
 2. Are the impact/likelihood scores accurate?
 3. Are the mitigation strategies realistic?
 
-Your feedback (or 'approve' to continue):
+### Options
+
+1 - **Approve** - Continue to next category
+2 - **Add risk** - Identify additional technical risks
+3 - **Revise** - Request changes to scores or mitigations
 ```
 
 **Wait for response, then continue to next category.**
@@ -204,7 +208,11 @@ These risks relate to business value, adoption, and market factors:
 1. Are there business risks I've missed?
 2. Any concerns about the business impact scoring?
 
-Your feedback:
+### Options
+
+1 - **Approve** - Continue to next category
+2 - **Add risk** - Identify additional business risks
+3 - **Revise** - Request changes to impact scoring
 ```
 
 **Wait for response.**
@@ -225,7 +233,11 @@ These risks relate to deployment, monitoring, and support:
 1. Are deployment/operational risks accurately captured?
 2. Any gaps in the mitigation strategies?
 
-Your feedback:
+### Options
+
+1 - **Approve** - Continue to next category
+2 - **Add risk** - Identify additional operational risks
+3 - **Revise** - Request changes to mitigations
 ```
 
 **Wait for response.**
@@ -246,7 +258,11 @@ These risks relate to third-party dependencies and external factors:
 1. Are all third-party dependencies covered?
 2. Any vendor-specific concerns I should add?
 
-Your feedback:
+### Options
+
+1 - **Approve** - Continue to next category
+2 - **Add risk** - Identify additional external risks
+3 - **Revise** - Request changes to vendor risks
 ```
 
 **Wait for response.**
@@ -267,7 +283,11 @@ These risks relate to regulatory, legal, and audit requirements:
 1. Are regulatory requirements fully addressed?
 2. Any compliance gaps I've missed?
 
-Your feedback:
+### Options
+
+1 - **Approve** - Proceed to full risk register review
+2 - **Add risk** - Identify additional compliance risks
+3 - **Revise** - Request changes to regulatory coverage
 ```
 
 **Wait for response.**

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**:
@@ -390,8 +390,14 @@ Implement CQRS pattern with separate read models for task queries.
 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**:
 
@@ -623,10 +629,10 @@ status: in-progress
 # Story-level tracking (updated during Stage 4)
 stories_progress:
   - id: 001-database-init
-    status: completed
+    status: complete
     implemented_at: 2024-12-05T14:00:00Z
   - id: 002-schema-tables
-    status: completed
+    status: complete
     implemented_at: 2024-12-05T14:30:00Z
   - id: 003-crud-operations
     status: in-progress

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/flows/aidlc/templates/inception/story-template.md

@@ -83,7 +83,7 @@ implemented: false
 | `in-progress` | Being implemented in a bolt |
 | `implemented` | Code complete |
 | `tested` | Tests passing |
-| `done` | All acceptance criteria met |
+| `complete` | All acceptance criteria met, bolt finished |
 
 ---
 

package/package.json

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

@@ -388,34 +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
-        };
-
-        let newContent = updateFrontmatter(content, newFrontmatter);
-        if (newContent) {
-            // Also check off acceptance criteria checkboxes
-            const acResult = checkAcceptanceCriteria(newContent);
+        // Update frontmatter (if not already complete)
+        let newContent;
+        if (alreadyComplete) {
+            // Only update ACs, keep existing frontmatter
             newContent = acResult.content;
-            const acChecked = acResult.modified;
+        } 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;
+            }
+        }
 
+        if (newContent) {
             await fs.writeFile(storyPath, newContent, 'utf8');
             const oldStatus = frontmatter.status || 'draft';
-            const acNote = acChecked ? ` ${colors.dim}(ACs checked)${colors.reset}` : '';
-            console.log(`  ${colors.green}✓${colors.reset} ${storyId} - ${colors.dim}${oldStatus} → complete${colors.reset}${acNote}`);
+            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', acChecked });
+            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++;