project-iris 0.0.6

package/README.md

@@ -0,0 +1,384 @@
+# 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:
+
+```bash
+# Create a new project directory
+mkdir my-project
+cd my-project
+
+# Install IRIS
+npx 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
+
+```bash
+# Check IRIS is working
+npx iris --help
+npx iris validate
+
+# Start using IRIS
+npx iris ask "scaffold a new login system"
+```
+
+### For Existing Projects
+
+If you already have a `package.json`, just run:
+
+```bash
+npx iris@latest install
+```
+
+IRIS will integrate with your existing project without breaking anything.
+
+---
+
+## 🔧 Global Install (Optional)
+
+For convenience, you can install IRIS globally:
+
+```bash
+npm install -g iris@latest
+
+# Now use 'iris' directly
+iris --version
+iris install
+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).
+
+Navi ensures these files always exist. If missing, `navi validate` fails. Use `navi validate --fix` to restore them.
+
+---
+
+## 🔄 The Workflow
+
+### 1. Ask (Route Intent)
+Don't guess which agent or prompt to use. Just ask IRIS.
+
+```bash
+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:
+
+```bash
+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").
+
+```bash
+iris validate
+```
+
+**Auto-Fix**: IRIS can repair missing directories and file structures automatically.
+```bash
+iris validate --fix
+```
+
+**Strict Mode (CI)**:
+Use strict mode to fail (exit non-zero) on quality warnings (e.g. placeholders, empty files).
+```bash
+iris validate --strict
+```
+
+---
+
+## 🤖 Automated Workflows with `iris develop`
+
+**NEW**: Automate the complete IRIS workflow from Intent → Bolt Plan → Execution with IDE agent integration.
+
+### Overview
+
+`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
+
+```bash
+# Terminal 1: Start bridge helper (recommended)
+iris bridge run
+
+# Terminal 2: Run workflow
+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:**
+```bash
+iris develop "Your intent description"
+```
+
+**Resume interrupted workflow:**
+```bash
+iris develop --resume <runId>
+```
+
+**Auto-approve gates (no prompts):**
+```bash
+iris develop --gate auto "Your intent"
+```
+
+**Override IDE selection:**
+```bash
+iris develop --ide cursor "Your intent"
+```
+
+**No-bridge mode (manual result creation):**
+```bash
+iris develop --no-bridge "Your intent"
+```
+
+### Bridge Helper
+
+The bridge helper watches for workflow tasks and opens them in your IDE:
+
+**Start the helper:**
+```bash
+iris bridge run
+```
+
+**Check bridge status:**
+```bash
+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`):
+```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`):
+```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:
+```bash
+cat .iris/runs/<runId>.md
+```
+
+### Troubleshooting
+
+**Bridge helper not finding tasks:**
+- Check `.iris/bridge/inbox/` for task files
+- Ensure bridge helper is running (`navi bridge run`)
+
+**IDE not opening automatically:**
+- Verify IDE CLI is available (`which cursor`, `which code`)
+- Use `--no-bridge` mode and open files manually
+- Check `navi 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., `npm run navi 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
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd iris-beta
+
+# 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
+
+```bash
+# 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
+
+```bash
+npm run unlink:iris
+```

package/dist/bridge/connector-factory.js

@@ -0,0 +1,27 @@
+import { FilesystemBridgeConnector } from "./filesystem-connector.js";
+import { CursorConnector } from "./connectors/cursor-connector.js";
+import { VSCodeConnector } from "./connectors/vscode-connector.js";
+import { AntigravityConnector } from "./connectors/antigravity-connector.js";
+import { WindsurfConnector } from "./connectors/windsurf-connector.js";
+/**
+ * Create a bridge connector based on IDE id
+ */
+export function createConnector(ideId) {
+    switch (ideId.toLowerCase()) {
+        case "cursor":
+            return new CursorConnector();
+        case "vscode":
+        case "code":
+            return new VSCodeConnector();
+        case "antigravity":
+        case "gemini":
+            return new AntigravityConnector();
+        case "windsurf":
+            return new WindsurfConnector();
+        case "claude":
+        case "codex":
+        default:
+            // Fallback to filesystem bridge for unsupported IDEs
+            return new FilesystemBridgeConnector();
+    }
+}

package/dist/bridge/connectors/antigravity-connector.js

@@ -0,0 +1,18 @@
+import { FilesystemBridgeConnector } from "../filesystem-connector.js";
+/**
+ * Antigravity connector
+ * Uses filesystem bridge (Antigravity doesn't have a standalone CLI)
+ */
+export class AntigravityConnector extends FilesystemBridgeConnector {
+    id = "antigravity";
+    displayName = "Antigravity (Google Gemini)";
+    async isAvailable() {
+        // Antigravity is always "available" via filesystem bridge
+        // The user interacts through the Gemini interface
+        return true;
+    }
+    async ensureRunning() {
+        await super.ensureRunning();
+        // No additional setup needed for Antigravity
+    }
+}

package/dist/bridge/connectors/cursor-connector.js

@@ -0,0 +1,31 @@
+import { execSync } from "child_process";
+import { FilesystemBridgeConnector } from "../filesystem-connector.js";
+/**
+ * Cursor IDE connector
+ * Extends filesystem bridge with Cursor CLI integration
+ */
+export class CursorConnector extends FilesystemBridgeConnector {
+    id = "cursor";
+    displayName = "Cursor IDE";
+    async isAvailable() {
+        try {
+            execSync("which cursor", { stdio: "ignore" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async ensureRunning() {
+        await super.ensureRunning();
+        // Try to open Cursor if available
+        if (await this.isAvailable()) {
+            try {
+                execSync("cursor --version", { stdio: "ignore" });
+            }
+            catch {
+                // Cursor not running or not available, continue anyway
+            }
+        }
+    }
+}

package/dist/bridge/connectors/vscode-connector.js

@@ -0,0 +1,31 @@
+import { execSync } from "child_process";
+import { FilesystemBridgeConnector } from "../filesystem-connector.js";
+/**
+ * VS Code connector
+ * Extends filesystem bridge with VS Code CLI integration
+ */
+export class VSCodeConnector extends FilesystemBridgeConnector {
+    id = "vscode";
+    displayName = "Visual Studio Code";
+    async isAvailable() {
+        try {
+            execSync("which code", { stdio: "ignore" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async ensureRunning() {
+        await super.ensureRunning();
+        // Try to verify VS Code is available
+        if (await this.isAvailable()) {
+            try {
+                execSync("code --version", { stdio: "ignore" });
+            }
+            catch {
+                // VS Code not running or not available, continue anyway
+            }
+        }
+    }
+}

package/dist/bridge/connectors/windsurf-connector.js

@@ -0,0 +1,23 @@
+import { execSync } from "child_process";
+import { FilesystemBridgeConnector } from "../filesystem-connector.js";
+/**
+ * Windsurf connector
+ * Extends filesystem bridge with Windsurf CLI integration (if available)
+ */
+export class WindsurfConnector extends FilesystemBridgeConnector {
+    id = "windsurf";
+    displayName = "Windsurf";
+    async isAvailable() {
+        try {
+            execSync("which windsurf", { stdio: "ignore" });
+            return true;
+        }
+        catch {
+            // Fallback to filesystem bridge
+            return true;
+        }
+    }
+    async ensureRunning() {
+        await super.ensureRunning();
+    }
+}

package/dist/bridge/filesystem-connector.js

@@ -0,0 +1,100 @@
+import fs from "fs";
+import path from "path";
+const BRIDGE_DIR = path.join(process.cwd(), ".iris/bridge");
+const INBOX_DIR = path.join(BRIDGE_DIR, "inbox");
+const OUTBOX_DIR = path.join(BRIDGE_DIR, "outbox");
+const STATE_DIR = path.join(BRIDGE_DIR, "state");
+/**
+ * Filesystem-based bridge connector (baseline implementation)
+ * Works by writing/reading JSON files in .iris/bridge/
+ */
+export class FilesystemBridgeConnector {
+    id = "filesystem";
+    displayName = "Filesystem Bridge";
+    async isAvailable() {
+        // Always available - just needs filesystem
+        return true;
+    }
+    async ensureRunning() {
+        // Ensure bridge directories exist
+        for (const dir of [INBOX_DIR, OUTBOX_DIR, STATE_DIR]) {
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+        }
+    }
+    async sendTask(packet) {
+        await this.ensureRunning();
+        const inboxPath = path.join(INBOX_DIR, `${packet.taskId}.json`);
+        fs.writeFileSync(inboxPath, JSON.stringify(packet, null, 2), "utf8");
+        // Also create a human-readable prompt file
+        const promptPath = path.join(STATE_DIR, `${packet.taskId}.md`);
+        const promptContent = this.generatePrompt(packet);
+        fs.writeFileSync(promptPath, promptContent, "utf8");
+        return { taskId: packet.taskId };
+    }
+    async waitResult(taskId, opts) {
+        const timeoutMs = opts?.timeoutMs || 300000; // 5 minutes default
+        const pollIntervalMs = opts?.pollIntervalMs || 1000; // 1 second
+        const outboxPath = path.join(OUTBOX_DIR, `${taskId}.json`);
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            if (fs.existsSync(outboxPath)) {
+                const content = fs.readFileSync(outboxPath, "utf8");
+                const result = JSON.parse(content);
+                // Clean up
+                fs.unlinkSync(outboxPath);
+                const inboxPath = path.join(INBOX_DIR, `${taskId}.json`);
+                if (fs.existsSync(inboxPath)) {
+                    fs.unlinkSync(inboxPath);
+                }
+                return result;
+            }
+            // Wait before next poll
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        }
+        throw new Error(`Timeout waiting for result: ${taskId}`);
+    }
+    generatePrompt(packet) {
+        return `# IRIS Workflow Task
+
+**Task ID:** ${packet.taskId}
+**Stage:** ${packet.stage}
+**Agent:** ${packet.agent}
+
+## Intent
+
+${packet.intent}
+
+## Instructions
+
+${packet.instructions}
+
+## Input Files
+
+${packet.inputs.map(p => `- [\`${path.basename(p)}\`](file://${path.resolve(p)})`).join("\n")}
+
+## Expected Outputs
+
+${packet.expectedOutputs.map(p => `- \`${p}\``).join("\n")}
+
+${packet.gates ? `\n## Gates\n\n${packet.gates.join("\n")}\n` : ""}
+
+---
+
+**When complete, create a result file at:**
+\`.iris/bridge/outbox/${packet.taskId}.json\`
+
+**Result format:**
+\`\`\`json
+{
+  "taskId": "${packet.taskId}",
+  "status": "ok" | "needs_user" | "error",
+  "message": "Description of what was done",
+  "filesChanged": ["path/to/file1.md", "path/to/file2.md"],
+  "logs": ["Optional log messages"]
+}
+\`\`\`
+`;
+    }
+}

package/dist/bridge/types.js

@@ -0,0 +1,10 @@
+/**
+ * Bridge types for navi develop workflow
+ */
+export var WorkflowStage;
+(function (WorkflowStage) {
+    WorkflowStage["INTENT_INCEPTION"] = "INTENT_INCEPTION";
+    WorkflowStage["BOLT_PLAN"] = "BOLT_PLAN";
+    WorkflowStage["BOLT_EXECUTION"] = "BOLT_EXECUTION";
+    WorkflowStage["DONE"] = "DONE";
+})(WorkflowStage || (WorkflowStage = {}));

package/dist/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { installCommand } from "./commands/install.js";
+import { uninstallCommand } from "./commands/uninstall.js";
+import { phaseCommand } from "./commands/phase.js";
+import { validateCommand } from "./commands/validate.js";
+import { statusCommand } from "./commands/status.js";
+import { runCommand } from "./commands/run.js";
+import { packCommand } from "./commands/pack.js";
+import { askCommand } from "./commands/ask.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { developCommand } from "./commands/develop.js";
+import { bridgeCommand } from "./commands/bridge.js";
+const program = new Command();
+program
+    .name("iris")
+    .description("IRIS CLI - Intelligent Repository for Intent-driven Systems")
+    .version("0.0.06")
+    .addCommand(installCommand)
+    .addCommand(uninstallCommand)
+    .addCommand(phaseCommand)
+    .addCommand(validateCommand)
+    .addCommand(statusCommand)
+    .addCommand(packCommand)
+    .addCommand(runCommand)
+    .addCommand(askCommand)
+    .addCommand(doctorCommand)
+    .addCommand(developCommand)
+    .addCommand(bridgeCommand);
+program.parseAsync(process.argv);