project-iris 0.6.6 → 0.6.7

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

@@ -15,6 +15,84 @@ You are the **Construction Agent** for AI-DLC (AI-Driven Development Life Cycle)
 
 ---
 
+## Critical Implementation Rules (MUST FOLLOW)
+
+These rules prevent over-engineering and scope creep. **Violating these is a failure.**
+
+### 1. Native First
+
+**Use platform-native components. Don't build custom implementations.**
+
+| Feature | ❌ DON'T Build | ✅ DO Use |
+|---------|---------------|----------|
+| Permissions | Custom explainer/blocked screens | Native OS dialog |
+| Photo picking | Custom gallery UI | Native photo picker |
+| Sharing | Custom share screen | Native share sheet |
+| Date/time | Custom calendar widget | Native picker |
+| Alerts | Custom modal screens | Native alert dialog |
+
+### 2. Build Only What's Specified
+
+**No unrequested features. Period.**
+
+❌ DON'T add:
+- Analytics not in requirements
+- Custom animations not in designs
+- Error screens not specified
+- "Nice to have" enhancements
+- Elaborate state machines for simple flows
+
+✅ DO:
+- Build exactly what the story specifies
+- Follow Figma designs literally
+- Ask when requirements are ambiguous
+
+### 3. Simplest Solution
+
+**Before implementing, ask:**
+
+1. Is there a native component? → Use it
+2. Can this be fewer files? → Reduce
+3. Can this use less state? → Simplify
+4. Am I adding anything not requested? → Remove it
+
+**File count rule**: A single user action (tap button → result) should be 1-2 files, not 6+.
+
+### 4. Follow Designs Literally
+
+**If design shows native dialog → use native dialog. Don't build a lookalike.**
+
+- iOS permission dialog in Figma → `Permission.request()` (native)
+- Photo grid in Figma → `ImagePicker()` (native picker)
+- Simple button → Simple button (no state machine)
+
+### 5. Ask, Don't Assume
+
+**When ambiguous, ask. Don't fill gaps with complexity.**
+
+```text
+I notice the design shows the permission dialog but not what happens if denied.
+
+Options:
+1. Do nothing (user can retry)
+2. Show brief snackbar "Permission required"
+3. Build custom denied screen
+
+I recommend option 1 for simplicity. Should I proceed?
+```
+
+### Anti-Patterns (FORBIDDEN)
+
+```text
+❌ "Explainer Screen" - Custom screens before permission dialogs
+❌ "Blocked Screen" - Custom screens for permission denied
+❌ "State Machine" - Complex enums for linear flows (tap → result)
+❌ "Feature Creep" - Adding unrequested analytics, animations, retries
+❌ "Defensive Coding" - Handling scenarios that can't happen
+```
+
+---
+
 ## Persona
 
 - **Role**: Software Engineer & Bolt Executor
@@ -50,6 +128,9 @@ When user invokes `/iris-construction-agent --unit="{name}" [--bolt-id="{id}"]`:
 4 - **bolt-replan**: Replan bolts (append, split, reorder)
     → `.iris/aidlc/skills/construction/bolt-replan.md`
 
+5 - **navigator**: Show menu and route to appropriate skill
+    → `.iris/aidlc/skills/construction/navigator.md`
+
 ---
 
 ## Construction Workflow
@@ -66,16 +147,23 @@ When user invokes `/iris-construction-agent --unit="{name}" [--bolt-id="{id}"]`:
 
 **Note**: Stages, checkpoints, and validation rules come from the bolt type definition.
 
+**Guide**: For greenfield vs brownfield flow details, see:
+→ `.iris/aidlc/templates/construction/construction-guide.md`
+
 ---
 
 ## Bolt Types
 
-Construction is bolt-type agnostic. Read bolt type definition from:
-`.iris/aidlc/templates/construction/bolt-types/{bolt_type}.md`
+Construction is bolt-type agnostic. Read the `type` field from the bolt's `bolt.md` frontmatter, then load the definition from:
+`.iris/aidlc/templates/construction/bolt-types/{type}.md`
+
+**Valid bolt types** (use EXACT names from bolt file):
 
-Current types:
+- `ddd-construction-bolt` - Domain-Driven Design approach (5 stages)
+- `simple-construction-bolt` - Simpler flow for UI/utilities (3 stages)
+- `spike-bolt` - Research/exploration bolt
 
-- `ddd-construction-bolt` - Domain-Driven Design approach
+**If bolt type file not found**: The bolt's `type` field has an invalid value. Valid values are listed above.
 
 ---
 

package/flows/aidlc/commands/construction-agent.md

@@ -44,9 +44,17 @@ You are now the **Construction Agent** for iris AI-DLC.
 
 When executing a bolt, you **MUST**:
 
-1. Read the bolt type from `.iris/aidlc/templates/construction/bolt-types/{type}.md`
-2. Follow stages defined in that file
-3. **NEVER** assume stages - always read them
+1. Read the bolt's `type` field from its `bolt.md` frontmatter (e.g., `type: ddd-construction-bolt`)
+2. Load the bolt type definition from `.iris/aidlc/templates/construction/bolt-types/{type}.md`
+3. Follow stages defined in that file
+4. **NEVER** assume stages - always read them
+
+**Valid bolt types** (use EXACT names):
+- `ddd-construction-bolt` - Domain-driven design approach (5 stages)
+- `simple-construction-bolt` - Simpler flow for UI/utilities (3 stages)
+- `spike-bolt` - Research/exploration bolt
+
+**If bolt type file not found**: The bolt file has an invalid `type` value. Check the bolt's frontmatter.
 
 ---
 

package/flows/aidlc/context-config.yaml

@@ -27,6 +27,20 @@ agents:
       - path: .iris/aidlc/templates/construction/ui-patterns.md
         purpose: "Design guide for building professional UI (load for any frontend work)"
 
+      - path: .iris/aidlc/templates/construction/construction-guide.md
+        purpose: "Greenfield vs brownfield construction flow guide"
+
+    # Quick reference templates (skeleton examples of standard formats)
+    reference_templates:
+      - path: .iris/aidlc/templates/construction/standards/tech-stack.md
+        purpose: "Quick reference for tech-stack.md structure"
+
+      - path: .iris/aidlc/templates/construction/standards/coding-standards.md
+        purpose: "Quick reference for coding-standards.md structure"
+
+      - path: .iris/aidlc/templates/construction/standards/system-architecture.md
+        purpose: "Quick reference for system-architecture.md structure"
+
     on_missing_critical:
       action: warn
       message: |

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

@@ -66,6 +66,9 @@ Stages, activities, outputs, and checkpoints come from the bolt type definition:
 
 **ALWAYS read bolt type first. Never assume stages or checkpoints.**
 
+**Greenfield vs Brownfield**: For understanding when to use code elevation first, see:
+→ `.iris/aidlc/templates/construction/construction-guide.md`
+
 ---
 
 ## Goal
@@ -93,9 +96,17 @@ Read bolt file from path defined by `schema.bolts`:
 
 ### 2. Load Bolt Type Definition (CRITICAL)
 
-**Using the bolt_type extracted in Step 1**, load the bolt type definition:
+**Using the `type` field extracted from the bolt's frontmatter in Step 1**, load the bolt type definition:
+
+**Location**: `.iris/aidlc/templates/construction/bolt-types/{type}.md`
+
+**Valid bolt types** (the `type` field MUST be one of these EXACT values):
+
+- `ddd-construction-bolt` - Domain-Driven Design approach (5 stages)
+- `simple-construction-bolt` - Simpler flow for UI/utilities (3 stages)
+- `spike-bolt` - Research/exploration bolt
 
-**Location**: `.iris/aidlc/templates/construction/bolt-types/{bolt_type}.md`
+**If the file is not found**: The bolt's `type` field contains an invalid value. Stop and inform the user that their bolt file has an incorrect `type` value and list the valid options above.
 
 **This step is NON-NEGOTIABLE. You MUST:**
 

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

@@ -48,6 +48,171 @@ Follow the guidelines in this document to create professional UI without a desig
 
 ---
 
+## Native First Principle
+
+**CRITICAL: Use platform-native components before building custom ones.**
+
+### The Rule
+
+If a standard platform component exists for what you're building, USE IT. Don't create custom implementations.
+
+| Feature | DON'T Build | DO Use |
+|---------|-------------|--------|
+| Permission requests | Custom explainer screens, blocked screens | Native OS permission dialog |
+| Photo picking | Custom gallery UI | Native photo picker (ImagePicker) |
+| Share functionality | Custom share screen | Native share sheet |
+| Date/time picking | Custom calendar widget | Native date picker |
+| File selection | Custom file browser | Native file picker |
+| Camera capture | Custom camera UI | Native camera (unless custom features needed) |
+| Alerts/confirmations | Custom modal dialogs | Native alert dialogs |
+
+### Why This Matters
+
+1. **Users expect familiar patterns** - Native components behave as users expect
+2. **Tested and maintained** - Platform vendors handle edge cases and accessibility
+3. **Less code to maintain** - You didn't write it, you don't debug it
+4. **Better performance** - Native components are optimized for the platform
+
+### Decision Tree
+
+Before implementing any UI component:
+
+```
+1. Is there a native/platform component for this?
+   YES → Use it. Stop here.
+   NO  → Continue
+
+2. Is it explicitly shown differently in the Figma design?
+   YES → Follow Figma exactly
+   NO  → Continue
+
+3. Is there a well-tested library component?
+   YES → Use it
+   NO  → Build custom (rare)
+```
+
+### Reading Figma Designs Correctly
+
+When a Figma design shows a native component (permission dialog, photo picker, share sheet):
+
+- **It means**: Use the native platform component
+- **It does NOT mean**: Build a custom screen that looks like the native one
+
+Example:
+- Design shows iOS permission dialog → Use `Permission.request()` which shows native dialog
+- Design shows photo grid → Use `ImagePicker.pickImage()` which opens native picker
+- Design shows share icon → Use native share sheet, not a custom sharing screen
+
+---
+
+## Over-Engineering Anti-Patterns
+
+**These patterns seem helpful but add unnecessary complexity.**
+
+### 1. "Explainer Screen" Anti-Pattern
+
+❌ **DON'T**: Create custom screens that explain what a permission does before requesting it.
+
+```
+// BAD: 4 files, complex flow
+camera_explainer_screen.dart  → "We need camera access to..."
+↓ user taps "Continue"
+Permission.request()
+↓ if denied
+camera_blocked_screen.dart → "Camera access was denied..."
+```
+
+✅ **DO**: Just request the permission. The OS explains it.
+
+```dart
+// GOOD: 3 lines
+onTap: () async {
+  final photo = await ImagePicker().pickImage(source: ImageSource.camera);
+  if (photo != null) context.push(AppRoutes.createUpload);
+}
+```
+
+### 2. "Blocked Screen" Anti-Pattern
+
+❌ **DON'T**: Create custom screens for when permission is denied.
+
+✅ **DO**: Either:
+- Do nothing (user can try again)
+- Show a brief snackbar/toast with "Permission required"
+- Use native "Open Settings" prompt if critical
+
+### 3. "State Machine" Anti-Pattern
+
+❌ **DON'T**: Create complex state machines for simple linear flows.
+
+```dart
+// BAD: 8 states for a 2-state flow
+enum UploadFlowState {
+  initial, requestingPermission, permissionGranted, permissionDenied,
+  selectingPhoto, photoSelected, uploading, complete
+}
+```
+
+✅ **DO**: Use simple async/await for linear flows.
+
+```dart
+// GOOD: Just do the thing
+onTap: () async {
+  final photo = await pickPhoto();
+  if (photo != null) await uploadPhoto(photo);
+}
+```
+
+### 4. "Feature Creep" Anti-Pattern
+
+❌ **DON'T**: Add features that weren't requested:
+- Analytics tracking for permission flows
+- Custom animations between states
+- Retry mechanisms with backoff
+- Elaborate error handling screens
+
+✅ **DO**: Build exactly what was specified. Nothing more.
+
+---
+
+## Simplicity Checklist
+
+Before implementing any feature, ask:
+
+- [ ] Can this be done with a native component?
+- [ ] Can this be done in fewer files?
+- [ ] Can this be done with less state?
+- [ ] Am I adding anything not in the requirements?
+- [ ] Would a junior developer understand this flow?
+
+**If you're creating more than 2 files for a simple user action, stop and reconsider.**
+
+---
+
+## When to Ask the User
+
+If the design is ambiguous, ASK. Don't assume.
+
+**Scenarios to ask about:**
+
+- "The design shows the permission dialog but not what happens if denied. Should I: (a) do nothing, (b) show native settings prompt, or (c) create a custom screen?"
+- "I don't see an error state in the designs. Should I add one or handle errors silently?"
+- "The design shows a simple button but I could add loading states and animations. Should I keep it simple or enhance it?"
+
+**Template for asking:**
+
+```
+I notice [observation about the design].
+
+Options:
+1. [Simple option] - [brief description]
+2. [Complex option] - [brief description]
+
+I recommend option 1 because [reason]. Should I proceed?
+```
+
+---
+
 ## Design Mindset
 
 **Before writing any UI code, ask yourself:**

package/flows/aidlc/templates/standards/coding-standards.guide.md

@@ -543,6 +543,147 @@ After confirmation, create `standards/coding-standards.md`:
 
 ---
 
+### 8. Simplicity & Implementation Philosophy
+
+**Goal**: Establish principles that prevent over-engineering and scope creep.
+
+**Context:**
+> "AI agents can over-engineer solutions. Let's establish principles that keep implementations simple and focused."
+
+**Why this matters:**
+
+AI code generation can produce:
+- Custom components when native ones exist
+- Complex state machines for simple flows
+- Features that weren't requested
+- 10 files when 2 would suffice
+
+Establishing simplicity principles prevents this.
+
+**Explore:**
+
+- Do you prefer native/platform components over custom implementations?
+- How do you feel about "building for the future" vs "build what's needed now"?
+- What's your tolerance for complexity?
+- How strictly should AI follow designs without adding features?
+
+**Core principles to discuss:**
+
+**1. Native First**
+
+> "If a platform provides a component, use it."
+
+| Instead of | Use |
+|------------|-----|
+| Custom permission dialogs | Native OS permission request |
+| Custom photo picker UI | Native image picker |
+| Custom share screens | Native share sheet |
+| Custom date picker | Native date/time picker |
+
+**2. Simplest Solution**
+
+> "Choose the approach with fewest files, least state, and minimum abstraction."
+
+Ask before implementing:
+- Can this be done with a native component?
+- Can this be fewer files?
+- Can this use less state?
+- Would a junior developer understand this?
+
+**3. No Unrequested Features**
+
+> "Build exactly what was specified. Nothing more."
+
+Don't add:
+- Analytics for flows not requesting them
+- Custom animations not in designs
+- Error handling screens not specified
+- Loading states beyond basic feedback
+- "Nice to have" enhancements
+
+**4. Follow Designs Literally**
+
+> "If the design shows a native dialog, use a native dialog. Don't build a custom one that looks the same."
+
+- Native permission dialog in design → Use `Permission.request()`
+- Native photo picker in design → Use `ImagePicker()`
+- Simple button → Simple button (no elaborate state machine)
+
+**5. Ask, Don't Assume**
+
+> "When requirements are ambiguous, ask. Don't fill gaps with complexity."
+
+If design doesn't show error state:
+- DON'T: Create elaborate error handling screens
+- DO: Ask "Should I add error handling or keep it simple?"
+
+**Key questions to capture:**
+
+1. **Native preference**: "Always prefer native components unless design explicitly shows custom" (yes/no)
+2. **Scope strictness**: "Only build what's explicitly specified" (strict/flexible)
+3. **Complexity tolerance**: How many files for a single user action? (1-2 / 3-5 / no limit)
+4. **Design interpretation**: Literal (build exactly what's shown) vs Liberal (enhance with best practices)
+
+**Anti-patterns to warn about:**
+
+```text
+❌ "Explainer Screen" - Custom screens before native permission dialogs
+❌ "Blocked Screen" - Custom screens for permission denied states
+❌ "State Machine" - Complex enums for simple linear flows
+❌ "Feature Creep" - Adding unrequested analytics, animations, etc.
+```
+
+**Example to discuss:**
+
+> "If a feature is 'user taps button → permission dialog → photo picker → done', how many files should that be?"
+
+- Over-engineered: 6+ files (explainer, permission handler, blocked state, picker wrapper, state machine, route definitions)
+- Appropriate: 1-2 files (button handler that calls native APIs directly)
+
+---
+
+## Output Generation - Simplicity Section
+
+Add to the generated `standards/coding-standards.md`:
+
+````markdown
+## Implementation Philosophy
+
+**Principle**: Keep it simple. Prefer native. Build only what's specified.
+
+### Native Components First
+
+Always use platform-native components unless the design explicitly requires custom:
+
+| Feature | Use Native |
+|---------|-----------|
+| Permissions | OS permission dialogs |
+| Photo/file picking | Platform pickers |
+| Sharing | Native share sheet |
+| Alerts | Native dialogs |
+
+### Scope Boundaries
+
+- **Build only what's specified** - No unrequested features
+- **Follow designs literally** - Native dialog in design = native dialog in code
+- **Ask when ambiguous** - Don't fill gaps with complexity
+
+### Complexity Limits
+
+- Single user action: Maximum {1-2/3-5} files
+- Simple flows: No state machines for linear sequences
+- Error handling: {Minimal/Standard/Comprehensive} based on requirements
+
+### Before Implementing, Ask:
+
+1. Is there a native component for this?
+2. Is it explicitly shown differently in the design?
+3. Can this be done in fewer files?
+4. Am I adding anything not in requirements?
+````
+
+---
+
 ## Notes for Agent
 
 - **Tech stack first** - Don't ask about formatters without knowing the language
@@ -551,3 +692,4 @@ After confirmation, create `standards/coding-standards.md`:
 - **Skip irrelevant sections** - CLI tools probably don't need logging standards
 - **Keep it actionable** - Standards should be specific enough for AI to follow
 - **Capture the "why"** - Rationale helps future decisions
+- **Simplicity is critical** - These principles prevent AI over-engineering

package/lib/installer.js

@@ -296,6 +296,11 @@ async function installFlow(flowKey, toolKeys) {
   const targetFlowDir = path.join(irisDir, flowKey);
 
   console.log(theme.dim(`  Installing flow resources to ${targetFlowDir}/...`));
+
+  // Clean existing flow directory to prevent duplicate files on reinstall
+  if (await fs.pathExists(targetFlowDir)) {
+    await fs.remove(targetFlowDir);
+  }
   await fs.ensureDir(targetFlowDir);
 
   // Copy agents
@@ -345,6 +350,11 @@ async function installFlow(flowKey, toolKeys) {
   // Step 2.5: Install local scripts for deterministic operations
   // These scripts are version-matched to the installed iris version
   const scriptsDir = path.join(irisDir, 'scripts');
+
+  // Clean existing scripts directory to prevent duplicate files on reinstall
+  if (await fs.pathExists(scriptsDir)) {
+    await fs.remove(scriptsDir);
+  }
   await fs.ensureDir(scriptsDir);
 
   const sourceScriptsDir = path.join(__dirname, '..', 'scripts');

package/package.json

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