@hybridlabor-api/aos 4.13.2 → 4.14.1

package/skills/global_config/plan-canvas/scripts/plan-canvas.js

@@ -21,6 +21,7 @@
 
 const fs = require('fs');
 const http = require('http');
+const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
 
@@ -37,7 +38,7 @@ const {
   resolvePort
 } = require('./lib/plan-canvas/server');
 
-const VERSION = '1.0.1';   // vendored Plan Canvas protocol version; matches SKILL.md metadata.version.
+const VERSION = '1.0.2';   // vendored Plan Canvas protocol version; matches SKILL.md metadata.version.
                            // Bump when the vendored JS changes, to force a stale detached server to restart.
 
 const SAFE_REQUEST_PATHS = new Set([
@@ -56,7 +57,11 @@ function usage() {
     '',
     'Usage:',
     '  aos-plan-canvas                  Show server status and sessions',
+    '  aos-plan-canvas modes            List available planning modes as JSON',
+    '  aos-plan-canvas templates        List plan templates as JSON ({id,label,description,useWhen,hasBoard})',
+    '  aos-plan-canvas new <template-id> <target-dir>  Copy a plan template into a new folder',
     '  aos-plan-canvas open <file>      Open (or resume) a review session',
+    '  aos-plan-canvas trail <plan-dir|plan.mdx>  Write an agenttrail plan file from a plan folder',
     '  aos-plan-canvas await <file>     Block until the human sends feedback',
     '  aos-plan-canvas pending          Show feedback queued for no listener',
     '  aos-plan-canvas typing <file>    Show a thinking/typing indicator in chat',
@@ -65,14 +70,21 @@ function usage() {
     '  aos-plan-canvas server           Run the server in the foreground',
     '',
     'Options:',
-    '  open:  --no-open      Do not launch a browser window',
+    '  open:  --mode <id>    Select planning mode (default: standard)',
+    '                   bdb-plan-builder builds <plan-dir>/plan.builder.html from',
+    '                   plan.mdx and opens that file instead',
+    '         --no-open      Do not launch a browser window',
     '         --reopen       Reopen a session the user ended from the browser',
+    '  new:   --mode <id>    bdb-plan-builder (default: plan.mdx, canvas.mdx) or standard (plan.md);',
+    '                   refuses a non-empty target (exit 2)',
+    '  trail: --out <file>   Output inside the workspace (default production_artifacts/00_execution_plan.md)',
+    '         --force        Overwrite an existing output file',
     '  await: --reply <msg>  Show an agent reply in the canvas chat before waiting',
     '         --timeout-ms <n>  Return {status:"waiting"} after n ms (tests/debug only)',
     '  typing: --state <thinking|typing|idle>  Defaults to typing',
     '  server: --port <n> --host <h>',
     '',
-    'Environment: AOS_PLAN_CANVAS_PORT, AOS_PLAN_CANVAS_STATE_DIR, AOS_PLAN_CANVAS_IDLE_MS'
+    'Environment: AOS_PLAN_CANVAS_PORT, AOS_PLAN_CANVAS_STATE_DIR, AOS_PLAN_CANVAS_IDLE_MS, AOS_PLAN_CANVAS_SKILL_DIRS'
   ].join('\n');
 }
 
@@ -225,12 +237,99 @@ async function cmdStatus({ stateDir, port }) {
   return { server: `http://${DEFAULT_HOST}:${port}`, version: health.version, sessions: sessions.body.sessions };
 }
 
+function cmdModes() {
+  return resolveModes();
+}
+
+function skillDirList() {
+  return (process.env.AOS_PLAN_CANVAS_SKILL_DIRS || [
+    path.join(process.env.HOME || os.homedir(), '.claude', 'skills'),
+    path.join(process.env.HOME || os.homedir(), '.agents', 'skills'),
+    path.join(process.env.HOME || os.homedir(), '.codex', 'skills'),
+    path.join(process.env.HOME || os.homedir(), '.config', 'opencode', 'skills'),
+    path.join(process.env.HOME || os.homedir(), '.gemini', 'config', 'skills')
+  ].join(':')).split(':');
+}
+
+function findSkillMd(name) {
+  for (const dir of skillDirList()) {
+    const p = path.join(dir, name, 'SKILL.md');
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function resolveModes() {
+  const modes = [
+    {
+      id: 'standard',
+      label: 'Standard Plan Canvas',
+      available: true,
+      reason: null
+    }
+  ];
+
+  // Check for bdb-plan-builder
+  const planBuilderPath = path.resolve(__dirname, 'lib', 'plan-builder', 'index.js');
+  modes.push({
+    id: 'bdb-plan-builder',
+    label: 'BDB Plan Builder',
+    available: fs.existsSync(planBuilderPath),
+    reason: fs.existsSync(planBuilderPath) ? null : 'bdb-plan-builder not installed'
+  });
+
+  // Check for visual-plan skill
+  const visualPlanFound = Boolean(findSkillMd('visual-plan'));
+
+  modes.push({
+    id: 'builder',
+    label: 'Builder.io Visual Plan',
+    available: visualPlanFound,
+    reason: visualPlanFound ? null : 'visual-plan skill not found'
+  });
+
+  return {
+    default: 'standard',
+    modes
+  };
+}
+
 async function cmdOpen(file, args, { stateDir, port }) {
   if (!file) throw new Error('open requires a file path');
   if (!fs.existsSync(path.resolve(file))) throw new Error(`artifact not found: ${file}`);
+
+  const mode = valueAfter(args, '--mode') || 'standard';
+  const modesInfo = resolveModes();
+  const modeConfig = modesInfo.modes.find(m => m.id === mode);
+
+  if (!modeConfig) {
+    process.stderr.write(`Unknown mode: ${mode}\n`);
+    return { error: `Unknown mode: ${mode}` };
+  }
+
+  if (!modeConfig.available) {
+    process.stderr.write(`Mode not available: ${mode} (${modeConfig.reason})\n`);
+    return { error: `Mode not available: ${mode} (${modeConfig.reason})` };
+  }
+
+  // bdb-plan-builder owns the artifact: it renders the plan folder to one
+  // self-contained HTML file next to plan.mdx, then that file goes through the
+  // normal session path unchanged.
+  let artifact = path.resolve(file);
+  let built = null;
+  if (mode === 'bdb-plan-builder') {
+    built = require('./lib/plan-builder').renderPlanFolder(file);
+    if (!built.outFile) {
+      const message = built.error || 'plan builder produced no output';
+      process.stderr.write(`${message}\n`);
+      return { error: message, mode };
+    }
+    artifact = built.outFile;
+  }
+
   await ensureServer({ stateDir, port });
   const res = await request(port, 'POST', '/api/sessions', {
-    file: path.resolve(file),
+    file: artifact,
     reopen: args.includes('--reopen')
   });
   if (res.statusCode === 409) return res.body;
@@ -241,8 +340,11 @@ async function cmdOpen(file, args, { stateDir, port }) {
     status: 'open',
     url,
     browser: launched ? 'opened' : 'not opened',
-    next_step:
-      'Run `aos-plan-canvas await <file>` and leave it running; it returns when the human sends feedback, a verdict, or ends the session.'
+    mode,
+    ...(built ? { artifact: built.outFile, warnings: built.warnings } : {}),
+    next_step: built && built.warnings.length
+      ? `Plan built with ${built.warnings.length} unreadable block(s), listed at the top of the artifact. Fix the MDX, then re-run \`open <dir> --mode bdb-plan-builder\` to rebuild. Then run \`aos-plan-canvas await <dir>/plan.builder.html\` and leave it running.`
+      : 'Run `aos-plan-canvas await <file>` and leave it running; it returns when the human sends feedback, a verdict, or ends the session.'
   };
 }
 
@@ -273,8 +375,26 @@ function awaitRequest(port, key, timeoutMs) {
   });
 }
 
+// A bdb-plan-builder session is keyed by the built plan.builder.html, but agents
+// know the plan by its folder or plan.mdx; follow either to the built artifact.
+function resolveArtifactArg(file) {
+  if (!file) return file;
+  const abs = path.resolve(file);
+  try {
+    const dir = fs.statSync(abs).isDirectory() ? abs : path.basename(abs) === 'plan.mdx' ? path.dirname(abs) : null;
+    if (dir) {
+      const built = path.join(dir, 'plan.builder.html');
+      if (fs.existsSync(built)) return built;
+    }
+  } catch (_) {
+    // fall through: a missing path is reported by the command itself
+  }
+  return file;
+}
+
 async function cmdAwait(file, args, { stateDir, port }) {
   if (!file) throw new Error('await requires a file path');
+  file = resolveArtifactArg(file);
   if (!(await healthCheck(port))) {
     return { status: 'no-server', hint: 'no canvas server is running; use `open` first', stateDir };
   }
@@ -303,6 +423,7 @@ async function cmdAwait(file, args, { stateDir, port }) {
 // Show the human an activity indicator in the canvas chat. Cheap and
 // fire-and-forget: a failed signal must never derail the actual work.
 async function cmdTyping(file, args, { port }) {
+  file = resolveArtifactArg(file);
   if (!file) throw new Error('typing requires a file path');
   const state = valueAfter(args, '--state') || 'typing';
   if (!(await healthCheck(port))) return { status: 'no-server' };
@@ -330,6 +451,7 @@ function cmdPending({ stateDir }) {
 }
 
 async function cmdEnd(file, { port }) {
+  file = resolveArtifactArg(file);
   if (!file) throw new Error('end requires a file path');
   if (!(await healthCheck(port))) return { status: 'no-server' };
   const res = await request(port, 'POST', '/api/end', { file: path.resolve(file) });
@@ -381,6 +503,51 @@ async function cmdServer(args, { stateDir, port }) {
   return new Promise(() => {}); // run until a signal or idle shutdown
 }
 
+const TEMPLATES_DIR = path.join(__dirname, 'lib', 'plan-builder', 'templates');
+
+function cmdTemplates() {
+  let ids = [];
+  try { ids = fs.readdirSync(TEMPLATES_DIR); } catch { /* no templates dir */ }
+  const list = [];
+  for (const id of ids.sort()) {
+    try {
+      const m = JSON.parse(fs.readFileSync(path.join(TEMPLATES_DIR, id, 'meta.json'), 'utf8'));
+      list.push({ id: m.id || id, label: m.label, description: m.description, useWhen: m.useWhen, hasBoard: Boolean(m.hasBoard) });
+    } catch { /* skip templates without readable meta.json */ }
+  }
+  return list;
+}
+
+function cmdNew(args) {
+  const fail = (error) => {
+    process.stderr.write(`${error}\n`);
+    output({ error });
+    return 2;
+  };
+  const mode = valueAfter(args, '--mode') || 'bdb-plan-builder';
+  const [id, target] = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--mode');
+  const ids = cmdTemplates().map(t => t.id);
+  if (!id || !ids.includes(id)) return fail(`Unknown template "${id || ''}". Valid ids: ${ids.join(', ') || '(none)'}`);
+  if (!target) return fail('Usage: aos-plan-canvas new <template-id> <target-dir> [--mode standard|bdb-plan-builder]');
+  if (mode !== 'standard' && mode !== 'bdb-plan-builder') return fail(`Unknown mode "${mode}". Valid modes: standard, bdb-plan-builder`);
+  const dir = path.resolve(target);
+  if (fs.existsSync(dir) && (!fs.statSync(dir).isDirectory() || fs.readdirSync(dir).length)) {
+    return fail(`Refusing to overwrite non-empty target: ${dir}`);
+  }
+  const src = path.join(TEMPLATES_DIR, id);
+  const files = mode === 'standard' ? [['standard.md', 'plan.md']] : [['plan.mdx', 'plan.mdx'], ['canvas.mdx', 'canvas.mdx']];
+  fs.mkdirSync(dir, { recursive: true });
+  const written = [];
+  for (const [from, to] of files) {
+    if (!fs.existsSync(path.join(src, from))) continue;
+    fs.copyFileSync(path.join(src, from), path.join(dir, to));
+    written.push(path.join(dir, to));
+  }
+  const entry = mode === 'standard' ? 'plan.md' : 'plan.mdx';
+  output({ template: id, mode, dir, files: written, next_step: `aos-plan-canvas open ${path.join(dir, entry)}${mode === 'standard' ? '' : ' --mode bdb-plan-builder'}` });
+  return 0;
+}
+
 async function main(argv = process.argv.slice(2)) {
   const args = argv.slice();
   if (args.includes('--help') || args.includes('-h')) {
@@ -394,7 +561,28 @@ async function main(argv = process.argv.slice(2)) {
   const context = { stateDir, port: (recorded && recorded.port) || resolvePort() };
   try {
     if (command === null) output(await cmdStatus(context));
-    else if (command === 'open') output(await cmdOpen(args[0], args, context));
+    else if (command === 'modes') output(cmdModes());
+    else if (command === 'templates') output(cmdTemplates());
+    else if (command === 'new') return cmdNew(args);
+    else if (command === 'open') {
+      const result = await cmdOpen(args[0], args, context);
+      if (result.error) {
+        output(result);
+        return 2;
+      }
+      output(result);
+    }
+    else if (command === 'trail') {
+      const { writeTrail, TrailError } = require('./lib/plan-builder/trail');
+      try {
+        output(writeTrail(args[0], { out: valueAfter(args, '--out'), force: args.includes('--force') }));
+      } catch (error) {
+        if (!(error instanceof TrailError)) throw error;
+        process.stderr.write(`${error.message}\n`);
+        output({ error: error.message });
+        return 2;
+      }
+    }
     else if (command === 'await') output(await cmdAwait(args[0], args, context));
     else if (command === 'pending') output(cmdPending(context));
     else if (command === 'typing') output(await cmdTyping(args[0], args, context));
@@ -418,4 +606,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { main, ensureServer, healthCheck };
+module.exports = { main, ensureServer, healthCheck, cmdTemplates, findSkillMd };

package/skills/global_config/pr-recap/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pr-recap
+description: Use when a PR or git range needs a visual recap page for a reviewer, with a changed-files tree, per-file notes, a Verified vs Not verified table, risks, and optional before/after images. Local and informational; never posts to GitHub.
+category: engineering-method
+user-invocable: true
+---
+
+# PR Recap
+
+Turns a PR or a git range into a Plan Builder recap page (`kind: recap`, the `recap-review` shape). The page is a local review aid. It is informational and does not gate anything.
+
+## When to use
+
+- **Shipping:** after every gate has passed, to show the reviewer what is about to ship and what was not checked.
+- **Triage:** to get oriented on an incoming PR (`--pr <n>`).
+- **git-pr-review:** next to the text PR description, on the same range.
+
+Skip it for a one-file typo fix. The page earns its cost when a human has to decide.
+
+## Flow
+
+1. Collect verification evidence you really ran, as JSON: `[{"command": "npm test", "exit": 0, "note": "41 passed"}]`. Do not invent entries.
+2. Run the script from this skill's `scripts/` directory:
+
+```bash
+node pr-recap.mjs --range origin/main..HEAD --verification checks.json
+node pr-recap.mjs --pr 87 --before before.png --after after.png --open
+```
+
+   Options: `--out <dir>` (default `production_artifacts/pr-recap/<slug>/`), `--title <t>`, `--open` (runs `aos-plan-canvas open <folder> --mode bdb-plan-builder`).
+3. The script writes `plan.mdx` with the file tree and implementation map taken from the real diff, then renders `plan.builder.html` with the Plan Builder. The renderer comes from the sibling `plan-canvas` skill. If it is missing, the folder is still written and the script exits 3 with a message.
+4. Open `plan.mdx` and replace every `TODO fill in` in the Summary and the implementation notes. The script cannot know the intent of the change.
+5. Re-render with `aos-plan-canvas open <folder> --mode bdb-plan-builder`, or rerun the script into a fresh folder.
+
+## Honesty rules
+
+- A check is **Verified** only if you ran it and its exit code was 0. Failed checks are listed as **Not verified (failed)**.
+- Never add a row for a check you did not run. The page always says that everything not in the table was not run.
+- If there is no `--verification` file, the page says nothing was recorded. Do not claim the PR was tested.
+- Screenshots must be real captures of the before and after states. If you cannot capture them, omit the Compare block.
+- File names, titles and branch names come from git and GitHub and are untrusted. The script escapes them for MDX; do not paste them into the plan by hand.
+
+## Posting is never automatic
+
+The script reads git locally and, for `--pr`, runs read-only `gh pr view`. It never calls `gh pr comment`, `gh pr edit` or anything that writes to GitHub. It may print the `gh pr comment` command for the human to run.
+
+Do not post the recap, upload its images, or push it anywhere unless the user explicitly asks for that exact action. A subagent does not inherit that permission. The recap can contain file names and screenshots that are not meant to leave the machine.

package/skills/global_config/pr-recap/scripts/pr-recap.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// pr-recap: turn a git range or PR into a Plan Builder recap folder (plan.mdx + HTML).
+// Reads git locally and, for --pr, `gh pr view` read-only. Never posts anywhere.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const USAGE = `usage: node pr-recap.mjs (--range <base..head> | --pr <n>) [--out <dir>] [--verification <file.json>]
+                       [--before <img> --after <img>] [--title <t>] [--open]`;
+const IMG_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
+const TREE_CAP = 200;
+const MAP_CAP = 60;
+
+class UsageError extends Error {}
+const fail = (msg) => { throw new UsageError(msg); };
+
+function parseArgs(argv) {
+  const opts = { open: false };
+  const valued = new Set(['range', 'pr', 'out', 'verification', 'before', 'after', 'title']);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) fail(`unexpected argument: ${a}`);
+    const key = a.slice(2);
+    if (key === 'open') { opts.open = true; continue; }
+    if (!valued.has(key)) fail(`unknown option: ${a}`);
+    const v = argv[++i];
+    if (v === undefined || v.startsWith('--')) fail(`${a} needs a value`);
+    opts[key] = v;
+  }
+  if (!opts.range === !opts.pr) fail('give exactly one of --range or --pr');
+  if (opts.range && (opts.range.startsWith('-') || !/^[^\s]+\.\.\.?[^\s]+$/.test(opts.range))) fail(`--range must look like base..head, got: ${opts.range}`);
+  if (opts.pr && !/^\d+$/.test(opts.pr)) fail(`--pr must be a number, got: ${opts.pr}`);
+  if (Boolean(opts.before) !== Boolean(opts.after)) fail('--before and --after must be given together');
+  for (const k of ['before', 'after']) {
+    if (!opts[k]) continue;
+    if (!IMG_EXT.has(extname(opts[k]).toLowerCase())) fail(`--${k} must be one of ${[...IMG_EXT].join(' ')}`);
+    if (!existsSync(opts[k])) fail(`--${k} file not found: ${opts[k]}`);
+  }
+  return opts;
+}
+
+const run = (cmd, args) => execFileSync(cmd, args, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+const git = (...args) => run('git', args);
+
+// Git and GitHub text is untrusted. `line` is for frontmatter and markdown
+// prose: single line, no characters MDX or markdown would act on.
+const line = (s, max = 160) => String(s ?? '').replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, ' ').replace(/[<>{}`"\\|]/g, '·').trim().slice(0, max);
+// `lit` is for JSX props: a JSON string literal with < > { } also \u-escaped.
+const lit = (s) => JSON.stringify(String(s ?? '')).replace(/[<>{}]/g, (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+
+function diffFiles(range) {
+  const status = git('diff', '--name-status', '-z', '-M', range, '--').split('\0').filter((x) => x !== '');
+  const files = new Map();
+  for (let i = 0; i < status.length;) {
+    const code = status[i++][0];
+    const from = code === 'R' || code === 'C' ? status[i++] : null;
+    const path = status[i++];
+    files.set(path, { path, change: code === 'A' || code === 'C' ? 'added' : code === 'D' ? 'deleted' : 'modified', from, add: 0, del: 0 });
+  }
+  const num = git('diff', '--numstat', '-z', '-M', range, '--').split('\0');
+  for (let i = 0; i < num.length; i++) {
+    const m = /^(\d+|-)\t(\d+|-)\t(.*)$/.exec(num[i]);
+    if (!m) continue;
+    let path = m[3];
+    if (path === '') { i += 2; path = num[i]; }
+    const f = files.get(path);
+    if (f) { f.add = m[1] === '-' ? 0 : Number(m[1]); f.del = m[2] === '-' ? 0 : Number(m[2]); }
+  }
+  return [...files.values()];
+}
+
+function fromGh(n) {
+  let pr;
+  try {
+    pr = JSON.parse(run('gh', ['pr', 'view', n, '--json', 'title,headRefName,baseRefName,headRefOid,baseRefOid,author,files,additions,deletions']));
+  } catch (e) {
+    throw new Error(`gh pr view ${n} failed (is gh installed and authenticated?): ${String(e.stderr || e.message).trim()}`);
+  }
+  let files;
+  try {
+    files = diffFiles(`${pr.baseRefOid}..${pr.headRefOid}`);
+  } catch {
+    // ponytail: commits not fetched locally, so fall back to gh's file list (no rename info)
+    files = (pr.files || []).map((f) => ({ path: f.path, change: f.changeType === 'ADDED' ? 'added' : f.changeType === 'DELETED' ? 'deleted' : 'modified', from: null, add: f.additions || 0, del: f.deletions || 0 }));
+  }
+  return { files, title: pr.title, branch: pr.headRefName, base: pr.baseRefName, commit: String(pr.headRefOid || '').slice(0, 7), author: pr.author?.login, pr: `#${n}` };
+}
+
+function fromRange(range) {
+  const files = diffFiles(range);
+  const head = range.split(/\.\.\.?/)[1];
+  const last = git('log', '-1', '--format=%h%x1f%an%x1f%s', head).trim().split('\x1f');
+  return { files, title: last[2], branch: head, base: range.split(/\.\.\.?/)[0], commit: last[0], author: last[1] };
+}
+
+function readVerification(file) {
+  let rows;
+  try { rows = JSON.parse(readFileSync(file, 'utf8')); } catch (e) { fail(`--verification is not readable JSON: ${e.message}`); }
+  if (!Array.isArray(rows) || rows.some((r) => !r || typeof r.command !== 'string' || !Number.isInteger(r.exit))) fail('--verification must be an array of {command, exit (integer), note?}');
+  return rows;
+}
+
+function treeEntries(files) {
+  const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : 1));
+  const out = [];
+  const seen = new Set();
+  for (const f of sorted) {
+    const parts = f.path.split('/');
+    for (let d = 0; d < parts.length - 1; d++) {
+      const dir = parts.slice(0, d + 1).join('/');
+      if (!seen.has(dir)) { seen.add(dir); out.push(`{ path: ${lit(dir)}, depth: ${d}, change: "modified" }`); }
+    }
+    const note = (f.from ? `renamed from ${f.from}; ` : '') + `+${f.add} -${f.del}`;
+    out.push(`{ path: ${lit(f.path)}, depth: ${parts.length - 1}, change: ${lit(f.change)}, note: ${lit(note)} }`);
+  }
+  return out;
+}
+
+function buildPlan({ info, verification, images, title }) {
+  const files = info.files;
+  const shown = files.slice(0, TREE_CAP);
+  const adds = files.reduce((s, f) => s + f.add, 0);
+  const dels = files.reduce((s, f) => s + f.del, 0);
+  const fm = [['title', title || info.title || 'Change recap'], ['subtitle', 'Recap generated from the diff. The Summary needs a human or agent to fill it in.'], ['kind', 'recap'],
+    ['pr', info.pr], ['branch', info.branch], ['base', info.base], ['commit', info.commit], ['files', files.length], ['additions', adds], ['deletions', dels],
+    ['author', info.author], ['date', new Date().toISOString().slice(0, 10)]]
+    .filter(([, v]) => v !== undefined && v !== '')
+    .map(([k, v]) => `${k}: ${typeof v === 'number' ? v : `"${line(v)}"`}`);
+
+  const rows = verification.map((v) => `[${lit(line(v.command, 200))}, ${lit(String(v.exit))}, ${lit(v.exit === 0 ? 'Verified' : 'Not verified (failed)')}, ${lit(line(v.note || '', 200))}]`);
+  const ok = verification.filter((v) => v.exit === 0).map((v) => `- \`${line(v.command, 120)}\` exited 0${v.note ? `: ${line(v.note, 120)}` : ''}`);
+  const bad = verification.filter((v) => v.exit !== 0).map((v) => `- \`${line(v.command, 120)}\` exited ${v.exit}${v.note ? `: ${line(v.note, 120)}` : ''}`);
+  const verified = ok.length ? ok.join('\n') : '- Nothing was recorded as passing';
+  const notVerified = [...bad, '- Everything not listed in the table above was not run'].join('\n');
+
+  const parts = [`---\n${fm.join('\n')}\n---\n`,
+    '## Summary\n\n- **What:** TODO fill in: what changed, in one sentence\n- **Why:** TODO fill in: the reason for the change\n- **Scope:** TODO fill in: what is deliberately untouched\n',
+    `## Changed areas\n\n<FileTree title="Files" entries={[\n  ${treeEntries(shown).join(',\n  ')},\n]} />\n`,
+    `<ImplementationMap title="What each file does now" files={[\n  ${files.slice(0, MAP_CAP).map((f) => `{ path: ${lit(f.path)}, change: ${lit(f.change)}, note: "TODO fill in: what this file does now" }`).join(',\n  ')},\n]} />\n`];
+  if (files.length > TREE_CAP || files.length > MAP_CAP) parts.push(`<Callout tone="note" title="Large diff">\n\nThe diff touches ${files.length} files. The tree shows the first ${Math.min(files.length, TREE_CAP)} and the implementation map the first ${Math.min(files.length, MAP_CAP)}. The rest are not listed.\n\n</Callout>\n`);
+  if (images) parts.push(`### Most important change\n\n<Compare>\n<Before>\n\n![Before](${images.before})\n\n</Before>\n<After>\n\n![After](${images.after})\n\n</After>\n</Compare>\n`);
+  parts.push(`## Verification\n\n<Table title="Commands run" columns={["Command", "Exit code", "Status", "Note"]} rows={[\n  ${rows.length ? rows.join(',\n  ') : '["none recorded", "-", "Not verified", "no --verification file given"]'},\n]} />\n`,
+    `<Columns columns={[\n  { label: "Verified", blocks: ${lit(verified)} },\n  { label: "Not verified", blocks: ${lit(notVerified)} },\n]} />\n`,
+    '## Risks and follow-ups\n\n<Checklist title="Risks and follow-ups">\n- [ ] Fill in the Summary and the implementation notes before sharing\n- [ ] Review every item under Not verified\n- [ ] Informational recap: it does not gate the merge\n</Checklist>\n');
+  return parts.join('\n');
+}
+
+function loadBuilder() {
+  const req = createRequire(import.meta.url);
+  for (const rel of ['../../plan-canvas/scripts/lib/plan-builder', '../../../global_config/plan-canvas/scripts/lib/plan-builder']) {
+    const p = resolve(HERE, rel);
+    if (existsSync(join(p, 'index.js'))) return req(p);
+  }
+  return null;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const verification = opts.verification ? readVerification(opts.verification) : [];
+  let info;
+  try { info = opts.pr ? fromGh(opts.pr) : fromRange(opts.range); } catch (e) { if (e instanceof UsageError) throw e; throw new Error(`git failed: ${String(e.stderr || e.message).trim()}`); }
+
+  const slug = (opts.pr ? `pr-${opts.pr}` : opts.range.replace(/[^A-Za-z0-9._-]+/g, '-')).slice(0, 80);
+  const out = resolve(opts.out || join('production_artifacts', 'pr-recap', slug));
+  mkdirSync(out, { recursive: true });
+  let images = null;
+  if (opts.before) {
+    images = { before: `before${extname(opts.before).toLowerCase()}`, after: `after${extname(opts.after).toLowerCase()}` };
+    copyFileSync(opts.before, join(out, images.before));
+    copyFileSync(opts.after, join(out, images.after));
+  }
+  writeFileSync(join(out, 'plan.mdx'), buildPlan({ info, verification, images, title: opts.title }));
+  console.log(`plan folder: ${out}`);
+
+  const builder = loadBuilder();
+  if (!builder) {
+    console.error('Plan Builder renderer not found (expected plan-canvas next to pr-recap). plan.mdx was written but not rendered; install the plan-canvas skill and rerun.');
+    return 3;
+  }
+  const r = builder.renderPlanFolder(out);
+  console.log(`rendered: ${r.outFile} (${r.warnings.length} warnings)`);
+  for (const w of r.warnings) console.error(`warning: ${w}`);
+  if (opts.open) {
+    const o = spawnSync('aos-plan-canvas', ['open', out, '--mode', 'bdb-plan-builder'], { stdio: 'inherit' });
+    if (o.status !== 0) { console.error('aos-plan-canvas open failed or is not installed'); return 1; }
+  }
+  if (opts.pr) console.log(`Not posted. To share it yourself, review the page first, then run:\n  gh pr comment ${opts.pr} --body "Visual recap (informational): <paste summary>"`);
+  return 0;
+}
+
+try {
+  process.exitCode = main();
+} catch (e) {
+  console.error(e instanceof UsageError ? `error: ${e.message}\n${USAGE}` : `error: ${e.message}`);
+  process.exitCode = e instanceof UsageError ? 2 : 1;
+}

package/skills/global_config/quick-recap/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: quick-recap
+description: Use when the user wants each agent response to end with a red/yellow/green status line showing whether the work is finished, pending a follow-up, or blocked on input.
+category: bdb-core
+source: BuilderIO/skills
+---
+
+# Quick Recap
+
+Make completion state obvious at the end of every response.
+
+## Status Block
+
+Every response that completes a unit of work must end with:
+
+```md
+🟢 Actual concise status sentence
+```
+
+Rules:
+
+- Keep the status line under 100 characters.
+- Use `🟢` when the requested work is finished.
+- Use `🟡` when non-routine follow-up remains; name the pending item.
+- Use `🔴` only when blocked on user input.
+- Put the status line at the very end of the response.
+- Do not add `---`, spacer lines, or any content after the status line.
+
+## Activation
+
+The convention applies only while this skill is loaded or the user asks for it.
+AOS does not inject a managed `AGENTS.md` / `CLAUDE.md` block for it.
+
+Choose the status from the user's perspective: finished, pending a specific
+non-routine step, or blocked.
+
+## Examples
+
+Finished work:
+
+```md
+🟢 Updated quick recap docs with output examples
+```
+
+Non-routine follow-up remains:
+
+```md
+🟡 Code updated, set PROVIDER_WEBHOOK_SECRET before testing webhooks
+```
+
+Blocked on user input:
+
+```md
+🔴 Need the production API key to continue
+```