project-iris 0.0.8 → 0.0.11

package/README.md

@@ -1,394 +1,424 @@
-# IRIS v0.0.06
+# IRIS v0.0.1
 
-**IRIS** (Intelligent Repository for Intent-driven Systems) is a framework that acts as an AI Project Manager for your codebase. It structures your project, routes natural language intents to specific agents, and enforces architectural standards through validation gates.
+**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.
 
 ## 🚀 Quick Start
 
-### For New Projects (Empty Folder)
-
-Start using IRIS in a brand-new directory:
+### New Projects
 
 ```bash
-# Create a new project directory
-mkdir my-project
-cd my-project
-
-# Install IRIS
+mkdir my-project && cd my-project
 npx project-iris@latest install
 ```
 
 The installer will:
-- Create a minimal `package.json` if one doesn't exist
-- Set up the IRIS framework (`.iris/` directory)
-- Create the memory bank structure (`memory-bank/`)
-- Generate `package-lock.json`
-- Prompt you to select your preferred IDE tools
+- 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)
 
-### Verify Installation
+### Select Your Agent
+
+IRIS can function as a standalone agent or bridge to your IDE:
 
 ```bash
-# Check IRIS is working
-npx project-iris --help
-npx project-iris validate
+# Use the built-in zero-config agent (Default)
+iris use auto
 
-# Start using IRIS
-npx project-iris ask "scaffold a new login system"
+# Bridge to an external IDE (e.g. Cursor, VS Code)
+iris use cursor
 ```
 
-> [!IMPORTANT]
-> **Package Name vs Command Name**
-> 
-> The npm package is named `project-iris`, but when installed globally, the command is `iris`.
-> 
-> - **With npx** (no global install): Use `npx project-iris <command>`
-> - **After global install**: Use `iris <command>`
-> 
-> This is why `npx iris` won't work - there's no package named `iris` on npm.
+### Existing Projects
 
-### For Existing Projects
+```bash
+npx project-iris@latest install
+```
 
-If you already have a `package.json`, just run:
+### Verify Installation
 
 ```bash
-npx project-iris@latest install
+iris --help
+iris validate
+iris status
 ```
 
-IRIS will integrate with your existing project without breaking anything.
+> **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 (Optional)
-
-For convenience, you can install IRIS globally:
+## � Global Install
 
 ```bash
 npm install -g project-iris@latest
-
-# Now use 'project-iris' directly
-project-iris --version
-project-iris install
-project-iris ask "create a new feature"
+iris --version
 ```
 
 ---
 
 ## 🧠 Core Concepts
 
-### The IRIS Method
-IRIS divides project lifecycle into three distinct phases:
-1.  **Inception**: Requirements gathering, architectural planning (`memory-bank/intents`).
-2.  **Construction**: Code implementation, unit testing (`memory-bank/units`).
-3.  **Operations**: Deployment, monitoring, runbooks (`memory-bank/operations`).
+### Lifecycle Phases
+
+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/` |
+
+### The Factory Loop (Construction)
+
+IRIS automates the delivery process through a deterministic loop:
+
+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 workflow engine orchestrates this loop using `iris run`.
+
+### Frameworks
+
+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
 
 ### The Memory Bank
-A standardized documentation structure enforced by Navi. The following minimal baseline is required:
 
-*   **`memory-bank/intents/default/`**:
-    *   `requirements.md`: Problem statement, scope, success criteria.
-    *   `system-context.md`: Architecture decisions, constraints, tool versions.
-    *   **Optional**: `units/<unit-name>/`:
-        *   `unit-brief.md` (Required if unit folder exists).
-*   **`memory-bank/bolts/`**: Reusable code snippets and patterns (`README.md` required).
-*   **`memory-bank/standards/`**: Coding and documentation standards (`README.md` required).
-*   **`memory-bank/operations/`**: Runbooks and maintenance guides (`README.md` required).
+A standardized documentation structure:
 
-IRIS ensures these files always exist. If missing, `project-iris validate` fails. Use `project-iris validate --fix` to restore them.
+```
+memory-bank/
+├── intents/           # Requirements and context
+│   └── default/
+│       ├── requirements.md
+│       └── system-context.md
+├── units/             # Implementation units
+├── bolts/             # Reusable patterns
+├── standards/         # Coding standards
+└── operations/        # Runbooks
+```
 
 ---
 
-## 🔄 The Workflow
+## 🔄 Commands
 
-### 1. Ask (Route Intent)
-Don't guess which agent or prompt to use. Just ask IRIS.
+### Intent & Routing
 
 ```bash
-project-iris ask "I need to fix the auth bug in login"
-```
-*   **Result**: IRIS analyzes `.iris/routes.yaml`, picks the right agent (e.g., `inception` vs `construction`), generates a context pack, and tells you exactly what command to run.
-*   **Artifact**: Creates `.iris/inbox/next.md` with instructions.
+# Route a natural language intent
+iris ask "I need to fix the auth bug"
 
-### 2. Pack (Context Generation)
-If you just need the context for an agent manually:
+# Interactive intent interview
+iris ask --interactive
 
-```bash
-project-iris pack --agent inception
-```
-*   **Result**: Generates a single Markdown file containing all relevant project context, rules, and active tasks.
+# Route a natural language intent (uses active agent)
+iris ask "I need to fix the auth bug"
 
-### 3. Validate (Enforcement)
-Ensure your project complies with the defined policies (e.g., "Designs must be approved before coding").
+# Interactive intent interview
+iris ask --interactive
 
-```bash
-project-iris validate
+# Machine-readable output
+iris ask --json "scaffold login system"
 ```
 
-**Auto-Fix**: IRIS can repair missing directories and file structures automatically.
-```bash
-project-iris validate --fix
-```
+> **Note**: `iris ask` uses the active agent set by `iris use`. Default is `auto` (In-Process Agent).
+
+### Context Generation
 
-**Strict Mode (CI)**:
-Use strict mode to fail (exit non-zero) on quality warnings (e.g. placeholders, empty files).
 ```bash
-project-iris validate --strict
-```
+# Generate context pack for current phase
+iris pack
 
----
+# Target specific agent
+iris pack --agent inception
 
-## 🤖 Automated Workflows with `project-iris develop`
+# Output to stdout
+iris pack --stdout
+```
 
-**NEW**: Automate the complete IRIS workflow from Intent → Bolt Plan → Execution with IDE agent integration.
+### Workflow Execution
 
-### Overview
+```bash
+# Start a new workflow run
+iris run --new
 
-`project-iris develop` orchestrates the entire IRIS workflow automatically:
-1. **Intent Inception** - Clarifies requirements through questions, generates intent artifacts
-2. **Bolt Plan** - Creates implementation plan and individual bolt files
-3. **Bolt Execution** - Executes each bolt (design → implement → test)
+# Run with a pre-defined intent (seed)
+iris run --new --seed intent-draft.json
 
-All stages interact with your IDE agent via a bridge protocol, with approval gates at each step.
+# Resume the latest run
+iris run --resume
 
-### Quick Start
+# Resume a specific run
+iris run --resume 2026-01-03-21-41-43-abc1
 
-```bash
-# Terminal 1: Start bridge helper (recommended)
-project-iris bridge run
+# Non-interactive mode (for CI/automation)
+iris run --new --seed draft.json --no-interactive
 
-# Terminal 2: Run workflow
-project-iris develop "Build a dashboard UI to track IRIS progress"
+# Machine-readable output
+iris run --json
 ```
 
-The workflow will:
-- Generate clarifying questions via your IDE agent
-- Prompt you for answers in the terminal
-- Create intent artifacts (requirements.md, system-context.md)
-- Generate bolt plan and bolt files
-- Execute each bolt with design, implementation, and testing phases
-- Request approval at each major stage
+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
 
-### Usage
+### Artifact Generation
 
-**Basic workflow:**
 ```bash
-project-iris develop "Your intent description"
-```
+# Generate artifacts from intent draft
+iris generate
 
-**Resume interrupted workflow:**
-```bash
-project-iris develop --resume <runId>
+# Use custom input/output
+iris generate --in custom-draft.json --out artifacts/
 ```
 
-**Auto-approve gates (no prompts):**
+### Validation
+
 ```bash
-project-iris develop --gate auto "Your intent"
+# Check policy compliance
+iris validate
+
+# Auto-fix missing artifacts
+iris validate --fix
+
+# Strict mode (fail on warnings)
+iris validate --strict
 ```
 
-**Override IDE selection:**
+### Lifecycle Management
+
 ```bash
-project-iris develop --ide cursor "Your intent"
+# View current status
+iris status
+
+# Request phase transition
+iris phase set construction
+
+# Validate and apply transition
+iris validate --apply
 ```
 
-**No-bridge mode (manual result creation):**
+### Automated Development
+
 ```bash
-project-iris develop --no-bridge "Your intent"
-```
+# Start automated workflow
+iris develop "Build a dashboard UI"
 
-### Bridge Helper
+# Resume interrupted workflow
+iris develop --resume <runId>
 
-The bridge helper watches for workflow tasks and opens them in your IDE:
+# Override IDE
+iris develop --ide cursor "intent"
 
-**Start the helper:**
-```bash
-project-iris bridge run
+# Auto-approve gates
+iris develop --gate auto "intent"
 ```
 
-**Check bridge status:**
-```bash
-project-iris bridge status
-```
+### Bridge (IDE Integration)
 
-The helper will:
-- Watch `.iris/bridge/inbox/` for new tasks
-- Generate human-readable prompts in `.iris/bridge/state/`
-- Attempt to open prompts in your selected IDE
-- Wait for results in `.iris/bridge/outbox/`
-- Clean up completed tasks
+IRIS "Auto" mode works out of the box. To use an external agent (like Cursor Composer or Windsurf), you must start the bridge:
 
-### How It Works
+```bash
+# Start bridge helper (only needed for external IDEs)
+iris bridge serve
 
-#### 1. Intent Inception Stage
-- Sends task to IDE agent: "Generate 3-8 clarifying questions"
-- Prompts you for answers in terminal
-- Sends task: "Create requirements.md and system-context.md based on answers"
-- Gate: "Approve intent? (y/N)"
+# Check bridge status
+iris bridge status
+```
 
-#### 2. Bolt Plan Stage
-- Sends task: "Generate bolt plan and individual bolt files"
-- Parses bolt list from generated plan
-- Gate: "Approve bolt plan? (y/N)"
+### Diagnostics
 
-#### 3. Bolt Execution Stage (for each bolt)
-- Design phase: Optional design notes and ADRs
-- Implementation phase: Code changes and task completion
-- Testing phase: Run tests or propose test commands
-- Gate: "Approve bolt? (y/N)"
+```bash
+# Check environment
+iris doctor
 
-### Bridge Protocol
+# Show version
+iris --version
+```
 
-Tasks are communicated via JSON files:
+---
+
+## 📁 Directory Structure
 
-**Task Packet** (`.iris/bridge/inbox/<taskId>.json`):
-```json
-{
-  "taskId": "uuid",
-  "intent": "Build a dashboard...",
-  "stage": "INTENT_INCEPTION",
-  "agent": "iris-inception-agent",
-  "instructions": "Generate clarifying questions...",
-  "inputs": ["path/to/context.md"],
-  "expectedOutputs": ["path/to/output.md"]
-}
+```
+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
 ```
 
-**Human Prompt** (`.iris/bridge/state/<taskId>.md`):
-- Human-readable version of the task
-- Includes file links and instructions
-- Shows expected result format
+---
 
-**Result** (`.iris/bridge/outbox/<taskId>.json`):
-```json
-{
-  "taskId": "uuid",
-  "status": "ok",
-  "message": "Created requirements.md",
-  "filesChanged": ["memory-bank/intents/slug/requirements.md"]
-}
+## � Configuration
+
+### State (`state.yaml`)
+
+```yaml
+version: 1
+framework:
+  current: iris-core
+  version: null
+phase:
+  current: inception
+  requested: null
+active:
+  intent_id: null
+  flow: null
 ```
 
-### IDE Support
-
-Supported IDEs with auto-open capability:
-- **Cursor** - Detects `cursor` CLI
-- **VS Code** - Detects `code` CLI
-- **Antigravity** - Always available (filesystem bridge)
-- **Windsurf** - Best-effort with fallback
+### Policy (`policy.yaml`)
+
+```yaml
+version: 1
+phases:
+  inception:
+    requires:
+      - path: memory-bank/intents/
+        type: directory
+    gates: []
+transitions:
+  - from: inception
+    to: construction
+```
 
-Unsupported IDEs fall back to filesystem bridge (manual file opening).
+### Routes (`routes.yaml`)
 
-### Run Tracking
+```yaml
+schemaVersion: 1
+routes:
+  - match: "bug|fix|error"
+    agent: construction
+  - match: ".*"
+    agent: inception
+```
 
-All workflow runs are tracked in `.iris/runs/`:
-- `<runId>.json` - Complete run state with events
-- `<runId>.state.json` - Quick resume snapshot
-- `<runId>.md` - Human-readable summary
+---
 
-View run summary:
-```bash
-cat .iris/runs/<runId>.md
-```
+## 🤖 Machine Interface
 
-### Troubleshooting
+### `iris run --json`
 
-**Bridge helper not finding tasks:**
-- Check `.iris/bridge/inbox/` for task files
-- Ensure bridge helper is running (`iris bridge run`)
+Outputs a single JSON object (RunState):
 
-**IDE not opening automatically:**
-- Verify IDE CLI is available (`which cursor`, `which code`)
-- Use `--no-bridge` mode and open files manually
-- Check `iris bridge status` for connector info
+```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", ... }
+  }
+}
+```
 
-**Workflow stuck waiting:**
-- Create result file manually in `.iris/bridge/outbox/<taskId>.json`
-- Or terminate and resume with `--resume <runId>`
+**Exit Codes:**
+- `0` - Success
+- `1` - Failure (validation error, step failed)
+- `2` - Blocked (requires input, non-interactive mode)
 
----
+### Event Log (`events.ndjson`)
 
-## 🛠 Command Reference
-
-
-### Lifecycle
-*   **`install`**: Downloads and sets up the strict `.iris` configuration and tools.
-*   **`uninstall`**: Safely removes IRIS components (preserves your `memory-bank` by default).
-
-### Workflow
-*   **`ask [intent]`**: Routes a natural language request.
-    *   `--dry-run`: See where it would route without generating files.
-    *   `--json`: Machine-readable output.
-*   **`pack`**: focused context bundle generator.
-    *   `--agent <name>`: Target specific agent context.
-    *   `--auth`: Include sensitive rules (optional).
-*   **`run <workflow>`**: Execute a named workflow (e.g., `iris run deploy`).
-*   **`develop [intent]`**: **NEW** - Automated workflow orchestration (Intent → Bolt Plan → Execution).
-    *   `--resume <runId>`: Resume interrupted workflow.
-    *   `--ide <ideId>`: Override IDE selection.
-    *   `--gate <auto|manual>`: Gate approval mode (default: manual).
-    *   `--no-bridge`: Fallback mode (manual result creation).
-
-### Bridge
-*   **`bridge run`**: **NEW** - Start bridge helper (watches inbox, opens IDE, waits for results).
-    *   `--poll-interval <ms>`: Polling interval (default: 2000ms).
-*   **`bridge status`**: **NEW** - Show bridge status, IDE info, and pending tasks.
-
-### Governance
-*   **`validate`**: Checks policy compliance.
-    *   `--fix`: Auto-creates missing required files/folders.
-    *   `--strict`: Fail on warnings.
-*   **`phase`**: Manage the project lifecycle phase.
-    *   `phase set <name>`: Request a transition (e.g., `inception` -> `construction`).
-*   **`status`**: View current phase, active intent, and validation state.
+```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"}
+```
 
 ---
 
-## 👥 Contributing to IRIS
-
-This section is for developers who want to contribute to IRIS itself (not for users of IRIS).
+## 👥 Contributing
 
-### Setup Development Environment
+### Setup
 
 ```bash
-# Clone the repository
 git clone <repo-url>
 cd project-iris
-
-# Install dependencies
 npm ci
-
-# Build the CLI
 npm run build
-
-# Link globally for testing
-npm run link:iris
-
-# Verify
+npm link
 iris --version
-iris doctor
 ```
 
-### Development Workflow
+### Development
 
 ```bash
 # Make changes to src/
-
-# Rebuild
 npm run build
+npm run test
 
-# Test your changes
-iris --help
-iris validate
-
-# Run verification
+# Run all verification
 npm run verify
 ```
 
-### Repository Hygiene
+### Testing
 
-*   **`node_modules/`** and **`dist/`** are explicitly ignored.
-*   **`verify:repo`**: Run `npm run verify:repo` to confirm hygiene.
-*   **`.iris/`**: Contains the "Brain" (policies, routes, state). **Do not delete.**
+```bash
+# Unit tests
+npm run test:unit
+
+# Smoke tests
+npm run test:smoke
+
+# All tests
+npm test
+```
 
-### Unlink Development Version
+### Unlink
 
 ```bash
-npm run unlink:iris
+npm unlink -g project-iris
 ```
+
+---
+
+## 📚 Learn More
+
+- [Baseline Documentation](docs/baseline-step0.md)
+- [Framework Development](docs/frameworks.md)
+- [Artifact Templates](docs/artifacts.md)
+
+---
+
+## License
+
+MIT