project-iris 0.0.12 → 0.0.14

package/flows/aidlc/quick-start.md

@@ -0,0 +1,322 @@
+# iris AI-DLC Quick Start Guide
+
+Get started with AI-Driven Development Lifecycle in minutes.
+
+---
+
+## Installation
+
+```bash
+npx project-iris@latest install
+```
+
+The installer will:
+
+1. Detect available agentic coding tools (Claude Code, Cursor, GitHub Copilot)
+2. Install agent definitions and skills
+3. Set up the memory bank structure
+4. Create slash commands for your tools
+
+---
+
+## Three-Phase Workflow
+
+AI-DLC has three sequential phases, each with a specialized agent:
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| **Inception** | Inception Agent | Capture intents, gather requirements, decompose into units |
+| **Construction** | Construction Agent | Execute bolts (rapid iterations) to build code |
+| **Operations** | Operations Agent | Deploy, verify, and monitor |
+
+The **Master Agent** orchestrates everything and helps you navigate.
+
+---
+
+## Quick Start Flow
+
+### Step 1: Initialize Your Project
+
+Open your AI coding tool (Claude Code, Cursor, etc.) and type this command as a prompt:
+
+```text
+/iris-master-agent
+```
+
+Then type `project-init` or `init` when prompted.
+
+This guides you through:
+
+- **Project type selection** (full-stack, backend API, frontend, CLI, library)
+- **Tech stack decisions** (language, framework, database, ORM)
+- **Coding standards** (formatting, linting, testing strategy)
+- **Optional standards** (architecture, UX guide, API conventions)
+
+Standards are saved to `memory-bank/standards/` and provide context for all AI agents.
+
+### Step 2: Create Your First Intent
+
+Switch to the Inception Agent:
+
+```text
+/iris-inception-agent intent-create
+```
+
+An **Intent** is a high-level goal. Examples:
+
+- "User authentication system"
+- "Product catalog with search"
+- "Payment processing integration"
+
+The agent will:
+
+1. Capture the intent
+2. Elaborate requirements
+3. Define system context
+4. Decompose into units
+
+### Step 3: Plan and Start Bolts
+
+Once units are defined, plan your first bolt:
+
+```text
+/iris-inception-agent bolt-plan
+```
+
+A **Bolt** is a rapid iteration (hours to days). Two types available:
+
+| Bolt Type | Best For |
+|-----------|----------|
+| **DDD Construction** | Complex business logic, domain modeling |
+| **Simple Construction** | UI, integrations, utilities |
+
+### Step 4: Execute Bolts
+
+Switch to the Construction Agent to execute:
+
+```text
+/iris-construction-agent bolt-start
+```
+
+Each bolt type has its own stages:
+
+**DDD Construction Bolt** (for complex business logic):
+
+1. **Domain Model** - Model the business domain
+2. **Technical Design** - Define interfaces and architecture
+3. **ADR Analysis** - Document significant decisions (optional)
+4. **Implement** - Write production code
+5. **Test** - Verify correctness
+
+**Simple Construction Bolt** (for UI, integrations, utilities):
+
+1. **Spec** - Define what to build
+2. **Implement** - Write the code
+3. **Test** - Verify it works
+
+Human validation happens at each stage.
+
+### Step 5: Deploy
+
+When bolts are complete, use the Operations Agent:
+
+```text
+/iris-operations-agent deploy
+```
+
+---
+
+## Agent Commands Reference
+
+### Master Agent (`/iris-master-agent`)
+
+| Skill | Purpose |
+|-------|---------|
+| `project-init` | Initialize project with standards |
+| `analyze-context` | View current project state |
+| `route-request` | Get directed to the right agent |
+| `explain-flow` | Learn about AI-DLC methodology |
+| `answer-question` | Get help with any iris question |
+
+### Inception Agent (`/iris-inception-agent`)
+
+| Skill | Purpose |
+|-------|---------|
+| `intent-create` | Create a new intent |
+| `intent-list` | List all intents |
+| `requirements` | Elaborate intent requirements |
+| `context` | Define system context |
+| `units` | Decompose into units |
+| `story-create` | Create stories for a unit |
+| `bolt-plan` | Plan bolts for stories |
+| `review` | Review inception artifacts |
+| `navigator` | Navigate inception workflow |
+
+### Construction Agent (`/iris-construction-agent`)
+
+| Skill | Purpose |
+|-------|---------|
+| `bolt-start` | Start executing a bolt |
+| `bolt-status` | Check bolt progress |
+| `bolt-list` | List all bolts |
+| `bolt-plan` | Plan additional bolts |
+| `navigator` | Navigate construction workflow |
+
+### Operations Agent (`/iris-operations-agent`)
+
+| Skill | Purpose |
+|-------|---------|
+| `build` | Build the project |
+| `deploy` | Deploy to environment |
+| `verify` | Verify deployment |
+| `monitor` | Set up monitoring |
+
+---
+
+## Project Types
+
+Choose your project type during initialization:
+
+| Type | Required Standards | Recommended Standards |
+|------|-------------------|----------------------|
+| **full-stack-web** | tech-stack, coding-standards | system-architecture, ux-guide, api-conventions |
+| **backend-api** | tech-stack, coding-standards | system-architecture, api-conventions |
+| **frontend-app** | tech-stack, coding-standards | ux-guide |
+| **cli-tool** | tech-stack, coding-standards | - |
+| **library** | tech-stack, coding-standards | api-conventions |
+
+---
+
+## File Structure
+
+After installation, your project will have:
+
+```text
+.iris/
+├── manifest.yaml                 # Installation manifest
+└── aidlc/                        # AI-DLC flow
+    ├── agents/                   # Agent definitions (master, inception, construction, operations)
+    ├── commands/                 # Slash commands for agentic tools
+    ├── skills/                   # Agent skills by phase
+    │   ├── master/               # Master agent skills
+    │   ├── inception/            # Inception phase skills
+    │   ├── construction/         # Construction phase skills
+    │   └── operations/           # Operations phase skills
+    ├── templates/                # Artifact templates
+    │   ├── inception/            # Intent, unit, story templates
+    │   ├── construction/         # Bolt templates and bolt-types
+    │   │   └── bolt-types/       # DDD and Simple bolt definitions
+    │   └── standards/            # Standards facilitation
+    │       ├── catalog.yaml      # Standards registry
+    │       └── *.guide.md        # Facilitation guides
+    ├── shared/                   # Shared agent behaviors
+    ├── memory-bank.yaml          # Memory bank schema
+    ├── context-config.yaml       # Context loading configuration
+    ├── quick-start.md            # This file
+    └── README.md                 # Detailed documentation
+
+memory-bank/                      # Created after project-init
+├── intents/                      # Your captured intents
+│   └── {intent-name}/
+│       ├── requirements.md
+│       ├── system-context.md
+│       ├── units.md
+│       └── units/
+│           └── {unit-name}/
+│               ├── unit-brief.md
+│               └── stories/
+│                   └── {NNN}-{title}.md
+├── bolts/                        # Bolt execution records
+│   └── {bolt-id}/
+│       ├── bolt.md               # Bolt definition
+│       └── {stage-artifacts}.md  # Stage outputs
+├── standards/                    # Your project standards
+│   ├── tech-stack.md
+│   ├── coding-standards.md
+│   └── ...
+└── operations/                   # Deployment context
+```
+
+---
+
+## Key Concepts
+
+### Intent
+
+A high-level statement of purpose. The starting point for AI-driven decomposition.
+
+### Unit
+
+A cohesive, self-contained work element derived from an Intent. Analogous to a Subdomain (DDD) or Epic (Scrum).
+
+### Bolt
+
+The smallest iteration in AI-DLC. Unlike Sprints (weeks), Bolts are hours to days. Two types: DDD Construction and Simple Construction.
+
+### Memory Bank
+
+File-based storage for all project artifacts. Maintains context across agent sessions.
+
+### Standards
+
+Project decisions that inform AI code generation (tech stack, coding style, architecture).
+
+---
+
+## Human Validation
+
+AI-DLC emphasizes human oversight as a "loss function" - catching errors early.
+
+**Key validation points:**
+
+- After requirements elaboration
+- After unit decomposition
+- After story creation
+- After each bolt stage
+- Before deployment
+
+Each validation step transforms artifacts into rich context for subsequent stages.
+
+---
+
+## Tips for Success
+
+1. **Start with standards** - Project-init ensures AI agents understand your preferences
+2. **Keep intents focused** - One major goal per intent
+3. **Validate frequently** - Don't skip human checkpoints
+4. **Use fresh chats** - Each agent invocation starts fresh; context comes from Memory Bank
+5. **Trust the process** - AI-DLC is iterative; refinement happens naturally
+
+---
+
+## Troubleshooting
+
+### Agents don't remember context
+
+Agents are stateless. They read from Memory Bank at startup. Ensure artifacts are saved after each step.
+
+### Standards not being followed
+
+Re-run `project-init` to update standards. Agents load standards fresh each session.
+
+### Reset project state
+
+- Clear `memory-bank/` to reset artifacts
+- Delete `.iris/` to uninstall iris
+
+### Get help
+
+```text
+/iris-master-agent
+# Then type: answer-question "your question here"
+```
+
+---
+
+## What's Next?
+
+1. Run `/iris-master-agent` and type `project-init` to set up your project
+2. Create your first intent with `/iris-inception-agent intent-create`
+3. Follow the guided workflow through Inception → Construction → Operations
+
+Welcome to AI-native development!

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

@@ -0,0 +1,163 @@
+# Skill: List Bolts
+
+---
+
+## Checkpoints in This Skill
+
+| Checkpoint | Purpose | Wait For |
+|------------|---------|----------|
+| Checkpoint 1 | Which bolt to work on? | User selection |
+
+---
+
+## Goal
+
+Display all bolt instances with their status, optionally filtered by unit or intent.
+
+---
+
+## Input
+
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--unit` - filter by unit name
+- **Optional**: `--intent` - filter by intent name
+
+---
+
+## Process
+
+### 1. Load Schema
+
+Read `.iris/aidlc/memory-bank.yaml` to get the `bolts` path.
+*(Default: `memory-bank/bolts/`)*
+
+### 2. Scan Bolt Files
+
+For each bolt directory in `memory-bank/bolts/`:
+
+1. Read `bolt.md` frontmatter for metadata
+2. Extract: id, unit, intent, bolt_type, status, current_stage, stories
+3. The `bolt_type` field indicates which bolt type definition to use for stage information
+
+### 3. Apply Filters
+
+If `--unit` or `--intent` provided:
+
+- Filter bolts to match the specified criteria
+- Show "No bolts found" if none match
+
+### 4. Calculate Progress
+
+For each bolt, determine progress:
+
+- **planned**: 0% - Not started
+- **in-progress**: `stages_completed / total_stages`
+- **completed**: 100%
+- **blocked**: Show blocker reason
+
+### 5. Display Results
+
+Sort bolts by:
+
+1. In-progress first (active work)
+2. Planned (upcoming)
+3. Blocked (needs attention)
+4. Completed (historical)
+
+---
+
+## Output
+
+```markdown
+## Bolts Overview
+
+### Active Bolts
+
+- ⏳ **002-auth-service** (auth-service, {bolt-type}) - Stage: {current-stage}, 2/4 (50%) ← working
+
+### Planned Bolts
+
+- [ ] **003-auth-service** (auth-service) - Stories: 005-*, 006-* - Ready ✅
+- [ ] **004-payment-api** (payment-api) - Stories: 001-*, 002-*, 003-* - Ready ✅
+
+### Blocked Bolts
+
+- 🚫 **005-api-gateway** - Waiting for auth (since 2024-12-04)
+
+### Completed Bolts
+
+- ✅ **001-auth-service** (auth-service) - Completed 2024-12-05 (4 hours)
+
+### Summary
+- **Total**: {n} bolts
+- **In Progress**: {n}
+- **Planned**: {n}
+- **Completed**: {n}
+- **Blocked**: {n}
+
+### Actions
+
+1 - **Continue active bolt**: Resume `002-auth-service`
+2 - **Start planned bolt**: Begin `003-auth-service`
+3 - **View bolt status**: Check detailed status
+4 - **Plan new bolts**: Create additional bolts
+
+**Type a number or bolt ID to continue.**
+```
+
+---
+
+## Output (Filtered)
+
+```markdown
+## Bolts for Unit: {unit-name}
+
+- ✅ **001-{unit-name}** ({bolt-type}) - Completed 100% - Stories: 001-*, 002-*
+- ⏳ **002-{unit-name}** ({bolt-type}) - In progress 50% - Stories: 003-*, 004-* ← current
+- [ ] **003-{unit-name}** ({bolt-type}) - Planned 0% - Stories: 005-*
+
+### Quick Actions
+
+1 - **Continue 002-{unit-name}**: Resume current work
+2 - **View 001-{unit-name} status**: Review completed bolt
+
+**Type a number to continue.**
+```
+
+---
+
+## Bolt Selection
+
+**Checkpoint 1**: Ask user which bolt to work on:
+
+```text
+### Available Bolts
+
+1 - 001-{unit-name} (planned) - Stories: 001-*, 002-*
+2 - 002-{unit-name} (planned) - Stories: 003-*, 004-*
+
+Which bolt would you like to work on?
+```
+
+**Wait for user response.**
+
+**CRITICAL**: Never auto-select a bolt. Always ask which bolt.
+
+---
+
+## Transition
+
+After user selects bolt at Checkpoint 1:
+
+- → **Bolt Start** - execute selected bolt
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name or intent filter
+output: List of bolts with status
+checkpoints: 1
+  - Checkpoint 1: User selects which bolt to work on
+```