iris

AI-native software development with multi-agent orchestration.

iris implements the AI-Driven Development Lifecycle (AI-DLC) methodology as a set of markdown-based agents that work with your favorite AI coding tools.

What is AI-DLC?

AI-DLC is a reimagined software development methodology where AI drives the conversation and humans validate. Unlike traditional Agile where iterations span weeks, AI-DLC operates in Bolts - rapid iterations measured in hours or days.

"Traditional development methods were built for human-driven, long-running processes. AI-DLC reimagines the development lifecycle with AI as a central collaborator, enabling rapid cycles measured in hours or days rather than weeks."

AI-DLC vs Traditional Methods

| Aspect | Agile/Scrum | AI-DLC | |--------|-------------|--------| | Iteration duration | Weeks (Sprints) | Hours/days (Bolts) | | Who drives | Human-driven, AI assists | AI-driven, human-validated | | Design techniques | Out of scope | Integrated (DDD, TDD, BDD) | | Task decomposition | Manual | AI-powered | | Phases | Repeating sprints | Rapid three-phase cycles (Inception → Construction → Operations) | | Rituals | Daily standups, retrospectives | Mob Elaboration, Mob Construction |

How It Works

iris provides four specialized agents that guide you through the entire development lifecycle:

                    ┌─────────────────┐
                    │  Master Agent   │  Orchestrates & navigates
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│   Inception   │ → │ Construction  │ → │  Operations   │
│     Agent     │   │     Agent     │   │     Agent     │
└───────────────┘   └───────────────┘   └───────────────┘
  Capture intent      Execute bolts      Deploy & monitor
  Define units        Build & test       Verify & scale
  Plan stories        Validate stages

The Three Phases

| Phase | Agent | Purpose | Key Outputs | |-------|-------|---------|-------------| | Inception | Inception Agent | Capture intents, elaborate requirements, decompose into units | User stories, NFRs, Unit definitions, Bolt plans | | Construction | Construction Agent | Execute bolts through Domain Design → Logical Design → Code Generation → Testing | Domain designs, Logical designs, Code, Tests | | Operations | Operations Agent | Deploy, verify, and monitor | Deployment units, Monitoring, Runbooks |

Quick Start

Installation

npx project-iris install

The installer detects your AI coding tools (Claude Code, Cursor, GitHub Copilot) and sets up:

• Agent definitions and skills
• Memory bank structure for context persistence
• Slash commands for easy agent invocation

Initialize Your Project

# Start the Master Agent
/iris-master-agent

# Then type:
project-init

This guides you through establishing:

• Tech Stack - Languages, frameworks, databases, infrastructure
• Coding Standards - Formatting, linting, naming, testing strategy
• System Architecture - Architecture style, API design, state management
• UX Guide - Design system, styling, accessibility (optional)
• API Conventions - API style, versioning, response formats (optional)

Create Your First Intent

/iris-inception-agent intent-create

An Intent is your high-level goal:

• "User authentication system"
• "Product catalog with search"
• "Payment processing integration"

The agent will:

1. Ask clarifying questions to minimize ambiguity
2. Elaborate into user stories and NFRs
3. Define system context
4. Decompose into loosely-coupled units

Plan and Execute Bolts

# Plan bolts for your stories
/iris-inception-agent bolt-plan

# Execute a bolt
/iris-construction-agent bolt-start

Each bolt goes through validated stages:

1. Domain Design - Model business logic using DDD principles
2. Logical Design - Apply patterns and make architecture decisions
3. ADR Analysis - Document significant decisions (optional)
4. Code Generation - Generate production code
5. Testing - Verify correctness with automated tests

Human validation happens at each stage gate.

Project Scenarios

iris supports both new projects and existing codebases.

Greenfield (New Projects)

Starting fresh with no existing code:

/iris-master-agent
# Then type: project-init

1. Initialize project with standards (tech stack, coding standards, architecture)
2. Begin Inception phase immediately
3. Build from scratch using AI-DLC methodology

Brownfield (Existing Codebases)

Adding features to an existing codebase requires understanding what's already there:

/iris-master-agent
# Then type: code-elevate

Code Elevation analyzes your existing codebase and creates:

• Static Model (memory-bank/elevation/static-model.md)

  • Components and their responsibilities
  • Relationships between components
  • Key abstractions and patterns used

• Dynamic Model (memory-bank/elevation/dynamic-model.md)

  • How components interact for significant use cases
  • Request/response flows
  • Event chains and data transformations

After code elevation, agents have full context about your existing architecture, enabling them to:

• Propose changes that fit existing patterns
• Identify integration points for new features
• Avoid breaking existing functionality

Key Concepts

Intent

A high-level statement of purpose that encapsulates what needs to be achieved - whether a business goal, feature, or technical outcome. It serves as the starting point for AI-driven decomposition.

Unit

A cohesive, self-contained work element derived from an Intent. Units are loosely coupled and can be developed independently. Analogous to a Subdomain (DDD) or Epic (Scrum).

Bolt

The smallest iteration in AI-DLC, designed for rapid implementation. Unlike Sprints (weeks), Bolts are hours to days. Each bolt encapsulates a well-defined scope of work.

| Type | Best For | Stages | |------|----------|--------| | DDD Construction | Complex business logic, domain modeling | Domain Design → Logical Design → ADR → Code Generation → Testing | | Simple Construction | UI, integrations, utilities | Plan → Code Generation → Testing |

Memory Bank

File-based storage for all project artifacts. Maintains context across agent sessions and provides traceability between artifacts.

Standards

Project decisions that inform AI code generation. Standards ensure consistency across all generated code and documentation.

Project Structure

After installation:

.iris/
├── manifest.yaml              # Installation manifest
└── aidlc/                     # AI-DLC flow
    ├── agents/                # Agent definitions
    ├── skills/                # Agent capabilities
    ├── templates/             # Artifact templates
    │   └── standards/         # Standards facilitation guides
    └── memory-bank.yaml       # Memory bank schema

memory-bank/                   # Created after project-init
├── project.yaml               # Project configuration
│
├── elevation/                 # Brownfield code analysis (if applicable)
│   ├── static-model.md        # Components, responsibilities, relationships
│   └── dynamic-model.md       # Use case interactions
│
├── intents/                   # Your captured intents
│   └── {NNN}-{intent-name}/
│       ├── requirements.md    # Functional & non-functional requirements
│       ├── prfaq.md           # Press Release / FAQ
│       ├── risks.md           # Risk assessment
│       ├── system-context.md  # System boundaries & actors
│       ├── units.md           # Unit decomposition overview
│       └── units/
│           └── {UUU}-{unit-name}/
│               ├── unit-brief.md
│               └── stories/
│
├── bolts/                     # Bolt execution records
│   └── {BBB}-{unit-name}/
│       ├── bolt.md            # Bolt instance metadata
│       ├── ddd-01-domain-design.md
│       ├── ddd-02-logical-design.md
│       ├── adr-{N}-{slug}.md  # ADR (optional)
│       └── ddd-03-test-report.md
│
├── standards/                 # Project standards
│   ├── tech-stack.md
│   ├── coding-standards.md
│   └── system-architecture.md
│
└── operations/                # Deployment context
    ├── deployment-units/
    └── playbooks/

Agent Commands

Master Agent

/iris-master-agent

| Command | Purpose | |---------|---------| | project-init | Initialize project with standards | | code-elevate | Analyze existing codebase (brownfield) | | 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

| Command | Purpose | |---------|---------| | intent-create | Create a new intent with PRFAQ | | intent-list | List all intents | | requirements | Gather requirements with measurements | | risks | Assess risks with mitigations | | 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 |

Construction Agent

/iris-construction-agent

| Command | Purpose | |---------|---------| | bolt-start | Start/continue executing a bolt | | bolt-status | Check bolt progress | | bolt-list | List all bolts | | bolt-replan | Replan bolts if needed |

Operations Agent

/iris-operations-agent

| Command | Purpose | |---------|---------| | build | Build deployment artifacts | | deploy | Deploy to environment | | verify | Verify deployment | | monitor | Set up monitoring and SLOs | | rollback | Rollback to previous version |

Why iris?

AI-Native, Not AI-Retrofitted

Built from the ground up for AI-driven development. AI-DLC is a reimagination based on first principles, not a retrofit of existing methods.

Human Oversight as Loss Function

Validation at each stage catches errors early before they cascade downstream. Each validation transforms artifacts into rich context for subsequent stages.

Design Techniques Built-In

DDD, TDD, and BDD are integral to the methodology - not optional add-ons. This addresses the "whitespace" in Agile that has led to quality issues.

Tool Agnostic

Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere.

Context Engineering

Specs and Memory Bank provide structured context for AI agents. Agents reload context each session - no more lost knowledge.

Supported Tools

| Tool | Status | Installation | |------|--------|--------------| | Claude Code | Full support | Slash commands in .claude/commands/ | | Cursor | Full support | Rules in .cursor/rules/ (.mdc format) | | GitHub Copilot | Full support | Agents in .github/agents/ (.agent.md format) | | Google Antigravity | Full support | Agents in .agent/agents/ |

FAQ

Q: Agents don't seem to remember previous context? Each agent invocation starts fresh. Agents read context from the Memory Bank at startup. Ensure artifacts are saved after each step.

Q: How do I reset project state? Clear the memory-bank/ directory to reset all artifacts. To remove iris entirely, delete the .iris/ directory and tool-specific command files.

Q: Can I use iris with existing Agile workflows? AI-DLC is designed as a reimagination, not a retrofit. However, familiar concepts (user stories, acceptance criteria) are retained to ease transition.

Q: What project types is this suited for? iris is designed for building complex systems that demand architectural complexity, trade-off management, and scalability. Simpler systems may be better suited for low-code/no-code approaches.

Resources

• AI-DLC Specification (AWS)

Analytics & Privacy

iris collects anonymous usage analytics during installation only. This helps us understand adoption and improve the product.

What we collect: OS, shell type, selected IDEs, installation success/failure, approximate location (country level).

What we don't collect: No usernames, no file paths, no project contents, no IP addresses stored.

Opt-Out

# Option 1: Environment variable
IRIS_TELEMETRY_DISABLED=1 npx project-iris@latest install

# Option 2: DO_NOT_TRACK standard
DO_NOT_TRACK=1 npx project-iris@latest install

Analytics are automatically disabled in CI environments.

See PRIVACY.md for full details.

License

MIT License - see LICENSE for details.