project-iris 0.0.12 → 0.0.14

package/flows/aidlc/skills/master/analyze-context.md

@@ -0,0 +1,239 @@
+# Skill: Analyze Context
+
+---
+
+## Role
+
+Diagnostic skill to determine current project state by inspecting memory bank artifacts.
+
+**NO Checkpoint** - Analysis is informational, not a decision point.
+
+---
+
+## Goal
+
+Deduce the current project state and recommend the logical next step by inspecting the memory bank artifacts.
+
+---
+
+## Input
+
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+- **Required**: Project artifacts at paths defined in schema
+
+---
+
+## Process
+
+### 1. Load Schema
+
+Read `.iris/aidlc/memory-bank.yaml` to understand artifact paths:
+
+- `schema.intents` - where intents are stored
+- `schema.units` - where units are stored
+- `schema.bolts` - where bolts are stored
+
+### 2. Inspect Intents
+
+List contents of `schema.intents` directory:
+
+- Are there any intent directories?
+- For each intent, what artifacts exist?
+
+### 3. Inspect Units (if intents exist)
+
+For recent/active intents:
+
+- Does `units.md` exist?
+- Does `units/` directory have content?
+- For each unit, are there stories in `stories/`?
+
+### 4. Inspect Bolts (if units exist)
+
+Check `schema.bolts` directory:
+
+- Are there bolt instance files?
+- What is their status? (planned, in-progress, completed)
+- What stage are in-progress bolts at?
+
+### 5. Determine Phase
+
+Based on evidence found:
+
+- **No intents** → Pre-Inception → Create first intent
+- **Intent exists, no requirements.md** → Early Inception → Gather requirements
+- **Requirements exist, no units.md** → Mid Inception → Decompose into units
+- **Units exist, no stories** → Late Inception → Create stories
+- **Stories exist, no bolts** → Inception Complete → Plan bolts
+- **Bolts planned** → Ready for Construction → Start first bolt
+- **Bolts in-progress** → Construction → Continue current bolt
+- **All bolts completed** → Ready for Operations → Deploy unit
+- **Deployed to production** → Operations → Monitor and maintain
+
+### 6. Validate Status Integrity
+
+Check for status inconsistencies across the artifact hierarchy. Status must cascade correctly:
+
+```text
+Bolt complete → Stories complete → Unit complete (if all bolts done) → Intent complete (if all units done)
+```
+
+#### 6.1 Story Status Check
+
+For each completed bolt:
+
+- Read bolt's `stories` array
+- Check each story file's `status` field
+- **Inconsistency**: Bolt complete but story has `status: draft` or `status: in-progress`
+
+#### 6.2 Unit Status Check
+
+For each unit:
+
+- Find all bolts for unit: `memory-bank/bolts/bolt-{unit}-*/bolt.md`
+- Determine expected status:
+  - If ANY bolt `in-progress` → unit should be `in-progress`
+  - If ALL bolts `complete` → unit should be `complete`
+  - If ALL bolts `planned` and at least one story defined → unit should be `stories-defined`
+  - If NO bolts exist but stories exist → unit should be `stories-defined`
+- **Inconsistency**: Unit status doesn't match expected based on bolt states
+
+#### 6.3 Intent Status Check
+
+For each intent:
+
+- Read all unit-briefs: `{intent}/units/*/unit-brief.md`
+- Determine expected status:
+  - If ANY unit `in-progress` → intent should be `construction`
+  - If ALL units `complete` → intent should be `complete`
+  - If units defined but none started → intent should be `units-defined`
+- **Inconsistency**: Intent status doesn't match expected based on unit states
+
+#### 6.4 Report Inconsistencies
+
+If inconsistencies found, report them:
+
+```markdown
+## ⚠️ Status Inconsistencies Detected
+
+| Artifact | Current Status | Expected Status | Reason |
+|----------|----------------|-----------------|--------|
+| unit-brief: file-watcher | draft | complete | All bolts complete |
+| requirements: 011-vscode-extension | units-defined | construction | Has in-progress units |
+
+### Actions
+1 - **fix**: Update all statuses to expected values
+2 - **skip**: Continue without fixing
+3 - **review**: Show details for each inconsistency
+
+**Type 1 to fix inconsistencies, or 2 to skip.**
+```
+
+#### 6.5 Auto-Fix (On User Confirmation)
+
+If user confirms fix:
+
+- Update each artifact's frontmatter `status` field
+- Update `updated` timestamp to current date
+- Log changes to `memory-bank/maintenance-log.md`
+- Report changes made
+
+#### 6.6 Log to Maintenance Log
+
+Append entry to `memory-bank/maintenance-log.md` (create if doesn't exist):
+
+```markdown
+## {ISO-8601-timestamp} - Status Sync
+
+**Triggered by**: analyze-context integrity check
+
+| Artifact | Old Status | New Status | Reason |
+|----------|------------|------------|--------|
+| {path} | {old} | {new} | {reason} |
+
+---
+```
+
+**Example**:
+
+```markdown
+## 2025-12-26T15:30:00Z - Status Sync
+
+**Triggered by**: analyze-context integrity check
+
+| Artifact | Old Status | New Status | Reason |
+|----------|------------|------------|--------|
+| 011-vscode-extension/units/file-watcher/unit-brief.md | draft | complete | All bolts complete (1/1) |
+| 011-vscode-extension/units/extension-core/unit-brief.md | draft | complete | All bolts complete (1/1) |
+| 011-vscode-extension/requirements.md | units-defined | construction | Has in-progress units |
+
+---
+```
+
+---
+
+## Output
+
+Provide a structured analysis:
+
+```markdown
+## Project State Analysis
+
+### Summary
+- **Phase**: {current phase}
+- **Active Intent**: {name or "None"}
+- **Active Unit**: {name or "None"}
+- **Active Bolt**: {id or "None"}
+
+### Evidence
+- Intents found: {count} ({list names})
+- Units found: {count} for {intent}
+- Stories found: {count} for {unit}
+- Bolts found: {count} ({status breakdown})
+
+### Status Integrity
+- ✅ All statuses consistent (or)
+- ⚠️ {N} inconsistencies found (see details below)
+
+### Current State Details
+{Specific details about what exists and what's missing}
+
+{If inconsistencies found, include the inconsistency table here}
+
+### Actions
+
+1 - **proceed**: Execute suggested action
+2 - **explain**: Learn more about current phase
+3 - **different**: Work on something else
+{If inconsistencies: 4 - **fix**: Fix status inconsistencies}
+
+### Suggested Next Step
+→ **proceed** - {Specific command to run}
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Point
+
+> "Based on my analysis, you're in the {phase} phase. Does this match your understanding? If not, tell me what you're trying to accomplish."
+
+---
+
+## Transition
+
+After analysis, either:
+
+- → **Route Request** (`.iris/skills/master/route-request.md`) - to direct user to specialist agent
+- → **Answer Question** (`.iris/skills/master/answer-question.md`) - if user has questions about state
+
+---
+
+## Test Contract
+
+```yaml
+input: Memory bank schema and artifacts
+output: Project state analysis with phase, evidence, and suggested next step
+checkpoints: 0 (informational only)
+```

package/flows/aidlc/skills/master/answer-question.md

@@ -0,0 +1,141 @@
+# Skill: Answer Question
+
+---
+
+## Role
+
+Knowledge retrieval skill to answer questions by querying memory bank artifacts.
+
+**NO Checkpoint** - Answering questions is informational, not a decision point.
+
+---
+
+## Goal
+
+Answer user questions about the project by querying the Memory Bank artifacts.
+
+---
+
+## Input
+
+- **Required**: User's question
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+
+---
+
+## Process
+
+### 1. Parse the Question
+
+Identify what type of information is being requested:
+
+- **Status of intent/unit/bolt** → Check respective artifact files
+- **Configuration/settings** → `{schema.standards}/`
+- **Requirements** → `{intent}/requirements.md`
+- **Architecture decisions** → `{unit}/ddd-02-technical-design.md` or `standards/system-architecture.md`
+- **Deployment info** → `{unit}/deployment/`
+- **Story details** → `{unit}/stories/`
+
+### 2. Search Logic
+
+1. **Extract keywords** from the question
+2. **Locate artifacts** using schema paths from `.iris/aidlc/memory-bank.yaml`
+3. **Read relevant files** to find the answer
+4. **Cite sources** in your response
+
+### 3. Formulate Answer
+
+**If found**:
+
+```markdown
+## Answer
+
+{Direct answer to the question}
+
+**Source**: `{path/to/file.md}`
+```
+
+**If not found**:
+
+```markdown
+## Answer
+
+I couldn't find information about "{topic}" in the memory bank.
+
+**Searched**:
+- `{path1}` - not found
+- `{path2}` - not found
+
+**Suggestions**:
+- Would you like to create this artifact?
+- Is this information stored elsewhere?
+```
+
+---
+
+## Common Questions & Sources
+
+- **"What is the status of {bolt}?"** → `{schema.bolts}` - check `status` field
+- **"What requirements do we have?"** → `{schema.intents}/{intent}/requirements.md`
+- **"What units are in {intent}?"** → `{schema.intents}/{intent}/units.md`
+- **"What stories are in {unit}?"** → `{schema.stories}` directory
+- **"What's the tech stack?"** → `{schema.standards}/tech-stack.md`
+- **"What are our coding standards?"** → `{schema.standards}/coding-standards.md`
+- **"What's the system architecture?"** → `{schema.standards}/system-architecture.md`
+- **"When was {unit} deployed?"** → `{schema.units}/{unit}/deployment/history.md`
+
+---
+
+## Output
+
+```markdown
+## {Question Rephrased}
+
+{Clear, direct answer}
+
+### Details
+{Supporting information if relevant}
+
+### Source
+- `{path/to/source/file.md}`
+
+### Related Information
+- {Other relevant artifacts if any}
+
+### Actions
+
+1 - **more**: Get more details
+2 - **action**: Take action based on this information
+3 - **another**: Ask another question
+
+### Suggested Next Step
+→ **more** - Learn more about {specific aspect}
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Point
+
+> "Does this answer your question? Would you like more details about {specific aspect}?"
+
+---
+
+## Transition
+
+After answering:
+
+- → **Route Request** (`.iris/skills/master/route-request.md`) - if user wants to take action
+- → **Analyze Context** (`.iris/skills/master/analyze-context.md`) - if user wants overall status
+- → Stay in Q&A mode if user has more questions
+
+---
+
+## Test Contract
+
+```yaml
+input: User question
+output: Answer with source citations or acknowledgment of not found
+checkpoints: 0 (informational only)
+```

package/flows/aidlc/skills/master/explain-flow.md

@@ -0,0 +1,158 @@
+# Skill: Explain Flow
+
+---
+
+## Role
+
+Educational skill to explain AI-DLC methodology and help users understand their position in the workflow.
+
+**NO Checkpoint** - Explanation is educational, not a decision point.
+
+---
+
+## Goal
+
+Explain the AI-DLC methodology and help the user understand where they are in the process.
+
+---
+
+## Input
+
+- **Required**: User's question about the flow
+- **Optional**: Current project state (from `analyze-context.md`)
+
+---
+
+## Process
+
+### 1. Provide Overview
+
+```markdown
+## AI-DLC: AI-Driven Development Lifecycle
+
+AI-DLC is a reimagined development methodology where AI drives the workflow and humans validate at key decision points.
+
+### The Three Phases
+
+1. **Inception** → Planning & Design
+   - Capture intents (high-level goals)
+   - Elaborate into requirements, units, and stories
+   - Plan bolts for construction
+   - Output: Complete implementation plan
+
+2. **Construction** → Building & Testing
+   - Execute bolts through their stages (stages vary by bolt type)
+   - AI generates designs, code, and tests
+   - Human validates at each stage
+   - Output: Tested, working code
+
+   **DDD Bolt** (for domain-heavy business logic):
+   - Stage 1: Domain Model → AI models entities, aggregates, events
+   - Stage 2: Technical Design → AI architects layers, APIs, data
+   - Stage 3: ADR Analysis → Capture architectural decisions (optional)
+   - Stage 4: Implement → AI generates code from designs
+   - Stage 5: Test → AI writes and runs tests
+
+   **Simple Bolt** (for straightforward tasks):
+   - Stage 1: Plan → Define what to build
+   - Stage 2: Implement → AI generates code
+   - Stage 3: Test → AI writes and runs tests
+
+3. **Operations** → Deploy & Monitor
+   - Package deployment units
+   - Deploy through environments (Dev → Staging → Prod)
+   - Setup monitoring and observability
+   - Output: Running production system
+
+### Key Concepts
+
+- **Intent**: High-level goal or feature request
+- **Unit**: Independently deployable component (like a bounded context)
+- **Story**: User story with acceptance criteria
+- **Bolt**: Time-boxed execution session (hours/days, not weeks)
+- **Bolt Type**: Methodology template (DDD or Simple)
+
+### Core Principles
+
+- **AI Drives, Human Validates**: AI proposes, humans approve
+- **Human Oversight as Loss Function**: Catch errors early before they compound
+- **Semantically Rich Context**: Each step builds context for the next
+- **Rapid Iteration**: Bolts are hours/days, not weeks
+```
+
+### 2. Show Current Position (if known)
+
+```markdown
+### Where You Are Now
+
+    Inception ──────► Construction ──────► Operations
+        │                  │                   │
+        ▼                  ▼                   ▼
+    [CURRENT] ───────► [Planned] ────────► [Future]
+
+You are in the **{phase}** phase, working on **{intent/unit/bolt}**.
+
+Next step: {specific action}
+
+```
+
+### 3. Answer Specific Questions
+
+- **"What is a bolt?"** → Explain bolt concept with analogy to sprints
+- **"How long does inception take?"** → Hours, not weeks - it's intensive but fast
+- **"When do I move to construction?"** → When all stories are defined and bolts planned
+- **"What's the difference from Agile?"** → AI-DLC is AI-native, rapid iterations, integrated design
+
+---
+
+## Output
+
+Provide a tailored explanation based on the user's question:
+
+```markdown
+## {Topic} Explained
+
+{Clear, concise explanation}
+
+### Your Current Context
+{Where user is in the flow, if known}
+
+### What This Means For You
+{Practical implications}
+
+### Actions
+
+1 - **proceed**: Execute recommended action
+2 - **more**: Learn more about this topic
+3 - **different**: Ask about something else
+
+### Suggested Next Step
+→ **proceed** - {Recommended action}
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Point
+
+> "Does this explanation help? Would you like me to elaborate on any part, or are you ready to proceed with {next action}?"
+
+---
+
+## Transition
+
+After explanation:
+
+- → **Route Request** (`.iris/skills/master/route-request.md`) - if user wants to proceed
+- → **Answer Question** (`.iris/skills/master/answer-question.md`) - if user has more questions
+
+---
+
+## Test Contract
+
+```yaml
+input: User question about AI-DLC flow
+output: Tailored explanation with current position highlighted
+checkpoints: 0 (educational only)
+```