project-iris 0.0.1

package/README.md

@@ -0,0 +1,424 @@
+# 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
+```
+
+---
+
+## 🔄 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"
+```
+
+> **Note**: `iris ask` uses the active agent set by `iris use`. Default is `auto` (In-Process Agent).
+
+### Context Generation
+
+```bash
+# Generate context pack for current phase
+iris pack
+
+# Target specific agent
+iris pack --agent inception
+
+# Output to stdout
+iris pack --stdout
+```
+
+### Workflow Execution
+
+```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
+```
+
+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
+
+```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
+```
+
+### Lifecycle Management
+
+```bash
+# View current status
+iris status
+
+# Request phase transition
+iris phase set construction
+
+# Validate and apply transition
+iris validate --apply
+```
+
+### 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"
+
+# Auto-approve gates
+iris develop --gate auto "intent"
+```
+
+### 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:
+
+```bash
+# Start bridge helper (only needed for external IDEs)
+iris bridge serve
+
+# Check bridge status
+iris bridge status
+```
+
+### Diagnostics
+
+```bash
+# Check environment
+iris doctor
+
+# Show version
+iris --version
+```
+
+---
+
+## 📁 Directory Structure
+
+```
+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
+```
+
+---
+
+## � 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
+```
+
+### Routes (`routes.yaml`)
+
+```yaml
+schemaVersion: 1
+routes:
+  - match: "bug|fix|error"
+    agent: construction
+  - match: ".*"
+    agent: inception
+```
+
+---
+
+## 🤖 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"}
+```
+
+---
+
+## 👥 Contributing
+
+### Setup
+
+```bash
+git clone <repo-url>
+cd project-iris
+npm ci
+npm run build
+npm link
+iris --version
+```
+
+### Development
+
+```bash
+# Make changes to src/
+npm run build
+npm run test
+
+# Run all verification
+npm run verify
+```
+
+### Testing
+
+```bash
+# 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/bridge/agent-runner.js

@@ -0,0 +1,190 @@
+import fs from "fs";
+import path from "path";
+import kleur from "kleur";
+import { INBOX_DIR, OUTBOX_DIR } from "./helper.js";
+export async function startAgentRunner(options = {}) {
+    const pollInterval = options.pollInterval || 2000;
+    const verbose = options.verbose !== false;
+    console.log(kleur.bold("🤖 IRIS Automated Agent Started"));
+    console.log(kleur.dim(`   Watching: ${INBOX_DIR}`));
+    console.log(kleur.dim(`   Answering to: ${OUTBOX_DIR}\n`));
+    // Ensure directories
+    fs.mkdirSync(INBOX_DIR, { recursive: true });
+    fs.mkdirSync(OUTBOX_DIR, { recursive: true });
+    const processed = new Set();
+    // Polling Loop
+    setInterval(async () => {
+        try {
+            const files = fs.readdirSync(INBOX_DIR).filter(f => f.endsWith(".json"));
+            for (const file of files) {
+                if (processed.has(file))
+                    continue;
+                const filePath = path.join(INBOX_DIR, file);
+                try {
+                    const content = fs.readFileSync(filePath, "utf8");
+                    const task = JSON.parse(content);
+                    processed.add(file);
+                    const outPath = path.join(OUTBOX_DIR, file);
+                    if (fs.existsSync(outPath)) {
+                        processed.add(file);
+                        continue;
+                    }
+                    if (verbose) {
+                        console.log(kleur.cyan(`\n[Active] Processing task: ${task.taskId}`));
+                        console.log(kleur.dim(`  Stage: ${task.stage}`));
+                        console.log(kleur.dim(`  Intent: ${task.intent}`));
+                    }
+                    // Think...
+                    await new Promise(r => setTimeout(r, 1000)); // Simulate latency
+                    // Handle
+                    const result = await handleTask(task);
+                    // Respond
+                    fs.writeFileSync(outPath, JSON.stringify(result, null, 2));
+                    console.log(kleur.green(`  ✓ Responded to ${task.taskId}`));
+                }
+                catch (err) {
+                    console.error(kleur.red(`  ✗ Failed to process ${file}: ${err.message}`));
+                }
+            }
+        }
+        catch (e) {
+            // Ignore read errors
+        }
+    }, pollInterval);
+}
+// Heuristic Intelligence
+export async function handleTask(task) {
+    // 1. Intent Inception (Ping-Pong)
+    if (task.stage === "INTENT_INCEPTION" && task.metadata?.step === "clarify_turn") {
+        return handleClarification(task);
+    }
+    // 2. Artifact Generation
+    if (task.stage === "INTENT_INCEPTION" && task.metadata?.step === "generate_artifacts") {
+        return handleArtifactGeneration(task);
+    }
+    // 3. Bolt Plan
+    if (task.stage === "BOLT_PLAN" && task.metadata?.step === "generate_bolt_plan") {
+        return handleBoltPlan(task);
+    }
+    // Default fallback
+    return {
+        taskId: task.taskId,
+        status: "ok",
+        message: "DONE",
+        filesChanged: []
+    };
+}
+function handleClarification(task) {
+    const instructions = task.instructions || "";
+    const historyLines = instructions.split("\n").filter(l => l.trim().startsWith("Q:"));
+    const turnCount = historyLines.length;
+    let message = "DONE";
+    // Simple Script
+    if (turnCount === 0) {
+        message = "\"Who is the primary user for this application?\"";
+    }
+    else if (turnCount === 1) {
+        message = "\"What are the key technical constraints (Language, DB)?\"";
+    }
+    else if (turnCount === 2) {
+        message = "\"What are the success criteria for this project?\"";
+    }
+    else if (turnCount === 3) {
+        message = "\"What are the non-goals (what should we NOT build)?\"";
+    }
+    else {
+        message = "\"DONE\"";
+    }
+    return {
+        taskId: task.taskId,
+        status: "ok",
+        message,
+        filesChanged: []
+    };
+}
+function handleArtifactGeneration(task) {
+    const intentSlug = task.metadata?.intentSlug || "default";
+    const prompt = task.instructions || "";
+    // 1. Parse Inputs (Poor man's extraction from "User Answers" section of prompt)
+    let targetUser = "Unknown User";
+    let techStack = "Node.js (Default)";
+    let successCriteria = "- Standard success criteria";
+    let nonGoals = "- None specified";
+    // Extract Answers
+    const qaRegex = /Q: (.*?)\nA: (.*?)(?=\nQ:|\n$)/gs;
+    const matches = [...prompt.matchAll(qaRegex)];
+    matches.forEach(([, q, a]) => {
+        const qLower = q.toLowerCase();
+        if (qLower.includes("primary user"))
+            targetUser = a.trim();
+        else if (qLower.includes("technical constraints"))
+            techStack = a.trim();
+        else if (qLower.includes("success criteria"))
+            successCriteria = a.trim().split('.').map(s => s.trim()).filter(Boolean).map(s => `- ${s}`).join("\n");
+        else if (qLower.includes("non-goals"))
+            nonGoals = a.trim().split('.').map(s => s.trim()).filter(Boolean).map(s => `- ${s}`).join("\n");
+    });
+    // 2. Generate Requirements
+    const reqContent = `# Requirements: ${task.intent}
+
+## Goal
+${task.intent}
+
+## Target User
+${targetUser}
+
+## Success Criteria
+${successCriteria}
+
+## Non-Goals
+${nonGoals}
+
+## Functional Requirements (Inferred)
+- User should be able to complete the core workflows described in criteria.
+- System should be performant and reliable.
+`;
+    // 3. Generate System Context
+    const sysContent = `# System Context
+
+## Tech Stack
+${techStack}
+
+## Architecture Decisions
+- **Frontend / Backend Split**: as implied by tech stack.
+- **Data Persistence**: ${techStack.includes("firebase") ? "Firebase" : "Local/File-based (Default)"}.
+
+## Constraints
+- ${techStack}
+`;
+    const root = process.cwd();
+    const reqPath = `memory-bank/intents/${intentSlug}/requirements.md`;
+    const sysPath = `memory-bank/intents/${intentSlug}/system-context.md`;
+    ensureFile(path.join(root, reqPath), reqContent);
+    ensureFile(path.join(root, sysPath), sysContent);
+    return {
+        taskId: task.taskId,
+        status: "ok",
+        message: "Artifacts generated.",
+        filesChanged: [reqPath, sysPath]
+    };
+}
+function handleBoltPlan(task) {
+    const root = process.cwd();
+    const planPath = "memory-bank/operations/bolts/plan.md";
+    const boltPath = "memory-bank/operations/bolts/b001-bootstrap.md";
+    const planContent = `# Bolt Plan\n\n- [ ] [B001] [Bootstrap Project](./b001-bootstrap.md)\n`;
+    const boltContent = `# Bolt: Bootstrap\n\n## Tasks\n- [ ] Init project\n\n## Acceptance\n- runs\n`;
+    ensureFile(path.join(root, planPath), planContent);
+    ensureFile(path.join(root, boltPath), boltContent);
+    return {
+        taskId: task.taskId,
+        status: "ok",
+        message: "Plan generated.",
+        filesChanged: [planPath, boltPath]
+    };
+}
+function ensureFile(p, content) {
+    const dir = path.dirname(p);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, content);
+}

package/dist/bridge/connector-factory.js

@@ -0,0 +1,31 @@
+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";
+import { InProcessBridgeConnector } from "./connectors/in-process-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 "auto":
+        case "internal":
+            return new InProcessBridgeConnector();
+        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
+            }
+        }
+    }
+}