project-iris 0.0.12 → 0.0.13

package/README.md

@@ -1,424 +1,148 @@
 # IRIS v0.0.1
 
-**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
-
-### New Projects
-
-```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)
-
-### Select Your Agent
-
-IRIS can function as a standalone agent or bridge to your IDE:
-
-```bash
-# Use the built-in zero-config agent (Default)
-iris use auto
-
-# Bridge to an external IDE (e.g. Cursor, VS Code)
-iris use cursor
-```
-
-### Existing Projects
-
-```bash
-npx project-iris@latest install
 ```
-
-### Verify Installation
-
-```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
-```
-
----
-
-## 🧠 Core Concepts
-
-### 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:
-
-```
-memory-bank/
-├── intents/           # Requirements and context
-│   └── default/
-│       ├── requirements.md
-│       └── system-context.md
-├── units/             # Implementation units
-├── bolts/             # Reusable patterns
-├── standards/         # Coding standards
-└── operations/        # Runbooks
-```
+**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.
 
 ---
 
-## 🔄 Commands
-
-### Intent & Routing
-
-```bash
-# Route a natural language intent
-iris ask "I need to fix the auth bug"
-
-# Interactive intent interview
-iris ask --interactive
-
-# Route a natural language intent (uses active agent)
-iris ask "I need to fix the auth bug"
-
-# Interactive intent interview
-iris ask --interactive
-
-# Machine-readable output
-iris ask --json "scaffold login system"
-```
+## 🚀 Quick Start
 
-> **Note**: `iris ask` uses the active agent set by `iris use`. Default is `auto` (In-Process Agent).
+### Scenario A: Start a New Project
 
-### Context Generation
+If you are starting from scratch and want IRIS to set up the foundation:
 
 ```bash
-# Generate context pack for current phase
-iris pack
-
-# Target specific agent
-iris pack --agent inception
-
-# Output to stdout
-iris pack --stdout
+mkdir my-new-project && cd my-new-project
+npx project-iris@latest install
 ```
 
-### Workflow Execution
+**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.
 
 ```bash
-# Start a new workflow run
-iris run --new
-
-# Run with a pre-defined intent (seed)
-iris run --new --seed intent-draft.json
-
-# Resume the latest run
-iris run --resume
-
-# Resume a specific run
-iris run --resume 2026-01-03-21-41-43-abc1
-
-# Non-interactive mode (for CI/automation)
-iris run --new --seed draft.json --no-interactive
-
-# Machine-readable output
-iris run --json
+# Define your first feature
+iris ask "I want to build a landing page with a hero section"
 ```
 
-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
+### Scenario B: Add to Existing Project
 
-### Artifact Generation
+If you have an existing codebase and want to add AI-driven management:
 
 ```bash
-# Generate artifacts from intent draft
-iris generate
-
-# Use custom input/output
-iris generate --in custom-draft.json --out artifacts/
-```
-
-### Validation
-
-```bash
-# Check policy compliance
-iris validate
-
-# Auto-fix missing artifacts
-iris validate --fix
-
-# Strict mode (fail on warnings)
-iris validate --strict
+cd my-existing-project
+npx project-iris@latest install
 ```
 
-### Lifecycle Management
+**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.
 
 ```bash
-# View current status
-iris status
-
-# Request phase transition
-iris phase set construction
-
-# Validate and apply transition
-iris validate --apply
+# Example: Ask IRIS to plan a refactor
+iris ask "Refactor the authentication module to use tokens"
 ```
 
-### Automated Development
-
-```bash
-# Start automated workflow
-iris develop "Build a dashboard UI"
-
-# Resume interrupted workflow
-iris develop --resume <runId>
+---
 
-# Override IDE
-iris develop --ide cursor "intent"
+## 🔄 The IRIS Workflow
 
-# Auto-approve gates
-iris develop --gate auto "intent"
-```
+IRIS manages development through a deterministic lifecycle. Whether you are building from scratch or maintaining legacy code, the loop is the same:
 
-### Bridge (IDE Integration)
+### 1. Inception (Defining *What*)
+Before writing code, we define the requirements.
 
-IRIS "Auto" mode works out of the box. To use an external agent (like Cursor Composer or Windsurf), you must start the bridge:
+*   **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.
 
-```bash
-# Start bridge helper (only needed for external IDEs)
-iris bridge serve
+### 2. Construction (Building *How*)
+Once requirements are set, we enter the **Factory Loop**:
 
-# Check bridge status
-iris bridge status
-```
+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.
 
-### Diagnostics
+*   **Command**: `iris run` (Or `iris develop` for the automated loop)
 
-```bash
-# Check environment
-iris doctor
-
-# Show version
-iris --version
-```
+### 3. Operations (Running It)
+IRIS monitors the health of the project and manages deployment (future scope).
 
 ---
 
-## 📁 Directory Structure
+## 🧠 Key Concepts
 
-```
-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
-```
+### 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.
 
----
+*   `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.
 
-## � Configuration
-
-### State (`state.yaml`)
-
-```yaml
-version: 1
-framework:
-  current: iris-core
-  version: null
-phase:
-  current: inception
-  requested: null
-active:
-  intent_id: null
-  flow: null
-```
-
-### Policy (`policy.yaml`)
-
-```yaml
-version: 1
-phases:
-  inception:
-    requires:
-      - path: memory-bank/intents/
-        type: directory
-    gates: []
-transitions:
-  - from: inception
-    to: construction
-```
+### Agents & Bridges
+IRIS works where you work.
 
-### Routes (`routes.yaml`)
-
-```yaml
-schemaVersion: 1
-routes:
-  - match: "bug|fix|error"
-    agent: construction
-  - match: ".*"
-    agent: inception
-```
+*   **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`.
 
 ---
 
-## 🤖 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`)
-
-```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"}
-```
+## 📚 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. |
 
 ---
 
 ## 👥 Contributing
 
-### Setup
+We welcome contributions to IRIS itself!
 
+### Setup
 ```bash
 git clone <repo-url>
 cd project-iris
 npm ci
 npm run build
 npm link
-iris --version
 ```
 
-### Development
-
+### Verification
 ```bash
-# Make changes to src/
-npm run build
-npm run test
-
-# Run all verification
+# Run all verification checks
 npm run verify
-```
-
-### Testing
 
-```bash
-# Unit tests
+# Run unit tests
 npm run test:unit
-
-# Smoke tests
-npm run test:smoke
-
-# All tests
-npm test
 ```
-
-### Unlink
-
-```bash
-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

package/dist/iris/bundle.js

@@ -20,7 +20,7 @@ export function getBundleRoot() {
         path.resolve(__dirname, "../../iris_bundle") // Another dist layout possibility
     ];
     for (const candidate of candidates) {
-        if (fs.existsSync(candidate) && fs.existsSync(path.join(candidate, ".iris"))) {
+        if (fs.existsSync(candidate) && fs.existsSync(path.join(candidate, "frameworks"))) {
             return candidate;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-iris",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "type": "module",
   "bin": {
     "iris": "dist/cli.js",