project-iris 0.4.0 → 0.5.1

package/flows/aidlc/README.md

@@ -127,6 +127,7 @@ src/flows/aidlc/
 **Goal**: Complete planning and design before construction begins
 
 **Activities**:
+
 - Capture intents (high-level goals)
 - Gather requirements (functional and non-functional)
 - Assess risks (technical, business, operational)
@@ -138,6 +139,7 @@ src/flows/aidlc/
 **Command**: `/iris-inception-agent --intent="intent-name"`
 
 **Outputs**:
+
 - PRFAQ document
 - Requirements with measurement criteria
 - Risk assessment
@@ -151,6 +153,7 @@ src/flows/aidlc/
 **Goal**: Build working software through iterative bolt execution
 
 **Activities**:
+
 - Execute bolts through DDD stages:
   1. **Domain Design** - Model business logic using DDD principles
   2. **Logical Design** - Apply NFRs and architectural patterns
@@ -161,6 +164,7 @@ src/flows/aidlc/
 **Command**: `/iris-construction-agent --unit="unit-name"`
 
 **Outputs**:
+
 - Domain design documents
 - Logical design documents
 - Architectural Decision Records (ADRs)
@@ -172,6 +176,7 @@ src/flows/aidlc/
 **Goal**: Deploy and operate the system
 
 **Activities**:
+
 - Build deployment artifacts (containers, functions, bundles)
 - Deploy through environments (Dev → Staging → Production)
 - Verify deployments with health checks
@@ -181,6 +186,7 @@ src/flows/aidlc/
 **Command**: `/iris-operations-agent --unit="unit-name"`
 
 **Outputs**:
+
 - Deployment units
 - Monitoring dashboards
 - Alert configurations
@@ -192,19 +198,24 @@ src/flows/aidlc/
 ## Project Scenarios
 
 ### Greenfield (New Projects)
+
 Starting fresh with no existing code:
+
 1. Initialize project with standards
 2. Begin Inception phase immediately
 3. Build from scratch using AI-DLC methodology
 
 ### Brownfield (Existing Codebases)
+
 Adding features to existing code:
+
 1. Initialize project with standards
 2. **Run code elevation** to analyze existing codebase
 3. AI creates static and dynamic models for context
 4. Begin Inception with full codebase understanding
 
 **Code Elevation Process**:
+
 - **Static Model**: Components, responsibilities, and relationships
 - **Dynamic Model**: How components interact for significant use cases
 
@@ -227,6 +238,7 @@ Intent (feature/capability)
 **Bolts** are time-boxed execution sessions scoped to a **Unit**. A Unit may require multiple Bolts to complete all its Stories.
 
 **Example**:
+
 - **Intent**: User Authentication
   - **Unit**: Auth Service
     - **Story 1**: User Registration
@@ -385,21 +397,27 @@ memory-bank/
 ## Key Principles
 
 ### 1. AI Drives, Human Validates
+
 AI proposes plans, decompositions, and implementations. Humans review and approve at checkpoints.
 
 ### 2. Human Oversight as Loss Function
+
 Validation at each step catches errors early before they cascade downstream.
 
 ### 3. Mob Elaboration
+
 Concentrated rapid planning during Inception. Complete all planning in hours, not weeks.
 
 ### 4. Bolts are Flexible
+
 Bolts take "hours or days" depending on complexity - not fixed-duration like sprints.
 
 ### 5. DDD Focus
+
 Domain-Driven Design principles guide the Construction phase with proper separation of concerns.
 
 ### 6. Persistent Context
+
 Everything is stored in the memory bank so context is never lost between sessions.
 
 ---
@@ -457,18 +475,21 @@ Here's a complete workflow for building a feature:
 ## Tips for Success
 
 ### Planning (Inception)
+
 - Be thorough - it pays off during Construction
 - Document NFRs with measurable criteria
 - Assess risks early with mitigations
 - Group related stories into the same bolt
 
 ### Building (Construction)
+
 - Follow the DDD stages in order
 - Don't skip testing
 - Keep bolts focused (5-8 stories max)
 - Document significant decisions as ADRs
 
 ### Deploying (Operations)
+
 - Always deploy to staging first
 - Run smoke tests after every deployment
 - Setup monitoring from the start

package/flows/aidlc/agents/README.md

@@ -15,9 +15,11 @@ agents/
 ## Agent Overview
 
 ### Master Agent
+
 **Role**: Orchestrator & Navigator
 
 The central entry point that:
+
 - Initializes new projects with standards
 - Analyzes current project state
 - Routes users to the appropriate phase agent
@@ -31,9 +33,11 @@ The central entry point that:
 ---
 
 ### Inception Agent
+
 **Role**: Planning & Design Specialist
 
 Handles the Inception phase:
+
 - Captures intents (high-level goals)
 - Gathers requirements (functional and non-functional)
 - Identifies risks
@@ -49,9 +53,11 @@ Handles the Inception phase:
 ---
 
 ### Construction Agent
+
 **Role**: Builder & Implementer
 
 Handles the Construction phase:
+
 - Executes bolts through DDD stages
 - Guides domain design
 - Creates logical designs
@@ -64,6 +70,7 @@ Handles the Construction phase:
 **Command**: `/iris-construction-agent --unit="unit-name"`
 
 **DDD Bolt Stages**:
+
 1. Domain Design
 2. Logical Design
 3. ADR Analysis (optional)
@@ -73,9 +80,11 @@ Handles the Construction phase:
 ---
 
 ### Operations Agent
+
 **Role**: DevOps Engineer & Deployment Orchestrator
 
 Handles the Operations phase:
+
 - Builds deployment artifacts
 - Deploys through environments (Dev → Staging → Production)
 - Verifies deployments
@@ -120,22 +129,28 @@ Each agent file follows this structure:
 ## Key Principles
 
 ### 1. Agent Independence
+
 Each agent operates independently but can redirect to other agents when appropriate:
+
 - Master → Inception (when ready to plan)
 - Master → Construction (when ready to build)
 - Inception → Construction (when inception complete)
 - Construction → Operations (when construction complete)
 
 ### 2. Human Validation
+
 All agents implement checkpoints where they pause for human approval before proceeding with significant actions.
 
 ### 3. Context Loading
+
 Agents load context from the memory bank at startup:
+
 - Standards (tech-stack, coding-standards)
 - Current phase state
 - Relevant artifacts
 
 ### 4. Consistent Output
+
 All agents follow the same output formatting rules defined in Mandatory Output Rules.
 
 ## Phase Flow

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

@@ -6,12 +6,87 @@ 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/agents/master-agent.md

@@ -99,6 +99,7 @@ No project configuration found. This appears to be a new project.
 ```
 
 **CRITICAL**: When user selects "Initialize project", the `project-init` skill MUST:
+
 1. Ask project type question FIRST (full-stack, backend, frontend, CLI, library)
 2. Then detect/ask scenario (greenfield/brownfield/hybrid)
 3. Save `project.yaml` with BOTH fields before proceeding to standards

package/flows/aidlc/skills/README.md

@@ -83,18 +83,23 @@ Every skill file follows this structure:
 ## Key Principles
 
 ### 1. Mandatory Output Rules
+
 Every skill starts with formatting rules to ensure consistent output:
+
 - Never use ASCII tables (they break at different terminal widths)
 - Always use numbered list format for options
 - Always use status indicators (✅ ⏳ [ ] 🚫)
 
 ### 2. Human Checkpoints
+
 Skills that make significant decisions include checkpoints where the AI pauses for human validation before proceeding.
 
 ### 3. Artifact Creation
+
 Skills that create artifacts reference templates from `../templates/` and follow the schema defined in `../memory-bank.yaml`.
 
 ### 4. Context Loading
+
 Skills load context as defined in `../context-config.yaml` to ensure consistent information access.
 
 ## Adding New Skills

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

@@ -32,10 +32,12 @@
 When referencing bolt files to the user, ALWAYS show the **bolt ID prominently**, not just "bolt.md":
 
 **WRONG**:
+
 - "Working on bolt.md"
 - "Open bolt.md to see details"
 
 **CORRECT**:
+
 - "Working on **001-extension-foundation**"
 - "Open **001-extension-foundation/bolt.md** to see details"
 
@@ -46,6 +48,7 @@ The bolt ID (directory name like `001-extension-foundation`) is the identifier.
 ## Checkpoints
 
 **Checkpoint 1**: Which bolt to work on?
+
 - Wait for: User selection
 
 ---

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

@@ -44,11 +44,13 @@
 When referencing bolt files to the user, ALWAYS show the **bolt ID prominently**, not just "bolt.md":
 
 **WRONG**:
+
 - "Working on bolt.md"
 - "Updating bolt.md status"
 - "Approve changes to bolt.md?"
 
 **CORRECT**:
+
 - "Working on **001-extension-foundation**"
 - "Updating **001-extension-foundation** status"
 - "Approve changes to **001-extension-foundation/bolt.md**?"
@@ -155,6 +157,7 @@ agents:
 **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`
@@ -300,19 +303,12 @@ For the current stage, follow the bolt type definition:
    - Template used: {yes/no}
 ```
 
-**Common artifacts by bolt type:**
+**Required artifacts are defined by the bolt type definition file.**
 
-| 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` |
+Each bolt type specifies its own stages and required artifacts. Refer to:
+`templates/construction/bolt-types/{bolt_type}.md`
 
-**If bolt type specifies an artifact, you MUST create it.**
+**If the bolt type definition specifies an artifact for a stage, you MUST create it.**
 
 ### 7b. Story-by-Story Execution (Code Generation Stages) - HARD GATE
 
@@ -350,12 +346,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)                 │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -373,15 +375,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,16 +4,39 @@
 
 ## 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
 - ✅ **ALWAYS** include User Story format: "As a {user}, I want {action} so that {benefit}"
 - ✅ **ALWAYS** include testable Acceptance Criteria (binary pass/fail)
@@ -21,6 +44,7 @@
 - ✅ **ALWAYS** identify dependencies between FRs
 
 ### Non-Functional Requirements Rules
+
 - ✅ **ALWAYS** walk through ALL 5 NFR categories (Performance, Scalability, Security, Reliability, Compliance)
 - ✅ **ALWAYS** ensure NFRs have measurable metrics (not vague)
 - ✅ **ALWAYS** define SLOs for critical requirements

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

@@ -119,6 +119,7 @@ Intent → Requirements → Units → Stories → Bolts
    - [ ] Bolt dependencies respect story dependencies
 
 **Validation Outcome:**
+
 - ✅ = Complete traceability
 - ⚠️ = Partial traceability (gaps identified)
 - ❌ = Broken traceability (must fix before Construction)

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

@@ -5,6 +5,7 @@
 ## Mandatory Output Rules (READ FIRST)
 
 ### General Rules
+
 - 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
 - ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
 - ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending)
@@ -14,6 +15,7 @@
 - 🛑 **STOP** at each checkpoint - wait for user response
 
 ### Risk Register Rules
+
 - ✅ **ALWAYS** categorize risks (Technical, Business, Operational, External, Compliance)
 - ✅ **ALWAYS** use standard impact/likelihood scoring (1-5 scale)
 - ✅ **ALWAYS** calculate risk score (Impact × Likelihood)
@@ -134,6 +136,7 @@ Please answer these questions so I can generate an accurate risk register.
 After user answers, generate risks covering all 5 categories:
 
 **Risk Scoring Matrix:**
+
 - **Impact** (1-5): 1=Negligible, 2=Minor, 3=Moderate, 4=Major, 5=Catastrophic
 - **Likelihood** (1-5): 1=Rare, 2=Unlikely, 3=Possible, 4=Likely, 5=Almost Certain
 - **Risk Score** = Impact × Likelihood
@@ -183,7 +186,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 +211,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 +236,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 +261,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 +286,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.**
@@ -519,11 +542,13 @@ Requirements
 During Construction and Operations, risks should be reviewed:
 
 ### Construction Phase
+
 - Review technical risks before each Bolt
 - Update risk status as mitigations are implemented
 - Add new risks discovered during development
 
 ### Operations Phase
+
 - Review operational risks before deployment
 - Update external/compliance risks as regulations change
 - Close mitigated risks, add new operational risks