project-iris 0.2.2 → 0.3.0

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

@@ -35,7 +35,7 @@ You are now the **Construction Agent** for iris AI-DLC.
 - **List Bolts**: `.iris/aidlc/skills/construction/bolt-list.md` → View all bolts
 - **Bolt Status**: `.iris/aidlc/skills/construction/bolt-status.md` → Detailed bolt status
 - **Start/Continue Bolt**: `.iris/aidlc/skills/construction/bolt-start.md` → Execute bolt stages
-- **Plan Bolts**: `.iris/aidlc/skills/construction/bolt-plan.md` → Redirects to Inception
+- **Replan Bolts**: `.iris/aidlc/skills/construction/bolt-replan.md` → Modify bolt plan during construction
 - **Menu**: `.iris/aidlc/skills/construction/navigator.md` → Show skills
 
 ---

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

@@ -36,6 +36,7 @@ You are now the **Operations Agent** for iris AI-DLC.
 - **Deploy**: `.iris/aidlc/skills/operations/deploy.md` → Deploy to environment
 - **Verify**: `.iris/aidlc/skills/operations/verify.md` → Validate deployment
 - **Monitor**: `.iris/aidlc/skills/operations/monitor.md` → Setup observability
+- **Rollback**: `.iris/aidlc/skills/operations/rollback.md` → Rollback deployment
 - **Menu**: `.iris/aidlc/skills/operations/navigator.md` → Show skills
 
 ---

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

@@ -21,6 +21,9 @@
 - ✅ Checkpoint prompts clear and actionable
 - ✅ Code references stories (comments: `// Story: S-XXX`)
 - ✅ Tests reference acceptance criteria they verify
+- ✅ **Stories processed sequentially in code generation stages**
+- ✅ **Story progress list shown during execution**
+- ✅ **stories_progress updated in bolt file after each story**
 
 ## Failure Modes
 
@@ -30,6 +33,9 @@
 - ❌ Not reading bolt type definition first
 - ❌ Code without story traceability comments
 - ❌ Tests without acceptance criteria references
+- ❌ **Implementing all stories at once without tracking progress**
+- ❌ **Not showing story progress during code generation**
+- ❌ **Stories implemented out of order without justification**
 
 ---
 
@@ -194,19 +200,75 @@ For the current stage, follow the bolt type definition:
    {From bolt type definition}
 
    ### Stories in Scope
-   {From bolt instance}
+   {From bolt instance - show with status}
+   - [ ] 001-story-one (pending)
+   - [ ] 002-story-two (pending)
    ```
 
 2. **Perform Activities**:
    - Follow bolt type's activity instructions exactly
    - Create artifacts as specified
    - Respect constraints (e.g., "no code in this stage")
+   - **For code generation stages**: Follow story-by-story execution (see 7b)
 
 3. **Generate Outputs**:
    - Create specified output artifacts
    - Use templates if specified by bolt type
    - Place in correct paths per schema
 
+### 7b. Story-by-Story Execution (Code Generation Stages)
+
+**⛔ CRITICAL**: When executing stages that involve code generation (e.g., Stage 4 in DDD bolts), process stories SEQUENTIALLY:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY-BY-STORY EXECUTION                                    │
+│                                                              │
+│  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"             │
+│                                                              │
+│  DO NOT batch implement - track each story individually!     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Story Progress Display (show after each story)**:
+
+```markdown
+### Story Progress ({completed}/{total})
+
+1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+3. ⏳ **{SSS}-{story-slug}**: In Progress
+4. [ ] **{SSS}-{story-slug}**: Pending
+5. [ ] **{SSS}-{story-slug}**: Pending
+6. [ ] **{SSS}-{story-slug}**: Pending
+```
+
+**Update bolt file after each story:**
+
+```yaml
+stories_progress:
+  - id: 001-database-init
+    status: completed
+    implemented_at: {timestamp}
+  - id: 002-schema-tables
+    status: completed
+    implemented_at: {timestamp}
+  - id: 003-crud-operations
+    status: in-progress
+  - id: 004-query-helpers
+    status: pending
+```
+
+This ensures:
+- Clear visibility into which story is being worked on
+- Ability to resume if interrupted
+- Validation that all stories are addressed
+
 ### 8. Handle Checkpoints (As Defined by Bolt Type)
 
 The bolt type definition specifies:
@@ -400,6 +462,13 @@ If construction log doesn't exist, create it using template:
 **Type**: {bolt-type}
 **Progress**: Stage {n} of {total}
 
+### Story Progress ({completed}/{total})
+
+1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+3. ⏳ **{SSS}-{story-slug}**: In Progress
+4. [ ] **{SSS}-{story-slug}**: Pending
+
 ### Activities Performed
 1. ✅ {activity 1}
 2. ✅ {activity 2}
@@ -408,10 +477,6 @@ If construction log doesn't exist, create it using template:
 ### Artifacts Created
 - `{path/to/artifact}` - {description}
 
-### Stories Addressed
-- ✅ **{SSS}-{story-slug}**: {criteria} - Complete
-- ⏳ **{SSS}-{story-slug}**: {criteria} - In Progress
-
 ---
 
 ### Checkpoint (if defined by bolt type)

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

@@ -17,6 +17,8 @@
 - ✅ Each story has: User Story format, Acceptance Criteria, Priority
 - ✅ story-index.md updated with ✅ GENERATED markers
 - ✅ Unit-brief.md updated with story summary
+- ✅ **All assigned FRs have corresponding stories (validation passed)**
+- ✅ **FR-to-story mapping shown in output**
 
 ## Failure Modes
 
@@ -24,6 +26,8 @@
 - ❌ Missing acceptance criteria in stories
 - ❌ Not updating story-index.md
 - ❌ Stories without INVEST criteria validation
+- ❌ **Assigned FRs without corresponding stories**
+- ❌ **Proceeding without FR-to-story validation**
 
 ---
 
@@ -144,6 +148,54 @@ Organize stories for bolt planning:
 - **Should**: Important but not blocking (Error handling, validation)
 - **Could**: Nice to have (Advanced features, optimizations)
 
+### 4b. Validate FR-to-Story Coverage (CRITICAL - HARD GATE)
+
+**⛔ HARD GATE**: Before creating story files, validate that ALL assigned FRs have stories.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FR-TO-STORY COVERAGE VALIDATION                             │
+│  → Read "Assigned Requirements" from unit-brief.md           │
+│  → Check each FR has at least one story                      │
+│  → If any FR is uncovered: STOP and create stories for it    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Validation output:**
+
+```markdown
+## FR-to-Story Coverage
+
+### Assigned FRs from Unit Brief
+- **FR-1**: {description}
+- **FR-2**: {description}
+- **FR-N**: {description}
+
+### Coverage Check
+
+- ✅ **FR-1**: {description} → `{SSS}-{story-slug}`, `{SSS}-{story-slug}`
+- ✅ **FR-2**: {description} → `{SSS}-{story-slug}`
+- ❌ **FR-3**: {description} → UNCOVERED
+
+### Validation Result
+- ✅ All FRs covered by stories (proceed)
+- ❌ {n} FRs uncovered - MUST create stories before proceeding:
+  - FR-X: {description} - NEEDS STORY
+```
+
+**If any FRs are uncovered:**
+
+1. **DO NOT PROCEED** to creating story files
+2. Create stories for uncovered FRs
+3. Re-run validation until all FRs are covered
+
+**Important Notes:**
+
+- One FR can map to multiple stories (complex features)
+- Multiple FRs can map to one story (closely related features)
+- Every FR MUST have at least one story
+- This validation catches FRs that were "lost" during decomposition
+
 ### 5. Document Stories
 
 1. **Read Path**: Check `schema.stories` from `.iris/aidlc/memory-bank.yaml`
@@ -294,6 +346,14 @@ This ensures each unit-brief shows its story count at a glance.
 ```markdown
 ## Stories Created: {unit-name}
 
+### FR-to-Story Coverage ✅
+
+- ✅ **FR-1**: {description} → `{SSS}-{story-slug}`, `{SSS}-{story-slug}`
+- ✅ **FR-2**: {description} → `{SSS}-{story-slug}`
+- ✅ **FR-3**: {description} → `{SSS}-{story-slug}`
+
+**All {n} assigned FRs have corresponding stories.**
+
 ### Story Summary
 
 - [ ] **S1**: User can register - Must - No dependencies

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

@@ -15,7 +15,8 @@
 
 - ✅ Unit directories created with unit-brief.md files
 - ✅ Dependency graph shown visually
-- ✅ All FRs mapped to exactly one unit
+- ✅ **All FRs mapped to exactly one unit (validation passed)**
+- ✅ FR coverage validation output shown
 - ✅ Frontend unit included if enabled in project type
 
 ## Failure Modes
@@ -23,6 +24,8 @@
 - ❌ Using ASCII table for unit listing
 - ❌ Not reading project type configuration
 - ❌ FRs not mapped to units
+- ❌ **Proceeding without FR coverage validation**
+- ❌ **Unmapped FRs not flagged**
 - ❌ Missing unit-brief.md files
 
 ---
@@ -149,6 +152,54 @@ This mapping ensures:
 - Units have clear scope based on assigned FRs
 - Stories will be created from unit's assigned FRs (not directly from intent)
 
+### 4b. Validate FR Coverage (CRITICAL - HARD GATE)
+
+**⛔ HARD GATE**: Before proceeding, validate that ALL FRs are mapped.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FR COVERAGE VALIDATION                                      │
+│  → Count FRs in requirements.md                              │
+│  → Count FRs in mapping                                      │
+│  → If mismatch: STOP and fix before proceeding               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Validation output:**
+
+```markdown
+## FR Coverage Validation
+
+### Requirements Count
+- **Total FRs in requirements.md**: {n}
+- **Must Have**: {n}
+- **Should Have**: {n}
+- **Could Have**: {n}
+
+### Mapping Count
+- **FRs mapped to units**: {n}
+- **FRs unmapped**: {list or "None"}
+
+### Validation Result
+- ✅ All FRs mapped (proceed to next step)
+- ❌ {n} FRs unmapped - MUST fix before proceeding:
+  - FR-X: {description} - NOT MAPPED
+  - FR-Y: {description} - NOT MAPPED
+```
+
+**If any FRs are unmapped:**
+
+1. **DO NOT PROCEED** to creating unit directories
+2. Review unmapped FRs and assign them to appropriate units
+3. Re-run validation until all FRs are mapped
+
+**Common reasons for unmapped FRs:**
+
+- FR was overlooked during domain analysis
+- FR spans multiple bounded contexts (split or create integration unit)
+- FR is an NFR incorrectly labeled as FR (move to NFRs)
+- FR is duplicate (merge with existing)
+
 ### 5. Create Frontend Unit (if enabled)
 
 **Skip this step if `frontend.enabled: false`.**

package/flows/aidlc/skills/master/project-init.md

@@ -15,6 +15,7 @@
 
 - ✅ project.yaml created with project type AND scenario (greenfield/brownfield/hybrid)
 - ✅ Scenario detected automatically with user confirmation
+- ✅ .gitignore updated with AI-DLC tooling entries
 - ✅ Standards created in correct order (dependencies respected)
 - ✅ Each question is single-focus (not combined)
 - ✅ Final summary shows all created/skipped standards
@@ -26,6 +27,7 @@
 - ❌ Creating standard before its dependencies
 - ❌ Not creating project.yaml
 - ❌ Not detecting/asking about greenfield vs brownfield scenario
+- ❌ Not updating .gitignore with AI-DLC tooling entries
 
 ---
 
@@ -125,9 +127,9 @@ This appears to be a **brownfield** project (enhancing existing code).
 2. **Greenfield** - No, ignore existing code, starting fresh
 3. **Hybrid** - Some features will modify existing, some are new
 
-This affects how the Construction Agent works:
-- **Brownfield**: Runs code elevation first to understand existing structure
-- **Greenfield**: Starts fresh with domain modeling
+This affects the development flow:
+- **Brownfield**: Master Agent runs code elevation first to understand existing structure
+- **Greenfield**: Construction Agent starts fresh with domain modeling
 - **Hybrid**: Asks per-intent which flow to use
 ```
 
@@ -185,6 +187,33 @@ existing_codebase:
 
 This file MUST be created before proceeding to standards facilitation, as other agents (e.g., Inception, Construction) read it to provide context-aware behavior.
 
+### 4b. Update .gitignore
+
+**Add AI-DLC tooling entries to `.gitignore`** to keep the product repository clean.
+
+#### If `.gitignore` exists:
+
+Check if entries already exist. If not, append:
+
+```gitignore
+
+# AI-DLC tooling (iris, claude)
+.iris/
+.claude/
+```
+
+#### If `.gitignore` doesn't exist:
+
+Create it with:
+
+```gitignore
+# AI-DLC tooling (iris, claude)
+.iris/
+.claude/
+```
+
+**Note**: `memory-bank/` is NOT gitignored - it contains valuable project specifications (PRFAQ, intents, stories, standards) that should be version controlled.
+
 ### 5. Check Existing Standards
 
 Before creating new standards, check if any exist:
@@ -314,6 +343,7 @@ After completing all standards:
 - **Type**: {project type} (e.g., full-stack-web)
 - **Scenario**: {scenario} (greenfield/brownfield/hybrid)
 - **Config**: `memory-bank/project.yaml`
+- **Gitignore**: `.gitignore` updated with AI-DLC tooling entries
 
 ### Standards Created
 
@@ -337,9 +367,9 @@ Your project is configured as a **{project type}** ({scenario}) using:
 - Use your chosen libraries and patterns
 - Follow your testing strategy
 
-**Scenario** - Construction Agent will:
-- {If greenfield}: Start with domain modeling (fresh design)
-- {If brownfield}: Run code elevation first (analyze existing code)
+**Scenario** - Development flow:
+- {If greenfield}: Construction Agent starts with domain modeling (fresh design)
+- {If brownfield}: Master Agent runs code elevation first (analyze existing code)
 - {If hybrid}: Ask per-intent which flow to use
 
 ### Actions

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

@@ -349,18 +349,45 @@ Implement CQRS pattern with separate read models for task queries.
 - **REQUIRED**: Load all bolt folder artifacts (see Bolt Context Loading section)
 - **OUTPUT**: Source code based on design docs
 
-**Activities**:
+**⛔ CRITICAL: Story-by-Story Execution**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY-BY-STORY EXECUTION MODE                               │
+│                                                              │
+│  Stories MUST be implemented SEQUENTIALLY:                   │
+│  1. Read bolt's stories array                                │
+│  2. For each story in order:                                 │
+│     a. Announce: "Implementing Story: {story-id}"            │
+│     b. Read story file for acceptance criteria               │
+│     c. Implement code for that story                         │
+│     d. Update story status in bolt tracking                  │
+│     e. Show: "Story {story-id}: ✅ Implemented"              │
+│  3. After ALL stories: proceed to checkpoint                 │
+│                                                              │
+│  DO NOT implement all stories at once without tracking!      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Story Execution Order:**
+
+1. Read `stories` array from bolt.md frontmatter
+2. Process stories in the order listed (this order respects dependencies)
+3. For each story, implement the code needed to satisfy its acceptance criteria
+4. Track progress visibly to user
+
+**Activities** (performed FOR EACH STORY):
 
-1 - **Setup project structure**: Create scaffolding
-2 - **Implement domain entities/value objects**: Create domain code
-3 - **Implement domain services**: Build service layer
-4 - **Implement application layer**: Create use cases
-5 - **Implement infrastructure**: Build repository implementations
-6 - **Implement presentation layer**: Create API endpoints
-7 - **Add validation and error handling**: Implement guards and handlers
-8 - **Add logging and instrumentation**: Add observability code
-9 - **Add story traceability**: Add `// Story: S-XXX` comments linking code to stories
-10 - **Run code quality validation**: Execute linting, type checking, build
+1 - **Announce story**: Display "⏳ Implementing Story: {story-id}: {title}"
+2 - **Read story file**: Load `stories/{story-id}.md` for acceptance criteria
+3 - **Implement code**: Create/modify code to satisfy acceptance criteria
+4 - **Add traceability**: Add `// Story: {story-id}` comments to code
+5 - **Mark progress**: Display "✅ Story {story-id}: Implemented"
+
+**After ALL stories are implemented:**
+
+6 - **Setup project structure**: Verify scaffolding exists
+7 - **Run code quality validation**: Execute linting, type checking, build
 
 **Artifact**: Source code in unit directory
 **Location**: `src/{unit}/` or as defined in project structure
@@ -405,6 +432,7 @@ src/{unit}/
 
 **Completion Criteria**:
 
+- [ ] **All stories implemented in order** (see Story Progress below)
 - [ ] All domain models implemented
 - [ ] All use cases implemented
 - [ ] All API endpoints implemented
@@ -422,6 +450,15 @@ src/{unit}/
 ```text
 ## Stage 4 Complete: Code Generation
 
+### Story Progress ({n}/{n})
+
+1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+3. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+4. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+5. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+6. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+
 ### Code Generated
 - {n} domain entities
 - {n} use cases
@@ -433,9 +470,8 @@ src/{unit}/
 - ✅ Build: Passed
 - ✅ Traceability: All files linked to stories
 
-### Story Coverage
-- S-001: {files implementing}
-- S-002: {files implementing}
+### Acceptance Criteria Preview
+Each story's ACs will be validated in Stage 5 (Testing).
 
 Ready to proceed to testing?
 1 - Yes, continue to Stage 5
@@ -560,19 +596,42 @@ Story S-002: Password Reset
 
 ## State Tracking
 
-Bolt instance tracks progress:
+Bolt instance tracks progress at both stage and story level:
 
 ```yaml
 ---
-current_stage: design
+current_stage: code
 stages_completed:
-  - name: model
+  - name: domain-design
     completed: 2024-12-05T10:00:00Z
     artifact: ddd-01-domain-design.md
+  - name: logical-design
+    completed: 2024-12-05T12:00:00Z
+    artifact: ddd-02-logical-design.md
 status: in-progress
+
+# Story-level tracking (updated during Stage 4)
+stories_progress:
+  - id: 001-database-init
+    status: completed
+    implemented_at: 2024-12-05T14:00:00Z
+  - id: 002-schema-tables
+    status: completed
+    implemented_at: 2024-12-05T14:30:00Z
+  - id: 003-crud-operations
+    status: in-progress
+  - id: 004-query-helpers
+    status: pending
 ---
 ```
 
+**Story status values:**
+
+- `pending` - Not yet started
+- `in-progress` - Currently being implemented
+- `completed` - Implementation done (not yet tested)
+- `verified` - Tests passing (after Stage 5)
+
 ---
 
 ## Bolt Context Loading