iriai-build 0.3.0 → 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.0",
+  "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("");
@@ -469,67 +476,43 @@ export class Orchestrator {
         this._notifyOperatorOfDecision(feature, planDecision);
       }
     } else if (role === "ux-designer") {
-      // Compound design step: ux-designer done → dispatch ui-designer (no phase-review yet)
-      await this.adapter.postPipelineMessage(feature.id,
-        `UX Designer complete. Starting UI Designer...`);
-      queries.updateFeaturePlanningRole(feature.id, "ui-designer");
-      this.dispatchPlanningRole(feature.id, "ui-designer");
-    } else if (role === "ui-designer") {
-      // Compound design step: ui-designer done → surface as "designer" phase-review
-      // Both sub-roles are complete; present combined output for user approval
-      await this._requestPhaseReview(feature, "designer", output);
-    } else if (role === "architect") {
-      // Architect validation: ensure structured plan directory before review gate.
-      // The architect often drifts to writing a monolithic architecture doc
-      // instead of the structured plan directory (plan.yaml + phases/ + task files).
-      // Validate required artifacts and redispatch if incomplete.
+      // Validate UX designer output before proceeding to UI designer
       const planDir = path.join(feature.signal_dir, "plans");
-      const validation = this._validateArchitectOutput(planDir);
-
-      if (validation.pass) {
-        await this._requestPhaseReview(feature, role, output);
+      const validation = this._validatePlanningOutput(role, planDir);
+      if (!validation.pass) {
+        await this.adapter.postPipelineMessage(feature.id,
+          `UX Designer output incomplete (missing: ${validation.missing.join(", ")}). Redispatching...`);
+        this._redispatchForMissingArtifacts(feature, role, validation);
       } else {
-        // Redispatch architect with focused instructions
-        console.log(`[orchestrator] Architect output incomplete for ${slug}: missing ${validation.missing.join(", ")}`);
+        // Compound design step: ux-designer done → dispatch ui-designer (no phase-review yet)
         await this.adapter.postPipelineMessage(feature.id,
-          `Architect investigation complete — redispatching for structured plan output (missing: ${validation.missing.join(", ")})`);
-
-        const signalDir = path.join(feature.signal_dir, "planning", "architect");
-        ensureDir(signalDir);
-
-        // Write focused redispatch instructions as .user-message so the agent picks it up
-        const redispatchMsg = [
-          `STRUCTURED PLAN OUTPUT REQUIRED`,
-          ``,
-          `Your investigation phase is complete. You wrote a thorough context.md in $PLAN_DIR/.`,
-          `Now you MUST produce the structured plan directory. Read your CLAUDE.md "Output Format" section carefully.`,
-          ``,
-          `WHAT EXISTS (do NOT redo):`,
-          validation.found.map(f => `  ✓ ${f}`).join("\n"),
-          ``,
-          `WHAT IS MISSING (you must create these):`,
-          validation.missing.map(f => `  ✗ ${f}`).join("\n"),
-          ``,
-          `INSTRUCTIONS:`,
-          `1. Read $PLAN_DIR/context.md for your investigation notes — do NOT re-explore the entire codebase`,
-          `2. Do targeted source code reads ONLY where you need specific file paths, function signatures, or line numbers for task files`,
-          `3. Produce plan.yaml with phase DAG, role assignments, and journey refs`,
-          `4. Create phases/ directory with structured task files (YAML frontmatter + detailed instructions)`,
-          `5. Create journeys/ directory with test journeys (happy-path, failure, regression)`,
-          `6. Every task file must cite real file paths and code evidence from the codebase`,
-          `7. Signal .done + .output when complete`,
-          ``,
-          `Your context.md is the foundation. Build the structured plan ON TOP of it.`,
-        ].join("\n");
-
-        writeSignal(path.join(signalDir, SIGNAL.USER_MESSAGE), redispatchMsg);
-        queries.updateFeaturePlanningRole(feature.id, "architect");
-        // Fresh context — investigation session is done, architect needs full budget for structured output
-        this.dispatchPlanningRole(feature.id, "architect", { continue: false });
+          `UX Designer complete. Starting UI Designer...`);
+        queries.updateFeaturePlanningRole(feature.id, "ui-designer");
+        this.dispatchPlanningRole(feature.id, "ui-designer");
+      }
+    } else if (role === "ui-designer") {
+      // Validate UI designer output before surfacing combined design review
+      const planDir = path.join(feature.signal_dir, "plans");
+      const validation = this._validatePlanningOutput(role, planDir);
+      if (!validation.pass) {
+        await this.adapter.postPipelineMessage(feature.id,
+          `UI Designer output incomplete (missing: ${validation.missing.join(", ")}). Redispatching...`);
+        this._redispatchForMissingArtifacts(feature, role, validation);
+      } else {
+        // Both sub-roles complete; present combined output for user approval
+        await this._requestPhaseReview(feature, "designer", output);
       }
     } else {
-      // Non-final role → summary + artifact upload + Block Kit review gate (all sequential)
-      await this._requestPhaseReview(feature, role, output);
+      // All other roles (pm, architect, designer): validate then review gate
+      const planDir = path.join(feature.signal_dir, "plans");
+      const validation = this._validatePlanningOutput(role, planDir);
+      if (!validation.pass) {
+        await this.adapter.postPipelineMessage(feature.id,
+          `${PLANNING_ROLE_LABELS[role] || role} output incomplete (missing: ${validation.missing.join(", ")}). Redispatching...`);
+        this._redispatchForMissingArtifacts(feature, role, validation);
+      } else {
+        await this._requestPhaseReview(feature, role, output);
+      }
     }
 
     } finally {
@@ -539,69 +522,124 @@ export class Orchestrator {
   }
 
   /**
-   * Validate that the architect produced the required structured plan directory.
-   * Auto-normalizes architecture.md → context.md if needed.
-   * Returns { pass: boolean, found: string[], missing: string[] }
+   * Artifact requirements per planning role.
+   * Each entry: { label, check(planDir) → boolean }
    */
-  _validateArchitectOutput(planDir) {
-    const found = [];
-    const missing = [];
+  static ROLE_ARTIFACTS = {
+    pm: [
+      { label: "PRD document (*-prd.md)", check: (d) => !!findArtifact("prd", d) },
+    ],
+    "ux-designer": [
+      { label: "design-decisions.md", check: (d) => !!findArtifact("design-decisions", d) },
+    ],
+    "ui-designer": [
+      { label: "design-decisions.md (with Visual Design Language)", check: (d) => {
+        const content = findArtifact("design-decisions", d);
+        if (!content) return false;
+        try {
+          const text = fs.readFileSync(content, "utf-8");
+          return text.includes("Visual Design Language") || text.includes("Color Palette");
+        } catch { return false; }
+      }},
+      { label: "mockup.html", check: (d) => fs.existsSync(path.join(d, "mockup.html")) },
+    ],
+    designer: [
+      { label: "design-decisions.md", check: (d) => !!findArtifact("design-decisions", d) },
+      { label: "mockup.html", check: (d) => fs.existsSync(path.join(d, "mockup.html")) },
+    ],
+    architect: [
+      { label: "context.md (investigation notes)", check: (d) => !!findArtifact("context", d) || !!findArtifact("architecture", d) },
+      { label: "plan.yaml (phase DAG)", check: (d) => fs.existsSync(path.join(d, "plan.yaml")) },
+      { label: "phases/ (task files)", check: (d) => {
+        try {
+          return fs.readdirSync(path.join(d, "phases"), { withFileTypes: true }).some(e => e.isDirectory());
+        } catch { return false; }
+      }},
+      { label: "journeys/ (test journeys)", check: (d) => {
+        try {
+          return fs.readdirSync(path.join(d, "journeys")).some(e => e.endsWith(".md"));
+        } catch { return false; }
+      }},
+    ],
+  };
 
-    // Normalize: rename architecture.md → context.md if architect used wrong name
-    const archFile = path.join(planDir, "architecture.md");
-    const contextFile = path.join(planDir, "context.md");
-    if (fs.existsSync(archFile) && !fs.existsSync(contextFile)) {
-      try {
-        fs.renameSync(archFile, contextFile);
-        console.log(`[orchestrator] Renamed architecture.md → context.md in ${planDir}`);
-      } catch { /* ok, proceed with whatever exists */ }
+  /**
+   * Validate that a planning role produced its required artifacts.
+   * Runs auto-normalization (e.g. architecture.md → context.md) before checking.
+   * Returns { pass, found, missing }
+   */
+  _validatePlanningOutput(role, planDir) {
+    // Auto-normalize known filename drift
+    if (role === "architect") {
+      const archFile = path.join(planDir, "architecture.md");
+      const contextFile = path.join(planDir, "context.md");
+      if (fs.existsSync(archFile) && !fs.existsSync(contextFile)) {
+        try {
+          fs.renameSync(archFile, contextFile);
+          console.log(`[orchestrator] Renamed architecture.md → context.md in ${planDir}`);
+        } catch { /* ok */ }
+      }
     }
 
-    // Check context.md (investigation notes)
-    if (findArtifact("context", planDir) || findArtifact("architecture", planDir)) {
-      found.push("context.md (investigation notes)");
-    } else {
-      missing.push("context.md (investigation notes)");
-    }
+    const artifacts = Orchestrator.ROLE_ARTIFACTS[role];
+    if (!artifacts) return { pass: true, found: [], missing: [] };
 
-    // Check plan.yaml (phase DAG metadata)
-    if (fs.existsSync(path.join(planDir, "plan.yaml"))) {
-      found.push("plan.yaml (phase DAG)");
-    } else {
-      missing.push("plan.yaml (phase DAG + metadata)");
+    const found = [];
+    const missing = [];
+    for (const art of artifacts) {
+      if (art.check(planDir)) {
+        found.push(art.label);
+      } else {
+        missing.push(art.label);
+      }
     }
 
-    // Check phases/ directory with at least one phase subdirectory
-    const phasesDir = path.join(planDir, "phases");
-    let hasPhases = false;
-    try {
-      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-      hasPhases = entries.some(e => e.isDirectory());
-    } catch { /* doesn't exist */ }
-    if (hasPhases) {
-      found.push("phases/ (task files)");
-    } else {
-      missing.push("phases/ directory with task files");
-    }
+    return { pass: missing.length === 0, found, missing };
+  }
 
-    // Check journeys/ directory
-    const journeysDir = path.join(planDir, "journeys");
-    let hasJourneys = false;
-    try {
-      const entries = fs.readdirSync(journeysDir);
-      hasJourneys = entries.some(e => e.endsWith(".md"));
-    } catch { /* doesn't exist */ }
-    if (hasJourneys) {
-      found.push("journeys/ (test journeys)");
-    } else {
-      missing.push("journeys/ (test journeys)");
+  /**
+   * Redispatch a planning role that produced incomplete output.
+   * Writes focused instructions to .user-message and re-spawns with fresh context.
+   */
+  _redispatchForMissingArtifacts(feature, role, validation) {
+    const slug = feature.slug;
+    console.log(`[orchestrator] ${role} output incomplete for ${slug}: missing ${validation.missing.join(", ")}`);
+
+    const signalDir = path.join(feature.signal_dir, "planning", role);
+    ensureDir(signalDir);
+
+    const roleName = PLANNING_ROLE_LABELS[role] || role;
+    const lines = [
+      `INCOMPLETE OUTPUT — REDISPATCH`,
+      ``,
+      `You signaled .done but required artifacts are missing.`,
+      `Read your CLAUDE.md output format section and produce the missing items.`,
+      ``,
+      `WHAT EXISTS (do NOT redo):`,
+      ...validation.found.map(f => `  ✓ ${f}`),
+      ``,
+      `WHAT IS MISSING (you MUST create these):`,
+      ...validation.missing.map(f => `  ✗ ${f}`),
+      ``,
+      `Write the missing artifacts to $PLAN_DIR/, then signal .done + .output again.`,
+    ];
+
+    // Role-specific guidance
+    if (role === "architect") {
+      lines.push(
+        ``,
+        `ARCHITECT-SPECIFIC:`,
+        `1. Read $PLAN_DIR/context.md for your investigation notes — do NOT re-explore the entire codebase`,
+        `2. Do targeted source code reads ONLY where needed for specific file paths or function signatures`,
+        `3. Every task file must cite real file paths and code evidence from the codebase`,
+      );
     }
 
-    return {
-      pass: missing.length === 0,
-      found,
-      missing,
-    };
+    writeSignal(path.join(signalDir, SIGNAL.USER_MESSAGE), lines.join("\n"));
+    queries.updateFeaturePlanningRole(feature.id, role);
+
+    // Fresh context for the structured output pass
+    this.dispatchPlanningRole(feature.id, role, { continue: false });
   }
 
   /**
@@ -1065,6 +1103,7 @@ export class Orchestrator {
         rolesDir: V3_ROLES_DIR,
         implBase: IMPL_BASE,
         planDir,
+        budget: this.budget,
       });
 
       // Launch implementation agents
@@ -1074,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;
@@ -1146,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);
@@ -1318,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);
@@ -1337,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)
@@ -1364,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");
@@ -1390,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
       }
@@ -1411,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
       }
@@ -1432,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: