用途
Universal Planner 是一个面向任意软件工程场景的统一规划与执行技能。它通过两种互斥模式覆盖软件工作的两个阶段：PLAN 模式负责产出专业、结构化的规划文档；EXECUTE 模式负责消费规划输出并逐冲刺、逐阶段、逐任务地实现。
主要能力
PLAN 模式
- 只产出文档，不实现、不编码、不构建、不部署。
- 自动检测场景并激活对应子模式：NEW_PROJECT（新项目）、NEW_FEATURE（新功能）、REFACTOR（重构）、BUG_FIX（缺陷修复）、TECH_DEBT（技术债）、ARCHITECTURE（架构）。
- 工作流：配置解析 → 代码库发现（生成 discovery/CONVENTIONS.md，NEW_PROJECT 除外）→ 分析（analysis/ANALYSIS.md）→ 规划（planning/PLANNING.md）→ 执行计划（execution/EXECUTION.md）→ 冲刺计划（可选，sprints/PROGRESS.md 与 sprints/SPRINT-*.md）→ 交接并停止。
- 可创建 CONVENTIONS.md，可创建和更新冲刺文件与 PROGRESS.md，可在文档中做架构决策。
EXECUTE 模式
- 只实现已有计划，不创建新规划文档、不修改策略、不重构冲刺。
- 以高级开发者与 Scrum Master 双重角色工作。
- 工作流：定位并校验计划目录 → 内化计划 → 执行当前冲刺（逐阶段、逐任务）→ 完成冲刺（更新跟踪、验证毕业门槛）→ 可选回顾 → 项目完成报告。
- 可编写和修改代码、运行验证命令、记录实现决策（Decision Log）、生成回顾（可选）、更新冲刺文件与 PROGRESS.md。
关键规则
- 模式边界绝对：PLAN 永不执行，EXECUTE 永不规划。
- 上下文优先：在既有代码库上做任何决策前，先探索并理解项目既有模式、约定与架构，偏离必须记录并说明理由。
- 自适应模式检测：从用户输入检测顶层模式与规划子模式，模糊时询问。
- 专业质量：PLAN 输出须如资深工程团队所写，无模糊语言与占位符；EXECUTE 须写生产级代码。
- 完整性：PLAN 生成子模式要求的全部文档；EXECUTE 完成一个阶段的所有任务后再进入下一阶段。
- 计划即事实来源（EXECUTE）：每个实现决策都可追溯到计划，不即兴设计架构或发明新模式。
- 约定不可协商：discovery/CONVENTIONS.md 定义项目 DNA，所有规划提案与实现代码必须遵循。
- 假设透明：信息缺失时，PLAN 在 ANALYSIS.md 记录假设，EXECUTE 在 Decision Log 记录决策，绝不静默假设。
使用方式
模式检测
- PLAN 信号：规划、分析、设计、“plan”、“create a plan”、无既有计划的新工作。示例：“Plan the auth system”“I need an app to track expenses”。
- EXECUTE 信号：实现、执行、“start working”、“implement the plan”、存在既有计划输出。示例：“Execute the project plan”“Start implementing Sprint 1”。
- 意图不清时询问：“Do you want me to plan this work (produce documentation) or execute an existing plan (implement code)?”
资产加载（按模式门控）
- PLAN 模式读取：output-resolve.md、PLAN.md、检测到的子模式 .md；不读 EXECUTE.md、config-resolver.md、decision-log.md、code-quality-standards.md、无关子模式文件、examples/、validators/。
- EXECUTE 模式读取：output-resolve.md、EXECUTE.md、decision-log.md、code-quality-standards.md；不读 PLAN.md、config-resolver.md、所有子模式文件、templates/、examples/、validators/。
- 按需辅助：troubleshooting.md 仅在出现问题时读取；config-resolver.md 仅在 output-resolve.md 找不到既有配置（首次设置）时加载。
快速开始
- PLAN 模式：例如“Plan the authentication system for the app.”，读取 output-resolve.md + PLAN.md，再读取检测到的子模式文件。
- EXECUTE 模式：例如“Execute the project plan.”，读取 output-resolve.md + EXECUTE.md + decision-log.md + code-quality-standards.md。
配置解析
{output_dir} 是存储所有规划文档的目录，启动时解析一次：从用户消息中的文件路径提取；在 {cwd} 中扫描 .agents/universal-planner/；若未找到则询问用户，默认建议 .agents/universal-planner/{project-name}/。无 AGENTS.md，无品牌块。
Obsidian 输出标准
- 每个 .md 文件包含通用 frontmatter 模式（title、date、updated、project、type、status、version、tags、changelog、related）。
- 类型包括 conventions、analysis、plan、execution-plan、sprint-plan、progress、requirements、architecture、retrospective。
- 文档间引用使用 [[filename]] wiki 链接语法，不使用相对路径链接。
- 每份文档以 ## References 结尾，列出 Parent、Siblings、Children、Input Documents。
- PROGRESS.md 与冲刺计划为活文档，修改时递增版本、更新 changelog、转换状态。
- ID 规范：FR-/NFR- 需求，ADR- 架构决策，T- 任务，DEC- 决策，K-/P-/L-/A- 回顾项。
- 双向引用：A 引用 B，则 B 须在 related 与 ## References 中引用 A。
- 指标使用 | Metric | Before | After | Delta | Status | 格式。
- 冲刺计划包含 ## Graduation Gate 可验证复选框标准。
- Sprint 2+ 包含 ## Carried Forward from [[previous-sprint]]。
- 阅读顺序重要处使用 01-、02- 前缀。
- 状态流转：draft → active → completed（或 draft → active → failed）。
冲刺结构标准
- 任务粒度：L1 冲刺（3-7 天）、L2 阶段（0.5-2 天）、L3 任务（1-4 小时，含文件路径、前后代码、验证）、L4 子任务（5-30 分钟）。
- 每个任务须包含：复选框、文件路径（适用时）、前后代码片段、验证命令、对既有模式/组件的引用。
适用场景
- 需要为软件工作产出结构化规划文档时使用 PLAN 模式。
- 需要按既有计划逐冲刺实现代码时使用 EXECUTE 模式。
- 与其他技能集成：code-analyzer 可在 PLAN 模式（REFACTOR 或 TECH_DEBT 子模式）前使用以获取技术报告；skill-creator 用于构建补充规划输出的技能；obsidian 用于同步规划输出到 vault 或读取笔记上下文，可通过 Skill("obsidian") 调用或说 "sync to obsidian"，子代理回退为直接读取 obsidian SKILL.md。
限制
- 模式边界：PLAN 不能执行，EXECUTE 不能规划。
- 需要输入：PLAN 需要工作描述，EXECUTE 需要计划输出。
- 假设须验证：推断的决策需团队评审后再实现。
- 技术建议仅为建议：最终选择由开发团队决定。
- 手动跟踪：冲刺进度须在执行期间手动更新。
- 无自动校验：无法验证计划与代码库现实是否一致，依赖彻底发现。
- 顺序执行：EXECUTE 一次按顺序处理一个冲刺。
- 外部阻塞：无法解决对外部团队或服务的依赖，记录后继续。
- 上下文窗口：超过 4 个冲刺的项目建议在独立会话中执行，EXECUTE 可从最后一个未完成冲刺恢复。