astrocode-workflow 0.1.19 → 0.1.23

package/dist/agents/prompts.d.ts

@@ -1,2 +1,2 @@
 export declare const BASE_ORCH_PROMPT = "You are Astro (Orchestrator) for Astrocode.\n\nMission:\n- Advance a deterministic pipeline: frame \u2192 plan \u2192 spec \u2192 implement \u2192 review \u2192 verify \u2192 close.\n- The SQLite DB is the source of truth. Prefer tools over prose.\n- Never narrate what prompts you received.\n- Keep outputs short; store large outputs as artifacts and reference paths.\n\nOperating rules:\n- Only start new runs when the user explicitly requests implementation, workflow management, or story processing.\n- Answer questions directly when possible without starting workflows.\n- Prefer calling astro_workflow_proceed (step/loop) and astro_status only when actively managing a workflow.\n- Delegate stage work only to the stage subagent matching the current stage.\n- If a stage subagent returns status=blocked, inject the BLOCKED directive and stop.\n- Never delegate from subagents (enforced by permissions).\n- Be discretionary: assess if the user's request requires workflow initiation or just information.\n";
-export declare const BASE_STAGE_PROMPT = "You are an Astro stage subagent.\n\nFollow the latest [SYSTEM DIRECTIVE: ASTROCODE \u2014 STAGE_*] you receive.\n\nOutput exactly in this order:\n1) Baton markdown (short, structured narrative summary)\n2) Valid ASTRO JSON between markers with ALL required fields (do not omit any):\n\n<!-- ASTRO_JSON_BEGIN -->\n{\n  \"schema_version\": 1,\n  \"stage_key\": \"CURRENT_STAGE\",\n  \"status\": \"ok\",\n  \"summary\": \"Brief summary of work done\",\n  \"decisions\": [],\n  \"next_actions\": [],\n  \"tasks\": [],\n  \"files\": [],\n  \"evidence\": [],\n  \"new_stories\": [],\n  \"questions\": [],\n  \"metrics\": {}\n}\n<!-- ASTRO_JSON_END -->\n\nCRITICAL REQUIREMENTS:\n- Include ALL fields shown above (even if empty arrays/objects)\n- stage_key must match the current stage exactly\n- status must be \"ok\", \"blocked\", or \"failed\"\n- summary must be a non-empty string describing the work\n- JSON must be valid syntax and parseable\n- Markers must be exact: <!-- ASTRO_JSON_BEGIN --> and <!-- ASTRO_JSON_END -->\n\nDo not narrate extra text. If blocked, set status=\"blocked\", ask exactly ONE question in questions array, and stop.\n";
+export declare const BASE_STAGE_PROMPT = "You are an Astro stage subagent.\n\n***CRITICAL: Follow the latest [SYSTEM DIRECTIVE: ASTROCODE \u2014 STAGE_*] you receive EXACTLY.***\n\nYour output MUST be in this EXACT format (no deviations):\n\n1) First, a short baton markdown summary (1-3 sentences).\n\n2) Then, immediately after, the ASTRO JSON markers with valid JSON:\n\n<!-- ASTRO_JSON_BEGIN -->\n{\n  \"schema_version\": 1,\n  \"stage_key\": \"CURRENT_STAGE\",\n  \"status\": \"ok\",\n  \"summary\": \"Brief summary\",\n  \"decisions\": [],\n  \"next_actions\": [],\n  \"tasks\": [],\n  \"files\": [],\n  \"evidence\": [],\n  \"new_stories\": [],\n  \"questions\": [],\n  \"metrics\": {}\n}\n<!-- ASTRO_JSON_END -->\n\nMANDATORY RULES:\n- ALL fields above MUST be present (use empty arrays/objects if no data)\n- stage_key MUST be \"CURRENT_STAGE\" (will be replaced)\n- status MUST be \"ok\" unless blocked/failed\n- summary MUST be a string describing the work\n- JSON MUST be valid and parseable\n- Markers MUST be exact as shown\n\nIf blocked, set status=\"blocked\" and put ONE question in questions array. Do not output anything else.\n";

package/dist/agents/prompts.js

@@ -17,18 +17,20 @@ Operating rules:
 `;
 export const BASE_STAGE_PROMPT = `You are an Astro stage subagent.
 
-Follow the latest [SYSTEM DIRECTIVE: ASTROCODE — STAGE_*] you receive.
+***CRITICAL: Follow the latest [SYSTEM DIRECTIVE: ASTROCODE — STAGE_*] you receive EXACTLY.***
 
-Output exactly in this order:
-1) Baton markdown (short, structured narrative summary)
-2) Valid ASTRO JSON between markers with ALL required fields (do not omit any):
+Your output MUST be in this EXACT format (no deviations):
+
+1) First, a short baton markdown summary (1-3 sentences).
+
+2) Then, immediately after, the ASTRO JSON markers with valid JSON:
 
 <!-- ASTRO_JSON_BEGIN -->
 {
   "schema_version": 1,
   "stage_key": "CURRENT_STAGE",
   "status": "ok",
-  "summary": "Brief summary of work done",
+  "summary": "Brief summary",
   "decisions": [],
   "next_actions": [],
   "tasks": [],
@@ -40,13 +42,13 @@ Output exactly in this order:
 }
 <!-- ASTRO_JSON_END -->
 
-CRITICAL REQUIREMENTS:
-- Include ALL fields shown above (even if empty arrays/objects)
-- stage_key must match the current stage exactly
-- status must be "ok", "blocked", or "failed"
-- summary must be a non-empty string describing the work
-- JSON must be valid syntax and parseable
-- Markers must be exact: <!-- ASTRO_JSON_BEGIN --> and <!-- ASTRO_JSON_END -->
+MANDATORY RULES:
+- ALL fields above MUST be present (use empty arrays/objects if no data)
+- stage_key MUST be "CURRENT_STAGE" (will be replaced)
+- status MUST be "ok" unless blocked/failed
+- summary MUST be a string describing the work
+- JSON MUST be valid and parseable
+- Markers MUST be exact as shown
 
-Do not narrate extra text. If blocked, set status="blocked", ask exactly ONE question in questions array, and stop.
+If blocked, set status="blocked" and put ONE question in questions array. Do not output anything else.
 `;

package/dist/shared/paths.js

@@ -42,9 +42,21 @@ export function assertInsideAstro(repoRoot, filePath) {
     const absRepo = path.resolve(repoRoot);
     const abs = path.resolve(filePath);
     const astroRoot = path.resolve(path.join(repoRoot, ".astro"));
+    // Allow writing certain files in the repo root
+    const relPath = path.relative(repoRoot, filePath);
+    const allowedOutside = [
+        "stories.md",
+        "README.md",
+        "CHANGELOG.md",
+        "CONTRIBUTING.md",
+        "LICENSE",
+        ".gitignore"
+    ];
     if (!abs.startsWith(astroRoot + path.sep) && abs !== astroRoot) {
-        const relPath = path.relative(repoRoot, filePath);
-        throw new Error(`Refusing to write outside .astro: ${filePath} (relative: ${relPath}, astroRoot: ${astroRoot})`);
+        // Check if it's an allowed file in repo root
+        if (!allowedOutside.includes(relPath)) {
+            throw new Error(`Refusing to write outside .astro: ${filePath} (relative: ${relPath}, astroRoot: ${astroRoot})`);
+        }
     }
     if (!abs.startsWith(absRepo + path.sep) && abs !== absRepo) {
         throw new Error(`Refusing to write outside repo root: ${filePath}`);

package/dist/tools/workflow.js

@@ -6,6 +6,7 @@ import { buildStageDirective, directiveHash } from "../workflow/directives";
 import { injectChatPrompt } from "../ui/inject";
 import { nowISO } from "../shared/time";
 import { newEventId } from "../state/ids";
+import { debug } from "../shared/log";
 import { createToastManager } from "../ui/toasts";
 // Agent name mapping for case-sensitive resolution
 const STAGE_TO_AGENT_MAP = {
@@ -63,7 +64,7 @@ function agentNameForStage(stage, cfg) {
 function buildDelegationPrompt(opts) {
     const { stageDirective, run_id, stage_key, stage_agent_name } = opts;
     const stageUpper = stage_key.toUpperCase();
-    return [
+    const prompt = [
         `[SYSTEM DIRECTIVE: ASTROCODE — DELEGATE_STAGE_${stageUpper}]`,
         ``,
         `Do this now, in order:`,
@@ -81,6 +82,9 @@ function buildDelegationPrompt(opts) {
         ``,
         `Important: do NOT do any stage work yourself in orchestrator mode.`,
     ].join("\n").trim();
+    // Debug log the delegation prompt to troubleshoot agent output issues
+    debug(`Delegating stage ${stage_key} to agent ${stage_agent_name}`, { prompt_length: prompt.length });
+    return prompt;
 }
 export function createAstroWorkflowProceedTool(opts) {
     const { ctx, config, db, agents } = opts;

package/dist/ui/inject.js

@@ -2,9 +2,11 @@ let isInjecting = false;
 let queuedInjection = null;
 export async function injectChatPrompt(opts) {
     const { ctx, sessionId, text } = opts;
+    // Prefix to clearly indicate source as Astro agent
+    const prefixedText = `[Astro Agent]\n\n${text}`;
     if (isInjecting) {
         // Replace any existing queued injection (keep only latest)
-        queuedInjection = opts;
+        queuedInjection = { ...opts, text: prefixedText };
         return;
     }
     isInjecting = true;
@@ -12,7 +14,7 @@ export async function injectChatPrompt(opts) {
         await ctx.client.session.prompt({
             path: { id: sessionId },
             body: {
-                parts: [{ type: "text", text }],
+                parts: [{ type: "text", text: prefixedText }],
             },
         });
     }
@@ -23,7 +25,7 @@ export async function injectChatPrompt(opts) {
             const next = queuedInjection;
             queuedInjection = null;
             // Schedule next injection asynchronously to prevent recursion
-            setImmediate(() => injectChatPrompt(next));
+            setImmediate(() => injectChatPrompt({ ...queuedInjection, text: prefixedText }));
         }
     }
 }

package/dist/workflow/baton.js

@@ -1,5 +1,6 @@
 import { clampLines, normalizeNewlines, stripCodeFences } from "../shared/text";
 import { z, ZodError } from "zod";
+import { debug } from "../shared/log";
 export const ASTRO_JSON_BEGIN = "<!-- ASTRO_JSON_BEGIN -->";
 export const ASTRO_JSON_END = "<!-- ASTRO_JSON_END -->";
 export const StageKeySchema = z.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]);
@@ -40,28 +41,46 @@ export function parseStageOutputText(text) {
     const norm = normalizeNewlines(text ?? "").trim();
     const beginIdx = norm.indexOf(ASTRO_JSON_BEGIN);
     const endIdx = norm.indexOf(ASTRO_JSON_END);
+    let baton_md = "";
+    let jsonRaw = "";
+    let fallbackUsed = false;
     if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) {
+        // Fallback: if no markers, check if the entire text is JSON
+        try {
+            const parsed = JSON.parse(norm);
+            const astroJson = AstroJsonSchema.parse(parsed);
+            debug("Used JSON fallback parsing (no markers found)", { stage_key: astroJson.stage_key });
+            return {
+                baton_md: "",
+                astro_json: astroJson,
+                astro_json_raw: norm,
+                error: null
+            };
+        }
+        catch (e) {
+            // Not JSON, proceed with marker error
+        }
         return {
             baton_md: norm,
             astro_json: null,
             astro_json_raw: null,
-            error: `Missing ASTRO JSON markers. Expected markers ${ASTRO_JSON_BEGIN} ... ${ASTRO_JSON_END}`,
+            error: `Missing ASTRO JSON markers. Expected markers ${ASTRO_JSON_BEGIN} ... ${ASTRO_JSON_END}. If output is pure JSON, ensure it's wrapped in markers.`,
         };
     }
     const before = norm.slice(0, beginIdx).trim();
-    const jsonRaw = norm.slice(beginIdx + ASTRO_JSON_BEGIN.length, endIdx).trim();
+    jsonRaw = norm.slice(beginIdx + ASTRO_JSON_BEGIN.length, endIdx).trim();
     const after = norm.slice(endIdx + ASTRO_JSON_END.length).trim();
-    const baton = [before, after].filter(Boolean).join("\n\n").trim();
+    baton_md = [before, after].filter(Boolean).join("\n\n").trim();
     try {
         const cleaned = stripCodeFences(jsonRaw).trim();
         const parsed = JSON.parse(cleaned);
         const astroJson = AstroJsonSchema.parse(parsed);
-        return { baton_md: baton, astro_json: astroJson, astro_json_raw: cleaned, error: null };
+        return { baton_md, astro_json: astroJson, astro_json_raw: cleaned, error: null };
     }
     catch (e) {
         if (e instanceof ZodError) {
             return {
-                baton_md: baton,
+                baton_md,
                 astro_json: null,
                 astro_json_raw: jsonRaw,
                 error: `Schema validation failed: ${e.message}. Ensure JSON conforms to ASTRO schema with required fields like stage_key, status, etc.`,

package/dist/workflow/directives.js

@@ -10,6 +10,8 @@ export function buildContinueDirective(opts) {
     const body = clampChars(normalizeNewlines([
         `[SYSTEM DIRECTIVE: ASTROCODE — CONTINUE]`,
         ``,
+        `This directive is injected by the Astro agent to continue the workflow.`,
+        ``,
         `Run: \`${run_id}\`${stage_key ? `  Stage: \`${stage_key}\`` : ""}`,
         ``,
         `Next action: ${next_action}`,
@@ -34,6 +36,8 @@ export function buildBlockedDirective(opts) {
     const body = normalizeNewlines([
         `[SYSTEM DIRECTIVE: ASTROCODE — BLOCKED]`,
         ``,
+        `This directive is injected by the Astro agent indicating the workflow is blocked.`,
+        ``,
         `Run: \`${run_id}\`  Stage: \`${stage_key}\``,
         ``,
         `You are blocked. Ask the user exactly ONE question (below), then stop.`,
@@ -54,6 +58,8 @@ export function buildRepairDirective(opts) {
     const body = normalizeNewlines([
         `[SYSTEM DIRECTIVE: ASTROCODE — REPAIR]`,
         ``,
+        `This directive is injected by the Astro agent after performing a repair pass.`,
+        ``,
         `Astrocode performed a repair pass. Summarize in <= 10 lines and continue.`,
         ``,
         `Repair report:`,
@@ -75,6 +81,8 @@ export function buildStageDirective(opts) {
     const body = clampChars(normalizeNewlines([
         `[SYSTEM DIRECTIVE: ASTROCODE — STAGE_${stageKeyUpper}]`,
         ``,
+        `This directive is injected by the Astro agent to delegate the stage task.`,
+        ``,
         `You are: \`${stage_agent_name}\``,
         `Run: \`${run_id}\``,
         `Story: \`${story_key}\` — ${story_title}`,
@@ -90,7 +98,6 @@ export function buildStageDirective(opts) {
         `     "schema_version": 1,`,
         `     "stage_key": "${stage_key}",`,
         `     "status": "ok",`,
-        `     "summary": "Brief summary of work done",`,
         `     ...`,
         `   }`,
         `   ${"<!-- ASTRO_JSON_END -->"}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrocode-workflow",
-  "version": "0.1.19",
+  "version": "0.1.23",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/agents/prompts.ts

@@ -18,18 +18,20 @@ Operating rules:
 
 export const BASE_STAGE_PROMPT = `You are an Astro stage subagent.
 
-Follow the latest [SYSTEM DIRECTIVE: ASTROCODE — STAGE_*] you receive.
+***CRITICAL: Follow the latest [SYSTEM DIRECTIVE: ASTROCODE — STAGE_*] you receive EXACTLY.***
 
-Output exactly in this order:
-1) Baton markdown (short, structured narrative summary)
-2) Valid ASTRO JSON between markers with ALL required fields (do not omit any):
+Your output MUST be in this EXACT format (no deviations):
+
+1) First, a short baton markdown summary (1-3 sentences).
+
+2) Then, immediately after, the ASTRO JSON markers with valid JSON:
 
 <!-- ASTRO_JSON_BEGIN -->
 {
   "schema_version": 1,
   "stage_key": "CURRENT_STAGE",
   "status": "ok",
-  "summary": "Brief summary of work done",
+  "summary": "Brief summary",
   "decisions": [],
   "next_actions": [],
   "tasks": [],
@@ -41,13 +43,13 @@ Output exactly in this order:
 }
 <!-- ASTRO_JSON_END -->
 
-CRITICAL REQUIREMENTS:
-- Include ALL fields shown above (even if empty arrays/objects)
-- stage_key must match the current stage exactly
-- status must be "ok", "blocked", or "failed"
-- summary must be a non-empty string describing the work
-- JSON must be valid syntax and parseable
-- Markers must be exact: <!-- ASTRO_JSON_BEGIN --> and <!-- ASTRO_JSON_END -->
+MANDATORY RULES:
+- ALL fields above MUST be present (use empty arrays/objects if no data)
+- stage_key MUST be "CURRENT_STAGE" (will be replaced)
+- status MUST be "ok" unless blocked/failed
+- summary MUST be a string describing the work
+- JSON MUST be valid and parseable
+- Markers MUST be exact as shown
 
-Do not narrate extra text. If blocked, set status="blocked", ask exactly ONE question in questions array, and stop.
+If blocked, set status="blocked" and put ONE question in questions array. Do not output anything else.
 `;

package/src/shared/paths.ts

@@ -61,10 +61,25 @@ export function assertInsideAstro(repoRoot: string, filePath: string) {
   const absRepo = path.resolve(repoRoot);
   const abs = path.resolve(filePath);
   const astroRoot = path.resolve(path.join(repoRoot, ".astro"));
+
+  // Allow writing certain files in the repo root
+  const relPath = path.relative(repoRoot, filePath);
+  const allowedOutside = [
+    "stories.md",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    ".gitignore"
+  ];
+
   if (!abs.startsWith(astroRoot + path.sep) && abs !== astroRoot) {
-    const relPath = path.relative(repoRoot, filePath);
-    throw new Error(`Refusing to write outside .astro: ${filePath} (relative: ${relPath}, astroRoot: ${astroRoot})`);
+    // Check if it's an allowed file in repo root
+    if (!allowedOutside.includes(relPath)) {
+      throw new Error(`Refusing to write outside .astro: ${filePath} (relative: ${relPath}, astroRoot: ${astroRoot})`);
+    }
   }
+
   if (!abs.startsWith(absRepo + path.sep) && abs !== absRepo) {
     throw new Error(`Refusing to write outside repo root: ${filePath}`);
   }

package/src/tools/workflow.ts

@@ -9,6 +9,7 @@ import { buildStageDirective, directiveHash } from "../workflow/directives";
 import { injectChatPrompt } from "../ui/inject";
 import { nowISO } from "../shared/time";
 import { newEventId } from "../state/ids";
+import { debug } from "../shared/log";
 import { createToastManager } from "../ui/toasts";
 
 // Agent name mapping for case-sensitive resolution
@@ -79,7 +80,7 @@ function buildDelegationPrompt(opts: {
   const { stageDirective, run_id, stage_key, stage_agent_name } = opts;
   const stageUpper = stage_key.toUpperCase();
 
-  return [
+  const prompt = [
     `[SYSTEM DIRECTIVE: ASTROCODE — DELEGATE_STAGE_${stageUpper}]`,
     ``,
     `Do this now, in order:`,
@@ -97,6 +98,11 @@ function buildDelegationPrompt(opts: {
     ``,
     `Important: do NOT do any stage work yourself in orchestrator mode.`,
   ].join("\n").trim();
+
+  // Debug log the delegation prompt to troubleshoot agent output issues
+  debug(`Delegating stage ${stage_key} to agent ${stage_agent_name}`, { prompt_length: prompt.length });
+
+  return prompt;
 }
 
 import { AgentConfig } from "@opencode-ai/sdk";

package/src/ui/inject.ts

@@ -8,9 +8,12 @@ export async function injectChatPrompt(opts: {
 }) {
   const { ctx, sessionId, text } = opts;
 
+  // Prefix to clearly indicate source as Astro agent
+  const prefixedText = `[Astro Agent]\n\n${text}`;
+
   if (isInjecting) {
     // Replace any existing queued injection (keep only latest)
-    queuedInjection = opts;
+    queuedInjection = { ...opts, text: prefixedText };
     return;
   }
 
@@ -20,7 +23,7 @@ export async function injectChatPrompt(opts: {
     await ctx.client.session.prompt({
       path: { id: sessionId },
       body: {
-        parts: [{ type: "text", text }],
+        parts: [{ type: "text", text: prefixedText }],
       },
     });
   } finally {
@@ -30,7 +33,7 @@ export async function injectChatPrompt(opts: {
       const next = queuedInjection;
       queuedInjection = null;
       // Schedule next injection asynchronously to prevent recursion
-      setImmediate(() => injectChatPrompt(next));
+      setImmediate(() => injectChatPrompt({ ...queuedInjection, text: prefixedText }));
     }
   }
 }

package/src/workflow/baton.ts

@@ -2,6 +2,7 @@ import { tool } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
 import { clampLines, normalizeNewlines, stripCodeFences } from "../shared/text";
 import { z, ZodError } from "zod";
+import { debug } from "../shared/log";
 
 export const ASTRO_JSON_BEGIN = "<!-- ASTRO_JSON_BEGIN -->";
 export const ASTRO_JSON_END = "<!-- ASTRO_JSON_END -->";
@@ -74,30 +75,49 @@ export function parseStageOutputText(text: string): ParsedStageOutput {
   const beginIdx = norm.indexOf(ASTRO_JSON_BEGIN);
   const endIdx = norm.indexOf(ASTRO_JSON_END);
 
+  let baton_md = "";
+  let jsonRaw = "";
+  let fallbackUsed = false;
+
   if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) {
+    // Fallback: if no markers, check if the entire text is JSON
+    try {
+      const parsed = JSON.parse(norm) as unknown;
+      const astroJson = AstroJsonSchema.parse(parsed);
+      debug("Used JSON fallback parsing (no markers found)", { stage_key: astroJson.stage_key });
+      return {
+        baton_md: "",
+        astro_json: astroJson,
+        astro_json_raw: norm,
+        error: null
+      };
+    } catch (e) {
+      // Not JSON, proceed with marker error
+    }
+
     return {
       baton_md: norm,
       astro_json: null,
       astro_json_raw: null,
-      error: `Missing ASTRO JSON markers. Expected markers ${ASTRO_JSON_BEGIN} ... ${ASTRO_JSON_END}`,
+      error: `Missing ASTRO JSON markers. Expected markers ${ASTRO_JSON_BEGIN} ... ${ASTRO_JSON_END}. If output is pure JSON, ensure it's wrapped in markers.`,
     };
   }
 
   const before = norm.slice(0, beginIdx).trim();
-  const jsonRaw = norm.slice(beginIdx + ASTRO_JSON_BEGIN.length, endIdx).trim();
+  jsonRaw = norm.slice(beginIdx + ASTRO_JSON_BEGIN.length, endIdx).trim();
   const after = norm.slice(endIdx + ASTRO_JSON_END.length).trim();
 
-  const baton = [before, after].filter(Boolean).join("\n\n").trim();
+  baton_md = [before, after].filter(Boolean).join("\n\n").trim();
 
   try {
     const cleaned = stripCodeFences(jsonRaw).trim();
     const parsed = JSON.parse(cleaned) as unknown;
     const astroJson = AstroJsonSchema.parse(parsed);
-    return { baton_md: baton, astro_json: astroJson, astro_json_raw: cleaned, error: null };
+    return { baton_md, astro_json: astroJson, astro_json_raw: cleaned, error: null };
   } catch (e) {
     if (e instanceof ZodError) {
       return {
-        baton_md: baton,
+        baton_md,
         astro_json: null,
         astro_json_raw: jsonRaw,
         error: `Schema validation failed: ${e.message}. Ensure JSON conforms to ASTRO schema with required fields like stage_key, status, etc.`,

package/src/workflow/directives.ts

@@ -32,6 +32,8 @@ export function buildContinueDirective(opts: {
       [
         `[SYSTEM DIRECTIVE: ASTROCODE — CONTINUE]`,
         ``,
+        `This directive is injected by the Astro agent to continue the workflow.`,
+        ``,
         `Run: \`${run_id}\`${stage_key ? `  Stage: \`${stage_key}\`` : ""}`,
         ``,
         `Next action: ${next_action}`,
@@ -67,6 +69,8 @@ export function buildBlockedDirective(opts: {
     [
       `[SYSTEM DIRECTIVE: ASTROCODE — BLOCKED]`,
       ``,
+      `This directive is injected by the Astro agent indicating the workflow is blocked.`,
+      ``,
       `Run: \`${run_id}\`  Stage: \`${stage_key}\``,
       ``,
       `You are blocked. Ask the user exactly ONE question (below), then stop.`,
@@ -91,6 +95,8 @@ export function buildRepairDirective(opts: { report_md: string }): BuiltDirectiv
     [
       `[SYSTEM DIRECTIVE: ASTROCODE — REPAIR]`,
       ``,
+      `This directive is injected by the Astro agent after performing a repair pass.`,
+      ``,
       `Astrocode performed a repair pass. Summarize in <= 10 lines and continue.`,
       ``,
       `Repair report:`,
@@ -130,6 +136,8 @@ export function buildStageDirective(opts: {
       [
         `[SYSTEM DIRECTIVE: ASTROCODE — STAGE_${stageKeyUpper}]`,
         ``,
+        `This directive is injected by the Astro agent to delegate the stage task.`,
+        ``,
         `You are: \`${stage_agent_name}\``,
         `Run: \`${run_id}\``,
         `Story: \`${story_key}\` — ${story_title}`,
@@ -145,7 +153,6 @@ export function buildStageDirective(opts: {
         `     "schema_version": 1,`,
         `     "stage_key": "${stage_key}",`,
         `     "status": "ok",`,
-        `     "summary": "Brief summary of work done",`,
         `     ...`,
         `   }`,
         `   ${"<!-- ASTRO_JSON_END -->"}`,