project-iris 0.0.13 → 0.0.15

package/README.md

@@ -1,148 +1,315 @@
-# IRIS v0.0.1
+# iris
+
+**AI-native software development with multi-agent orchestration.**
+
+iris implements the [AI-Driven Development Lifecycle (AI-DLC)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) methodology as a set of markdown-based agents that work with your favorite AI coding tools.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 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
 ```
 
-**IRIS** (Intelligent Repository for Intent-driven Systems) is an AI-native project management framework. It structures your codebase, routes natural language intents to the right agents, and enforces architectural standards through validation gates.
+### 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 → test | Domain models, Technical designs, Code, Tests |
+| **Operations** | Operations Agent | Deploy, verify, and monitor | Deployment units, Monitoring, Runbooks |
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
+
+### Installation
 
-### Scenario A: Start a New Project
+```bash
+npx project-iris install
+```
 
-If you are starting from scratch and want IRIS to set up the foundation:
+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
 
 ```bash
-mkdir my-new-project && cd my-new-project
-npx project-iris@latest install
+# Start the Master Agent
+/iris-master-agent
+
+# Then type:
+project-init
 ```
 
-**What happens next?**
-1.  **Bootstrap**: IRIS initializes a `package.json` and the `.iris/` framework.
-2.  **Memory Bank**: It creates a `memory-bank/` directory for your project documentation.
-3.  **First Feature**: You are ready to build.
+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
 
 ```bash
-# Define your first feature
-iris ask "I want to build a landing page with a hero section"
+/iris-inception-agent intent-create
 ```
 
-### Scenario B: Add to Existing Project
+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
 
-If you have an existing codebase and want to add AI-driven management:
+### Plan and Execute Bolts
 
 ```bash
-cd my-existing-project
-npx project-iris@latest install
+# 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 Model** - Model business logic using DDD principles
+2. **Technical Design** - Apply patterns and make architecture decisions
+3. **ADR Analysis** - Document significant decisions (optional)
+4. **Implement** - Generate production code
+5. **Test** - Verify correctness with automated tests
+
+**Human validation happens at each stage gate.**
+
+---
+
+## 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 | Model → Design → ADR → Implement → Test |
+| **Simple Construction** | UI, integrations, utilities | Plan → Implement → Test |
+
+### 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
+├── intents/                   # Your captured intents
+│   └── {intent-name}/
+│       ├── requirements.md
+│       ├── system-context.md
+│       └── units/
+├── bolts/                     # Bolt execution records
+├── standards/                 # Project standards
+│   ├── tech-stack.md
+│   ├── coding-standards.md
+│   └── ...
+└── operations/                # Deployment context
+```
+
+---
 
-**What happens next?**
-1.  **Analysis**: IRIS scans your project to understand its structure.
-2.  **Integration**: It adds the `.iris` folder without touching your source code.
-3.  **Refactor/Build**: You can now use IRIS to manage new features or refactors.
+## Agent Commands
 
+### Master Agent
+```bash
+/iris-master-agent
+```
+| Command | 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
+```bash
+/iris-inception-agent
+```
+| Command | 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 |
+
+### Construction Agent
+```bash
+/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
 ```bash
-# Example: Ask IRIS to plan a refactor
-iris ask "Refactor the authentication module to use tokens"
+/iris-operations-agent
 ```
+| Command | Purpose |
+|---------|---------|
+| `build` | Build the project |
+| `deploy` | Deploy to environment |
+| `verify` | Verify deployment |
+| `monitor` | Set up monitoring |
 
 ---
 
-## 🔄 The IRIS Workflow
+## 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.
 
-IRIS manages development through a deterministic lifecycle. Whether you are building from scratch or maintaining legacy code, the loop is the same:
+### 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.
 
-### 1. Inception (Defining *What*)
-Before writing code, we define the requirements.
+### 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.
 
-*   **Command**: `iris ask "Your intent here"`
-*   **Action**: IRIS interviews you (or uses your prompt) to generate a **Requirements** document in `memory-bank/intents/`.
-*   **Result**: A clear, approved plan of what to build.
+### Tool Agnostic
+Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere.
 
-### 2. Construction (Building *How*)
-Once requirements are set, we enter the **Factory Loop**:
+### Context Engineering
+Specs and Memory Bank provide structured context for AI agents. Agents reload context each session - no more lost knowledge.
 
-1.  **Plan**: IRIS breaks the work down into **Units** (logical chunks of work).
-2.  **Brief**: Each Unit gets a **Unit Brief** (technical spec).
-3.  **Bolt**: Briefs are converted into **Bolts** (executable tasks).
-4.  **Execute**: The Agent writes code and runs tests.
+---
 
-*   **Command**: `iris run` (Or `iris develop` for the automated loop)
+## Supported Tools
 
-### 3. Operations (Running It)
-IRIS monitors the health of the project and manages deployment (future scope).
+| 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/` |
 
 ---
 
-## 🧠 Key Concepts
+## FAQ
 
-### The Memory Bank (`memory-bank/`)
-Your project's brain. IRIS stores all context here, so any AI agent (or human) can understand the project instantly.
+**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.
 
-*   `intents/`: What we want to build (the "Why").
-*   `units/`: How we are building it (the "How").
-*   `bolts/`: The atomic tasks (the "What").
-*   `runbooks/`: Operational guides.
+**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.
 
-### Agents & Bridges
-IRIS works where you work.
+**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.
 
-*   **Auto (Default)**: IRIS runs as a standalone agent in your terminal.
-*   **Bridge**: IRIS connects to your AI IDE (Cursor, Windsurf, VS Code).
-    *   Command: `iris use cursor` or `iris use windsurf`.
+**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.
 
 ---
 
-## 📚 Command Reference
-
-### Planning & Context
-| Command | Description |
-| content | content |
-| `iris ask "<intent>"` | Route a new intent or feature request. |
-| `iris ask --interactive` | Start a Q&A session to define requirements. |
-| `iris pack` | tailored context bundle for LLMs. |
-
-### Execution
-| Command | Description |
-| content | content |
-| `iris run` | Execute the next step in the workflow loop. |
-| `iris develop "<intent>"` | Run the full automated loop for an intent. |
-| `iris run --resume` | Resume an interrupted workflow. |
-
-### Management
-| Command | Description |
-| content | content |
-| `iris status` | Show current phase, active agent, and progress. |
-| `iris validate` | Verify project structure and memory bank integrity. |
-| `iris doctor` | Check environment health. |
+## Resources
+
+- [AI-DLC Specification (AWS)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)
 
 ---
 
-## 👥 Contributing
+## Analytics & Privacy
 
-We welcome contributions to IRIS itself!
+iris collects **anonymous** usage analytics during installation only. This helps us understand adoption and improve the product.
 
-### Setup
-```bash
-git clone <repo-url>
-cd project-iris
-npm ci
-npm run build
-npm link
-```
+**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
 
-### Verification
 ```bash
-# Run all verification checks
-npm run verify
+# Option 1: Environment variable
+IRIS_TELEMETRY_DISABLED=1 npx project-iris@latest install
 
-# Run unit tests
-npm run test:unit
+# 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](PRIVACY.md) for full details.
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+

package/bin/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const installer = require('../lib/installer');
+const packageJson = require('../package.json');
+
+program
+    .version(packageJson.version)
+    .description(packageJson.description);
+
+program
+    .command('install')
+    .description('Interactively install a iris flow')
+    .action(installer.install);
+
+program
+    .command('uninstall')
+    .description('Uninstall iris from the current project')
+    .action(installer.uninstall);
+
+program.parse(process.argv);