project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/src/flows/aidlc/templates/construction/bolt-types/simple-construction-bolt.md

@@ -0,0 +1,347 @@
+# Bolt Type: Simple Construction
+
+## Mandatory Output Rules (READ FIRST)
+
+- 🚫 **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) 🚫 (blocked)
+
+## Success Metrics
+
+- ✅ Activities presented as numbered lists (not tables)
+- ✅ Stage progress shown with status indicators
+- ✅ Human checkpoints clearly marked
+
+## Failure Modes
+
+- ❌ Using ASCII table for activities
+- ❌ Auto-advancing without human confirmation
+- ❌ Skipping stages
+
+---
+
+## ⛔ CRITICAL: Stage Execution Sequence
+
+**Stages MUST be executed in this exact order:**
+
+```text
+Stage 1: Plan → Stage 2: Implement → Stage 3: Test
+```
+
+**Stage Overview:**
+
+- ✅/[ ] **1. Plan** (Required) → `implementation-plan.md`
+- ✅/[ ] **2. Implement** (Required) → Source code + `implementation-walkthrough.md`
+- ✅/[ ] **3. Test** (Required) → Tests + `test-walkthrough.md`
+
+**Rules**:
+
+- Each stage MUST be completed before the next begins
+- **⛔ Human validation is MANDATORY at each stage checkpoint - STOP and WAIT for approval**
+- NEVER auto-advance to next stage without explicit user confirmation
+
+---
+
+## Metadata
+
+```yaml
+bolt_type: simple-construction-bolt
+name: Simple Construction Bolt
+description: Lightweight construction for UI, integrations, utilities, and non-DDD work
+version: 1.0.0
+suitable_for:
+  - Frontend pages and components
+  - Simple backend endpoints
+  - Integrations with external APIs
+  - Utilities and helper modules
+  - Scripts and automation
+  - CLI commands
+stages_count: 3
+```
+
+---
+
+## Overview
+
+This bolt type provides a lightweight construction process for work that doesn't need full domain modeling. It's ideal for UI work, integrations, utilities, and any code where the design is straightforward.
+
+**Best For**:
+
+- Frontend pages, components, layouts
+- Simple CRUD endpoints without complex business logic
+- Third-party API integrations
+- Utility functions and helpers
+- CLI commands and scripts
+- Configuration and setup tasks
+
+**NOT For** (use `ddd-construction-bolt` instead):
+
+- Complex domain logic with business rules
+- Systems requiring bounded contexts
+- Services with rich domain models
+
+---
+
+## Stages
+
+### Stage 1: Plan
+
+**Objective**: Define what to build with clear requirements
+
+**Duration**: Minutes to hours (typically 15-60 minutes)
+
+**Activities**:
+
+1 - **Review stories**: Understand what needs to be built
+2 - **Define scope**: List specific deliverables
+3 - **Identify dependencies**: External APIs, other units, libraries
+4 - **Define acceptance criteria**: How will we know it's done?
+5 - **Note technical approach**: High-level implementation notes
+
+**Artifact**: `implementation-plan.md`
+**Location**: `memory-bank/bolts/{bolt-id}/implementation-plan.md`
+
+**Template Structure**:
+
+```markdown
+---
+stage: plan
+bolt: {bolt-id}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+## Implementation Plan: {unit-name}
+
+### Objective
+{What this bolt will accomplish}
+
+### Deliverables
+- {Deliverable 1}
+- {Deliverable 2}
+
+### Dependencies
+- {Dependency 1}: {why needed}
+
+### Technical Approach
+{Brief notes on how to implement}
+
+### Acceptance Criteria
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+```
+
+**Completion Criteria**:
+
+- [ ] Stories reviewed and understood
+- [ ] Deliverables clearly defined
+- [ ] Dependencies identified
+- [ ] Acceptance criteria documented
+
+**⛔ HUMAN Checkpoint**: Present plan summary and **STOP**. Wait for user to confirm before proceeding to Stage 2.
+
+---
+
+### Stage 2: Implement
+
+**Objective**: Write the code and document what was done
+
+**Duration**: Hours (varies by complexity)
+
+**Activities**:
+
+1 - **Setup structure**: Create files and folders
+2 - **Implement core functionality**: Build the main features
+3 - **Handle edge cases**: Error handling, validation
+4 - **Add documentation**: Code comments, JSDoc/docstrings
+5 - **Run linting**: Ensure code style compliance
+6 - **Document implementation**: Create implementation walkthrough
+
+**Artifacts**:
+
+- Source code - As defined in project structure (e.g., `src/`, `app/`, `pages/`)
+- `implementation-walkthrough.md` - `memory-bank/bolts/{bolt-id}/implementation-walkthrough.md`
+
+**Implementation Walkthrough Guidelines**:
+
+⚠️ **CRITICAL RULES**:
+
+- **NO CODE** in this document - only structure summaries and descriptions
+- **USE CHECKMARKS** for all file entries (completed work)
+- **BE CONSISTENT** - follow the template exactly
+
+**Template**:
+
+```markdown
+---
+stage: implement
+bolt: {bolt-id}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+## Implementation Walkthrough: {unit-name}
+
+### Summary
+
+{2-3 sentence overview of what was built - NO CODE}
+
+### Structure Overview
+
+{High-level description of the architecture/organization - NO CODE}
+
+### Completed Work
+
+- [x] `{path/to/file}` - {what this file does, not how}
+- [x] `{path/to/file}` - {what this file does, not how}
+- [x] `{path/to/file}` - {what this file does, not how}
+
+### Key Decisions
+
+- **{Decision}**: {Why this approach was chosen}
+
+### Deviations from Plan
+
+{Any changes from implementation-plan.md and why, or "None"}
+
+### Dependencies Added
+
+- [x] `{package}` - {why needed}
+
+### Developer Notes
+
+{Gotchas, tips, or context for future work - keep brief}
+```
+
+**What to Include**:
+
+- ✅ File paths with brief purpose descriptions
+- ✅ Architectural decisions and rationale
+- ✅ Deviations from original plan
+- ✅ High-level structure explanations
+
+**What NOT to Include**:
+
+- ❌ Code snippets or examples
+- ❌ Implementation details (how it works internally)
+- ❌ Line-by-line explanations
+- ❌ API signatures or type definitions
+
+**Completion Criteria**:
+
+- [ ] All deliverables from plan implemented
+- [ ] Code follows project coding standards
+- [ ] Linting passes
+- [ ] Code is documented
+- [ ] Implementation walkthrough created
+
+**⛔ HUMAN Checkpoint**: Present implementation summary and **STOP**. Wait for user to confirm before proceeding to Stage 3.
+
+---
+
+### Stage 3: Test
+
+**Objective**: Verify the implementation works correctly
+
+**Duration**: Minutes to hours (typically 30-120 minutes)
+
+**Activities**:
+
+1 - **Write unit tests**: Test individual functions/components
+2 - **Write integration tests**: Test API endpoints or component interactions
+3 - **Run test suite**: Execute all tests
+4 - **Verify acceptance criteria**: Check against plan
+5 - **Document results**: Create test report
+
+**Artifact**: `test-walkthrough.md`
+**Location**: `memory-bank/bolts/{bolt-id}/test-walkthrough.md`
+
+**Template Structure**:
+
+```markdown
+---
+stage: test
+bolt: {bolt-id}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+## Test Report: {unit-name}
+
+### Summary
+
+- **Tests**: {passed}/{total} passed
+- **Coverage**: {percentage}%
+
+### Test Files
+
+- [x] `{path/to/test-file.test.ts}` - {what this test file covers}
+- [x] `{path/to/another.test.ts}` - {what this test file covers}
+
+### Acceptance Criteria Validation
+
+- ✅/❌ **{Criterion}**: {Status}
+
+### Issues Found
+{Any issues discovered during testing}
+
+### Notes
+{Additional observations}
+```
+
+**Completion Criteria**:
+
+- [ ] All tests passing
+- [ ] Acceptance criteria verified
+- [ ] Test report created
+
+**⛔ HUMAN Checkpoint**: Present test report and **STOP**. Wait for user to confirm bolt completion.
+
+---
+
+## State Tracking
+
+Bolt instance tracks progress:
+
+```yaml
+---
+current_stage: implement
+stages_completed:
+  - name: plan
+    completed: 2024-12-05T10:00:00Z
+    artifact: implementation-plan.md
+status: in-progress
+---
+```
+
+---
+
+## Bolt Context Loading
+
+For Stage 2 (Implement) and Stage 3 (Test), load all artifacts from the bolt folder:
+
+**Location**: `memory-bank/bolts/{bolt-id}/`
+
+**Load all files in this folder**, which may include:
+
+- `bolt.md` - Bolt instance metadata
+- `implementation-plan.md` - Plan from Stage 1
+- `implementation-walkthrough.md` - Developer notes from Stage 2 (if exists)
+
+This ensures later stages have full context from earlier work.
+
+---
+
+## Usage by Construction Agent
+
+1. **Load bolt instance** from path defined by `schema.bolts`
+2. **Read `bolt_type` field** (e.g., `simple-construction-bolt`)
+3. **Load this definition** from `.irismd/aidlc/templates/construction/bolt-types/`
+4. **Check `current_stage`** in bolt instance
+5. **Load bolt folder artifacts** if stage requires previous context
+6. **Execute stage** following activities defined here
+7. **Create artifacts** as specified
+8. **⛔ STOP and present completion summary** - DO NOT continue automatically
+9. **Wait for user confirmation** - user must explicitly approve
+10. **Only after approval**: Update bolt state and advance to next stage
+
+**⛔ CRITICAL**: Steps 8-9 are MANDATORY. Never skip the human checkpoint. Never auto-advance.
+
+The Construction Agent is **bolt-type agnostic** - it reads stages from this file and executes them.

package/src/iris_bundle/frameworks/iris-core/src/flows/aidlc/templates/construction/bolt-types/spike-bolt.md

@@ -0,0 +1,240 @@
+# Bolt Type: Spike (Research)
+
+## Mandatory Output Rules (READ FIRST)
+
+- 🚫 **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) 🚫 (blocked)
+
+## Success Metrics
+
+- ✅ Activities presented as numbered lists (not tables)
+- ✅ Stage progress shown with status indicators
+- ✅ Human checkpoints clearly marked
+
+## Failure Modes
+
+- ❌ Using ASCII table for activities
+- ❌ Auto-advancing without human confirmation
+- ❌ Exceeding time-box without approval
+
+---
+
+## Metadata
+
+```yaml
+bolt_type: spike-bolt
+name: Spike Bolt
+description: Research and proof-of-concept for unknown areas
+version: 1.0.0
+suitable_for:
+  - Technical research
+  - Proof of concept
+  - Evaluating technologies
+  - Risk mitigation
+stages_count: 2
+```
+
+---
+
+## Overview
+
+This bolt type is for research and proof-of-concept work when there are unknowns that need investigation before committing to implementation.
+
+**Best For**:
+
+- Evaluating new technologies
+- Proof of concept for risky approaches
+- Research before estimation
+- Validating assumptions
+- Learning and experimentation
+
+**Important**: Spike bolts produce **knowledge**, not production code. The output is documentation, not deployable software.
+
+---
+
+## Stages
+
+### Stage 1: explore
+
+**Objective**: Investigate the unknown area and document findings
+
+**Duration**: Time-boxed (hours to days, strictly limited)
+
+**Activities**:
+
+1 - **Define research questions**: List what needs to be answered
+2 - **Investigate options**: Research and document alternatives
+3 - **Build throwaway prototypes**: Create proof-of-concept code
+4 - **Test assumptions**: Validate or invalidate beliefs
+5 - **Identify risks**: Document potential issues
+6 - **Evaluate trade-offs**: Compare options
+
+**Artifact**: `spike-exploration.md`
+**Location**: Path defined by `schema.units` in `.irismd/aidlc/memory-bank.yaml`
+*(Default: `{intents-path}/{intent}/units/{unit}/spike-exploration.md`)*
+
+**Template Structure**:
+
+```markdown
+---
+stage: explore
+bolt: {bolt-id}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+time_box: {hours}
+---
+
+## Spike Exploration: {topic}
+
+### Research Questions
+1. {question 1}
+2. {question 2}
+
+### Options Investigated
+
+- **{Option}**: {Description} - Pros: {list} - Cons: {list}
+
+### Prototype Notes
+{What was built, what was learned}
+
+### Assumptions Tested
+
+- **{Assumption}**: Valid: {yes/no} - Evidence: {details}
+
+### Risks Identified
+
+- **{Risk}**: Likelihood: {H/M/L} - Impact: {H/M/L} - Mitigation: {approach}
+```
+
+**Completion Criteria**:
+
+- [ ] All research questions addressed
+- [ ] Options evaluated
+- [ ] Prototypes built (if applicable)
+- [ ] Assumptions validated or invalidated
+- [ ] Risks documented
+
+**⛔ HUMAN Checkpoint**: Present exploration summary and **STOP**. Wait for user to confirm before proceeding to Stage 2.
+
+---
+
+### Stage 2: document
+
+**Objective**: Consolidate findings into actionable recommendations
+
+**Duration**: Hours (typically 1-2 hours)
+
+**Activities**:
+
+1 - **Summarize findings**: Create high-level summary
+2 - **Make recommendations**: Propose best approach
+3 - **Estimate implementation**: Provide effort estimates
+4 - **Identify next bolts**: Suggest follow-up work
+5 - **Present to team**: Share knowledge
+
+**Artifact**: `spike-report.md`
+**Location**: Path defined by `schema.units` in `.irismd/aidlc/memory-bank.yaml`
+*(Default: `{intents-path}/{intent}/units/{unit}/spike-report.md`)*
+
+**Template Structure**:
+
+```markdown
+---
+stage: document
+bolt: {bolt-id}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+## Spike Report: {topic}
+
+### Summary
+{High-level summary of what was learned}
+
+### Key Findings
+1. {finding 1}
+2. {finding 2}
+
+### Recommendation
+**Recommended Approach**: {option}
+
+**Rationale**: {why this option}
+
+### Implementation Estimate
+
+- **{Component}**: Effort: {estimate} - Confidence: {H/M/L}
+
+### Risks to Monitor
+
+- **{Risk}**: Mitigation: {strategy}
+
+### Suggested Next Steps
+1. {Create bolt for...}
+2. {Update requirements with...}
+3. {Add story for...}
+
+### Artifacts to Archive
+- [ ] Prototype code (if reusable): {location}
+- [ ] Research notes: {location}
+```
+
+**Completion Criteria**:
+
+- [ ] Findings documented
+- [ ] Clear recommendation made
+- [ ] Estimates provided
+- [ ] Next steps identified
+- [ ] Knowledge shared with team
+
+**⛔ HUMAN Checkpoint**: Present spike report and **STOP**. Wait for user to confirm bolt completion.
+
+---
+
+## Stage Execution
+
+### Sequence
+
+```text
+explore → document
+```
+
+### Time-Boxing
+
+Spikes **MUST** be time-boxed:
+
+- Define maximum duration upfront
+- Stop when time-box expires
+- Document whatever was learned
+- Don't extend without explicit approval
+
+### State Tracking
+
+```yaml
+---
+current_stage: document
+stages_completed:
+  - name: explore
+    completed: 2024-12-05T16:00:00Z
+    time_spent: 4h
+status: in-progress
+time_box: 8h
+time_remaining: 4h
+---
+```
+
+---
+
+## Important Notes
+
+### Spike Output
+
+- **NOT** production code
+- **NOT** deployable software
+- **IS** knowledge and documentation
+- **IS** input for real construction bolts
+
+### After a Spike
+
+1. Review findings with team
+2. Update requirements if needed
+3. Create real construction bolts
+4. Archive or delete prototype code

package/src/iris_bundle/frameworks/iris-core/src/flows/aidlc/templates/construction/construction-log-template.md

@@ -0,0 +1,129 @@
+# Construction Log Template
+
+Use this template to track construction progress and replanning decisions for a unit.
+
+---
+
+## Location
+
+`{intents-path}/{intent}/units/{unit}/construction-log.md`
+
+---
+
+## Template
+
+```markdown
+---
+unit: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+last_updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+# Construction Log: {unit-name}
+
+## Original Plan
+
+**From Inception**: {number} bolts planned
+**Planned Date**: {inception-date}
+
+| Bolt ID | Stories | Type |
+|---------|---------|------|
+| {bolt-1} | {stories} | {type} |
+| {bolt-2} | {stories} | {type} |
+
+## Replanning History
+
+| Date | Action | Change | Reason | Approved |
+|------|--------|--------|--------|----------|
+
+## Current Bolt Structure
+
+| Bolt ID | Stories | Status | Changed |
+|---------|---------|--------|---------|
+| {bolt-1} | {stories} | ✅ completed | - |
+| {bolt-2} | {stories} | ⏳ in-progress | - |
+| {bolt-3} | {stories} | [ ] planned | Split from bolt-2 |
+
+## Execution History
+
+| Date | Bolt | Event | Details |
+|------|------|-------|---------|
+| {date} | {bolt-id} | started | Stage 1: {stage-name} |
+| {date} | {bolt-id} | stage-complete | {stage} → {next-stage} |
+| {date} | {bolt-id} | completed | All {n} stages done |
+
+## Execution Summary
+
+| Metric | Value |
+|--------|-------|
+| Original bolts planned | {n} |
+| Current bolt count | {n} |
+| Bolts completed | {n} |
+| Bolts in progress | {n} |
+| Bolts remaining | {n} |
+| Replanning events | {n} |
+
+## Notes
+
+{Any additional observations or decisions made during construction}
+```
+
+---
+
+## When to Create
+
+Create this file when:
+
+1. First bolt for a unit starts (initialize with original plan)
+2. Any replanning action occurs (append, split, reorder)
+
+---
+
+## When to Update
+
+Update this file when:
+
+1. A bolt starts (add to Execution History, update Current Bolt Structure)
+2. A stage completes (add to Execution History)
+3. A bolt completes (add to Execution History, update Current Bolt Structure, update Execution Summary)
+4. A replanning action occurs (add to Replanning History, update Current Bolt Structure)
+5. Construction completes (add final summary to Notes)
+
+---
+
+## Replanning History Actions
+
+| Action | Description |
+|--------|-------------|
+| `append` | New bolt(s) added to plan |
+| `split` | Existing bolt split into multiple |
+| `reorder` | Execution order changed |
+| `scope-change` | Stories added/removed from bolt |
+
+---
+
+## Example Entries
+
+### Replanning History Example
+
+```markdown
+| Date | Action | Change | Reason | Approved |
+|------|--------|--------|--------|----------|
+| 2025-12-07 | split | bolt-2 → bolt-2, bolt-3 | Scope too large for single bolt | Yes |
+| 2025-12-08 | append | Added bolt-4 | New stories from feedback | Yes |
+| 2025-12-09 | reorder | bolt-4 before bolt-3 | Dependency discovered | Yes |
+```
+
+### Execution History Example
+
+```markdown
+| Date | Bolt | Event | Details |
+|------|------|-------|---------|
+| 2025-12-07 | bolt-auth-1 | started | Stage 1: Model |
+| 2025-12-07 | bolt-auth-1 | stage-complete | Model → Design |
+| 2025-12-07 | bolt-auth-1 | stage-complete | Design → Implement |
+| 2025-12-08 | bolt-auth-1 | stage-complete | Implement → Test |
+| 2025-12-08 | bolt-auth-1 | completed | All 4 stages done |
+| 2025-12-08 | bolt-auth-2 | started | Stage 1: Model |
+```