Menu
2: [T] 制定实施计划，生成执行合约
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Fork Overlay：Task Bundle 持久化 + Failure FSM 集成。在 ce:work 基础上增加 state.md 读写和状态机转换。使用时机：执行 ce:work 时，如果任务有对应的 Task Bundle（docs/tasks/<id>/），加载此 skill 以启用持久化和状态追踪。
Fork Overlay：Codex-first 外部执行器策略。按任务特征路由到 Claude 或 Codex，Codex-first（非品牌路由）。使用时机：需要决定是否将当前任务派发给 Codex 时加载此 skill。
Fork Overlay：经验分层沉淀升级阶梯。检测是否值得将 solution 升级为 pattern 或 skill。使用时机：ce:compound 完成后手动调用，分析 docs/solutions/ 中的重复模式。（不会自动触发，需主动加载此 skill）
Fork Overlay：外部模型调用前置检查门控。调用 Codex/Gemini 之前运行五项检查，防止调用失败浪费时间。使用时机：任何调用外部模型（Codex [C]、Gemini [G]）之前自动运行。
Fork Overlay：ce:work 意图分类门控。在执行前识别任务意图（实现/修复/重构/探索），设定对应的执行策略。使用时机：ce:work Phase 0（环境扫描）之后、Phase 1（Quick Start）之前。
Fork Overlay：Codex Patch Approval 咨询版。当 Codex 返回 patch 时，Claude 审批后才写入文件。使用时机：Codex 以 patch/diff 格式返回代码变更时，由 Claude 作为审批层。
| name | ce:plan |
| description | 2: [T] 制定实施计划，生成执行合约 |
| argument-hint | [功能/需求文档路径] [T=生成.team-contract.md+追溯审查] |
Note: The current year is 2026. Use this when dating plans and searching for recent documentation.
ce:brainstorm defines WHAT to build. ce:plan defines HOW to build it. ce:work executes the plan.
This workflow produces a durable implementation plan. It does not implement code, run tests, or learn from execution-time results. If the answer depends on changing code and seeing what happens, that belongs in ce:work, not here.
Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (AskUserQuestion in Claude Code, request_user_input in Codex, ask_user in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
Ask one question at a time. Prefer a concise single-select choice when natural options exist.
<feature_description> #$ARGUMENTS </feature_description>
If the feature description above is empty, ask the user: "What would you like to plan? Describe the task, goal, or project you have in mind."
Do not proceed until you have a clear planning input.
IMPORTANT: All file references in the plan document must use repo-relative paths (e.g., src/models/user.rb), never absolute paths (e.g., /Users/name/Code/project/src/models/user.rb). This applies everywhere — implementation unit file lists, pattern references, origin document links, and prose mentions. Absolute paths break portability across machines, worktrees, and teammates.
ce:brainstorm produced a requirements document, planning should build from it rather than re-inventing behavior.Every plan should contain:
- Given: [前置条件]; When: [操作]; Then: [可验证的断言]
(需手动验证)。Execution note 时，默认 Execution note: test-first（纯配置/scaffolding/styling/文档单元除外，这些标记 Test expectation: none）A plan is ready when an implementer can start confidently without needing the plan to write the code for them.
If the user references an existing plan file or there is an obvious recent matching plan in docs/plans/:
Deepen intent: The word "deepen" (or "deepening") in reference to a plan is the primary trigger for the deepening fast path. When the user says "deepen the plan", "deepen my plan", "run a deepening pass", or similar, the target document is a plan in docs/plans/, not a requirements document. Use any path, keyword, or context the user provides to identify the right plan. If a path is provided, verify it is actually a plan document. If the match is not obvious, confirm with the user before proceeding.
Words like "strengthen", "confidence", "gaps", and "rigor" are NOT sufficient on their own to trigger deepening. These words appear in normal editing requests ("strengthen that section about the diagram", "there are gaps in the test scenarios") and should not cause a holistic deepening pass. Only treat them as deepening intent when the request clearly targets the plan as a whole and does not name a specific section or content area to change — and even then, prefer to confirm with the user before entering the deepening flow.
Once the plan is identified and appears complete (all major sections present, implementation units defined, status: active):
# Title heading with Created: date instead of frontmatter), route to references/universal-planning.md for editing or deepening instead of Phase 5.3. Non-software plans do not use the software confidence check.Normal editing requests (e.g., "update the test scenarios", "add a new implementation unit", "strengthen the risk section") should NOT trigger the fast path — they follow the standard resume flow.
If the plan already has a deepened: YYYY-MM-DD frontmatter field and there is no explicit user request to re-deepen, the fast path still applies the same confidence-gap evaluation — it does not force deepening.
If the task involves building, modifying, or architecting software (references code, repos, APIs, databases, or asks to build/modify/deploy), continue to Phase 0.2.
If the task is about a non-software domain and describes a multi-step goal worth planning, read references/universal-planning.md and follow that workflow instead. Skip all subsequent phases.
If genuinely ambiguous (e.g., "plan a migration" with no other context), ask the user before routing.
For everything else (quick questions, error messages, factual lookups), respond directly without any planning workflow.
Before asking planning questions, search docs/brainstorms/ for files matching *-requirements.md.
Relevance criteria: A requirements document is relevant if:
If multiple source documents match, ask which one to use using the platform's blocking question tool when available (see Interaction Method). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
If a relevant requirements document exists:
(see origin: <source-path>)If no relevant requirements document exists, planning may proceed from the user's request directly.
If no relevant requirements document exists:
ce:brainstorm firstThe planning bootstrap should establish:
Keep this bootstrap brief. It exists to preserve direct-entry convenience, not to replace a full brainstorm.
If the bootstrap uncovers major unresolved product questions:
ce:brainstorm againIf the origin document contains Resolve Before Planning or similar blocking questions:
If true product blockers remain:
ce:brainstorm to resolve themClassify the work into one of these plan depths:
If depth is unclear, ask one targeted question and then continue.
Prepare a concise planning context summary (a paragraph or two) to pass as input to the research agents:
Run these agents in parallel:
docs/solutions/Slack context (opt-in) — never auto-dispatch. Route by condition:
compound-engineering:research:slack-researcher with the planning context summary in parallel with other Phase 1.1 agents. If the origin document has a Slack context section, pass it verbatim so the researcher focuses on gaps. Include findings in consolidation.Decide whether the plan should carry a lightweight execution posture signal.
Look for signals such as:
Execution target: external-delegate to implementation units that are pure code writingWhen the signal is clear, carry it forward silently in the relevant implementation units.
Ask the user only if the posture would materially change sequencing or risk and cannot be responsibly inferred.
Based on the origin document, user signals, and local findings, decide whether external research adds value.
Read between the lines. Pay attention to signals from the conversation so far:
Leverage repo-research-analyst's technology context:
The repo-research-analyst output includes a structured Technology & Infrastructure summary. Use it to make sharper external research decisions:
Always lean toward external research when:
Skip external research when:
Announce the decision briefly before continuing. Examples:
If Step 1.2 indicates external research is useful, run these agents in parallel:
Summarize:
If the current classification is Lightweight and Phase 1 research found that the work touches any of these external contract surfaces, reclassify to Standard:
.github/workflows/, Dockerfile, deployment scripts)This ensures flow analysis (Phase 1.5) runs and the confidence check (Phase 5.3) applies critical-section bonuses. Announce the reclassification briefly: "Reclassifying to Standard — this change touches [environment variables / exported APIs / CI config] with external consumers."
For Standard or Deep plans, or when user flow completeness is still unclear, run:
Use the output to:
Build a planning question list from:
For each question, decide whether it should be:
Ask the user only when the answer materially affects architecture, scope, sequencing, or risk and cannot be responsibly inferred. Use the platform's blocking question tool when available (see Interaction Method).
Do not run tests, build the app, or probe runtime behavior in this phase. The goal is a strong plan, not partial execution.
feat: Add user authentication or fix: Prevent checkout double-submitfeat, fix, or refactordocs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
docs/plans/ if it does not exist2026-01-15-001-feat-user-authentication-flow-plan.md, 2026-02-03-002-fix-checkout-race-condition-plan.mdFor Standard or Deep plans, briefly consider who is affected by this change — end users, developers, operations, other teams — and how that should shape the plan. For cross-cutting work, note affected parties in the System-Wide Impact section.
Break the work into logical implementation units. Each unit should represent one meaningful change that an implementer could typically land as an atomic commit.
Good units are:
Avoid:
Before detailing implementation units, decide whether an overview would help a reviewer validate the intended approach. This section communicates the shape of the solution — how pieces fit together — without dictating implementation.
When to include it:
| Work involves... | Best overview form |
|---|---|
| DSL or API surface design | Pseudo-code grammar or contract sketch |
| Multi-component integration | Mermaid sequence or component diagram |
| Data pipeline or transformation | Data flow sketch |
| State-heavy lifecycle | State diagram |
| Complex branching logic | Flowchart |
| Mode/flag combinations or multi-input behavior | Decision matrix (inputs -> outcomes) |
| Single-component with non-obvious shape | Pseudo-code sketch |
When to skip it:
Choose the medium that fits the work. Do not default to pseudo-code when a diagram communicates better, and vice versa.
Frame every sketch with: "This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce."
Keep sketches concise — enough to validate direction, not enough to copy-paste into production.
For each unit, include:
Test expectation: none -- [reason] instead of leaving the field blank.
Every feature-bearing unit should include the test file path in **Files:**.
Use Execution note sparingly. Good uses include:
Execution note: Start with a failing integration test for the request/response contract.Execution note: Add characterization coverage before modifying this legacy parser.Execution note: Implement new domain behavior test-first.Execution note: Execution target: external-delegateDo not expand units into literal RED/GREEN/REFACTOR substeps.
If something is important but not knowable yet, record it explicitly under deferred implementation notes rather than pretending to resolve it in the plan.
Examples:
Use one planning philosophy across all depths. Change the amount of detail, not the boundary between planning and execution.
Lightweight
Standard
Deep
For sufficiently large, risky, or cross-cutting work, add the sections that genuinely help:
Do not add these as boilerplate. Include them only when they improve execution quality or stakeholder alignment.
Omit clearly inapplicable optional sections, especially for Lightweight plans.
---
title: [Plan Title]
type: [feat|fix|refactor]
status: active
date: YYYY-MM-DD
origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md # include when planning from a requirements doc
deepened: YYYY-MM-DD # optional, set when the confidence check substantively strengthens the plan
---
# [Plan Title]
## Overview
[What is changing and why]
## Problem Frame
[Summarize the user/business problem and context. Reference the origin doc when present.]
## Requirements Trace
- R1. [Requirement or success criterion this plan must satisfy]
- R2. [Requirement or success criterion this plan must satisfy]
## Scope Boundaries
- [Explicit non-goal or exclusion]
## Context & Research
### Relevant Code and Patterns
- [Existing file, class, component, or pattern to follow]
### Institutional Learnings
- [Relevant `docs/solutions/` insight]
### External References
- [Relevant external docs or best-practice source, if used]
## Key Technical Decisions
- [Decision]: [Rationale]
## Open Questions
### Resolved During Planning
- [Question]: [Resolution]
### Deferred to Implementation
- [Question or unknown]: [Why it is intentionally deferred]
<!-- Optional: Include this section only when the work involves DSL design, multi-component
integration, complex data flow, state-heavy lifecycle, or other cases where prose alone
would leave the approach shape ambiguous. Omit it entirely for well-patterned or
straightforward work. -->
## High-Level Technical Design
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
[Pseudo-code grammar, mermaid diagram, data flow sketch, or state diagram — choose the medium that best communicates the solution shape for this work.]
## Implementation Units
- [ ] **Unit 1: [Name]**
**Goal:** [What this unit accomplishes]
**Requirements:** [R1, R2]
**Dependencies:** [None / Unit 1 / external prerequisite]
**Files:**
- Create: `path/to/new_file`
- Modify: `path/to/existing_file`
- Test: `path/to/test_file`
**Approach:**
- [Key design or sequencing decision]
**Execution note:** [Optional test-first, characterization-first, external-delegate, or other execution posture signal]
**Technical design:** *(optional -- pseudo-code or diagram when the unit's approach is non-obvious. Directional guidance, not implementation specification.)*
**Patterns to follow:**
- [Existing file, class, or pattern]
**Test scenarios:**
<!-- Include only categories that apply to this unit. Omit categories that don't. For units with no behavioral change, use "Test expectation: none -- [reason]" instead of leaving this section blank. -->
- [Scenario: specific input/action -> expected outcome. Prefix with category — Happy path, Edge case, Error path, or Integration — to signal intent]
**Verification:**
- [Outcome that should hold when this unit is complete]
## System-Wide Impact
- **Interaction graph:** [What callbacks, middleware, observers, or entry points may be affected]
- **Error propagation:** [How failures should travel across layers]
- **State lifecycle risks:** [Partial-write, cache, duplicate, or cleanup concerns]
- **API surface parity:** [Other interfaces that may require the same change]
- **Integration coverage:** [Cross-layer scenarios unit tests alone will not prove]
- **Unchanged invariants:** [Existing APIs, interfaces, or behaviors that this plan explicitly does not change — and how the new work relates to them. Include when the change touches shared surfaces and reviewers need blast-radius assurance]
<!-- 当计划预期使用 ce:work [T] 模式时包含此章节；否则可省略。 -->
<!-- 省略时：ce:work [T] 的 Layer 3 自动切换宽松核查模式——对照任务需求逐条核查已修改文件，不按场景表逐行比对（见 ce:work Phase 3.5 Layer 3）。 -->
## 验收场景（[T] 模式使用）
> 每条场景对应 ce:work [T] 的验证层。Layer 3 独立 reviewer 将逐条核查变更文件是否满足以下标准。
> 有 [T] 参数时建议包含此章节；若无，Layer 3 切换宽松核查模式（读文件对照需求，不运行验证命令）并发出警告。
| # | 场景 | 操作步骤 | 期望结果 | 层级 |
|---|------|----------|----------|------|
| 1 | [功能场景描述] | [用户操作步骤] | [可观测的期望结果] | Layer 0/1/2/3 |
## Risks & Dependencies
| Risk | Mitigation |
|------|------------|
| [Meaningful risk] | [How it is addressed or accepted] |
## Documentation / Operational Notes
- [Docs, rollout, monitoring, or support impacts when relevant]
## Sources & References
- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path)
- Related code: [path or symbol]
- Related PRs/issues: #[number]
- External docs: [url]
For larger Deep plans, extend the core template only when useful with sections such as:
## Alternative Approaches Considered
- [Approach]: [Why rejected or not chosen]
## Success Metrics
- [How we will know this solved the intended problem]
## Dependencies / Prerequisites
- [Technical, organizational, or rollout dependency]
## Risk Analysis & Mitigation
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk] | [Low/Med/High] | [Low/Med/High] | [How addressed] |
## Phased Delivery
### Phase 1
- [What lands first and why]
### Phase 2
- [What follows and why]
## Documentation Plan
- [Docs or runbooks to update]
## Operational / Rollout Notes
- [Monitoring, migration, feature flag, or rollout considerations]
/Users/name/Code/project/src/file.ts. Use src/file.ts instead. Absolute paths make plans non-portable across machines, worktrees, and teammates. When a plan targets a different repo than the document's home, state the target repo once at the top of the plan (e.g., **Target repo:** my-other-project) and use repo-relative paths throughout- [ ] syntax for progress trackingRED/GREEN/REFACTOR instructionsce:work [T], include a ## 验收场景 section; the Layer 3 reviewer will check each criterion against changed files. If omitted, Layer 3 falls back to loose-check mode against task requirements (see Phase 3.5 of ce:work).When the plan contains 4+ implementation units with non-linear dependencies, 3+ interacting surfaces in System-Wide Impact, 3+ behavioral modes/variants in Overview or Problem Frame, or 3+ interacting decisions in Key Technical Decisions or alternatives in Alternative Approaches, read references/visual-communication.md for diagram and table guidance. This covers plan-structure visuals (dependency graphs, interaction diagrams, comparison tables) — not solution-design diagrams, which are covered in Section 3.4.
[T] 标志存在时）⚠️ 延迟执行指令：读到此处时不要执行——跳过，继续 Phase 5。待 Phase 5.3.7（Deepening Execution）完成后，在进入 Phase 5.3.8（Document Review）之前返回此处执行。
触发条件: $ARGUMENTS 包含 [T] 或 [T+]
执行时机: Phase 5.3.7 完成后，Phase 5.3.8（Document Review）之前
原因：Phase 5.1 Final Review 和 Phase 5.3 Deepening 均可能修改 Implementation Units（添加/删除文件、变更范围）。必须在这两个阶段都完成后生成合约，确保 allowed_files 基于最终计划，避免与实际执行范围不一致。
Load the team-mode skill for role definitions (合约主, 追溯审查).
合约主读取刚生成的计划文件，提取边界合约：
allowed_files：遍历所有 Implementation Units 的 Files 字段，提取文件路径：
forbidden_surfaces：从计划描述和技术方案中识别高风险文件：
**/plugin.json、package.json（当版本管理是明确任务时例外）db/schema.rb、**/*_schema.*auth、credential、secret、permission 的配置文件required_invariants：从以下优先顺序提取可检查的不变式（转换为命令式短句）：
a. 计划末尾的 ## 验收场景 章节（如存在）→ 提取每个场景的"期望结果"列
b. 各 Implementation Unit 的 Verification 字段 → 提取层级为 Layer 0/1 的可执行验证
c. 若两者均不存在 → required_invariants 留空，合约生成时宣告：「⚠️ 未找到验收场景或 Verification 字段，required_invariants 为空，Patch Gate Rule 4 无法执行后置验证」
转换规则：
requires_human_check: truemax_files_per_patch：默认 1（one-finding-one-patch 原则）
生成合约文件：使用以下格式写入 .team-contract.md（repo 根目录），填充提取的值：
---
team_mode: true
generated_by: "ce:plan [T]"
generated_at: YYYY-MM-DD
plan_source: <刚生成的计划文件路径>
plan_source_commit: null # 计划文件在 Phase 5 写入后尚未 commit，此处始终为 null
# 启用版本检测方法：在 Phase 5 写入计划文件后，运行：
# git log -1 --format='%H' -- <plan_file>
# 将结果填入此字段，或让 ce:work [T] 在执行前手动更新
allowed_files:
- <从 Implementation Units 提取的文件路径>
forbidden_surfaces:
- <识别的高风险文件>
required_invariants:
- "<从 ## 验收场景章节或 Unit Verification 字段转换的不变式命令>"
max_files_per_patch: 1
last_verification_failure: null
---
# Team Contract
## 背景
<!-- 本次计划的任务背景和边界约束 -->
追溯审查者（只读角色）执行历史经验检查：
docs/solutions/ 查找与当前计划相关的历史案例输出：.team-contract.md 写入根目录；追溯审查结果（如有）写入计划文件末尾
Phase 5.2（Write Plan File）完成后，如需启用版本检测：
PLAN_HASH=$(git log -1 --format='%H' -- <plan_source_path> 2>/dev/null)
如 PLAN_HASH 非空（计划文件已提交），在 .team-contract.md 的 YAML frontmatter 中更新：
plan_source_commit: <PLAN_HASH>
如 PLAN_HASH 为空（计划文件尚未提交，是常见状态），保留 null 即可。
建议：在首次运行 ce:work [T] 前手动 commit 计划文件，以启用完整版本保护。
Before finalizing, check:
ce:brainstormExecution noteTest expectation: none -- [reason] annotation is only valid for non-feature-bearing units (pure config, scaffolding, styling)If the plan originated from a requirements document, re-read that document and verify:
ce:brainstormREQUIRED: Write the plan file to disk before presenting any options.
Use the Write tool to save the complete plan to:
docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
Confirm:
Plan written to docs/plans/[filename]
Pipeline mode: If invoked from an automated workflow such as LFG, SLFG, or any disable-model-invocation context, skip interactive questions. Make the needed choices automatically and proceed to writing the plan.
After writing the plan file, automatically evaluate whether the plan needs strengthening.
Two deepening modes:
Interactive mode exists because on-demand deepening is a different user posture — the user already has a plan they are invested in and wants to be surgical about what changes. This applies whether the plan was generated by this skill, written by hand, or produced by another tool.
document-review and this confidence check are different:
document-review skill when the document needs clarity, simplification, completeness, or scope controlPipeline mode: This phase always runs in auto mode in pipeline/disable-model-invocation contexts. No user interaction needed.
Determine the plan depth from the document:
Build a risk profile. Treat these as high-risk signals:
If the plan already appears sufficiently grounded and the thin-grounding override does not apply, report "Confidence check passed — no sections need strengthening" and skip to Phase 5.3.8 (Document Review). Document-review always runs regardless of whether deepening was needed — the two tools catch different classes of issues.
When deepening is warranted, read references/deepening-workflow.md for confidence scoring checklists, section-to-agent dispatch mapping, execution mode selection, research execution, interactive finding review, and plan synthesis instructions. Execute steps 5.3.3 through 5.3.7 from that file, then return here for 5.3.8.
[T] 触发点：如果
$ARGUMENTS包含[T]或[T+]，在进入 Document Review 之前，立即执行 Phase 4.5（Contract Generation）。
When reaching this phase, read references/plan-handoff.md for document review instructions (5.3.8), final checks and cleanup (5.3.9), post-generation options menu (5.4), and issue creation. Do not load this file earlier. Document review is mandatory — do not skip it even if the confidence check already ran.
NEVER CODE! Research, decide, and write the plan.