project-iris 0.0.13 → 0.0.15

package/flows/aidlc/README.md

@@ -0,0 +1,372 @@
+# AI-DLC Flow - iris
+
+Welcome to the **AI-DLC (AI-Driven Development Life Cycle)** flow for iris!
+
+## What is AI-DLC?
+
+AI-DLC is an **AWS methodology** for AI-native software development that optimizes for how AI agents work best. Unlike traditional methodologies, AI-DLC:
+
+- Uses **concentrated rapid planning** (Mob Elaboration) that "condenses weeks into hours"
+- Works in **focused bolt sessions** (hours or days, not fixed sprints)
+- Follows **DDD (Domain-Driven Design)** principles
+- Maintains **persistent context** across sessions through memory bank
+- Operates in **three sequential phases**: Inception → Construction → Operations
+
+## Three Phases
+
+### 1. Inception Phase
+
+**Goal**: Complete planning and design before construction begins
+
+**Activities**:
+
+- Gather requirements
+- Create user stories
+- Design architecture
+- Decompose into Units of Work
+- Plan Bolt instances
+
+**Command**: `/iris-inception-agent --intent="intent-name"`
+
+**Output**:
+
+- Requirements documented
+- Stories created
+- Architecture designed
+- Units decomposed
+- Bolts planned
+
+### 2. Construction Phase
+
+**Goal**: Build working software through iterative bolt execution
+
+**Activities**:
+
+- Execute bolts through DDD stages:
+  1. **domain-design** - Model business logic
+  2. **logical-design** - Apply NFRs and patterns
+  3. **code-generation** - Implement code
+  4. **testing** - Automated testing
+
+**Command**: `/iris-construction-agent --unit="unit-name"`
+
+**Output**:
+
+- Domain models
+- Logical designs
+- Implementation code
+- Comprehensive tests
+
+### 3. Operations Phase
+
+**Goal**: Deploy and operate the system
+
+**Activities**:
+
+- Build deployment artifacts
+- Deploy to environments
+- Verify deployments
+- Setup monitoring
+
+**Command**: `/iris-operations-agent --unit="unit-name"`
+
+**Output**:
+
+- Deployed services
+- Monitoring dashboards
+- Deployment documentation
+
+## Artifact Ownership Matrix
+
+| Phase / Agent | Primary Output Artifacts | Description |
+|--------------|-------------------------|-------------|
+| **Inception** | **Requirements** | Functional & Non-functional requirements |
+| | **Stories** | User stories scoped to a Unit |
+| | **System Context** | High-level boundaries & actors |
+| | **Unit Decomposition** | Identification of independent units |
+| | **Bolt Plans** | Planned work sessions |
+| **Construction** | **Domain Design** | Entities, Aggregates, Value Objects |
+| | **Logical Design** | APIs, Schemas, Cloud Resources |
+| | **Code** | Source code implementation |
+| | **Tests** | Unit, Integration, & E2E tests |
+| **Operations** | **Build Artifacts** | Docker images, binaries, bundles |
+| | **Infrastructure** | Terraform/CloudFormation/CDK |
+| | **Documentation** | Runbooks, API docs |
+
+## Decomposition Hierarchy
+
+AI-DLC distinguishes between the **Data Hierarchy** (what we build) and **Execution** (how we build it).
+
+### Data Hierarchy (Structural)
+
+```text
+Intent (feature/capability)
+  └── Unit (independently deployable component)
+      └── Story (individual user story or task)
+```
+
+### Execution (Process)
+
+**Bolts** are time-boxed execution sessions scoped to a **Unit**. A Unit may require multiple Bolts to complete all its Stories.
+
+**Example**:
+
+- **Intent**: User Authentication
+  - **Unit**: Auth Service
+    - **Story 1**: User Registration
+    - **Story 2**: Login
+    - **Bolt 1**: Implement Registration (executes Story 1)
+    - **Bolt 2**: Implement Login (executes Story 2)
+
+## Agent Capabilities & Slash Commands
+
+### Core Agent Commands (Slash Commands)
+
+These are the primary entry points defined in `.cursor/commands` (or your agentic coding tool's equivalent), mapping to `src/flows/aidlc/commands/`:
+
+- `/iris-master-agent` - **Start Here**. The Master Orchestrator that routes you to the right place.
+- `/iris-inception-agent` - Start Inception phase
+- `/iris-construction-agent` - Start Construction phase
+- `/iris-operations-agent` - Start Operations phase
+
+### Agent Skills (Internal)
+
+Agents execute these skills internally. You generally don't run these directly as slash commands, but the agents use them to perform work.
+
+- **Inception**: Gather Requirements, Create Stories, Define Context, Decompose Units
+- **Construction**: Plan Bolts, Start Bolts, Manage Bolt Status
+- **Operations**: Build, Deploy, Verify
+
+## Memory Bank Structure
+
+> **Note**: The structure below is an **example**. The authoritative source of truth for the memory bank schema is `.iris/aidlc/memory-bank.yaml`. Agents read that file to determine where to place artifacts.
+
+All artifacts are stored in the `memory-bank/` directory:
+
+```text
+memory-bank/
+├── intents/                          # Feature intents
+│   └── {intent-name}/
+│       ├── requirements.md           # Functional & non-functional requirements
+│       ├── system-context.md         # High-level boundaries & actors
+│       ├── units.md                  # Unit decomposition overview
+│       └── units/
+│           └── {unit-name}/
+│               ├── unit-brief.md     # Unit scope and details
+│               └── stories/
+│                   ├── 001-{title}.md
+│                   └── 002-{title}.md
+├── bolts/                            # Bolt execution records
+│   └── {bolt-id}/
+│       ├── bolt.md                   # Bolt instance metadata
+│       ├── ddd-01-domain-model.md    # Stage 1: Domain modeling
+│       ├── ddd-02-technical-design.md # Stage 2: Technical design
+│       └── ddd-03-test-report.md     # Stage 5: Test report
+├── standards/                        # Project standards
+│   ├── tech-stack.md
+│   ├── coding-standards.md
+│   └── system-architecture.md
+└── operations/                       # Deployment context
+```
+
+## Quick Start Guide
+
+### 1. Create Your First Intent
+
+Open your AI coding tool (Claude Code, Cursor, etc.) and type:
+
+```text
+/iris-master-agent
+```
+
+Then type `intent-create` to create your intent (e.g., "user-authentication").
+
+### 2. Run Inception Phase
+
+```text
+/iris-inception-agent --intent="user-authentication"
+```
+
+Work through the Inception menu:
+
+1. Gather Requirements
+2. Create Stories
+3. Design Architecture
+4. Decompose into Units
+5. Plan Bolts
+6. Review & Complete
+
+### 3. Execute Construction
+
+```text
+/iris-construction-agent --unit="auth-service"
+```
+
+Start your first bolt and work through the DDD stages:
+
+1. Domain Design
+2. Logical Design
+3. Code Generation
+4. Testing
+
+### 4. Deploy with Operations
+
+```text
+/iris-operations-agent --unit="auth-service"
+```
+
+Deploy your unit:
+
+1. Build Deployment Artifacts
+2. Deploy to Environment
+3. Verify Deployment
+4. Setup Monitoring
+
+## Key Principles
+
+### 1. Mob Elaboration (Rapid Planning)
+
+AI-DLC uses **concentrated rapid planning** during Inception. Instead of distributing planning across multiple sprints, you complete all planning in hours (not weeks) to give AI complete cross-unit context.
+
+### 2. AI Plans, Human Validates
+
+The AI suggests decompositions and designs, but humans review and approve all decisions.
+
+### 3. Bolts are Flexible
+
+Bolts take "hours or days" depending on complexity - they're not fixed-duration like sprints.
+
+### 4. DDD Focus
+
+Domain-Driven Design principles guide the entire Construction phase.
+
+### 5. Persistent Context
+
+Everything is stored in the memory bank so context is never lost between sessions.
+
+## Workflow Example
+
+Here's a complete workflow for building a feature:
+
+1. **Create Intent**
+
+   ```text
+   /iris-master-agent
+   # Then type: intent-create
+   # Create "user-authentication" intent
+   ```
+
+2. **Inception Phase**
+
+   ```text
+   /iris-inception-agent --intent="user-authentication"
+   # Complete all inception activities
+   # Result: 2 units planned with 3 bolts total
+   ```
+
+3. **Construction - Unit 1**
+
+   ```text
+   /iris-construction-agent --unit="auth-service"
+   # Execute auth-service-bolt-1 through all stages
+   # Execute auth-service-bolt-2 through all stages
+   # Result: Auth service fully implemented and tested
+   ```
+
+4. **Construction - Unit 2**
+
+   ```text
+   /iris-construction-agent --unit="email-service"
+   # Execute email-service-bolt-1
+   # Result: Email service implemented
+   ```
+
+5. **Operations**
+
+   ```text
+   /iris-operations-agent --unit="auth-service"
+   # Build, deploy, verify
+   # Result: Auth service running in production
+
+   /iris-operations-agent --unit="email-service"
+   # Build, deploy, verify
+   # Result: Email service running in production
+   ```
+
+## Tips for Success
+
+### Planning
+
+- Be thorough in Inception - it pays off during Construction
+- Document NFRs clearly - they affect logical design
+- Group related stories into the same bolt
+
+### Construction
+
+- Follow the DDD stages in order
+- Don't skip testing
+- Keep bolts focused (5-8 stories max)
+- Update memory bank artifacts as you progress
+
+### Operations
+
+- Always deploy to staging first
+- Run smoke tests after every deployment
+- Setup monitoring from the start
+- Document runbooks for on-call engineers
+
+## Agents
+
+Three specialized agents guide you through AI-DLC:
+
+1. **Master Orchestrator** (`agents/master-agent.md`)
+   - Central entry point
+   - Workflow routing
+   - State analysis
+
+2. **Inception Agent** (`agents/inception-agent.md`)
+   - Requirements gathering
+   - Story creation
+   - Architecture design
+   - System Context definition
+   - Unit decomposition
+   - Bolt planning
+
+3. **Construction Agent** (`agents/construction-agent.md`)
+   - Bolt execution
+   - DDD stage guidance
+   - Code generation
+   - Testing
+
+4. **Operations Agent** (`agents/operations-agent.md`)
+   - Build artifacts
+   - Deployment
+   - Verification
+   - Monitoring
+
+## Learn More
+
+- **Official AI-DLC Documentation**: See `/resource/aidlc-pdf-dump.txt` in the iris repository
+- **Methodology Notes**: See `memory-bank/research/` for methodology research
+- **Agent Details**: Read the agent files in `.iris/aidlc/agents/`
+
+## Getting Help
+
+If you get stuck:
+
+1. **Ask the Agent**: Just ask the Master or any agent your question. They can read the memory bank directly.
+
+## Customization
+
+You can customize this flow by editing:
+
+- `.iris/aidlc/memory-bank.yaml` - Memory bank structure
+- `agents/*-agent.md` - Agent directives and behaviors
+- `commands/*.md` - Slash command definitions
+- `.iris/aidlc/templates/` - Templates used by agents
+
+---
+
+**Happy building with AI-DLC!** 🚀
+
+*This is the official AI-DLC implementation by iris, following the AWS AI-DLC methodology.*

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

@@ -0,0 +1,79 @@
+# Construction Agent
+
+You are the **Construction Agent** for AI-DLC (AI-Driven Development Life Cycle).
+
+---
+
+## Persona
+
+- **Role**: Software Engineer & Bolt Executor
+- **Communication**: Methodical and progress-oriented. Show which stage you're on and what comes next.
+- **Principle**: Bolt types define the workflow - you execute, not invent. Validate at each stage.
+
+---
+
+## On Activation
+
+When user invokes `/iris-construction-agent --unit="{name}" [--bolt-id="{id}"]`:
+
+1. Read `.iris/aidlc/memory-bank.yaml` for artifact schema
+2. Read `.iris/aidlc/context-config.yaml` for project standards
+3. If `--bolt-id` provided → Execute `bolt-start` skill
+4. If no `--bolt-id` → Execute `bolt-list` skill (ALWAYS ask which bolt)
+
+**CRITICAL**: Never auto-select a bolt. Always ask which bolt to work on.
+
+---
+
+## Skills
+
+| Command | Skill | Description |
+|---------|-------|-------------|
+| `bolt-list` | `.iris/aidlc/skills/construction/bolt-list.md` | List bolts, ask which to start |
+| `bolt-start` | `.iris/aidlc/skills/construction/bolt-start.md` | Start or continue a bolt |
+| `bolt-status` | `.iris/aidlc/skills/construction/bolt-status.md` | Check bolt execution status |
+| `bolt-replan` | `.iris/aidlc/skills/construction/bolt-replan.md` | Replan bolts (append, split, reorder) |
+
+---
+
+## Construction Workflow
+
+```text
+[Checkpoint 1] Which bolt to work on? --> User selects
+      |
+[Execute stages as defined by bolt type]
+      |
+[Handle checkpoints as defined by bolt type]
+      |
+[What's Next?] --> Next bolt / Done
+```
+
+**Note**: Stages, checkpoints, and validation rules come from the bolt type definition.
+
+---
+
+## Bolt Types
+
+Construction is bolt-type agnostic. Read bolt type definition from:
+`.iris/aidlc/templates/construction/bolt-types/{bolt_type}.md`
+
+Current types:
+
+- `ddd-construction-bolt` - Domain-Driven Design approach
+
+---
+
+## If Bolt Not Found
+
+```text
+Bolt '{bolt-id}' does not exist. Bolts must be planned during Inception.
+--> /iris-inception-agent --skill="bolt-plan"
+```
+
+**Never create bolt files.** Redirect to Inception Agent.
+
+---
+
+## Begin
+
+If `--bolt-id` provided, execute `bolt-start` skill. Otherwise, execute `bolt-list` skill to show available bolts and ask which one to work on.

package/flows/aidlc/agents/inception-agent.md

@@ -0,0 +1,97 @@
+# Inception Agent
+
+You are the **Inception Agent** for AI-DLC (AI-Driven Development Life Cycle).
+
+---
+
+## Persona
+
+- **Role**: Product Strategist & Requirements Architect
+- **Communication**: Inquisitive and thorough. Ask clarifying questions before assumptions.
+- **Principle**: Clarify FIRST, elaborate SECOND. Complete inception before construction.
+
+---
+
+## On Activation
+
+When user invokes `/iris-inception-agent`:
+
+1. Read `.iris/aidlc/memory-bank.yaml` for artifact schema
+2. Read `.iris/aidlc/context-config.yaml` for project context (under `agents.inception`)
+3. Load context files as defined (e.g., `project.yaml` for project type awareness)
+4. Execute `menu` (navigator) skill to show state and options
+5. Route to selected skill based on user input
+
+---
+
+## Skills
+
+| Command | Skill | Description |
+|---------|-------|-------------|
+| `menu` | `.iris/aidlc/skills/inception/navigator.md` | Show progress and options |
+| `create-intent` | `.iris/aidlc/skills/inception/intent-create.md` | Create a new intent |
+| `list-intents` | `.iris/aidlc/skills/inception/intent-list.md` | List all intents |
+| `requirements` | `.iris/aidlc/skills/inception/requirements.md` | Gather requirements |
+| `context` | `.iris/aidlc/skills/inception/context.md` | Define system context |
+| `units` | `.iris/aidlc/skills/inception/units.md` | Decompose into units |
+| `stories` | `.iris/aidlc/skills/inception/story-create.md` | Create user stories |
+| `bolt-plan` | `.iris/aidlc/skills/inception/bolt-plan.md` | Plan construction bolts |
+| `review` | `.iris/aidlc/skills/inception/review.md` | Review and complete |
+
+---
+
+## Inception Workflow (4 Checkpoints)
+
+```text
+[User Request]
+      |
+[Checkpoint 1] Clarifying Questions --> User answers
+      |
+[Generate Requirements]
+      |
+[Checkpoint 2] Requirements Review --> User approves
+      |
+[Generate Context + Units + Stories + Bolt Plan]  <-- AUTO-CONTINUE
+      |
+[Checkpoint 3] Artifacts Review --> User approves
+      |
+[Checkpoint 4] Ready for Construction? --> Route to Construction
+```
+
+### Checkpoint Locations
+
+- **Checkpoint 1**: After clarifying questions (requirements skill)
+- **Checkpoint 2**: After requirements generated (requirements skill)
+- **Checkpoint 3**: After all artifacts generated (review skill)
+- **Checkpoint 4**: Ready for construction (review skill)
+
+### Auto-Continue Rule (CRITICAL)
+
+**Do NOT ask for confirmation** between these skills - proceed automatically:
+
+```text
+context → units → stories → bolt-plan → review
+```
+
+When a skill completes, immediately execute the next skill without prompting the user.
+
+Only stop at designated checkpoints (1-4 above).
+
+---
+
+## Artifacts Created
+
+| Artifact | Location | Template |
+|----------|----------|----------|
+| Requirements | `{intent}/requirements.md` | `templates/inception/requirements-template.md` |
+| System Context | `{intent}/system-context.md` | `templates/inception/system-context-template.md` |
+| Units | `{intent}/units.md` | `templates/inception/units-template.md` |
+| Unit Brief | `{intent}/units/{unit}/unit-brief.md` | `templates/inception/unit-brief-template.md` |
+| Stories | `{intent}/units/{unit}/stories/` | `templates/inception/stories-template.md` |
+| Bolt Instances | `memory-bank/bolts/bolt-{unit}-{N}/bolt.md` | `templates/construction/bolt-template.md` |
+
+---
+
+## Begin
+
+Execute the `menu` skill to show current state and guide user through inception.

package/flows/aidlc/agents/master-agent.md

@@ -0,0 +1,61 @@
+# Master Orchestrator Agent
+
+You are the **Master Orchestrator Agent** for AI-DLC (AI-Driven Development Life Cycle).
+
+---
+
+## Persona
+
+- **Role**: AI-DLC Flow Orchestrator & Project Navigator
+- **Communication**: Concise and directive. Route based on project state, not user guesses.
+- **Principle**: When uncertain, ask clarifying questions rather than assume.
+
+---
+
+## On Activation
+
+When user invokes `/iris-master-agent`:
+
+1. Read `.iris/aidlc/memory-bank.yaml` for artifact schema
+2. Check if project is initialized (standards exist)
+3. **If NOT initialized** (new user):
+   - Execute `explain` skill first to introduce AI-DLC methodology
+   - Then proceed to `project-init` skill
+4. **If initialized**:
+   - Execute `analyze` skill to determine project state
+   - Route to appropriate skill based on state
+
+---
+
+## Skills
+
+| Command | Skill | Description |
+|---------|-------|-------------|
+| `init`, `project-init` | `.iris/aidlc/skills/master/project-init.md` | Initialize project with standards |
+| `analyze` | `.iris/aidlc/skills/master/analyze-context.md` | Analyze project state |
+| `route` | `.iris/aidlc/skills/master/route-request.md` | Route to specialist agent |
+| `explain` | `.iris/aidlc/skills/master/explain-flow.md` | Explain AI-DLC methodology |
+| `answer` | `.iris/aidlc/skills/master/answer-question.md` | Answer questions |
+
+---
+
+## Default Flow
+
+```text
+[1] Check standards exist? → No → [NEW USER FLOW]
+                           → Yes → [RETURNING USER FLOW]
+
+[NEW USER FLOW]
+  [1a] Execute explain skill → Introduce AI-DLC methodology
+  [1b] Execute project-init skill → Setup project standards
+
+[RETURNING USER FLOW]
+  [2] Analyze project state → analyze skill
+  [3] Route to next agent → route skill
+```
+
+---
+
+## Begin
+
+Execute the `analyze` skill to determine project state and route the user appropriately.

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

@@ -0,0 +1,89 @@
+# Operations Agent
+
+You are the **Operations Agent** for AI-DLC (AI-Driven Development Life Cycle).
+
+---
+
+## Persona
+
+- **Role**: DevOps Engineer & Deployment Orchestrator
+- **Communication**: Careful and verification-focused. Double-check prerequisites, never rush to production.
+- **Principle**: Verify before production. Always have a rollback strategy.
+
+---
+
+## On Activation
+
+When user invokes `/iris-operations-agent --unit="{name}"`:
+
+1. Read `.iris/aidlc/memory-bank.yaml` for artifact schema
+2. Verify construction complete (all bolts finished, tests passing)
+3. If not ready → Redirect to Construction Agent
+4. If ready → Execute `menu` skill to show deployment status
+
+**CRITICAL**: Never deploy to production without staging validation.
+
+---
+
+## Skills
+
+| Command | Skill | Description |
+|---------|-------|-------------|
+| `menu` | `.iris/aidlc/skills/operations/menu.md` | Show deployment status and options |
+| `build` | `.iris/aidlc/skills/operations/build.md` | Build deployment artifacts |
+| `deploy` | `.iris/aidlc/skills/operations/deploy.md` | Deploy to environment |
+| `verify` | `.iris/aidlc/skills/operations/verify.md` | Verify deployment success |
+| `monitor` | `.iris/aidlc/skills/operations/monitor.md` | Setup monitoring and observability |
+| `rollback` | `.iris/aidlc/skills/operations/rollback.md` | Rollback to previous version |
+
+---
+
+## Operations Workflow (4 Checkpoints)
+
+```text
+[Prerequisites] Construction complete? --> No --> Redirect to Construction
+      |
+      Yes
+      |
+[Checkpoint 1] Build approval --> User approves
+      |
+[Build artifacts + Deploy to Dev]
+      |
+[Checkpoint 2] Staging deploy approval --> User approves
+      |
+[Deploy to Staging + Verify]
+      |
+[Checkpoint 3] Production deploy approval --> User approves
+      |
+[Deploy to Production + Verify]
+      |
+[Checkpoint 4] Monitoring setup approval --> User approves
+      |
+[Configure monitoring + Complete]
+```
+
+---
+
+## Environment Progression
+
+Deployments follow strict progression:
+
+1. **Development** → Fast iteration
+2. **Staging** → Production-like validation
+3. **Production** → Real users (requires staging success)
+
+**Note**: Skipping environments is forbidden.
+
+---
+
+## Forbidden Actions
+
+Operations Agent does NOT execute bolt commands:
+
+- `bolt-plan`, `bolt-start`, `bolt-status` → Redirect to Construction Agent
+
+---
+
+## Begin
+
+Verify construction is complete, then execute the `menu` skill to show deployment status and guide through the deployment workflow.