@sireai/optimus 0.1.7 → 0.1.9

package/embedded-skills/shared/video-keyframe-analyzer/scripts/extract-keyframes.mjs

@@ -0,0 +1,614 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { access, copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+
+const DEFAULT_SAMPLE_FPS = 2;
+const DEFAULT_SCENE_THRESHOLD = 0.18;
+const DEFAULT_CONTACT_FPS = "1,0.5";
+const DEFAULT_TILE = "4x4";
+const DEFAULT_MIN_KEYFRAME_GAP_SECONDS = 0.8;
+const DEFAULT_STATIC_KEEP_SECONDS = 5;
+const DEFAULT_MAX_KEYFRAMES = 24;
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token?.startsWith("--")) {
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      parsed[key] = "true";
+      continue;
+    }
+    parsed[key] = next;
+    index += 1;
+  }
+  return parsed;
+}
+
+function usage() {
+  return [
+    "Usage:",
+    "  extract-keyframes --video <path> [options]",
+    "",
+    "Options:",
+    "  --output-dir <dir>              Explicit output directory. Highest priority",
+    "  --task-root <dir>               Write to <task-root>/.optimus/artifacts/video-keyframes/<video-stem>",
+    "  --artifact-name <name>          Artifact subdirectory name under video-keyframes",
+    "  --sample-fps <n>                Uniform sampled frames FPS. Default: 2",
+    "  --scene-threshold <n>           ffmpeg scene threshold. Default: 0.18",
+    "  --contact-fps <csv>             Contact sheet FPS values. Default: 1,0.5",
+    "  --tile <cols>x<rows>            Contact sheet tile layout. Default: 4x4",
+    "  --min-keyframe-gap <seconds>    De-duplicate nearby scene frames. Default: 0.8",
+    "  --static-keep-seconds <seconds> Preserve tail frame before long static periods end. Default: 5",
+    "  --max-keyframes <n>             Maximum selected keyframes including first/last. Default: 24"
+  ].join("\n");
+}
+
+async function run(command, args, options = {}) {
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", rejectPromise);
+    child.on("close", (code) => {
+      if (code !== 0) {
+        rejectPromise(new Error(`Command failed: ${command} ${args.join(" ")}\n${stderr.trim() || stdout.trim()}`));
+        return;
+      }
+      resolvePromise({ stdout, stderr });
+    });
+  });
+}
+
+async function ensureTool(name) {
+  try {
+    await run("which", [name]);
+  } catch (error) {
+    throw new Error(`Required tool not found: ${name}. Install ffmpeg so both ffmpeg and ffprobe are available.`);
+  }
+}
+
+async function readDuration(videoPath) {
+  const { stdout } = await run("ffprobe", [
+    "-v",
+    "error",
+    "-show_entries",
+    "format=duration",
+    "-of",
+    "default=nw=1:nk=1",
+    videoPath
+  ]);
+  const duration = Number.parseFloat(stdout.trim());
+  if (!Number.isFinite(duration) || duration <= 0) {
+    throw new Error(`Unable to read video duration from ffprobe output: ${stdout.trim()}`);
+  }
+  return duration;
+}
+
+async function extractFrameAt(videoPath, outputPath, timeSeconds) {
+  await run("ffmpeg", [
+    "-y",
+    "-ss",
+    formatSeconds(timeSeconds),
+    "-i",
+    videoPath,
+    "-frames:v",
+    "1",
+    "-q:v",
+    "2",
+    outputPath
+  ]);
+}
+
+async function extractSampledFrames(videoPath, framesDir, sampleFps) {
+  await rm(framesDir, { recursive: true, force: true });
+  await mkdir(framesDir, { recursive: true });
+  await run("ffmpeg", [
+    "-y",
+    "-i",
+    videoPath,
+    "-vf",
+    `fps=${sampleFps}`,
+    "-q:v",
+    "3",
+    join(framesDir, "frame-%04d.jpg")
+  ]);
+  const files = await listJpegs(framesDir);
+  return files.length;
+}
+
+async function extractContactSheet(videoPath, outputPath, fps, tile) {
+  await run("ffmpeg", [
+    "-y",
+    "-i",
+    videoPath,
+    "-vf",
+    `fps=${fps},scale=180:-1,tile=${tile}`,
+    "-frames:v",
+    "1",
+    "-update",
+    "1",
+    outputPath
+  ]);
+}
+
+async function extractSceneFrames(videoPath, sceneDir, threshold, durationSeconds) {
+  await mkdir(sceneDir, { recursive: true });
+  const metadataPath = join(sceneDir, "scene-metadata.txt");
+  try {
+    await run("ffmpeg", [
+      "-y",
+      "-i",
+      videoPath,
+      "-vf",
+      `select='gt(scene,${threshold})',metadata=print:file=${metadataPath}`,
+      "-vsync",
+      "vfr",
+      "-q:v",
+      "2",
+      join(sceneDir, "scene-%04d.jpg")
+    ]);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("Nothing was written") && !message.includes("No filtered frames")) {
+      throw error;
+    }
+  }
+
+  const files = await listJpegs(sceneDir);
+  const times = await readSceneTimes(metadataPath);
+  return files.map((file, index) => ({
+    sourcePath: join(sceneDir, file),
+    timeSeconds: times[index] ?? estimateSceneTime(index, files.length, durationSeconds),
+    reason: "visual_change"
+  }));
+}
+
+async function readSceneTimes(metadataPath) {
+  try {
+    const raw = await readFile(metadataPath, "utf8");
+    const times = [];
+    for (const line of raw.split(/\r?\n/u)) {
+      const match = line.match(/pts_time:([0-9.]+)/u);
+      if (match?.[1]) {
+        const value = Number.parseFloat(match[1]);
+        if (Number.isFinite(value)) {
+          times.push(value);
+        }
+      }
+    }
+    return times;
+  } catch {
+    return [];
+  }
+}
+
+async function buildKeyframes(input) {
+  const keyframesDir = join(input.outputDir, "keyframes");
+  const sceneDir = join(input.outputDir, "scene-candidates");
+  await rm(keyframesDir, { recursive: true, force: true });
+  await rm(sceneDir, { recursive: true, force: true });
+  await mkdir(keyframesDir, { recursive: true });
+
+  const candidates = [];
+  const firstPath = join(keyframesDir, "keyframe-first-source.jpg");
+  await extractFrameAt(input.videoPath, firstPath, 0);
+  candidates.push({
+    sourcePath: firstPath,
+    timeSeconds: 0,
+    reason: "first"
+  });
+
+  const sceneCandidates = dedupeSceneCandidates(
+    await extractSceneFrames(input.videoPath, sceneDir, input.sceneThreshold, input.durationSeconds),
+    input.minKeyframeGapSeconds
+  );
+  const staticTailCandidates = await buildStaticTailCandidates({
+    videoPath: input.videoPath,
+    outputDir: input.outputDir,
+    sceneCandidates,
+    durationSeconds: input.durationSeconds,
+    staticKeepSeconds: input.staticKeepSeconds,
+    minKeyframeGapSeconds: input.minKeyframeGapSeconds
+  });
+  candidates.push(...sceneCandidates, ...staticTailCandidates);
+
+  const lastTime = Math.max(input.durationSeconds - Math.min(0.5, input.durationSeconds / 2), 0);
+  const lastPath = join(keyframesDir, "keyframe-last-source.jpg");
+  await extractFrameAt(input.videoPath, lastPath, lastTime);
+  candidates.push({
+    sourcePath: lastPath,
+    timeSeconds: input.durationSeconds,
+    reason: "last"
+  });
+
+  const selectedCandidates = limitCandidates(
+    sortCandidates(candidates),
+    input.maxKeyframes
+  );
+  const normalized = [];
+  for (const candidate of selectedCandidates) {
+    const sequence = normalized.length + 1;
+    const safeTime = Number.isFinite(candidate.timeSeconds) ? candidate.timeSeconds : 0;
+    const outputName = `keyframe-${String(sequence).padStart(3, "0")}-${String(Math.round(safeTime * 1000)).padStart(6, "0")}ms-${candidate.reason}.jpg`;
+    const outputPath = join(keyframesDir, outputName);
+    if (candidate.sourcePath !== outputPath) {
+      await copyFile(candidate.sourcePath, outputPath);
+    }
+    normalized.push({
+      index: sequence,
+      time_seconds: roundSeconds(safeTime),
+      reason: candidate.reason,
+      path: outputPath
+    });
+  }
+
+  await rm(sceneDir, { recursive: true, force: true });
+  await rm(join(input.outputDir, "static-tail-candidates"), { recursive: true, force: true });
+  await rm(firstPath, { force: true });
+  await rm(lastPath, { force: true });
+  return normalized;
+}
+
+async function buildStaticTailCandidates(input) {
+  if (input.staticKeepSeconds <= 0 || input.sceneCandidates.length === 0) {
+    return [];
+  }
+
+  const staticDir = join(input.outputDir, "static-tail-candidates");
+  await mkdir(staticDir, { recursive: true });
+  const candidates = [];
+  const orderedSceneTimes = input.sceneCandidates
+    .map((candidate) => candidate.timeSeconds)
+    .filter((time) => Number.isFinite(time))
+    .sort((left, right) => left - right);
+  let previousChangeTime = 0;
+  let sequence = 1;
+  for (const sceneTime of orderedSceneTimes) {
+    const gap = sceneTime - previousChangeTime;
+    if (gap >= input.staticKeepSeconds) {
+      const tailTime = Math.max(sceneTime - 0.05, previousChangeTime);
+      if (tailTime - previousChangeTime >= input.minKeyframeGapSeconds) {
+        const outputPath = join(staticDir, `static-tail-${String(sequence).padStart(4, "0")}.jpg`);
+        await extractFrameAt(input.videoPath, outputPath, tailTime);
+        candidates.push({
+          sourcePath: outputPath,
+          timeSeconds: tailTime,
+          reason: "static_tail"
+        });
+        sequence += 1;
+      }
+    }
+    previousChangeTime = sceneTime;
+  }
+
+  return candidates;
+}
+
+function sortCandidates(candidates) {
+  return [...candidates].sort((left, right) => {
+    const leftTime = Number.isFinite(left.timeSeconds) ? left.timeSeconds : Number.POSITIVE_INFINITY;
+    const rightTime = Number.isFinite(right.timeSeconds) ? right.timeSeconds : Number.POSITIVE_INFINITY;
+    if (leftTime !== rightTime) {
+      return leftTime - rightTime;
+    }
+    return reasonPriority(left.reason) - reasonPriority(right.reason);
+  });
+}
+
+function limitCandidates(candidates, maxKeyframes) {
+  if (!Number.isFinite(maxKeyframes) || maxKeyframes <= 0 || candidates.length <= maxKeyframes) {
+    return candidates;
+  }
+
+  const first = candidates.find((candidate) => candidate.reason === "first") ?? candidates[0];
+  const last = [...candidates].reverse().find((candidate) => candidate.reason === "last") ?? candidates[candidates.length - 1];
+  const middle = candidates.filter((candidate) => candidate !== first && candidate !== last);
+  const allowedMiddleCount = Math.max(maxKeyframes - 2, 0);
+  const selectedMiddle = sampleEvenly(middle, allowedMiddleCount);
+  return sortCandidates([first, ...selectedMiddle, last]);
+}
+
+function sampleEvenly(items, count) {
+  if (count <= 0) {
+    return [];
+  }
+  if (items.length <= count) {
+    return items;
+  }
+
+  const selected = [];
+  for (let index = 0; index < count; index += 1) {
+    const sourceIndex = Math.round(index * (items.length - 1) / Math.max(count - 1, 1));
+    selected.push(items[sourceIndex]);
+  }
+  return Array.from(new Set(selected));
+}
+
+function reasonPriority(reason) {
+  switch (reason) {
+    case "first":
+      return 0;
+    case "visual_change":
+      return 1;
+    case "static_tail":
+      return 2;
+    case "last":
+      return 3;
+    default:
+      return 9;
+  }
+}
+
+function dedupeSceneCandidates(candidates, minGapSeconds) {
+  const withTimes = candidates.filter((candidate) => Number.isFinite(candidate.timeSeconds));
+  if (withTimes.length === 0) {
+    return candidates;
+  }
+
+  const selected = [];
+  for (const candidate of withTimes) {
+    const previous = selected[selected.length - 1];
+    if (!previous || candidate.timeSeconds - previous.timeSeconds >= minGapSeconds) {
+      selected.push(candidate);
+    }
+  }
+  return selected;
+}
+
+function estimateSceneTime(index, total, durationSeconds) {
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0 || total <= 0) {
+    return undefined;
+  }
+  return durationSeconds * (index + 1) / (total + 1);
+}
+
+async function buildImageSheetFromPattern(inputDir, outputPath, tile) {
+  const files = await listJpegs(inputDir);
+  if (files.length === 0) {
+    return undefined;
+  }
+  await run("ffmpeg", [
+    "-y",
+    "-pattern_type",
+    "glob",
+    "-i",
+    join(inputDir, "*.jpg"),
+    "-vf",
+    `scale=180:-1,tile=${tile}`,
+    "-frames:v",
+    "1",
+    "-update",
+    "1",
+    outputPath
+  ]);
+  return outputPath;
+}
+
+async function listJpegs(dir) {
+  const entries = await readdir(dir);
+  return entries
+    .filter((entry) => /\.(jpe?g)$/iu.test(entry))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function parsePositiveNumber(value, fallback) {
+  const parsed = Number.parseFloat(value ?? "");
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function parsePositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(value ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+async function resolveDefaultOutputDir(input) {
+  if (input.outputDir) {
+    return resolve(input.outputDir);
+  }
+
+  const artifactName = sanitizeArtifactName(input.artifactName || input.videoStem);
+  if (input.taskRoot) {
+    return join(resolve(input.taskRoot), ".optimus", "artifacts", "video-keyframes", artifactName);
+  }
+
+  const inferredTaskRoot = await findNearestTaskRoot(process.cwd());
+  if (inferredTaskRoot) {
+    return join(inferredTaskRoot, ".optimus", "artifacts", "video-keyframes", artifactName);
+  }
+
+  return resolve(dirname(input.videoPath), `${input.videoStem}-keyframes`);
+}
+
+async function findNearestTaskRoot(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    if (await pathExists(join(current, ".optimus"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+}
+
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sanitizeArtifactName(value) {
+  const normalized = String(value || "video")
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/gu, "-")
+    .replace(/^-+|-+$/gu, "");
+  return normalized || "video";
+}
+
+function parseContactFps(value) {
+  return (value || DEFAULT_CONTACT_FPS)
+    .split(",")
+    .map((item) => Number.parseFloat(item.trim()))
+    .filter((item) => Number.isFinite(item) && item > 0);
+}
+
+function formatSeconds(value) {
+  return Math.max(value, 0).toFixed(3);
+}
+
+function roundSeconds(value) {
+  return Math.round(value * 1000) / 1000;
+}
+
+async function cleanOutputArtifacts(outputDir) {
+  await mkdir(outputDir, { recursive: true });
+  await rm(join(outputDir, "frames"), { recursive: true, force: true });
+  await rm(join(outputDir, "keyframes"), { recursive: true, force: true });
+  await rm(join(outputDir, "scene-candidates"), { recursive: true, force: true });
+  await rm(join(outputDir, "static-tail-candidates"), { recursive: true, force: true });
+  await rm(join(outputDir, "manifest.json"), { force: true });
+  await rm(join(outputDir, "summary.md"), { force: true });
+  await rm(join(outputDir, "contact-keyframes.jpg"), { force: true });
+  for (const file of await readdir(outputDir).catch(() => [])) {
+    if (/^contact-[0-9_]+fps\.jpg$/u.test(file)) {
+      await rm(join(outputDir, file), { force: true });
+    }
+  }
+}
+
+async function writeSummary(outputPath, manifest) {
+  const reasonCounts = manifest.keyframes.reduce((counts, frame) => {
+    counts[frame.reason] = (counts[frame.reason] ?? 0) + 1;
+    return counts;
+  }, {});
+  const lines = [
+    "# Video Keyframe Summary",
+    "",
+    `- Video: ${manifest.video}`,
+    `- Duration: ${manifest.duration_seconds}s`,
+    `- Sample FPS: ${manifest.sampled_frame_fps}`,
+    `- Scene threshold: ${manifest.scene_threshold}`,
+    `- Static keep seconds: ${manifest.static_keep_seconds}`,
+    `- Keyframes: ${manifest.keyframes.length} (${Object.entries(reasonCounts).map(([key, value]) => `${key}=${value}`).join(", ")})`,
+    `- Keyframe sheet: ${manifest.keyframe_sheet ?? "not generated"}`,
+    "",
+    "## Keyframes",
+    "",
+    "| # | Time | Reason | Path |",
+    "|---:|---:|---|---|",
+    ...manifest.keyframes.map((frame) => `| ${frame.index} | ${frame.time_seconds}s | ${frame.reason} | ${frame.path} |`),
+    "",
+    "## Notes",
+    "",
+    "- `visual_change` frames are selected by ffmpeg scene-change detection.",
+    "- `static_tail` frames preserve the state immediately before a long static span ends.",
+    "- First and last frames are always preserved for entry and exit context."
+  ];
+  await writeFile(outputPath, lines.join("\n"), "utf8");
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.video) {
+    console.log(usage());
+    process.exitCode = args.help ? 0 : 1;
+    return;
+  }
+
+  await ensureTool("ffmpeg");
+  await ensureTool("ffprobe");
+
+  const videoPath = resolve(String(args.video));
+  const videoStem = basename(videoPath, extname(videoPath));
+  const outputDir = await resolveDefaultOutputDir({
+    videoPath,
+    videoStem,
+    outputDir: args["output-dir"] ? String(args["output-dir"]) : undefined,
+    taskRoot: args["task-root"] ? String(args["task-root"]) : undefined,
+    artifactName: args["artifact-name"] ? String(args["artifact-name"]) : undefined
+  });
+  const sampleFps = parsePositiveNumber(args["sample-fps"], DEFAULT_SAMPLE_FPS);
+  const sceneThreshold = parsePositiveNumber(args["scene-threshold"], DEFAULT_SCENE_THRESHOLD);
+  const minKeyframeGapSeconds = parsePositiveNumber(args["min-keyframe-gap"], DEFAULT_MIN_KEYFRAME_GAP_SECONDS);
+  const staticKeepSeconds = parsePositiveNumber(args["static-keep-seconds"], DEFAULT_STATIC_KEEP_SECONDS);
+  const maxKeyframes = parsePositiveInteger(args["max-keyframes"], DEFAULT_MAX_KEYFRAMES);
+  const tile = String(args.tile ?? DEFAULT_TILE);
+  const contactFps = parseContactFps(String(args["contact-fps"] ?? DEFAULT_CONTACT_FPS));
+
+  await cleanOutputArtifacts(outputDir);
+
+  const durationSeconds = await readDuration(videoPath);
+  const framesDir = join(outputDir, "frames");
+  const sampledFrameCount = await extractSampledFrames(videoPath, framesDir, sampleFps);
+
+  const contactSheets = [];
+  for (const fps of contactFps) {
+    const label = String(fps).replace(".", "_");
+    const outputPath = join(outputDir, `contact-${label}fps.jpg`);
+    await extractContactSheet(videoPath, outputPath, fps, tile);
+    contactSheets.push(outputPath);
+  }
+
+  const keyframes = await buildKeyframes({
+    videoPath,
+    outputDir,
+    durationSeconds,
+    sceneThreshold,
+    minKeyframeGapSeconds,
+    staticKeepSeconds,
+    maxKeyframes
+  });
+  const keyframeSheet = await buildImageSheetFromPattern(join(outputDir, "keyframes"), join(outputDir, "contact-keyframes.jpg"), tile);
+
+  const manifest = {
+    video: videoPath,
+    duration_seconds: roundSeconds(durationSeconds),
+    output_dir: outputDir,
+    frames_dir: framesDir,
+    sampled_frame_fps: sampleFps,
+    sampled_frame_count: sampledFrameCount,
+    scene_threshold: sceneThreshold,
+    min_keyframe_gap_seconds: minKeyframeGapSeconds,
+    static_keep_seconds: staticKeepSeconds,
+    max_keyframes: maxKeyframes,
+    contact_sheets: contactSheets,
+    keyframe_sheet: keyframeSheet,
+    keyframes,
+    tile
+  };
+  const manifestPath = join(outputDir, "manifest.json");
+  const summaryPath = join(outputDir, "summary.md");
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+  await writeSummary(summaryPath, {
+    ...manifest,
+    summary_path: summaryPath
+  });
+  manifest.summary_path = summaryPath;
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+  console.log(JSON.stringify(manifest, null, 2));
+}
+
+main().catch((error) => {
+  console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

package/embedded-skills/shared/{repo-inspection → video-keyframe-analyzer}/skill.json

@@ -1,5 +1,5 @@
 {
-  "id": "repo-inspection",
+  "id": "video-keyframe-analyzer",
   "level": "shared",
   "version": "1.0.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sireai/optimus",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Optimus Codex-native background task runtime and harness scaffolding.",
   "repository": {
     "type": "git",
@@ -47,6 +47,9 @@
     "start": "node dist/cli/optimus.js start",
     "version": "node dist/cli/optimus.js version",
     "upgrade": "node dist/cli/optimus.js upgrade",
+    "feishu-auth-login": "node dist/cli/optimus.js feishu auth login",
+    "feishu-auth-status": "node dist/cli/optimus.js feishu auth status",
+    "feishu-auth-logout": "node dist/cli/optimus.js feishu auth logout",
     "release:status": "node scripts/release.mjs status",
     "release:prepare": "node scripts/release.mjs prepare",
     "release:preflight": "node scripts/release.mjs preflight",
@@ -94,7 +97,8 @@
     "jira-poll-once": "node dist/integrations/jira/jira-cli.js poll-once",
     "jira-poll-daemon": "node dist/integrations/jira/jira-cli.js poll-daemon",
     "sentry-get-event": "node dist/integrations/sentry/sentry-cli.js get-event",
-    "sentry-submit-event": "node dist/integrations/sentry/sentry-cli.js submit-event"
+    "sentry-submit-event": "node dist/integrations/sentry/sentry-cli.js submit-event",
+    "video-keyframes": "node embedded-skills/shared/video-keyframe-analyzer/scripts/extract-keyframes.mjs"
   },
   "keywords": [
     "optimus",

package/embedded-skills/shared/repo-inspection/SKILL.md

@@ -1,9 +0,0 @@
-# Repo Inspection
-
-Use this skill when the task requires quickly understanding repository layout, module boundaries, entrypoints, or key build and test commands before making changes.
-
-## Workflow
-- Read the task package first and identify the suspected repository area.
-- Inspect repository structure, build files, and task-relevant docs before editing.
-- Summarize the likely execution chain and the files that matter most to the bug.
-- Prefer targeted searches and file reads over broad scans.