iriai-build 0.3.1 → 0.4.0

package/bin/cli.js

@@ -38,23 +38,26 @@ program
 program
   .command("plan [description]")
   .description("Run planning pipeline. After plan approved, prompts to continue to implementation.")
-  .action(async (description) => {
-    await withReadyCheck(() => planCommand(description));
+  .option("--budget <tier>", "Usage budget tier: unrestricted, econ, or budget")
+  .action(async (description, opts) => {
+    await withReadyCheck(() => planCommand(description, opts));
   });
 
 program
   .command("implementation")
   .alias("impl")
   .description("Select from planned/in-progress features and run implementation.")
-  .action(async () => {
-    await withReadyCheck(() => implementationCommand());
+  .option("--budget <tier>", "Usage budget tier: unrestricted, econ, or budget")
+  .action(async (opts) => {
+    await withReadyCheck(() => implementationCommand(opts));
   });
 
 program
   .command("launch [description]")
   .description("Full flow: planning -> implementation -> complete. Without arg: select or create.")
-  .action(async (description) => {
-    await withReadyCheck(() => launchCommand(description));
+  .option("--budget <tier>", "Usage budget tier: unrestricted, econ, or budget")
+  .action(async (description, opts) => {
+    await withReadyCheck(() => launchCommand(description, opts));
   });
 
 program

package/cli/bootstrap.js

@@ -11,17 +11,21 @@ import * as queries from "../v3/queries.js";
 import { DB_PATH, PORTAL_PORT } from "../v3/constants.js";
 import { ArtifactPortal } from "../v3/artifact-portal.js";
 import { slugify } from "../v3/helpers.js";
+import { resolveBudget } from "../v3/budget.js";
 
 /**
  * Bootstrap the engine for CLI use.
- * Returns { orchestrator, adapter, recovery, input, shutdown }.
+ * @param {object} [opts]
+ * @param {string} [opts.budgetOverride] - CLI flag override for budget tier
+ * Returns { orchestrator, adapter, recovery, input, shutdown, budget }.
  */
-export function bootstrap() {
+export function bootstrap({ budgetOverride } = {}) {
   db.open(DB_PATH);
 
+  const budget = resolveBudget(budgetOverride);
   const adapter = new TerminalAdapter();
   const reviewSessions = new ReviewSessionManager();
-  const orchestrator = new Orchestrator({ adapter, reviewSessions });
+  const orchestrator = new Orchestrator({ adapter, reviewSessions, budget });
   const input = new TerminalInput({ orchestrator });
   adapter.setInputHandler(input);
   const recovery = new Recovery({ orchestrator, adapter });
@@ -61,7 +65,7 @@ export function bootstrap() {
     });
   }
 
-  return { orchestrator, adapter, recovery, input, shutdown };
+  return { orchestrator, adapter, recovery, input, shutdown, budget };
 }
 
 /**

package/cli/commands/implementation.js

@@ -7,9 +7,10 @@ import { bootstrap } from "../bootstrap.js";
 import { banner, formatFeatureChoice, successMsg, systemMsg, errorMsg } from "../display.js";
 import { waitForCompletion } from "../wait.js";
 
-export async function implementationCommand() {
+export async function implementationCommand(opts = {}) {
   banner();
-  const { orchestrator, adapter, recovery, input, shutdown } = bootstrap();
+  const { orchestrator, adapter, recovery, input, shutdown, budget } = bootstrap({ budgetOverride: opts.budget });
+  systemMsg(`Budget: ${budget.label} — ${budget.description}`);
 
   const features = queries.getFeaturesForImplCommand();
   if (features.length === 0) {

package/cli/commands/launch.js

@@ -8,9 +8,10 @@ import { bootstrap, initNewFeature } from "../bootstrap.js";
 import { banner, formatFeatureChoice, successMsg, systemMsg, errorMsg } from "../display.js";
 import { waitForPlanDecision, waitForCompletion } from "../wait.js";
 
-export async function launchCommand(description) {
+export async function launchCommand(description, opts = {}) {
   banner();
-  const { orchestrator, adapter, recovery, input, shutdown } = bootstrap();
+  const { orchestrator, adapter, recovery, input, shutdown, budget } = bootstrap({ budgetOverride: opts.budget });
+  systemMsg(`Budget: ${budget.label} — ${budget.description}`);
 
   let featureId;
   let isNew = false;

package/cli/commands/plan.js

@@ -7,9 +7,10 @@ import { bootstrap, initNewFeature } from "../bootstrap.js";
 import { banner, formatFeatureChoice, successMsg, systemMsg, errorMsg } from "../display.js";
 import { waitForPlanDecision, waitForCompletion } from "../wait.js";
 
-export async function planCommand(description) {
+export async function planCommand(description, opts = {}) {
   banner();
-  const { orchestrator, adapter, recovery, input, shutdown } = bootstrap();
+  const { orchestrator, adapter, recovery, input, shutdown, budget } = bootstrap({ budgetOverride: opts.budget });
+  systemMsg(`Budget: ${budget.label} — ${budget.description}`);
 
   // Defer impl launch so we can prompt "Continue to implementation?" first
   orchestrator.deferImplLaunch = true;

package/cli/commands/setup.js

@@ -1,9 +1,10 @@
 // setup.js — `iriai-build setup` command.
 // Interactive config for Slack tokens and tool paths.
 
-import { input, confirm } from "@inquirer/prompts";
+import { input, confirm, select } from "@inquirer/prompts";
 import * as config from "../config.js";
 import { banner, systemMsg, successMsg, errorMsg } from "../display.js";
+import { BUDGET_TIERS } from "../../v3/budget.js";
 
 function mask(value) {
   if (!value) return null;
@@ -47,6 +48,20 @@ export async function setupCommand() {
     message: `Slack Planning Channel ID (C...):${hint(current.slack_channel_id)}`,
   });
 
+  // Budget tier
+  console.log("\n\x1b[1mUsage Budget\x1b[0m");
+  console.log("\x1b[2mControls model selection, team count, and review depth during implementation.\x1b[0m");
+  console.log("\x1b[2mPlanning is always full-quality regardless of tier.\x1b[0m\n");
+
+  const budgetTier = await select({
+    message: `Usage budget:${hint(current.budget_tier || "unrestricted")}`,
+    choices: Object.entries(BUDGET_TIERS).map(([key, tier]) => ({
+      name: `${tier.label} — ${tier.description}`,
+      value: key,
+    })),
+    default: current.budget_tier || "unrestricted",
+  });
+
   // Tool paths
   console.log("\n\x1b[1mTool Paths\x1b[0m");
   console.log("\x1b[2mOptional — Enter to keep defaults.\x1b[0m\n");
@@ -67,6 +82,7 @@ export async function setupCommand() {
   if (channelId) updates.slack_channel_id = channelId;
   if (claudeBin) updates.claude_bin = claudeBin;
   if (qaFeedbackBin) updates.qa_feedback_bin = qaFeedbackBin;
+  updates.budget_tier = budgetTier;
 
   config.save(updates);
 

package/cli/config.js

@@ -92,6 +92,14 @@ export function getProjectRoot() {
   return get("project_root", "PROJECT_ROOT") || process.cwd();
 }
 
+/**
+ * Get the budget tier. Env var IRIAI_BUDGET overrides config file.
+ * Defaults to null (will be prompted on first run).
+ */
+export function getBudgetTier() {
+  return get("budget_tier", "IRIAI_BUDGET") || null;
+}
+
 /**
  * Get the config file path (for display purposes).
  */

package/cli/first-run.js

@@ -5,9 +5,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
-import { input } from "@inquirer/prompts";
+import { input, select } from "@inquirer/prompts";
 import * as config from "./config.js";
 import { banner, systemMsg, successMsg, errorMsg, separator } from "./display.js";
+import { BUDGET_TIERS } from "../v3/budget.js";
 
 const C = {
   reset: "\x1b[0m",
@@ -65,10 +66,27 @@ export async function onboard() {
     default: detectedClaude || "claude",
   });
 
+  // 3. Budget tier
+  console.log("");
+  console.log(`${C.bold}Usage Budget${C.reset}`);
+  console.log(`${C.dim}Controls model selection, team count, and review depth during implementation.${C.reset}`);
+  console.log(`${C.dim}Planning is always full-quality regardless of tier. Change anytime via ${C.bold}iriai-build setup${C.reset}${C.dim}.${C.reset}`);
+  console.log("");
+
+  const budgetTier = await select({
+    message: "Select your usage budget:",
+    choices: Object.entries(BUDGET_TIERS).map(([key, tier]) => ({
+      name: `${tier.label} — ${tier.description}`,
+      value: key,
+    })),
+    default: "unrestricted",
+  });
+
   // Save minimal config
   config.save({
     project_root: resolvedRoot,
     claude_bin: claudeBin || detectedClaude || "claude",
+    budget_tier: budgetTier,
   });
 
   console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iriai-build",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Iriai Build tool — AI agent orchestration CLI",
   "type": "module",
   "bin": {

package/v3/agent-supervisor.js

@@ -13,11 +13,13 @@ import {
   ROLE_HARD_TIMEOUT_MS, ORCH_SOFT_TIMEOUT_MS, FL_SOFT_TIMEOUT_MS,
   RSS_CEILING_KB, STUCK_THRESHOLD_MS, HEALTH_CHECK_INTERVAL_MS,
 } from "./constants.js";
+import { resolveBudget } from "./budget.js";
 import { readSignal, ensureDir } from "./helpers.js";
 
 export class AgentSupervisor extends EventEmitter {
-  constructor() {
+  constructor(budget) {
     super();
+    this.budget = budget || resolveBudget();
     // agentKey -> { process: AgentProcess, retryTimer, healthRegistered }
     this._processes = {};
     this._healthTimer = null;
@@ -254,7 +256,8 @@ export class AgentSupervisor extends EventEmitter {
       const agent = queries.getAgentByKey(key);
       if (!agent) continue;
 
-      // Hard timeout based on agent type
+      // Hard timeout based on agent type (budget-aware for role and FL)
+      const budgetTimeouts = this.budget.timeouts;
       let hardTimeout;
       switch (agent.agent_type) {
         case "planning-role":
@@ -262,16 +265,16 @@ export class AgentSupervisor extends EventEmitter {
           break;
         case "role-agent":
         case "review-agent":
-          hardTimeout = ROLE_HARD_TIMEOUT_MS;
+          hardTimeout = budgetTimeouts.roleHardMs;
           break;
         case "team-orchestrator":
           hardTimeout = ORCH_SOFT_TIMEOUT_MS;
           break;
         case "feature-lead":
-          hardTimeout = FL_SOFT_TIMEOUT_MS;
+          hardTimeout = budgetTimeouts.flSoftMs;
           break;
         default:
-          hardTimeout = ROLE_HARD_TIMEOUT_MS;
+          hardTimeout = budgetTimeouts.roleHardMs;
       }
 
       if (hardTimeout && elapsed > hardTimeout) {

package/v3/budget.js

@@ -0,0 +1,110 @@
+// budget.js — Budget tier presets for iriai-build.
+// Controls model selection, team limits, role sets, review agents, timeouts, and retries.
+// Planning phase is identical across all tiers.
+
+import * as config from "../cli/config.js";
+
+export const BUDGET_TIERS = {
+  unrestricted: {
+    label: "Unrestricted",
+    description: "Full power — Opus everywhere, up to 5 teams, all review agents",
+    models: {
+      "feature-lead": "opus",
+      "team-orchestrator": "opus",
+      "role-agent": "opus",
+      "review-agent": "opus",
+      operator: "haiku",
+    },
+    maxTeams: 5,
+    reviewRoles: ["integration-tester", "code-reviewer", "security-auditor", "regression-tester", "verifier"],
+    timeouts: {
+      roleHardMs: 75 * 60 * 1000,
+      flSoftMs: 45 * 60 * 1000,
+    },
+    retries: {
+      role: 3,
+      orchestrator: 3,
+      featureLead: 5,
+      featureLeadInit: 3,
+      planning: 5,
+      operator: 3,
+    },
+  },
+
+  econ: {
+    label: "Econ",
+    description: "Balanced — Sonnet for most agents, 1 team, code reviewer + verifier",
+    models: {
+      "feature-lead": "opus",
+      "team-orchestrator": "sonnet",
+      "role-agent": "sonnet",
+      "review-agent": "sonnet",
+      operator: "haiku",
+    },
+    maxTeams: 1,
+    reviewRoles: ["code-reviewer", "verifier"],
+    timeouts: {
+      roleHardMs: 30 * 60 * 1000,
+      flSoftMs: 20 * 60 * 1000,
+    },
+    retries: {
+      role: 2,
+      orchestrator: 2,
+      featureLead: 3,
+      featureLeadInit: 2,
+      planning: 5,
+      operator: 3,
+    },
+  },
+
+  budget: {
+    label: "Budget",
+    description: "Minimal spend — Haiku/Sonnet, 1 team, verifier only",
+    models: {
+      "feature-lead": "sonnet",
+      "team-orchestrator": "sonnet",
+      "role-agent": "haiku",
+      "review-agent": "haiku",
+      operator: "haiku",
+    },
+    maxTeams: 1,
+    reviewRoles: ["verifier"],
+    timeouts: {
+      roleHardMs: 15 * 60 * 1000,
+      flSoftMs: 10 * 60 * 1000,
+    },
+    retries: {
+      role: 1,
+      orchestrator: 1,
+      featureLead: 2,
+      featureLeadInit: 1,
+      planning: 5,
+      operator: 3,
+    },
+  },
+};
+
+/**
+ * Resolve the active budget tier. Priority: explicit override > config > default (unrestricted).
+ * @param {string} [override] - CLI flag override (e.g., --budget econ)
+ * @returns {object} The budget preset object
+ */
+export function resolveBudget(override) {
+  const tierName = override || config.get("budget_tier") || "unrestricted";
+  const tier = BUDGET_TIERS[tierName];
+  if (!tier) {
+    console.warn(`[budget] Unknown tier "${tierName}", falling back to unrestricted`);
+    return { ...BUDGET_TIERS.unrestricted, name: "unrestricted" };
+  }
+  return { ...tier, name: tierName };
+}
+
+/**
+ * Get the model for a given agent type from the budget.
+ * @param {object} budget - Resolved budget preset
+ * @param {string} agentType - One of: feature-lead, team-orchestrator, role-agent, review-agent, operator
+ * @returns {string} Model name (opus, sonnet, haiku)
+ */
+export function getModel(budget, agentType) {
+  return budget.models[agentType] || "opus";
+}

package/v3/constants.js

@@ -163,10 +163,12 @@ export const AVAILABLE_TEMPLATES = [];
 export const PORTAL_PORT = process.env.PORTAL_PORT ? parseInt(process.env.PORTAL_PORT) : 8900;
 
 // ─── Feature Review Roles ────────────────────────────────────────────────────
+// Default (unrestricted) review roles. Budget-aware code should use budget.reviewRoles instead.
 
 export const FEATURE_REVIEW_ROLES = [
   "integration-tester",
   "code-reviewer",
   "security-auditor",
-  "health-monitor",
+  "regression-tester",
+  "verifier",
 ];

package/v3/launch-impl.js

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
 import { IMPL_BASE, PROJECT_ROOT, V3_ROLES_DIR } from "./constants.js";
+import { resolveBudget } from "./budget.js";
 
 const LEADERSHIP_ROLES = new Set([
   "orchestrator", "feature-lead", "planning-lead", "pm", "designer", "architect", "operator",
@@ -76,25 +77,43 @@ function discoverDispatchRoles(rolesDir) {
  *
  * @param {string} featureSlug - Kebab-case feature name
  * @param {object} opts
- * @param {number} [opts.numTeams=2] - Number of teams
+ * @param {number} [opts.numTeams] - Number of teams (capped by budget.maxTeams)
  * @param {string[]} [opts.roles] - Explicit roles (auto-discovered if not set)
  * @param {string} [opts.rolesDir] - Roles directory (defaults to V3_ROLES_DIR)
  * @param {string} [opts.implBase] - Implementation signal base directory
  * @param {string} [opts.planDir] - Plan directory to check for plan.yaml
+ * @param {object} [opts.budget] - Resolved budget preset (from resolveBudget())
  */
 export function launchImpl(featureSlug, {
-  numTeams = 2,
+  numTeams,
   roles,
   rolesDir = V3_ROLES_DIR,
   implBase = IMPL_BASE,
   planDir,
+  budget: budgetOverride,
 } = {}) {
+  const budget = budgetOverride || resolveBudget();
   const dispatchRoles = roles || discoverDispatchRoles(rolesDir);
   const featureDir = path.join(implBase, "features", featureSlug);
 
+  // Determine team count: explicit param > plan.yaml num_teams > budget max.
+  // Plan compiler should set num_teams based on actual plan structure (not to fill a max).
+  // Budget maxTeams is always the hard cap.
+  let planTeams = numTeams;
+  if (!planTeams && planDir) {
+    try {
+      const planYaml = fs.readFileSync(path.join(planDir, "plan.yaml"), "utf-8");
+      const match = planYaml.match(/^num_teams:\s*(\d+)/m);
+      if (match) planTeams = parseInt(match[1], 10);
+    } catch { /* no plan.yaml or no num_teams field */ }
+  }
+  const effectiveTeams = Math.min(planTeams || budget.maxTeams, budget.maxTeams);
+
   console.log(`\nLaunching feature: ${featureSlug}`);
-  console.log(`  Teams: ${numTeams}`);
+  console.log(`  Budget: ${budget.label}`);
+  console.log(`  Teams: ${effectiveTeams} (max: ${budget.maxTeams})`);
   console.log(`  Roles per team: ${dispatchRoles.length}`);
+  console.log(`  Review roles: ${budget.reviewRoles.join(", ")}`);
   console.log(`  Signal base: ${featureDir}`);
 
   // Warn if no plan.yaml
@@ -117,15 +136,15 @@ export function launchImpl(featureSlug, {
     symlinkRole(rolesDir, "operator", opDir);
   }
 
-  // Feature-level review roles
-  for (const reviewRole of ["code-reviewer", "integration-tester", "security-auditor"]) {
+  // Feature-level review roles (budget-aware)
+  for (const reviewRole of budget.reviewRoles) {
     const reviewDir = path.join(featureDir, "feature-review", reviewRole);
     fs.mkdirSync(reviewDir, { recursive: true });
     symlinkRole(rolesDir, reviewRole, reviewDir);
   }
 
   // Per-team directories
-  for (let i = 1; i <= numTeams; i++) {
+  for (let i = 1; i <= effectiveTeams; i++) {
     const teamDir = path.join(featureDir, "teams", `team-${i}`);
     const orchDir = path.join(teamDir, "orchestrator");
 
@@ -190,11 +209,13 @@ export function launchImpl(featureSlug, {
   }
   fs.writeFileSync(path.join(flMcpDir, "settings.local.json"), JSON.stringify({ mcpServers: flServers }, null, 2) + "\n");
 
-  // Feature-level review roles
-  configureMcp("integration-tester", path.join(featureDir, "feature-review", "integration-tester"));
+  // Feature-level review roles (only configure MCP for roles in budget)
+  if (budget.reviewRoles.includes("integration-tester")) {
+    configureMcp("integration-tester", path.join(featureDir, "feature-review", "integration-tester"));
+  }
 
   // Per-team roles
-  for (let i = 1; i <= numTeams; i++) {
+  for (let i = 1; i <= effectiveTeams; i++) {
     const teamDir = path.join(featureDir, "teams", `team-${i}`);
     configureMcp("orchestrator", path.join(teamDir, "orchestrator"));
     for (const role of dispatchRoles) {

package/v3/orchestrator.js

@@ -18,6 +18,7 @@ import {
 } from "./prompt-builder.js";
 import { planningComplete } from "./planning-complete.js";
 import { launchImpl } from "./launch-impl.js";
+import { resolveBudget, getModel } from "./budget.js";
 import {
   IMPL_BASE, IRIAI_TEAM_DIR, PROJECT_ROOT,
   V3_ROLES_DIR, PLANNING_ROLES, PLANNING_ROLE_LABELS,
@@ -38,10 +39,11 @@ import { formatAnnotationsAsFeedback } from "./review-sessions.js";
 import { compilePlanReviewHtml } from "./plan-compiler.js";
 
 export class Orchestrator {
-  constructor({ adapter, reviewSessions = null }) {
+  constructor({ adapter, reviewSessions = null, budget = null }) {
     this.adapter = adapter;
     this.reviewSessions = reviewSessions;
-    this.supervisor = new AgentSupervisor();
+    this.budget = budget || resolveBudget();
+    this.supervisor = new AgentSupervisor(this.budget);
     this.fileIO = new FileIO();
 
     // Per-feature signal trees (discovered on launch)
@@ -348,6 +350,11 @@ export class Orchestrator {
       `THREAD_TS=${feature.thread_ts}`,
     ];
 
+    // Inject available review roles for architect and plan-compiler
+    if (role === "architect" || role === "plan-compiler") {
+      taskHeaderLines.push(`AVAILABLE_REVIEW_ROLES=${this.budget.reviewRoles.join(",")}`);
+    }
+
     // Role-specific dispatch instructions (interview enforcement)
     if ((role === "architect" || role === "pm" || role === "designer" || role === "ux-designer") && !revisionContext) {
       taskHeaderLines.push("");
@@ -1096,6 +1103,7 @@ export class Orchestrator {
         rolesDir: V3_ROLES_DIR,
         implBase: IMPL_BASE,
         planDir,
+        budget: this.budget,
       });
 
       // Launch implementation agents
@@ -1105,7 +1113,7 @@ export class Orchestrator {
         queries.updateFeaturePhase(featureId, "impl");
       });
 
-      queries.insertEvent(featureId, "phase-transition", "bridge", "Implementation launched");
+      queries.insertEvent(featureId, "phase-transition", "bridge", `Implementation launched (budget: ${this.budget.label})`);
     } catch (err) {
       console.error("[orchestrator] Implementation launch error:", err.message);
       const stderr = err.stderr ? err.stderr.toString().slice(-500) : err.message;
@@ -1177,6 +1185,7 @@ export class Orchestrator {
           rolesDir: V3_ROLES_DIR,
           implBase: IMPL_BASE,
           planDir,
+          budget: this.budget,
         });
       } catch (launchErr) {
         console.error("[orchestrator] launchImpl failed:", launchErr.message);
@@ -1349,6 +1358,7 @@ export class Orchestrator {
     const feature = queries.getFeatureById(featureId);
     if (!feature) return;
 
+    const budget = this.budget;
     const tree = this.discoverSignalTree(feature.slug);
     const numTeams = Object.keys(tree.teams).length || feature.num_teams;
     const worktreeDir = path.join(PROJECT_ROOT, ".features", feature.slug);
@@ -1368,10 +1378,11 @@ export class Orchestrator {
           roleName: "feature-lead",
           signalDir: tree.featureLead,
           cwd: featureCwd,
-          maxRetries: MAX_FL_RETRIES,
+          model: getModel(budget, "feature-lead"),
+          maxRetries: budget.retries.featureLead,
         });
       } else {
-        this._syncAgentRetries(flAgent, MAX_FL_RETRIES);
+        this._syncAgentRetries(flAgent, budget.retries.featureLead);
       }
 
       // Use "refresh" mode if FEATURE-STATUS.md exists (recovery/restart scenario)
@@ -1395,10 +1406,11 @@ export class Orchestrator {
           roleName: "operator",
           signalDir: tree.operator,
           cwd: featureCwd,
-          maxRetries: MAX_OPERATOR_RETRIES,
+          model: getModel(budget, "operator"),
+          maxRetries: budget.retries.operator,
         });
       } else {
-        this._syncAgentRetries(opAgent, MAX_OPERATOR_RETRIES);
+        this._syncAgentRetries(opAgent, budget.retries.operator);
       }
       // Operator is reactive — spawned by routeUserMessage
       queries.updateAgentStatus(opAgent.id, "idle");
@@ -1421,10 +1433,11 @@ export class Orchestrator {
             teamNum,
             signalDir: team.orchestrator,
             cwd: teamCwd,
-            maxRetries: MAX_ORCH_RETRIES,
+            model: getModel(budget, "team-orchestrator"),
+            maxRetries: budget.retries.orchestrator,
           });
         } else {
-          this._syncAgentRetries(orchAgent, MAX_ORCH_RETRIES);
+          this._syncAgentRetries(orchAgent, budget.retries.orchestrator);
         }
         // Orchestrator waits for .task — no auto-start
       }
@@ -1442,10 +1455,11 @@ export class Orchestrator {
             teamNum,
             signalDir: roleDir,
             cwd: teamCwd,
-            maxRetries: MAX_ROLE_RETRIES,
+            model: getModel(budget, "role-agent"),
+            maxRetries: budget.retries.role,
           });
         } else {
-          this._syncAgentRetries(roleAgent, MAX_ROLE_RETRIES);
+          this._syncAgentRetries(roleAgent, budget.retries.role);
         }
         // Role waits for .task — no auto-start
       }
@@ -1463,10 +1477,11 @@ export class Orchestrator {
           roleName: role,
           signalDir: reviewDir,
           cwd: featureCwd,
-          maxRetries: MAX_ROLE_RETRIES,
+          model: getModel(budget, "review-agent"),
+          maxRetries: budget.retries.role,
         });
       } else {
-        this._syncAgentRetries(reviewAgent, MAX_ROLE_RETRIES);
+        this._syncAgentRetries(reviewAgent, budget.retries.role);
       }
     }
 

package/v3/prompt-builder.js

@@ -667,37 +667,42 @@ adversarial cross-check happens LAST (after all review agents have completed):
 1. **Read team evidence** — Read \`.gate-evidence.yaml\` from each team's orchestrator signal dir.
    If any team lacks \`.gate-evidence.yaml\`, REJECT the gate immediately.
 2. **Push team branches** and create PRs (team branch → integration branch) per repo using gh CLI
-3. **Dispatch feature-level review agents** by writing .task files:
+3. **Determine which review agents to dispatch** for this gate:
+   a. Read the current phase's \`phase.yaml\` and look for the \`review_roles\` field.
+   b. If \`review_roles\` is present, dispatch ONLY the listed roles.
+   c. If \`review_roles\` is absent, discover available review roles by listing the directories under \`${featureReviewDir}/\`:
+      \`\`\`bash
+      ls ${featureReviewDir}/
+      \`\`\`
+      Dispatch all discovered review roles.
+   d. Only dispatch to roles that have a directory — skip any that don't exist.
+4. **Dispatch review agents** by writing .task files to each role:
    \`\`\`bash
    PREVIEW_ENV=""
    if [ -f "${featureLeadDir}/preview-env.json" ]; then
      PREVIEW_ENV="Preview environment: ${featureLeadDir}/preview-env.json"
    fi
-   cat > ${featureReviewDir}/integration-tester/.task << TASK_EOF
-   <your review task here>
+   # For each review role from step 3:
+   cat > ${featureReviewDir}/<role-name>/.task << TASK_EOF
+   <your review task here — include gate context, PRs, journeys to verify>
    \$PREVIEW_ENV
    TASK_EOF
-   cat > ${featureReviewDir}/code-reviewer/.task << 'TASK_EOF'
-   <your review task here>
-   TASK_EOF
-   cat > ${featureReviewDir}/security-auditor/.task << 'TASK_EOF'
-   <your review task here>
-   TASK_EOF
    \`\`\`
-4. **Wait for all review agents** to complete (.done files) — poll every 75s:
+5. **Wait for all dispatched review agents** to complete (.done files) — poll every 75s:
    \`\`\`bash
-   while [ ! -f ${featureReviewDir}/integration-tester/.done ] || \\
-         [ ! -f ${featureReviewDir}/code-reviewer/.done ] || \\
-         [ ! -f ${featureReviewDir}/security-auditor/.done ]; do
-     sleep 75
+   # Check .done for each role you dispatched in step 4
+   ALL_DONE=true
+   for role in <list of dispatched roles>; do
+     [ ! -f "${featureReviewDir}/$role/.done" ] && ALL_DONE=false
    done
+   # Repeat until ALL_DONE is true
    \`\`\`
-5. **Adversarial cross-check** (FINAL step before user sees it):
+6. **Adversarial cross-check** (FINAL step before user sees it):
    - Cross-check evidence across ALL teams for inconsistencies
    - Call \`get_screenshots\` for critical journeys and independently verify orchestrator claims
    - Review feature-level review agent outputs
    - If discrepancies found → REJECT gate, do NOT escalate to user
-6. **Merge evidence** — Combine all team YAMLs + feature-level review outputs into:
+7. **Merge evidence** — Combine all team YAMLs + feature-level review outputs into:
    \`\`\`bash
    cat > ${featureLeadDir}/.gate-evidence.yaml << 'EVIDENCE_EOF'
    <merged evidence YAML>
@@ -706,14 +711,14 @@ adversarial cross-check happens LAST (after all review agents have completed):
    Include: \`coverage_matrix\`, \`deviations\`, \`self_reported_risks\` (aggregated from all teams)
    Include: \`reviewer_comments\` with your FL assessment
    Include: \`cross_team_surface\` (APIs, contracts, shared state)
-7. **Compile feature gate HTML** — Call \`compile_gate_evidence\` MCP tool:
+8. **Compile feature gate HTML** — Call \`compile_gate_evidence\` MCP tool:
    - \`evidence_yaml_path\`: ${featureLeadDir}/.gate-evidence.yaml
    - \`output_html_path\`: ${featureLeadDir}/.gate-evidence.html
    - \`doc_type\`: \`"feature"\`
    - \`team_html_paths\`: list of \`{ team_num, html_path }\` for each team's gate HTML
-   - If tool returns ERROR → re-dispatch affected verification role → retry from step 4
+   - If tool returns ERROR → re-dispatch affected verification role → retry from step 5
    - Do NOT proceed until \`compile_gate_evidence\` succeeds
-8. **Post feature gate HTML** to .agent-response — the HTML IS the message:
+9. **Post feature gate HTML** to .agent-response — the HTML IS the message:
    - \`[evidence:${featureLeadDir}/.gate-evidence.html]\` marker
    - \`[DECISION]\` block with approve/reject buttons
    - No text summary needed — the HTML contains everything

package/v3/roles/architect/CLAUDE.md

@@ -272,6 +272,7 @@ Conforms to `phase.schema.md`. Contains:
 - Phase identity (id, title, objective, risk)
 - Task DAG — ordered list of tasks with dependency references
 - Role assignments — which role executes which tasks
+- Review roles — which feature-level review agents run at this phase's gate
 - Phase-level acceptance criteria (user_criteria with action/observe pairs)
 - Phase-scoped journey references
 - Regression test references
@@ -311,6 +312,15 @@ role_assignments:
   verifier: ["1.v"]
   test-author: ["1.t"]
 
+# Which feature-level review agents run at this phase's gate.
+# ONLY use roles from $AVAILABLE_REVIEW_ROLES (set in your task header).
+# Choose based on what changed: security-auditor for auth/data changes,
+# integration-tester for API/UI flows, code-reviewer for structural quality, etc.
+# If omitted, all available review roles are dispatched (wasteful — always specify).
+review_roles:
+  - code-reviewer
+  - integration-tester
+
 acceptance:
   user_criteria:
     - action: "POST /api/bot-collaborator/invite with body {repo_owner, repo_name}"

package/v3/roles/feature-lead/CLAUDE.md

@@ -57,8 +57,8 @@ You post to the feature's channel via the bridge. Rules:
 
 1. **Read team evidence** — Read `.gate-evidence.yaml` from each team's orchestrator signal dir
 2. **Validate evidence exists** — If any team lacks `.gate-evidence.yaml`, REJECT the gate immediately (write feedback to team orchestrator, do not escalate to user)
-3. **Dispatch feature-level review agents** (integration-tester, code-reviewer, security-auditor) — these run against the merged codebase and produce their own `.output` files
-4. **Wait for review agents to complete** — read their `.output` files
+3. **Dispatch feature-level review agents** — read the current phase's `phase.yaml` for a `review_roles` field. If present, dispatch ONLY those roles. If absent, dispatch all review roles that have directories under `feature-review/`. These run against the merged codebase and produce their own `.output` files.
+4. **Wait for dispatched review agents to complete** — read their `.output` files
 4b. **Review gaps across all levels.** Read `gaps` from:
     - Each team orchestrator's `.gate-evidence.yaml` (team-level QA gaps)
     - Each team's compiled `.gate-evidence.html` (review visually)

package/v3/roles/plan-compiler/CLAUDE.md

@@ -58,6 +58,16 @@ You are a fresh-context validator. The Architect just produced a structured plan
 - [ ] No orphaned tasks (every task is reachable from the root of the DAG)
 - [ ] Parallelizable tasks have no false dependencies (tasks that could run in parallel shouldn't depend on each other unless truly necessary)
 
+### 2b. Review Roles Validation
+
+- [ ] Every `phase.yaml` has a `review_roles` list (warn if missing — FL will fall back to dispatching all available review roles, which is wasteful)
+- [ ] Every role in `review_roles` is from `$AVAILABLE_REVIEW_ROLES` (set in your task header) — reject any role not in that list
+- [ ] Review role selection makes sense for the phase:
+  - Phases touching auth, secrets, or data access should include `security-auditor`
+  - Phases with API or UI changes should include `integration-tester`
+  - `code-reviewer` and `verifier` are reasonable defaults for any phase
+  - `regression-tester` should be included when the phase modifies existing behavior
+
 ### 3. Codebase Cross-Check
 
 For every task's `scope.modify` and `scope.read` paths:
@@ -204,6 +214,21 @@ budget:
 
 If the user delegates, use sensible defaults and document them.
 
+### Step 6c: Team Count (`num_teams` in plan.yaml)
+
+Add a `num_teams` field to `plan.yaml` that reflects the **actual parallelism needed by the plan** — NOT just filling to a maximum. Consider:
+
+- How many independent domain boundaries exist (e.g., backend vs frontend vs infrastructure)
+- Whether phases can actually run in parallel or are sequential
+- A single-service feature with 2 phases probably needs 1 team, not 5
+
+The orchestrator will cap `num_teams` to the user's budget tier maximum, so err toward what the plan actually needs. If only 2 independent workstreams exist, set `num_teams: 2` even if the budget allows 5.
+
+```yaml
+# In plan.yaml:
+num_teams: 2  # Based on 2 independent workstreams: backend API + frontend UI
+```
+
 ### Step 7: Write Final Report
 
 Write your findings to `.output` with this structure: