iriai-build

AI agent orchestration CLI for planning, implementing, and shipping features. Drives multi-agent workflows from the terminal or via Slack, using the claude CLI as the underlying execution engine.

Prerequisites

• Node.js >= 18
• claude CLI installed and available on PATH (or configured via CLAUDE_BIN)

Installation

npm install -g iriai-build

Usage

Run iriai-build with no arguments for an interactive menu, or use a subcommand directly.

iriai-build [command] [options]

Commands

| Command | Alias | Description | |---|---|---| | launch [description] | | Full flow: planning, implementation, and completion in one session | | plan [description] | | Run the planning pipeline only. Prompts to continue to implementation after approval | | implementation | impl | Select from planned or in-progress features and run implementation | | slack | | Launch the Slack bridge for async decisions and updates via Slack | | transfer-to-slack | | Sync CLI-created features to Slack channels and start the bridge | | setup | | Interactive configuration for tokens, tool paths, budget tier, and preferences |

Global Options

| Flag | Description | |---|---| | --budget <tier> | Set budget tier: unrestricted, econ, or budget |

How It Works

Feature Lifecycle

Each feature moves through a state machine:

1. Planning — Sequential agent pipeline: PM → Designer → Architect → Plan Compiler, with phase-review gates between each stage
2. Plan Approval — User reviews compiled plan, approves or rejects
3. Implementation — Feature Lead dispatches teams, role agents execute phases in parallel, review agents audit at gate boundaries
4. Gate Reviews — Review agents produce evidence; user approves or rejects each gate
5. Completion — Feature branch merged to main

Signal-Based Agent Communication

Agents and the orchestrator communicate via filesystem signals:

• .task / .user-message — Bridge → Agent (job descriptions, user replies)
• .agent-response / .done / .question — Agent → Bridge (outputs, completion, decisions)
• .gate-approved / .gate-rejected — Bridge → Agent (verification results)

Multi-Team Coordination

Features are partitioned across teams that work in parallel. A Feature Lead coordinates progress, dispatches review agents at gate boundaries, and compiles evidence for user decisions.

Budget Tiers

Control cost and concurrency with three tiers:

| Tier | Models | Max Teams | Review Roles | |---|---|---|---| | unrestricted | Opus everywhere | 5 | All 5 reviewers | | econ | Opus FL, Sonnet others | 1 | Code reviewer + verifier | | budget | Sonnet/Haiku | 1 | Verifier only |

All tiers use the same timeouts: 75min per role agent, 45min for Feature Lead.

Terminal vs Slack

• Terminal mode — Full feature lifecycle with inline @inquirer/prompts decisions. No Slack required.
• Slack mode — Long-running bridge posts Block Kit decisions to Slack channels. Supports async collaboration across multiple users.
• Transfer — Features started in the terminal can be synced to Slack via transfer-to-slack.

Configuration

Run iriai-build setup to configure interactively. Values are saved to ~/.iriai/config.json.

| Setting | Config key | Env var override | Default | |---|---|---|---| | Project root | project_root | PROJECT_ROOT | Current directory | | Claude CLI path | claude_bin | CLAUDE_BIN | claude | | QA feedback tool | qa_feedback_bin | QA_FEEDBACK_BIN | iriai-feedback | | Slack App Token | slack_app_token | SLACK_APP_TOKEN | — | | Slack Bot Token | slack_bot_token | SLACK_BOT_TOKEN | — | | Slack Channel ID | slack_channel_id | SLACK_CHANNEL_ID | — | | Budget tier | budget_tier | IRIAI_BUDGET | unrestricted |

Environment variables always take precedence over config file values. Slack tokens are required only for slack and transfer-to-slack commands.

Running as a Service (macOS)

A launchd plist is included for running the Slack bridge as a persistent background service:

# Install
launchctl load com.iriai.slack-bridge-v3.plist

# Restart
touch .restart-bridge-v3

# Logs
tail -f /tmp/iriai-bridge-v3.log

The service auto-restarts on crash and prevents macOS sleep while running.

Architecture

bin/cli.js              CLI entry point (commander)
cli/commands/           Command implementations
v3/
  orchestrator.js       Core state machine (planning → impl → completion)
  agent-supervisor.js   Process spawning, health monitoring, retries
  file-io.js            Signal directory watcher (chokidar)
  recovery.js           Startup recovery for orphaned processes
  adapters/
    slack-adapter.js    Socket Mode + Block Kit decisions
    terminal-adapter.js @inquirer/prompts inline decisions
  budget.js             Tier presets (models, concurrency, timeouts)
  schema.sql            SQLite schema (features, agents, decisions, events)
bridge-v3.js            Slack bridge entry point
lib/                    Shared utilities (agent process, slack helpers)

Database

State is persisted in SQLite (~/.iriai/bridge-v3.db) with tables for features, agents, decisions, events, and an operator relay queue.