astrocode-workflow 0.0.1

package/src/tools/repair.ts

@@ -0,0 +1,31 @@
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import { withTx } from "../state/db";
+import { repairState, formatRepairReport } from "../workflow/repair";
+import { putArtifact } from "../workflow/artifacts";
+import { nowISO } from "../shared/time";
+
+export function createAstroRepairTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { ctx, config, db } = opts;
+
+  return tool({
+    description: "Repair Astrocode invariants and recover from inconsistent DB state. Writes a repair report artifact.",
+    args: {
+      write_report_artifact: tool.schema.boolean().default(true),
+    },
+    execute: async ({ write_report_artifact }) => {
+      const repoRoot = ctx.directory as string;
+      const report = withTx(db, () => repairState(db, config));
+      const md = formatRepairReport(report);
+
+      if (write_report_artifact) {
+        const rel = `.astro/repair/repair_${nowISO().replace(/[:.]/g, "-")}.md`;
+        const a = putArtifact({ repoRoot, db, run_id: null, stage_key: null, type: "log", rel_path: rel, content: md, meta: { kind: "repair" } });
+        return md + `\n\nReport saved: ${rel} (artifact=${a.artifact_id})`;
+      }
+
+      return md;
+    },
+  });
+}

package/src/tools/run.ts

@@ -0,0 +1,62 @@
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import { abortRun, getActiveRun, getStageRuns, getStory } from "../workflow/state-machine";
+
+export function createAstroRunGetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { db } = opts;
+
+  return tool({
+    description: "Get run details (and stage run statuses). Defaults to active run if run_id omitted.",
+    args: {
+      run_id: tool.schema.string().optional(),
+      include_stage_summaries: tool.schema.boolean().default(false),
+    },
+    execute: async ({ run_id, include_stage_summaries }) => {
+      const active = getActiveRun(db);
+      const rid = run_id ?? active?.run_id;
+      if (!rid) return "No active run.";
+
+      const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(rid) as any;
+      if (!run) throw new Error(`Run not found: ${rid}`);
+
+      const story = getStory(db, run.story_key);
+      const stages = getStageRuns(db, rid);
+
+      const lines: string[] = [];
+      lines.push(`# Run ${rid}`);
+      lines.push(`- Status: **${run.status}**`);
+      lines.push(`- Story: \`${run.story_key}\` — ${story?.title ?? "(missing)"}`);
+      lines.push(`- Current stage: \`${run.current_stage_key ?? "?"}\``);
+
+      lines.push("", "## Stages");
+      for (const s of stages) {
+        lines.push(`- \`${s.stage_key}\` (${s.status})`);
+        if (include_stage_summaries && s.summary_md) {
+          lines.push(`  - summary: ${s.summary_md.split("\n")[0].slice(0, 120)}${s.summary_md.length > 120 ? "…" : ""}`);
+        }
+      }
+
+      return lines.join("\n").trim();
+    },
+  });
+}
+
+export function createAstroRunAbortTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { db } = opts;
+
+  return tool({
+    description: "Abort a run and unlock its story (returns story to approved). Defaults to active run if run_id omitted.",
+    args: {
+      run_id: tool.schema.string().optional(),
+      reason: tool.schema.string().default("aborted by user"),
+    },
+    execute: async ({ run_id, reason }) => {
+      const active = getActiveRun(db);
+      const rid = run_id ?? active?.run_id;
+      if (!rid) return "No active run to abort.";
+      abortRun(db, rid, reason);
+      return `🛑 Aborted run ${rid}. Reason: ${reason}`;
+    },
+  });
+}

package/src/tools/spec.ts

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import path from "node:path";
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import { getAstroPaths, ensureAstroDirs } from "../shared/paths";
+import { nowISO } from "../shared/time";
+import { sha256Hex } from "../shared/hash";
+
+export function createAstroSpecGetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { ctx, config, db } = opts;
+
+  return tool({
+    description: "Get current project spec stored at .astro/spec.md",
+    args: {},
+    execute: async () => {
+      const repoRoot = ctx.directory as string;
+      const paths = getAstroPaths(repoRoot, config.db.path);
+      ensureAstroDirs(paths);
+
+      if (!fs.existsSync(paths.specPath)) return "No spec found at .astro/spec.md (run astro_init or astro_spec_set).";
+      const md = fs.readFileSync(paths.specPath, "utf-8");
+      return md;
+    },
+  });
+}
+
+export function createAstroSpecSetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { ctx, config, db } = opts;
+
+  return tool({
+    description: "Set/replace the project spec at .astro/spec.md and record its hash in the DB.",
+    args: {
+      spec_md: tool.schema.string().min(1),
+    },
+    execute: async ({ spec_md }) => {
+      const repoRoot = ctx.directory as string;
+      const paths = getAstroPaths(repoRoot, config.db.path);
+      ensureAstroDirs(paths);
+
+      fs.writeFileSync(paths.specPath, spec_md);
+      const h = sha256Hex(spec_md);
+      const now = nowISO();
+
+      db.prepare("UPDATE repo_state SET spec_hash_after=?, updated_at=? WHERE id=1").run(h, now);
+
+      return `✅ Spec updated (${path.relative(repoRoot, paths.specPath)}). sha256=${h}`;
+    },
+  });
+}

package/src/tools/stage.ts

@@ -0,0 +1,361 @@
+import path from "node:path";
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import { withTx } from "../state/db";
+import type { StageKey, StageRunRow } from "../state/types";
+import { buildBatonSummary, parseStageOutputText } from "../workflow/baton";
+import { buildContextSnapshot } from "../workflow/context";
+import { putArtifact } from "../workflow/artifacts";
+import { nowISO } from "../shared/time";
+import { getAstroPaths, ensureAstroDirs, toPosix } from "../shared/paths";
+import { failRun, getActiveRun, getStageRuns, startStage, completeRun } from "../workflow/state-machine";
+import { newEventId } from "../state/ids";
+import { insertStory } from "../workflow/story-helpers";
+
+function nextStageKey(pipeline: StageKey[], current: StageKey): StageKey | null {
+  const i = pipeline.indexOf(current);
+  if (i === -1) return null;
+  return pipeline[i + 1] ?? null;
+}
+
+function ensureStageMatches(run: any, stage_key: StageKey) {
+  if (run.current_stage_key && run.current_stage_key !== stage_key) {
+    throw new Error(`Stage mismatch: run.current_stage_key=${run.current_stage_key} but got stage_key=${stage_key}`);
+  }
+}
+
+export function createAstroStageStartTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { config, db } = opts;
+
+  return tool({
+    description: "Start a stage for a run (sets stage_run.status=running). Usually called by astro_workflow_proceed.",
+    args: {
+      run_id: tool.schema.string().optional(),
+      stage_key: tool.schema.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]).optional(),
+      subagent_type: tool.schema.string().optional(),
+      subagent_session_id: tool.schema.string().optional(),
+    },
+    execute: async ({ run_id, stage_key, subagent_type, subagent_session_id }) => {
+      const active = getActiveRun(db);
+      const rid = run_id ?? active?.run_id;
+      if (!rid) throw new Error("No active run and no run_id provided.");
+
+      const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(rid) as any;
+      if (!run) throw new Error(`Run not found: ${rid}`);
+
+      const sk = (stage_key ?? run.current_stage_key) as StageKey;
+      if (!sk) throw new Error("No stage_key provided and run.current_stage_key is null.");
+
+      startStage(db, rid, sk, { subagent_type, subagent_session_id });
+
+      return `🟦 Started stage ${sk} for run ${rid}`;
+    },
+  });
+}
+
+export function createAstroStageCompleteTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { ctx, config, db } = opts;
+
+  return tool({
+    description:
+      "Complete a stage from stage-agent output text. Writes baton artifacts, updates stage_runs, advances pipeline, and can auto-queue split stories.",
+    args: {
+      run_id: tool.schema.string().optional(),
+      stage_key: tool.schema.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]).optional(),
+
+      // Pass FULL stage-agent message text. This tool parses baton + ASTRO JSON markers.
+      output_text: tool.schema.string().min(1),
+
+      allow_new_stories: tool.schema.boolean().default(true),
+      relation_reason: tool.schema.string().default("split from stage output"),
+    },
+    execute: async ({ run_id, stage_key, output_text, allow_new_stories, relation_reason }) => {
+      const repoRoot = ctx.directory as string;
+      const paths = getAstroPaths(repoRoot, config.db.path);
+      ensureAstroDirs(paths);
+
+      const active = getActiveRun(db);
+      const rid = run_id ?? active?.run_id;
+      if (!rid) throw new Error("No active run and no run_id provided.");
+
+      const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(rid) as any;
+      if (!run) throw new Error(`Run not found: ${rid}`);
+
+      const sk = (stage_key ?? run.current_stage_key) as StageKey;
+      if (!sk) throw new Error("No stage_key provided and run.current_stage_key is null.");
+
+      const stageRow = db.prepare("SELECT * FROM stage_runs WHERE run_id=? AND stage_key=?").get(rid, sk) as StageRunRow | undefined;
+      if (!stageRow) throw new Error(`Stage run not found: ${rid}/${sk}`);
+      if (stageRow.status !== "running") {
+        throw new Error(`Stage ${sk} is not running (status=${stageRow.status}). Start it first.`);
+      }
+
+      const parsed = parseStageOutputText(output_text);
+      if (parsed.error || !parsed.astro_json) throw new Error(parsed.error ?? "ASTRO JSON missing");
+
+      if (parsed.astro_json.stage_key !== sk) {
+        throw new Error(`ASTRO JSON stage_key mismatch: expected ${sk}, got ${parsed.astro_json.stage_key}`);
+      }
+
+      // Evidence requirement
+      const evidenceRequired =
+        (sk === "verify" && config.workflow.evidence_required.verify) ||
+        (sk === "implement" && config.workflow.evidence_required.implement);
+
+      if (evidenceRequired && (parsed.astro_json.evidence ?? []).length === 0) {
+        throw new Error(`Evidence is required for stage ${sk} but ASTRO JSON evidence[] is empty.`);
+      }
+
+      const batonSummary = buildBatonSummary({ config, stage_key: sk, astro_json: parsed.astro_json, baton_md: parsed.baton_md });
+
+      const now = nowISO();
+      const pipeline = JSON.parse(run.pipeline_stages_json ?? "[]") as StageKey[];
+      const next = nextStageKey(pipeline, sk);
+
+      const stageDirRel = toPosix(path.join(".astro", "runs", rid, sk));
+      const batonRel = toPosix(path.join(stageDirRel, config.artifacts.baton_filename));
+      const summaryRel = toPosix(path.join(stageDirRel, config.artifacts.baton_summary_filename));
+      const jsonRel = toPosix(path.join(stageDirRel, config.artifacts.baton_json_filename));
+
+      const created: { artifact_id: string; path: string }[] = [];
+
+      const result = withTx(db, () => {
+        // Persist artifacts
+        if (config.artifacts.write_full_baton_md) {
+          const a = putArtifact({
+            repoRoot,
+            db,
+            run_id: rid,
+            stage_key: sk,
+            type: "baton",
+            rel_path: batonRel,
+            content: parsed.baton_md,
+            meta: { stage_key: sk },
+          });
+          created.push({ artifact_id: a.artifact_id, path: batonRel });
+        }
+
+        if (config.artifacts.write_baton_summary_md) {
+          const a = putArtifact({
+            repoRoot,
+            db,
+            run_id: rid,
+            stage_key: sk,
+            type: "summary",
+            rel_path: summaryRel,
+            content: batonSummary,
+            meta: { stage_key: sk },
+          });
+          created.push({ artifact_id: a.artifact_id, path: summaryRel });
+        }
+
+        if (config.artifacts.write_baton_output_json) {
+          const a = putArtifact({
+            repoRoot,
+            db,
+            run_id: rid,
+            stage_key: sk,
+            type: "baton",
+            rel_path: jsonRel,
+            content: JSON.stringify(parsed.astro_json, null, 2),
+            meta: { stage_key: sk, schema_version: parsed.astro_json.schema_version },
+          });
+          created.push({ artifact_id: a.artifact_id, path: jsonRel });
+        }
+
+        // Update stage_runs row
+        db.prepare(
+          "UPDATE stage_runs SET status=?, completed_at=?, updated_at=?, baton_path=?, summary_md=?, output_json=?, error_text=NULL WHERE stage_run_id=?"
+        ).run(
+          parsed.astro_json.status === "ok" ? "completed" : "failed",
+          now,
+          now,
+          batonRel,
+          batonSummary,
+          parsed.astro_json_raw ?? JSON.stringify(parsed.astro_json),
+          stageRow.stage_run_id
+        );
+
+        // stage event
+        db.prepare(
+          "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+        ).run(
+          newEventId(),
+          rid,
+          sk,
+          parsed.astro_json.status === "ok" ? "stage.completed" : parsed.astro_json.status === "blocked" ? "stage.blocked" : "stage.failed",
+          JSON.stringify({ artifacts: created, metrics: parsed.astro_json.metrics ?? {} }),
+          now
+        );
+
+        // Metrics
+        if (parsed.astro_json.metrics && typeof parsed.astro_json.metrics === "object") {
+          const ins = db.prepare(
+            "INSERT INTO workflow_metrics (metric_id, run_id, stage_key, name, value_num, value_text, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)"
+          );
+          for (const [k, v] of Object.entries(parsed.astro_json.metrics)) {
+            const metricId = `metric_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+            if (typeof v === "number") ins.run(metricId, rid, sk, k, v, null, now);
+            else ins.run(metricId, rid, sk, k, null, String(v), now);
+          }
+        }
+
+        // New stories (split)
+        const newStoryKeys: string[] = [];
+        if (allow_new_stories && parsed.astro_json.new_stories?.length) {
+          for (const ns of parsed.astro_json.new_stories) {
+            const key = insertStory(db, { title: ns.title, body_md: ns.body_md ?? "", priority: ns.priority ?? 0, state: "queued" });
+            newStoryKeys.push(key);
+            db.prepare(
+              "INSERT OR IGNORE INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, 'split', ?, ?)"
+            ).run(run.story_key, key, relation_reason, now);
+          }
+        }
+
+        if (parsed.astro_json.status !== "ok") {
+          const err = parsed.astro_json.status === "blocked"
+            ? `blocked: ${(parsed.astro_json.questions?.[0] ?? "needs input")}`
+            : `failed: ${(parsed.astro_json.summary ?? "stage failed")}`;
+          // Mark run failed (also unlocks story)
+          failRun(db, rid, sk, err);
+          return { ok: false as const, next_stage: null as StageKey | null, new_stories: newStoryKeys, error: err };
+        }
+
+        // Advance run.current_stage_key
+        if (next) {
+          db.prepare("UPDATE runs SET current_stage_key=?, updated_at=? WHERE run_id=?").run(next, now, rid);
+        } else {
+          db.prepare("UPDATE runs SET current_stage_key=NULL, updated_at=? WHERE run_id=?").run(now, rid);
+        }
+
+        // If last stage, complete run
+        const stageRuns = getStageRuns(db, rid);
+        const incomplete = stageRuns.find((s) => s.status !== "completed" && s.status !== "skipped");
+        if (!incomplete) {
+          completeRun(db, rid);
+          return { ok: true as const, next_stage: null as StageKey | null, new_stories: newStoryKeys, completed_run: true };
+        }
+
+        return { ok: true as const, next_stage: next, new_stories: newStoryKeys, completed_run: false };
+      });
+
+      const context = buildContextSnapshot({ db, config, run_id: rid });
+
+      const lines: string[] = [];
+      if (result.ok) {
+        lines.push(`✅ Stage ${sk} completed for run ${rid}.`);
+      } else {
+        lines.push(`⛔ Stage ${sk} ended with status ${parsed.astro_json.status} for run ${rid}.`);
+        lines.push(`Reason: ${result.error}`);
+      }
+
+      lines.push(``, `Artifacts:`);
+      for (const a of created) lines.push(`- ${a.path} (id=${a.artifact_id})`);
+
+      if (result.new_stories?.length) {
+        lines.push(``, `New stories queued: ${result.new_stories.map((k) => `\`${k}\``).join(", ")}`);
+      }
+
+      if (result.ok) {
+        if (result.completed_run) {
+          lines.push(``, `🎉 Run completed.`);
+        } else if (result.next_stage) {
+          lines.push(``, `Next stage: \`${result.next_stage}\``);
+        }
+      }
+
+      lines.push(``, `Context snapshot (post-update):`);
+      lines.push(context);
+
+      return lines.join("\n").trim();
+    },
+  });
+}
+
+export function createAstroStageFailTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { db } = opts;
+
+  return tool({
+    description: "Manually fail a stage and mark run failed.",
+    args: {
+      run_id: tool.schema.string().optional(),
+      stage_key: tool.schema.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]).optional(),
+      error_text: tool.schema.string().min(1),
+    },
+    execute: async ({ run_id, stage_key, error_text }) => {
+      const active = getActiveRun(db);
+      const rid = run_id ?? active?.run_id;
+      if (!rid) throw new Error("No active run and no run_id provided.");
+
+      const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(rid) as any;
+      if (!run) throw new Error(`Run not found: ${rid}`);
+
+      const sk = (stage_key ?? run.current_stage_key) as StageKey;
+      if (!sk) throw new Error("No stage_key provided and run.current_stage_key is null.");
+
+      // Update stage_run row too
+      const now = nowISO();
+      const stageRow = db.prepare("SELECT * FROM stage_runs WHERE run_id=? AND stage_key=?").get(rid, sk) as StageRunRow | undefined;
+      if (!stageRow) throw new Error(`Stage run not found: ${rid}/${sk}`);
+
+      withTx(db, () => {
+        db.prepare(
+          "UPDATE stage_runs SET status='failed', completed_at=?, updated_at=?, error_text=? WHERE stage_run_id=?"
+        ).run(now, now, error_text, stageRow.stage_run_id);
+
+        db.prepare(
+          "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, 'stage.failed', ?, ?)"
+        ).run(newEventId(), rid, sk, JSON.stringify({ error_text }), now);
+
+        failRun(db, rid, sk, error_text);
+      });
+
+      return `⛔ Failed stage ${sk} and marked run ${rid} failed: ${error_text}`;
+    },
+  });
+}
+
+export function createAstroStageResetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { db } = opts;
+
+  return tool({
+    description:
+      "Admin: reset a stage (and later stages) back to pending for a run. Re-opens run as running. Use carefully.",
+    args: {
+      run_id: tool.schema.string(),
+      stage_key: tool.schema.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]),
+      note: tool.schema.string().default("reset by user"),
+    },
+    execute: async ({ run_id, stage_key, note }) => {
+      const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(run_id) as any;
+      if (!run) throw new Error(`Run not found: ${run_id}`);
+
+      const now = nowISO();
+      const pipeline = JSON.parse(run.pipeline_stages_json ?? "[]") as StageKey[];
+      const idx = pipeline.indexOf(stage_key);
+      if (idx === -1) throw new Error(`Stage ${stage_key} not in pipeline for run ${run_id}`);
+
+      withTx(db, () => {
+        // Reset selected stage + later stages
+        db.prepare(
+          "UPDATE stage_runs SET status='pending', started_at=NULL, completed_at=NULL, baton_path=NULL, summary_md=NULL, output_json=NULL, error_text=NULL, subagent_session_id=NULL, updated_at=? WHERE run_id=? AND stage_index>=?"
+        ).run(now, run_id, idx);
+
+        // Re-open run
+        db.prepare("UPDATE runs SET status='running', error_text=NULL, completed_at=NULL, current_stage_key=?, updated_at=? WHERE run_id=?").run(stage_key, now, run_id);
+
+        // Re-lock story
+        db.prepare(
+          "UPDATE stories SET state='in_progress', in_progress=1, locked_by_run_id=?, locked_at=COALESCE(locked_at, ?), updated_at=? WHERE story_key=?"
+        ).run(run_id, now, now, run.story_key);
+
+        db.prepare(
+          "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, 'stage.reset', ?, ?)"
+        ).run(newEventId(), run_id, stage_key, JSON.stringify({ note }), now);
+      });
+
+      return `🔄 Reset stage ${stage_key} (and later) for run ${run_id}.`;
+    },
+  });
+}

package/src/tools/status.ts

@@ -0,0 +1,119 @@
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import { decideNextAction, getActiveRun, getStageRuns, getStory } from "../workflow/state-machine";
+
+function statusIcon(status: string): string {
+  switch (status) {
+    case "running":
+      return "🟦";
+    case "completed":
+      return "✅";
+    case "failed":
+      return "⛔";
+    case "aborted":
+      return "🛑";
+    case "created":
+      return "🆕";
+    default:
+      return "⬜";
+  }
+}
+
+function stageIcon(status: string): string {
+  switch (status) {
+    case "completed":
+      return "✅";
+    case "running":
+      return "🟦";
+    case "failed":
+      return "⛔";
+    case "skipped":
+      return "⏭️";
+    default:
+      return "⬜";
+  }
+}
+
+export function createAstroStatusTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { config, db } = opts;
+
+  return tool({
+    description: "Show a compact Astrocode status dashboard: active run/stage, pipeline, story board counts, and next action.",
+    args: {
+      include_board: tool.schema.boolean().default(true),
+      include_recent_events: tool.schema.boolean().default(false),
+    },
+    execute: async ({ include_board, include_recent_events }) => {
+      // Check if database is available
+      if (!db) {
+        return "🔄 Astrocode Status\n\n⚠️ Limited Mode: Database not available\nAstrocode is running with reduced functionality";
+      }
+
+      const active = getActiveRun(db);
+
+      const lines: string[] = [];
+      lines.push(`# Astrocode Status`);
+
+      if (!active) {
+        lines.push(`- Active run: *(none)*`);
+        const next = decideNextAction(db, config);
+        if (next.kind === "idle") lines.push(`- Next: ${next.reason === "no_approved_stories" ? "No approved stories." : "Idle."}`);
+
+        if (include_board) {
+          const counts = db
+            .prepare("SELECT state, COUNT(*) as c FROM stories GROUP BY state ORDER BY state")
+            .all() as Array<{ state: string; c: number }>;
+          lines.push(``, `## Story board`);
+          for (const row of counts) lines.push(`- ${row.state}: ${row.c}`);
+        }
+
+        return lines.join("\n");
+      }
+
+      const story = getStory(db, active.story_key);
+      const stageRuns = getStageRuns(db, active.run_id);
+
+      lines.push(`- Active run: \`${active.run_id}\` ${statusIcon(active.status)} **${active.status}**`);
+      lines.push(`- Story: \`${active.story_key}\` — ${story?.title ?? "(missing)"}  (${story?.state ?? "?"})`);
+      lines.push(`- Current stage: \`${active.current_stage_key ?? "?"}\``);
+
+      lines.push(``, `## Pipeline`);
+      for (const s of stageRuns) {
+        lines.push(`- ${stageIcon(s.status)} \`${s.stage_key}\` (${s.status})`);
+      }
+
+      const next = decideNextAction(db, config);
+      lines.push(``, `## Next`);
+      lines.push(`- ${next.kind}`);
+
+      if (next.kind === "await_stage_completion") {
+        lines.push(`- Awaiting output for stage \`${next.stage_key}\`. When you have it, call **astro_stage_complete** with the stage output text.`);
+      } else if (next.kind === "delegate_stage") {
+        lines.push(`- Need to run stage \`${next.stage_key}\`. Use **astro_workflow_proceed** (or delegate to the matching stage agent).`);
+      } else if (next.kind === "complete_run") {
+        lines.push(`- All stages done. Run can be completed via **astro_workflow_proceed**.`);
+      } else if (next.kind === "failed") {
+        lines.push(`- Run failed at \`${next.stage_key}\`: ${next.error_text}`);
+      }
+
+      if (include_board) {
+        const counts = db
+          .prepare("SELECT state, COUNT(*) as c FROM stories GROUP BY state ORDER BY state")
+          .all() as Array<{ state: string; c: number }>;
+        lines.push(``, `## Story board`);
+        for (const row of counts) lines.push(`- ${row.state}: ${row.c}`);
+      }
+
+      if (include_recent_events) {
+        const evs = db
+          .prepare("SELECT created_at, type, run_id, stage_key FROM events ORDER BY created_at DESC LIMIT 10")
+          .all() as Array<{ created_at: string; type: string; run_id: string | null; stage_key: string | null }>;
+        lines.push(``, `## Recent events`);
+        for (const e of evs) lines.push(`- ${e.created_at} — ${e.type}${e.run_id ? ` (run=${e.run_id})` : ""}${e.stage_key ? ` stage=${e.stage_key}` : ""}`);
+      }
+
+      return lines.join("\n");
+    },
+  });
+}