project-iris 0.0.12 → 0.0.14

package/README.md

@@ -1,424 +1,315 @@
-# IRIS v0.0.1
+# iris
 
-**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.
+**AI-native software development with multi-agent orchestration.**
 
-## 🚀 Quick Start
+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.
 
-### New Projects
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-```bash
-mkdir my-project && cd my-project
-npx project-iris@latest install
-```
+---
 
-The installer will:
-- Create `package.json` if missing
-- Set up `.iris/` framework directory
-- Create `memory-bank/` structure
-- Install the default `iris-core` framework
-- **SaaS Bootstrap**: Auto-generates a "Repo Bootstrap" unit (`U000`) if `package.json` is missing.
-- Prompt for IDE selection (defaults to `auto` for internal agent)
+## What is AI-DLC?
 
-### Select Your Agent
+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.
 
-IRIS can function as a standalone agent or bridge to your IDE:
+> "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."
 
-```bash
-# Use the built-in zero-config agent (Default)
-iris use auto
+### AI-DLC vs Traditional Methods
 
-# Bridge to an external IDE (e.g. Cursor, VS Code)
-iris use cursor
-```
+| 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 |
 
-### Existing Projects
+---
 
-```bash
-npx project-iris@latest install
-```
+## How It Works
 
-### Verify Installation
+iris provides four specialized agents that guide you through the entire development lifecycle:
 
-```bash
-iris --help
-iris validate
-iris status
 ```
-
-> **Note**: The npm package is `project-iris`, but the CLI command is `iris`.
-> - With npx: `npx project-iris <command>`
-> - After global install: `iris <command>`
-
----
-
-## � Global Install
-
-```bash
-npm install -g project-iris@latest
-iris --version
+                    ┌─────────────────┐
+                    │  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
 ```
 
----
-
-## 🧠 Core Concepts
+### The Three Phases
 
-### Lifecycle 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 |
 
-IRIS divides your project into three phases:
+---
 
-| Phase | Focus | Artifacts |
-|-------|-------|-----------|
-| **Inception** | Requirements, architecture | `memory-bank/intents/` |
-| **Construction** | Implementation, testing | `memory-bank/units/`, `memory-bank/bolts/` |
-| **Operations** | Deployment, monitoring | `memory-bank/logs/` |
+## Quick Start
 
-### The Factory Loop (Construction)
+### Installation
 
-IRIS automates the delivery process through a deterministic loop:
+```bash
+npx project-iris install
+```
 
-1.  **Unit List** (`unit-list.md`) - High-level breakdown of work.
-2.  **Unit Briefs** (`unit-brief.md`) - Detailed specs for each unit (Planning).
-3.  **Bolts** (`bolt.md`) - Executable tasks derived from briefs (Construction).
-4.  **Code & Test** - Implementation and verification (Execution).
+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
 
-The workflow engine orchestrates this loop using `iris run`.
+### Initialize Your Project
 
-### Frameworks
+```bash
+# Start the Master Agent
+/iris-master-agent
 
-Frameworks are pluggable configurations that define:
-- **Policy** - Required artifacts and validation gates
-- **Routes** - Intent routing rules
-- **Interview** - Interactive Q&A for intent capture
-- **Artifacts** - Generated document templates
-- **Workflow** - Step execution order
+# Then type:
+project-init
+```
 
-### The Memory Bank
+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)
 
-A standardized documentation structure:
+### Create Your First Intent
 
-```
-memory-bank/
-├── intents/           # Requirements and context
-│   └── default/
-│       ├── requirements.md
-│       └── system-context.md
-├── units/             # Implementation units
-├── bolts/             # Reusable patterns
-├── standards/         # Coding standards
-└── operations/        # Runbooks
+```bash
+/iris-inception-agent intent-create
 ```
 
----
+An **Intent** is your high-level goal:
+- "User authentication system"
+- "Product catalog with search"
+- "Payment processing integration"
 
-## 🔄 Commands
+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
 
-### Intent & Routing
+### Plan and Execute Bolts
 
 ```bash
-# Route a natural language intent
-iris ask "I need to fix the auth bug"
+# Plan bolts for your stories
+/iris-inception-agent bolt-plan
 
-# Interactive intent interview
-iris ask --interactive
+# Execute a bolt
+/iris-construction-agent bolt-start
+```
 
-# Route a natural language intent (uses active agent)
-iris ask "I need to fix the auth bug"
+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
 
-# Interactive intent interview
-iris ask --interactive
+**Human validation happens at each stage gate.**
 
-# Machine-readable output
-iris ask --json "scaffold login system"
-```
-
-> **Note**: `iris ask` uses the active agent set by `iris use`. Default is `auto` (In-Process Agent).
+---
 
-### Context Generation
+## Key Concepts
 
-```bash
-# Generate context pack for current phase
-iris pack
+### 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.
 
-# Target specific agent
-iris pack --agent inception
+### 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).
 
-# Output to stdout
-iris pack --stdout
-```
+### 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.
 
-### Workflow Execution
+| Type | Best For | Stages |
+|------|----------|--------|
+| **DDD Construction** | Complex business logic, domain modeling | Model → Design → ADR → Implement → Test |
+| **Simple Construction** | UI, integrations, utilities | Plan → Implement → Test |
 
-```bash
-# Start a new workflow run
-iris run --new
+### Memory Bank
+File-based storage for all project artifacts. Maintains context across agent sessions and provides traceability between artifacts.
 
-# Run with a pre-defined intent (seed)
-iris run --new --seed intent-draft.json
+### Standards
+Project decisions that inform AI code generation. Standards ensure consistency across all generated code and documentation.
 
-# Resume the latest run
-iris run --resume
+---
 
-# Resume a specific run
-iris run --resume 2026-01-03-21-41-43-abc1
+## Project Structure
 
-# Non-interactive mode (for CI/automation)
-iris run --new --seed draft.json --no-interactive
+After installation:
 
-# Machine-readable output
-iris run --json
+```
+.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
 ```
 
-144: **Workflow Steps:**
-145: 1. **Interview** - Capture intent (interactive or seed)
-146: 2. **Artifacts** - Generate documents from templates
-147: 3. **Plan** - Create unit briefs from unit list
-148: 4. **Build** - Generate bolts from approved briefs
-149: 5. **Execute** - Run bolt commands and generate test reports
-150: 6. **Validate** - Check policy compliance
-151: 7. **Pack** - Create context bundle
-152: 8. **Handoff** - Generate final summary
+---
 
-### Artifact Generation
+## Agent Commands
 
+### Master Agent
 ```bash
-# Generate artifacts from intent draft
-iris generate
-
-# Use custom input/output
-iris generate --in custom-draft.json --out artifacts/
+/iris-master-agent
 ```
-
-### Validation
-
+| 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
-# Check policy compliance
-iris validate
-
-# Auto-fix missing artifacts
-iris validate --fix
-
-# Strict mode (fail on warnings)
-iris validate --strict
+/iris-inception-agent
 ```
-
-### Lifecycle Management
-
+| 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
-# View current status
-iris status
-
-# Request phase transition
-iris phase set construction
-
-# Validate and apply transition
-iris validate --apply
+/iris-construction-agent
 ```
-
-### Automated Development
-
+| 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
-# Start automated workflow
-iris develop "Build a dashboard UI"
-
-# Resume interrupted workflow
-iris develop --resume <runId>
-
-# Override IDE
-iris develop --ide cursor "intent"
-
-# Auto-approve gates
-iris develop --gate auto "intent"
+/iris-operations-agent
 ```
+| Command | Purpose |
+|---------|---------|
+| `build` | Build the project |
+| `deploy` | Deploy to environment |
+| `verify` | Verify deployment |
+| `monitor` | Set up monitoring |
 
-### Bridge (IDE Integration)
+---
 
-IRIS "Auto" mode works out of the box. To use an external agent (like Cursor Composer or Windsurf), you must start the bridge:
+## Why iris?
 
-```bash
-# Start bridge helper (only needed for external IDEs)
-iris bridge serve
+### 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.
 
-# Check bridge status
-iris bridge status
-```
+### 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.
 
-### Diagnostics
+### 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.
 
-```bash
-# Check environment
-iris doctor
+### Tool Agnostic
+Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere.
 
-# Show version
-iris --version
-```
+### Context Engineering
+Specs and Memory Bank provide structured context for AI agents. Agents reload context each session - no more lost knowledge.
 
 ---
 
-## 📁 Directory Structure
+## Supported Tools
 
-```
-your-project/
-├── .iris/
-│   ├── state.yaml           # Current phase, framework, active flow
-│   ├── policy.yaml           # (Legacy) Validation rules
-│   ├── routes.yaml           # (Legacy) Intent routing
-│   ├── frameworks/           # Installed frameworks
-│   │   └── iris-core/
-│   ├── runs/                 # Workflow run history
-│   │   ├── latest            # Pointer to latest run
-│   │   └── 2026-01-03-.../   # Run directory
-│   │       ├── run.json      # Run state
-│   │       ├── events.ndjson # Event log
-│   │       ├── intent-draft.json
-│   │       ├── artifacts.json
-│   │       ├── validate.json
-│   │       ├── pack.md
-│   │       └── handoff.json
-│   ├── inbox/                # Generated context packs
-│   └── bridge/               # IDE bridge files
-│       ├── inbox/
-│       ├── outbox/
-│       └── state/
-├── memory-bank/              # Project documentation
-└── package.json
-```
+| 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/` |
 
 ---
 
-## � Configuration
-
-### State (`state.yaml`)
-
-```yaml
-version: 1
-framework:
-  current: iris-core
-  version: null
-phase:
-  current: inception
-  requested: null
-active:
-  intent_id: null
-  flow: null
-```
+## FAQ
 
-### Policy (`policy.yaml`)
-
-```yaml
-version: 1
-phases:
-  inception:
-    requires:
-      - path: memory-bank/intents/
-        type: directory
-    gates: []
-transitions:
-  - from: inception
-    to: construction
-```
+**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.
 
-### Routes (`routes.yaml`)
+**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.
 
-```yaml
-schemaVersion: 1
-routes:
-  - match: "bug|fix|error"
-    agent: construction
-  - match: ".*"
-    agent: inception
-```
+**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.
 
-## 🤖 Machine Interface
-
-### `iris run --json`
-
-Outputs a single JSON object (RunState):
-
-```json
-{
-  "schemaVersion": 1,
-  "runId": "2026-01-03-21-41-43-abc1",
-  "framework": { "id": "iris-core", "version": null },
-  "steps": {
-    "interview": { "status": "done", ... },
-    "artifacts": { "status": "done", ... },
-    "validate": { "status": "done", ... },
-    "pack": { "status": "done", ... },
-    "handoff": { "status": "done", ... }
-  }
-}
-```
-
-**Exit Codes:**
-- `0` - Success
-- `1` - Failure (validation error, step failed)
-- `2` - Blocked (requires input, non-interactive mode)
+---
 
-### Event Log (`events.ndjson`)
+## Resources
 
-```json
-{"ts":"2026-01-03T21:41:43.732Z","type":"RUN_STARTED"}
-{"ts":"2026-01-03T21:41:43.733Z","type":"STEP_STARTED","stepId":"interview"}
-{"ts":"2026-01-03T21:41:43.733Z","type":"STEP_DONE","stepId":"interview"}
-```
+- [AI-DLC Specification (AWS)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)
 
 ---
 
-## 👥 Contributing
+## Analytics & Privacy
 
-### Setup
+iris collects **anonymous** usage analytics during installation only. This helps us understand adoption and improve the product.
 
-```bash
-git clone <repo-url>
-cd project-iris
-npm ci
-npm run build
-npm link
-iris --version
-```
+**What we collect**: OS, shell type, selected IDEs, installation success/failure, approximate location (country level).
 
-### Development
+**What we don't collect**: No usernames, no file paths, no project contents, no IP addresses stored.
 
-```bash
-# Make changes to src/
-npm run build
-npm run test
-
-# Run all verification
-npm run verify
-```
-
-### Testing
+### Opt-Out
 
 ```bash
-# Unit tests
-npm run test:unit
-
-# Smoke tests
-npm run test:smoke
+# Option 1: Environment variable
+IRIS_TELEMETRY_DISABLED=1 npx project-iris@latest install
 
-# All tests
-npm test
+# Option 2: DO_NOT_TRACK standard
+DO_NOT_TRACK=1 npx project-iris@latest install
 ```
 
-### Unlink
+Analytics are automatically disabled in CI environments.
 
-```bash
-npm unlink -g project-iris
-```
+See [PRIVACY.md](PRIVACY.md) for full details.
 
 ---
 
-## 📚 Learn More
-
-- [Baseline Documentation](docs/baseline-step0.md)
-- [Framework Development](docs/frameworks.md)
-- [Artifact Templates](docs/artifacts.md)
+## License
 
----
+MIT License - see [LICENSE](LICENSE) for details.
 
-## License
 
-MIT

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);