ai-agentmanager 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.9.0 (2026-10-31)
+
+- **Intent, spec and plan:** each task agent now has INTENT.md (the request as given, its Jira summary, attachments and who started it; written by AI Agent Manager), SPEC.md (requirements, acceptance criteria, out of scope; the agent writes it before changing code) and PLAN.md (steps it ticks off), next to its brief. **Intent · Spec · Plan** buttons and the split view's Docs menu show them; Explain, the documents and AI review read the spec and plan; **Push & open PR** puts them in the pull request's description (intent in full, spec and plan folded). `"specs": false` in config.json turns the spec and plan instructions off.
+- **Export diagrams:** every drawn diagram has **Copy image** (paste into Slack, a PR comment or a doc), **PNG** and **SVG**; a document with diagrams also downloads as one self-contained **.html**. Diagrams now use SVG text labels so they export as images.
+- **Listen:** **🔊 Listen** reads Explain, the documents and the change walkthrough aloud with the browser's own voices (nothing leaves the device; works on phones). The walkthrough is read change by change, showing each as it's read. Pause, stop and speed (0.85× to 1.75×).
+
 ## 1.8.0 (2026-10-31)
 
 - **Update from your phone:** **Update to …** and **About → Update and restart** now show over remote access too; the install and restart run on the computer and the page reloads when it's back. It installs only the official release, from where this copy came from.

package/README.md

@@ -85,13 +85,13 @@ Runs on macOS and Linux; on Windows, use WSL2. Requires Node 20+, `git`, and the
 
 ```sh
 npm install -g ai-agentmanager          # the latest release
-npm install -g ai-agentmanager@1.8.0    # or a specific one
+npm install -g ai-agentmanager@1.9.0    # or a specific one
 ```
 
 Or from the repository, at a release tag:
 
 ```sh
-git clone --branch v1.8.0 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
+git clone --branch v1.9.0 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
 cd ai-agentmanager-core
 npm install
 npm link            # optional: puts `agentmgr` on your PATH
@@ -111,7 +111,7 @@ npm link
 | Installed with | Update |
 | --- | --- |
 | npm | `npm install -g ai-agentmanager@latest` |
-| A clone at a release tag | `git fetch --tags && git checkout v1.8.0 && npm install` (the tag you want) |
+| A clone at a release tag | `git fetch --tags && git checkout v1.9.0 && npm install` (the tag you want) |
 | A clone of `main` | `git pull && npm install` |
 
 **Check your setup.** `agentmgr doctor` checks Node.js, Claude Code and its sign-in, git, `gh`, the data folder, the daemon's port and Chrome, and says how to fix anything missing.
@@ -331,6 +331,8 @@ The Brief panel's **Share for review** buttons, or `agentmgr doc <agent> <kind>`
 | **Human vs AI** | Your top 5 decisions, each with why it needs you, the stakes, options and what the work suggests, plus a box for your answer. Up to 5 questions the AI answers, each with its confidence, evidence and how to check it. A second model's verdict on each. |
 | **Diagrams** | Diagrams only, for a quick grasp: the problem, the architecture (with what changes highlighted), the design, the data flow (animated) and the key interaction, plus the plan. Drawn from the documents already written and the agent's work. Optional: **Write all** leaves it out. |
 
+Each drawn diagram has **Copy image** (paste it into Slack, a PR comment or a doc), **PNG** and **SVG**, and a document with diagrams also downloads as one **.html** file. **🔊 Listen** reads Explain, documents and the change walkthrough aloud with the browser's own voices; the walkthrough is read change by change, showing each as it goes.
+
 **Human vs AI.** This review takes two separate read-only calls.
 1. **The split.** The agent's engine splits the open questions. *For you to decide* covers judgment calls such as intent, priorities, risk appetite and trade-offs. *Answered by AI* covers reasoning and evaluation: correctness, edge cases, test coverage and what's left.
 2. **The second opinion.** Another model reviews that split against the same context. It marks each AI answer *agrees*, *partly* or *disagrees*, with a correction where needed. It marks each of your questions *keep*, *AI could answer* or *reword*, and lists questions both lists missed.
@@ -387,7 +389,8 @@ Each card has at most **three points of about 12 words each**, so they're easy t
 - **Line comments.** Click **+** next to a line (or its line number) to comment on it, and add an overall comment if you like. **Send to agent** types them into the agent as one message, each with its file, line and the code it is about, and asks it to address them. Comments not sent yet are kept in this browser.
 - **Explain changes** explains each change one by one: a title, what it changes, why (from the request and the conversation), the risk and what to check, in the order a reviewer should read them. Each explanation sits above its hunk, and **◀ / ▶** (or **[** and **]**) step through them, opening folded files on the way. When the agent changes the code afterwards, the page says so and **Explain again** brings it up to date. From the CLI: `agentmgr doc <agent> walkthrough`.
 - **Commit all** commits everything in the worktree, new files included, with your git name and email.
-- **Push & open PR** pushes the branch and opens a pull request with `gh`, against the branch the agent started from (title from your text, or from the commits; **Draft** if you like). With a pull request already open, it pushes to it. The pull request is linked to the agent.
+- **Intent, spec and plan.** Each agent keeps INTENT.md (what was asked, written by AI Agent Manager), SPEC.md (requirements and acceptance criteria, written by the agent before it changes code) and PLAN.md (steps, ticked off as it goes) next to its brief. Open them with **Intent · Spec · Plan** or in the split view's Docs; Explain, the documents and AI review read them too. `"specs": false` in config.json stops asking agents for the spec and plan.
+- **Push & open PR** pushes the branch and opens a pull request with `gh`, against the branch the agent started from (title from your text, or from the commits; **Draft** if you like). Its description carries the intent, and the spec and plan in folded sections. With a pull request already open, it pushes to it. The pull request is linked to the agent.
 
 The same from the API: `GET /api/agents/:id/changes`, `POST …/changes/comments`, `…/changes/commit`, `…/changes/pr`. Plugins can refuse a commit or a pull request (`agent.commit`, `agent.pr`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agentmanager",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Run background coding agents (Claude Code, Codex) per intent, and keep track of them from a web UI, your phone or the CLI",
   "keywords": [
     "claude",

package/public/app.js

@@ -6,6 +6,8 @@ import { touchScroll } from '/touchscroll.js';
 import { openStream, post, REMOTE } from '/transport.js';
 import { attachBox } from '/attach.js';
 import { initSide } from '/side.js';
+import { addTools, download, htmlFile, initExport } from '/export.js';
+import { bindListen, listenHtml, play, speakable, now as speaking, stop as stopSpeaking } from '/speak.js';
 import { initReview } from '/review.js';
 import { initLand, prChips } from '/land.js';
 import { initTriggers } from '/triggers.js';
@@ -169,10 +171,13 @@ const isDark = () => {
   const t = document.documentElement.dataset.theme;
   return t ? t === 'dark' : matchMedia('(prefers-color-scheme: dark)').matches;
 };
+// SVG text labels rather than HTML ones: a diagram then exports to PNG (the browser won't turn
+// HTML-in-SVG into an image).
+const mermaidConfig = () => ({ startOnLoad: false, securityLevel: 'strict', theme: isDark() ? 'dark' : 'default', htmlLabels: false, flowchart: { htmlLabels: false } });
 // Diagrams are drawn in the theme's colors: redraw them when it changes.
 window.addEventListener('agentmgr-theme', () => {
   diagrams.clear();
-  mermaidLib?.initialize({ startOnLoad: false, securityLevel: 'strict', theme: isDark() ? 'dark' : 'default' });
+  mermaidLib?.initialize(mermaidConfig());
   for (const el of document.querySelectorAll('[data-mermaid][data-filled]')) delete el.dataset.filled;
   renderDiagrams(document);
 });
@@ -201,8 +206,7 @@ async function renderDiagrams(root) {
       try {
         if (!mermaidLib) {
           mermaidLib = (await import('/vendor/mermaid/mermaid.esm.min.mjs')).default;
-          const dark = isDark();
-          mermaidLib.initialize({ startOnLoad: false, securityLevel: 'strict', theme: dark ? 'dark' : 'default' });
+          mermaidLib.initialize(mermaidConfig());
         }
         const { svg } = await mermaidLib.render(`mmd-${diagrams.size}-${Date.now()}`, src);
         diagrams.set(src, { svg });
@@ -215,7 +219,10 @@ async function renderDiagrams(root) {
     for (const el of document.querySelectorAll('[data-mermaid]')) {
       if (el.dataset.mermaid !== src || el.dataset.filled) continue;
       el.dataset.filled = '1';
-      if (out.svg) el.innerHTML = out.svg;
+      if (out.svg) {
+        el.innerHTML = out.svg;
+        addTools(el);
+      }
       else el.innerHTML = `<div class="hint">Diagram could not be drawn (${esc(out.error)}). Source:</div><pre>${esc(src)}</pre>`;
     }
   }
@@ -233,7 +240,7 @@ function explainBox(a) {
       ${ex.markdown
         ? `${stale ? '<p class="hint">The brief has changed since this explanation; use <b>Explain again</b> to refresh it.</p>' : ''}
            ${clamp(a, 'explain', md(ex.markdown))}
-           <p class="hint">Explained ${ago(ex.at)}.</p>`
+           <p class="hint explain-foot">Explained ${ago(ex.at)}. ${listenHtml(`explain:${a.id}`, { title: 'Read the explanation aloud' })}</p>`
         : ''}
     </div>`;
   return { button, box };
@@ -263,9 +270,18 @@ const INSIGHT_ICONS = { why: '🎯', what: '📦', how: '🛠', now: '📍' };
 const DOCS = { analysis: 'Analysis', design: 'Design', flow: 'Flow', proposal: 'Proposal', humanai: 'Human vs AI', diagrams: 'Diagrams' };
 // Optional extras that "Write all" leaves out.
 const DOC_EXTRAS = new Set(['diagrams']);
-const DOC_TITLES = { ...DOCS, plan: 'Implementation plan' };
+const DOC_TITLES = { ...DOCS, plan: 'Plan', intent: 'Intent', spec: 'Spec' };
+// The agent's intent, spec and plan files (read from the daemon when opened; kept here by agent and kind).
+const SPEC_KINDS = { intent: 'Intent', spec: 'Spec', plan: 'Plan' };
+const specCache = new Map(); // "<agent>:<kind>" -> { markdown, at }
+const isSpecKind = (a, kind) => Boolean(SPEC_KINDS[kind]) && !(kind === 'plan' && a?.planReview);
+async function loadSpec(agentId, kind) {
+  const r = await api('GET', `/agents/${agentId}/specs/${kind}`).catch(() => null);
+  specCache.set(`${agentId}:${kind}`, { markdown: r?.markdown ?? null, at: r?.updatedAt ?? null, loaded: true });
+}
 /** What the document dialog shows: a stakeholder document, or the agent's plan under review. */
-const docOf = (a, kind) => (kind === 'plan' ? a?.planReview && { markdown: a.planReview.markdown, at: a.planReview.updatedAt } : a?.docs?.[kind]);
+const docOf = (a, kind) =>
+  isSpecKind(a, kind) ? specCache.get(`${a?.id}:${kind}`) : kind === 'plan' ? a?.planReview && { markdown: a.planReview.markdown, at: a.planReview.updatedAt } : a?.docs?.[kind];
 
 const VERDICT = { agree: '✓ Agrees', partly: '≈ Partly agrees', disagree: '✗ Disagrees', keep: '✓ Keep', ai: '🤖 AI could answer', reword: '✎ Reword' };
 const CONFIDENCE = { high: 'High confidence', medium: 'Medium confidence', low: 'Low confidence' };
@@ -336,6 +352,17 @@ function docButtons(a) {
       return `<button class="small doc-btn ${d?.markdown ? 'has' : ''}" data-doc="${k}" ${d?.pending ? 'disabled' : ''}
         title="${k === 'diagrams' ? (d?.markdown ? `Open the diagrams${stale ? ' (the brief changed since)' : ''}` : 'Draw the problem and its solution for a quick grasp: architecture, design, data flow (animated) and the key interaction, diagrams only. Built from the documents already written and the agent\'s work') : d?.markdown ? `Open the ${label.toLowerCase()} document${stale ? ' (the brief changed since)' : ''}` : `Write a ${label.toLowerCase()} document for stakeholders`}">${d?.pending ? `${label}…` : label}${d?.markdown ? (stale ? ' •' : ' ✓') : ''}</button>`;
     })
+    .join('')}</span>${specButtons(a)}`;
+}
+
+/** Intent · Spec · Plan: the files kept for reviewers (and put in the pull request's description). */
+function specButtons(a) {
+  if (!a.specDocs) return '';
+  return `<span class="doc-buttons spec-buttons" title="For reviewers, people and agents: what was asked, what done means, and the plan. Push & open PR puts them in the description">${Object.entries(SPEC_KINDS)
+    .map(([k, label]) => {
+      const at = a.specDocs[k] ?? (k === 'plan' ? a.planReview?.updatedAt : null);
+      return `<button class="small doc-btn ${at ? 'has' : ''}" data-doc="${k}" title="${at ? `Open ${label} (updated ${ago(at)})` : k === 'intent' ? 'Written when the agent is created' : `The agent writes it ${k === 'spec' ? 'before changing code' : 'and keeps it current'}`}">${label}${at ? ' ✓' : ''}</button>`;
+    })
     .join('')}</span>`;
 }
 
@@ -346,7 +373,9 @@ function renderDocDialog() {
   const a = agents.get(docView.agentId);
   const d = docOf(a, docView.kind);
   const label = DOC_TITLES[docView.kind];
-  const plan = docView.kind === 'plan';
+  // The plan under review (approve / send back); otherwise a plain file to read.
+  const plan = docView.kind === 'plan' && Boolean(a?.planReview);
+  const specKind = isSpecKind(a, docView.kind);
   $('#doc-title').textContent = `${label} · ${a?.name ?? ''}`;
   const body = $('#doc-body');
   body.classList.toggle('diagrams-view', docView.kind === 'diagrams');
@@ -355,6 +384,8 @@ function renderDocDialog() {
     body.dataset.rendered = '';
   } else if (d?.error) body.innerHTML = `<p class="error">Couldn't write it: ${esc(d.error)}</p>`;
   else if (plan && !d?.markdown) body.innerHTML = '<p class="hint">The agent is investigating and hasn\'t written its plan yet. You\'ll see it here (and in the inbox) when it has.</p>';
+  else if (specKind && !d?.loaded) body.innerHTML = '<p class="hint">Loading…</p>';
+  else if (specKind && !d?.markdown) body.innerHTML = `<p class="hint">${docView.kind === 'intent' ? 'No intent file for this agent (agents created before 1.9 have none).' : `The agent hasn't written its ${label.toLowerCase()} yet. It writes ${docView.kind === 'spec' ? 'the spec before changing code' : 'the plan and keeps it current'}.`}</p>`;
   else if (d?.markdown) {
     if (body.dataset.rendered !== d.at) {
       body.innerHTML = d.data ? humanAiHtml(d) : docHtml(d.markdown);
@@ -364,10 +395,13 @@ function renderDocDialog() {
   }
   const stale = !plan && d?.markdown && a.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
   const by = d?.writer ? ` by ${d.writer}${d.critique ? `, checked by ${d.critique.label}` : ''}${d.from ? ` from ${d.from.length ? d.from.join(', ') : "the agent's work"}` : ''}` : '';
-  $('#doc-meta').textContent = d?.markdown ? `${plan ? `Plan · ${PLAN_LABEL[a.planReview.status]} · updated` : docView.kind === 'diagrams' ? 'Drawn' : 'Written'} ${ago(d.at)}${by}${stale ? ' · the brief has changed since; Regenerate for the latest' : ''}` : '';
+  $('#doc-meta').textContent = d?.markdown ? `${plan ? `Plan · ${PLAN_LABEL[a.planReview.status]} · updated` : specKind ? 'Updated' : docView.kind === 'diagrams' ? 'Drawn' : 'Written'} ${ago(d.at)}${by}${stale && !specKind ? ' · the brief has changed since; Regenerate for the latest' : ''}${specKind ? ' · goes into the pull request description' : ''}` : '';
   for (const id of ['doc-copy', 'doc-download', 'doc-print']) $(`#${id}`).disabled = !d?.markdown;
-  $('#doc-print').hidden = plan;
-  $('#doc-regen').hidden = plan;
+  // Diagrams: the whole document as one HTML file with every diagram (each also has Copy / PNG / SVG).
+  $('#doc-html').hidden = !/```mermaid/.test(d?.markdown ?? '');
+  $('#doc-listen').innerHTML = d?.markdown && docView.kind !== 'diagrams' ? listenHtml(`doc:${docView.agentId}:${docView.kind}`, { title: 'Read the document aloud' }) : '';
+  $('#doc-print').hidden = plan || specKind;
+  $('#doc-regen').hidden = plan || specKind;
   $('#doc-regen').disabled = Boolean(d?.pending);
   $('#doc-bg').hidden = !d?.pending;
   // Footer: send your answers (Human vs AI), or approve / send back the plan.
@@ -388,7 +422,10 @@ function openDoc(agentId, kind) {
   $('#doc-body').dataset.rendered = '';
   $('#doc-dialog').showModal();
   const a = agents.get(agentId);
-  if (kind !== 'plan' && !a.docs?.[kind]?.markdown && !a.docs?.[kind]?.pending) generateDoc();
+  if (isSpecKind(a, kind)) {
+    specCache.delete(`${agentId}:${kind}`);
+    loadSpec(agentId, kind).then(() => docView?.agentId === agentId && docView.kind === kind && renderDocDialog());
+  } else if (kind !== 'plan' && !a.docs?.[kind]?.markdown && !a.docs?.[kind]?.pending) generateDoc();
   renderDocDialog();
 }
 
@@ -398,6 +435,7 @@ function generateDoc() {
 }
 
 $('#doc-close').onclick = () => {
+  if (speaking()?.id.startsWith('doc:')) stopSpeaking();
   docView = null;
   $('#doc-dialog').close();
 };
@@ -484,6 +522,25 @@ function planRow(a) {
     ${p.status !== 'approved' ? '<button class="small ghost" data-act="plan-skip" title="Stop waiting for review; the agent goes ahead">Skip review</button>' : ''}</div>`;
 }
 $('#doc-print').onclick = () => window.open(`/share.html#${docView.agentId}/${docView.kind}`, '_blank', 'noopener');
+$('#doc-html').onclick = () => {
+  const a = agents.get(docView.agentId);
+  download(htmlFile($('#doc-body'), `${DOC_TITLES[docView.kind]}: ${a?.name ?? ''}`), `${a?.slug ?? 'agent'}-${docView.kind}.html`);
+};
+
+// Diagram export: files named after the agent they belong to.
+initExport({ toast, base: (slot) => (slot.closest('#doc-body') && docView ? agents.get(docView.agentId)?.slug : agents.get(term.agentId)?.slug ?? agents.get(selectedId)?.slug) ?? '' });
+
+// Listening: what each Listen control reads.
+bindListen((id) => {
+  const [what, agentId, kind] = id.split(':');
+  const a = agents.get(agentId);
+  let parts = null;
+  if (what === 'explain') parts = [speakable(a?.explanation?.markdown)];
+  else if (what === 'doc') parts = [speakable(kind === 'explain' ? a?.explanation?.markdown : docOf(a, kind)?.markdown)];
+  else if (what === 'walk') parts = reviewUi.listenParts();
+  else if (what === 'sidewalk') parts = sidePane?.listenParts();
+  if (!parts?.length || !play(id, parts)) toast('Nothing to read aloud here (or this browser has no speech)');
+});
 
 /** Why / What / How / Now as four cards. */
 function insightsBox(a) {
@@ -2120,6 +2177,7 @@ sidePane = initSide({
   codeUi,
   docHtml,
   renderDiagrams,
+  listenHtml,
   mainKind: () => term.kind,
   setMain: (kind) => term.agentId && term.open(term.agentId, kind),
   refit: () => requestAnimationFrame(() => term.refit()),
@@ -2909,6 +2967,10 @@ function upsert(a) {
 /** Views that show one agent's details outside the main render: keep them current. */
 function agentChanged(a) {
   if (a.id === term.agentId) term.renderTabs();
+  // An open intent / spec / plan that the agent just updated: read it again.
+  if (docView?.agentId === a.id && isSpecKind(a, docView.kind) && specCache.get(`${a.id}:${docView.kind}`)?.at !== (a.specDocs?.[docView.kind] ?? null)) {
+    loadSpec(a.id, docView.kind).then(renderDocDialog);
+  }
   reviewUi.agentChanged(a);
   sidePane?.agentChanged(a);
 }

package/public/export.js

@@ -0,0 +1,110 @@
+// Taking diagrams out of the page, for a pull request or Slack: each drawn diagram gets Copy image,
+// PNG and SVG; a whole document of diagrams downloads as one self-contained HTML file. Diagrams are
+// drawn with SVG text labels (not HTML in foreignObject), so they turn into PNGs without the
+// browser refusing a "tainted" canvas.
+
+const TOOLS = `<span class="dg-tools"><button type="button" class="small ghost" data-dg="copy" title="Copy as an image: paste into Slack, a GitHub comment or a doc">Copy image</button><button type="button" class="small ghost" data-dg="png" title="Download as a PNG">PNG</button><button type="button" class="small ghost" data-dg="svg" title="Download as an SVG (sharp at any size)">SVG</button></span>`;
+
+/** Add the export buttons to a drawn diagram slot. */
+export function addTools(slot) {
+  if (slot.querySelector('.dg-tools') || !slot.querySelector('svg')) return;
+  slot.insertAdjacentHTML('afterbegin', TOOLS);
+}
+
+const pageBg = () => getComputedStyle(document.body).backgroundColor || '#ffffff';
+
+/** A standalone copy of a diagram's SVG: sized, namespaced, on the page's background. */
+export function svgText(svg, { background = pageBg() } = {}) {
+  const copy = svg.cloneNode(true);
+  copy.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+  copy.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink');
+  const vb = svg.viewBox?.baseVal;
+  const box = svg.getBoundingClientRect();
+  const w = Math.ceil(vb?.width || box.width || 800);
+  const h = Math.ceil(vb?.height || box.height || 600);
+  copy.setAttribute('width', w);
+  copy.setAttribute('height', h);
+  copy.removeAttribute('style'); // mermaid's max-width would shrink it outside the page
+  if (background) {
+    const bg = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+    Object.entries({ x: vb?.x ?? 0, y: vb?.y ?? 0, width: '100%', height: '100%', fill: background }).forEach(([k, v]) => bg.setAttribute(k, v));
+    if (vb) {
+      bg.setAttribute('width', vb.width);
+      bg.setAttribute('height', vb.height);
+    }
+    copy.insertBefore(bg, copy.firstChild);
+  }
+  return { text: new XMLSerializer().serializeToString(copy), w, h };
+}
+
+/** The diagram as a PNG blob, at twice its size so it stays sharp on retina screens and in PRs. */
+export function pngBlob(svg, scale = 2) {
+  const { text, w, h } = svgText(svg);
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => {
+      const canvas = Object.assign(document.createElement('canvas'), { width: w * scale, height: h * scale });
+      const ctx = canvas.getContext('2d');
+      ctx.scale(scale, scale);
+      ctx.drawImage(img, 0, 0, w, h);
+      canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('Could not make the image'))), 'image/png');
+    };
+    img.onerror = () => reject(new Error('Could not draw the diagram as an image'));
+    img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(text)}`;
+  });
+}
+
+export function download(blob, name) {
+  const link = Object.assign(document.createElement('a'), { href: URL.createObjectURL(blob), download: name });
+  document.body.append(link);
+  link.click();
+  link.remove();
+  setTimeout(() => URL.revokeObjectURL(link.href), 2000);
+}
+
+const slugOf = (s) => String(s || 'diagram').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'diagram';
+
+/** The diagram's name for files: its heading in the document, or "diagram". */
+function nameOf(slot, base) {
+  let el = slot.previousElementSibling;
+  while (el && !/^H[1-4]$/.test(el.tagName)) el = el.previousElementSibling;
+  return `${base ? `${slugOf(base)}-` : ''}${slugOf(el?.textContent)}`;
+}
+
+/** One page with every diagram (and heading) of a rendered document, to keep or attach. */
+export function htmlFile(article, title) {
+  const copy = article.cloneNode(true);
+  copy.querySelectorAll('.dg-tools').forEach((t) => t.remove());
+  copy.querySelectorAll('svg').forEach((svg, i) => {
+    const live = article.querySelectorAll('svg')[i];
+    if (live) svg.outerHTML = svgText(live, { background: null }).text;
+  });
+  const css = `body{font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;max-width:1000px;margin:32px auto;padding:0 16px;color:#1c2330;background:#fff}
+h1{font-size:24px}h2{font-size:18px;margin-top:28px;border-top:1px solid #dde1e7;padding-top:14px}
+.diagram{display:flex;justify-content:center;margin:12px 0;overflow-x:auto}svg{max-width:100%;height:auto}`;
+  const html = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title.replace(/</g, '&lt;')}</title><style>${css}</style></head><body>${copy.innerHTML}</body></html>`;
+  return new Blob([html], { type: 'text/html' });
+}
+
+/** Clicks on any diagram's buttons, wherever it is drawn. `base` names the files (the agent). */
+export function initExport({ toast, base = () => '' }) {
+  document.addEventListener('click', async (e) => {
+    const b = e.target.closest('[data-dg]');
+    if (!b) return;
+    const slot = b.closest('.diagram');
+    const svg = slot?.querySelector('svg');
+    if (!svg) return;
+    const name = nameOf(slot, base(slot));
+    try {
+      if (b.dataset.dg === 'svg') download(new Blob([svgText(svg).text], { type: 'image/svg+xml' }), `${name}.svg`);
+      else if (b.dataset.dg === 'png') download(await pngBlob(svg), `${name}.png`);
+      else {
+        // Safari wants the promise handed over within the click.
+        await navigator.clipboard.write([new ClipboardItem({ 'image/png': pngBlob(svg) })]);
+        toast('Diagram copied as an image: paste it into Slack, a PR comment or a doc');
+      }
+    } catch (err) {
+      toast(b.dataset.dg === 'copy' ? `Couldn't copy (${err.message}); use PNG instead` : `Couldn't export: ${err.message}`, 5000);
+    }
+  });
+}

package/public/index.html

@@ -378,7 +378,9 @@
         <button type="button" id="doc-bg" class="small" hidden title="Close this and keep writing; you'll be told when it's ready">Continue in background</button>
         <button type="button" id="doc-regen" class="small" title="Write it again from the agent's latest work">Regenerate</button>
         <button type="button" id="doc-copy" class="small" title="Copy as Markdown">Copy Markdown</button>
+        <span id="doc-listen"></span>
         <button type="button" id="doc-download" class="small">Download .md</button>
+        <button type="button" id="doc-html" class="small" hidden title="One HTML file with every diagram: open it anywhere, attach it, or print it">Download .html</button>
         <button type="button" id="doc-print" class="small primary" title="Open a print-ready page (Save as PDF)">Print / PDF</button>
         <button type="button" id="doc-close" class="small ghost">Close</button>
       </div>

package/public/review.js

@@ -1,7 +1,8 @@
 // Review screen: an agent's changes file by file, line comments sent back to the agent as one
 // message, and Commit / Push & open PR. Comments not sent yet are kept per agent in this browser.
 // With a walkthrough, each hunk shows its explanation and ◀ / ▶ step through them in reading order.
-import { cardHtml, explainButton, stepOf, walkthroughOf } from './walkthrough.js';
+import { cardHtml, explainButton, listenParts as walkParts, stepOf, walkthroughOf } from './walkthrough.js';
+import { listenHtml, now as speaking, stop as stopSpeaking } from './speak.js';
 
 /** Unified diff -> [{ path, status, binary, hunks: [{ head, lines: [{ t, old, new, text }] }] }] */
 export function parseDiff(text) {
@@ -163,7 +164,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
     const nav = n
       ? `<span class="rv-walk"><button type="button" class="small ghost" data-rv-step="-1" title="Previous change ([)">◀</button><span class="hint">${st.step == null ? `${n} changes` : `${st.step + 1} of ${n}`}</span><button type="button" class="small ghost" data-rv-step="1" title="Next change (])">▶</button></span>`
       : '';
-    return `${nav}${explainButton(w, 'data-rv-explain')}`;
+    return `${nav}${n ? listenHtml(`walk:${st.id}`, { title: 'Hear the changes one by one; each is shown as it is read' }) : ''}${explainButton(w, 'data-rv-explain')}`;
   }
 
   function walkNote() {
@@ -432,6 +433,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
 
   $('#review-close').onclick = () => dlg.close();
   dlg.addEventListener('close', () => {
+    if (speaking()?.id.startsWith('walk:')) stopSpeaking();
     st.id = null;
     st.note = st.msg = st.prTitle = '';
   });
@@ -447,5 +449,13 @@ export function initReview({ api, esc, toast, agents, $ }) {
     render();
   }
 
-  return { open, agentChanged, get openId() { return dlg.open ? st.id : null; } };
+  /** What Listen reads: the summary, then each change still in the diff, shown as it is read. */
+  function listenParts() {
+    const w = walk();
+    if (!w.doc) return [];
+    const ok = new Set(present(w));
+    return walkParts(w.doc.data, (i) => (ok.has(i) ? () => gotoStep(i) : null)).filter((p) => typeof p === 'string' || ok.has(p.i));
+  }
+
+  return { open, agentChanged, listenParts, get openId() { return dlg.open ? st.id : null; } };
 }

package/public/share.js

@@ -24,7 +24,7 @@ async function main() {
   document.title = (d.markdown.match(/^#\s+(.+)$/m)?.[1] ?? `${kind} · ${a.name}`).slice(0, 120);
   if (blocks.length) {
     const mermaid = (await import('/vendor/mermaid/mermaid.esm.min.mjs')).default;
-    mermaid.initialize({ startOnLoad: false, securityLevel: 'strict', theme: 'default' });
+    mermaid.initialize({ startOnLoad: false, securityLevel: 'strict', theme: 'default', htmlLabels: false, flowchart: { htmlLabels: false } });
     for (const el of document.querySelectorAll('.diagram')) {
       try {
         el.innerHTML = (await mermaid.render(`d${el.dataset.i}`, blocks[Number(el.dataset.i)])).svg;

package/public/side.js

@@ -2,10 +2,13 @@
 // pane shows the same agent's Code, its Docs (Diagrams by default) or its Changes explained one by
 // one. On, the tab and the document are remembered in this browser.
 import { parseDiff } from '/review.js';
-import { cardHtml, explainButton, walkthroughOf } from '/walkthrough.js';
+import { cardHtml, explainButton, listenParts as walkParts, walkthroughOf } from '/walkthrough.js';
 
 const DOCS = [
   ['diagrams', 'Diagrams'],
+  ['intent', 'Intent'],
+  ['spec', 'Spec'],
+  ['plan', 'Plan'],
   ['design', 'Design'],
   ['flow', 'Flow'],
   ['analysis', 'Analysis'],
@@ -27,14 +30,23 @@ const pref = {
   },
 };
 
-export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDiagrams, mainKind, setMain, refit }) {
+export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDiagrams, listenHtml, mainKind, setMain, refit }) {
   const pane = $('#side-pane');
   const body = $('#side-body');
   const code = $('#code');
   const codeHome = $('#term-main');
   const st = { on: pref.get('on', '0') === '1', tab: pref.get('tab', 'docs'), doc: pref.get('doc', 'diagrams'), agentId: null, changes: null, sig: '', loading: false };
 
-  const docOf = (a, kind) => (kind === 'explain' ? a?.explanation : a?.docs?.[kind]);
+  // Intent, spec and plan are files the daemon reads on request; the rest live on the agent.
+  const FILES = new Set(['intent', 'spec', 'plan']);
+  const files = new Map(); // "<agent>:<kind>" -> { markdown, at }
+  const docOf = (a, kind) => (FILES.has(kind) ? files.get(`${a?.id}:${kind}`) : kind === 'explain' ? a?.explanation : a?.docs?.[kind]);
+  async function loadFile(kind) {
+    const id = st.agentId;
+    const r = await api('GET', `/agents/${id}/specs/${kind}`).catch(() => null);
+    files.set(`${id}:${kind}`, { markdown: r?.markdown ?? null, at: r?.updatedAt ?? null, loaded: true });
+    if (st.agentId === id && st.doc === kind) renderDocs(true);
+  }
 
   function show() {
     const on = st.on && Boolean(st.agentId);
@@ -56,22 +68,37 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
   // ------------------------------------------------------------ Docs
   function renderDocs(force) {
     const a = agents.get(st.agentId);
-    const d = docOf(a, st.doc);
+    let d = docOf(a, st.doc);
+    // A file that changed on disk (or was never read): read it, then draw.
+    if (FILES.has(st.doc) && (!d || (d.at ?? null) !== (a?.specDocs?.[st.doc] ?? null))) {
+      if (!d?.loading) {
+        files.set(`${st.agentId}:${st.doc}`, { ...d, loading: true });
+        loadFile(st.doc);
+      }
+      d = d?.loaded ? d : null;
+      if (!d) {
+        body.innerHTML = '<p class="hint side-pad">Loading…</p>';
+        return;
+      }
+    }
     const sig = `docs|${st.agentId}|${st.doc}|${d?.at}|${d?.pending}|${d?.error}`;
     if (!force && sig === st.sig) return;
     st.sig = sig;
     const label = DOCS.find(([k]) => k === st.doc)?.[1] ?? st.doc;
     const picker = `<select data-side-doc>${DOCS.map(([k, l]) => `<option value="${k}" ${k === st.doc ? 'selected' : ''}>${l}${docOf(a, k)?.markdown ? ' ✓' : ''}</option>`).join('')}</select>`;
     const stale = d?.markdown && a?.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
-    const action = d?.pending
+    const action = FILES.has(st.doc)
+      ? ''
+      : d?.pending
       ? `<span class="hint">Writing…</span>`
       : `<button type="button" class="small ${d?.markdown ? 'ghost' : 'primary'}" data-side-write>${d?.markdown ? 'Again' : st.doc === 'diagrams' ? 'Draw' : 'Write'}</button>`;
     let content;
     if (d?.pending && !d?.markdown) content = `<p class="hint">Writing the ${esc(label.toLowerCase())} from the agent's work so far…</p>`;
     else if (d?.error && !d?.markdown) content = `<p class="error">Couldn't write it: ${esc(d.error)}</p>`;
     else if (d?.markdown) content = `<div class="md ${st.doc === 'diagrams' ? 'diagrams-view' : ''}">${docHtml(d.markdown)}</div>`;
-    else content = `<p class="hint">No ${esc(label.toLowerCase())} for this agent yet.</p>`;
-    body.innerHTML = `<div class="side-tools">${picker}<span class="spacer"></span>${stale ? '<span class="hint">brief changed since</span>' : ''}${action}</div><div class="side-scroll">${content}</div>`;
+    else content = `<p class="hint">No ${esc(label.toLowerCase())} for this agent yet.${FILES.has(st.doc) && st.doc !== 'intent' ? ' The agent writes it as it works.' : ''}</p>`;
+    const listen = d?.markdown && st.doc !== 'diagrams' ? listenHtml(`doc:${st.agentId}:${st.doc}`, { title: 'Read it aloud' }) : '';
+    body.innerHTML = `<div class="side-tools">${picker}<span class="spacer"></span>${stale ? '<span class="hint">brief changed since</span>' : ''}${listen}${action}</div><div class="side-scroll">${content}</div>`;
     renderDiagrams(body);
   }
 
@@ -107,7 +134,7 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
     const sig = `changes|${st.agentId}|${a?.docs?.walkthrough?.at}|${w.pending}|${w.error}|${st.changes.diffHash}`;
     if (!force && sig === st.sig) return;
     st.sig = sig;
-    const tools = `<div class="side-tools">${explainButton(w, 'data-side-explain')}<span class="spacer"></span><button type="button" class="small ghost" data-side-reload title="Load the changes again">⟳</button></div>`;
+    const tools = `<div class="side-tools">${explainButton(w, 'data-side-explain')}${w.doc ? listenHtml(`sidewalk:${st.agentId}`, { title: 'Hear the changes one by one' }) : ''}<span class="spacer"></span><button type="button" class="small ghost" data-side-reload title="Load the changes again">⟳</button></div>`;
     let content;
     if (st.changes.error) content = `<p class="error">${esc(st.changes.error)}</p>`;
     else if (!st.changes.files.length) content = '<p class="hint">No changes yet.</p>';
@@ -115,7 +142,7 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
     else {
       const list = w.doc.data.changes;
       content = `<p class="hint">${esc(w.doc.data.summary)}${w.stale ? ' <b>The changes moved since this was written.</b>' : ''}</p>${list
-        .map((c, i) => `<section class="sd-step"><div class="sd-file"><code>${esc(c.file)}</code></div>${cardHtml(c, i, list.length, esc)}${hunkHtml(c.file, c.head)}</section>`)
+        .map((c, i) => `<section class="sd-step" id="sd-step-${i}"><div class="sd-file"><code>${esc(c.file)}</code></div>${cardHtml(c, i, list.length, esc)}${hunkHtml(c.file, c.head)}</section>`)
         .join('')}`;
     }
     body.innerHTML = `${tools}<div class="side-scroll">${content}</div>`;
@@ -182,6 +209,17 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
       }
     },
     showing: (tab) => st.on && Boolean(st.agentId) && st.tab === tab,
+    /** What Listen reads in Changes: each change, scrolled to and marked as it is read. */
+    listenParts() {
+      const w = walkthroughOf(agents.get(st.agentId), st.changes?.diffHash);
+      if (!w.doc) return [];
+      return walkParts(w.doc.data, (i) => () => {
+        body.querySelectorAll('.sd-step.current').forEach((el) => el.classList.remove('current'));
+        const el = body.querySelector(`#sd-step-${i}`);
+        el?.classList.add('current');
+        el?.scrollIntoView({ block: 'start', behavior: 'smooth' });
+      });
+    },
     agentChanged(a) {
       if (!st.on || a.id !== st.agentId) return;
       if (st.tab === 'docs') renderDocs(false);

package/public/speak.js

@@ -0,0 +1,171 @@
+// Listening instead of reading: Explain, the documents and the change walkthrough read aloud with
+// the browser's own speech (nothing leaves the device; it works on phones). Text goes in short
+// pieces, since some browsers stop a long utterance partway. One thing plays at a time.
+
+const RATES = [0.85, 1, 1.25, 1.5, 1.75];
+const RATE_KEY = 'agentmgr.speechRate';
+
+export const canSpeak = () => typeof window !== 'undefined' && 'speechSynthesis' in window && 'SpeechSynthesisUtterance' in window;
+
+/** Markdown as something to say: no code, diagrams, links' addresses or markup. */
+export function speakable(markdown) {
+  return String(markdown ?? '')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/https?:\/\/\S+/g, 'a link')
+    .replace(/^#{1,6}\s+(.*)$/gm, '$1.')
+    .replace(/^\s*[-*+]\s+/gm, '')
+    .replace(/^\s*\d+\.\s+/gm, '')
+    .replace(/[*_~>|]/g, '')
+    .replace(/\.\.+/g, '.')
+    .replace(/[ \t]+/g, ' ')
+    .trim();
+}
+
+/** Text in pieces of a few sentences (under ~220 characters), on paragraph and sentence breaks. */
+export function pieces(text, max = 220) {
+  const out = [];
+  for (const para of String(text).split(/\n\s*\n|\n/)) {
+    const sentences = para.match(/[^.!?]+[.!?]*\s*/g) ?? [];
+    let cur = '';
+    for (const s of sentences) {
+      if ((cur + s).length > max && cur) {
+        out.push(cur.trim());
+        cur = '';
+      }
+      cur += s;
+    }
+    if (cur.trim()) out.push(cur.trim());
+  }
+  return out.filter((p) => /\w/.test(p));
+}
+
+let session = null; // { id, parts: [{ text, onStart }], i, paused, onEnd, onState }
+
+function rate() {
+  try {
+    const r = Number(localStorage.getItem(RATE_KEY));
+    return RATES.includes(r) ? r : 1;
+  } catch {
+    return 1;
+  }
+}
+
+function playNext() {
+  const s = session;
+  if (!s) return;
+  if (s.i >= s.parts.length) return stop(true);
+  const part = s.parts[s.i];
+  const u = new SpeechSynthesisUtterance(part.text);
+  u.rate = rate();
+  u.onstart = () => part.onStart?.();
+  u.onend = () => {
+    if (session !== s || s.paused) return;
+    s.i++;
+    playNext();
+  };
+  u.onerror = (e) => {
+    if (session !== s || e.error === 'interrupted' || e.error === 'canceled') return;
+    stop(false);
+  };
+  speechSynthesis.speak(u);
+}
+
+/**
+ * Play `parts` (strings, or { text, onStart } to follow along, e.g. highlight a change) under `id`.
+ * `onState(state)` hears 'playing' | 'paused' | 'stopped'.
+ */
+export function play(id, parts, { onState, onEnd } = {}) {
+  stop(false);
+  if (!canSpeak()) return false;
+  const list = parts.flatMap((p) => {
+    const text = typeof p === 'string' ? p : p.text;
+    const chunks = pieces(text);
+    return chunks.map((c, k) => ({ text: c, onStart: k === 0 && typeof p !== 'string' ? p.onStart : null }));
+  });
+  if (!list.length) return false;
+  session = { id, parts: list, i: 0, paused: false, onState, onEnd };
+  onState?.('playing');
+  notify();
+  playNext();
+  return true;
+}
+
+export function pause() {
+  if (!session || session.paused) return;
+  session.paused = true;
+  // Cancel rather than speechSynthesis.pause(): pausing is unreliable on Chrome and iOS. Resume
+  // restarts the piece that was playing.
+  speechSynthesis.cancel();
+  session.onState?.('paused');
+  notify();
+}
+
+export function resume() {
+  if (!session?.paused) return;
+  session.paused = false;
+  session.onState?.('playing');
+  notify();
+  playNext();
+}
+
+export function stop(finished = false) {
+  const s = session;
+  session = null;
+  if (canSpeak()) speechSynthesis.cancel();
+  if (s) {
+    s.onState?.('stopped');
+    if (finished) s.onEnd?.();
+    notify();
+  }
+}
+
+/** What is playing: { id, paused } or null. */
+export const now = () => (session ? { id: session.id, paused: session.paused } : null);
+
+export function cycleRate() {
+  const next = RATES[(RATES.indexOf(rate()) + 1) % RATES.length];
+  try {
+    localStorage.setItem(RATE_KEY, String(next));
+  } catch {}
+  notify();
+  return next;
+}
+export const rateLabel = () => `${rate()}×`;
+
+// Buttons anywhere on the page redraw themselves from this.
+const listeners = new Set();
+export const onChange = (fn) => listeners.add(fn);
+const notify = () => listeners.forEach((fn) => fn(now()));
+
+/**
+ * A Listen control for `id`: 🔊 Listen, or ⏸ / ▶ with ■ and the speed while that id plays.
+ * Clicks are handled by `bindListen`; `data-say` names what to read.
+ */
+export function listenHtml(id, { title = 'Read it aloud' } = {}) {
+  if (!canSpeak()) return '';
+  const cur = now();
+  if (cur?.id !== id) return `<span class="say" data-say="${id}"><button type="button" class="small ghost" data-say-act="play" title="${title}">🔊 Listen</button></span>`;
+  return `<span class="say on" data-say="${id}"><button type="button" class="small" data-say-act="${cur.paused ? 'resume' : 'pause'}" title="${cur.paused ? 'Resume' : 'Pause'}">${cur.paused ? '▶' : '⏸'}</button><button type="button" class="small ghost" data-say-act="stop" title="Stop">■</button><button type="button" class="small ghost" data-say-act="rate" title="Speed">${rateLabel()}</button></span>`;
+}
+
+/** Handle Listen controls: `start(id)` begins playing that id (it knows what to read). */
+export function bindListen(start) {
+  document.addEventListener('click', (e) => {
+    const b = e.target.closest('[data-say-act]');
+    if (!b) return;
+    const id = b.closest('[data-say]').dataset.say;
+    const act = b.dataset.sayAct;
+    if (act === 'play') start(id);
+    else if (act === 'pause') pause();
+    else if (act === 'resume') resume();
+    else if (act === 'stop') stop(false);
+    else if (act === 'rate') cycleRate();
+  });
+  // Keep every visible control in step with what is playing.
+  onChange(() => {
+    for (const el of document.querySelectorAll('[data-say]')) el.outerHTML = listenHtml(el.dataset.say);
+  });
+}

package/public/style.css

@@ -894,3 +894,15 @@ form.dropping { outline: 2px dashed var(--accent, #6b8cff); outline-offset: 4px;
 .menu-theme .seg { display: inline-flex; border: 1px solid var(--border); border-radius: 6px; overflow: hidden; margin-left: auto; }
 .menu-theme .seg button { border: 0; border-radius: 0; padding: 3px 9px; font-size: 12px; background: transparent; }
 .menu-theme .seg button.on { background: var(--accent); color: var(--accent-text); }
+
+/* Diagram export buttons: on each drawn diagram, shown on hover (always on touch screens). */
+.diagram { position: relative; }
+.dg-tools { position: absolute; top: 6px; right: 6px; display: flex; gap: 4px; opacity: 0; transition: opacity .15s; z-index: 1; }
+.diagram:hover .dg-tools, .diagram:focus-within .dg-tools { opacity: 1; }
+@media (hover: none) { .dg-tools { opacity: 1; position: static; justify-content: flex-end; margin-bottom: 4px; } }
+.dg-tools button { background: var(--panel); }
+/* Listen controls. */
+.say { display: inline-flex; gap: 4px; align-items: center; vertical-align: middle; }
+.say.on button:first-child { min-width: 30px; }
+.explain-foot { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.sd-step.current { box-shadow: 0 0 0 2px var(--accent, #6b8cff); }

package/public/walkthrough.js

@@ -34,3 +34,19 @@ export function explainButton(w, attrs = 'data-wt-explain') {
   return `<button type="button" class="small ${w.doc && !w.stale ? 'ghost' : 'primary'}" ${attrs} ${w.pending ? 'disabled' : ''}
     title="Explain each change one by one: what, why, the risk and what to check, in the order to read them (a separate one-off call; the agent isn't interrupted)">${label}</button>`;
 }
+
+/** What Listen reads for a walkthrough: the summary, then each change; `follow(i)` runs as change i starts. */
+export function listenParts(data, follow = () => null) {
+  const n = data.changes.length;
+  return [
+    data.summary ? `${data.summary} ${n} change${n === 1 ? '' : 's'} to go through.` : `${n} changes to go through.`,
+    ...data.changes.map((c, i) => ({
+      i,
+      text: c.unexplained ? `Change ${i + 1} of ${n}, in ${spokenFile(c.file)}, has no explanation.` : `Change ${i + 1} of ${n}: ${c.title}. In ${spokenFile(c.file)}. ${c.what} ${c.why && c.why !== 'Not stated' ? `Why: ${c.why}` : ''} Risk: ${c.risk}. ${c.check ? `Check: ${c.check}` : ''}`,
+      onStart: follow(i),
+    })),
+  ];
+}
+
+/** "src/server/auth.js" read as "auth.js". */
+const spokenFile = (f) => String(f).split('/').pop();

package/src/brief.js

@@ -654,3 +654,82 @@ export function loadPlanFile(agentId, prev) {
   if (prev && prev.mtimeMs === st.mtimeMs) return null;
   return { markdown: fs.readFileSync(planPath(agentId), 'utf8').slice(0, 200_000), mtimeMs: st.mtimeMs, updatedAt: st.mtime.toISOString() };
 }
+
+// ------------------------------------------------------------------ intent, spec and plan
+
+// Three files per agent, next to the brief, for reviewers (people, other agents, AI review):
+//   INTENT.md - what was asked, written by AI Agent Manager when the agent is created
+//   SPEC.md   - what done means (requirements, acceptance criteria), written by the agent first
+//   PLAN.md   - how it gets there, step by step, kept by the agent (the plan review uses it too)
+// Push & open PR puts them in the pull request's description.
+export const INTENT_FILE = 'INTENT.md';
+export const SPEC_FILE = 'SPEC.md';
+export const intentPath = (agentId) => path.join(briefDir(agentId), INTENT_FILE);
+export const specPath = (agentId) => path.join(briefDir(agentId), SPEC_FILE);
+export const SPEC_DOCS = { intent: intentPath, spec: specPath, plan: planPath };
+
+/** INTENT.md: the request as given, and where it came from. */
+export function intentMarkdown(agent) {
+  const by = agent.startedBy ? 'the assistant' : agent.trigger ? (agent.trigger.source === 'github' ? 'a labeled GitHub issue' : 'a webhook') : agent.playbook ? `the playbook ${agent.playbook.name}` : agent.team ? `team ${agent.team.id} (${agent.team.role})` : agent.raceId ? `race ${agent.raceId}` : 'you';
+  const out = [`# Intent: ${agent.name}`, ''];
+  if (agent.synopsis?.text) out.push(`**${agent.synopsis.source === 'jira' ? `${agent.synopsis.key}: ` : ''}${agent.synopsis.text}**`, '');
+  out.push('## Request', '', agent.intent || '(none)', '');
+  const ctx = [
+    `- Started by: ${by}${agent.trigger?.url ? ` (${agent.trigger.url})` : ''}`,
+    agent.repo || agent.requestedDir ? `- Where: ${agent.repo || agent.requestedDir}${agent.base ? ` (from ${agent.base})` : ''}` : null,
+    agent.engine ? `- Engine: ${agent.engine}${agent.model ? ` (${agent.model})` : ''}` : null,
+    `- Created: ${agent.createdAt}`,
+  ].filter(Boolean);
+  out.push('## Context', '', ...ctx, '');
+  return out.join('\n');
+}
+
+/** The agent's instructions for SPEC.md and PLAN.md (the plan only when the plan review isn't on). */
+export const specPrompt = (specFile, planFile, { withPlan = true } = {}) =>
+  `Before you change any code, write a short spec of the task to ${specFile} (Markdown), so reviewers (people and other agents) ` +
+  'can check the work against it:\n# Spec: <short name>\n## Requirements\nWhat must be true when it is done, as a list.\n' +
+  '## Acceptance criteria\nHow each requirement is checked: a command, a test or an observable behavior.\n## Out of scope\n## Open questions\n' +
+  (withPlan
+    ? `Then write your plan to ${planFile}: "# Plan: <short name>", then "## Steps" as a task list ("- [ ]" to do, "- [x]" done), ` +
+      'small enough to check, and "## Files to change". Keep both current: tick steps as you finish them, and update the spec ' +
+      'if the requirements change (say why). Do not stop to wait for approval; carry on with the work. '
+    : 'Keep it current if the requirements change (say why). ') +
+  'Both files are outside the repository: never copy them into the repo or commit them.';
+
+/** One of the three (intent, spec, plan): its Markdown and when it changed, or null. */
+export function readSpecDoc(agentId, name) {
+  const file = SPEC_DOCS[name]?.(agentId);
+  if (!file) return null;
+  try {
+    const st = fs.statSync(file);
+    return { name, path: file, markdown: fs.readFileSync(file, 'utf8').slice(0, 200_000), updatedAt: st.mtime.toISOString() };
+  } catch {
+    return null;
+  }
+}
+
+/** Which of the three exist, and when they changed (for the page's buttons). */
+export function specDocsInfo(agentId) {
+  const out = {};
+  for (const [name, fn] of Object.entries(SPEC_DOCS)) {
+    try {
+      out[name] = fs.statSync(fn(agentId)).mtime.toISOString();
+    } catch {}
+  }
+  return out;
+}
+
+/** The pull request description's sections: the intent in full, the spec and plan folded. */
+export function prSections(agentId, read = (n) => readSpecDoc(agentId, n)?.markdown) {
+  const doc = (n) => read(n)?.trim();
+  // Demote the files' own headings under the description's.
+  const demote = (md) => md.replace(/^(#{1,4}) /gm, '#$1 ').replace(/^## (Intent|Spec|Plan): .*\n+/m, '');
+  const parts = [];
+  const intent = doc('intent');
+  if (intent) parts.push('## Intent', '', demote(intent), '');
+  for (const [name, label] of [['spec', 'Spec'], ['plan', 'Plan']]) {
+    const md = doc(name);
+    if (md) parts.push(`<details><summary><b>${label}</b></summary>`, '', demote(md), '', '</details>', '');
+  }
+  return parts.length ? [...parts, '<sub>Intent, spec and plan kept by AI Agent Manager.</sub>'].join('\n') : '';
+}

package/src/manager.js

@@ -29,6 +29,12 @@ import {
   parseJsonReply,
   loadPlanFile,
   planApprovedPrompt,
+  intentMarkdown,
+  intentPath,
+  readSpecDoc,
+  specDocsInfo,
+  specPath,
+  specPrompt,
   planPath,
   planReviewPrompt,
 } from './brief.js';
@@ -336,6 +342,8 @@ export class AgentManager extends EventEmitter {
     const prs = Object.values(agent.prs ?? {});
     return {
       ...agent,
+      // Intent, spec and plan files that exist, with when each changed (task agents).
+      ...(NO_REPO.has(agent.kind) ? {} : { specDocs: specDocsInfo(agent.id) }),
       results: this.results(agent, rt, prs),
       priority: agent.priority ?? 2,
       activeAt: this.activeAt(agent, rt),
@@ -675,6 +683,7 @@ export class AgentManager extends EventEmitter {
     this.store.put(agent);
     this.registerProject(agent);
     this.changed(agent);
+    this.writeIntent(agent.id);
     if (issue) this.fetchSynopsis(agent.id).catch(() => {});
 
     this.plugins.emit('agent.created', { agent: this.auditView(agent) });
@@ -701,9 +710,27 @@ export class AgentManager extends EventEmitter {
       synopsis: { text: summary, source: 'jira', key: issue.key },
       ...(bug && !bug.title ? { bugs: { ...cur.bugs, [issue.key]: { ...bug, title: summary } } } : {}),
     });
+    this.writeIntent(cur.id);
     return summary;
   }
 
+  /** INTENT.md for a task agent: the request as given and where it came from (see brief.js). */
+  writeIntent(id) {
+    const agent = this.store.get(id);
+    if (!agent || NO_REPO.has(agent.kind)) return;
+    try {
+      fs.mkdirSync(briefDir(id), { recursive: true });
+      fs.writeFileSync(intentPath(id), intentMarkdown(agent));
+    } catch {}
+  }
+
+  /** One of an agent's intent, spec and plan files. */
+  specDoc(ref, name) {
+    const agent = this.mustGet(ref);
+    if (!['intent', 'spec', 'plan'].includes(name)) throw Object.assign(new Error('Unknown file (intent, spec or plan)'), { status: 400 });
+    return readSpecDoc(agent.id, name) ?? { name, markdown: null };
+  }
+
   /** Fill in summaries still missing (after Jira settings change); returns how many it found. */
   async refreshSynopses() {
     let found = 0;
@@ -983,6 +1010,13 @@ export class AgentManager extends EventEmitter {
       prompts.push(briefPrompt(path.join(dir, path.basename(briefPath(agent.id)))));
       if (this.config.inbox !== false) prompts.push(questionsPrompt(path.join(dir, path.basename(questionsPath(agent.id)))));
     }
+    // SPEC.md before changing code, and PLAN.md kept as it goes (unless the plan review asks for the plan).
+    if (task && this.config.specs !== false) {
+      fs.mkdirSync(briefDir(agent.id), { recursive: true });
+      const dir = fs.realpathSync(briefDir(agent.id));
+      writableDir ??= dir;
+      prompts.push(specPrompt(path.join(dir, path.basename(specPath(agent.id))), path.join(dir, path.basename(planPath(agent.id))), { withPlan: !agent.planReview }));
+    }
     if (agent.planReview && task) {
       fs.mkdirSync(briefDir(agent.id), { recursive: true });
       const file = path.join(fs.realpathSync(briefDir(agent.id)), path.basename(planPath(agent.id)));
@@ -2008,7 +2042,9 @@ export class AgentManager extends EventEmitter {
           .join('\n\n');
       }
     }
-    return { intent: agent.intent, status, digest, repo, briefMarkdown };
+    // The spec and plan go along with the brief: what done means, and how it gets there.
+    const extra = ['spec', 'plan'].map((n) => readSpecDoc(agent.id, n)?.markdown.trim()).filter(Boolean);
+    return { intent: agent.intent, status, digest, repo, briefMarkdown: [briefMarkdown, ...extra].filter(Boolean).join('\n\n') };
   }
 
   /** The engine (and model) that writes an agent's summaries: its own when it can make a one-shot call, else Claude Code. */

package/src/review.js

@@ -2,6 +2,7 @@
 // back to the agent as one message, and commit / push / open a pull request from the UI.
 import * as git from './git.js';
 import { hash } from './judge.js';
+import { prSections } from './brief.js';
 import { NO_REPO } from './manager.js';
 import { ghBin } from './tracker.js';
 
@@ -193,8 +194,15 @@ export class Review {
     }
     const args = ['pr', 'create', '--head', branch];
     if (target) args.push('--base', target);
-    if (String(title).trim()) args.push('--title', String(title).trim(), '--body', String(body ?? ''));
-    else args.push('--fill');
+    // The description: your text (else the commits), then the intent, spec and plan.
+    const sections = prSections(agent.id);
+    if (String(title).trim() || sections) {
+      const log = base ? await git.run('git', ['log', '--reverse', '--format=%s', `${base.sha}..HEAD`], opts).catch(() => '') : '';
+      const subjects = log.split('\n').filter(Boolean);
+      const t = String(title).trim() || subjects[0] || agent.name;
+      const lead = String(body ?? '').trim() || (subjects.length > 1 ? subjects.map((x) => `- ${x}`).join('\n') : '');
+      args.push('--title', t, '--body', [lead, sections].filter(Boolean).join('\n\n'));
+    } else args.push('--fill');
     if (draft) args.push('--draft');
     let out;
     try {

package/src/server.js

@@ -240,6 +240,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
       return manager.document(req.params.id, req.params.kind);
     }),
   );
+  api.get('/agents/:id/specs/:name', wrap((req) => manager.specDoc(req.params.id, req.params.name)));
   api.post('/agents/:id/plan', wrap((req) => manager.startPlanning(req.params.id)));
   api.post('/agents/:id/plan/approve', wrap((req) => manager.approvePlan(req.params.id, req.body?.note)));
   api.post('/agents/:id/plan/changes', wrap((req) => manager.requestPlanChanges(req.params.id, req.body?.note)));