iriai-build 0.2.8 → 0.3.0

package/package.json

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

package/v3/adapters/slack-adapter.js

@@ -353,7 +353,7 @@ export class SlackAdapter extends InterfaceAdapter {
     const slug = slugify(featureDesc);
 
     if (this._orchestrator) {
-      await this._orchestrator.initializeFeature(slug, messageTs, userId);
+      await this._orchestrator.initializeFeature(slug, messageTs, userId, featureDesc);
     }
   }
 

package/v3/constants.js

@@ -143,6 +143,7 @@ export const SIGNAL = {
   NEEDS_REPOS: ".needs-repos",
   GATE_EVIDENCE: ".gate-evidence.yaml",
   OUTPUT_PARTIAL: ".output.partial",
+  SCOPING_COMPLETE: ".scoping-complete",
 };
 
 // ─── Known Repos ─────────────────────────────────────────────────────────────

package/v3/file-io.js

@@ -51,6 +51,8 @@ export class FileIO extends EventEmitter {
         this.emit("impl:userMessage", { slug, agent: "operator", filePath });
       } else if (fileName === ".needs-repos") {
         this.emit("impl:needsRepos", { slug, filePath });
+      } else if (fileName === ".scoping-complete") {
+        this.emit("planning:scopingComplete", { slug, filePath });
       }
       return;
     }

package/v3/orchestrator.js

@@ -14,6 +14,7 @@ import { invokeOperator, invokeOperatorRelay, parseOperatorResponse } from "./op
 import {
   buildPlanningRolePrompt, buildArtifactSummarizerPrompt, buildRolePrompt, buildOrchestratorPrompt,
   buildFeatureLeadInitPrompt, buildFeatureLeadRefreshPrompt, buildFeatureLeadTriggerPrompt,
+  buildScopingPrompt,
 } from "./prompt-builder.js";
 import { planningComplete } from "./planning-complete.js";
 import { launchImpl } from "./launch-impl.js";
@@ -70,9 +71,9 @@ export class Orchestrator {
 
   /**
    * Initialize a feature from [FEATURE] detection: create per-feature dirs,
-   * feature channel, operator record, and start planning pipeline.
+   * feature channel, operator record, and start scoping phase.
    */
-  async initializeFeature(slug, messageTs, userId) {
+  async initializeFeature(slug, messageTs, userId, featureDescription = "") {
     const featureDir = path.join(IMPL_BASE, "features", slug);
 
     // 1. Create directories
@@ -100,9 +101,14 @@ export class Orchestrator {
     try { fs.unlinkSync(opDest); } catch { /* ok */ }
     fs.symlinkSync(opSrc, opDest);
 
-    // 3. Create feature in SQLite
+    // 3. Create feature in SQLite — store the original description in metadata
     const feature = queries.createFeature({ slug, threadTs: messageTs, signalDir: featureDir });
     queries.insertEvent(feature.id, "system", `user:${userId}`, `Feature requested: ${slug}`);
+    if (featureDescription) {
+      const meta = queries.getFeatureMetadata(feature.id);
+      meta.feature_description = featureDescription;
+      queries.updateFeatureMetadata(feature.id, meta);
+    }
 
     // 4. Create feature channel immediately
     const channelId = await this.adapter.createFeatureChannel(feature.id, slug);
@@ -126,7 +132,7 @@ export class Orchestrator {
       await this.adapter.postThreadMessage(feature.id,
         `*[Pipeline]* Starting planning for *${slug}*. Implementation channel: <#${channelId}>`);
       await this.adapter.postMessage(feature.id,
-        `*[Pipeline]* Planning pipeline started for feature: *${slug}*\nPhase 1: Product Manager interview`);
+        `*[Pipeline]* Feature scoping started for: *${slug}*`);
 
       // Pin artifact portal URL in the feature channel
       const portalUrl = `http://localhost:${PORTAL_PORT}/features/${slug}`;
@@ -141,7 +147,7 @@ export class Orchestrator {
       }
     } else {
       await this.adapter.postThreadMessage(feature.id,
-        `*[Pipeline]* Starting planning pipeline for: *${slug}*\nPhase 1: Product Manager interview`);
+        `*[Pipeline]* Starting feature scoping for: *${slug}*`);
     }
 
     // 7. Cache signal tree with planning field
@@ -158,13 +164,95 @@ export class Orchestrator {
     // 8. Start watching per-feature planning + operator signals
     this.fileIO.watchFeaturePlanningSignals(slug, planningTree, operatorDir);
 
-    // 9. Set active planning role and dispatch PM
-    queries.updateFeaturePlanningRole(feature.id, "pm");
-    this.dispatchPlanningRole(feature.id, "pm");
+    // 9. Dispatch scoping phase — Operator converses with user to establish
+    // scope, blast radius, constraints before PM starts.
+    this._dispatchScoping(feature, operatorDir, featureDescription);
 
     return feature;
   }
 
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SCOPING PHASE (Operator ↔ User conversation before PM)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Dispatch the Operator for feature scoping. This is the Operator's FIRST
+   * invocation — it converses with the user to establish scope, blast radius,
+   * and constraints. The same Operator session persists via --continue for
+   * the rest of the feature lifecycle, preserving scoping context.
+   *
+   * When done, the Operator writes:
+   * - .task in PM signal dir (structured PRD request)
+   * - .needs-repos in operator dir (repos to pull in)
+   * - .scoping-complete (triggers PM dispatch)
+   */
+  _dispatchScoping(feature, operatorDir, featureDescription) {
+    const agent = queries.getAgentByKey(`op-${feature.slug}`);
+    if (!agent) {
+      console.error(`[orchestrator] No operator agent for ${feature.slug}`);
+      return;
+    }
+
+    const projectRoot = PROJECT_ROOT;
+    const directoryMapPath = path.join(projectRoot, "DIRECTORY_MAP.MD");
+    const hasDirectoryMap = fs.existsSync(directoryMapPath);
+    const pmSignalDir = path.join(feature.signal_dir, "planning", "pm");
+
+    const prompt = buildScopingPrompt({
+      featureName: feature.slug,
+      featureDescription,
+      operatorDir,
+      pmSignalDir,
+      planDir: path.join(feature.signal_dir, "plans"),
+      directoryMapPath: hasDirectoryMap ? directoryMapPath : null,
+      projectRoot,
+    });
+
+    queries.updateFeaturePlanningRole(feature.id, "scoping");
+    queries.insertEvent(feature.id, "system", "bridge", "Scoping phase started — Operator conversing with user");
+
+    // Fresh session — this becomes the Operator's long-lived session
+    // that all future --continue invocations build on.
+    this.supervisor.spawn(agent.id, prompt, { continue: false });
+    console.log(`[orchestrator] Dispatched Operator scoping for ${feature.slug}`);
+  }
+
+  /**
+   * Handle .scoping-complete signal from Operator — transition to PM dispatch.
+   * At this point: .task exists in PM signal dir, .needs-repos may have been written.
+   */
+  async _handleScopingComplete(slug) {
+    const feature = queries.getFeatureBySlug(slug);
+    if (!feature) return;
+
+    // Process any pending .needs-repos that may not have been picked up yet
+    const tree = this._signalTrees[feature.slug];
+    if (tree?.operator) {
+      const reposFile = path.join(tree.operator, SIGNAL.NEEDS_REPOS);
+      if (fs.existsSync(reposFile)) {
+        const content = readSignal(reposFile, { deleteAfter: true });
+        if (content) await this._handleNeedsRepos(feature, content);
+      }
+    }
+
+    // Verify the PM .task file was written
+    const pmSignalDir = path.join(feature.signal_dir, "planning", "pm");
+    const taskFile = path.join(pmSignalDir, SIGNAL.TASK);
+    if (!fs.existsSync(taskFile)) {
+      console.warn(`[orchestrator] Scoping complete for ${slug} but no .task file for PM — using feature description`);
+      const meta = queries.getFeatureMetadata(feature.id);
+      const desc = meta.feature_description || feature.slug;
+      writeSignal(taskFile, `Feature request: ${desc}`);
+    }
+
+    queries.insertEvent(feature.id, "phase-transition", "bridge", "Scoping complete — dispatching PM");
+    await this.adapter.postPipelineMessage(feature.id, "Scoping complete. Starting Product Manager interview.");
+
+    // Dispatch PM with the structured .task from scoping
+    queries.updateFeaturePlanningRole(feature.id, "pm");
+    this.dispatchPlanningRole(feature.id, "pm");
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════
   // PLANNING PIPELINE
   // ═══════════════════════════════════════════════════════════════════════════
@@ -390,6 +478,55 @@ export class Orchestrator {
       // 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.
+      const planDir = path.join(feature.signal_dir, "plans");
+      const validation = this._validateArchitectOutput(planDir);
+
+      if (validation.pass) {
+        await this._requestPhaseReview(feature, role, output);
+      } else {
+        // Redispatch architect with focused instructions
+        console.log(`[orchestrator] Architect output incomplete for ${slug}: missing ${validation.missing.join(", ")}`);
+        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 });
+      }
     } else {
       // Non-final role → summary + artifact upload + Block Kit review gate (all sequential)
       await this._requestPhaseReview(feature, role, output);
@@ -401,6 +538,72 @@ 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[] }
+   */
+  _validateArchitectOutput(planDir) {
+    const found = [];
+    const missing = [];
+
+    // 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 */ }
+    }
+
+    // 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)");
+    }
+
+    // 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)");
+    }
+
+    // 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");
+    }
+
+    // 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)");
+    }
+
+    return {
+      pass: missing.length === 0,
+      found,
+      missing,
+    };
+  }
+
   /**
    * Post phase summary, upload artifact, then post Block Kit approve/reject buttons.
    * Everything is sequential to guarantee correct message ordering.
@@ -1839,6 +2042,17 @@ export class Orchestrator {
       }
     });
 
+    // Scoping complete — Operator finished scoping conversation, dispatch PM
+    this.fileIO.on("planning:scopingComplete", async ({ slug, filePath }) => {
+      try {
+        // Clean up the signal file
+        try { fs.unlinkSync(filePath); } catch { /* ok */ }
+        await this._handleScopingComplete(slug);
+      } catch (err) {
+        console.error("[orchestrator] Scoping complete error:", err.message);
+      }
+    });
+
     // Implementation signals — FL .agent-response routed through Operator relay
     this.fileIO.on("impl:response", async ({ slug, agent, filePath }) => {
       try {
@@ -2090,6 +2304,9 @@ export class Orchestrator {
       if (agentName !== "operator") return;
       const feature = queries.getFeatureBySlug(slug);
       if (!feature) return;
+      // During scoping phase, the long-running scoping Operator polls for
+      // .user-message directly — don't consume it with ephemeral Operator.
+      if (feature.active_planning_role === "scoping") return;
       this._handleOperatorMessage(feature);
     });
 
@@ -2286,6 +2503,23 @@ export class Orchestrator {
 
     console.log(`[orchestrator] Operator exited with code ${exitCode} after ${elapsed}ms — scheduling retry`);
 
+    // If still in scoping phase, re-dispatch scoping (not ephemeral Operator)
+    if (feature.active_planning_role === "scoping") {
+      const retried = this.supervisor.scheduleRetry(agentId, async () => {
+        console.log(`[orchestrator] Operator scoping retry for ${feature.slug}`);
+        const freshFeature = queries.getFeatureById(feature.id) || feature;
+        const meta = queries.getFeatureMetadata(freshFeature.id);
+        this._dispatchScoping(freshFeature, tree.operator, meta.feature_description || "");
+        return null;
+      });
+      if (!retried) {
+        console.error(`[orchestrator] Operator scoping for ${feature.slug} exhausted retries`);
+        // Fallback: skip scoping and dispatch PM directly
+        this._handleScopingComplete(feature.slug);
+      }
+      return;
+    }
+
     // Capture stashed context for the retry closure
     const stashedCtx = this._lastOperatorContext?.[feature.slug];
 

package/v3/plan-compiler.js

@@ -27,8 +27,8 @@ export function compilePlanReviewHtml(planDir) {
     tabs.push({ id: "design", label: "Design Decisions", content: designContent });
   }
 
-  // Architecture (context.md)
-  const contextContent = readArtifact(planDir, "context");
+  // Architecture (context.md or architecture.md — agents may use either name)
+  const contextContent = readArtifact(planDir, "context") || readArtifact(planDir, "architecture");
   if (contextContent) {
     tabs.push({ id: "architecture", label: "Architecture", content: contextContent });
   }

package/v3/prompt-builder.js

@@ -3,6 +3,170 @@
 
 import { IRIAI_TEAM_DIR, IMPL_BASE, V3_ROLES_DIR } from "./constants.js";
 
+// ─── Scoping Phase (Operator as long-running scoping agent) ──────────────────
+
+/**
+ * Build prompt for the scoping phase — Operator converses with user to
+ * establish scope, blast radius, and constraints before PM starts.
+ */
+export function buildScopingPrompt({ featureName, featureDescription, operatorDir, pmSignalDir, planDir, directoryMapPath, projectRoot }) {
+  const directoryMapSection = directoryMapPath
+    ? `## Directory Map (Codebase Topology)
+Read the directory map for high-level understanding of the project:
+DIRECTORY_MAP=${directoryMapPath}
+
+Use this to identify which repos/services are affected by this feature.
+Do NOT read source code files — only use the directory map for repo identification.`
+    : `## No Directory Map Available
+There is no DIRECTORY_MAP.MD in this project. Use the feature description
+and your conversation with the user to understand the scope. You may explore
+the top-level directory structure (ls, not reading source files) to identify repos.`;
+
+  return `You are the Operator for feature '${featureName}'.
+
+Read your CLAUDE.md for your full role definition. This is your FIRST invocation —
+your session will persist via --continue for the entire feature lifecycle.
+
+## CURRENT TASK: Feature Scoping
+
+Before any planning agents start, you must scope this feature with the user.
+Your job is boundary-setting — narrowing the sandbox that downstream agents work within.
+
+You are NOT:
+- Writing requirements (that's the PM's job)
+- Making design decisions (that's the Designer's job)
+- Investigating source code (that's the Architect's job)
+
+You ARE:
+- Establishing what repos/services are in scope
+- Identifying blast radius (what else might be affected)
+- Capturing non-functional requirements and constraints
+- Recording any upfront decisions the user already has opinions on
+- Identifying if new repos need to be created
+
+## Signal Directories
+OPERATOR_DIR=${operatorDir}
+PM_SIGNAL_DIR=${pmSignalDir}
+PLAN_DIR=${planDir}
+PROJECT_ROOT=${projectRoot}
+
+${directoryMapSection}
+
+## Feature Description (from user)
+${featureDescription || featureName}
+
+## Communication Protocol
+1. To send a message to the user: write to .agent-response
+   cat > ${operatorDir}/.agent-response << 'MSG_EOF'
+   your message here
+   MSG_EOF
+   The bridge posts it to the user and deletes the file.
+
+2. To receive a reply: poll for .user-message
+   while [ ! -f ${operatorDir}/.user-message ]; do sleep 5; done
+   MSG=$(cat ${operatorDir}/.user-message) && rm -f ${operatorDir}/.user-message
+
+3. After each .agent-response write, wait 2 seconds before polling.
+
+Format for mobile: under 300 words per message, numbered options, bold key questions.
+
+## Conversation Flow
+
+1. **Read the directory map** (if available) to understand the project topology.
+
+2. **Greet the user and confirm the feature request.** Restate your understanding
+   of what they want in 2-3 sentences. Ask if that's correct.
+
+3. **Ask scoping questions one at a time.** Focus on:
+   - What repos/services are affected? (Use directory map to suggest candidates)
+   - Is this extending existing functionality or building something new?
+   - If new: what's the new repo/app name and where does it live?
+   - What are the constraints? (Performance, security, accessibility, compatibility)
+   - Are there any hard non-negotiable requirements?
+   - What is explicitly OUT of scope?
+
+4. **Keep it brief.** 3-5 questions max. Don't duplicate PM/Designer/Architect work.
+   If the user gives you enough context in the first message, you can skip to the summary.
+
+5. **Summarize and confirm.** Present a scoping summary for user approval:
+   - Scope (what's being built)
+   - Affected repos/services
+   - New repos to create (if any)
+   - Constraints/NFRs
+   - Out of scope
+
+## When Scoping Is Complete
+
+After the user confirms your summary, do THREE things in order:
+
+### 1. Write the structured PRD request for the PM
+Write a .task file in the PM's signal directory. This is the PM's starting brief.
+
+cat > ${pmSignalDir}/.task << 'TASK_EOF'
+FEATURE: ${featureName}
+
+## User's Request
+<restate the feature request clearly>
+
+## Scope
+<what is in scope — be specific>
+
+## Affected Repos/Services
+<list repos identified from directory map + conversation>
+
+## New Repos
+<any new repos to create, or "none">
+
+## Constraints & Non-Functional Requirements
+<performance, security, accessibility, compatibility requirements>
+
+## Out of Scope
+<what is explicitly excluded>
+
+## User Decisions
+<any decisions the user made during scoping>
+TASK_EOF
+
+### 2. Write .needs-repos
+Identify the repos from the directory map that need worktrees.
+Write their paths (relative to PROJECT_ROOT) to .needs-repos.
+${directoryMapPath ? `Read DIRECTORY_MAP for the exact paths.` : `List the repo paths based on your conversation with the user.`}
+
+For existing repos:
+cat > ${operatorDir}/.needs-repos << 'REPOS_EOF'
+path/to/repo1
+path/to/repo2
+REPOS_EOF
+
+For NEW repos that don't exist yet, use the + prefix:
++<local-path>:<github-name>[:<template>]
+
+Available templates: fastapi-postgres, react-parcel
+If no template fits, omit it (bare scaffold with README + .gitignore).
+
+### 3. Signal scoping complete
+echo "DONE" > ${operatorDir}/.scoping-complete
+
+This tells the bridge to dispatch the PM with your .task file.
+After this signal, you will continue operating as the Operator for this feature
+(relaying messages, routing decisions, pulling in additional repos as needed).
+
+## Important
+- Do NOT write .scoping-complete until AFTER .task and .needs-repos are written
+- Do NOT read source code — only the directory map for high-level repo identification
+- Keep the conversation focused — you're setting boundaries, not doing analysis
+- If the user wants to skip scoping (e.g., "just build it"), write a minimal .task
+  from the feature description and proceed
+
+## Context Preservation
+This scoping conversation is critical context for your entire lifecycle as Operator.
+The repos you identified, the user's constraints, and their decisions must be preserved.
+If you ever need to write a .handover file for context refresh, ALWAYS include the full
+scoping summary (repos, scope, constraints, user decisions) verbatim — do NOT summarize
+or truncate it.
+`;
+}
+
 // ─── Operator (Ephemeral) ────────────────────────────────────────────────────
 
 /**

package/v3/slack-adapter.js

@@ -249,7 +249,7 @@ export class SlackAdapter {
     const slug = slugify(featureDesc);
 
     if (this._orchestrator) {
-      await this._orchestrator.initializeFeature(slug, messageTs, userId);
+      await this._orchestrator.initializeFeature(slug, messageTs, userId, featureDesc);
     }
   }