geo-ai-search-optimization 1.2.15 → 1.2.17

package/README.md

@@ -226,6 +226,47 @@ geo-ai-search-optimization agent-decision-log ./your-site --append-from ./report
 - 最新建议下一步命令
 - 可直接复制给 agent 的 decision log prompt
 
+## Agent Retrospective 命令
+
+如果你希望不只是看多轮决策历史，而是直接总结“为什么这几轮顺利 / 为什么总卡住”，可以直接用 `agent-retrospective`：
+
+```bash
+geo-ai-search-optimization agent-retrospective ./your-site
+geo-ai-search-optimization agent-retrospective ./reports/agent-decision-log.json
+geo-ai-search-optimization agent-retrospective ./reports/agent-decision-log.json --format json --out ./reports/agent-retrospective.json
+```
+
+`agent-retrospective` 会输出：
+
+- 当前复盘状态
+- 重复阻塞与重复任务包
+- 关键学习
+- 下一轮建议
+- 决策分布
+- 多轮时间线
+- 可直接复制给 agent 的 retrospective prompt
+
+## Agent Playbook Pack 命令
+
+如果你希望把多轮复盘、决策历史和交接信息压成一个“下一位 agent 一拿到就能继续做”的单入口工件，可以直接用 `agent-playbook-pack`：
+
+```bash
+geo-ai-search-optimization agent-playbook-pack ./your-site
+geo-ai-search-optimization agent-playbook-pack ./reports/agent-decision-log.json
+geo-ai-search-optimization agent-playbook-pack ./reports/agent-retrospective.json --format json --out ./reports/agent-playbook-pack.json
+```
+
+`agent-playbook-pack` 会输出：
+
+- 当前状态
+- 恢复摘要
+- 启动命令
+- 当前包与下一包
+- 先读什么
+- 现在先做什么 / 现在不要做什么
+- 后续命令
+- 可直接复制给 agent 的 playbook prompt
+
 ## Quick Start
 
 如果你要从 0 到 1 启动一个 GEO 项目，建议照这个顺序做。
@@ -628,6 +669,8 @@ geo-ai-search-optimization agent-progress-tracker ./your-site
 geo-ai-search-optimization agent-status-board ./your-site
 geo-ai-search-optimization agent-checkpoint ./your-site
 geo-ai-search-optimization agent-decision-log ./your-site
+geo-ai-search-optimization agent-retrospective ./your-site
+geo-ai-search-optimization agent-playbook-pack ./your-site
 geo-ai-search-optimization skills
 geo-ai-search-optimization where
 geo-ai-search-optimization doctor
@@ -698,6 +741,21 @@ geo-ai-search-optimization help
 - 输出 do-now checklist、stop checklist、success checklist、验证命令和回报模板
 - 新增 `geo-ai-search-optimization-agent-executor` skill
 
+## New in 1.2.17
+
+- 新增 `agent-playbook-pack`
+- 把 `agent-retrospective + agent-decision-log + handoff-bundle` 压成一个单入口执行包
+- 让下一位 agent 可以直接从 current packet、start command 和 do-now checklist 继续
+- `completion-report` 现在也能直接吃 retrospective / handoff bundle / playbook pack 这类工件
+- 新增 `geo-ai-search-optimization-agent-playbook-pack` skill
+
+## New in 1.2.16
+
+- 新增 `agent-retrospective` 命令
+- 把多轮 decision log 压成复盘视图，识别重复阻塞、重复任务包和反复出现的决策模式
+- 支持从 `agent-decision-log`、`agent-checkpoint`、目录、网址等输入继续生成 retrospective
+- 新增 `geo-ai-search-optimization-agent-retrospective` skill
+
 ## New in 1.2.15
 
 - 新增 `agent-decision-log` 命令
@@ -928,6 +986,8 @@ The installed package now includes a bundled GEO skill pack, including:
 - `geo-ai-search-optimization-agent-status-board`
 - `geo-ai-search-optimization-agent-checkpoint`
 - `geo-ai-search-optimization-agent-decision-log`
+- `geo-ai-search-optimization-agent-retrospective`
+- `geo-ai-search-optimization-agent-playbook-pack`
 - `geo-ai-search-optimization-usage`
 - `geo-ai-search-optimization-agent-handoff`
 - `geo-ai-search-optimization-repair-loop`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.2.15",
+  "version": "1.2.17",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/resources/geo-ai-search-optimization/references/skill-bundle-map.md

@@ -112,6 +112,26 @@ Best for:
 - giving PM and the next agent a reusable decision history across rounds
 - appending a fresh checkpoint onto an existing GEO execution history
 
+### `geo-ai-search-optimization-agent-retrospective`
+
+Use this when the next agent or PM should understand the pattern across several rounds, not just inherit the last decision.
+
+Best for:
+
+- explaining why the same blocker or packet kept recurring
+- turning decision history into lessons learned and next-round advice
+- producing a cross-round retrospective before meetings, closeout, or final delivery
+
+### `geo-ai-search-optimization-agent-playbook-pack`
+
+Use this when the next agent should get one single-entry resume pack instead of piecing together retrospective, decision history, and handoff artifacts manually.
+
+Best for:
+
+- handing one GEO artifact to the next agent and saying "continue from here"
+- compressing multi-round history into one current packet, one start command, and one follow-up chain
+- reducing restart risk after several GEO rounds or multiple handoffs
+
 ## Usage guide
 
 ### `geo-ai-search-optimization-usage`

package/resources/geo-ai-search-optimization-agent-playbook-pack/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: geo-ai-search-optimization-agent-playbook-pack
+description: Bundle GEO retrospective, decision history, and handoff artifacts into one single-entry playbook for the next agent. Use when a PM or agent wants the next agent to continue from prior GEO rounds without rebuilding the whole chain, and needs a current packet, start command, do-now checklist, avoid-now checklist, and follow-up commands in one artifact.
+---
+
+# GEO Agent Playbook Pack
+
+Use this skill when the next agent should not rebuild the GEO chain from scratch.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- reads GEO retrospective, decision log, and handoff bundle style inputs
+- compresses them into one agent-ready entrypoint
+- tells the next agent where to resume, what to do now, and what not to do now
+- keeps cross-round context without forcing the next agent to read every artifact first
+
+## Best use
+
+- when PM wants to hand one artifact to the next agent and say "continue from here"
+- when GEO work has already gone through multiple rounds and needs a stable resume point
+- when the team wants one start command, one current packet, and one follow-up chain instead of many separate artifacts

package/resources/geo-ai-search-optimization-agent-playbook-pack/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Playbook Pack"
+  short_description: "Compress GEO history into one resume entrypoint"
+  default_prompt: "Use $geo-ai-search-optimization-agent-playbook-pack to turn this GEO history into one playbook artifact with a resume summary, start command, do-now checklist, and follow-up commands for the next agent."

package/resources/geo-ai-search-optimization-agent-retrospective/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: geo-ai-search-optimization-agent-retrospective
+description: Turn GEO decision history into a multi-round retrospective. Use when an agent or PM should understand why prior GEO rounds kept advancing, stalled on blockers, or reached closeout, and needs recurring patterns, lessons learned, and next-round guidance instead of a single checkpoint.
+---
+
+# GEO Agent Retrospective
+
+Use this skill when one checkpoint or one decision log is not enough, and the team needs to understand the pattern across rounds.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- reads GEO decision history across multiple rounds
+- highlights recurring blockers, repeated packets, and repeated decisions
+- explains what changed from round to round
+- turns history into lessons learned and next-round advice
+
+## Best use
+
+- when PM asks why the team keeps getting blocked in the same place
+- when the next agent should inherit not only the latest decision, but the pattern behind it
+- when the team wants a reusable retrospective before closeout, meetings, or final delivery

package/resources/geo-ai-search-optimization-agent-retrospective/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Retrospective"
+  short_description: "Summarize cross-round GEO patterns and lessons"
+  default_prompt: "Use $geo-ai-search-optimization-agent-retrospective to turn this GEO decision history into a multi-round retrospective with recurring patterns, lessons learned, and next-round guidance."

package/resources/geo-ai-search-optimization-usage/SKILL.md

@@ -13,7 +13,7 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as twenty-two layers:
+The package is best explained as twenty-four layers:
 
 1. `auto-flow`: auto-select the next skill and command chain
 2. `agent-session`: build a runnable session for the next agent
@@ -24,19 +24,21 @@ The package is best explained as twenty-two layers:
 7. `agent-status-board`: turn the execution state into a board view for PM and agents
 8. `agent-checkpoint`: freeze the current round into a continue / unblock / closeout decision
 9. `agent-decision-log`: preserve why each round continued, paused, or closed out
-10. `skills`: inspect the bundled skill package
-11. `onboard-url` / `onboard`: first look
-12. `scan`: raw signal check
-13. `audit` / `report`: diagnosis
-14. `fix-plan` / `owner-board`: execution planning
-15. `agent-handoff`: agent takeover package
-16. `apply-plan`: execution loop
-17. `completion-report`: closeout
-18. `handoff-bundle`: all-in-one package
-19. `share-pack`: audience-ready delivery
-20. `export-pack`: folder export
-21. `html-pack` / `publish-pack`: browsable and final delivery output
-22. `pm-brief` / `roadmap`: stakeholder alignment
+10. `agent-retrospective`: explain multi-round patterns, lessons, and next-round advice
+11. `agent-playbook-pack`: compress retrospective, decision history, and handoff into one resume entrypoint
+12. `skills`: inspect the bundled skill package
+13. `onboard-url` / `onboard`: first look
+14. `scan`: raw signal check
+15. `audit` / `report`: diagnosis
+16. `fix-plan` / `owner-board`: execution planning
+17. `agent-handoff`: agent takeover package
+18. `apply-plan`: execution loop
+19. `completion-report`: closeout
+20. `handoff-bundle`: all-in-one package
+21. `share-pack`: audience-ready delivery
+22. `export-pack`: folder export
+23. `html-pack` / `publish-pack`: browsable and final delivery output
+24. `pm-brief` / `roadmap`: stakeholder alignment
 
 ## Recommended command order
 
@@ -52,6 +54,8 @@ npx geo-ai-search-optimization agent-progress-tracker https://example.com
 npx geo-ai-search-optimization agent-status-board https://example.com
 npx geo-ai-search-optimization agent-checkpoint https://example.com
 npx geo-ai-search-optimization agent-decision-log https://example.com
+npx geo-ai-search-optimization agent-retrospective https://example.com
+npx geo-ai-search-optimization agent-playbook-pack https://example.com
 npx geo-ai-search-optimization onboard-url https://example.com
 npx geo-ai-search-optimization pm-brief https://example.com
 npx geo-ai-search-optimization roadmap https://example.com
@@ -69,6 +73,8 @@ npx geo-ai-search-optimization agent-progress-tracker ./your-site
 npx geo-ai-search-optimization agent-status-board ./your-site
 npx geo-ai-search-optimization agent-checkpoint ./your-site
 npx geo-ai-search-optimization agent-decision-log ./your-site
+npx geo-ai-search-optimization agent-retrospective ./your-site
+npx geo-ai-search-optimization agent-playbook-pack ./your-site
 npx geo-ai-search-optimization scan ./your-site
 npx geo-ai-search-optimization audit ./your-site
 npx geo-ai-search-optimization fix-plan ./your-site
@@ -95,6 +101,8 @@ npx geo-ai-search-optimization roadmap ./your-site
 - `agent-status-board`: present the current execution state as a board with done, in-progress, blocked, next, and queued columns
 - `agent-checkpoint`: convert the current round into a checkpoint decision for continue, unblock, or closeout
 - `agent-decision-log`: preserve multiple rounds of checkpoint history so the next agent can inherit the reasoning
+- `agent-retrospective`: explain why the last few rounds advanced or stalled, and turn that into lessons and next-round guidance
+- `agent-playbook-pack`: compress retrospective, decision history, and handoff into one single-entry resume pack for the next agent
 - `onboard-url`: first-time website check from a live URL
 - `onboard`: interactive first-time onboarding
 - `skills`: list the bundled skills and decide which skill or command chain fits the task
@@ -128,6 +136,8 @@ When explaining the tool to a user:
 - if the user wants the next agent to present execution state as a board for PM and agent coordination, move them to `agent-status-board`
 - if the user wants a per-round decision artifact that says continue, unblock, or close out, move them to `agent-checkpoint`
 - if the user wants cross-round decision memory and not just one checkpoint, move them to `agent-decision-log`
+- if the user wants to understand why multiple rounds kept advancing or getting stuck, move them to `agent-retrospective`
+- if the user wants one artifact that the next agent can take over from immediately, move them to `agent-playbook-pack`
 - explain the result in PM language, not implementation jargon
 - if the user sounds new, start with `onboard-url` or `quick-start`
 - if the user wants another agent to take over, move them to `agent-handoff`

package/src/agent-playbook-pack.js

@@ -0,0 +1,267 @@
+import { createAgentDecisionLog } from "./agent-decision-log.js";
+import { createAgentRetrospective } from "./agent-retrospective.js";
+import { createHandoffBundle } from "./handoff-bundle.js";
+import { writeScanOutput } from "./scan.js";
+
+const VALID_FORMATS = new Set(["markdown", "json"]);
+
+function normalizeFormat(format) {
+  const resolved = (format || "markdown").toLowerCase();
+  if (!VALID_FORMATS.has(resolved)) {
+    throw new Error(`不支持的 agent-playbook-pack 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+function inferPlaybookStatus(retrospective, decisionLog, handoffBundle) {
+  if (
+    retrospective.retrospectiveStatus === "ready-for-closeout" ||
+    decisionLog.latestDecision === "move-to-closeout"
+  ) {
+    return "closeout-ready";
+  }
+  if (
+    retrospective.retrospectiveStatus === "repeated-blocker" ||
+    retrospective.retrospectiveStatus === "blocked-this-round" ||
+    decisionLog.latestDecision === "resolve-blockers"
+  ) {
+    return "unblock-first";
+  }
+  if (handoffBundle.summary.executionMode === "implementation-ready") {
+    return "implementation-ready";
+  }
+  if (handoffBundle.summary.executionMode === "advice-only") {
+    return "advice-ready";
+  }
+  return "artifact-guided";
+}
+
+function buildResumeSummary(status, retrospective, decisionLog) {
+  if (status === "closeout-ready") {
+    return "这轮已经接近或进入收尾，不要再扩展新任务，直接整理 closeout 与交付。";
+  }
+  if (status === "unblock-first") {
+    return `当前应先解除阻塞，再继续 ${decisionLog.currentPacket?.id || "当前包"}。`;
+  }
+  if (status === "implementation-ready") {
+    return `当前可以直接接着做 ${decisionLog.currentPacket?.id || "第一包"}，并按既有节奏推进。`;
+  }
+  if (status === "advice-ready") {
+    return "当前更适合先给建议与实施路径，不要假设已经拥有仓库写入权限。";
+  }
+  return `当前建议沿着最近一次决策继续推进 ${decisionLog.currentPacket?.id || "下一包"}。`;
+}
+
+function buildStartCommand(status, retrospective, decisionLog, handoffBundle) {
+  if (status === "closeout-ready") {
+    return `geo-ai-search-optimization completion-report ${decisionLog.source}`;
+  }
+  if (retrospective.suggestedNextCommand) {
+    return retrospective.suggestedNextCommand;
+  }
+  if (decisionLog.suggestedNextCommand) {
+    return decisionLog.suggestedNextCommand;
+  }
+  const firstPacket = handoffBundle.applyPlan.packets[0];
+  return firstPacket
+    ? `geo-ai-search-optimization agent-executor ${decisionLog.source} --task ${firstPacket.id}`
+    : `geo-ai-search-optimization agent-session ${decisionLog.source}`;
+}
+
+function buildReadOrder() {
+  return [
+    "先读 retrospective，总结多轮里为什么推进顺利或反复卡住。",
+    "再读 decision log，确认最近一次决策、当前包和下一步命令。",
+    "最后读 handoff bundle，接着看 apply-plan 和 completion-report 的执行细节。"
+  ];
+}
+
+function buildDoNowChecklist(status, retrospective, decisionLog) {
+  const items = [];
+
+  if (status === "closeout-ready") {
+    items.push("不要再新开执行包。");
+    items.push("直接整理 completion-report、meeting-pack 和 publish-pack。");
+  } else if (status === "unblock-first") {
+    items.push("先解决当前阻塞，不要直接继续改代码。");
+    items.push("阻塞解除后，再回到当前包继续推进。");
+  } else {
+    items.push(`沿着当前包 ${decisionLog.currentPacket?.id || "第一包"} 继续，不要重新生成一条新链。`);
+    items.push("先按已有 runbook / executor 节奏推进，再更新状态。");
+  }
+
+  items.push(...retrospective.nextRoundAdvice.slice(0, 2));
+  return Array.from(new Set(items));
+}
+
+function buildAvoidNowChecklist(status, retrospective) {
+  const items = [];
+
+  if (status !== "closeout-ready") {
+    items.push("不要同时切换目标、任务包和执行模式。");
+  }
+  if (status === "unblock-first") {
+    items.push("不要假装阻塞不存在，也不要跳过 preflight 直接改动。");
+  }
+  if (retrospective.retrospectiveStatus === "restarting-too-often") {
+    items.push("不要再从第一包重新开始，优先延续最近一次 current packet。");
+  }
+  if (retrospective.recurringBlockers[0]?.count >= 2) {
+    items.push(`不要忽视重复阻塞「${retrospective.recurringBlockers[0].title}」，先把它变成固定检查项。`);
+  }
+  if (status === "closeout-ready") {
+    items.push("不要在 closeout 阶段继续扩展新的修复范围。");
+  }
+
+  return items;
+}
+
+function buildFollowupCommands(status, source) {
+  if (status === "closeout-ready") {
+    return [
+      `geo-ai-search-optimization completion-report ${source}`,
+      `geo-ai-search-optimization meeting-pack ${source}`,
+      `geo-ai-search-optimization publish-pack ${source}`
+    ];
+  }
+
+  return [
+    `geo-ai-search-optimization agent-status-board ${source}`,
+    `geo-ai-search-optimization agent-decision-log ${source}`,
+    `geo-ai-search-optimization agent-retrospective ${source}`
+  ];
+}
+
+function buildPlaybookPrompt(pack) {
+  const lines = [
+    "你现在进入 GEO Agent Playbook 模式。",
+    `输入来源：${pack.source}`,
+    `当前状态：${pack.playbookStatus}`,
+    `恢复摘要：${pack.resumeSummary}`,
+    `启动命令：${pack.startCommand}`,
+    `当前包：${pack.currentPacket?.id || "无"}`
+  ];
+
+  if (pack.nextPacket) {
+    lines.push(`下一包：${pack.nextPacket.id}｜${pack.nextPacket.title}`);
+  }
+  if (pack.retrospective.recurringBlockers.length > 0) {
+    lines.push(
+      `重复阻塞：${pack.retrospective.recurringBlockers.map((item) => `${item.title} (${item.count})`).join("；")}`
+    );
+  }
+
+  lines.push("请先解释你为什么沿着这条 playbook 继续，而不是重新规划一整条新链。");
+  lines.push("然后按 read order、do now checklist、avoid now checklist 输出执行建议。");
+  lines.push("最后给出本轮完成后应该更新哪些工件。");
+  return lines.join("\n");
+}
+
+export async function createAgentPlaybookPack(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const retrospective = await createAgentRetrospective(input, { format: "json" });
+  const decisionLog = retrospective.decisionLog || (await createAgentDecisionLog(input, { format: "json" }));
+  const baseSource = retrospective.source || decisionLog.source || input;
+  const handoffBundle = await createHandoffBundle(baseSource, { format: "json", taskId: options.taskId });
+
+  const playbookStatus = inferPlaybookStatus(retrospective, decisionLog, handoffBundle);
+  const source = baseSource;
+  const startCommand = buildStartCommand(playbookStatus, retrospective, decisionLog, handoffBundle);
+
+  const pack = {
+    kind: "geo-agent-playbook-pack",
+    input,
+    source,
+    sourceType: decisionLog.sourceType,
+    artifactKind: decisionLog.kind,
+    format,
+    playbookStatus,
+    resumeSummary: buildResumeSummary(playbookStatus, retrospective, decisionLog),
+    currentPacket: decisionLog.currentPacket,
+    nextPacket: decisionLog.nextPacket,
+    startCommand,
+    readOrder: buildReadOrder(),
+    doNowChecklist: buildDoNowChecklist(playbookStatus, retrospective, decisionLog),
+    avoidNowChecklist: buildAvoidNowChecklist(playbookStatus, retrospective),
+    followupCommands: buildFollowupCommands(playbookStatus, source),
+    decisionLog,
+    retrospective,
+    handoffBundle,
+    playbookPrompt: ""
+  };
+
+  pack.playbookPrompt = buildPlaybookPrompt(pack);
+  return pack;
+}
+
+export function renderAgentPlaybookPackMarkdown(pack) {
+  const lines = [
+    "# GEO Agent Playbook Pack",
+    "",
+    `- 输入：\`${pack.source}\``,
+    `- 来源类型：\`${pack.sourceType}\``,
+    `- 当前状态：\`${pack.playbookStatus}\``,
+    `- 恢复摘要：${pack.resumeSummary}`,
+    `- 启动命令：\`${pack.startCommand}\``,
+    ""
+  ];
+
+  if (pack.currentPacket) {
+    lines.push("## 当前包", "", `- ${pack.currentPacket.id}｜${pack.currentPacket.title}`);
+    lines.push(`- Owner：${pack.currentPacket.owner}`);
+    lines.push(`- 优先级：${pack.currentPacket.priority}`);
+    lines.push("");
+  }
+
+  if (pack.nextPacket) {
+    lines.push("## 下一包", "", `- ${pack.nextPacket.id}｜${pack.nextPacket.title}`);
+    lines.push(`- Owner：${pack.nextPacket.owner}`);
+    lines.push(`- 优先级：${pack.nextPacket.priority}`);
+    lines.push("");
+  }
+
+  lines.push("## 先读什么", "");
+  for (const item of pack.readOrder) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 现在先做什么", "");
+  for (const item of pack.doNowChecklist) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 现在不要做什么", "");
+  if (pack.avoidNowChecklist.length === 0) {
+    lines.push("- 当前没有额外禁忌项。");
+  } else {
+    for (const item of pack.avoidNowChecklist) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  lines.push("", "## 后续命令", "");
+  for (const command of pack.followupCommands) {
+    lines.push(`- \`${command}\``);
+  }
+
+  lines.push(
+    "",
+    "## 内含工件摘要",
+    "",
+    `- decision-log：${pack.decisionLog.totalEntries} 轮`,
+    `- retrospective：${pack.retrospective.retrospectiveStatus}`,
+    `- handoff-bundle：${pack.handoffBundle.summary.executionMode} / ${pack.handoffBundle.summary.executionType}`,
+    "",
+    "## 可直接复制给 Agent 的 Playbook Prompt",
+    "",
+    "```text",
+    pack.playbookPrompt,
+    "```"
+  );
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentPlaybookPackOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/agent-retrospective.js

@@ -0,0 +1,452 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createAgentDecisionLog } from "./agent-decision-log.js";
+import { writeScanOutput } from "./scan.js";
+
+const VALID_FORMATS = new Set(["markdown", "json"]);
+
+function normalizeFormat(format) {
+  const resolved = (format || "markdown").toLowerCase();
+  if (!VALID_FORMATS.has(resolved)) {
+    throw new Error(`不支持的 agent-retrospective 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function cloneForFormat(record, format) {
+  return {
+    ...record,
+    format
+  };
+}
+
+function incrementMapCount(map, key) {
+  if (!key) {
+    return;
+  }
+  map.set(key, (map.get(key) || 0) + 1);
+}
+
+function toSortedFrequencyList(map, formatter) {
+  return [...map.entries()]
+    .sort((left, right) => right[1] - left[1] || String(left[0]).localeCompare(String(right[0])))
+    .map(([key, count]) => formatter(key, count));
+}
+
+async function resolveDecisionLog(input, options = {}) {
+  const resolvedInput = path.resolve(input);
+  if (await pathExists(resolvedInput)) {
+    try {
+      const raw = await fs.readFile(resolvedInput, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed?.kind === "geo-agent-retrospective" && !options.forceRefresh) {
+        return {
+          retrospective: cloneForFormat(parsed, normalizeFormat(options.format)),
+          decisionLog: parsed.decisionLog || null
+        };
+      }
+      if (parsed?.kind === "geo-agent-decision-log") {
+        return {
+          retrospective: null,
+          decisionLog: parsed
+        };
+      }
+    } catch {
+      // Fall through to log generation.
+    }
+  }
+
+  return {
+    retrospective: null,
+    decisionLog: await createAgentDecisionLog(input, { format: "json" })
+  };
+}
+
+function analyzeProgressTrend(entries) {
+  if (entries.length === 0) {
+    return {
+      progressDelta: 0,
+      firstProgress: 0,
+      latestProgress: 0
+    };
+  }
+
+  return {
+    progressDelta: (entries.at(-1)?.progressPercent || 0) - (entries[0]?.progressPercent || 0),
+    firstProgress: entries[0]?.progressPercent || 0,
+    latestProgress: entries.at(-1)?.progressPercent || 0
+  };
+}
+
+function inferRetrospectiveStatus(log, blockerFrequency, decisionCounts, progressTrend) {
+  if (log.latestDecision === "move-to-closeout") {
+    return "ready-for-closeout";
+  }
+  if (
+    log.latestDecision === "resolve-blockers" &&
+    blockerFrequency.length > 0 &&
+    blockerFrequency[0].count >= 2
+  ) {
+    return "repeated-blocker";
+  }
+  if (log.latestDecision === "resolve-blockers") {
+    return "blocked-this-round";
+  }
+  if ((decisionCounts["start-first-packet"] || 0) >= 2) {
+    return "restarting-too-often";
+  }
+  if (progressTrend.progressDelta > 0) {
+    return "advancing";
+  }
+  if (log.totalEntries <= 1) {
+    return "early-cycle";
+  }
+  return "stable-but-flat";
+}
+
+function buildKeyLearnings(log, blockerFrequency, packetFrequency, decisionCounts, progressTrend) {
+  const learnings = [];
+
+  if (blockerFrequency[0]?.count >= 2) {
+    learnings.push(`阻塞「${blockerFrequency[0].title}」重复出现 ${blockerFrequency[0].count} 次，说明进入执行前的上下文准备还不够稳定。`);
+  }
+  if ((decisionCounts["start-first-packet"] || 0) >= 2) {
+    learnings.push("多轮都回到 start-first-packet，说明执行连续性不足，团队还在反复重启。");
+  }
+  if (packetFrequency[0]?.count >= 2) {
+    learnings.push(`当前包 ${packetFrequency[0].id} 在多轮里重复出现，说明这一包是整条链最容易卡住的地方。`);
+  }
+  if (progressTrend.progressDelta > 0) {
+    learnings.push(`整体进度从 ${progressTrend.firstProgress}% 提升到 ${progressTrend.latestProgress}%，说明执行链并非停滞，而是在缓慢推进。`);
+  }
+  if (log.latestDecision === "move-to-closeout") {
+    learnings.push("最新决策已经进入 closeout，下一步重点不是再开新包，而是整理复盘与交付。");
+  }
+  if (log.latestDecision === "resolve-blockers" && blockerFrequency[0]?.count === 1) {
+    learnings.push("当前阻塞是本轮新出现的问题，适合先快速排除，再继续当前包。");
+  }
+
+  if (learnings.length === 0) {
+    learnings.push("当前决策链整体稳定，但还没有足够多的轮次来识别更强的模式。");
+  }
+
+  return learnings;
+}
+
+function buildRepeatedPatterns(blockerFrequency, packetFrequency, decisionCounts) {
+  const patterns = [];
+
+  if (blockerFrequency[0] && blockerFrequency[0].count >= 2) {
+    patterns.push({
+      type: "blocker",
+      label: `重复阻塞：${blockerFrequency[0].title}`,
+      count: blockerFrequency[0].count
+    });
+  }
+  if (packetFrequency[0] && packetFrequency[0].count >= 2) {
+    patterns.push({
+      type: "packet",
+      label: `反复卡在同一包：${packetFrequency[0].id}｜${packetFrequency[0].title}`,
+      count: packetFrequency[0].count
+    });
+  }
+  for (const [decision, count] of Object.entries(decisionCounts)) {
+    if (count >= 2) {
+      patterns.push({
+        type: "decision",
+        label: `重复决策：${decision}`,
+        count
+      });
+    }
+  }
+
+  return patterns.sort((left, right) => right.count - left.count || left.label.localeCompare(right.label));
+}
+
+function buildNextRoundAdvice(log, status, blockerFrequency) {
+  const advice = [];
+
+  if (status === "repeated-blocker") {
+    advice.push("下一轮不要先做页面修改，先把重复出现的阻塞前置清掉。");
+    advice.push("把权限、模板、数据源或生成链问题单独列成 preflight checklist。");
+  } else if (status === "blocked-this-round") {
+    advice.push("这一轮先解除当前阻塞，再回到当前包继续推进。");
+  } else if (status === "ready-for-closeout") {
+    advice.push("下一轮不需要再开新执行包，应直接整理 closeout、meeting pack 和交付包。");
+  } else if (status === "restarting-too-often") {
+    advice.push("下一轮要保持执行连续性，不要再从第一包重新开始。");
+    advice.push("优先沿着最近一次 current packet 继续，而不是重新生成新的执行队列。");
+  } else if (status === "advancing") {
+    advice.push("执行链在推进，下一轮重点是保留当前节奏并继续当前包。");
+  } else {
+    advice.push("下一轮先延续最近一次决策，不要同时改变执行顺序和目标。");
+  }
+
+  if (blockerFrequency[0]?.count >= 2) {
+    advice.push(`把「${blockerFrequency[0].title}」变成固定的进入执行前检查项，避免下一轮再次卡住。`);
+  }
+
+  if (log.currentPacket) {
+    advice.push(`当前最优先仍是 ${log.currentPacket.id}｜${log.currentPacket.title}`);
+  }
+
+  return advice;
+}
+
+function buildSuggestedNextCommand(log, status) {
+  if (status === "ready-for-closeout") {
+    return `geo-ai-search-optimization completion-report ${log.source}`;
+  }
+  if (status === "repeated-blocker" || status === "blocked-this-round") {
+    return log.suggestedNextCommand || `geo-ai-search-optimization agent-runbook ${log.source}`;
+  }
+  if (log.latestDecision === "start-first-packet" || log.latestDecision === "continue-current-packet") {
+    return log.suggestedNextCommand || `geo-ai-search-optimization agent-executor ${log.source}`;
+  }
+  return `geo-ai-search-optimization agent-decision-log ${log.source}`;
+}
+
+function buildFollowupCommands(log, status) {
+  if (status === "ready-for-closeout") {
+    return [
+      `geo-ai-search-optimization completion-report ${log.source}`,
+      `geo-ai-search-optimization meeting-pack ${log.source}`,
+      `geo-ai-search-optimization publish-pack ${log.source}`
+    ];
+  }
+
+  return [
+    buildSuggestedNextCommand(log, status),
+    `geo-ai-search-optimization agent-status-board ${log.source}`,
+    `geo-ai-search-optimization agent-decision-log ${log.source}`
+  ].filter(Boolean);
+}
+
+function buildRoundNarrative(entries) {
+  return entries.map((entry, index) => {
+    const previous = entries[index - 1];
+    let whatChanged = "这是目前的起始轮次。";
+
+    if (previous) {
+      if (previous.decision !== entry.decision) {
+        whatChanged = `决策从 ${previous.decision} 切换到 ${entry.decision}。`;
+      } else if ((previous.progressPercent || 0) !== (entry.progressPercent || 0)) {
+        whatChanged = `进度从 ${previous.progressPercent || 0}% 变化到 ${entry.progressPercent || 0}%。`;
+      } else if ((previous.blockedItems?.length || 0) !== (entry.blockedItems?.length || 0)) {
+        whatChanged = `阻塞数从 ${previous.blockedItems?.length || 0} 变化到 ${entry.blockedItems?.length || 0}。`;
+      } else {
+        whatChanged = "当前轮次延续了上一轮的总体判断。";
+      }
+    }
+
+    return {
+      id: entry.id,
+      createdAt: entry.createdAt,
+      decision: entry.decision,
+      checkpointType: entry.checkpointType,
+      currentPacket: entry.currentPacket,
+      note: entry.note,
+      whatChanged,
+      decisionReason: entry.decisionReason
+    };
+  });
+}
+
+function buildRetrospectivePrompt(report) {
+  const lines = [
+    "你现在进入 GEO 多轮复盘模式。",
+    `当前输入：${report.source}`,
+    `轮次数：${report.totalRounds}`,
+    `当前复盘状态：${report.retrospectiveStatus}`,
+    `最新决策：${report.latestDecision}`,
+    `复盘结论：${report.retrospectiveSummary}`
+  ];
+
+  if (report.recurringBlockers.length > 0) {
+    lines.push(`重复阻塞：${report.recurringBlockers.map((item) => `${item.title} (${item.count})`).join("；")}`);
+  }
+  if (report.currentPacket) {
+    lines.push(`当前包：${report.currentPacket.id}｜${report.currentPacket.title}`);
+  }
+
+  lines.push("请先解释这几轮里发生了什么变化，再给出下一轮最该避免的错误和最该保留的节奏。");
+  lines.push("最后输出建议下一步命令，以及对 PM 和下一位 agent 的简短建议。");
+  return lines.join("\n");
+}
+
+export async function createAgentRetrospective(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const { retrospective, decisionLog } = await resolveDecisionLog(input, { ...options, format });
+
+  if (retrospective) {
+    return retrospective;
+  }
+
+  if (!decisionLog) {
+    throw new Error("无法从当前输入生成 decision log，因此不能创建 retrospective。");
+  }
+
+  const entries = decisionLog.entries || [];
+  const decisionCounts = entries.reduce((accumulator, entry) => {
+    accumulator[entry.decision] = (accumulator[entry.decision] || 0) + 1;
+    return accumulator;
+  }, {});
+
+  const blockerMap = new Map();
+  const packetMap = new Map();
+
+  for (const entry of entries) {
+    for (const blocker of entry.blockedItems || []) {
+      incrementMapCount(blockerMap, blocker.title);
+    }
+    if (entry.currentPacket?.id) {
+      incrementMapCount(packetMap, `${entry.currentPacket.id}|||${entry.currentPacket.title}`);
+    }
+  }
+
+  const recurringBlockers = toSortedFrequencyList(blockerMap, (title, count) => ({
+    title,
+    count
+  }));
+  const repeatedPackets = toSortedFrequencyList(packetMap, (packedValue, count) => {
+    const [id, title] = String(packedValue).split("|||");
+    return { id, title, count };
+  });
+  const progressTrend = analyzeProgressTrend(entries);
+  const retrospectiveStatus = inferRetrospectiveStatus(decisionLog, recurringBlockers, decisionCounts, progressTrend);
+  const keyLearnings = buildKeyLearnings(decisionLog, recurringBlockers, repeatedPackets, decisionCounts, progressTrend);
+  const repeatedPatterns = buildRepeatedPatterns(recurringBlockers, repeatedPackets, decisionCounts);
+  const nextRoundAdvice = buildNextRoundAdvice(decisionLog, retrospectiveStatus, recurringBlockers);
+  const followupCommands = buildFollowupCommands(decisionLog, retrospectiveStatus);
+
+  const report = {
+    kind: "geo-agent-retrospective",
+    input,
+    source: decisionLog.source,
+    sourceType: decisionLog.sourceType,
+    artifactKind: decisionLog.kind,
+    format,
+    totalRounds: decisionLog.totalEntries,
+    retrospectiveStatus,
+    latestDecision: decisionLog.latestDecision,
+    latestDecisionReason: decisionLog.latestDecisionReason,
+    latestCheckpointType: decisionLog.latestCheckpointType,
+    currentPacket: decisionLog.currentPacket,
+    nextPacket: decisionLog.nextPacket,
+    progressTrend,
+    decisionCounts,
+    recurringBlockers,
+    repeatedPackets,
+    repeatedPatterns,
+    retrospectiveSummary: `${decisionLog.logSummary} 当前更适合：${nextRoundAdvice[0]}`,
+    keyLearnings,
+    nextRoundAdvice,
+    suggestedNextCommand: buildSuggestedNextCommand(decisionLog, retrospectiveStatus),
+    followupCommands,
+    roundNarrative: buildRoundNarrative(entries),
+    decisionLog,
+    retrospectivePrompt: ""
+  };
+
+  report.retrospectivePrompt = buildRetrospectivePrompt(report);
+  return report;
+}
+
+export function renderAgentRetrospectiveMarkdown(report) {
+  const lines = [
+    "# GEO Agent Retrospective",
+    "",
+    `- 输入：\`${report.source}\``,
+    `- 来源类型：\`${report.sourceType}\``,
+    `- 决策工件：\`${report.artifactKind}\``,
+    `- 轮次数：\`${report.totalRounds}\``,
+    `- 当前复盘状态：\`${report.retrospectiveStatus}\``,
+    `- 最新决策：\`${report.latestDecision}\``,
+    `- 最新检查点类型：\`${report.latestCheckpointType}\``,
+    `- 复盘总结：${report.retrospectiveSummary}`,
+    ""
+  ];
+
+  if (report.currentPacket) {
+    lines.push("## 当前包", "", `- ${report.currentPacket.id}｜${report.currentPacket.title}`);
+    lines.push(`- Owner：${report.currentPacket.owner}`);
+    lines.push(`- 优先级：${report.currentPacket.priority}`);
+    lines.push("");
+  }
+
+  if (report.nextPacket) {
+    lines.push("## 下一包", "", `- ${report.nextPacket.id}｜${report.nextPacket.title}`);
+    lines.push(`- Owner：${report.nextPacket.owner}`);
+    lines.push(`- 优先级：${report.nextPacket.priority}`);
+    lines.push("");
+  }
+
+  lines.push("## 重复模式", "");
+  if (report.repeatedPatterns.length === 0) {
+    lines.push("- 当前还没有明显重复模式。", "");
+  } else {
+    for (const pattern of report.repeatedPatterns) {
+      lines.push(`- ${pattern.label}｜出现 ${pattern.count} 次`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## 关键学习", "");
+  for (const item of report.keyLearnings) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 下一轮建议", "");
+  for (const item of report.nextRoundAdvice) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 决策分布", "");
+  for (const [decision, count] of Object.entries(report.decisionCounts)) {
+    lines.push(`- ${decision}：${count} 次`);
+  }
+
+  lines.push("", "## 轮次时间线", "");
+  for (const round of report.roundNarrative) {
+    lines.push(`### ${round.id}`);
+    lines.push("");
+    lines.push(`- 时间：\`${round.createdAt}\``);
+    lines.push(`- 决策：\`${round.decision}\``);
+    lines.push(`- 检查点类型：\`${round.checkpointType}\``);
+    lines.push(`- 原因：${round.decisionReason}`);
+    lines.push(`- 变化：${round.whatChanged}`);
+    if (round.currentPacket) {
+      lines.push(`- 当前包：${round.currentPacket.id}｜${round.currentPacket.title}`);
+    }
+    if (round.note) {
+      lines.push(`- 备注：${round.note}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## 建议下一步命令", "", `- \`${report.suggestedNextCommand}\``);
+
+  if (report.followupCommands.length > 0) {
+    lines.push("", "## 后续命令", "");
+    for (const command of report.followupCommands) {
+      lines.push(`- \`${command}\``);
+    }
+  }
+
+  lines.push("", "## 可直接复制给 Agent 的 Retrospective Prompt", "", "```text", report.retrospectivePrompt, "```");
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentRetrospectiveOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/agent-session.js

@@ -67,6 +67,12 @@ function inferSkillForCommand(commandName, flow) {
   if (commandName === "agent-decision-log") {
     return "geo-ai-search-optimization-agent-decision-log";
   }
+  if (commandName === "agent-retrospective") {
+    return "geo-ai-search-optimization-agent-retrospective";
+  }
+  if (commandName === "agent-playbook-pack") {
+    return "geo-ai-search-optimization-agent-playbook-pack";
+  }
   if (commandName === "skills" || commandName === "quick-start") {
     return "geo-ai-search-optimization-usage";
   }
@@ -141,6 +147,10 @@ function inferStepPurpose(commandName, flow) {
       return "把当前阶段压成继续 / 阻塞 / 收尾的决策检查点。";
     case "agent-decision-log":
       return "把每一轮 checkpoint 沉淀成可继承的决策历史。";
+    case "agent-retrospective":
+      return "把多轮决策历史压成复盘结论、重复模式和下一轮建议。";
+    case "agent-playbook-pack":
+      return "把复盘、决策历史和交接信息压成下一位 agent 的单入口执行包。";
     case "apply-plan":
       return "把交接结果推进到具体执行包。";
     case "completion-report":
@@ -195,6 +205,10 @@ function inferExpectedArtifact(commandName) {
       return "agent 阶段检查点工件";
     case "agent-decision-log":
       return "agent 决策历史工件";
+    case "agent-retrospective":
+      return "agent 多轮复盘工件";
+    case "agent-playbook-pack":
+      return "agent 单入口 playbook 包";
     case "apply-plan":
       return "执行包";
     case "completion-report":
@@ -248,6 +262,12 @@ function buildStepInstructions(parsedCommand, flow) {
   if (parsedCommand.commandName === "agent-decision-log") {
     lines.push("这一步用于保留跨轮决策历史，方便下一位 agent 直接承接上一次判断。");
   }
+  if (parsedCommand.commandName === "agent-retrospective") {
+    lines.push("这一步用于总结为什么前几轮卡住或推进顺利，并把这些模式转成下一轮建议。");
+  }
+  if (parsedCommand.commandName === "agent-playbook-pack") {
+    lines.push("这一步用于把多轮复盘和交接结果压成单入口执行包，方便下一位 agent 直接开始。");
+  }
   if (parsedCommand.commandName === "agent-handoff" && flow.intent === "execute") {
     lines.push("如果还是 advice-only，说明还缺仓库或本地项目上下文。");
   }

package/src/auto-flow.js

@@ -59,6 +59,12 @@ function inferTaskTextMode(text) {
   if (/(decision-log|decision log|决策历史|决策日志|为什么这样决定|历史决策)/i.test(normalized)) {
     return "execute";
   }
+  if (/(playbook-pack|playbook pack|playbook 包|agent playbook|单入口执行包|复盘执行包|接着干的入口)/i.test(normalized)) {
+    return "execute";
+  }
+  if (/(retrospective|retro|多轮复盘|执行复盘|为什么总卡住|经验总结|回顾前几轮)/i.test(normalized)) {
+    return "closeout";
+  }
   if (/(executor|先做哪一个|先做哪一包|single task|执行第一包|先执行一个任务)/i.test(normalized)) {
     return "execute";
   }
@@ -159,6 +165,12 @@ function resolveEffectiveIntent(intent, detected) {
   if (detected.artifactKind === "geo-completion-report") {
     return "closeout";
   }
+  if (detected.artifactKind === "geo-agent-retrospective") {
+    return "closeout";
+  }
+  if (detected.artifactKind === "geo-agent-playbook-pack") {
+    return detected.parsed?.playbookStatus === "closeout-ready" ? "closeout" : "execute";
+  }
   if (
     [
       "geo-share-pack",
@@ -403,6 +415,26 @@ function buildCommandChain(detected, intent) {
               `geo-ai-search-optimization agent-decision-log ${baseSource} --append-from ${source}`
             ];
     }
+    case "geo-agent-retrospective":
+      return [
+        `geo-ai-search-optimization completion-report ${source}`,
+        `geo-ai-search-optimization meeting-pack ${source}`,
+        `geo-ai-search-optimization publish-pack ${source}`
+      ];
+    case "geo-agent-playbook-pack": {
+      const baseSource = detected.parsed?.source || source;
+      return detected.parsed?.playbookStatus === "closeout-ready"
+        ? [
+            detected.parsed?.startCommand || `geo-ai-search-optimization completion-report ${baseSource}`,
+            `geo-ai-search-optimization meeting-pack ${baseSource}`,
+            `geo-ai-search-optimization publish-pack ${baseSource}`
+          ]
+        : [
+            detected.parsed?.startCommand || `geo-ai-search-optimization agent-executor ${baseSource}`,
+            `geo-ai-search-optimization agent-status-board ${baseSource}`,
+            `geo-ai-search-optimization agent-decision-log ${baseSource}`
+          ];
+    }
     case "geo-apply-plan":
       return [
         `geo-ai-search-optimization agent-executor ${source}`,
@@ -486,6 +518,10 @@ function pickSkillName(detected, intent) {
       return "geo-ai-search-optimization-agent-checkpoint";
     case "geo-agent-decision-log":
       return "geo-ai-search-optimization-agent-decision-log";
+    case "geo-agent-retrospective":
+      return "geo-ai-search-optimization-agent-retrospective";
+    case "geo-agent-playbook-pack":
+      return "geo-ai-search-optimization-agent-playbook-pack";
     case "geo-completion-report":
       return "geo-ai-search-optimization-completion-report";
     case "geo-handoff-bundle":
@@ -527,6 +563,7 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
       "geo-agent-status-board",
       "geo-agent-checkpoint",
       "geo-agent-decision-log",
+      "geo-agent-playbook-pack",
       "geo-apply-plan"
     ].includes(
       detected.artifactKind
@@ -537,6 +574,7 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
     names.add("geo-ai-search-optimization-agent-status-board");
     names.add("geo-ai-search-optimization-agent-checkpoint");
     names.add("geo-ai-search-optimization-agent-decision-log");
+    names.add("geo-ai-search-optimization-agent-playbook-pack");
     names.add("geo-ai-search-optimization-agent-executor");
     names.add("geo-ai-search-optimization-agent-runbook");
     names.add("geo-ai-search-optimization-agent-handoff");
@@ -544,6 +582,7 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
   }
   if (intent === "closeout") {
     names.add("geo-ai-search-optimization-completion-report");
+    names.add("geo-ai-search-optimization-agent-retrospective");
   }
 
   names.delete(primarySkill);
@@ -571,6 +610,8 @@ function buildStage(intent, detected) {
       "geo-agent-status-board",
       "geo-agent-checkpoint",
       "geo-agent-decision-log",
+      "geo-agent-playbook-pack",
+      "geo-agent-retrospective",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)
@@ -588,6 +629,8 @@ function buildStage(intent, detected) {
       "geo-agent-status-board",
       "geo-agent-checkpoint",
       "geo-agent-decision-log",
+      "geo-agent-playbook-pack",
+      "geo-agent-retrospective",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)
@@ -680,9 +723,15 @@ function buildNextAction(detected, intent, commands) {
     if (detected.artifactKind === "geo-agent-decision-log") {
       return `先运行 \`${commands[0]}\`，沿着最近一次阶段决策继续推进，而不是重新判断整条链。`;
     }
+    if (detected.artifactKind === "geo-agent-playbook-pack") {
+      return `先运行 \`${commands[0]}\`，直接沿着 playbook 的起始命令继续，不要重新拆链。`;
+    }
     return `先运行 \`${commands[0]}\`，把当前输入推进到 agent 可执行状态。`;
   }
   if (intent === "closeout") {
+    if (detected.artifactKind === "geo-agent-retrospective") {
+      return `先运行 \`${commands[0]}\`，把多轮复盘结论整理成正式 closeout 与交付结果。`;
+    }
     return `先运行 \`${commands[0]}\`，整理本轮完成情况和剩余风险。`;
   }
   if (intent === "guide") {

package/src/cli.js

@@ -16,6 +16,12 @@ import {
 } from "./agent-progress-tracker.js";
 import { createAgentCheckpoint, renderAgentCheckpointMarkdown, writeAgentCheckpointOutput } from "./agent-checkpoint.js";
 import { createAgentDecisionLog, renderAgentDecisionLogMarkdown, writeAgentDecisionLogOutput } from "./agent-decision-log.js";
+import {
+  createAgentPlaybookPack,
+  renderAgentPlaybookPackMarkdown,
+  writeAgentPlaybookPackOutput
+} from "./agent-playbook-pack.js";
+import { createAgentRetrospective, renderAgentRetrospectiveMarkdown, writeAgentRetrospectiveOutput } from "./agent-retrospective.js";
 import { createAgentStatusBoard, renderAgentStatusBoardMarkdown, writeAgentStatusBoardOutput } from "./agent-status-board.js";
 import { createAgentRunbook, renderAgentRunbookMarkdown, writeAgentRunbookOutput } from "./agent-runbook.js";
 import { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
@@ -83,6 +89,8 @@ function printHelp() {
       "  geo-ai-search-optimization agent-status-board <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization agent-checkpoint <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization agent-decision-log <input> [--append-from <file>] [--note <text>] [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
+      "  geo-ai-search-optimization agent-retrospective <input> [--format <markdown|json>] [--out <file>]",
+      "  geo-ai-search-optimization agent-playbook-pack <input> [--task <id>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization skills [--json]",
       "  geo-ai-search-optimization where",
       "  geo-ai-search-optimization doctor [--json]",
@@ -395,6 +403,57 @@ async function handleAgentDecisionLog(args) {
   process.stdout.write(renderedOutput);
 }
 
+async function handleAgentRetrospective(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("agent-retrospective 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
+  }
+
+  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
+  const retrospective = await createAgentRetrospective(input, {
+    format
+  });
+  const outputJson = retrospective.format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(retrospective, null, 2)}\n`
+    : renderAgentRetrospectiveMarkdown(retrospective);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeAgentRetrospectiveOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 agent retrospective：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
+async function handleAgentPlaybookPack(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("agent-playbook-pack 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
+  }
+
+  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
+  const pack = await createAgentPlaybookPack(input, {
+    format,
+    taskId: getFlagValue(args, "--task")
+  });
+  const outputJson = pack.format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(pack, null, 2)}\n`
+    : renderAgentPlaybookPackMarkdown(pack);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeAgentPlaybookPackOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 agent playbook pack：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
 function handleWhere() {
   process.stdout.write(
     [
@@ -980,6 +1039,16 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "agent-retrospective") {
+    await handleAgentRetrospective(rest);
+    return;
+  }
+
+  if (command === "agent-playbook-pack") {
+    await handleAgentPlaybookPack(rest);
+    return;
+  }
+
   if (command === "skills") {
     await handleSkills(rest);
     return;

package/src/completion-report.js

@@ -131,6 +131,37 @@ async function resolveApplyPlan(input) {
     return parsed;
   }
 
+  if (parsed.kind === "geo-handoff-bundle" && parsed.applyPlan?.kind === "geo-apply-plan") {
+    return parsed.applyPlan;
+  }
+
+  if (parsed.kind === "geo-agent-progress-tracker" && parsed.applyPlan?.kind === "geo-apply-plan") {
+    return parsed.applyPlan;
+  }
+
+  if (parsed.kind === "geo-agent-status-board" && parsed.tracker?.applyPlan?.kind === "geo-apply-plan") {
+    return parsed.tracker.applyPlan;
+  }
+
+  if (parsed.kind === "geo-agent-checkpoint" && parsed.statusBoard?.tracker?.applyPlan?.kind === "geo-apply-plan") {
+    return parsed.statusBoard.tracker.applyPlan;
+  }
+
+  if (parsed.kind === "geo-agent-decision-log") {
+    return createApplyPlan(parsed.source || parsed.latestCheckpoint?.source || resolvedPath, { format: "json" });
+  }
+
+  if (
+    parsed.kind === "geo-agent-retrospective" &&
+    parsed.decisionLog?.latestCheckpoint?.statusBoard?.tracker?.applyPlan?.kind === "geo-apply-plan"
+  ) {
+    return parsed.decisionLog.latestCheckpoint.statusBoard.tracker.applyPlan;
+  }
+
+  if (parsed.kind === "geo-agent-playbook-pack" && parsed.handoffBundle?.applyPlan?.kind === "geo-apply-plan") {
+    return parsed.handoffBundle.applyPlan;
+  }
+
   return createApplyPlan(resolvedPath, { format: "json" });
 }
 

package/src/index.js

@@ -10,6 +10,8 @@ export { createApplyPlan, renderApplyPlanMarkdown, writeApplyPlanOutput } from "
 export { createAgentBatchExecutor, renderAgentBatchExecutorMarkdown, writeAgentBatchExecutorOutput } from "./agent-batch-executor.js";
 export { createAgentCheckpoint, renderAgentCheckpointMarkdown, writeAgentCheckpointOutput } from "./agent-checkpoint.js";
 export { createAgentDecisionLog, renderAgentDecisionLogMarkdown, writeAgentDecisionLogOutput } from "./agent-decision-log.js";
+export { createAgentPlaybookPack, renderAgentPlaybookPackMarkdown, writeAgentPlaybookPackOutput } from "./agent-playbook-pack.js";
+export { createAgentRetrospective, renderAgentRetrospectiveMarkdown, writeAgentRetrospectiveOutput } from "./agent-retrospective.js";
 export { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
 export { createAgentExecutor, renderAgentExecutorMarkdown, writeAgentExecutorOutput } from "./agent-executor.js";
 export {

package/src/skills.js

@@ -13,6 +13,8 @@ const SKILL_ORDER = [
   "geo-ai-search-optimization-agent-status-board",
   "geo-ai-search-optimization-agent-checkpoint",
   "geo-ai-search-optimization-agent-decision-log",
+  "geo-ai-search-optimization-agent-retrospective",
+  "geo-ai-search-optimization-agent-playbook-pack",
   "geo-ai-search-optimization-usage",
   "geo-ai-search-optimization-agent-handoff",
   "geo-ai-search-optimization-repair-loop",
@@ -35,6 +37,8 @@ const SKILL_CATEGORY = {
   "geo-ai-search-optimization-agent-status-board": "execution",
   "geo-ai-search-optimization-agent-checkpoint": "execution",
   "geo-ai-search-optimization-agent-decision-log": "execution",
+  "geo-ai-search-optimization-agent-retrospective": "execution",
+  "geo-ai-search-optimization-agent-playbook-pack": "execution",
   "geo-ai-search-optimization-usage": "guidance",
   "geo-ai-search-optimization-agent-handoff": "execution",
   "geo-ai-search-optimization-repair-loop": "execution",
@@ -176,6 +180,8 @@ export function renderBundledSkillsMarkdown(bundle) {
     "- 如果要把当前执行状态直接整理成看板，再进入 agent-status-board。",
     "- 如果要在每轮结束时做继续 / 阻塞 / 收尾决策，再进入 agent-checkpoint。",
     "- 如果要把多轮决策沉淀成可继承的历史，再进入 agent-decision-log。",
+    "- 如果要总结多轮为什么推进顺利或反复卡住，再进入 agent-retrospective。",
+    "- 如果要把复盘、决策和交接压成下一位 agent 的单入口，再进入 agent-playbook-pack。",
     "- 再看 usage skill，知道什么时候该跑哪个命令。",
     "- 如果要交给 agent 执行，再进入 handoff / apply / completion 这一条执行链。",
     "- 如果要产出给团队分发，再进入 share / export / html / publish 这一条交付链。",