add-feature

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add Feature

添加功能

Always use the skill

load-plain-reference

to retrieve the ***plain syntax rules — but only if you haven't done so yet.

This skill is the continuous-loop counterpart of the full QA workflow in

forge-plain

. Where that workflow bootstraps an entire project from scratch,

add-feature

adds a single feature to an existing set of

.plain

specs. Like

forge-plain

, it works incrementally: ask focused questions, author the resulting

.plain

content immediately, review just the snippet that changed, and only then move on. Do not run a big upfront interview and then write everything at the end.

请始终使用

load-plain-reference

技能获取***plain语法规则——但仅在你尚未获取过的情况下使用。

本技能是

forge-plain

中完整QA工作流的循环迭代版本。

forge-plain

用于从零开始搭建整个项目，而

add-feature

则是向现有的

.plain

规格文档集中添加单个功能。与

forge-plain

一样，它采用增量式工作方式：提出针对性问题，立即编写生成的

.plain

内容，仅审核刚修改的代码片段，完成后再进行下一步。请勿先进行大规模前置调研，再一次性完成所有编写工作。

Input

输入

A feature request from the user — anything from a one-liner ("add dark mode") to a detailed description. The request may be vague; the functionality loop in Phase 2 will sharpen it as you go.

用户提出的功能需求——可以是一句话（如“添加深色模式”），也可以是详细描述。需求可能较为模糊，第二阶段的功能循环会逐步明确需求细节。

Phase 1 — Scope

第一阶段——范围

Keep this phase short. The goal is to know enough to start the first functionality — not to design the entire feature on paper.

Read the request. Identify what is being asked for at a high level and which existing
```
.plain
```
file(s) the feature most likely belongs to.
Read the target
.plain
file(s). Follow their
```
import
```
and
```
requires
```
chains so you understand the existing definitions, implementation reqs, functional specs, test reqs, and acceptance tests. You need this context to recognize impact when it surfaces in Phase 2.
Frame the work. Ask 1–3 framing questions only if the request leaves you unable to start: which module, what overall behavior, anything obviously cross-cutting. Use AskQuestion with concrete options plus a free-form catch-all. Do not front-load every edge case, every constraint, or every break/augment decision — those happen per-functionality in Phase 2.
Skip ahead when the request is already concrete. If the request is small and unambiguous (e.g. "add a
```
created_at
```
timestamp to
```
Task
```
"), go straight to Phase 2 with a single functionality. Don't manufacture a topic walk for trivial features.

End Phase 1 when you can name the file(s) you'll modify and the first functionality you'll author.

本阶段需简短处理。目标是了解足够信息以启动第一个功能的开发——无需在纸上完成整个功能的设计。

阅读需求：从宏观层面明确用户的需求，确定该功能最可能归属的现有
```
.plain
```
文件。
阅读目标
.plain
文件：跟进文件的
```
import
```
和
```
requires
```
依赖链，了解现有的定义、实现要求、功能规格、测试要求和验收测试。你需要这些上下文信息，以便在第二阶段识别需求带来的影响。
规划工作：仅当需求模糊到无法启动时，提出1-3个框架性问题：归属哪个模块、整体行为是什么、是否存在明显的跨模块内容。使用AskQuestion提供具体选项，同时保留自由输入的兜底选项。请勿提前罗列所有边缘情况、约束条件或修改/增强决策——这些将在第二阶段针对每个功能逐一处理。
需求明确时直接跳过：如果需求小且明确（如“为
```
Task
```
添加
```
created_at
```
时间戳”），直接进入第二阶段处理单个功能。无需为简单功能强行设置讨论环节。

当你能确定要修改的文件以及第一个要编写的功能时，第一阶段结束。

Phase 2 — Functionality loop

第二阶段——功能循环

A functionality is the smallest user-visible piece of behavior that fits in a single ***plain functional spec (≤200 LOC). Walk the feature one functionality at a time. For each functionality, run this tight loop and finish it before starting the next:

一个功能是指最小的用户可见行为单元，可放入单个***plain功能规格文档（≤200行代码）。逐个功能推进开发。针对每个功能，执行以下紧凑循环，完成当前功能后再启动下一个：

2a. Ask

2a. 提问

Use AskQuestion for just the questions needed to author this functionality. Keep batches small (1–5 related questions). Cover only what shapes this functionality:

Behavior — what exactly should happen, what triggers it, what the expected outcome is.
Entities — does this functionality introduce a new concept or extend an existing one, and which attributes are involved?
Edge cases — invalid input, empty state, missing data, boundary values, only as they apply here.
Constraints — business rules, permissions, ordering, size limits that apply here.
Implementation guidance — only if the functionality needs technology, libraries, data formats, or architectural patterns not already in the file or its imports.
Verification — only if conformance testing is configured (see Conformance gate below): what concrete outcome proves this functionality works.

Frame each question with concrete options when the answer space is predictable, plus a free-form catch-all so the user can add detail you didn't anticipate.

仅使用AskQuestion提出编写当前功能所需的问题。每次提问数量要少（1-5个相关问题）。仅覆盖影响当前功能的内容：

行为——具体应发生什么、触发条件是什么、预期结果是什么。
实体——该功能是否引入新概念或扩展现有概念，涉及哪些属性？
边缘情况——无效输入、空状态、缺失数据、边界值，但仅针对当前功能相关的情况。
约束条件——适用于当前功能的业务规则、权限、排序、大小限制。
实现指导——仅当功能需要文件或其依赖中未涉及的技术、库、数据格式或架构模式时才需要。
验证方式——仅当配置了一致性测试（见下文“一致性检查门”）时：什么具体结果能证明该功能正常工作。

当答案范围可预测时，每个问题都要提供具体选项，同时保留自由输入的兜底选项，以便用户补充你未考虑到的细节。

2b. Author

2b. 编写

Translate the answers directly into

.plain

content by editing the target file(s) yourself. Run the relevant checks inline before inserting each snippet:

New concepts — add to the
```
***definitions***
```
section. Define each concept before it is referenced by anything else.
New functional spec — draft the spec text; then always run
```
analyze-if-func-spec-too-complex
```
to verify it implies ≤200 LOC of generated code (if it doesn't, break it down with the user into smaller specs that each fit the limit); always run
```
analyze-func-specs
```
once, with the new spec plus every existing spec that touches the same concepts, to surface every conflicting pair in a single call (do not invoke a pair-by-pair analyzer); only after both analyzers pass, insert it into
```
***functional specs***
```
at the correct chronological position.
New implementation reqs — only when the functionality introduces technology, libraries, data formats, or architectural patterns not already present. Add to
```
***implementation reqs***
```
.
New acceptance tests — only if conformance testing is configured (see Conformance gate below) and the functionality needs concrete verification. Add as a child block under the relevant functional spec.
New test reqs — only if conformance testing is configured and this functionality changes how conformance tests should be run (new framework, new execution command, new constraint). Add to
```
***test reqs***
```
. Rarely needed for a single feature.

After inserting a new functional spec, re-read the chronological ordering and confirm earlier specs still build cleanly. A new spec should slot in at the correct point in the build order; existing specs should not need to move.

将用户的回答直接转化为

.plain

内容，自行编辑目标文件。插入每个代码片段前务必先进行相关检查：

新概念——添加到
```
***definitions***
```
部分。每个概念需在被其他内容引用前完成定义。
新功能规格——起草规格文本；然后务必运行
```
analyze-if-func-spec-too-complex
```
验证其对应的生成代码是否≤200行（如果超过，需与用户沟通拆分为多个符合限制的小型规格）；务必运行一次
```
analyze-func-specs
```
，将新规格与所有涉及相同概念的现有规格一起检查，一次性找出所有冲突对（请勿逐一调用分析器）；只有通过这两个分析器的检查后，才能将其插入到
```
***functional specs***
```
中正确的时序位置。
新实现要求——仅当功能引入了现有文件中未涉及的技术、库、数据格式或架构模式时才添加。将其加入
```
***implementation reqs***
```
。
新验收测试——仅当配置了一致性测试（见下文“一致性检查门”）且该功能需要具体验证时才添加。作为子模块添加到对应的功能规格下。
新测试要求——仅当配置了一致性测试且该功能改变了一致性测试的运行方式（如新框架、新执行命令、新约束）时才添加。将其加入
```
***test reqs***
```
。单个功能很少需要此步骤。

插入新功能规格后，重新阅读时序顺序，确认之前的规格仍能正常衔接。新规格应插入到构建顺序的正确位置；现有规格无需移动。

2c. Handle impact just-in-time

2c. 及时处理影响

analyze-func-specs

reports any conflicting pair involving the new spec, or if authoring this functionality would break (contradict, invalidate) or augment (change the meaning of, add behavior to) an existing concept, functional spec, implementation req, test req, or acceptance test, stop authoring and surface it to the user right now. Show the exact existing snippet (for each conflicting pair the batched analyzer reported) and ask whether to:

(a) keep the existing spec as-is and adjust this functionality to fit around it,
(b) augment the existing spec — embed the proposed new wording in the question so the user can see what they're approving, or
(c) replace the existing spec.

Apply the decision before continuing:

For conflicts, rewrite the affected spec(s) directly so both intents hold, or replace the older spec if it is fully superseded.
For augment or replace, edit the affected spec directly in the
```
.plain
```
file.
If the user approved augmenting a concept, walk every existing functional spec, implementation req, test req, and acceptance test that references it and update each so it still holds under the new definition. Limit changes to the scope the user approved — do not opportunistically rewrite unrelated specs.

Never silently rewrite or weaken prior intent. If you didn't surface a break/augment to the user, you cannot make it.

如果

analyze-func-specs

报告新规格与现有规格存在冲突，或者编写当前功能会破坏（矛盾、失效）或增强（改变含义、添加行为）现有概念、功能规格、实现要求、测试要求或验收测试，请立即停止编写并向用户说明情况。展示确切的现有代码片段（针对批量分析器报告的每个冲突对），询问用户选择：

(a) 保留现有规格，调整当前功能以适配它；
(b) 增强现有规格——在问题中嵌入拟议的新表述，以便用户清楚了解其批准的内容；
(c) 替换现有规格。

根据用户的决定继续推进：

对于冲突，直接重写受影响的规格，确保两者的意图都能实现；如果旧规格完全被取代，则替换旧规格。
对于增强或替换，直接在
```
.plain
```
文件中编辑受影响的规格。
如果用户批准增强某个概念，需检查所有引用该概念的现有功能规格、实现要求、测试要求和验收测试，并逐一更新以适配新定义。修改范围仅限用户批准的内容——请勿随意重写无关规格。

请勿擅自重写或弱化之前的需求意图。如果未向用户说明破坏/增强情况，不得进行相关修改。

2d. Review

2d. 审核

Surface only what just changed using AskQuestion. Embed each snippet directly in the prompt so the user sees exactly what they are approving — the new concept, the new functional spec, the new impl req, the new acceptance test, or any existing spec you just augmented or replaced. For each snippet, frame the question around one or more of:

Missing parts — anything that should be in the spec but isn't (an attribute, a validation rule, an edge case, a missing concept).
Possible extensions — behavior or detail that could reasonably be expanded.
Ambiguities — wording, ordering, or relationships that could be read multiple ways.

Offer concrete options such as "Approve as written", "Extend with …", "Clarify …", plus a free-form catch-all. Apply the user's response back to the

.plain

file(s) and re-surface any snippet that materially changed. Continue until every snippet from this functionality has been explicitly approved.

仅使用AskQuestion展示刚修改的内容。将每个代码片段直接嵌入提示中，让用户清楚看到他们要批准的内容——新概念、新功能规格、新实现要求、新验收测试，或任何你刚增强/替换的现有规格。针对每个代码片段，围绕以下一个或多个方面提出问题：

缺失内容——规格中应包含但未有的内容（如属性、验证规则、边缘情况、缺失的概念）。
可扩展点——可合理扩展的行为或细节。
歧义点——可被多种解读的表述、顺序或关系。

提供具体选项，如“按现有内容批准”、“扩展为……”、“澄清……”，同时保留自由输入的兜底选项。将用户的反馈应用到

.plain

文件中，并重新展示任何实质性修改的代码片段。持续此过程，直到当前功能的所有代码片段都得到明确批准。

2e. Decide what's next

2e. 决定下一步

Either start the next functionality (back to 2a) or, if the feature is fully covered, move to Phase 3.

要么启动下一个功能（回到2a），如果功能已完全覆盖，则进入第三阶段。

Conformance gate

一致性检查门

Steps 2b–2d above only generate

***test reqs***

and

***acceptance tests***

when the project has a

config.yaml

with a valid

conformance-tests-script

entry pointing at an existing conformance-test script in

test_scripts/

. Check the relevant

config.yaml

(the one that covers this module — there may be more than one in multi-part projects) and confirm the referenced script file exists. If conformance testing is not configured, skip those authoring paths entirely; functional specs, concepts, and implementation reqs still get authored normally.

只有当项目的

config.yaml

中存在有效的

conformance-tests-script

条目，且该条目指向

test_scripts/

中现有的一致性测试脚本时，上述2b–2d步骤才会生成

***test reqs***

和

***acceptance tests***

。请检查相关的

config.yaml

（覆盖当前模块的配置——多模块项目可能有多个配置文件），确认引用的脚本文件存在。如果未配置一致性测试，请完全跳过这些编写路径；功能规格、概念和实现要求仍需正常编写。

Phase 3 — Final review

第三阶段——最终审核

Most checks have already happened per-functionality. Phase 3 is a slim consistency pass over the whole result, not a re-do of the functionality loop.

Read the modified
```
.plain
```
file(s) in full.
Verify:
- All new concepts are defined before use and have no circular references.
- Chronological ordering is correct end-to-end (no new spec depends on something that comes after it).
- Functional specs are language-agnostic.
- All external interfaces are explicit (endpoint paths, methods, CLI args, formats, etc.).
- Acceptance tests (if any) are consistent with their parent specs.
Present the final diff for the modified file(s) to the user for approval.
If the user requests changes, apply them and re-review only the affected snippets — do not restart the functionality loop for the whole feature.
Run
plain-healthcheck
. Once the user has approved the final diff, invoke the
```
plain-healthcheck
```
skill before declaring the feature done. It validates every
```
config.yaml
```
and dry-runs every top module, so a feature is never considered finished while the project would fail to render. If
```
plain-healthcheck
```
returns
```
FAIL
```
, work through the numbered list it produced (fix only
```
.plain
```
files /
```
config.yaml
```
/ scripts — never generated code) and re-run it until it returns
```
PASS
```
. Only then tell the user the feature is ready and remind them to re-render with
```
codeplain <module>.plain
```
.

大多数检查已在每个功能的处理过程中完成。第三阶段是对整体结果进行简洁的一致性检查，而非重新执行功能循环。

完整阅读修改后的
```
.plain
```
文件。
验证：
- 所有新概念均在引用前定义，且无循环引用。
- 整体时序顺序正确（无新规格依赖后续内容）。
- 功能规格与语言无关。
- 所有外部接口均明确（端点路径、方法、CLI参数、格式等）。
- 验收测试（如有）与父级规格一致。
向用户展示修改后文件的最终差异，请求批准。
如果用户要求修改，应用修改并仅审核受影响的代码片段——无需针对整个功能重新启动功能循环。
运行
plain-healthcheck
。用户批准最终差异后，在宣布功能完成前调用
```
plain-healthcheck
```
技能。它会验证所有
```
config.yaml
```
并试运行所有顶级模块，确保项目不会在渲染失败的情况下被视为完成。如果
```
plain-healthcheck
```
返回
```
FAIL
```
，请处理它生成的编号列表（仅修复
```
.plain
```
文件/
```
config.yaml
```
/脚本——请勿修改生成的代码），并重新运行直到返回
```
PASS
```
。只有此时才能告知用户功能已准备就绪，并提醒他们使用
```
codeplain <module>.plain
```
重新渲染。

When the User Comes Back with Another Feature

用户提出新功能时

After completing one feature, the user may immediately describe the next. Start again from Phase 1. This creates a continuous loop: scope → functionality loop → final review → scope → ...

完成一个功能后，用户可能立即提出下一个功能需求。请从第一阶段重新开始。这会形成一个持续循环：范围规划 → 功能循环 → 最终审核 → 范围规划 → ...

Validation Checklist

验证 checklist

Target
```
.plain
```
file(s) and their
```
import
```
/
```
requires
```
chain were read before authoring
Each functionality was asked, authored, conflict-checked, and reviewed before the next functionality started
New concepts defined before they are referenced
No circular concept references
Each functional spec implies ≤ 200 LOC (verified via
```
analyze-if-func-spec-too-complex
```
)
No unresolved conflicts with existing specs (verified via a single batched
```
analyze-func-specs
```
call per new spec)
Every break/augment of an existing spec was explicitly surfaced and approved by the user
Functional specs are language-agnostic
All external interfaces are explicit (endpoint paths, methods, CLI args, formats, etc.)
Acceptance tests are consistent with their parent functional specs
User approved the final diff
```
plain-healthcheck
```
returned
```
PASS
```
after the final diff was approved

编写前已阅读目标
```
.plain
```
文件及其
```
import
```
/
```
requires
```
依赖链
每个功能均完成提问、编写、冲突检查和审核后，才启动下一个功能
新概念在引用前已定义
无概念循环引用
每个功能规格对应的生成代码≤200行（通过
```
analyze-if-func-spec-too-complex
```
验证）
与现有规格无未解决的冲突（通过每个新规格对应的单次批量
```
analyze-func-specs
```
调用验证）
所有对现有规格的破坏/增强均已明确告知用户并获得批准
功能规格与语言无关
所有外部接口均明确（端点路径、方法、CLI参数、格式等）
验收测试与父级功能规格一致
用户已批准最终差异
```
plain-healthcheck
```
在用户批准最终差异后返回
```
PASS
```

Question style

提问风格

The questions you put to the user must use simple grammatical structures:

Prefer short, direct sentences over compound or nested clauses.
Use plain words over jargon when both convey the same meaning.
One idea per sentence. If a sentence needs a comma-separated list of clauses, split it.

Simpler grammar must not come at the cost of detail. Keep every constraint, edge case, option, and piece of context the user needs to answer accurately. If simplifying a sentence would drop a detail, split it into more sentences instead.

向用户提出的问题必须使用简单的语法结构：

优先使用简短、直接的句子，而非复合句或嵌套从句。
当普通词汇与专业术语表达相同含义时，使用普通词汇。
每句表达一个想法。如果句子需要逗号分隔的多个从句，请拆分句子。

简化语法不能以牺牲细节为代价。需保留用户准确回答所需的所有约束条件、边缘情况、选项和上下文信息。如果简化句子会丢失细节，请拆分为多个句子。