Back to Details

spec-loop-plan-task

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
This skill is mandatory unless the user explicitly opts out.
Read this file fully unless it is already loaded in the current session context.
Apply project instructions such as 
AGENTS.md
when present.
After loading the applicable rules, immediately emit 🫡.
除非用户明确选择退出，否则本Skill为强制要求。
请完整阅读本文件，除非它已加载到当前会话语境中。
若存在
AGENTS.md
等项目说明，请遵循其要求。
加载适用规则后，请立即发送🫡。

Shared workflow rules

通用工作流规则

  • Principle over ceremony
  • Intent-first. Judge by outcome, not checklist.
  • Whenever the LLM stops or pauses, it must explain the reason explicitly.
  • If 
    AGENTS.md
    and these rules conflict, stop and ask the User.
  • Enforcement, pre-edit gate, and LLM stewardship
  • These rules are mandatory. The LLM enforces them.
  • Only the User may override these rules.
  • 原则优先于形式
  • 以意图为先。以结果而非checklist为评判标准。
  • 每当LLM停止或暂停时，必须明确解释原因。
  • 若
    AGENTS.md
    与本规则存在冲突，请停止操作并询问用户。
  • 规则执行、编辑前检查与LLM管理
  • 本规则为强制要求，由LLM执行。
  • 仅用户可 override 本规则。

Read and enforcement model

阅读与执行模型

  • Already injected or attached: don't re-read.
  • Else: read once, keep a 3-5 line digest in context.
  • Re-read only if the digest is missing or the User says the rules changed.
  • 已注入或附加的内容：无需重新阅读。
  • 其他情况：阅读一次，在语境中保留3-5行摘要。
  • 仅当摘要丢失或用户说明规则已变更时，才重新阅读。

Phase model

阶段模型

Phases:
  • PLAN - research, design/spec, and test specification for executable work.
  • IMPLEMENTATION - approved executable changes and their coupled updates, including code, tests, config, dependencies, packaging, runtime assets, and any required documentation updates.
  • DONE - verified and accepted.
PLAN allows edits only to planning artifacts for the current executable work item, especially task files. Commands are allowed for research or verification only if they do not change repository contents outside those artifacts. If they would, treat that work as IMPLEMENTATION and get explicit User approval first.
Anything touching executable behavior, tests, build or config, dependencies, packaging, runtime assets, or documentation coupled to those changes is IMPLEMENTATION and needs explicit User instruction.
Work starts in PLAN and returns to PLAN after each work item unless the User says otherwise.
  • Ask questions before PLAN whenever scope, constraints, domain language, expected behavior, priorities, or other essential uncertainties remain.
  • During PLAN, ask targeted User questions as soon as essential doubts appear in Research or Design. Do not guess through material ambiguity just because work is not yet formally blocked.
  • No permission questions for already requested work.
  • Starting PLAN artifacts, entering IMPLEMENTATION, and marking DONE require explicit User instruction.
  • After approval, material implementation changes still require renewed User approval. On the short planning path, use this skill again before continuing. On the task-file path, follow 
    ../spec-loop-implementation-flow/SKILL.md
    for implementation-time handling and return-to-PLAN routing.
  • Phases are exclusive unless the User allows combined planning-plus-implementation.
Phase model governs executable work and documentation coupled to that work. Standalone documentation work is outside it unless the User or project instructions say otherwise.
阶段划分：
  • PLAN（规划）：针对可执行工作进行调研、设计/规格定义及测试规范制定。
  • IMPLEMENTATION（实施）：经批准的可执行变更及相关更新，包括代码、测试、配置、依赖项、打包、运行时资源，以及任何必要的文档更新。
  • DONE（完成）：已验证并获认可。
PLAN阶段仅允许编辑当前可执行工作项的规划工件，尤其是任务文件。仅允许执行用于调研或验证的命令，且不得修改这些工件之外的仓库内容。若会修改，则将该工作视为IMPLEMENTATION阶段，并需先获得用户明确批准。
任何涉及可执行行为、测试、构建或配置、依赖项、打包、运行时资源，或与这些变更相关联的文档的工作，均属于IMPLEMENTATION阶段，需用户明确指示。
工作默认从PLAN阶段开始，完成每个工作项后返回PLAN阶段，除非用户另有说明。
  • 若范围、约束、领域语言、预期行为、优先级或其他关键不确定性仍存在，在进入PLAN阶段前需先提问。
  • 在PLAN阶段，调研或设计过程中一旦出现关键疑问，需立即向用户提出针对性问题。不得因工作尚未正式受阻，就对重大歧义进行猜测。
  • 对于已请求的工作，无需再次询问权限。
  • 启动PLAN工件、进入IMPLEMENTATION阶段及标记为DONE，均需用户明确指示。
  • 获得批准后，若实施内容发生重大变更，仍需重新获得用户批准。若采用短规划路径，需再次使用本Skill后再继续；若采用任务文件路径，请遵循
    ../spec-loop-implementation-flow/SKILL.md
    处理实施阶段的流程及返回PLAN阶段的路由。
  • 阶段为互斥的，除非用户允许将规划与实施合并进行。
阶段模型适用于可执行工作及与之关联的文档。独立文档工作不在此范围内，除非用户或项目说明另有规定。

Planning paths

规划路径

Executable changes require explicit planning before implementation.
Choose between:
  • the short planning path documented in chat, and
  • the task-file path documented in task artifacts.
Take the short planning path when all of the following are true:
  • this is the first planning pass for the task in the current conversation;
  • the required research is lightweight;
  • the design has a single clear implementation path;
  • the required verification is lightweight and easy to track in chat;
  • no task file exists yet for this task.
In that case, document the plan in chat only and present it to the user as a request to approve both:
  • using the short planning path without creating a task file, and
  • implementation from that chat plan.
Project instructions or the user may still require the task-file path for work that would otherwise match the short planning path.
Use the task-file path otherwise.
Once a task file exists for a task, continue using that task file for that task instead of moving planning back into chat.
If the short path later needs heavier research, more than one plausible implementation path, or heavier verification, use this skill again and promote the task to a task file before continuing.
可执行变更需在实施前进行明确规划。
可选择以下两种路径：
  • 聊天中记录的短规划路径；
  • 任务工件中记录的任务文件路径。
当满足以下所有条件时，采用短规划路径：
  • 这是当前对话中针对该任务的首次规划；
  • 所需调研工作较简单；
  • 设计有单一清晰的实施路径；
  • 所需验证工作较简单且易于在聊天中跟踪；
  • 该任务尚未存在任务文件。
在此情况下，仅需在聊天中记录规划，并向用户请求批准以下两项：
  • 使用短规划路径而不创建任务文件；
  • 根据该聊天规划进行实施。
即使符合短规划路径的条件，项目说明或用户仍可能要求采用任务文件路径。
其他情况均采用任务文件路径。
一旦某任务存在任务文件，后续该任务的规划需继续使用该任务文件，而非转回聊天进行规划。
若短路径后续需要更深入的调研、存在多个可行的实施路径，或需要更复杂的验证，请再次使用本Skill，并将该任务升级为任务文件后再继续。

ADR and documentation routing

ADR与文档路由

Ceremony follows executable impact, not file type.
Standalone documentation work may stay outside the task-file path when all of the following are true:
  • the requested work is confined to documentation artifacts;
  • it does not require executable changes; and
  • no project rule requires a task file.
ADRs and instruction files, including skill files, are normally treated as standalone documentation when the requested work is confined to those artifacts.
ADR-only work is not implementation-task planning by default. When the requested work is only to create, revise, or compare an ADR, do not create a task file unless the user explicitly asks for one or the ADR work is part of a larger task already being tracked in a task file.
Use ADRs for decisions affecting public behavior, dependencies, or long-term design.
  • Record architecture decisions in 
    architecture-decisions/
    as one file per decision with meaningful names.
  • ADR file names should use readable descriptive words, without prefixes, numbering, or abbreviations.
  • Use the short template: Title, Date, Status, Context, Decision, Consequences.
If documentation is part of a larger executable change, keep it in that task. Plan the documentation update during PLAN and perform it during IMPLEMENTATION.
形式规范取决于可执行影响，而非文件类型。
当满足以下所有条件时，独立文档工作可无需采用任务文件路径：
  • 请求的工作仅限于文档工件；
  • 无需进行可执行变更；
  • 项目规则未要求创建任务文件。
ADR（架构决策记录）及说明文件（包括Skill文件），当请求的工作仅限于这些工件时，通常视为独立文档。
默认情况下，仅涉及ADR的工作不属于实施任务规划。当请求的工作仅为创建、修订或比较ADR时，无需创建任务文件，除非用户明确要求，或该ADR工作是已在任务文件中跟踪的更大任务的一部分。
对于影响公共行为、依赖项或长期设计的决策，请使用ADR。
  • 将架构决策记录在
    architecture-decisions/
    目录下，每个决策对应一个文件，文件名需具有明确含义。
  • ADR文件名应使用可读性强的描述性词汇，无需前缀、编号或缩写。
  • 使用简短模板：标题、日期、状态、背景、决策、影响。
若文档工作是更大规模可执行变更的一部分，请将其纳入该任务中。在PLAN阶段规划文档更新，在IMPLEMENTATION阶段执行更新。

Glossary policy

术语表策略

Default glossary policy:
  • glossary use is opted in;
  • project or session instructions may opt out;
  • when the project uses the AsciiDoc glossary format defined by 
    spec-loop-write-glossary
    , use 
    spec-loop-write-glossary
    ;
  • otherwise follow the project's glossary format.
Recognize 
glossary.adoc
and 
glossary.md
as project glossary files. If both exist, ask which one is canonical before updating either.
Once a project glossary exists, it defines shared domain language above individual tasks and code.
Creating the first project glossary from approved information is normally standalone documentation work and does not require a task file unless the user or project rules require one.
When approved work changes, clarifies, or implements shared domain terms:
  • include the glossary update in the plan, including short-path work;
  • perform the glossary update during IMPLEMENTATION;
  • use 
    spec-loop-write-glossary
    when the glossary uses the Spec Loop AsciiDoc glossary format;
  • otherwise update the glossary directly in the project's active format.
默认术语表策略：
  • 默认启用术语表；
  • 项目或会话说明可选择禁用；
  • 若项目使用
    spec-loop-write-glossary
    定义的AsciiDoc术语表格式，请使用
    spec-loop-write-glossary
    ；
  • 否则遵循项目的术语表格式。
将
glossary.adoc
和
glossary.md
视为项目术语表文件。若两者均存在，在更新前需询问用户哪个是标准版本。
一旦项目术语表存在，它将定义独立于单个任务和代码的共享领域语言。
根据已批准的信息创建首个项目术语表通常属于独立文档工作，无需创建任务文件，除非用户或项目规则要求。
当已批准的工作变更、澄清或实现共享领域术语时：
  • 将术语表更新纳入规划，包括短路径工作；
  • 在IMPLEMENTATION阶段执行术语表更新；
  • 若术语表使用Spec Loop AsciiDoc格式，请使用
    spec-loop-write-glossary
    ；
  • 否则直接以项目的当前格式更新术语表。

Task-file path

任务文件路径

When the task-file path is in use:
  • read task-file-constitution.md fully;
  • create or update the required task files under it;
  • draft or revise the active task file to capture Research, Scenario when required, Design, Test specification, and task administration needed for the current increment;
  • if no suitable task file exists yet, create one before executable changes;
  • chat stays for coordination and approvals, but the task file is the durable planning artifact for that task;
  • before treating task-file planning as complete or asking for implementation approval from a task file, use ../spec-loop-prepare-implementation-approval/SKILL.md;
  • after task-file implementation approval, use ../spec-loop-implementation-flow/SKILL.md for implementation-phase routing, clarification handling, 
    Implementation notes
    checks, and 
    in-progress
    -> 
    review
    checks.
If project instructions do not define a task directory, use 
tasks/
as the default.
When drafting or repairing embedded PlantUML in task files, follow 
examples/example-task-wordle-cli.md
as a collection of valid diagram patterns and section-placement examples. Do not treat it as a required task length or as a model for how much detail every task or first planning pass must contain.
当使用任务文件路径时：
  • 完整阅读task-file-constitution.md；
  • 在其下创建或更新所需的任务文件；
  • 起草或修订当前任务文件，以记录调研、必要场景、设计、测试规范，以及当前增量所需的任务管理内容；
  • 若尚无合适的任务文件，需在进行可执行变更前创建一个；
  • 聊天仅用于协调和审批，任务文件是该任务的持久规划工件；
  • 在认为任务文件规划已完成，或从任务文件请求实施批准前，请使用../spec-loop-prepare-implementation-approval/SKILL.md；
  • 获得任务文件的实施批准后，请使用../spec-loop-implementation-flow/SKILL.md处理实施阶段的路由、澄清处理、
    Implementation notes
    检查，以及
    in-progress
    -> 
    review
    检查。
若项目说明未定义任务目录，默认使用
tasks/
目录。
起草或修复任务文件中嵌入的PlantUML时，请参考
examples/example-task-wordle-cli.md
中的有效图表模式和章节放置示例。请勿将其视为任务所需的长度标准，或每个任务首次规划必须包含的详细程度模板。