project-iris 0.0.11 → 0.0.12

package/dist/templates/inception/stories-template.md

@@ -0,0 +1,38 @@
+---
+intent: {NNN}-{intent-name}
+phase: inception
+status: stories-created
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+# {Intent Name} - Stories
+
+## User Stories
+
+### Story-1: {Title}
+
+**As a** {user type}
+**I want** {goal}
+**So that** {benefit}
+
+**Acceptance Criteria**:
+
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+
+**Priority**: High/Medium/Low
+**Estimate**: {T-shirt size: S/M/L/XL}
+
+### Story-2: {Title}
+
+...
+
+## Technical Stories
+
+### Tech-Story-1: {Title}
+
+**Description**: {What needs to be done technically}
+**Rationale**: {Why this is needed}
+**Acceptance Criteria**:
+
+- [ ] {Criterion}

package/dist/templates/inception/story-template.md

@@ -0,0 +1,147 @@
+# Story Template
+
+Use this template when creating individual story files during story creation.
+
+---
+
+## Frontmatter
+
+```yaml
+---
+id: {SSS}-{title-slug}
+unit: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
+status: draft
+priority: must|should|could
+created: {YYYY-MM-DDTHH:MM:SSZ}
+assigned_bolt: null
+implemented: false
+---
+```
+
+---
+
+## Content
+
+```markdown
+# Story: {SSS}-{title-slug}
+
+## User Story
+
+**As a** {user role}
+**I want** {goal/action}
+**So that** {benefit/reason}
+
+## Acceptance Criteria
+
+- [ ] **Given** {precondition}, **When** {action}, **Then** {expected outcome}
+- [ ] **Given** {precondition}, **When** {action}, **Then** {expected outcome}
+- [ ] **Given** {precondition}, **When** {action}, **Then** {expected outcome}
+
+## Technical Notes
+
+{Implementation hints, constraints, or considerations}
+
+## Dependencies
+
+### Requires
+- {Other stories this depends on, or "None"}
+
+### Enables
+- {Stories that depend on this, or "None"}
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| {edge case 1} | {behavior} |
+| {edge case 2} | {behavior} |
+
+## Out of Scope
+
+- {What this story does NOT cover}
+```
+
+---
+
+## Priority Levels
+
+| Priority | Meaning | Criteria |
+|----------|---------|----------|
+| `must` | Required for MVP | System unusable without this |
+| `should` | Important | Significant value, not blocking |
+| `could` | Nice to have | Enhances experience |
+
+---
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `draft` | Story written, needs review |
+| `ready` | Reviewed, ready for bolt |
+| `in-progress` | Being implemented in a bolt |
+| `implemented` | Code complete |
+| `tested` | Tests passing |
+| `done` | All acceptance criteria met |
+
+---
+
+## Example
+
+```yaml
+---
+id: 001-user-signup
+unit: 001-auth-service
+intent: 001-user-authentication
+status: ready
+priority: must
+created: 2024-12-05T10:00:00Z
+assigned_bolt: 001-auth-service
+implemented: false
+---
+```
+
+```markdown
+# Story: 001-user-signup
+
+## User Story
+
+**As a** new user
+**I want** to register with my email and password
+**So that** I can access the application
+
+## Acceptance Criteria
+
+- [ ] **Given** I am on the registration page, **When** I enter valid email and password, **Then** my account is created and I receive a confirmation email
+- [ ] **Given** I enter an email that already exists, **When** I submit registration, **Then** I see an error message "Email already registered"
+- [ ] **Given** I enter a password less than 8 characters, **When** I submit, **Then** I see validation error
+
+## Technical Notes
+
+- Password must be hashed with bcrypt (cost factor 12)
+- Email validation should use RFC 5322 compliant regex
+- Rate limit registration to 5 attempts per IP per hour
+
+## Dependencies
+
+### Requires
+- None (first story)
+
+### Enables
+- 002-user-login (User login)
+- 003-email-verification (Email verification)
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| SQL injection in email | Safely escaped, validation fails |
+| Very long email (255+ chars) | Validation error |
+| Unicode in password | Allowed, properly encoded |
+
+## Out of Scope
+
+- Social login (OAuth) - separate story
+- Password reset - separate story
+```

package/dist/templates/inception/system-context-template.md

@@ -0,0 +1,29 @@
+---
+intent: {NNN}-{intent-name}
+phase: inception
+status: context-defined
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+# {Intent Name} - System Context
+
+## System Overview
+
+{High-level description of what we are building}
+
+## Context Diagram
+
+{Mermaid diagram showing System, Users, and External Systems}
+
+## External Integrations
+
+- **System A**: {Purpose of integration}
+- **System B**: {Purpose of integration}
+
+## High-Level Constraints
+
+- {e.g., Must run on AWS, Must use existing Auth provider}
+
+## Key NFR Goals
+
+- {High-level performance/security goals to guide construction}

package/dist/templates/inception/unit-brief-template.md

@@ -0,0 +1,177 @@
+# Unit Brief Template
+
+Use this template when creating unit briefs during decomposition. This is the **critical input for Construction**.
+
+---
+
+## Frontmatter
+
+```yaml
+---
+unit: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
+phase: inception
+status: draft|ready
+created: {YYYY-MM-DDTHH:MM:SSZ}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+```
+
+**Note**: The `unit` field uses the full folder name including the 3-digit prefix (e.g., `001-auth-service`). This matches the folder structure and enables direct path construction in scripts. Story naming uses the story title (e.g., `001-user-signup.md`).
+
+---
+
+## Content
+
+```markdown
+# Unit Brief: {Unit Name}
+
+## Purpose
+
+{Clear, concise statement of what this unit does and why it exists}
+
+## Scope
+
+### In Scope
+- {What this unit IS responsible for}
+- {What this unit IS responsible for}
+
+### Out of Scope
+- {What this unit is NOT responsible for}
+- {What other units handle}
+
+---
+
+## Assigned Requirements
+
+**These FRs from the intent are assigned to this unit. Stories will be created from these.**
+
+| FR | Requirement | Priority |
+|----|-------------|----------|
+| FR-{n} | {description from intent requirements.md} | Must/Should/Could |
+
+---
+
+## Domain Concepts
+
+### Key Entities
+| Entity | Description | Attributes |
+|--------|-------------|------------|
+| {Entity 1} | {What it represents} | {Key properties} |
+| {Entity 2} | {What it represents} | {Key properties} |
+
+### Key Operations
+| Operation | Description | Inputs | Outputs |
+|-----------|-------------|--------|---------|
+| {Operation 1} | {What it does} | {Input data} | {Output data} |
+| {Operation 2} | {What it does} | {Input data} | {Output data} |
+
+---
+
+## Story Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Stories | {n} |
+| Must Have | {n} |
+| Should Have | {n} |
+| Could Have | {n} |
+
+### Stories
+
+| Story ID | Title | Priority | Status |
+|----------|-------|----------|--------|
+| {story-1} | {Title} | Must | Planned |
+| {story-2} | {Title} | Should | Planned |
+
+---
+
+## Dependencies
+
+### Depends On
+| Unit | Reason |
+|------|--------|
+| {unit-name} | {Why this dependency exists} |
+
+### Depended By
+| Unit | Reason |
+|------|--------|
+| {unit-name} | {Why they depend on this} |
+
+### External Dependencies
+| System | Purpose | Risk |
+|--------|---------|------|
+| {External system} | {Why needed} | {Risk level} |
+
+---
+
+## Technical Context
+
+### Suggested Technology
+{Recommendations based on tech stack standards}
+
+### Integration Points
+| Integration | Type | Protocol |
+|-------------|------|----------|
+| {System/Unit} | API/Event/DB | REST/GraphQL/Kafka |
+
+### Data Storage
+| Data | Type | Volume | Retention |
+|------|------|--------|-----------|
+| {Data type} | SQL/NoSQL/Cache | {Volume} | {Retention} |
+
+---
+
+## Constraints
+
+- {Technical constraint specific to this unit}
+- {Business constraint specific to this unit}
+
+---
+
+## Success Criteria
+
+### Functional
+- [ ] {Criterion 1: What must work}
+- [ ] {Criterion 2: What must work}
+
+### Non-Functional
+- [ ] {Performance target}
+- [ ] {Security requirement}
+
+### Quality
+- [ ] Code coverage > 80%
+- [ ] All acceptance criteria met
+- [ ] Code reviewed and approved
+
+---
+
+## Bolt Suggestions
+
+Based on stories and complexity:
+
+| Bolt | Type | Stories | Objective |
+|------|------|---------|-----------|
+| bolt-{unit}-1 | DDD | S1, S2 | Core entities |
+| bolt-{unit}-2 | DDD | S3, S4 | API layer |
+
+---
+
+## Notes
+
+{Any additional context, risks, or considerations for Construction}
+```
+
+---
+
+## Quality Checklist
+
+Before marking unit brief as ready:
+
+- [ ] Purpose is clear and specific
+- [ ] Scope boundaries are defined
+- [ ] Key entities identified
+- [ ] Stories assigned to this unit
+- [ ] Dependencies mapped
+- [ ] Success criteria are measurable
+- [ ] Bolt suggestions provided

package/dist/templates/inception/units-template.md

@@ -0,0 +1,52 @@
+---
+intent: {NNN}-{intent-name}
+phase: inception
+status: units-decomposed
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+# {Intent Name} - Unit Decomposition
+
+## Units Overview
+
+This intent decomposes into {N} units of work:
+
+### Unit 1: {unit-name}
+
+**Description**: {What this unit does}
+
+**Stories**:
+
+- Story-1: {Title}
+- Story-3: {Title}
+
+**Deliverables**:
+
+- {Specific artifacts this unit produces}
+
+**Dependencies**:
+
+- Depends on: {Other units}
+- Depended by: {Units that need this}
+
+**Estimated Complexity**: S/M/L/XL
+
+### Unit 2: {unit-name}
+
+...
+
+## Unit Dependency Graph
+
+```text
+[Unit A] ──> [Unit B] ──> [Unit D]
+   │            │
+   └────> [Unit C] ──┘
+```
+
+## Execution Order
+
+Based on dependencies:
+
+1. Day 1-2: Unit A (foundation)
+2. Day 2-4: Unit B, Unit C (parallel)
+3. Day 5-6: Unit D (integration)

package/dist/workflows/bolt-plan.js

@@ -5,6 +5,9 @@ import fs from "fs";
 import path from "path";
 import { WorkflowStage } from "../bridge/types.js";
 import { appendEvent, saveRun } from "../iris/run-state.js";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 /**
  * Execute Bolt Plan stage
  * Steps:
@@ -18,44 +21,69 @@ export async function executeBoltPlan(runState, connector, options) {
     // Step 1: Generate bolt plan
     console.log(kleur.cyan("→ Generating bolt plan..."));
     const planTaskId = randomUUID();
+    // Load template
+    const templateDir = path.join(__dirname, "../templates/construction");
+    let boltTemplate = "";
+    try {
+        if (fs.existsSync(path.join(templateDir, "bolt-template.md"))) {
+            boltTemplate = fs.readFileSync(path.join(templateDir, "bolt-template.md"), "utf-8");
+        }
+    }
+    catch (e) {
+        console.error("Failed to load bolt template:", e);
+    }
     const planPacket = {
         taskId: planTaskId,
         intent: runState.intent,
         stage: WorkflowStage.BOLT_PLAN,
         agent: "iris-master-agent",
         instructions: `Based on the intent artifacts, create a bolt plan and individual bolt files.
+        
+You must create a DETAILED implementation plan.
 
 Intent: ${runState.intent}
 
 Review the intent artifacts in memory-bank/intents/ to understand requirements.
 
 Create:
-1. memory-bank/operations/bolts/plan.md - Overall implementation plan listing all bolts
-2. memory-bank/operations/bolts/<bolt-id>.md - One file per bolt
-
-Each bolt should be a focused, testable unit of work (e.g., "setup-database", "create-api-endpoint", "build-ui-component").
-
-Bolt file format:
-# Bolt: <Name>
+1. memory-bank/bolts/plan.md - Overall implementation plan listing all bolts
+2. memory-bank/bolts/<bolt-id>/bolt.md - One directory and file per bolt
 
-## Purpose
-Brief description of what this bolt accomplishes
+For each bolt, generate a separate markdown file with:
+1. Rich YAML frontmatter:
+   - id, unit, intent, type, status
+   - stories list
+   - timestamps (created, started, completed)
+   - requires_bolts/enables_bolts arrays
+   - complexity metrics
+2. Full bolt structure:
+   - Overview, Objective, Stories Included
+   - Bolt Type with reference
+   - Stages checklist
+   - Dependencies (Requires/Enables)
+   - Success Criteria
+   - Implementation Notes
 
-## Dependencies
-List any other bolts this depends on
+Analyze dependencies:
+- Identify which bolts must complete before others
+- Set requires_bolts field for dependent bolts
+- Set enables_bolts to show what each bolt unlocks
+- Calculate complexity based on:
+  - avg_complexity: 1-5 (code complexity)
+  - avg_uncertainty: 1-5 (requirements clarity)
+  - max_dependencies: count
+  - testing_scope: 1-5 (testing needed)
 
-## Tasks
-- [ ] Task 1
-- [ ] Task 2
+Use the following Bolt Template EXACTLY for each bolt file:
 
-## Acceptance Criteria
-- Criterion 1
-- Criterion 2
+--- TEMPLATE: bolt.md ---
+${boltTemplate}
+-------------------------
 
 In plan.md, list all bolts in dependency order.`,
         inputs: runState.artifacts,
         expectedOutputs: [
-            "memory-bank/operations/bolts/plan.md"
+            "memory-bank/bolts/plan.md"
         ],
         metadata: { step: "generate_bolt_plan" }
     };
@@ -154,17 +182,17 @@ In plan.md, list all bolts in dependency order.`,
  * Looks for bolt file references or creates default list
  */
 async function parseBoltsFromPlan() {
-    const planPath = path.join(process.cwd(), "memory-bank/operations/bolts/plan.md");
+    const planPath = path.join(process.cwd(), "memory-bank/bolts/plan.md");
     if (!fs.existsSync(planPath)) {
         return [];
     }
     const content = fs.readFileSync(planPath, "utf8");
     const bolts = [];
-    // Look for bolt file references (e.g., "- bolt-name.md" or "1. bolt-name")
-    const boltPattern = /(?:^|\n)(?:\d+\.|[-*])\s+([a-z0-9-]+)(?:\.md)?/gi;
+    // Look for bolt file references (e.g., "- bolt-name" or "1. bolt-name")
+    const boltPattern = /(?:^|\n)(?:\d+\.|[-*])\s+([a-z0-9-]+)(?:\/bolt\.md)?/gi;
     let match;
     while ((match = boltPattern.exec(content)) !== null) {
-        const boltId = match[1].replace(/\.md$/, "");
+        const boltId = match[1].replace(/\/bolt\.md$/, "");
         if (!bolts.find(b => b.id === boltId)) {
             bolts.push({
                 id: boltId,
@@ -172,16 +200,17 @@ async function parseBoltsFromPlan() {
             });
         }
     }
-    // Also check for actual bolt files in the directory
-    const boltsDir = path.join(process.cwd(), "memory-bank/operations/bolts");
+    // Also check for actual bolt directories
+    const boltsDir = path.join(process.cwd(), "memory-bank/bolts");
     if (fs.existsSync(boltsDir)) {
         const files = fs.readdirSync(boltsDir);
         files.forEach(file => {
-            if (file.endsWith(".md") && file !== "plan.md") {
-                const boltId = file.replace(/\.md$/, "");
-                if (!bolts.find(b => b.id === boltId)) {
+            // Check if it's a directory and has bolt.md
+            const boltPath = path.join(boltsDir, file, "bolt.md");
+            if (fs.existsSync(boltPath)) {
+                if (!bolts.find(b => b.id === file)) {
                     bolts.push({
-                        id: boltId,
+                        id: file,
                         status: "pending"
                     });
                 }

package/dist/workflows/intent-inception.js

@@ -1,8 +1,13 @@
 import { randomUUID } from "crypto";
 import inquirer from "inquirer";
 import kleur from "kleur";
+import path from "path";
 import { WorkflowStage } from "../bridge/types.js";
 import { appendEvent, saveRun } from "../iris/run-state.js";
+import fs from "fs";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 /**
  * Execute Intent Inception stage
  * Steps:
@@ -114,17 +119,35 @@ Return ONLY the question string or "DONE". Do not include JSON or explanation.`;
             .replace(/^-|-$/g, "")
             .substring(0, 50);
         const artifactsTaskId = randomUUID();
+        // Load templates
+        const templateDir = path.join(__dirname, "../templates/inception");
+        let templates = {
+            requirements: "",
+            systemContext: "",
+            units: "",
+            unitBrief: "",
+            story: ""
+        };
+        try {
+            if (fs.existsSync(path.join(templateDir, "requirements-template.md"))) {
+                templates.requirements = fs.readFileSync(path.join(templateDir, "requirements-template.md"), "utf-8");
+                templates.systemContext = fs.readFileSync(path.join(templateDir, "system-context-template.md"), "utf-8");
+                templates.units = fs.readFileSync(path.join(templateDir, "units-template.md"), "utf-8");
+                templates.unitBrief = fs.readFileSync(path.join(templateDir, "unit-brief-template.md"), "utf-8");
+                templates.story = fs.readFileSync(path.join(templateDir, "story-template.md"), "utf-8");
+            }
+        }
+        catch (e) {
+            console.error("Failed to load templates:", e);
+        }
         const artifactsPacket = {
             taskId: artifactsTaskId,
             intent: runState.intent,
             stage: WorkflowStage.INTENT_INCEPTION,
             agent: "iris-inception-agent",
-            instructions: `Based on the intent and user answers, create the following intent artifacts:
-
-1. requirements.md - Problem statement, scope, success criteria
-2. system-context.md - Architecture decisions, constraints, tooling
-3. stories.md - User stories or feature breakdown (optional)
-4. units/ - If applicable, identify major units/components
+            instructions: `Based on the intent and user answers, create the following intent artifacts.
+            
+You refer to the templates below. Your job is to fill them out with EXTREME DETAIL based on the user's input.
 
 Intent: ${runState.intent}
 
@@ -133,7 +156,59 @@ ${Object.entries(answers).map(([q, a]) => `Q: ${q}\nA: ${a}`).join("\n\n")}
 
 Create files in: memory-bank/intents/${intentSlug}/
 
-Use the IRIS templates as guidance. Do not use placeholders - write real, specific content based on the intent and answers.`,
+=== INSTRUCTIONS ===
+
+1. **requirements.md**:
+   - Use the TEMPLATE below.
+   - Use "FR-X.Y" numbering for functional requirements.
+   - Use "SHALL", "SHOULD", "MAY" keywords.
+   - Group FRs by feature area.
+   - Include specific metrics for NFRs.
+   - Fill out "Business Goals" with measurable metrics.
+
+2. **system-context.md**:
+   - Use the TEMPLATE below.
+   - Draw a Mermaid diagram for the context.
+   - List specific external integrations.
+
+3. **units.md**:
+   - Decompose the intent into 3-8 logical units.
+   - Each unit should have a clear responsibility.
+   - Define dependencies between units.
+
+4. **unit-brief.md** (for each unit):
+   - Create a directory for each unit: memory-bank/intents/${intentSlug}/units/{unit-name}/
+   - Create unit-brief.md inside.
+   - Use the TEMPLATE below.
+
+5. **stories.md**:
+   - Use the TEMPLATE below.
+   - Create clear user stories and technical stories.
+
+DO NOT use placeholders like "{insert here}". Write REAL content.
+
+=== TEMPLATES ===
+
+--- TEMPLATE: requirements.md ---
+${templates.requirements}
+--------------------------------
+
+--- TEMPLATE: system-context.md ---
+${templates.systemContext}
+----------------------------------
+
+--- TEMPLATE: units.md (Use for listing units) ---
+${templates.units}
+-------------------------------------------------
+
+--- TEMPLATE: unit-brief.md (Use for each unit in units/) ---
+${templates.unitBrief}
+-----------------------------------------------------------
+
+--- TEMPLATE: story.md (Use for each story in unit stories/) ---
+${templates.story}
+--------------------------------------------------------------
+`,
             inputs: [],
             expectedOutputs: [
                 `memory-bank/intents/${intentSlug}/requirements.md`,