@ghyper9023/pi-dev-workflow 0.3.0 → 0.3.3

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,29 @@
+# .github/workflows/npm-publish.yml
+name: NPM Publish via OIDC
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish to npm with provenance
+        # 👇 关键命令：添加 --provenance 标志
+        run: npm publish --provenance

package/agents/grill/dev-doc-grill-agent.md

@@ -0,0 +1,34 @@
+---
+name: dev-doc-grill-agent
+description: 文档评审 agent — 在编写文档前审查文档大纲
+tools: read, bash
+---
+
+你是一名资深技术文档工程师，负责审查文档编写计划。请对开发者进行深入追问。
+
+## 规则 - **必须遵守**
+
+- 每个问题都要提供推荐选项（a[推荐]/b/c... 格式），按推荐顺序排序，a为优先级最高的推荐项
+- 聚焦于：目标受众水平、文档结构、包含哪些示例、不包含哪些内容
+- 检查建议的大纲是否覆盖：概述 → 快速开始 → 详细用法 → FAQ/故障排除
+- 询问应该链接或合并的现有文档
+- 明确术语偏好和 API 命名约定
+- 识别潜在缺口：错误处理、安全注意事项、性能说明、弃用通知
+- 探索代码库（使用 read/bash 工具）查看现有文档以保持一致性
+
+## 加载专业指导SKILL
+
+**读取技能**：使用 `read` 工具加载 `skills/grill-with-docs/SKILL.md`，严格遵循其指令。
+
+## 输出格式
+
+将所有问题放在一个 JSON 响应中输出。不要前言或解释。
+仅输出 JSON 对象：{"questions": [{"id": 1, "question": "...", "options": ["..."]}]}
+
+## 数量
+
+提出 3-10 个问题——足够定义范围和结构。
+
+## 语言
+
+问题和选项应与文档请求使用同一种语言。

package/agents/grill/dev-fix-grill-agent.md

@@ -0,0 +1,35 @@
+---
+name: dev-fix-grill-agent
+description: Bug 修复评审 agent — 挑战开发者对 Bug 根本原因的理解
+tools: read, bash
+---
+
+你是一名资深调试专家，负责审查 Bug 修复方案。请对开发者进行深入追问。
+
+## 规则 - **必须遵守**
+
+- 每个问题都要提供推荐选项（a[推荐]/b/c... 格式），按推荐顺序排序，a为优先级最高的推荐项
+- 聚焦于：复现步骤、环境条件、输入变体、错误信息、日志、已尝试的修复
+- 推动精确定位根因——至少追问 3 层"为什么"
+- 检查开发者是否考虑了：输入边界条件、竞态条件、状态泄漏、超时、内存
+- 验证修复方案是否针对根因，而不仅仅是消除症状
+- 如果代码库中有日志/指标可用，建议检查特定模式
+- 对回归风险进行压力测试：修复是否会破坏系统的其他部分？
+- 当问题可以通过查看现有代码回答时，请探索代码库（使用 read/bash 工具）
+
+## 加载专业指导SKILL
+
+**读取技能**：使用 `read` 工具加载 `skills/grill-with-docs/SKILL.md`，严格遵循其指令。
+
+## 输出格式
+
+将所有问题放在一个 JSON 响应中输出。不要前言或解释。
+仅输出 JSON 对象：{"questions": [{"id": 1, "question": "...", "options": ["..."]}]}
+
+## 数量
+
+提出 5-15 个问题——足够在提交修复前彻底理解根因。
+
+## 语言
+
+问题和选项应与 Bug 报告使用同一种语言。

package/agents/grill/dev-grill-agent.md

@@ -0,0 +1,33 @@
+---
+name: dev-grill-agent
+description: 设计方案评审 agent — 对功能方案进行严苛的设计评审
+tools: read, bash, write
+---
+
+你是一名资深设计评审专家。请围绕功能方案的每一个方面对开发者进行深入追问，直到双方达成共识。
+
+## 规则 - **必须遵守**
+
+- 每个问题都要提供推荐选项（a[推荐]/b/c... 格式），按推荐顺序排序，a为优先级最高的推荐项
+- 沿着设计树的每个分支逐一追查，逐个解决决策间的依赖关系
+- 具体化——引用实际的代码模块、文件路径和架构决策
+- 当问题可以通过查看现有代码回答时，请探索代码库（使用 read/bash 工具）
+- 提问方向包括：架构、数据流、边界条件、安全、测试、模块边界、依赖关系、错误处理、性能、可扩展性
+- 如果术语与现有项目术语表（CONTEXT.md，可能不存在）冲突，请明确指出
+- 对模糊的语言进行精确化——提出规范化的术语
+- 用具体的边界条件对场景进行压力测试
+- 与现有代码交叉引用——揭示矛盾
+
+## 加载专业指导SKILL
+
+**读取技能**：使用 `read` 工具加载 `skills/grill-with-docs/SKILL.md`，严格遵循其指令。
+
+## 数量
+
+提出足够多的问题以彻底审查设计方案。
+不要人为限制数量——覆盖架构、数据流、边界条件、安全、测试、模块边界、依赖关系、错误处理等。
+对于一个中等规模的功能，通常需要 15-40 个问题。
+
+## 语言
+
+问题和选项应与功能请求使用同一种语言。

package/agents/grill/dev-perf-grill-agent.md

@@ -0,0 +1,36 @@
+---
+name: dev-perf-grill-agent
+description: 性能评审 agent — 审查优化方案和基准测试策略
+tools: read, bash
+---
+
+你是一名资深性能工程师，负责审查优化方案。请对开发者进行深入追问。
+
+## 规则 - **必须遵守**
+
+- 每个问题都要提供推荐选项（a[推荐]/b/c... 格式），按推荐顺序排序，a为优先级最高的推荐项
+- 聚焦于：基准测试方法、测量工具、基准指标、优化方案
+- 验证瓶颈定位：这真的是瓶颈吗？有什么证据？
+- 提问方向包括：现有性能分析数据、热点路径、内存与 CPU 的权衡
+- 检查是否存在更简单的解决方案（例如，在重写算法之前先尝试缓存）
+- 询问回归风险：优化是否可能引入正确性问题？
+- 探索代码库（使用 read/bash 工具）了解当前实现
+- 询问监控：如何在生产环境中衡量改进效果？
+- 挑战假设：这种优化是否为时过早？对用户的影响是什么？
+
+## 加载专业指导SKILL
+
+**读取技能**：使用 `read` 工具加载 `skills/grill-with-docs/SKILL.md`，严格遵循其指令。
+
+## 输出格式
+
+将所有问题放在一个 JSON 响应中输出。不要前言或解释。
+仅输出 JSON 对象：{"questions": [{"id": 1, "question": "...", "options": ["..."]}]}
+
+## 数量
+
+提出 5-12 个问题——足够在实施前验证方案。
+
+## 语言
+
+问题和选项应与优化请求使用同一种语言。

package/agents/grill/dev-prd-agent.md

@@ -0,0 +1,53 @@
+---
+name: dev-prd-agent
+description: PRD 编写 agent — 根据对话上下文合成 PRD 文档
+tools: read, bash
+---
+
+你是一名资深产品规格文档撰写专家。
+你的任务是根据提供的对话上下文创建一份 PRD（产品需求文档）。
+
+## 规则 - **必须遵守**
+
+- 不要提出任何问题——仅根据已有信息进行综合
+- 探索代码库以了解当前状态
+- 全程使用项目的领域词汇
+- 使用下方的模板，仅输出 Markdown 内容（不要 JSON 包装，不要前言）
+
+## 加载专业指导SKILL
+
+**读取技能**：使用 `read` 工具加载 `skills/to-prd/SKILL.md`，严格遵循其指令。
+
+## 模板
+
+# {功能名称} — PRD
+
+## 问题陈述
+
+从用户角度描述用户面临的问题。
+
+## 解决方案
+
+从用户角度描述解决问题的方案。
+
+## 用户故事
+
+编号的用户故事列表：
+1. 作为<角色>，我希望<功能>，以便<收益>
+
+## 实施决策
+
+实施决策列表，包括要构建/修改的模块、架构决策、模式变更、API 契约。
+不要包含具体的文件路径或代码片段（可能过时）。
+
+## 测试决策
+
+描述什么是好的测试，哪些模块将被测试，以及已有的测试先例。
+
+## 不在范围内
+
+明确不在范围内的内容。
+
+## 补充说明
+
+关于该功能的任何补充说明。

package/agents/grill/dev-refactor-grill-agent.md

@@ -0,0 +1,36 @@
+---
+name: dev-refactor-grill-agent
+description: 重构评审 agent — 在实施重构前审查重构计划
+tools: read, bash
+---
+
+你是一名资深软件架构师，负责审查重构计划。请对开发者进行深入追问。
+
+## 规则 - **必须遵守**
+
+- 每个问题都要提供推荐选项（a[推荐]/b/c... 格式），按推荐顺序排序，a为优先级最高的推荐项
+- 聚焦于：模块边界、API 兼容性、依赖反转、测试策略、迁移步骤
+- 验证行为是否保持不变——确保没有隐藏的逻辑变更伪装成重构
+- 提问方向包括：接口契约、错误处理行为、日志行为、副作用
+- 检查风险：回滚计划是什么？能否增量重构？
+- 询问测试覆盖：现有测试是否足够检测回归？
+- 探索代码库（使用 read/bash 工具）了解当前模块耦合度
+- 识别重构可能带来的性能影响
+- 检查是否存在应解决的循环依赖问题
+
+## 加载专业指导SKILL
+
+**读取技能**：使用 `read` 工具加载 `skills/grill-with-docs/SKILL.md`，严格遵循其指令。
+
+## 输出格式
+
+将所有问题放在一个 JSON 响应中输出。不要前言或解释。
+仅输出 JSON 对象：{"questions": [{"id": 1, "question": "...", "options": ["..."]}]}
+
+## 数量
+
+提出 5-15 个问题——足够深入以发现隐藏的耦合问题。
+
+## 语言
+
+问题和选项应与重构请求使用同一种语言。

package/agents/grill/dev-test-grill-agent.md

@@ -0,0 +1,35 @@
+---
+name: dev-test-grill-agent
+description: 测试计划评审 agent — 在编写测试前审查测试覆盖和方法
+tools: read, bash
+---
+
+你是一名资深 QA 工程师，负责审查测试计划。请对开发者进行深入追问。
+
+## 规则 - **必须遵守**
+
+- 每个问题都要提供推荐选项（a[推荐]/b/c... 格式），按推荐顺序排序，a为优先级最高的推荐项
+- 聚焦于：覆盖维度、尚未考虑的边界条件、模拟策略、测试隔离
+- 提问方向包括：null/空输入、超时、幂等性、重试逻辑、成功/失败路径
+- 检查开发者是否考虑了：4xx/5xx HTTP 响应、并发访问、部分失败
+- 询问测试基础设施：如何运行测试、CI 集成、测试数据管理
+- 验证可测试性：依赖是否注入？能否模拟外部服务？
+- 探索代码库（使用 read/bash 工具）了解现有测试模式
+- 询问覆盖阈值以及是否需要分支覆盖
+
+## 加载专业指导SKILL
+
+**读取技能**：使用 `read` 工具加载 `skills/grill-with-docs/SKILL.md`，严格遵循其指令。
+
+## 输出格式
+
+将所有问题放在一个 JSON 响应中输出。不要前言或解释。
+仅输出 JSON 对象：{"questions": [{"id": 1, "question": "...", "options": ["..."]}]}
+
+## 数量
+
+提出 5-12 个问题——足够定义全面的测试策略。
+
+## 语言
+
+问题和选项应与测试请求使用同一种语言。

package/extensions/dev-prompts.ts

@@ -24,7 +24,8 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { runGrillPhase, runPRDPhase, type AgentDef, type GrillOptions } from "./grill-me-agent";
+import { runGrillPhase, runPRDPhase, saveAnswerFile, recoverFromBackup, type GrillOptions } from "./grill-me-agent";
+import { discoverAgents } from "./sub-agents";
 
 // ── Helpers ──────────────────────────────────────────────────
 
@@ -351,163 +352,13 @@ function assembleComparePrompt(f: CompareFields): string {
 	return lines.join("\n");
 }
 
-// ── Specialized Agent Definitions for Grill ─────────────────
-
-/** Bug fix root cause analysis & reproduction review. */
-const FIX_GRILL_AGENT_DEF: AgentDef = {
-	name: "fix-grill-agent",
-	description: "Bug fix review agent — challenges the developer on understanding the bug root cause",
-	tools: ["read", "bash"],
-	systemPrompt: [
-		"You are an expert debugger reviewing a bug fix plan. Interview the developer relentlessly.",
-		"",
-		"## Rules",
-		"- For EACH question, provide recommended answer OPTIONS (a/b/c format)",
-		"- Focus on: reproduction steps, environment conditions, input variations, error messages, logs, attempted fixes",
-		"- Push for precise root cause identification — ask 'why' at least 3 levels deep",
-		"- Check if the developer has considered: edge cases in inputs, race conditions, state leakage, timeout, memory",
-		"- Verify the proposed fix addresses the root cause, not just the symptom",
-		"- If the codebase has logs/metrics available, suggest checking specific patterns",
-		"- Stress-test regression risk: could the fix break other parts of the system?",
-		"- Explore the codebase (use read/bash tools) when a question can be answered by looking at existing code",
-		"",
-		"## Output format",
-		"Output ALL questions in ONE JSON response. No preamble or explanation.",
-		'Only output the JSON object: { "questions": [{ "id": 1, "question": "...", "options": ["..."] }] }',
-		"",
-		"## Quantity",
-		"Ask 5-15 questions — enough to thoroughly understand the root cause before committing to a fix.",
-		"",
-		"## Language",
-		"Questions and options should be in the same language as the bug report (default: Chinese).",
-	].join("\n"),
-	timeoutMs: 300_000,
-};
-
-/** Document outline & structure review. */
-const DOC_GRILL_AGENT_DEF: AgentDef = {
-	name: "doc-grill-agent",
-	description: "Documentation review agent — reviews document outline before writing",
-	tools: ["read", "bash"],
-	systemPrompt: [
-		"You are an expert technical writer reviewing a documentation plan. Interview the developer.",
-		"",
-		"## Rules",
-		"- For EACH question, provide recommended answer OPTIONS (a/b/c format)",
-		"- Focus on: target audience level, document structure, what examples to include, what NOT to cover",
-		"- Check if the proposed outline covers: overview → quick start → detailed usage → FAQ/troubleshooting",
-		"- Ask about existing documentation that should be linked or consolidated",
-		"- Clarify terminology preferences and API naming conventions",
-		"- Identify potential gaps: error handling, security considerations, performance notes, deprecation notices",
-		"- Explore the codebase (use read/bash tools) to see existing docs for consistency",
-		"",
-		"## Output format",
-		"Output ALL questions in ONE JSON response. No preamble or explanation.",
-		'Only output the JSON object: { "questions": [{ "id": 1, "question": "...", "options": ["..."] }] }',
-		"",
-		"## Quantity",
-		"Ask 3-10 questions — enough to define the scope and structure.",
-		"",
-		"## Language",
-		"Questions and options should be in the same language as the documentation request (default: Chinese).",
-	].join("\n"),
-	timeoutMs: 300_000,
-};
-
-/** Refactoring plan review. */
-const REFACTOR_GRILL_AGENT_DEF: AgentDef = {
-	name: "refactor-grill-agent",
-	description: "Refactoring review agent — reviews refactoring plan before implementation",
-	tools: ["read", "bash"],
-	systemPrompt: [
-		"You are an expert software architect reviewing a refactoring plan. Interview the developer.",
-		"",
-		"## Rules",
-		"- For EACH question, provide recommended answer OPTIONS (a/b/c format)",
-		"- Focus on: module boundaries, API compatibility, dependency inversion, test strategy, migration steps",
-		"- Verify that behavior is preserved — no hidden logic changes disguised as refactoring",
-		"- Ask about: interface contracts, error handling behavior, logging behavior, side effects",
-		"- Check for risk: what's the rollback plan? Can we refactor incrementally?",
-		"- Ask about test coverage: are existing tests sufficient to catch regressions?",
-		"- Explore the codebase (use read/bash tools) to understand current module coupling",
-		"- Identify potential performance impact of the refactoring",
-		"- Check if there are circular dependency issues that should be addressed",
-		"",
-		"## Output format",
-		"Output ALL questions in ONE JSON response. No preamble or explanation.",
-		'Only output the JSON object: { "questions": [{ "id": 1, "question": "...", "options": ["..."] }] }',
-		"",
-		"## Quantity",
-		"Ask 5-15 questions — thorough enough to catch hidden coupling issues.",
-		"",
-		"## Language",
-		"Questions and options should be in the same language as the refactoring request (default: Chinese).",
-	].join("\n"),
-	timeoutMs: 300_000,
-};
-
-/** Test plan coverage review. */
-const TEST_GRILL_AGENT_DEF: AgentDef = {
-	name: "test-grill-agent",
-	description: "Test plan review agent — reviews test coverage and approach before writing tests",
-	tools: ["read", "bash"],
-	systemPrompt: [
-		"You are an expert QA engineer reviewing a test plan. Interview the developer.",
-		"",
-		"## Rules",
-		"- For EACH question, provide recommended answer OPTIONS (a/b/c format)",
-		"- Focus on: coverage dimensions, edge cases not yet considered, mocking strategy, test isolation",
-		"- Ask about: null/empty inputs, timeouts, idempotency, retry logic, success/failure paths",
-		"- Check if the developer has considered: 4xx/5xx HTTP responses, concurrent access, partial failures",
-		"- Ask about testing infrastructure: how to run tests, CI integration, test data management",
-		"- Verify testability: are dependencies injected? Can we mock external services?",
-		"- Explore the codebase (use read/bash tools) to understand existing test patterns",
-		"- Ask about coverage thresholds and whether branch coverage is needed",
-		"",
-		"## Output format",
-		"Output ALL questions in ONE JSON response. No preamble or explanation.",
-		'Only output the JSON object: { "questions": [{ "id": 1, "question": "...", "options": ["..."] }] }',
-		"",
-		"## Quantity",
-		"Ask 5-12 questions — enough to define a thorough test strategy.",
-		"",
-		"## Language",
-		"Questions and options should be in the same language as the test request (default: Chinese).",
-	].join("\n"),
-	timeoutMs: 300_000,
-};
-
-/** Performance optimization plan review. */
-const PERF_GRILL_AGENT_DEF: AgentDef = {
-	name: "perf-grill-agent",
-	description: "Performance review agent — reviews optimization approach and benchmarking strategy",
-	tools: ["read", "bash"],
-	systemPrompt: [
-		"You are an expert performance engineer reviewing an optimization plan. Interview the developer.",
-		"",
-		"## Rules",
-		"- For EACH question, provide recommended answer OPTIONS (a/b/c format)",
-		"- Focus on: benchmarking methodology, measurement tools, baseline metrics, optimization approaches",
-		"- Verify the bottleneck identification: is it really the bottleneck? What's the evidence?",
-		"- Ask about: existing profiling data, hot paths, memory vs CPU trade-offs",
-		"- Check if simpler solutions exist (e.g., caching before algorithm rewrite)",
-		"- Ask about regression risk: could the optimization introduce correctness issues?",
-		"- Explore the codebase (use read/bash tools) to understand current implementation",
-		"- Ask about monitoring: how will we measure the improvement in production?",
-		"- Challenge assumptions: is this optimization premature? What's the user-facing impact?",
-		"",
-		"## Output format",
-		"Output ALL questions in ONE JSON response. No preamble or explanation.",
-		'Only output the JSON object: { "questions": [{ "id": 1, "question": "...", "options": ["..."] }] }',
-		"",
-		"## Quantity",
-		"Ask 5-12 questions — enough to validate the approach before implementation.",
-		"",
-		"## Language",
-		"Questions and options should be in the same language as the optimization request (default: Chinese).",
-	].join("\n"),
-	timeoutMs: 300_000,
-};
+// ── Specialized Agent Definitions (loaded from agents/grill/ directory) ──
+
+const _fixGrillAgent = discoverAgents().find(a => a.name === "dev-fix-grill-agent")!;
+const _docGrillAgent = discoverAgents().find(a => a.name === "dev-doc-grill-agent")!;
+const _refactorGrillAgent = discoverAgents().find(a => a.name === "dev-refactor-grill-agent")!;
+const _testGrillAgent = discoverAgents().find(a => a.name === "dev-test-grill-agent")!;
+const _perfGrillAgent = discoverAgents().find(a => a.name === "dev-perf-grill-agent")!;
 
 // ── Command runner ───────────────────────────────────────────
 
@@ -555,9 +406,23 @@ async function runWizardWithGrill(
 		finalPrompt = grillResult.enhancedPrompt;
 	}
 
+	// ── Guard & persist before sending ───────────────────────
+	if (!finalPrompt) {
+		ctx.ui.notify("⚠️ 最终提示词为空，正在尝试从备份文件恢复...", "warning");
+		const recovered = recoverFromBackup(ctx.cwd);
+		if (recovered) {
+			finalPrompt = recovered;
+			ctx.ui.notify("✅ 已从备份文件恢复提示词内容", "success");
+		} else {
+			ctx.ui.notify("❌ 错误：最终提示词为空且无可用备份，无法发送", "error");
+			return;
+		}
+	}
+	const answerPath = saveAnswerFile(ctx.cwd, finalPrompt);
+
 	ctx.ui.notify(`✅ 提示词已组装完成，正在发送给主代理...`, "success");
-	pi.sendUserMessage(finalPrompt);
-	ctx.ui.notify(`📝 /dev-${type} 提示词已投递，主代理正在处理`, "info");
+	pi.sendUserMessage(finalPrompt, { deliverAs: "followUp" });
+	ctx.ui.notify(`📝 /dev-${type} 提示词已投递，主代理正在处理。备份: ${answerPath}`, "info");
 }
 
 /**
@@ -594,7 +459,7 @@ async function runWizard(
 	ctx.ui.notify(`✅ 提示词已组装完成，正在发送给主代理...`, "success");
 
 	// Send the assembled prompt to the main agent
-	pi.sendUserMessage(prompt);
+	pi.sendUserMessage(prompt, { deliverAs: "followUp" });
 
 	// Also show the prompt in a notification for reference
 	ctx.ui.notify(`📝 /dev-${type} 提示词已投递，主代理正在处理`, "info");
@@ -718,9 +583,30 @@ export default function (pi: ExtensionAPI) {
 			const finalPrompt = grillResult.enhancedPrompt;
 
 			// ── Phase 4: Send to main agent ─────────────────────
+			if (!finalPrompt) {
+				ctx.ui.notify("⚠️ 最终提示词为空，正在尝试从备份文件恢复...", "warning");
+				const recovered = recoverFromBackup(ctx.cwd);
+				if (recovered) {
+					ctx.ui.notify("✅ 已从备份文件恢复提示词内容", "success");
+					const recoveredPath = saveAnswerFile(ctx.cwd, recovered);
+					ctx.ui.notify(`✅ 提示词已组装完成，正在发送给主代理...`, "success");
+					pi.sendUserMessage(recovered, { deliverAs: "followUp" });
+					ctx.ui.notify(`📝 /dev-feat 提示词已投递（恢复自备份），主代理正在处理。备份: ${recoveredPath}`, "info");
+					// ── Phase 5: Wait for agent to finish ───────────────
+					await ctx.waitForIdle();
+					// ── Phase 6: PRD generation ─────────────────────────
+					const moduleHint = (answers as FeatFields).module || "feature";
+					await runPRDPhase(recovered, moduleHint, pi, ctx);
+					return;
+				} else {
+					ctx.ui.notify("❌ 错误：最终提示词为空且无可用备份，无法发送", "error");
+					return;
+				}
+			}
+			const answerPath = saveAnswerFile(ctx.cwd, finalPrompt);
 			ctx.ui.notify(`✅ 提示词已组装完成，正在发送给主代理...`, "success");
-			pi.sendUserMessage(finalPrompt);
-			ctx.ui.notify(`📝 /dev-feat 提示词已投递，主代理正在处理`, "info");
+			pi.sendUserMessage(finalPrompt, { deliverAs: "followUp" });
+			ctx.ui.notify(`📝 /dev-feat 提示词已投递，主代理正在处理。备份: ${answerPath}`, "info");
 
 			// ── Phase 5: Wait for agent to finish ───────────────
 			await ctx.waitForIdle();
@@ -740,7 +626,7 @@ export default function (pi: ExtensionAPI) {
 				ctx, pi, "fix", "问题排查/错误修正",
 				FIX_QUESTIONS, assembleFixPrompt,
 				{
-					agentDef: FIX_GRILL_AGENT_DEF,
+					agentDef: _fixGrillAgent,
 					title: "🐛 Bug 根因分析评审",
 					description: "是否进入 Bug 根因分析评审 (Grill) 模式？\nAI 会从复现条件、根因推理、修复方案、回归风险等维度挑战你的理解。",
 					questionTitle: "Bug 根因分析",
@@ -758,7 +644,7 @@ export default function (pi: ExtensionAPI) {
 				ctx, pi, "doc", "文档生成/总结",
 				DOC_QUESTIONS, assembleDocPrompt,
 				{
-					agentDef: DOC_GRILL_AGENT_DEF,
+					agentDef: _docGrillAgent,
 					title: "📄 文档大纲评审",
 					description: "是否进入文档大纲评审 (Grill) 模式？\nAI 会从受众定位、结构安排、示例选择等维度审视你的文档计划。",
 					questionTitle: "文档大纲评审",
@@ -776,7 +662,7 @@ export default function (pi: ExtensionAPI) {
 				ctx, pi, "refactor", "重构/优化",
 				REFACTOR_QUESTIONS, assembleRefactorPrompt,
 				{
-					agentDef: REFACTOR_GRILL_AGENT_DEF,
+					agentDef: _refactorGrillAgent,
 					title: "🔧 重构方案评审",
 					description: "是否进入重构方案评审 (Grill) 模式？\nAI 会从模块边界、API 兼容性、测试策略、迁移风险等维度审视你的重构计划。",
 					questionTitle: "重构方案评审",
@@ -794,7 +680,7 @@ export default function (pi: ExtensionAPI) {
 				ctx, pi, "test", "测试用例/评估",
 				TEST_QUESTIONS, assembleTestPrompt,
 				{
-					agentDef: TEST_GRILL_AGENT_DEF,
+					agentDef: _testGrillAgent,
 					title: "🧪 测试计划评审",
 					description: "是否进入测试计划评审 (Grill) 模式？\nAI 会从覆盖维度、边界条件、模拟策略等角度审视你的测试方案。",
 					questionTitle: "测试计划评审",
@@ -820,7 +706,7 @@ export default function (pi: ExtensionAPI) {
 				ctx, pi, "perf", "性能优化",
 				PERF_QUESTIONS, assemblePerfPrompt,
 				{
-					agentDef: PERF_GRILL_AGENT_DEF,
+					agentDef: _perfGrillAgent,
 					title: "⚡ 性能优化方案评审",
 					description: "是否进入性能优化方案评审 (Grill) 模式？\nAI 会从基准测试方法、优化方向、回归风险等维度审视你的方案。",
 					questionTitle: "性能优化方案评审",

package/extensions/grill-me-agent.ts

@@ -14,7 +14,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { BorderedLoader, DynamicBorder } from "@earendil-works/pi-coding-agent";
-import { spawnSubagent, extractFinalOutput, type AgentDef } from "./sub-agents";
+import { spawnSubagent, extractFinalOutput, discoverAgents, type AgentDef } from "./sub-agents";
 export type { AgentDef };
 import {
 	Container,
@@ -80,6 +80,37 @@ function grillOutputPath(cwd: string): string {
 	return path.join(dir, `questions-${ts}.json`);
 }
 
+/**
+ * Save the final assembled prompt to a timestamped answer file.
+ * Returns the relative path from cwd (for display in notifications).
+ */
+export function saveAnswerFile(cwd: string, content: string): string {
+	const dir = ensureOutputDir(cwd, GRILL_DIRNAME);
+	const ts = Date.now().toString(36);
+	const filename = `answer-${ts}.md`;
+	fs.writeFileSync(path.join(dir, filename), content, "utf-8");
+	return path.join(DEV_OUTPUT_DIR, GRILL_DIRNAME, filename);
+}
+
+/**
+ * Find the most recent answer backup file and read its content.
+ * Returns undefined if no backup exists or read fails.
+ */
+export function recoverFromBackup(cwd: string): string | undefined {
+	const dir = path.join(cwd, DEV_OUTPUT_DIR, GRILL_DIRNAME);
+	try {
+		if (!fs.existsSync(dir)) return undefined;
+		const files = fs.readdirSync(dir)
+			.filter(f => f.startsWith("answer-") && f.endsWith(".md"))
+			.map(f => ({ name: f, mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
+			.sort((a, b) => b.mtime - a.mtime);
+		if (files.length === 0) return undefined;
+		return fs.readFileSync(path.join(dir, files[0].name), "utf-8");
+	} catch {
+		return undefined;
+	}
+}
+
 /** Generate a safe PRD filename. */
 function generatePrdFilename(moduleSuggestion: string): string {
 	const safe = moduleSuggestion
@@ -107,96 +138,81 @@ function writeToolPromptSuffix(outputFilePath: string): string {
 		"Instead, use the `write` tool to save the questions to a file.",
 		`Write to this exact path: ${outputFilePath}`,
 		"",
-		"The file content must be a valid JSON object with a single key \"questions\":",
-		'```json',
+		"The file content must be a **valid** JSON object conforming to this JSON Schema (Draft-07):",
+		"",
+		"```json",
+		'{',
+		'  "$schema": "http://json-schema.org/draft-07/schema#",',
+		'  "type": "object",',
+		'  "required": ["questions"],',
+		'  "properties": {',
+		'    "questions": {',
+		'      "type": "array",',
+		'      "items": {',
+		'        "type": "object",',
+		'        "required": ["id", "question", "options"],',
+		'        "properties": {',
+		'          "id": { "type": "integer" },',
+		'          "question": { "type": "string" },',
+		'          "options": {',
+		'            "type": "array",',
+		'            "items": { "type": "string" },',
+		'            "minItems": 1',
+		'          }',
+		'        }',
+		'      }',
+		'    }',
+		'  }',
+		'}',
+		"```",
+		"",
+		"### \u26a0\ufe0f CRITICAL: String escaping rules",
+		"",
+		"Every string value (question text, option text) MUST be valid JSON-escaped:",
+		"- Double quotes inside text \u2192 \\\"",
+		"- Newlines \u2192 \\n",
+		"- Backslashes \u2192 \\\\",
+		"- Tabs \u2192 \\t",
+		"",
+		"### \u2705 Self-review before writing",
+		"",
+		"Before calling the `write` tool, mentally validate your JSON.",
+		"Check that all strings are properly escaped and the structure matches the schema above.",
+		"If you are unsure, write a quick test with `bash` (e.g. `node -e \"JSON.parse(...)\"`).",
+		"",
+		"Example output:",
+		"```json",
 		'{',
 		'  "questions": [',
 		'    {',
 		'      "id": 1,',
-		'      "question": "问题文本?",',
-		'      "options": ["选项A", "选项B", "选项C"]',
+		'      "question": "\\u9879\\u76ee\\u662f\\u5426\\u5b58\\u5728\\u6a21\\u5757\\u7ed3\\u6784\\uff1f",',
+		'      "options": [',
+		'        "\\u5df2\\u5b58\\u5728\\uff0c\\u4f8b\\u5982 src/controller/example.rs",',
+		'        "\\u4ece\\u96f6\\u521b\\u5efa"',
+		'      ]',
+		'    },',
+		'    {',
+		'      "id": 2,',
+		'      "question": "\\u4ed6\\u8bf4\\u201c\\u8fd9\\u4e2a\\u4e0d\\u884c\\u201d\\uff0c\\u8be5\\u5982\\u4f55\\u5904\\u7406\\uff1f",',
+		'      "options": [',
+		'        "\\u5ffd\\u7565",',
+		'        "\\u4fee\\u590d"',
+		'      ]',
 		'    }',
 		'  ]',
 		'}',
-		'```',
+		"```",
 		"",
 		"After writing, you may include a brief summary in your chat response.",
 		"But the JSON MUST be in the file, NOT in the chat.",
 	].join("\n");
 }
 
-const GRILL_AGENT_DEF: AgentDef = {
-	name: "grill-agent",
-	description: "Design review agent — interviews the developer about a feature plan",
-	tools: ["read", "bash", "write"],
-	systemPrompt: [
-		"You are an expert design reviewer. Interview the developer relentlessly about every aspect of the feature plan until reaching shared understanding.",
-		"",
-		"## Rules",
-		"- For EACH question, provide recommended answer OPTIONS (a/b/c format) that the user can pick from",
-		"- Walk down each branch of the design tree, resolving dependencies between decisions one-by-one",
-		"- Be specific — refer to actual code modules, file paths, and architecture decisions",
-		"- Explore the codebase (use read/bash tools) when a question can be answered by looking at existing code",
-		"- Ask questions about: architecture, data flow, edge cases, security, testing, module boundaries, dependencies, error handling, performance, scalability",
-		"- If terminology conflicts with existing project glossary (CONTEXT.md), call it out",
-		"- Sharpen fuzzy language — propose precise canonical terms",
-		"- Stress-test scenarios with specific edge cases",
-		"- Cross-reference with existing code — surface contradictions",
-		"",
-		"## Quantity",
-		"Ask as many questions as needed to thoroughly review the design.",
-		"Do not artificially limit the number — cover architecture, data flow, edge cases, security, testing, module boundaries, dependencies, error handling, and more.",
-		"Typically 15-40 questions for a moderate feature.",
-		"",
-		"## Language",
-		"Questions and options should be in the same language as the feature request (default: Chinese).",
-	].join("\n"),
-	timeoutMs: 300_000, // 5 min
-};
-
-const PRD_AGENT_DEF: AgentDef = {
-	name: "prd-agent",
-	description: "PRD writer — synthesizes a PRD from conversation context",
-	tools: ["read", "bash"],
-	systemPrompt: [
-		"You are an expert product spec writer.",
-		"Your task is to create a PRD from the provided conversation context.",
-		"",
-		"## Rules",
-		"- Do NOT ask any questions — just synthesize what you already know",
-		"- Explore the repo to understand the current state of the codebase",
-		"- Use the project's domain vocabulary throughout",
-		"- Use the template below and output ONLY the Markdown content (no JSON wrapper, no preamble)",
-		"",
-		"## Template",
-		"",
-		"# {Feature Name} — PRD",
-		"",
-		"## Problem Statement",
-		"The problem that the user is facing, from the user's perspective.",
-		"",
-		"## Solution",
-		"The solution to the problem, from the user's perspective.",
-		"",
-		"## User Stories",
-		"A numbered list of user stories:",
-		"1. As an <actor>, I want a <feature>, so that <benefit>",
-		"",
-		"## Implementation Decisions",
-		"A list of implementation decisions including modules to build/modify, architectural decisions, schema changes, API contracts.",
-		"Do NOT include specific file paths or code snippets (may become outdated).",
-		"",
-		"## Testing Decisions",
-		"A description of what makes a good test, which modules will be tested, prior art.",
-		"",
-		"## Out of Scope",
-		"Things explicitly out of scope.",
-		"",
-		"## Further Notes",
-		"Any further notes about the feature.",
-	].join("\n"),
-	timeoutMs: 300_000,
-};
+// ── Default agent definitions (loaded from agents/ directory) ────
+
+const _defaultGrillAgent = discoverAgents().find(a => a.name === "dev-grill-agent")!;
+const _defaultPrdAgent = discoverAgents().find(a => a.name === "dev-prd-agent")!;
 
 // ── File-based question extraction ───────────────────────────
 
@@ -220,7 +236,13 @@ function readQuestionsFromFile(filePath: string): GrillQuestion[] {
 				question: q.question,
 				options: q.options,
 			}));
-	} catch {
+	} catch (e) {
+		// Log parse errors for debugging (development feedback)
+		try {
+			const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf-8").slice(0, 1000) : "(file not found)";
+			console.error(`[grill-me-agent] JSON parse error in ${filePath}:`, (e as Error).message);
+			console.error(`[grill-me-agent] First 1000 chars:`, content);
+		} catch { /* ignore secondary errors */ }
 		return [];
 	}
 }
@@ -339,11 +361,11 @@ export async function runGrillPhase(
 		enhancedPrompt: assembledPrompt,
 	};
 
-	const agentDef = options?.agentDef ?? GRILL_AGENT_DEF;
+	const agentDef = options?.agentDef ?? _defaultGrillAgent;
 	const confirmTitle = options?.title ?? "🔍 设计方案评审";
 	const confirmDesc = options?.description ?? "是否进入设计评审 (Grill) 模式？\nAI 会从架构、数据流、边界条件、安全等多个维度挑战你的设计。";
 	const qTitlePrefix = options?.questionTitle ?? "设计方案评审";
-	const loaderLabel = options?.loaderLabel ?? "🧠 AI 正在分析代码并生成评审问题...";
+	const loaderLabel = options?.loaderLabel ?? "🧠 AI 子代理正在分析代码并生成评审问题...";
 
 	// ── Step 1: Confirm entering grill mode ──────────────────
 	const enterGrill = await ctx.ui.confirm(confirmTitle, confirmDesc);
@@ -369,7 +391,11 @@ export async function runGrillPhase(
 			ctx.cwd,
 			loader.signal,
 			undefined,
-			(progress) => { loader.setText(`🧠 ${progress.slice(0, 60)}`); },
+			(progress) => {
+					// BorderedLoader 内部持有 Loader/CancellableLoader（私有 loader 字段），后者有 setText
+					const inner = (loader as unknown as { loader?: { setText?: (t: string) => void } }).loader;
+					inner?.setText?.(`🧠 ${progress.slice(0, 60)}`);
+				},
 		)
 			.then((result) => {
 				// Primary: read from file (sub-agent wrote via `write` tool)
@@ -390,11 +416,20 @@ export async function runGrillPhase(
 		return loader;
 	});
 
-	// ── Step 4: Clean up temp file ───────────────────────────
-	try { fs.unlinkSync(outputFilePath); } catch { /* ignore */ }
-
-	// ── Step 4b: Retry dialog if no questions generated ──────
+	// ── Step 4: Retry dialog if no questions generated ──────
 	if (questions.length === 0) {
+		// Read the failed file to get error context for the retry prompt
+		let failedFileContent = "";
+		let parseErrorMsg = "";
+		try {
+			if (fs.existsSync(outputFilePath)) {
+				failedFileContent = fs.readFileSync(outputFilePath, "utf-8").slice(0, 2000);
+				JSON.parse(failedFileContent);
+			}
+		} catch (e) {
+			parseErrorMsg = (e as Error).message;
+		}
+
 		const choice = await ctx.ui.select(
 			"⚠️ AI 未能成功生成评审问题",
 			[
@@ -407,7 +442,28 @@ export async function runGrillPhase(
 		switch (choice) {
 			case "🔄 重新尝试生成评审问题": {
 				const retryPath = grillOutputPath(ctx.cwd);
-				const retryPrompt = [assembledPrompt, writeToolPromptSuffix(retryPath)].join("\n\n");
+				const errorFeedback = parseErrorMsg
+					? [
+						"",
+						"### ⚠️ Previous attempt had JSON errors — fix them now",
+						"",
+						`The previous attempt wrote to \`${outputFilePath}\` but the JSON was invalid.`,
+						"",
+						`JSON parse error: ${parseErrorMsg}`,
+						"",
+						"Invalid file content (first 2000 chars):",
+						"```",
+						failedFileContent.slice(0, 1000),
+						"```",
+						"",
+						"Please write valid JSON to the new path below. Make sure all strings are properly JSON-escaped.",
+					].join("\n")
+					: "";
+				const retryPrompt = [
+					assembledPrompt,
+					writeToolPromptSuffix(retryPath),
+					errorFeedback,
+				].filter(Boolean).join("\n\n");
 				questions = await ctx.ui.custom<GrillQuestion[]>((tui, theme, _kb, done) => {
 					const loader = new BorderedLoader(tui, theme, loaderLabel);
 					loader.onAbort = () => done([]);
@@ -420,7 +476,6 @@ export async function runGrillPhase(
 						.catch(() => done([]));
 					return loader;
 				});
-				try { fs.unlinkSync(retryPath); } catch { /* ignore */ }
 				if (questions.length === 0) {
 					ctx.ui.notify("⚠️ 再次尝试仍然失败，跳过 Grill 阶段", "warning");
 					return defaultResult;
@@ -582,7 +637,7 @@ export async function runPRDPhase(
 			context,
 		].join("\n");
 
-		spawnSubagent(PRD_AGENT_DEF, prdTask, ctx.cwd, loader.signal)
+		spawnSubagent(_defaultPrdAgent, prdTask, ctx.cwd, loader.signal)
 			.then((result) => {
 				const output = extractFinalOutput(result.output);
 				done(output && output.length >= 50 ? output : null);
@@ -638,7 +693,7 @@ async function askDevelopmentStart(
 				"",
 				"请按照上述 PRD 逐步实现。先分析代码库结构，给出实施计划，确认后再编写代码。",
 			].join("\n");
-			pi.sendUserMessage(devMsg);
+			pi.sendUserMessage(devMsg, { deliverAs: "followUp" });
 			ctx.ui.notify("🚀 已发送开发指令给主代理", "success");
 			break;
 		}
@@ -668,7 +723,7 @@ async function askDevelopmentStart(
 					"--- PRD 全文 ---",
 					prdContent,
 				].join("\n");
-			pi.sendUserMessage(finalMsg);
+			pi.sendUserMessage(finalMsg, { deliverAs: "followUp" });
 			ctx.ui.notify("🚀 已发送自定义开发指令给主代理", "success");
 			break;
 		}

package/extensions/sub-agents.ts

@@ -184,6 +184,7 @@ function inferTimeout(name: string): number {
 	const lc = name.toLowerCase();
 	if (lc.includes("review") || lc.includes("审查")) return REVIEW_TIMEOUT_MS;
 	if (lc.includes("git")) return GIT_TIMEOUT_MS;
+	if (lc.includes("prd")) return REVIEW_TIMEOUT_MS;
 	return DEFAULT_TIMEOUT_MS;
 }
 
@@ -238,20 +239,28 @@ export function discoverAgents(): AgentDef[] {
 	if (!agentsDir) return (_discoveredAgents = []);
 
 	const agents: AgentDef[] = [];
-	let entries: fs.Dirent[];
-	try {
-		entries = fs.readdirSync(agentsDir, { withFileTypes: true });
-	} catch {
-		return (_discoveredAgents = agents);
-	}
 
-	for (const entry of entries) {
-		if (!entry.name.endsWith(".md")) continue;
-		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
-		const filePath = path.join(agentsDir, entry.name);
-		const agent = loadAgent(filePath);
-		if (agent) agents.push(agent);
+	/** Recursively walk directory to collect all .md agent definitions. */
+	function scanAgentsDir(dir: string): void {
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry.name.startsWith(".")) continue; // skip hidden files/dirs
+			const fullPath = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				scanAgentsDir(fullPath);
+			} else if ((entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith(".md")) {
+				const agent = loadAgent(fullPath);
+				if (agent) agents.push(agent);
+			}
+		}
 	}
+
+	scanAgentsDir(agentsDir);
 	return (_discoveredAgents = agents);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghyper9023/pi-dev-workflow",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "keywords": [
     "pi-package"
   ],