IRIS v0.0.06

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.

🚀 Quick Start

For New Projects (Empty Folder)

Start using IRIS in a brand-new directory:

# Create a new project directory
mkdir my-project
cd my-project

# Install IRIS
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

Verify Installation

# Check IRIS is working
npx project-iris --help
npx project-iris validate

# Start using IRIS
npx project-iris ask "scaffold a new login system"

[!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.

For Existing Projects

If you already have a package.json, just run:

npx project-iris@latest install

IRIS will integrate with your existing project without breaking anything.

🔧 Global Install (Optional)

For convenience, you can install IRIS globally:

npm install -g project-iris@latest

# Now use 'project-iris' directly
project-iris --version
project-iris install
project-iris ask "create a new feature"

🧠 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).

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

IRIS ensures these files always exist. If missing, project-iris validate fails. Use project-iris validate --fix to restore them.

🔄 The Workflow

1. Ask (Route Intent)

Don't guess which agent or prompt to use. Just ask IRIS.

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.

2. Pack (Context Generation)

If you just need the context for an agent manually:

project-iris pack --agent inception

• Result: Generates a single Markdown file containing all relevant project context, rules, and active tasks.

3. Validate (Enforcement)

Ensure your project complies with the defined policies (e.g., "Designs must be approved before coding").

project-iris validate

Auto-Fix: IRIS can repair missing directories and file structures automatically.

project-iris validate --fix

Strict Mode (CI): Use strict mode to fail (exit non-zero) on quality warnings (e.g. placeholders, empty files).

project-iris validate --strict

🤖 Automated Workflows with project-iris develop

NEW: Automate the complete IRIS workflow from Intent → Bolt Plan → Execution with IDE agent integration.

Overview

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)

All stages interact with your IDE agent via a bridge protocol, with approval gates at each step.

Quick Start

# Terminal 1: Start bridge helper (recommended)
project-iris bridge run

# Terminal 2: Run workflow
project-iris develop "Build a dashboard UI to track IRIS progress"

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

Usage

Basic workflow:

project-iris develop "Your intent description"

Resume interrupted workflow:

project-iris develop --resume <runId>

Auto-approve gates (no prompts):

project-iris develop --gate auto "Your intent"

Override IDE selection:

project-iris develop --ide cursor "Your intent"

No-bridge mode (manual result creation):

project-iris develop --no-bridge "Your intent"

Bridge Helper

The bridge helper watches for workflow tasks and opens them in your IDE:

Start the helper:

project-iris bridge run

Check bridge status:

project-iris bridge status

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

How It Works

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

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

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

Bridge Protocol

Tasks are communicated via JSON files:

Task Packet (.iris/bridge/inbox/<taskId>.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"]
}

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

{
  "taskId": "uuid",
  "status": "ok",
  "message": "Created requirements.md",
  "filesChanged": ["memory-bank/intents/slug/requirements.md"]
}

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

Unsupported IDEs fall back to filesystem bridge (manual file opening).

Run Tracking

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:

cat .iris/runs/<runId>.md

Troubleshooting

Bridge helper not finding tasks:

• Check .iris/bridge/inbox/ for task files
• Ensure bridge helper is running (iris bridge run)

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

Workflow stuck waiting:

• Create result file manually in .iris/bridge/outbox/<taskId>.json
• Or terminate and resume with --resume <runId>

🛠 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.

👥 Contributing to IRIS

This section is for developers who want to contribute to IRIS itself (not for users of IRIS).

Setup Development Environment

# 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
iris --version
iris doctor

Development Workflow

# Make changes to src/

# Rebuild
npm run build

# Test your changes
iris --help
iris validate

# Run verification
npm run verify

Repository Hygiene

• 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.

Unlink Development Version

npm run unlink:iris