@bastani/atomic 0.8.17-0 → 0.8.18-0

package/dist/builtin/workflows/builtin/deep-research-codebase.ts

@@ -9,10 +9,11 @@
  */
 
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, extname, join } from "node:path";
+import { dirname, extname, isAbsolute, join, relative } from "node:path";
 import { defineWorkflow } from "../src/index.js";
 import type {
   WorkflowOutputMode,
+  WorkflowRunContext,
   WorkflowTaskResult,
   WorkflowTaskStep,
 } from "../src/shared/types.js";
@@ -73,12 +74,13 @@ function positiveInteger(value: number | undefined, fallback: number): number {
     : fallback;
 }
 
-function countCodebaseLines(): number {
+function countCodebaseLines(cwd = process.cwd()): number {
   try {
     const gitFiles = Bun.spawnSync({
       cmd: ["git", "ls-files", "--cached", "--others", "--exclude-standard"],
       stdout: "pipe",
       stderr: "pipe",
+      cwd,
     });
     const files =
       gitFiles.success && gitFiles.stdout
@@ -98,6 +100,7 @@ function countCodebaseLines(): number {
         cmd: ["wc", "-l", "--", ...batch],
         stdout: "pipe",
         stderr: "pipe",
+        cwd,
       });
       if (!wc.stdout) continue;
 
@@ -150,7 +153,10 @@ function slugifyResearchTopic(prompt: string): string {
 
 function defaultResearchDocPath(prompt: string, now = new Date()): string {
   const date = now.toISOString().slice(0, 10);
-  return join(DEFAULT_RESEARCH_DOC_DIR, `${date}-${slugifyResearchTopic(prompt)}.md`);
+  return join(
+    DEFAULT_RESEARCH_DOC_DIR,
+    `${date}-${slugifyResearchTopic(prompt)}.md`,
+  );
 }
 
 function sanitizeRunId(value: string): string {
@@ -172,7 +178,10 @@ function suffixedPath(path: string, suffix: number): string {
 }
 
 function isFileExistsError(error: unknown): boolean {
-  return error instanceof Error && (error as { readonly code?: string }).code === "EEXIST";
+  return (
+    error instanceof Error &&
+    (error as { readonly code?: string }).code === "EEXIST"
+  );
 }
 
 interface DeepResearchArtifactRoot {
@@ -180,13 +189,17 @@ interface DeepResearchArtifactRoot {
   readonly artifactRoot: string;
 }
 
-async function createArtifactRoot(startedAt: Date): Promise<DeepResearchArtifactRoot> {
-  await mkdir(DEFAULT_RESEARCH_DOC_DIR, { recursive: true });
+async function createArtifactRoot(
+  startedAt: Date,
+  cwd = process.cwd(),
+): Promise<DeepResearchArtifactRoot> {
+  const researchDocDir = join(cwd, DEFAULT_RESEARCH_DOC_DIR);
+  await mkdir(researchDocDir, { recursive: true });
   const baseRunId = timestampRunId(startedAt);
   for (let suffix = 0; ; suffix += 1) {
     const runId = suffix === 0 ? baseRunId : `${baseRunId}-${suffix + 1}`;
     const artifactRoot = join(
-      DEFAULT_RESEARCH_DOC_DIR,
+      researchDocDir,
       `${DEEP_RESEARCH_RUN_DIR_PREFIX}${runId}`,
     );
     try {
@@ -208,11 +221,17 @@ interface DeepResearchManifest {
   readonly artifacts: Record<string, string>;
 }
 
-async function writeManifest(path: string, manifest: DeepResearchManifest): Promise<void> {
+async function writeManifest(
+  path: string,
+  manifest: DeepResearchManifest,
+): Promise<void> {
   await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
 }
 
-async function writeResearchDoc(path: string, content: string): Promise<string> {
+async function writeResearchDoc(
+  path: string,
+  content: string,
+): Promise<string> {
   await mkdir(dirname(path), { recursive: true });
 
   for (let suffix = 0; ; suffix += 1) {
@@ -227,7 +246,10 @@ async function writeResearchDoc(path: string, content: string): Promise<string>
   }
 }
 
-async function readArtifactText(path: string | undefined, fallback: string): Promise<string> {
+async function readArtifactText(
+  path: string | undefined,
+  fallback: string,
+): Promise<string> {
   if (path === undefined) return fallback;
   try {
     return await readFile(path, "utf8");
@@ -270,12 +292,13 @@ async function specialistHandoffFromArtifacts(
 function manifestArtifactPaths(
   artifactPathsByStage: ReadonlyMap<string, string>,
   manifestPath: string,
+  display: (path: string) => string,
 ): Record<string, string> {
   const artifacts: Record<string, string> = {};
   for (const [stage, path] of artifactPathsByStage) {
-    artifacts[stage] = displayPath(path);
+    artifacts[stage] = display(path);
   }
-  artifacts.manifest = displayPath(manifestPath);
+  artifacts.manifest = display(manifestPath);
   return artifacts;
 }
 
@@ -292,596 +315,591 @@ function displayPath(path: string): string {
   return path.replace(/\\/g, "/");
 }
 
+function displayPathFrom(cwd: string, path: string): string {
+  const relativePath = relative(cwd, path);
+  if (relativePath.length === 0) return ".";
+  if (!relativePath.startsWith("..") && !isAbsolute(relativePath)) {
+    return displayPath(relativePath);
+  }
+  return displayPath(path);
+}
+
 function displayPaths(paths: readonly string[]): string {
   return paths.map(displayPath).join(", ");
 }
 
-export default defineWorkflow("deep-research-codebase")
-  .description(
-    "Scout + research-history chain → parallel specialist waves → aggregator for deep codebase research.",
-  )
-  .input("prompt", {
-    type: "text",
-    required: true,
-    description: "Research question or investigation focus for the codebase.",
-  })
-  .input("max_partitions", {
-    type: "number",
-    default: DEFAULT_MAX_PARTITIONS,
-    description:
-      "Maximum number of codebase partitions to explore in parallel. Actual partitions scale by one per 10K LoC, capped by this value.",
-  })
-  .input("max_concurrency", {
-    type: "number",
-    default: DEFAULT_MAX_CONCURRENCY,
-    description:
-      "Maximum number of workflow stages to run concurrently during deep research.",
-  })
-  .run(async (ctx) => {
-    const inputs = ctx.inputs as {
-      prompt?: string;
-      max_partitions?: number;
-      max_concurrency?: number;
-    };
-    const prompt = inputs.prompt ?? "";
-    const requestedMaxPartitions = positiveInteger(
-      inputs.max_partitions,
-      DEFAULT_MAX_PARTITIONS,
-    );
-    const maxConcurrency = positiveInteger(
-      inputs.max_concurrency,
-      DEFAULT_MAX_CONCURRENCY,
-    );
-    const startedAt = new Date();
-    const finalResearchDocPath = defaultResearchDocPath(prompt);
-    const codebaseLines = countCodebaseLines();
-    const partitionCap = calculatePartitionCap(
-      requestedMaxPartitions,
-      codebaseLines,
-    );
-    const { runId, artifactRoot } = await createArtifactRoot(startedAt);
-    const artifactPathsByStage = new Map<string, string>();
-    const addArtifact = (stage: string, path: string) => {
-      artifactPathsByStage.set(stage, path);
-      return path;
-    };
-    const fileOnlyOutput = (output: string): {
-      output: string;
-      outputMode: WorkflowOutputMode;
-    } => ({
-      output,
-      outputMode: FILE_ONLY_OUTPUT,
-    });
+export async function runDeepResearchCodebaseWorkflow(
+  ctx: WorkflowRunContext<Record<string, unknown>>,
+  workflowStartCwd = process.cwd(),
+): Promise<DeepResearchCodebaseResult> {
+  const inputs = ctx.inputs as {
+    prompt?: string;
+    max_partitions?: number;
+    max_concurrency?: number;
+  };
+  const prompt = inputs.prompt ?? "";
+  const requestedMaxPartitions = positiveInteger(
+    inputs.max_partitions,
+    DEFAULT_MAX_PARTITIONS,
+  );
+  const maxConcurrency = positiveInteger(
+    inputs.max_concurrency,
+    DEFAULT_MAX_CONCURRENCY,
+  );
+  const startedAt = new Date();
+  const finalResearchDocPath = join(
+    workflowStartCwd,
+    defaultResearchDocPath(prompt),
+  );
+  const codebaseLines = countCodebaseLines(workflowStartCwd);
+  const partitionCap = calculatePartitionCap(
+    requestedMaxPartitions,
+    codebaseLines,
+  );
+  const { runId, artifactRoot } = await createArtifactRoot(
+    startedAt,
+    workflowStartCwd,
+  );
+  const artifactPathsByStage = new Map<string, string>();
+  const addArtifact = (stage: string, path: string) => {
+    artifactPathsByStage.set(stage, path);
+    return path;
+  };
+  const fileOnlyOutput = (
+    output: string,
+  ): {
+    output: string;
+    outputMode: WorkflowOutputMode;
+  } => ({
+    output,
+    outputMode: FILE_ONLY_OUTPUT,
+  });
+  const displayWorkflowPath = (path: string): string =>
+    displayPathFrom(workflowStartCwd, path);
+  const displayWorkflowPaths = (paths: readonly string[]): string =>
+    paths.map(displayWorkflowPath).join(", ");
+
+  const scoutPath = addArtifact(
+    "codebase-scout",
+    join(artifactRoot, "00-codebase-scout.md"),
+  );
+  const partitionPlanPath = addArtifact(
+    "partition",
+    join(artifactRoot, "01-partition-plan.md"),
+  );
+  const historyLocatorPath = addArtifact(
+    "history-locator",
+    join(artifactRoot, "01-history-locator.md"),
+  );
+  const historyAnalyzerPath = addArtifact(
+    "history-analyzer",
+    join(artifactRoot, "02-history-analyzer.md"),
+  );
 
-    const scoutPath = addArtifact(
-      "codebase-scout",
-      join(artifactRoot, "00-codebase-scout.md"),
-    );
-    const partitionPlanPath = addArtifact(
-      "partition",
-      join(artifactRoot, "01-partition-plan.md"),
-    );
-    const historyLocatorPath = addArtifact(
-      "history-locator",
-      join(artifactRoot, "01-history-locator.md"),
-    );
-    const historyAnalyzerPath = addArtifact(
-      "history-analyzer",
-      join(artifactRoot, "02-history-analyzer.md"),
-    );
+  const plannerModelConfig = {
+    model: "openai/gpt-5.5",
+    fallbackModels: [
+      "openai-codex/gpt-5.5",
+      "github-copilot/gpt-5.5",
+      "anthropic/claude-opus-4-7",
+      "github-copilot/claude-opus-4.7",
+    ],
+    thinkingLevel: "high" as const,
+    excludeTools: ["ask_user_question"],
+  };
+
+  const explorerModelConfig = {
+    model: "openai/gpt-5.4-mini",
+    fallbackModels: [
+      "openai-codex/gpt-5.4-mini",
+      "github-copilot/gpt-5.4-mini",
+      "anthropic/claude-haiku-4-5",
+      "github-copilot/claude-haiku-4.5",
+    ],
+    thinkingLevel: "low" as const,
+    excludeTools: ["ask_user_question"],
+  };
+
+  const initialDiscovery = await ctx.parallel(
+    [
+      {
+        name: "codebase-scout",
+        task: taggedPrompt([
+          [
+            "role",
+            "You are a senior codebase research scout preparing work for specialist agents.",
+          ],
+          ["objective", `Map the repository. Research question: ${prompt}`],
+          [
+            "codebase_skills",
+            codebaseSkillGuidance("locator", "analyzer", "patternFinder"),
+          ],
+          [
+            "instructions",
+            [
+              "Identify the subsystems, files, tests, docs, and runtime/configuration areas most likely to answer the question.",
+              `Propose at most ${partitionCap} independent investigation partitions that can be assigned to parallel specialists.`,
+              "Ground codebase claims in concrete paths, symbols, commands, or docs when possible.",
+              "If evidence is missing or uncertain, say so explicitly instead of guessing.",
+            ].join("\n"),
+          ],
+          [
+            "output_format",
+            [
+              "Markdown with these headings:",
+              "1. Executive orientation",
+              "2. Key paths and why they matter",
+              "3. Suggested partitions",
+              "4. Known unknowns / risks",
+            ].join("\n"),
+          ],
+        ]),
+        ...fileOnlyOutput(scoutPath),
+        ...plannerModelConfig,
+      },
+      {
+        name: "history-locator",
+        task: taggedPrompt([
+          ["role", "You locate prior project research and decision history."],
+          [
+            "objective",
+            "Find existing docs, specs, ADRs, issues/PR notes, TODOs, and research artifacts relevant to the task.",
+          ],
+          ["task", "{task}"],
+          ["codebase_skills", codebaseSkillGuidance("researchLocator")],
+          [
+            "instructions",
+            [
+              "Search broadly before narrowing.",
+              "Prefer exact file paths, section names, and short relevance notes.",
+              "Separate strong evidence from weak/possibly stale evidence.",
+              "If no prior research exists, state that plainly and list where you looked.",
+            ].join("\n"),
+          ],
+          [
+            "output_format",
+            "A markdown table with columns: Path, Evidence, Relevance, Confidence.",
+          ],
+        ]),
+        ...fileOnlyOutput(historyLocatorPath),
+        ...explorerModelConfig,
+      },
+    ],
+    { task: prompt, concurrency: maxConcurrency },
+  );
 
-    const noAskQuestionToolSet = [
-      "read",
-      "bash",
-      "edit",
-      "write",
-      "todo",
-      "subagent",
-      "web_search",
-      "code_search",
-      "fetch_content",
-      "get_search_content",
-      "intercom",
-    ];
-
-    const plannerModelConfig = {
-      model: "openai/gpt-5.5",
-      fallbackModels: [
-        "openai-codex/gpt-5.5",
-        "github-copilot/gpt-5.5",
-        "anthropic/claude-opus-4-7",
-        "github-copilot/claude-opus-4.7",
+  const scout =
+    findResult(initialDiscovery, "codebase-scout") ?? initialDiscovery[0]!;
+  const historyLocator =
+    findResult(initialDiscovery, "history-locator") ?? initialDiscovery[1]!;
+  await ctx.chain(
+    [
+      {
+        name: "history-analyzer",
+        task: taggedPrompt([
+          [
+            "role",
+            "You synthesize prior project research for downstream investigators.",
+          ],
+          [
+            "objective",
+            `Extract reusable historical context. Research question: ${prompt}`,
+          ],
+          ["prior_research_locator_output", "{previous}"],
+          ["codebase_skills", codebaseSkillGuidance("researchAnalyzer")],
+          [
+            "instructions",
+            [
+              "Cluster related prior decisions and unresolved questions.",
+              "Identify which findings are still likely valid and which may be stale.",
+              "Quote or cite paths from the locator output for every important claim.",
+              "Do not invent history that is not supported by the locator output.",
+            ].join("\n"),
+          ],
+          [
+            "output_format",
+            [
+              "Markdown with headings:",
+              "1. Prior decisions",
+              "2. Relevant research artifacts",
+              "3. Open questions",
+              "4. How this should steer the new investigation",
+            ].join("\n"),
+          ],
+        ]),
+        previous: historyLocator,
+        reads: [historyLocatorPath],
+        ...fileOnlyOutput(historyAnalyzerPath),
+        ...plannerModelConfig,
+      },
+    ],
+    { task: prompt },
+  );
+
+  const partitionPlan = await ctx.task("partition", {
+    prompt: taggedPrompt([
+      ["role", "You turn scout research into clean work partitions."],
+      [
+        "objective",
+        `Return at most ${partitionCap} independent partitions for this research question: ${prompt}`,
       ],
-      thinkingLevel: "high" as const,
-      tools: noAskQuestionToolSet,
-    };
-
-    const explorerModelConfig = {
-      model: "openai/gpt-5.4-mini",
-      fallbackModels: [
-        "openai-codex/gpt-5.4-mini",
-        "github-copilot/gpt-5.4-mini",
-        "anthropic/claude-haiku-4-5",
-        "github-copilot/claude-haiku-4.5",
+      ["scout_output", "{previous}"],
+      [
+        "codebase_skills",
+        codebaseSkillGuidance("locator", "analyzer", "patternFinder"),
       ],
-      thinkingLevel: "low" as const,
-      tools: noAskQuestionToolSet,
-    };
-
-    const initialDiscovery = await ctx.parallel(
       [
+        "instructions",
+        [
+          "Each partition must be concrete enough for one specialist to investigate independently.",
+          "Prefer boundaries based on files, subsystems, runtime layers, or documented concepts.",
+          "Do not include bullets, numbering, markdown fences, explanations, or duplicate partitions.",
+        ].join("\n"),
+      ],
+      ["output_format", "Plain text only: one partition per line."],
+    ]),
+    previous: scout,
+    output: partitionPlanPath,
+    reads: [scoutPath],
+    ...plannerModelConfig,
+  });
+
+  const partitions = parsePartitions(partitionPlan.text, partitionCap);
+  const locatorArtifactPaths = new Map<number, string>();
+
+  const wave1Steps: WorkflowTaskStep[] = partitions.flatMap(
+    (partition, index) => {
+      const i = index + 1;
+      const locatorPath = addArtifact(
+        `locator-${i}`,
+        join(artifactRoot, `locator-${i}.md`),
+      );
+      const patternFinderPath = addArtifact(
+        `pattern-finder-${i}`,
+        join(artifactRoot, `pattern-finder-${i}.md`),
+      );
+      locatorArtifactPaths.set(i, locatorPath);
+      return [
         {
-          name: "codebase-scout",
+          name: `locator-${i}`,
           task: taggedPrompt([
+            ["role", "You are a codebase locator specialist."],
+            ["assignment", `Partition ${i}/${partitions.length}: ${partition}`],
+            ["research_question", prompt],
             [
-              "role",
-              "You are a senior codebase research scout preparing work for specialist agents.",
-            ],
-            ["objective", `Map the repository. Research question: ${prompt}`],
-            [
-              "codebase_skills",
-              codebaseSkillGuidance("locator", "analyzer", "patternFinder"),
+              "scout_context",
+              `Read the scout artifact before making evidence claims: ${displayWorkflowPath(scoutPath)}\nCompact saved-output reference: {previous}`,
             ],
+            ["codebase_skills", codebaseSkillGuidance("locator")],
             [
               "instructions",
               [
-                "Identify the subsystems, files, tests, docs, and runtime/configuration areas most likely to answer the question.",
-                `Propose at most ${partitionCap} independent investigation partitions that can be assigned to parallel specialists.`,
-                "Ground codebase claims in concrete paths, symbols, commands, or docs when possible.",
-                "If evidence is missing or uncertain, say so explicitly instead of guessing.",
+                "Find the highest-signal files, tests, docs, commands, configs, and symbols for this partition.",
+                "Explain why each path matters for the research question.",
+                "Prioritize exact paths and symbol names over broad descriptions.",
+                "Flag areas that look relevant but could not be verified.",
               ].join("\n"),
             ],
             [
               "output_format",
               [
-                "Markdown with these headings:",
-                "1. Executive orientation",
-                "2. Key paths and why they matter",
-                "3. Suggested partitions",
-                "4. Known unknowns / risks",
+                "Markdown with headings:",
+                "1. Must-read paths",
+                "2. Supporting paths",
+                "3. Entry points / symbols",
+                "4. Gaps or uncertainty",
               ].join("\n"),
             ],
           ]),
-          ...fileOnlyOutput(scoutPath),
-          ...plannerModelConfig,
+          previous: scout,
+          reads: [scoutPath],
+          ...fileOnlyOutput(locatorPath),
+          ...explorerModelConfig,
         },
         {
-          name: "history-locator",
+          name: `pattern-finder-${i}`,
           task: taggedPrompt([
-            ["role", "You locate prior project research and decision history."],
+            ["role", "You are a codebase pattern-finding specialist."],
+            ["assignment", `Partition ${i}/${partitions.length}: ${partition}`],
+            ["research_question", prompt],
             [
-              "objective",
-              "Find existing docs, specs, ADRs, issues/PR notes, TODOs, and research artifacts relevant to the task.",
+              "scout_context",
+              `Read the scout artifact before making evidence claims: ${displayWorkflowPath(scoutPath)}\nCompact saved-output reference: {previous}`,
             ],
-            ["task", "{task}"],
-            ["codebase_skills", codebaseSkillGuidance("researchLocator")],
+            ["codebase_skills", codebaseSkillGuidance("patternFinder")],
             [
               "instructions",
               [
-                "Search broadly before narrowing.",
-                "Prefer exact file paths, section names, and short relevance notes.",
-                "Separate strong evidence from weak/possibly stale evidence.",
-                "If no prior research exists, state that plainly and list where you looked.",
+                "Identify recurring implementation patterns, abstractions, naming conventions, and anti-patterns in this partition.",
+                "Use concrete examples with paths, symbols, or test names.",
+                "Distinguish established conventions from one-off implementation details.",
+                "Avoid generic advice that is not grounded in the repository.",
               ].join("\n"),
             ],
             [
               "output_format",
-              "A markdown table with columns: Path, Evidence, Relevance, Confidence.",
+              [
+                "Markdown with headings:",
+                "1. Established patterns",
+                "2. Variations / exceptions",
+                "3. Anti-patterns or risks",
+                "4. Evidence index",
+              ].join("\n"),
             ],
           ]),
-          ...fileOnlyOutput(historyLocatorPath),
+          previous: scout,
+          reads: [scoutPath],
+          ...fileOnlyOutput(patternFinderPath),
           ...explorerModelConfig,
         },
-      ],
-      { task: prompt, concurrency: maxConcurrency },
-    );
+      ];
+    },
+  );
 
-    const scout =
-      findResult(initialDiscovery, "codebase-scout") ?? initialDiscovery[0]!;
-    const historyLocator =
-      findResult(initialDiscovery, "history-locator") ?? initialDiscovery[1]!;
-    await ctx.chain(
-      [
+  const wave1 = await ctx.parallel(wave1Steps, {
+    task: prompt,
+    concurrency: maxConcurrency,
+  });
+
+  const wave2Steps: WorkflowTaskStep[] = partitions.flatMap(
+    (partition, index) => {
+      const i = index + 1;
+      const locator = findResult(wave1, `locator-${i}`);
+      const locatorPath =
+        locator === undefined ? undefined : locatorArtifactPaths.get(i);
+      const analyzerReads =
+        locatorPath === undefined ? [scoutPath] : [scoutPath, locatorPath];
+      const onlineResearcherReads =
+        locatorPath === undefined ? [scoutPath] : [locatorPath];
+      const onlineResearcherLocalContext =
+        locatorPath === undefined
+          ? `Read scout context before researching: ${displayWorkflowPath(scoutPath)}\nCompact saved-output reference: {previous}`
+          : `Read local artifact context before researching: ${displayWorkflowPath(locatorPath)}\nCompact saved-output reference: {previous}`;
+      const analyzerPath = addArtifact(
+        `analyzer-${i}`,
+        join(artifactRoot, `analyzer-${i}.md`),
+      );
+      const onlineResearcherPath = addArtifact(
+        `online-${i}`,
+        join(artifactRoot, `online-${i}.md`),
+      );
+      return [
         {
-          name: "history-analyzer",
+          name: `analyzer-${i}`,
           task: taggedPrompt([
+            ["role", "You are a codebase behavior and architecture analyzer."],
+            ["assignment", `Partition ${i}/${partitions.length}: ${partition}`],
+            ["research_question", prompt],
             [
-              "role",
-              "You synthesize prior project research for downstream investigators.",
-            ],
-            [
-              "objective",
-              `Extract reusable historical context. Research question: ${prompt}`,
+              "context",
+              `Read these artifacts before analyzing: ${displayWorkflowPaths(analyzerReads)}\nCompact saved-output reference: {previous}`,
             ],
-            ["prior_research_locator_output", "{previous}"],
-            ["codebase_skills", codebaseSkillGuidance("researchAnalyzer")],
+            ["codebase_skills", codebaseSkillGuidance("analyzer")],
             [
               "instructions",
               [
-                "Cluster related prior decisions and unresolved questions.",
-                "Identify which findings are still likely valid and which may be stale.",
-                "Quote or cite paths from the locator output for every important claim.",
-                "Do not invent history that is not supported by the locator output.",
+                "Analyze behavior, control flow, data flow, lifecycle, error handling, and test coverage for this partition.",
+                "Build on the locator output; do not repeat file discovery except where needed as evidence.",
+                "Call out edge cases, invariants, and coupling to other partitions.",
+                "If evidence is incomplete, explain what remains unknown and how to verify it.",
               ].join("\n"),
             ],
             [
               "output_format",
               [
                 "Markdown with headings:",
-                "1. Prior decisions",
-                "2. Relevant research artifacts",
-                "3. Open questions",
-                "4. How this should steer the new investigation",
+                "1. Behavioral model",
+                "2. Key flows and invariants",
+                "3. Tests / validation",
+                "4. Risks, unknowns, and verification steps",
               ].join("\n"),
             ],
           ]),
-          previous: historyLocator,
-          reads: [historyLocatorPath],
-          ...fileOnlyOutput(historyAnalyzerPath),
-          ...plannerModelConfig,
+          previous: locator === undefined ? scout : [scout, locator],
+          reads: analyzerReads,
+          ...fileOnlyOutput(analyzerPath),
+          ...explorerModelConfig,
         },
-      ],
-      { task: prompt },
-    );
-
-    const partitionPlan = await ctx.task("partition", {
-      prompt: taggedPrompt([
-        ["role", "You turn scout research into clean work partitions."],
-        [
-          "objective",
-          `Return at most ${partitionCap} independent partitions for this research question: ${prompt}`,
-        ],
-        ["scout_output", "{previous}"],
-        [
-          "codebase_skills",
-          codebaseSkillGuidance("locator", "analyzer", "patternFinder"),
-        ],
-        [
-          "instructions",
-          [
-            "Each partition must be concrete enough for one specialist to investigate independently.",
-            "Prefer boundaries based on files, subsystems, runtime layers, or documented concepts.",
-            "Do not include bullets, numbering, markdown fences, explanations, or duplicate partitions.",
-          ].join("\n"),
-        ],
-        ["output_format", "Plain text only: one partition per line."],
-      ]),
-      previous: scout,
-      output: partitionPlanPath,
-      reads: [scoutPath],
-      ...plannerModelConfig,
-    });
-
-    const partitions = parsePartitions(partitionPlan.text, partitionCap);
-    const locatorArtifactPaths = new Map<number, string>();
-
-    const wave1Steps: WorkflowTaskStep[] = partitions.flatMap(
-      (partition, index) => {
-        const i = index + 1;
-        const locatorPath = addArtifact(
-          `locator-${i}`,
-          join(artifactRoot, `locator-${i}.md`),
-        );
-        const patternFinderPath = addArtifact(
-          `pattern-finder-${i}`,
-          join(artifactRoot, `pattern-finder-${i}.md`),
-        );
-        locatorArtifactPaths.set(i, locatorPath);
-        return [
-          {
-            name: `locator-${i}`,
-            task: taggedPrompt([
-              ["role", "You are a codebase locator specialist."],
-              [
-                "assignment",
-                `Partition ${i}/${partitions.length}: ${partition}`,
-              ],
-              ["research_question", prompt],
-              [
-                "scout_context",
-                `Read the scout artifact before making evidence claims: ${displayPath(scoutPath)}\nCompact saved-output reference: {previous}`,
-              ],
-              ["codebase_skills", codebaseSkillGuidance("locator")],
-              [
-                "instructions",
-                [
-                  "Find the highest-signal files, tests, docs, commands, configs, and symbols for this partition.",
-                  "Explain why each path matters for the research question.",
-                  "Prioritize exact paths and symbol names over broad descriptions.",
-                  "Flag areas that look relevant but could not be verified.",
-                ].join("\n"),
-              ],
-              [
-                "output_format",
-                [
-                  "Markdown with headings:",
-                  "1. Must-read paths",
-                  "2. Supporting paths",
-                  "3. Entry points / symbols",
-                  "4. Gaps or uncertainty",
-                ].join("\n"),
-              ],
-            ]),
-            previous: scout,
-            reads: [scoutPath],
-            ...fileOnlyOutput(locatorPath),
-            ...explorerModelConfig,
-          },
-          {
-            name: `pattern-finder-${i}`,
-            task: taggedPrompt([
-              ["role", "You are a codebase pattern-finding specialist."],
-              [
-                "assignment",
-                `Partition ${i}/${partitions.length}: ${partition}`,
-              ],
-              ["research_question", prompt],
-              [
-                "scout_context",
-                `Read the scout artifact before making evidence claims: ${displayPath(scoutPath)}\nCompact saved-output reference: {previous}`,
-              ],
-              ["codebase_skills", codebaseSkillGuidance("patternFinder")],
-              [
-                "instructions",
-                [
-                  "Identify recurring implementation patterns, abstractions, naming conventions, and anti-patterns in this partition.",
-                  "Use concrete examples with paths, symbols, or test names.",
-                  "Distinguish established conventions from one-off implementation details.",
-                  "Avoid generic advice that is not grounded in the repository.",
-                ].join("\n"),
-              ],
-              [
-                "output_format",
-                [
-                  "Markdown with headings:",
-                  "1. Established patterns",
-                  "2. Variations / exceptions",
-                  "3. Anti-patterns or risks",
-                  "4. Evidence index",
-                ].join("\n"),
-              ],
-            ]),
-            previous: scout,
-            reads: [scoutPath],
-            ...fileOnlyOutput(patternFinderPath),
-            ...explorerModelConfig,
-          },
-        ];
-      },
-    );
-
-    const wave1 = await ctx.parallel(wave1Steps, {
-      task: prompt,
-      concurrency: maxConcurrency,
-    });
-
-    const wave2Steps: WorkflowTaskStep[] = partitions.flatMap(
-      (partition, index) => {
-        const i = index + 1;
-        const locator = findResult(wave1, `locator-${i}`);
-        const locatorPath =
-          locator === undefined ? undefined : locatorArtifactPaths.get(i);
-        const analyzerReads =
-          locatorPath === undefined ? [scoutPath] : [scoutPath, locatorPath];
-        const onlineResearcherReads =
-          locatorPath === undefined ? [scoutPath] : [locatorPath];
-        const onlineResearcherLocalContext =
-          locatorPath === undefined
-            ? `Read scout context before researching: ${displayPath(scoutPath)}\nCompact saved-output reference: {previous}`
-            : `Read local artifact context before researching: ${displayPath(locatorPath)}\nCompact saved-output reference: {previous}`;
-        const analyzerPath = addArtifact(
-          `analyzer-${i}`,
-          join(artifactRoot, `analyzer-${i}.md`),
-        );
-        const onlineResearcherPath = addArtifact(
-          `online-${i}`,
-          join(artifactRoot, `online-${i}.md`),
-        );
-        return [
-          {
-            name: `analyzer-${i}`,
-            task: taggedPrompt([
-              [
-                "role",
-                "You are a codebase behavior and architecture analyzer.",
-              ],
-              [
-                "assignment",
-                `Partition ${i}/${partitions.length}: ${partition}`,
-              ],
-              ["research_question", prompt],
-              [
-                "context",
-                `Read these artifacts before analyzing: ${displayPaths(analyzerReads)}\nCompact saved-output reference: {previous}`,
-              ],
-              ["codebase_skills", codebaseSkillGuidance("analyzer")],
-              [
-                "instructions",
-                [
-                  "Analyze behavior, control flow, data flow, lifecycle, error handling, and test coverage for this partition.",
-                  "Build on the locator output; do not repeat file discovery except where needed as evidence.",
-                  "Call out edge cases, invariants, and coupling to other partitions.",
-                  "If evidence is incomplete, explain what remains unknown and how to verify it.",
-                ].join("\n"),
-              ],
-              [
-                "output_format",
-                [
-                  "Markdown with headings:",
-                  "1. Behavioral model",
-                  "2. Key flows and invariants",
-                  "3. Tests / validation",
-                  "4. Risks, unknowns, and verification steps",
-                ].join("\n"),
-              ],
-            ]),
-            previous: locator === undefined ? scout : [scout, locator],
-            reads: analyzerReads,
-            ...fileOnlyOutput(analyzerPath),
-            ...explorerModelConfig,
-          },
-          {
-            name: `online-researcher-${i}`,
-            task: taggedPrompt([
-              [
-                "role",
-                "You are an ecosystem and documentation research specialist.",
-              ],
-              [
-                "assignment",
-                `Partition ${i}/${partitions.length}: ${partition}`,
-              ],
-              ["research_question", prompt],
-              [
-                "local_context",
-                onlineResearcherLocalContext,
-              ],
-              ["codebase_skills", codebaseSkillGuidance("onlineResearcher")],
+        {
+          name: `online-researcher-${i}`,
+          task: taggedPrompt([
+            [
+              "role",
+              "You are an ecosystem and documentation research specialist.",
+            ],
+            ["assignment", `Partition ${i}/${partitions.length}: ${partition}`],
+            ["research_question", prompt],
+            ["local_context", onlineResearcherLocalContext],
+            ["codebase_skills", codebaseSkillGuidance("onlineResearcher")],
+            [
+              "instructions",
               [
-                "instructions",
-                [
-                  "Identify external library/framework behavior, standards, or docs that materially affect the local interpretation.",
-                  "Cite sources, package names, API names, versions, or documentation titles when available.",
-                  "Explain how each external fact applies to this repository.",
-                  "If external research is unnecessary or unavailable, say so and focus on local implications.",
-                ].join("\n"),
-              ],
+                "Identify external library/framework behavior, standards, or docs that materially affect the local interpretation.",
+                "Cite sources, package names, API names, versions, or documentation titles when available.",
+                "Explain how each external fact applies to this repository.",
+                "If external research is unnecessary or unavailable, say so and focus on local implications.",
+              ].join("\n"),
+            ],
+            [
+              "output_format",
               [
-                "output_format",
-                [
-                  "Markdown with headings:",
-                  "1. Relevant external facts",
-                  "2. Local implications",
-                  "3. Version/API assumptions",
-                  "4. Unverified or unnecessary research",
-                ].join("\n"),
-              ],
-            ]),
-            previous: locator === undefined ? scout : locator,
-            reads: onlineResearcherReads,
-            ...fileOnlyOutput(onlineResearcherPath),
-            ...explorerModelConfig,
-          },
-        ];
-      },
-    );
+                "Markdown with headings:",
+                "1. Relevant external facts",
+                "2. Local implications",
+                "3. Version/API assumptions",
+                "4. Unverified or unnecessary research",
+              ].join("\n"),
+            ],
+          ]),
+          previous: locator === undefined ? scout : locator,
+          reads: onlineResearcherReads,
+          ...fileOnlyOutput(onlineResearcherPath),
+          ...explorerModelConfig,
+        },
+      ];
+    },
+  );
 
-    const wave2 = await ctx.parallel(wave2Steps, {
-      task: prompt,
-      concurrency: maxConcurrency,
-    });
-    const historyOverview = await readArtifactText(historyAnalyzerPath, "");
-    const explorerPaths = await Promise.all(
-      partitions.map(async (partition, index) => {
-        const i = index + 1;
-        const explorerPath = addArtifact(
-          `explorer-${i}`,
-          join(artifactRoot, `explorer-${i}.md`),
-        );
-        const explorer = await specialistHandoffFromArtifacts(
-          partition,
-          index,
-          artifactPathsByStage,
-        );
-        await writeFile(explorerPath, explorer, "utf8");
-        return explorerPath;
-      }),
-    );
-    const aggregatorReadPaths = [
-      scoutPath,
-      partitionPlanPath,
-      ...(historyOverview === "" ? [] : [historyAnalyzerPath]),
-      ...explorerPaths,
-    ];
-
-    const aggregate = await ctx.task("aggregator", {
-      prompt: taggedPrompt([
-        ["role", "You are the final deep-research aggregator."],
-        [
-          "objective",
-          `Answer the research question comprehensively: ${prompt}`,
-        ],
-        [
-          "context_artifacts",
-          [
-            `Read the scout artifact at ${displayPath(scoutPath)}.`,
-            `Read the partition plan artifact at ${displayPath(partitionPlanPath)}.`,
-            historyOverview === ""
-              ? "No prior research overview artifact is available."
-              : `Read the prior research overview artifact at ${displayPath(historyAnalyzerPath)}.`,
-          ].join("\n"),
-        ],
+  const wave2 = await ctx.parallel(wave2Steps, {
+    task: prompt,
+    concurrency: maxConcurrency,
+  });
+  const historyOverview = await readArtifactText(historyAnalyzerPath, "");
+  const explorerPaths = await Promise.all(
+    partitions.map(async (partition, index) => {
+      const i = index + 1;
+      const explorerPath = addArtifact(
+        `explorer-${i}`,
+        join(artifactRoot, `explorer-${i}.md`),
+      );
+      const explorer = await specialistHandoffFromArtifacts(
+        partition,
+        index,
+        artifactPathsByStage,
+      );
+      await writeFile(explorerPath, explorer, "utf8");
+      return explorerPath;
+    }),
+  );
+  const aggregatorReadPaths = [
+    scoutPath,
+    partitionPlanPath,
+    ...(historyOverview === "" ? [] : [historyAnalyzerPath]),
+    ...explorerPaths,
+  ];
+
+  const aggregate = await ctx.task("aggregator", {
+    prompt: taggedPrompt([
+      ["role", "You are the final deep-research aggregator."],
+      ["objective", `Answer the research question comprehensively: ${prompt}`],
+      [
+        "context_artifacts",
         [
-          "prior_research_overview",
+          `Read the scout artifact at ${displayWorkflowPath(scoutPath)}.`,
+          `Read the partition plan artifact at ${displayWorkflowPath(partitionPlanPath)}.`,
           historyOverview === ""
-            ? "(no prior research found)"
-            : `Read the prior research overview artifact at ${displayPath(historyAnalyzerPath)}.`,
-        ],
-        [
-          "specialist_reports",
-          `Read the complete explorer handoff artifact(s) at ${displayPaths(explorerPaths)}. They preserve every partition's Locator, Pattern Finder, Analyzer, and Online Researcher output from the original inline specialist handoff while keeping this prompt bounded.`,
-        ],
-        [
-          "codebase_skills",
-          codebaseSkillGuidance(
-            "analyzer",
-            "researchAnalyzer",
-            "onlineResearcher",
-          ),
-        ],
+            ? "No prior research overview artifact is available."
+            : `Read the prior research overview artifact at ${displayWorkflowPath(historyAnalyzerPath)}.`,
+        ].join("\n"),
+      ],
+      [
+        "prior_research_overview",
+        historyOverview === ""
+          ? "(no prior research found)"
+          : `Read the prior research overview artifact at ${displayWorkflowPath(historyAnalyzerPath)}.`,
+      ],
+      [
+        "specialist_reports",
+        `Read the complete explorer handoff artifact(s) at ${displayWorkflowPaths(explorerPaths)}. They preserve every partition's Locator, Pattern Finder, Analyzer, and Online Researcher output from the original inline specialist handoff while keeping this prompt bounded.`,
+      ],
+      [
+        "codebase_skills",
+        codebaseSkillGuidance(
+          "analyzer",
+          "researchAnalyzer",
+          "onlineResearcher",
+        ),
+      ],
+      [
+        "instructions",
         [
-          "instructions",
-          [
-            "Synthesize; do not merely concatenate specialist reports.",
-            "Use the supplied input files as the source of detailed scout, partition, history, and specialist evidence instead of relying on inline transcripts.",
-            "Prioritize claims supported by concrete paths, symbols, tests, docs, or cited external references.",
-            "Resolve contradictions explicitly and preserve important uncertainty.",
-            "Avoid inventing facts not supported by the supplied reports; state unknowns instead.",
-            "End with actionable next steps for a developer who will use this research.",
-          ].join("\n"),
-        ],
+          "Synthesize; do not merely concatenate specialist reports.",
+          "Use the supplied input files as the source of detailed scout, partition, history, and specialist evidence instead of relying on inline transcripts.",
+          "Prioritize claims supported by concrete paths, symbols, tests, docs, or cited external references.",
+          "Resolve contradictions explicitly and preserve important uncertainty.",
+          "Avoid inventing facts not supported by the supplied reports; state unknowns instead.",
+          "End with actionable next steps for a developer who will use this research.",
+        ].join("\n"),
+      ],
+      [
+        "output_format",
         [
-          "output_format",
-          [
-            "Markdown with headings:",
-            "1. Executive answer",
-            "2. Architecture / behavior findings",
-            "3. Evidence by partition",
-            "4. Risks and unknowns",
-            "5. Recommended next steps",
-          ].join("\n"),
-        ],
-      ]),
-      reads: aggregatorReadPaths,
-      ...explorerModelConfig,
-    });
-
-    const writtenResearchDocPath = await writeResearchDoc(
-      finalResearchDocPath,
-      aggregate.text,
-    );
-    const manifestPath = join(artifactRoot, "manifest.json");
-    const completedAt = new Date();
-    await writeManifest(manifestPath, {
-      runId,
-      startedAt: startedAt.toISOString(),
-      completedAt: completedAt.toISOString(),
-      researchQuestion: prompt,
-      finalAsset: displayPath(writtenResearchDocPath),
-      artifacts: manifestArtifactPaths(artifactPathsByStage, manifestPath),
-    });
+          "Markdown with headings:",
+          "1. Executive answer",
+          "2. Architecture / behavior findings",
+          "3. Evidence by partition",
+          "4. Risks and unknowns",
+          "5. Recommended next steps",
+        ].join("\n"),
+      ],
+    ]),
+    reads: aggregatorReadPaths,
+    ...explorerModelConfig,
+  });
+
+  const writtenResearchDocPath = await writeResearchDoc(
+    finalResearchDocPath,
+    aggregate.text,
+  );
+  const manifestPath = join(artifactRoot, "manifest.json");
+  const completedAt = new Date();
+  await writeManifest(manifestPath, {
+    runId,
+    startedAt: startedAt.toISOString(),
+    completedAt: completedAt.toISOString(),
+    researchQuestion: prompt,
+    finalAsset: displayWorkflowPath(writtenResearchDocPath),
+    artifacts: manifestArtifactPaths(
+      artifactPathsByStage,
+      manifestPath,
+      displayWorkflowPath,
+    ),
+  });
+
+  const result: DeepResearchCodebaseResult = {
+    findings: aggregate.text,
+    research_doc_path: displayWorkflowPath(writtenResearchDocPath),
+    artifact_dir: displayWorkflowPath(artifactRoot),
+    manifest_path: displayWorkflowPath(manifestPath),
+    partitions,
+    explorer_count: partitions.length,
+    specialist_count: wave1.length + wave2.length,
+    max_concurrency: maxConcurrency,
+    history: historyOverview,
+  };
+  return result;
+}
 
-    const result: DeepResearchCodebaseResult = {
-      findings: aggregate.text,
-      research_doc_path: displayPath(writtenResearchDocPath),
-      artifact_dir: displayPath(artifactRoot),
-      manifest_path: displayPath(manifestPath),
-      partitions,
-      explorer_count: partitions.length,
-      specialist_count: wave1.length + wave2.length,
-      max_concurrency: maxConcurrency,
-      history: historyOverview,
-    };
-    return result;
+export default defineWorkflow("deep-research-codebase")
+  .description(
+    "Scout + research-history chain → parallel specialist waves → aggregator for deep codebase research.",
+  )
+  .input("prompt", {
+    type: "text",
+    required: true,
+    description: "Research question or investigation focus for the codebase.",
+  })
+  .input("max_partitions", {
+    type: "number",
+    default: DEFAULT_MAX_PARTITIONS,
+    description:
+      "Maximum number of codebase partitions to explore in parallel. Actual partitions scale by one per 10K LoC, capped by this value.",
+  })
+  .input("max_concurrency", {
+    type: "number",
+    default: DEFAULT_MAX_CONCURRENCY,
+    description:
+      "Maximum number of workflow stages to run concurrently during deep research.",
   })
+  .run(async (ctx) => runDeepResearchCodebaseWorkflow(ctx, ctx.cwd))
   .compile();