prd-taskmaster

prd-taskmaster — Atlas 引擎

零配置的目标转任务引擎。AI 负责探索和内容；引擎后端（优先使用 MCP 服务，script.py 作为回退方案——参见阶段 0）负责处理机制。

命令： /atlas 是规范的调用方式（也可以使用 /prd-taskmaster，或者直接说“我想构建……”）。完整的插件安装还会提供各阶段的技能；这个独立技能会内联运行整个流程。

脚本： ~/.claude/skills/prd-taskmaster/script.py（所有命令均输出 JSON）。它是捆绑的 prd_taskmaster/ 包的轻量封装——该包是与插件共享的唯一事实来源。

手动标志： 如果用户说 --manual、manual=true 或“手动完成”，请自行执行 TaskMaster 的机制：编写 .taskmaster/docs/prd.md，编写包含任务和子任务的 .taskmaster/tasks/tasks.json，运行 validate-tasks，然后运行 enrich-tasks。不要因 TaskMaster CLI/MCP 解析而停滞。

适用场景

启用：PRD、产品需求、taskmaster、任务驱动开发、“我想构建 X”以及任何目标。 跳过：API 文档、测试规格、项目时间线、PDF 创建。

阶段 0：引擎后端解析（强制——必须先于其他任何引擎操作）

引擎有两个可互换的后端：atlas-engine MCP 服务（优先）和 script.py（零依赖回退方案）。现在就解析本会话使用哪个后端。不要默默默认使用 script.py。

Claude Code 说明——延迟加载的工具： MCP 工具通常是延迟加载的：它们的名称会出现在系统提醒列表中，但在使用 ToolSearch 工具加载其架构之前，无法调用它们。“我没看到可调用的 engine_preflight 工具”不意味着服务不存在——几乎总是因为你还没有运行 ToolSearch。

按以下顺序进行解析：

1. 如果本会话中存在 ToolSearch 工具： a. ToolSearch(query="select:mcp__atlas-engine__engine_preflight") b. 如果没有匹配项：ToolSearch(query="+engine preflight atlas", max_results=10)——这也会查找类似 mcp__plugin_prd_go__engine_preflight 的插件作用域 ID。 c. 如果加载了架构 → MCP-mode = ON。记录前缀（例如 mcp__atlas-engine__）。如果用户作用域和插件作用域均匹配，优先选择 mcp__atlas-engine__。
2. 如果没有 ToolSearch，但已经可以直接调用 engine_preflight MCP 工具 → 使用该前缀，MCP-mode = ON。
3. 否则 → MCP-mode = OFF（CLI-mode）。

进入阶段 1 之前，用一行准确播报解析结果： Engine backend: MCP (<prefix>*) 或 Engine backend: script.py (CLI fallback)。

本次运行期间必须遵守以下规则：

• MCP-mode ON： 下方“引擎操作”表中的每项操作都必须使用对应的 MCP 工具。如果本会话前缀中存在某项操作对应的 MCP 工具，却运行 python3 script.py <cmd> 执行该操作，即属违规——唯一例外是“仅限脚本/Agent”表中的操作，以及已解析前缀中缺少对应工具的操作（某些插件安装提供的工具较少——仅对这些操作回退到 script.py）。
• MCP-mode OFF： 严格按下文所述使用 script.py 命令。其他运行环境（codex、gemini）没有 ToolSearch，也可能没有 MCP 服务——CLI-mode 完全受支持，体验并未降级。
• 如果 MCP 调用在运行中出错（服务崩溃/断开连接），请明确说明，然后切换到 CLI-mode 并继续。

阶段 1：零配置预检

运行预检并自动检测所有内容。不询问任何设置问题。

MCP 模式（来自阶段 0 — 一次批量调用，不刷屏调用脚本）： 调用一次 <prefix>engine_preflight — 它涵盖预检、TaskMaster 检测、提供商配置和功能，并返回一个可原样呈现的 summary 列表。 跳过下面所有单独的脚本调用。

CLI 模式（零依赖安装）： 使用一个批量子命令，结果相同：

python3 ~/.claude/skills/prd-taskmaster/script.py engine-preflight

根据预检 JSON 确定状态：

条件	操作
prd_path 存在 + task_count > 0	询问：执行任务／更新 PRD／新建 PRD／审查
backend.ai_ops == "agent"	后端会自动解析；打印一行说明：添加 API 密钥或安装 task-master-ai 以支持无头 AI 操作；继续
存在手动标志	使用 Native Mode 继续（TaskMaster 可选），无论 TaskMaster CLI/MCP 状态如何
has_taskmaster == false + 已选择后端	运行 init-project（见下文），然后继续
存在 has_taskmaster 但没有 PRD	继续进入 Discovery
存在 has_crash_state	提供选择：从崩溃点恢复或重新开始

如有需要，初始化项目，然后自动配置提供商（静默进行）。对已解析的后端使用 init-project。对于 taskmaster 后端，此操作会保留现有的 .mcp.json；直接运行 task-master init 则会用占位模板覆盖它。 仅在明确使用 taskmaster 后端时才使用 init-taskmaster：

python3 ~/.claude/skills/prd-taskmaster/script.py init-project         # only when .taskmaster/ absent
python3 ~/.claude/skills/prd-taskmaster/script.py init-taskmaster      # taskmaster backend only
python3 ~/.claude/skills/prd-taskmaster/script.py configure-providers
python3 ~/.claude/skills/prd-taskmaster/script.py detect-providers

如果 configure-providers 返回 recommended_action: "init_taskmaster"，先运行 init-project；如果明确使用 taskmaster 后端，也可以安全地运行 init-taskmaster，它会保留 .mcp.json。

简要报告状态：

  ✓ Backend: taskmaster-api|native-api|agent
  ✓ Detected: TaskMaster (MCP|CLI)
  ✓ Detected: Provider (Claude Code|Codex CLI|Anthropic API)
  ✓ Detected: Research (Perplexity API Free|Perplexity MCP|Perplexity API|fallback)

关卡：后端已解析（始终为真）。报告 ai_ops 功能。继续进入 Discovery。

提供商默认设置

始终优先使用订阅／原生提供商，而非付费 API 密钥：

1. 主选：存在 claude 时使用 claude-code / sonnet；否则，存在 codex 时使用 codex-cli / gpt-5.2-codex。
2. 备用：可用时使用 codex-cli / gpt-5.2-codex；否则使用 claude-code / sonnet。
3. 研究：通过 TaskMaster 的 openai-compatible 提供商使用本地 Perplexity API Free：
   • 模型：sonar
   • baseURL：http://127.0.0.1:8765
   • .env 密钥：OPENAI_COMPATIBLE_API_KEY="local-perplexity-api-free"（仅为本地虚拟密钥）

当原生 Claude/Codex 和 Perplexity API Free 可用时，不要要求提供 ANTHROPIC_API_KEY 或付费的 PERPLEXITY_API_KEY。

阶段 2：Discovery

阅读阶段文件并按其说明操作：

Read ~/.claude/skills/prd-taskmaster/phases/DISCOVER.md

通过 superpowers:brainstorming 进行渐进式、自适应、与领域无关的 Discovery。

关卡：Discovery 已完成且用户已批准设计。继续进入 Generate。

阶段 3：生成与验证

阅读阶段文件并按其说明操作：

Read ~/.claude/skills/prd-taskmaster/phases/GENERATE.md

生成规格说明，验证质量，解析任务，并补充元数据。

关卡：PRD 已验证为 GOOD+，且已通过 TaskMaster parse/expand 或 Native Mode 创建任务。继续进入 Handoff。

Native Mode（TaskMaster 可选）

以前称为“手动机制模式”。引擎无需 TaskMaster 也能生成相同的已验证任务图；当用户传入 --manual、未安装 TaskMaster，或其解析／扩展不合适时，请使用此模式。

1. 按常规生成 .taskmaster/docs/prd.md。
2. 手动编写符合 TaskMaster 格式的 .taskmaster/tasks/tasks.json：
   • 顶层对象包含 tasks: []
   • 每个任务包含 id、title、description、details、testStrategy、status、dependencies、priority 和 subtasks
   • 每个任务至少有 2 个子任务，且每个子任务包含 id、title、description、status 和 dependencies
3. 运行：

   python3 ~/.claude/skills/prd-taskmaster/script.py validate-tasks
   python3 ~/.claude/skills/prd-taskmaster/script.py enrich-tasks
   python3 ~/.claude/skills/prd-taskmaster/script.py validate-tasks --require-phase-config
   

4. 将成功的验证、补充元数据和 phaseConfig 验证视为等同于 TaskMaster 的 parse + expand。

阶段 4：交接

阅读阶段文件并按其指示操作：

Read ~/.claude/skills/prd-taskmaster/phases/HANDOFF.md

检测功能，推荐一种执行模式并完成交接。模式（面向用户的名称）： Verified Loop（当存在 superpowers 和循环运行器时推荐）、Auto-Execute （TaskMaster 的原生循环）、Plan & Drive（仅规划）。Atlas Fleet — 并行多会话 执行 — 在检测到已获许可的 atlas-launcher 时，会作为 Atlas Pro 选项显示； 否则会显示一个指向 https://atlas-ai.au/pro 的锁定预告。免费引擎始终可以独立完整使用。

关卡：用户已选择模式且交接已完成。

反馈

在复盘时，每个执行中的 Agent 都要记录本次运行情况。MCP 模式： <prefix>feedback_submit / <prefix>feedback_report。CLI 模式： python3 script.py feedback-add --rating <1-5> --agent <name> --harness <claude-code|codex|gemini|api|other> --task-ref <id> --well <text> --failed <text> --suggest <text>。反馈存储在 .atlas-ai/feedback.jsonl 中；使用 python3 script.py feedback-report 汇总。

引擎操作

此表具有规范效力 — 指令文档会按名称引用这些操作。在 MCP 模式下使用 MCP 工具（替换为阶段 0 的前缀）；在 CLI 模式下使用 script.py 命令。

操作	MCP 工具（MCP 模式）	script.py（CLI 模式 / 回退）
engine-preflight	engine_preflight	engine-preflight
preflight	preflight	preflight
detect-taskmaster	detect_taskmaster	detect-taskmaster
backend-detect	backend_detect	backend-detect
init	init_project	init-project
init-taskmaster	init_taskmaster	init-taskmaster
validate-setup	validate_setup	（由 engine-preflight 覆盖）
detect-capabilities	detect_capabilities	detect-capabilities
load-template	load_template	load-template --type comprehensive|minimal
calc-tasks	calc_tasks	calc-tasks --requirements <count> [--scale solo|team|enterprise]
validate-prd	validate_prd	validate-prd --input <path>
backup-prd	backup_prd	backup-prd --input <path>
parse-prd	parse_prd	parse-prd --input <path> --num-tasks N [--tag]
rate	rate_tasks	rate [--tag] [--no-research]
expand	expand_tasks	expand [--id N ...] [--no-research] [--tag]
next	next_task	next-task [--tag]
set-status	set_task_status	set-status --id <id> --status <status> [--tag]
fleet-waves	compute_fleet_waves	fleet-waves
feedback-add	feedback_submit	feedback-add --rating <1-5> ...
feedback-report	feedback_report	feedback-report
status	render_status	status [--phase P] [--format boxed|ascii|json] [--all]

在每个阶段边界（以及按需）通过 status / render_status 渲染进度面板 — 包括方框样式的阶段跟踪器、验证评分卡、发布检查关卡和执行进度。

通过任一接口，后端行为都相同：taskmaster 后端会安全地封装原生 TaskMaster 操作（init/parse/rate/expand）；native 后端使用直接 API 调用，或返回 agent_action_required；所有后端中的 next / set-status 均为引擎原生操作。

脚本/Agent 专用操作（无 MCP 工具 — 始终使用 script.py，任何模式）

命令	用途
configure-providers	配置原生 Claude/Codex + 本地 Perplexity API Free 默认项
detect-providers	自动检测 AI 提供商
validate-tasks [--input <path>] [--require-phase-config]	验证手动编写的 tasks.json
enrich-tasks	为任务添加 phaseConfig 元数据
parallel-plan [--missing-only]	为并行子 Agent 生成逐任务研究资料包
parallel-apply --input <results.json>	原子合并并行研究结果
parallel-extract --output <path> / parallel-inject --input <path>	带标签 ⇄ 扁平任务桥接
economy-report	按 (op_class, model) 汇总遥测数据

并行研究与复杂度

扩展 + 研究的决策树（考虑令牌经济性）：

Manual flag                        → Native Mode (unchanged)
pending tasks ≤ 3                  → TaskMasterBackend.expand internal: serial NATIVE
                                     rate --research, then expand per task (main dir)
task-master ≥ 0.43 AND research
  role is a REAL structured API    → TaskMasterBackend.expand internal: NATIVE-PARALLEL
  (sonar/anthropic/openai… key)      one serial analyze-complexity, then N isolated workdirs each running
                                     native `expand --id N --research` with an economy-tier model; ONE
                                     atomic harvest merge. Failed packets → agent-parallel rerun.
free local proxy / no API key /
  TM provider errors / TM < 0.43   → native/agent path: AGENT-PARALLEL (fallback):
                                     parallel-plan → N subagents → parallel-apply

为何使用隔离目录：task-master 0.43+ 使用 proper-lockfile 和原子写入，但其 10 秒的锁过期窗口与 30–120 秒的 AI 调用时长不匹配，因此在同一目录中并发调用并不安全 — N 个隔离的项目目录可以完全避开锁问题，还可作为每次尝试的模型机制（expand 没有 --model 标志；每个工作目录都带有自己的 config.json）。本地免费 Perplexity 代理返回的是散文，而 TaskMaster 需要严格的 JSON — 因此代理保留了经 Agent 规范化的路径，而真实 API 使用原生路径。

模式 — 并行处理由 Agent 实现，而非脚本：

python3 ~/.claude/skills/prd-taskmaster/script.py parallel-plan --missing-only   # research packets JSON
# AGENT: split packets into N groups (by lane/domain), spawn N parallel research
#   subagents; each verifies files in-repo + researches APIs and returns
#   [{id, complexityScore, recommendedSubtasks, reasoning, researchNotes, subtasks[]}]
# AGENT: concatenate results -> results.json
python3 ~/.claude/skills/prd-taskmaster/script.py parallel-apply --input results.json   # ONE atomic write
#   + writes .taskmaster/reports/task-complexity-report[_<tag>].json (TaskMaster format)
#   + returns needs_more_subtasks (score >= threshold w/ too-few subtasks) for a second pass

如果 perplexity-api-free MCP 封装超时或提示代理无法访问，请检查代理的直接运行状况：

curl -sS -X POST http://127.0.0.1:8765/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"sonar","messages":[{"role":"user","content":"Return exactly: ok"}],"max_tokens":16}'

如果直接使用 curl 可行，则继续：使用 MCP、直接调用代理或通过 Agent 研究来生成 results.json 架构，然后将散文规范化为有效 JSON，再运行 parallel-apply。不要因原生的 task-master analyze-complexity --research 而阻塞。

用于明确采用扁平文件工作流的标签桥接（脚本也会直接读取带标签的 TaskMaster 文件）：

python3 ~/.claude/skills/prd-taskmaster/script.py parallel-extract --output /tmp/flat.json
python3 ~/.claude/skills/prd-taskmaster/script.py validate-tasks --input /tmp/flat.json
python3 ~/.claude/skills/prd-taskmaster/script.py enrich-tasks  --input /tmp/flat.json
python3 ~/.claude/skills/prd-taskmaster/script.py validate-tasks --input /tmp/flat.json --require-phase-config
python3 ~/.claude/skills/prd-taskmaster/script.py parallel-inject --input /tmp/flat.json

所有命令默认将 .taskmaster/state.json 中的 currentTag 作为 --tag，并从项目根目录运行。

上下文

独立运行： 可独立工作。输入任意目标，生成规格说明 + 任务。 产出： spec.md + tasks.json（位于 .taskmaster/ 中）。 然后： 移交给执行模式（Verified Loop / Auto-Execute / Plan & Drive），或移交给 Atlas Fleet，通过 Atlas Pro 并行执行多个会话。

关键规则

1. 不询问任何设置问题 — 检测所有信息，只询问发现性问题
2. 通过 superpowers:brainstorming 进行发现 — 一次只问一个问题，并根据情况调整
3. 不限领域 — 适用于任何目标（应用、渗透测试、业务等）
4. 验证 PRD 时捕获占位符 — mustache、TBD、TODO 模式都会导致验证失败
5. 手动标志表示“手动执行 TaskMaster 的操作”，而非“跳过验证”
6. 移交时只推荐一种模式 — 呈现最合适的选项，而非同等选择
7. 必须明确读取阶段文件 — 它们不会自动加载
8. 由 configure-providers 强制使用原生/免费提供商默认项；除非原生/免费路径不可用，否则不得切回付费 Anthropic/Perplexity API
9. Perplexity API Free 研究必须通过 parallel-apply 进行规范化；只有在原生 TaskMaster 研究返回有效的结构化输出且验证通过时，才可接受
10. 必须在阶段 0 解析后端 — 在 MCP 模式下，对于已解析前缀中存在 MCP 工具的任何操作，禁止使用 script.py