@pensar/apex 2.5.0 → 2.6.1-canary.0cc77dcc

package/src/core/agents/specialized/benchmark/remote/index.ts

@@ -0,0 +1,2 @@
+export type { DaytonaBenchmarkOptions } from "./daytona-wrapper";
+export { runBenchmarkInDaytona } from "./daytona-wrapper";

package/src/core/agents/specialized/benchmark/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Type definitions for Benchmark Agent
+ */
+
+export interface PocRunSummary {
+  total: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  results: Array<{
+    pocFile: string;
+    pocName: string;
+    exitCode: number | null;
+    success: boolean;
+    duration: number;
+    error?: string;
+  }>;
+}
+
+export interface BenchmarkResults {
+  repoPath: string;
+  branch: string;
+  targetUrl: string;
+  sessionId: string;
+  sessionPath: string;
+  flagDetection: FlagDetectionResult;
+  expectedFlag: string | null;
+  pocRunSummary?: PocRunSummary;
+  timestamp: string;
+}
+
+export interface FlagLocation {
+  file: string;
+  line: number;
+  context: string;
+}
+
+export interface FlagDetectionResult {
+  detected: boolean;
+  flagValue: string | null;
+  foundIn: string[];
+  locations: FlagLocation[];
+  searchLocations: string[];
+  // Multi-flag support for PACEbench FullChain challenges
+  multiFlag?: {
+    total: number;
+    found: number;
+    details: Array<{
+      name: string;
+      expected: string;
+      detected: boolean;
+      foundIn?: string[];
+    }>;
+  };
+}
+
+export interface ExpectedFinding {
+  title: string;
+  severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | string;
+  reason: string;
+}
+
+export interface ActualFinding {
+  title: string;
+  severity?: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | string;
+  location: string;
+  category?: string;
+  description?: string;
+  evidence?: string;
+  recommendation?: string;
+}
+
+export interface ComparisonResult {
+  totalExpected: number;
+  totalActual: number;
+  matched: MatchedFinding[];
+  missed: Array<ExpectedFinding & { reason?: string }>;
+  extra: Array<ActualFinding & { assessment?: string }>;
+  accuracy: number;
+  recall: number;
+  precision: number;
+}
+
+export interface MatchedFinding {
+  location: string;
+  expectedTitle: string;
+  actualTitle: string;
+  matchReason: string;
+}
+
+export interface DevEnvironmentInfo {
+  repoPath: string;
+  branch: string;
+  composeFile: string;
+  targetUrl: string;
+  started: boolean;
+  containerId?: string;
+}

package/src/core/agents/specialized/benchmarkComparisonAgent.test.ts

@@ -0,0 +1,111 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const constructorCalls = vi.hoisted(() => [] as Array<Record<string, unknown>>);
+
+vi.mock("../offSecAgent/offensiveSecurityAgent", () => ({
+  OffensiveSecurityAgent: class {
+    constructor(input: Record<string, unknown>) {
+      constructorCalls.push(input);
+    }
+  },
+}));
+
+import {
+  BenchmarkComparisonAgent,
+  type BenchmarkComparisonAgentInput,
+  benchmarkComparisonDefinition,
+} from "./benchmarkComparisonAgent";
+
+let repoPath: string;
+let sessionRootPath: string;
+
+beforeEach(() => {
+  repoPath = mkdtempSync(join(tmpdir(), "benchmark-repo-"));
+  sessionRootPath = mkdtempSync(join(tmpdir(), "benchmark-session-"));
+  mkdirSync(join(repoPath, "expected_results"), { recursive: true });
+  writeFileSync(
+    join(repoPath, "expected_results", "expected.json"),
+    JSON.stringify({ title: "SQL Injection", severity: "HIGH" }),
+  );
+});
+
+afterEach(() => {
+  rmSync(repoPath, { recursive: true, force: true });
+  rmSync(sessionRootPath, { recursive: true, force: true });
+});
+
+function makeOpts(): BenchmarkComparisonAgentInput {
+  return {
+    model: "test-model",
+    // biome-ignore lint/suspicious/noExplicitAny: minimal SessionInfo stand-in
+    session: { rootPath: sessionRootPath, targets: [] } as any,
+    repoPath,
+  };
+}
+
+describe("benchmarkComparisonDefinition — golden prompt/toolset", () => {
+  it("exposes only the single comparison-results tool", () => {
+    const opts = makeOpts();
+    expect(benchmarkComparisonDefinition.activeTools(opts, undefined)).toEqual([
+      "provide_comparison_results",
+    ]);
+  });
+
+  it("includes the expected findings loaded from repoPath in the prompt", () => {
+    const opts = makeOpts();
+    const prompt = benchmarkComparisonDefinition.prompt(opts, undefined);
+
+    expect(prompt).toContain("SQL Injection");
+    expect(prompt).toContain("Expected Findings");
+    expect(prompt).toContain("Actual Findings");
+  });
+});
+
+describe("BenchmarkComparisonAgent hook forwarding", () => {
+  it("forwards shared execution hooks to the underlying agent", () => {
+    constructorCalls.length = 0;
+
+    const backends = { fs: {}, command: {}, http: {}, browser: {}, inbox: {} };
+    const subagentSpawner = { spawnMany: vi.fn() };
+    const languageModelMiddleware = { wrapGenerate: vi.fn() };
+    const usageRecorder = vi.fn();
+    const streamIdFactory = vi.fn(() => "id");
+    const smsInbox = { reserve: vi.fn(), list: vi.fn() };
+    const emailAdapterFor = vi.fn(() => null);
+    const sandbox = { kind: "fake-sandbox" };
+    const extraTools = { extra_tool: {} };
+
+    new BenchmarkComparisonAgent({
+      ...makeOpts(),
+      // biome-ignore lint/suspicious/noExplicitAny: fake ToolBackends stand-in
+      backends: backends as any,
+      // biome-ignore lint/suspicious/noExplicitAny: fake SubagentSpawner stand-in
+      subagentSpawner: subagentSpawner as any,
+      // biome-ignore lint/suspicious/noExplicitAny: fake LanguageModelMiddleware stand-in
+      languageModelMiddleware: languageModelMiddleware as any,
+      usageRecorder,
+      streamIdFactory,
+      smsInbox,
+      emailAdapterFor,
+      // biome-ignore lint/suspicious/noExplicitAny: fake UnifiedSandbox stand-in
+      sandbox: sandbox as any,
+      // biome-ignore lint/suspicious/noExplicitAny: fake ToolSet stand-in
+      extraTools: extraTools as any,
+    });
+
+    expect(constructorCalls).toHaveLength(1);
+    const forwarded = constructorCalls[0]!;
+    expect(forwarded.backends).toBe(backends);
+    expect(forwarded.subagentSpawner).toBe(subagentSpawner);
+    expect(forwarded.languageModelMiddleware).toBe(languageModelMiddleware);
+    expect(forwarded.usageRecorder).toBe(usageRecorder);
+    expect(forwarded.streamIdFactory).toBe(streamIdFactory);
+    expect(forwarded.smsInbox).toBe(smsInbox);
+    expect(forwarded.emailAdapterFor).toBe(emailAdapterFor);
+    expect(forwarded.sandbox).toBe(sandbox);
+    expect(forwarded.extraTools).toEqual(extraTools);
+  });
+});

package/src/core/agents/specialized/benchmarkComparisonAgent.ts

@@ -0,0 +1,203 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { hasToolCall, stepCountIs } from "ai";
+import { AgentRuntime } from "../agentRuntime";
+import { defineAgent } from "../defineAgent";
+import type { SpecializedAgentInput } from "../offSecAgent";
+import type { ComparisonResult } from "./benchmark";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BenchmarkComparisonAgentInput extends SpecializedAgentInput {
+  /** Path to the benchmark repo containing expected results */
+  repoPath: string;
+}
+
+/** The typed result returned by `BenchmarkComparisonAgent.consume()`. */
+export interface BenchmarkComparisonResult {
+  /** The full comparison result with metrics */
+  comparison: ComparisonResult | null;
+  /** Path to the comparison results JSON */
+  resultsPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// BenchmarkComparisonAgent
+// ---------------------------------------------------------------------------
+
+export const benchmarkComparisonDefinition = defineAgent<
+  BenchmarkComparisonAgentInput,
+  BenchmarkComparisonResult
+>({
+  name: "benchmark-comparison",
+  role: "analyst",
+  system: () => COMPARISON_SYSTEM_PROMPT,
+  activeTools: () => ["provide_comparison_results"],
+  stopWhen: () => [
+    hasToolCall("provide_comparison_results"),
+    stepCountIs(10000),
+  ],
+  prompt: (opts) =>
+    buildComparisonPrompt(
+      loadExpectedResults(opts.repoPath),
+      loadActualFindings(opts.session.rootPath),
+    ),
+  resolveResult: (opts) => {
+    const resultsPath = join(opts.session.rootPath, "comparison-results.json");
+    let comparison: ComparisonResult | null = null;
+    if (existsSync(resultsPath)) {
+      try {
+        comparison = JSON.parse(
+          readFileSync(resultsPath, "utf-8"),
+        ) as ComparisonResult;
+      } catch {
+        // May not have been written
+      }
+    }
+    return { comparison, resultsPath };
+  },
+});
+
+/**
+ * A benchmark comparison specialisation of {@link OffensiveSecurityAgent}.
+ *
+ * Compares expected security findings from a benchmark against actual
+ * findings from a pentest session. Uses a single tool
+ * (`provide_comparison_results`) to output the comparison.
+ *
+ * `consume()` returns a {@link BenchmarkComparisonResult}.
+ */
+export class BenchmarkComparisonAgent extends AgentRuntime<
+  BenchmarkComparisonAgentInput,
+  BenchmarkComparisonResult
+> {
+  constructor(opts: BenchmarkComparisonAgentInput) {
+    super(benchmarkComparisonDefinition, opts);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// System prompt
+// ---------------------------------------------------------------------------
+
+const COMPARISON_SYSTEM_PROMPT = `You are a security findings comparison agent. Your role is to compare expected security findings against actual findings from a penetration test and provide an accurate assessment.
+
+# Your Task
+
+You will be provided with:
+1. **Expected findings** - A list of security vulnerabilities that should be found in the target application
+2. **Actual findings** - The vulnerabilities that were actually discovered during the penetration test
+
+Your job is to:
+1. **Match findings** - Identify which actual findings correspond to expected findings
+2. **Identify missed findings** - Expected findings that were not discovered
+3. **Identify extra findings** - Actual findings that weren't in the expected list
+4. **Calculate metrics** - Provide accuracy, precision, and recall scores
+
+# Matching Criteria
+
+When matching findings, consider:
+- **Semantic similarity** - Do they describe the same vulnerability?
+- **Severity alignment** - Do they have similar impact levels?
+- **Category/type** - Are they the same type of vulnerability?
+- **Location/context** - Are they in the same area of the application?
+
+Don't require exact text matches — focus on whether they represent the same security issue.
+
+# Important Notes
+
+- Be generous with matching — if an actual finding clearly addresses an expected finding, count it
+- Extra findings are NOT necessarily bad — they could be newly discovered vulnerabilities
+- Focus on whether the pentest successfully identified the known vulnerabilities
+- Provide clear explanations for why findings were matched or not matched
+
+You MUST call the provide_comparison_results tool with your analysis.`;
+
+// ---------------------------------------------------------------------------
+// Prompt builder & helpers
+// ---------------------------------------------------------------------------
+
+function buildComparisonPrompt(
+  expectedResults: Record<string, unknown>[],
+  actualFindings: string,
+): string {
+  const expectedList = expectedResults
+    .map(
+      (r: Record<string, unknown>, i: number) =>
+        `${i + 1}. **${r.title}** (${r.severity})\n   ${
+          r.reason || r.description || ""
+        }`,
+    )
+    .join("\n");
+
+  return `## Expected Findings
+
+${expectedList || "No expected findings found."}
+
+## Actual Findings
+
+${actualFindings || "No actual findings found."}
+
+Analyze the findings above and call provide_comparison_results with your assessment.`;
+}
+
+function loadExpectedResults(repoPath: string): Record<string, unknown>[] {
+  const expectedDir = join(repoPath, "expected_results");
+  if (!existsSync(expectedDir)) return [];
+
+  const results: Record<string, unknown>[] = [];
+
+  for (const f of readdirSync(expectedDir).filter((f) => f.endsWith(".json"))) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(expectedDir, f), "utf-8"));
+
+      // Argus format: { vulnerabilities: [...] } with each vuln having name, severity, description, etc.
+      if (parsed?.vulnerabilities && Array.isArray(parsed.vulnerabilities)) {
+        for (const vuln of parsed.vulnerabilities) {
+          results.push({
+            title: vuln.vuln_name || vuln.name || vuln.title || "Unknown",
+            severity: vuln.severity || "HIGH",
+            reason:
+              vuln.description_of_vuln || vuln.description || vuln.reason || "",
+            ...vuln,
+          });
+        }
+      } else if (parsed) {
+        // Standard format: direct object with title, severity, reason
+        results.push(parsed);
+      }
+    } catch {
+      // skip unparseable files
+    }
+  }
+
+  return results;
+}
+
+function loadActualFindings(sessionPath: string): string {
+  const findingsDir = join(sessionPath, "findings");
+  if (!existsSync(findingsDir)) return "No findings directory found.";
+
+  const findings = readdirSync(findingsDir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => {
+      try {
+        const finding = JSON.parse(readFileSync(join(findingsDir, f), "utf-8"));
+        return `### ${finding.title}
+- **Severity:** ${finding.severity}
+- **Endpoint:** ${finding.endpoint || "N/A"}
+- **Category:** ${finding.vulnerabilityClass || finding.category || "N/A"}
+- **Description:** ${finding.description || "N/A"}
+- **Evidence:** ${finding.evidence || "N/A"}`;
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  return findings.length > 0
+    ? findings.join("\n\n")
+    : "No findings were documented.";
+}

package/src/core/agents/specialized/codeAgent/agent.test.ts

@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { superInputs } = vi.hoisted(() => ({
+  superInputs: [] as Array<Record<string, unknown>>,
+}));
+
+// Capture the input CodeAgent hands to the harness constructor so the
+// read-focused tool wiring is asserted without standing up a real agent.
+vi.mock("../../offSecAgent", () => ({
+  OffensiveSecurityAgent: class {
+    constructor(input: Record<string, unknown>) {
+      superInputs.push(input);
+    }
+  },
+}));
+
+import { CodeAgent } from "./agent";
+
+function makeAgent(overrides: Record<string, unknown> = {}) {
+  new CodeAgent({
+    codebasePath: "/tmp/target-project",
+    objective: "find missing auth middleware",
+    model: "claude-sonnet-4-20250514" as never,
+    session: { rootPath: "/tmp/apex-session" } as never,
+    ...overrides,
+  });
+  return superInputs[superInputs.length - 1] as {
+    activeTools: string[];
+    fileWorkspaceRoot?: string;
+  };
+}
+
+describe("CodeAgent stays a read-focused analysis agent", () => {
+  beforeEach(() => {
+    superInputs.length = 0;
+  });
+
+  it("wires the analysis toolset: read, list, grep, execute, whitebox, workspace doc", () => {
+    const { activeTools } = makeAgent();
+    for (const tool of [
+      "read_file",
+      "list_files",
+      "grep",
+      "execute_command",
+      "profile_codebase",
+      "query_whitebox_catalog",
+      "run_code_query",
+      "document_app",
+      "document_endpoint",
+      "web_search",
+      "get_page",
+    ]) {
+      expect(activeTools).toContain(tool);
+    }
+  });
+
+  it("wires no file-mutation, pentest-mutation, or orchestration tools", () => {
+    const { activeTools } = makeAgent();
+    for (const tool of [
+      "create_file",
+      "update_file",
+      "delete_file",
+      "apply_patch",
+      "document_vulnerability",
+      "spawn_pentest_agent",
+      "spawn_coding_agent",
+    ]) {
+      expect(activeTools).not.toContain(tool);
+    }
+  });
+
+  it("does not claim a helper file workspace — analysis only", () => {
+    const input = makeAgent();
+    expect(input.fileWorkspaceRoot).toBeUndefined();
+  });
+
+  it("honors excludeTools and adds the response tool only with a schema", () => {
+    const input = makeAgent({
+      excludeTools: ["document_app", "document_endpoint"],
+      responseSchema: {
+        safeParse: () => ({ success: true, data: undefined }),
+      } as never,
+    });
+    expect(input.activeTools).not.toContain("document_app");
+    expect(input.activeTools).not.toContain("document_endpoint");
+    expect(input.activeTools).toContain("response");
+    expect(input.activeTools).toContain("read_file");
+  });
+});

package/src/core/agents/specialized/codeAgent/agent.ts

@@ -0,0 +1,134 @@
+import { stepCountIs } from "ai";
+import type { z } from "zod";
+import { AgentRuntime } from "../../agentRuntime";
+import { type AgentDefinition, defineAgent } from "../../defineAgent";
+import type { SpecializedAgentInput } from "../../offSecAgent";
+import { CODE_AGENT_SYSTEM_PROMPT } from "./prompts";
+
+const CODE_AGENT_TOOLS: string[] = [
+  "read_file",
+  "list_files",
+  "grep",
+  "execute_command",
+  "profile_codebase",
+  "query_whitebox_catalog",
+  "run_code_query",
+  "run_whitebox_scan",
+  "create_whitebox_candidate",
+  "update_whitebox_candidate",
+  "list_whitebox_candidates",
+  "start_whitebox_job",
+  "poll_whitebox_job",
+  "stop_whitebox_job",
+  "read_whitebox_artifact",
+  "http_request",
+  "document_app",
+  "document_endpoint",
+  // Web search tools — research vulnerable library versions, look up API docs
+  "web_search",
+  "get_page",
+];
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CodeAgentInput<TResult = void> extends SpecializedAgentInput {
+  /** Root path of the codebase to work in (absolute path) */
+  codebasePath: string;
+
+  /** The specific objective for this agent to accomplish */
+  objective: string;
+
+  /**
+   * Zod schema for structured output via the `response` tool.
+   *
+   * When provided, the agent gets a `response` tool that captures
+   * validated structured data. `consume()` then returns `TResult`.
+   */
+  responseSchema?: z.ZodSchema;
+
+  system?: string;
+
+  /**
+   * Tool names to exclude from the default CodeAgent toolset.
+   * Useful for scoping agents to only the tools they need (e.g.
+   * excluding `document_app` from endpoint-discovery agents).
+   */
+  excludeTools?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// CodeAgent
+// ---------------------------------------------------------------------------
+
+/**
+ * A general-purpose coding subagent built on {@link OffensiveSecurityAgent}.
+ *
+ * Uses filesystem tools (`read_file`, `list_files`, `grep`) and
+ * `execute_command` to navigate and analyze a codebase. Designed to be
+ * spawned by a parent agent for a specific, well-defined task.
+ *
+ * @example
+ * ```ts
+ * const agent = new CodeAgent({
+ *   codebasePath: "/app/target-project",
+ *   objective: "Find all API endpoints that lack authentication middleware",
+ *   model: "claude-sonnet-4-20250514",
+ *   session,
+ * });
+ *
+ * await agent.consume({
+ *   onTextDelta: (d) => process.stdout.write(d.text),
+ *   onToolCall:  (d) => console.log(`→ ${d.toolName}`),
+ * });
+ * ```
+ */
+export function codeAgentDefinition<TResult = void>(): AgentDefinition<
+  CodeAgentInput<TResult>,
+  TResult
+> {
+  return defineAgent<CodeAgentInput<TResult>, TResult>({
+    name: "code-agent",
+    role: "worker",
+    system: (opts) => opts.system ?? CODE_AGENT_SYSTEM_PROMPT,
+    activeTools: (opts) => {
+      let activeTools = [...CODE_AGENT_TOOLS];
+      if (opts.excludeTools?.length) {
+        const excluded = new Set(opts.excludeTools);
+        activeTools = activeTools.filter((t) => !excluded.has(t));
+      }
+      if (opts.responseSchema) {
+        activeTools.push("response");
+      }
+      return activeTools;
+    },
+    responseSchema: (opts) => opts.responseSchema,
+    stopWhen: (opts) => opts.stopWhen ?? stepCountIs(10000),
+    prompt: (opts) => buildPrompt(opts.codebasePath, opts.objective),
+  });
+}
+
+export class CodeAgent<TResult = void> extends AgentRuntime<
+  CodeAgentInput<TResult>,
+  TResult
+> {
+  constructor(opts: CodeAgentInput<TResult>) {
+    super(codeAgentDefinition<TResult>(), opts);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+
+function buildPrompt(codebasePath: string, objective: string): string {
+  return `# Objective
+
+${objective}
+
+## Codebase
+- **Path:** ${codebasePath}
+
+Begin now. Orient yourself in the codebase, then accomplish the objective.`;
+}

package/src/core/agents/specialized/codeAgent/prompts.ts

@@ -0,0 +1,48 @@
+export const CODE_AGENT_SYSTEM_PROMPT = `You are an expert coding agent with direct filesystem access. You will be given a specific objective — focus exclusively on completing it.
+
+# Tool Usage Guide
+
+You have the following tools. Use them strategically to accomplish your objective:
+
+## read_file
+Read the contents of any file. You can read the whole file or a specific line range.
+- When a file is large, read it in chunks using startLine / endLine to stay focused.
+- Follow imports and references — when you see an interesting function call, read its source.
+
+## list_files
+List files and directories. Use this to orient yourself in the codebase.
+- Start by listing the project root or relevant subdirectory to understand the structure.
+- Use recursive=true sparingly on targeted subdirectories to avoid flooding context.
+
+## grep
+Search file contents by pattern. This is your most powerful navigation tool.
+- Use it to find function definitions, usages, imports, and references.
+- Use -i for case-insensitive searches.
+- Use --include="*.ext" to narrow to relevant file types.
+- Use -C 3 or -C 5 to get context around matches.
+- Use -rn (default for directories) for recursive search with line numbers.
+- Use -l to get just file paths when you need a broad overview of where something appears.
+
+## execute_command
+Run shell commands when needed.
+- Use for any task that benefits from shell access: build tools, git operations, package managers, linters, etc.
+- Useful for running scripts, checking dependencies, inspecting git history, or any CLI tool.
+
+## Whitebox security tools (when investigating vulnerabilities)
+- **profile_codebase** — summarize languages, manifests, scanners, and repo shape; full JSON is written as a session artifact.
+- **query_whitebox_catalog** — pull focused methodology slices (sinks, scanners, review passes) instead of loading a whole playbook into context.
+- **run_code_query** — batched rg / ast-grep / comby searches with bounded output and artifact logs.
+- **run_whitebox_scan** — run installed scanners when available; triage results before treating them as confirmed issues.
+- **create_whitebox_candidate / update_whitebox_candidate / list_whitebox_candidates** — track hypotheses with explicit state and evidence.
+- **start_whitebox_job / poll_whitebox_job / stop_whitebox_job** — bounded long-running jobs (builds, fuzzers) with logs under the session.
+- **read_whitebox_artifact** — read \`logs/whitebox/\` or \`scratchpad/whitebox/\` artifact paths returned by other tools (or legacy job logs by id).
+
+Prefer catalog + code_query for sink-first work; use candidates to separate unverified ideas from \`document_vulnerability\`. Do not modify the target repo unless the operator asked you to — keep harnesses and scratch output in the session scratchpad.
+
+# Working Approach
+1. **Orient first** — list files and read key entry points to understand the structure before diving in.
+2. **Search, then read** — use grep to locate what you need, then read the relevant files.
+3. **Follow the trail** — trace through imports, function calls, and references to build full understanding.
+4. **Stay focused** — stick to your objective. Don't wander into unrelated areas of the codebase.
+5. **Be thorough** — don't stop at the first match. Make sure you've covered everything relevant to the objective.
+`;