iriai-build 0.2.8 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iriai-build",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "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
   // ═══════════════════════════════════════════════════════════════════════════
@@ -381,18 +469,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");
+      // Validate UX designer output before proceeding to UI designer
+      const planDir = path.join(feature.signal_dir, "plans");
+      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 {
+        // 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);
+      // 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 {
@@ -401,6 +514,127 @@ export class Orchestrator {
     }
   }
 
+  /**
+   * Artifact requirements per planning role.
+   * Each entry: { label, check(planDir) → boolean }
+   */
+  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; }
+      }},
+    ],
+  };
+
+  /**
+   * 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 */ }
+      }
+    }
+
+    const artifacts = Orchestrator.ROLE_ARTIFACTS[role];
+    if (!artifacts) return { pass: true, found: [], missing: [] };
+
+    const found = [];
+    const missing = [];
+    for (const art of artifacts) {
+      if (art.check(planDir)) {
+        found.push(art.label);
+      } else {
+        missing.push(art.label);
+      }
+    }
+
+    return { pass: missing.length === 0, found, missing };
+  }
+
+  /**
+   * 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`,
+      );
+    }
+
+    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 });
+  }
+
   /**
    * Post phase summary, upload artifact, then post Block Kit approve/reject buttons.
    * Everything is sequential to guarantee correct message ordering.
@@ -1839,6 +2073,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 +2335,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 +2534,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);
     }
   }