Workflow
You and the agent plan the overall change, divide it into steps, and detail the next PR. After merge, the agent updates those plans with what it learned.
Read the workflow ↗A practical arrangement is one planning conversation and one fresh implementation conversation for each PR. The planning conversation can cover requirements, the overall plan, the current step, and the next PR design; these do not each need their own chat. The workflow requires a fresh implementation context for each new PR, not a separate chat for every commit or test. This separation matters because planning often contains rejected proposals and superseded assumptions. A fresh implementation session starts from the approved files and current code, reducing the chance that an old discussion is mistaken for the final requirement.
| Conversation | What you do there | When to switch |
|---|---|---|
| Planning conversation | Discuss requirements, ask the agent to inspect the repo and write the plans, review the current PR design, and approve its execution contract. | When that PR is approved, ask for a kickoff with the actual document paths and open a fresh implementation conversation. |
| Implementation conversation for PR A | Give the approved design and contract to the agent. Let it implement, validate, review, commit, and handle authorized PR/CI work. | Keep ordinary fixes, commits, and compact/resume in the same PR context. Do not start PR B here. |
| Review of PR A | Read the diff and handoff. Request repairs in the same implementation conversation, or explicitly authorize merge after you are satisfied. | A separate reviewer conversation is optional, not required. Repairs need updated evidence and CI for the final HEAD. |
| Planning and implementation for PR B | After A is confirmed merged, have the agent update A, its parent step, and the overall plan. Use those records to detail and approve B. | You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation. |
For a feature with two PRs, that usually means three working conversations: planning, implementation A, and implementation B. This is an example, not a fixed quota. A long planning conversation may need replacement, and an interrupted implementation may need recovery. Saved project documents, rather than another chat's memory, carry the agreement between sessions. A handoff is the agent's saved continuation note: what is done, what is still running, and what to do next.
+A practical arrangement is one planning conversation and one fresh implementation conversation for each PR. The planning conversation can cover requirements, the overall plan, the current step, and the next PR design; these do not each need their own chat. The workflow requires a fresh implementation context for each new PR, not a separate chat for every commit or test. This separation matters because planning often contains rejected proposals and superseded assumptions. A fresh implementation session starts from the approved files and current code, reducing the chance that an old discussion is mistaken for the final requirement.
| Conversation | What you do there | When to switch |
|---|---|---|
| Planning conversation | Discuss requirements, ask the agent to inspect the repo and write the plans, review the current PR design, and approve its execution contract. | When that PR is approved, ask for a kickoff with the actual document paths and open a fresh implementation conversation. |
| Implementation conversation for PR A | Give the approved design and contract to the agent. Let it implement, validate, review, commit, and handle authorized PR/CI work. | Keep ordinary fixes, commits, and compact/resume in the same PR context. Do not start PR B here. |
| Review of PR A | Read the diff and handoff. Request repairs in the same implementation conversation, or explicitly authorize merge after you are satisfied. | A separate reviewer conversation is optional, not required. Repairs need updated evidence and CI for the final HEAD. |
| Planning and implementation for PR B | After A is confirmed merged, the implementation conversation records A's merge identity and evidence; the synchronization owner — by default this planning conversation — updates A's parent step and the overall plan, then uses those records to detail and approve B. | Finishing A does not finish the plan: the overall stays open until every step it listed is delivered or you drop it. You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation. |
For a feature with two PRs, that usually means three working conversations: planning, implementation A, and implementation B. This is an example, not a fixed quota. A long planning conversation may need replacement, and an interrupted implementation may need recovery. Saved project documents, rather than another chat's memory, carry the agreement between sessions. A handoff is the agent's saved continuation note: what is done, what is still running, and what to do next.
一个方便的安排是：保留一个 planning 会话，每个 PR 再开一个新的 implementation 会话。需求、overall plan、当前 step 和下一个 PR design，可以在同一个 planning 会话里讨论，不用各开一个。工作流要求的是每个新 PR 用新的 implementation context，不是每次 commit 或 test 都换聊天。 这样分开，是因为 planning 里常有被否决的方案和后来改变的假设。新的 implementation 会话从已批准的文件和当前 code 开始，减少把讨论中的旧想法当成最终要求的机会。
| 会话 | 你在这里做什么 | 什么时候切换 |
|---|---|---|
| Planning 会话 | 讨论需求，让 agent 检查 repo、写计划，review 当前 PR design，并批准 execution contract。 | 当前 PR 批准后，让 agent 准备带真实文档路径的 kickoff，再开新的 implementation 会话。 |
| PR A 的 implementation 会话 | 把已批准的 design 和 contract 交给 agent，让它实现、验证、review、commit，并完成已授权的 PR 和 CI 工作。 | 普通修复、commit、compact 和 resume 都继续处理这个 PR，不在这里启动 PR B。 |
| PR A 的 review | 你看 diff 和 handoff。有问题，就在原 implementation 会话里要求修复；满意以后，再明确授权 merge。 | 可以另开 reviewer 会话，但不是必须。修复后，要更新证据，并确认最终 HEAD 的 CI。 |
| PR B 的 planning 和 implementation | 确认 A 已 merge 后，让 agent 更新 A 的记录、所属 step 和 overall plan，再据此设计并批准 B。 | 你可以回原 planning 会话，也可以新开一个，让它读已保存的计划。B 的 implementation 必须另开新会话。 |
比如一个功能拆成两个 PR，通常就是三个工作会话：planning、implementation A、implementation B。这是示例，不是硬性数量限制。Planning 聊得太长可以换会话，implementation 中断了也可以恢复。会话之间传递约定，靠的是项目里保存的文档，不是指望另一个聊天自动记得前面的事。 Handoff 就是 agent 保存的接续说明，告诉恢复后的会话：做到哪儿了、什么还在跑、下一步是什么。
+一个方便的安排是：保留一个 planning 会话，每个 PR 再开一个新的 implementation 会话。需求、overall plan、当前 step 和下一个 PR design，可以在同一个 planning 会话里讨论，不用各开一个。工作流要求的是每个新 PR 用新的 implementation context，不是每次 commit 或 test 都换聊天。 这样分开，是因为 planning 里常有被否决的方案和后来改变的假设。新的 implementation 会话从已批准的文件和当前 code 开始，减少把讨论中的旧想法当成最终要求的机会。
| 会话 | 你在这里做什么 | 什么时候切换 |
|---|---|---|
| Planning 会话 | 讨论需求，让 agent 检查 repo、写计划，review 当前 PR design，并批准 execution contract。 | 当前 PR 批准后，让 agent 准备带真实文档路径的 kickoff，再开新的 implementation 会话。 |
| PR A 的 implementation 会话 | 把已批准的 design 和 contract 交给 agent，让它实现、验证、review、commit，并完成已授权的 PR 和 CI 工作。 | 普通修复、commit、compact 和 resume 都继续处理这个 PR，不在这里启动 PR B。 |
| PR A 的 review | 你看 diff 和 handoff。有问题，就在原 implementation 会话里要求修复；满意以后，再明确授权 merge。 | 可以另开 reviewer 会话，但不是必须。修复后，要更新证据，并确认最终 HEAD 的 CI。 |
| PR B 的规划与实现 | 确认 A 已 merge 之后，implementation 对话记录 A 的 merge 身份和证据；synchronization owner——默认就是这个 planning 对话——回写 A 的 parent step 和 overall plan，再拿这些记录去细化并批准 B。 | 做完 A 不等于做完计划：overall 里列出的每个 step 都交付、或者被你去掉之前，它一直是未完成的。你可以回到 planning 对话，也可以开一个替代对话去读已保存的 plans。B 要在另一个全新的 implementation 对话里开始。 |
比如一个功能拆成两个 PR，通常就是三个工作会话：planning、implementation A、implementation B。这是示例，不是硬性数量限制。Planning 聊得太长可以换会话，implementation 中断了也可以恢复。会话之间传递约定，靠的是项目里保存的文档，不是指望另一个聊天自动记得前面的事。 Handoff 就是 agent 保存的接续说明，告诉恢复后的会话：做到哪儿了、什么还在跑、下一步是什么。
The package gives you a workflow to follow, specifications that define acceptable work, prompt templates that tell the agent how to execute, and optional hooks that help at specific moments. You do not have to assemble these pieces yourself. Installing them does not, however, turn every written rule into an enforced check.
You and the agent plan the overall change, divide it into steps, and detail the next PR. After merge, the agent updates those plans with what it learned.
Read the workflow ↗The PR requirements tell the agent what a design must contain: inspected code, a commit plan, observable acceptance criteria, and separate evidence for implementation, validation, and review.
Read the specification ↗The working rules tell the agent how to proceed. A filled execution contract records what your project authorizes, what must stay unchanged, what budget applies, and when to stop.
Read the templates ↗The test rules help the agent choose checks that observe the promised behavior. A passing Unit test is not a substitute for a real model or lifecycle test when the claim depends on one.
Read the test rules ↗The continuity preset helps preserve and recover work around compact. The checkpoints preset gives commit and review reminders. Neither supplies a merge guard.
Read setup and limits ↗The project installer copies the same core skill for Codex or Claude Code. You can use either host; you do not need both, and installation does not change global settings.
Read the platform notes ↗You need Git, Python 3.9 or later, and either Codex or Claude Code. Open a terminal on macOS, Linux, or WSL. The commands below download this toolkit and install it into an existing project; they do not create the application you want to build.
Get the repo once
git clone --depth 1 https://github.com/yuema137/structured-coding.gitChoose your agent
./structured-coding/scripts/install codex --project /path/to/your-project./structured-coding/scripts/install claude-code --project /path/to/your-projectKeep the terminal in the parent directory that now contains the cloned structured-coding folder. Replace /path/to/your-project with the project you want the agent to work on, not the toolkit folder. Choose one of the following commands. Quote the path if it contains spaces. If you have already downloaded the toolkit, skip the clone command and use the existing copy.
Prefix your request with $structured-coding in Codex or /structured-coding in Claude Code. Describe the feature and its constraints; ask for planning first, not implementation.
For Codex, the installed folder is .agents/skills/structured-coding inside your project; for Claude Code, it is .claude/skills/structured-coding. Start a new agent session in that project and explicitly invoke the skill. The default installation includes the instructions and supporting resources but registers no hooks. If installation reports an existing copy, compare or back it up before updating; the installer will not overwrite your changes. Global settings and permissions stay unchanged.
Want continuity or checkpoints? See the opt-in commands and limits below.
Think of the specification as the written requirements, not a program watching every action. The agent reads those requirements and applies them to your project. A hook is a small program the host runs at a supported event, such as compact or a tool call. It can check or remind only where its implementation actually provides that behavior.
| Who or what | What it is responsible for | What it does not replace |
|---|---|---|
| You | You define the intended behavior, approve the current PR design, decide material changes, and explicitly authorize merge after review. | You do not have to approve each ordinary fix, test, or commit that is already inside the agreed scope. |
| Specifications and prompt templates | They define what belongs in a PR design, how the agent executes, what counts as validation, and where authorization is required. | Written rules do not automatically block tools. The hook contract includes future requirements, not only features that are shipped. |
| The agent | It reads the full applicable rules, inspects code, drafts the plan, implements, tests, reviews logic, and keeps the design and handoff current. | A completed checklist or confident answer cannot replace test evidence or your approval. The agent remains responsible for following rules even without hooks. |
| Optional hooks | Continuity checks a recorded checkpoint before manual compact, attempts a rescue snapshot for automatic compact, and supplies recovery instructions. Checkpoints supplies commit-preparation advice and a review-intent notice. | They do not understand every design decision, prove tests passed, enforce design freeze, or prevent every merge. They do not run an automatic continuation loop. |
For example, the specification requires the PR design to record validation evidence. The agent runs the test and records its result. A checkpoints reminder can tell it to inspect missing evidence, but cannot decide that the test passed. You review the result before authorizing merge. Installing more hooks does not remove any of those responsibilities.
A practical arrangement is one planning conversation and one fresh implementation conversation for each PR. The planning conversation can cover requirements, the overall plan, the current step, and the next PR design; these do not each need their own chat. The workflow requires a fresh implementation context for each new PR, not a separate chat for every commit or test. This separation matters because planning often contains rejected proposals and superseded assumptions. A fresh implementation session starts from the approved files and current code, reducing the chance that an old discussion is mistaken for the final requirement.
| Conversation | What you do there | When to switch |
|---|---|---|
| Planning conversation | Discuss requirements, ask the agent to inspect the repo and write the plans, review the current PR design, and approve its execution contract. | When that PR is approved, ask for a kickoff with the actual document paths and open a fresh implementation conversation. |
| Implementation conversation for PR A | Give the approved design and contract to the agent. Let it implement, validate, review, commit, and handle authorized PR/CI work. | Keep ordinary fixes, commits, and compact/resume in the same PR context. Do not start PR B here. |
| Review of PR A | Read the diff and handoff. Request repairs in the same implementation conversation, or explicitly authorize merge after you are satisfied. | A separate reviewer conversation is optional, not required. Repairs need updated evidence and CI for the final HEAD. |
| Planning and implementation for PR B | After A is confirmed merged, have the agent update A, its parent step, and the overall plan. Use those records to detail and approve B. | You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation. |
For a feature with two PRs, that usually means three working conversations: planning, implementation A, and implementation B. This is an example, not a fixed quota. A long planning conversation may need replacement, and an interrupted implementation may need recovery. Saved project documents, rather than another chat's memory, carry the agreement between sessions. A handoff is the agent's saved continuation note: what is done, what is still running, and what to do next.
A practical arrangement is one planning conversation and one fresh implementation conversation for each PR. The planning conversation can cover requirements, the overall plan, the current step, and the next PR design; these do not each need their own chat. The workflow requires a fresh implementation context for each new PR, not a separate chat for every commit or test. This separation matters because planning often contains rejected proposals and superseded assumptions. A fresh implementation session starts from the approved files and current code, reducing the chance that an old discussion is mistaken for the final requirement.
| Conversation | What you do there | When to switch |
|---|---|---|
| Planning conversation | Discuss requirements, ask the agent to inspect the repo and write the plans, review the current PR design, and approve its execution contract. | When that PR is approved, ask for a kickoff with the actual document paths and open a fresh implementation conversation. |
| Implementation conversation for PR A | Give the approved design and contract to the agent. Let it implement, validate, review, commit, and handle authorized PR/CI work. | Keep ordinary fixes, commits, and compact/resume in the same PR context. Do not start PR B here. |
| Review of PR A | Read the diff and handoff. Request repairs in the same implementation conversation, or explicitly authorize merge after you are satisfied. | A separate reviewer conversation is optional, not required. Repairs need updated evidence and CI for the final HEAD. |
| Planning and implementation for PR B | After A is confirmed merged, the implementation conversation records A's merge identity and evidence; the synchronization owner — by default this planning conversation — updates A's parent step and the overall plan, then uses those records to detail and approve B. | Finishing A does not finish the plan: the overall stays open until every step it listed is delivered or you drop it. You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation. |
For a feature with two PRs, that usually means three working conversations: planning, implementation A, and implementation B. This is an example, not a fixed quota. A long planning conversation may need replacement, and an interrupted implementation may need recovery. Saved project documents, rather than another chat's memory, carry the agreement between sessions. A handoff is the agent's saved continuation note: what is done, what is still running, and what to do next.
Follow this example in order. Suppose your application reads files and you want an optional alphabetical order while preserving the current default. The paths and PR label in the sample messages are placeholders, not files supplied by this toolkit. Ask the planning agent to create the real documents first, then replace the placeholders before execution. The English entry messages below are identical in both language versions; they do not replace the full original prompts.
Open your target project in your chosen agent host. Invoke $structured-coding in Codex or /structured-coding in Claude Code, then send the planning request below with your actual requirements.
For the example, say that alphabetical mode must visit [c, a, b] as [a, b, c], and that leaving the option off must preserve the old behavior. Explain what is outside scope, such as changing the resume mechanism in this PR. The agent should inspect the repo, ask about unresolved product decisions, and propose an overall direction. It should not start implementing merely because you asked for a plan.
Use the structured-coding skill for this feature. Read its SKILL.md
entrypoint first and load the complete resources its table lists for the
current phase.
diff --git a/docs/index.zh-CN.html b/docs/index.zh-CN.html
index 9414f2b..8925c39 100644
--- a/docs/index.zh-CN.html
+++ b/docs/index.zh-CN.html
@@ -18,7 +18,7 @@
02这套 package 具体提供什么？
我们提供的是一套能接着用的东西：工作流告诉你怎么推进，specification 规定什么才算合格，prompt template 告诉 agent 怎么执行，可选 hook 在特定时刻帮忙检查或提醒。你不用自己把这些零件拼起来。不过，装好了 skill，不代表每条文字规则都已经变成程序强制检查。
01Workflow
你和 agent 先规划整体目标，再拆 step、细化下一个 PR。Merge 后，agent 把新发现写回这些计划。
看完整流程 ↗ 02PR specification
PR requirements 告诉 agent，design 必须包括已检查的 code、commit plan、可观察的验收要求，以及分别记录的 implementation、validation 和 review 证据。
看设计要求 ↗ 03Execution templates
Working rules 告诉 agent 怎么推进。填好的 execution contract 记录你的项目允许做什么、什么必须不变、预算是多少，以及在哪里停止。
看执行模板 ↗ 04Validation rules
Test rules 帮助 agent 选择能观察到承诺行为的检查。如果一个结论依赖真实 model 或完整 lifecycle，Unit test 通过不能替代相应的真实验证。
看测试规则 ↗ 05可选 hook preset
Continuity 帮助 agent 在 compact 前后保存和恢复工作。Checkpoints 提供 commit 和 review 提醒。两者都不提供 merge guard。
看设置方式和限制 ↗ 06两套平台 package
项目 installer 给 Codex 和 Claude Code 安装相同的核心 skill。你选一个 host 就行，不需要两个都用，也不会修改全局设置。
看平台说明 ↗
03装好，再给一个需求。
你需要 Git、Python 3.9 或更新版本，以及 Codex 或 Claude Code 中的一个。在 macOS、Linux 或 WSL 里打开 terminal。下面的命令会下载这个 toolkit，并把 skill 安装到已有项目里，不会替你创建要开发的应用。
获取 repo，只做一次
git clone --depth 1 https://github.com/yuema137/structured-coding.git
选你用的 agent
Codex
./structured-coding/scripts/install codex --project /path/to/your-project
Claude Code
./structured-coding/scripts/install claude-code --project /path/to/your-project
Terminal 保持在刚才 clone 所在的父目录，里面现在应该有 structured-coding 文件夹。把 /path/to/your-project 换成你要让 agent 修改的项目，不是 toolkit 目录。下面两条安装命令选一条就行，路径有空格就加引号。已经下载过 toolkit 的话，跳过 clone，使用现有副本。
然后在目标项目的 agent 聊天里Codex 的请求开头加 $structured-coding，Claude Code 加 /structured-coding。说清 feature 和约束，先让它规划，不要直接开始实现。
Codex 安装后，文件夹在目标项目的 .agents/skills/structured-coding；Claude Code 则在 .claude/skills/structured-coding。接着在目标项目里开新的 agent 会话，明确调用 skill。默认安装带上完整指令和资源，但不注册 hook。如果提示已经有一份，先比较或备份再更新，installer 不会覆盖你的修改。全局设置和权限都不变。
04你、specification、agent 和 hook，到底各管什么？
Specification 是写下来的要求，不是一个盯着所有操作的程序。agent 读这些要求，再结合你的项目执行。Hook 则是 host 在特定事件发生时运行的小程序，比如 compact 或调用工具的时候。它能检查什么、提醒什么，要看我们实际实现了什么，不能光看 specification 里写了什么。
谁来负责 具体做什么 不能替代什么 你 你决定要做出什么行为，批准当前 PR design，对实质变化作出选择，并在 review 后明确授权 merge。 已经在约定范围内的普通修复、test 和 commit，不用每次再等你点头。 Specification 和 prompt template 它们规定 PR design 要写什么、agent 怎么执行、什么算有效的验证，以及哪些地方必须有授权。 文字规则不会自动拦住工具。Hook contract 还包括未来要实现的要求，不全是已经提供的功能。 Agent 它读完整的相关规则，检查 code，写计划，实现、运行 test、review 逻辑，并持续更新 design 和 handoff。 打完勾或说得很有把握，都不能替代 test evidence 和你的批准。即使没装 hook，agent 也得遵守工作流。 可选 hook Continuity 在手动 compact 前检查已记录的 checkpoint，自动 compact 时尝试保存现场，并在恢复时提供读文档的指令。Checkpoints 提供 commit 准备提醒和 review 提醒。 它们不能理解每项设计取舍，不能证明 test 通过，不能强制 design freeze，也不能拦住所有 merge。它们不会让 agent 自动一轮接一轮地继续。
比如，specification 要求 PR design 里记录验证证据。agent 得真的运行 test，再把结果写进去。Checkpoints 可以提醒它检查缺失的证据，但不能替它认定 test 通过。最后你看结果，再决定是否批准 merge。多装几个 hook，也不能省掉这些责任。
-05到底要开几个会话？
一个方便的安排是：保留一个 planning 会话，每个 PR 再开一个新的 implementation 会话。需求、overall plan、当前 step 和下一个 PR design，可以在同一个 planning 会话里讨论，不用各开一个。工作流要求的是每个新 PR 用新的 implementation context，不是每次 commit 或 test 都换聊天。 这样分开，是因为 planning 里常有被否决的方案和后来改变的假设。新的 implementation 会话从已批准的文件和当前 code 开始，减少把讨论中的旧想法当成最终要求的机会。
会话 你在这里做什么 什么时候切换 Planning 会话 讨论需求，让 agent 检查 repo、写计划，review 当前 PR design，并批准 execution contract。 当前 PR 批准后，让 agent 准备带真实文档路径的 kickoff，再开新的 implementation 会话。 PR A 的 implementation 会话 把已批准的 design 和 contract 交给 agent，让它实现、验证、review、commit，并完成已授权的 PR 和 CI 工作。 普通修复、commit、compact 和 resume 都继续处理这个 PR，不在这里启动 PR B。 PR A 的 review 你看 diff 和 handoff。有问题，就在原 implementation 会话里要求修复；满意以后，再明确授权 merge。 可以另开 reviewer 会话，但不是必须。修复后，要更新证据，并确认最终 HEAD 的 CI。 PR B 的 planning 和 implementation 确认 A 已 merge 后，让 agent 更新 A 的记录、所属 step 和 overall plan，再据此设计并批准 B。 你可以回原 planning 会话，也可以新开一个，让它读已保存的计划。B 的 implementation 必须另开新会话。
比如一个功能拆成两个 PR，通常就是三个工作会话：planning、implementation A、implementation B。这是示例，不是硬性数量限制。Planning 聊得太长可以换会话，implementation 中断了也可以恢复。会话之间传递约定，靠的是项目里保存的文档，不是指望另一个聊天自动记得前面的事。 Handoff 就是 agent 保存的接续说明，告诉恢复后的会话：做到哪儿了、什么还在跑、下一步是什么。
+05到底要开几个会话？
一个方便的安排是：保留一个 planning 会话，每个 PR 再开一个新的 implementation 会话。需求、overall plan、当前 step 和下一个 PR design，可以在同一个 planning 会话里讨论，不用各开一个。工作流要求的是每个新 PR 用新的 implementation context，不是每次 commit 或 test 都换聊天。 这样分开，是因为 planning 里常有被否决的方案和后来改变的假设。新的 implementation 会话从已批准的文件和当前 code 开始，减少把讨论中的旧想法当成最终要求的机会。
会话 你在这里做什么 什么时候切换 Planning 会话 讨论需求，让 agent 检查 repo、写计划，review 当前 PR design，并批准 execution contract。 当前 PR 批准后，让 agent 准备带真实文档路径的 kickoff，再开新的 implementation 会话。 PR A 的 implementation 会话 把已批准的 design 和 contract 交给 agent，让它实现、验证、review、commit，并完成已授权的 PR 和 CI 工作。 普通修复、commit、compact 和 resume 都继续处理这个 PR，不在这里启动 PR B。 PR A 的 review 你看 diff 和 handoff。有问题，就在原 implementation 会话里要求修复；满意以后，再明确授权 merge。 可以另开 reviewer 会话，但不是必须。修复后，要更新证据，并确认最终 HEAD 的 CI。 PR B 的规划与实现 确认 A 已 merge 之后，implementation 对话记录 A 的 merge 身份和证据；synchronization owner——默认就是这个 planning 对话——回写 A 的 parent step 和 overall plan，再拿这些记录去细化并批准 B。 做完 A 不等于做完计划：overall 里列出的每个 step 都交付、或者被你去掉之前，它一直是未完成的。你可以回到 planning 对话，也可以开一个替代对话去读已保存的 plans。B 要在另一个全新的 implementation 对话里开始。
比如一个功能拆成两个 PR，通常就是三个工作会话：planning、implementation A、implementation B。这是示例，不是硬性数量限制。Planning 聊得太长可以换会话，implementation 中断了也可以恢复。会话之间传递约定，靠的是项目里保存的文档，不是指望另一个聊天自动记得前面的事。 Handoff 就是 agent 保存的接续说明，告诉恢复后的会话：做到哪儿了、什么还在跑、下一步是什么。
06第一次使用，照着走完一个功能
下面按实际操作顺序走一遍。假设你的应用会读取文件，你想加一个可选的字母排序模式，同时保留当前默认行为。示例消息里的路径和 PR 编号都需要替换，不是这个 toolkit 已经替你创建好的文件。先让 planning agent 写出真实文档，再把真实路径填进 execution 消息。下面的英文入口消息在中英文页面里完全相同，也不能代替原始长 prompt。
1. 开 planning 会话，先说清楚你要什么结果。
在选好的 agent host 里打开目标项目。Codex 用 $structured-coding，Claude Code 用 /structured-coding 调用 skill，然后发送下面的 planning 请求，把需求换成你自己的。
拿这个例子来说，你要说明：输入是 [c, a, b]，启用字母排序后应按 [a, b, c] 读取；不开这个选项，旧行为必须不变。也要说清楚这次不做什么，比如这个 PR 先不改 resume 机制。Agent 应该先检查 repo，把未确定的产品问题问清楚，再提出整体方向。你说的是做计划，它就不能直接开始 implementation。
Use the structured-coding skill for this feature. Read its SKILL.md
entrypoint first and load the complete resources its table lists for the
current phase.
diff --git a/structured-coding/README.md b/structured-coding/README.md
index e08888d..e056457 100644
--- a/structured-coding/README.md
+++ b/structured-coding/README.md
@@ -105,7 +105,7 @@ A practical arrangement is one planning conversation and one fresh implementatio
| Planning conversation | Discuss requirements, ask the agent to inspect the repo and write the plans, review the current PR design, and approve its execution contract. | When that PR is approved, ask for a kickoff with the actual document paths and open a fresh implementation conversation. |
| Implementation conversation for PR A | Give the approved design and contract to the agent. Let it implement, validate, review, commit, and handle authorized PR/CI work. | Keep ordinary fixes, commits, and compact/resume in the same PR context. Do not start PR B here. |
| Review of PR A | Read the diff and handoff. Request repairs in the same implementation conversation, or explicitly authorize merge after you are satisfied. | A separate reviewer conversation is optional, not required. Repairs need updated evidence and CI for the final HEAD. |
-| Planning and implementation for PR B | After A is confirmed merged, have the agent update A, its parent step, and the overall plan. Use those records to detail and approve B. | You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation. |
+| Planning and implementation for PR B | After A is confirmed merged, the implementation conversation records A's merge identity and evidence; the synchronization owner — by default this planning conversation — updates A's parent step and the overall plan, then uses those records to detail and approve B. | Finishing A does not finish the plan: the overall stays open until every step it listed is delivered or you drop it. You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation. |
For a feature with two PRs, that usually means three working conversations: planning, implementation A, and implementation B. This is an example, not a fixed quota. A long planning conversation may need replacement, and an interrupted implementation may need recovery. Saved project documents, rather than another chat's memory, carry the agreement between sessions. A handoff is the agent's saved continuation note: what is done, what is still running, and what to do next.
diff --git a/structured-coding/README.zh-CN.md b/structured-coding/README.zh-CN.md
index bc3430f..b0a921d 100644
--- a/structured-coding/README.zh-CN.md
+++ b/structured-coding/README.zh-CN.md
@@ -105,7 +105,7 @@ Specification 是写下来的要求，不是一个盯着所有操作的程序。
| Planning 会话 | 讨论需求，让 agent 检查 repo、写计划，review 当前 PR design，并批准 execution contract。 | 当前 PR 批准后，让 agent 准备带真实文档路径的 kickoff，再开新的 implementation 会话。 |
| PR A 的 implementation 会话 | 把已批准的 design 和 contract 交给 agent，让它实现、验证、review、commit，并完成已授权的 PR 和 CI 工作。 | 普通修复、commit、compact 和 resume 都继续处理这个 PR，不在这里启动 PR B。 |
| PR A 的 review | 你看 diff 和 handoff。有问题，就在原 implementation 会话里要求修复；满意以后，再明确授权 merge。 | 可以另开 reviewer 会话，但不是必须。修复后，要更新证据，并确认最终 HEAD 的 CI。 |
-| PR B 的 planning 和 implementation | 确认 A 已 merge 后，让 agent 更新 A 的记录、所属 step 和 overall plan，再据此设计并批准 B。 | 你可以回原 planning 会话，也可以新开一个，让它读已保存的计划。B 的 implementation 必须另开新会话。 |
+| PR B 的规划与实现 | 确认 A 已 merge 之后，implementation 对话记录 A 的 merge 身份和证据；synchronization owner——默认就是这个 planning 对话——回写 A 的 parent step 和 overall plan，再拿这些记录去细化并批准 B。 | 做完 A 不等于做完计划：overall 里列出的每个 step 都交付、或者被你去掉之前，它一直是未完成的。你可以回到 planning 对话，也可以开一个替代对话去读已保存的 plans。B 要在另一个全新的 implementation 对话里开始。 |
比如一个功能拆成两个 PR，通常就是三个工作会话：planning、implementation A、implementation B。这是示例，不是硬性数量限制。Planning 聊得太长可以换会话，implementation 中断了也可以恢复。会话之间传递约定，靠的是项目里保存的文档，不是指望另一个聊天自动记得前面的事。 Handoff 就是 agent 保存的接续说明，告诉恢复后的会话：做到哪儿了、什么还在跑、下一步是什么。
diff --git a/structured-coding/SKILL.md b/structured-coding/SKILL.md
index 2ca2070..6651774 100644
--- a/structured-coding/SKILL.md
+++ b/structured-coding/SKILL.md
@@ -39,7 +39,7 @@ The original long prompts are deliberately preserved. Do not replace them with t
7. Audit uncertainty before asking. Resolve bounded details and ordinary failures autonomously. Record departures immediately. Escalate material changes or work outside existing authorization with concrete evidence and a proposed next step.
8. Respect test ownership and the approved cost envelope. Real Gates require real evidence. CI evidence must match the exact final PR head; do not repeat expensive full suites without an independent reason.
9. Continue authorized execution until the PR is ready for operator review, including CI repair when needed. Present the complete handoff and retain the explicit merge-approval boundary.
-10. After confirmed merge, update progress and implications in the step and overall documents. Detail one step ahead; do not begin the next PR in the old implementation context.
+10. After confirmed merge, update progress and implications in the step and overall documents. Completing a PR does not complete its overall; record what remains. Detail one step ahead; do not begin the next PR in the old implementation context.
## Authority and packaging boundaries
diff --git a/structured-coding/prompts/implementation-working-rules.md b/structured-coding/prompts/implementation-working-rules.md
index b6f6026..63fa26b 100644
--- a/structured-coding/prompts/implementation-working-rules.md
+++ b/structured-coding/prompts/implementation-working-rules.md
@@ -199,6 +199,17 @@ ENDPOINT AUTHORITY:
that restriction has a source: the operator's instruction. The absence of any
instruction does not.
+POST-MERGE SYNCHRONIZATION OWNER:
+
+
+ One conversation may own both. Record which, so neither session assumes the
+ other did it. Only the owner writes the parent documents; the other reports
+ to the owner. Do not overwrite parent content that has moved on — reconcile.
+
+ Owning this is not merge authority and does not confer it.
+
NORMAL STOP CONDITION:
diff --git a/structured-coding/references/agent-workflow.md b/structured-coding/references/agent-workflow.md
index 07d2f4c..0761759 100644
--- a/structured-coding/references/agent-workflow.md
+++ b/structured-coding/references/agent-workflow.md
@@ -41,6 +41,16 @@ Work with the operator to establish the final requirement, major use cases, obse
Describe modules and large capabilities. Leave file/function details for the PR that will implement them. Explain meaningful tradeoffs and ask about missing product or direction decisions that the available evidence cannot settle. Continue independent audit and drafting while those decisions are pending.
+Before the operator accepts the overall, and before the first PR is frozen, the document must cover the whole selected effort:
+
+1. The complete effort and its observable outcomes, without pulling in later phases the operator has not approved.
+2. Every currently identifiable necessary high-level step, each with its intended output, broad dependency or order, and acceptance checkpoint. Low-level implementation detail stays unresolved.
+3. Each operator-required outcome matched to a step or to an explicit unresolved decision. A requirement leaves the effort only through an explicit scope decision — never because it does not fit the first PR.
+4. Discovery-dependent work represented as a conditional step or a decision point rather than omitted. An audit may establish that a contemplated change is unnecessary; record that evidence and any scope agreement it needs.
+5. Which subset the current PR covers, and what remains after it.
+
+This is a completeness check on the route, not a demand for speculative architecture, a minimum number of steps, or detail the audits have not produced yet. An effort that genuinely needs one step stays a one-step effort.
+
Use a form suited to the project. An overall document is ready when the operator understands and agrees on what will be delivered and the broad route. Do not infer agreement from silence or proceed into code merely because an overall document exists.
## 3. Step planning: choose useful PR checkpoints
@@ -49,7 +59,7 @@ Read the agreed overall direction and inspect the relevant subsystem. Determine
For multiple PRs, describe each PR's medium scope: likely files or file groups, their relationships, dependencies, and excluded follow-up work. Define a meaningful integration checkpoint for each PR, with observable pass conditions and adversarial criteria. Avoid splitting PRs solely by file count or arbitrary size.
-For one PR, first establish the step scope, then expand that same document in place to PR-level detail. Label its combined step/PR role and link it directly to the overall document. Do not maintain two separate copies of the same plan.
+For one PR, first establish the step scope, then expand that same document in place to PR-level detail. Label its combined step/PR role and link it directly to the overall document. Do not maintain two separate copies of the same plan. This is a document-layout rule about one step; it says nothing about how many steps the overall has.
Keep later PRs at medium scope until evidence from earlier implementation justifies their detailed design. A known dependency that invalidates a later step should be flagged immediately, even though only the next PR is fully detailed.
@@ -191,8 +201,16 @@ After confirmed merge:
3. Update the overall document with resulting progress and material direction/dependency implications.
4. Re-audit and detail the immediate next PR using the merged code and new findings. Flag wider implications at their proper level without rewriting every future PR in detail.
+A merged PR completes that PR. It does not complete its step or its overall: record what remains, and treat the overall as complete only when every enumerated step is delivered or explicitly dropped by an operator scope decision. If merged work revealed necessary steps the overall does not list, add them at their own level — a PR that is already frozen and bounded stays bounded, and the remaining work is planned separately rather than folded into the active PR.
+
For a combined step/PR document, update it once and then the overall document; do not invent a separate parent or create a self-reference.
+Those four actions have owners, and the owner is recorded rather than inferred. By default the implementation session owns action 1, because it holds the evidence; the synchronization owner named in the contract — by default the planning session — owns actions 2 and 3, because it holds the agreement and will design the next PR from those records; action 4 belongs to the planning session. One conversation may own all of it, and a project that wants implementation-side propagation says so in the contract. The point of recording it is that neither session assumes the other did it.
+
+The handoff between them is explicit. The implementation session marks parent synchronization pending in the PR document and names the owner; the owner records the parent updates and acknowledges in the same place what it recorded. Only the owner writes the parent documents; the other reports to the owner. Parent content that has moved on is reconciled, never overwritten. Owning propagation is not merge authority and does not confer it.
+
+An implementation conversation may close once its PR document carries the merge identity, validation evidence, deviations, remaining issues and a durable handoff, and responsibility for any remaining synchronization has been explicitly accepted. Durable does not mean published: a project that keeps its plans out of version control keeps them there.
+
Make status updates through the repository's established documentation process. If the implementation branch is closed or protected, prepare/use the appropriate documentation change rather than silently pushing to a protected branch. Do not claim parent synchronization is complete until it is recorded in the authoritative location.
The next PR design must obtain its own freeze/implementation authorization and begin in a fresh execution session. Its knowledge comes from merged state and binding documents, not unfinished memory from the previous PR.
diff --git a/structured-coding/references/agent-workflow.zh-CN.md b/structured-coding/references/agent-workflow.zh-CN.md
index abde5c2..3d7c89f 100644
--- a/structured-coding/references/agent-workflow.zh-CN.md
+++ b/structured-coding/references/agent-workflow.zh-CN.md
@@ -41,6 +41,16 @@
描述 module 和主要能力，把文件与函数细节留给实际实现它们的 PR。解释有意义的取舍；现有证据无法确定的产品或方向问题，需要询问 operator。等待决定时，继续独立的 audit 和起草工作。
+operator 认可 overall 之前、第一个 PR freeze 之前，这份文档必须覆盖整个选定的 effort：
+
+1. 完整的 effort 及其可观察的产出，不要把 operator 还没批准的后续阶段拉进来。
+2. 当前能识别出来的每一个必要的高层 step，各自写清预期产出、大致依赖或顺序、验收检查点。低层实现细节可以先不定。
+3. operator 要求的每一项产出，都要对上一个 step，或者对上一个明确"尚未决定"的条目。某项需求要退出这个 effort，只能通过明确的 scope 决定——绝不能因为它装不进第一个 PR 就消失。
+4. 依赖后续发现才能定的工作，要写成条件 step 或决策点，而不是省略掉。audit 有可能证明某个设想的改动其实不必要；那就把这个证据、以及它需要的 scope 共识记下来。
+5. 当前这个 PR 覆盖其中哪一部分，做完之后还剩什么。
+
+这是对路线完整性的检查，不是要你去编还没做过 audit 的架构、也不是规定 step 的最小数量。真的只需要一步的 effort，就还是一步。
+
采用适合项目的文档形式。operator 理解并同意交付内容和大方向后，overall doc 才算准备好。不能把沉默当成同意，也不能因为已有 overall doc 就开始改代码。
## 3. Step planning：选择有意义的 PR checkpoint
@@ -49,7 +59,7 @@
如果需要多个 PR，描述各自的 medium scope：可能涉及的文件或文件组、彼此关系、依赖和不包含的后续工作。为每个 PR 定义有意义的 integration checkpoint、可观察的通过条件和 adversarial criteria。不要只按文件数或任意大小拆 PR。
-如果只需要一个 PR，先确定 step scope，再将同一文档原地扩充到 PR 级细节。标明其兼任 step/PR 的角色，并直接链接 overall doc。不要维护同一计划的两个独立副本。
+如果只需要一个 PR，先确定 step scope，再将同一文档原地扩充到 PR 级细节。标明其兼任 step/PR 的角色，并直接链接 overall doc。不要维护同一计划的两个独立副本。这是关于单个 step 的文档排布规则，它跟 overall 有几个 step 无关。
后续 PR 保持 medium scope，直到前面实现提供的证据足以支撑详细设计。已知依赖如果推翻后续 step，应立即指出，即使当前只会完整细化下一个 PR。
@@ -191,8 +201,16 @@ review 要求修复时，明确恢复同一个 PR 的工作、核对状态并重
3. 向 overall doc 回写进度，以及重要方向或依赖影响。
4. 根据 merged code 和新发现，重新 audit 并细化紧接着的下一个 PR。在相应层级标注更广的影响，不必详细重写所有后续 PR。
+PR merge 了，只说明这个 PR 完成了。它不代表对应的 step 或 overall 完成了：把剩余工作记下来；只有当所有列出的 step 都交付、或者被 operator 明确的 scope 决定去掉之后，overall 才算完成。如果已合并的工作暴露出 overall 里没有列的必要 step，就在它自己的层级上补上——已经 freeze 且有边界的 PR 保持原边界，剩下的工作单独规划，不要塞进正在进行的 PR。
+
同一文档兼任 step/PR 时，只更新一次，然后更新 overall doc；不要虚构独立 parent 或产生自引用。
+这四件事各有归属，而归属是记下来的，不是靠推断。默认：action 1 由 implementation session 负责，因为证据在它手里；action 2 和 3 由 contract 里写明的 synchronization owner 负责——默认是 planning session，因为共识在它手里，而且它要拿这些记录去设计下一个 PR；action 4 属于 planning session。一个对话全包也可以；希望由 implementation 侧回写的项目，在 contract 里写清楚就行。记下来的意义在于：不要两个 session 都以为对方做了。
+
+两者之间的交接是明确的。implementation session 在 PR 文档里把 parent 同步标成 pending 并写明 owner；owner 完成 parent 更新后，在同一处确认自己记了什么。只有 owner 写 parent 文档，另一方向 owner 汇报。parent 里已经往前走了的内容要对账，不能覆盖。负责回写不等于 merge 权限，也不会带来 merge 权限。
+
+implementation 对话可以在满足以下条件后关闭：它的 PR 文档里有 merge 身份、验证证据、偏离、遗留问题和一份可持续的 handoff，并且剩余同步工作的责任已被明确接手。可持续不等于发布出去：把 plans 留在版本库之外的项目，就继续留在外面。
+
按照仓库既有文档流程更新状态。implementation branch 已关闭或受保护时，准备或使用合适的文档改动途径，不要静默 push 到受保护 branch。未在权威位置记录前，不能声称 parent 同步已经完成。
下一个 PR design 必须取得自己的 freeze/implementation 授权，并在 fresh execution session 开始。其知识来自 merged state 和 binding 文档，不来自上一个 PR 尚未结束的记忆。
diff --git a/translations.json b/translations.json
index 6591774..445ff1c 100644
--- a/translations.json
+++ b/translations.json
@@ -3,15 +3,15 @@
"presentation_source_pair": {
"english": "docs/content.en.json",
"chinese": "docs/content.zh-CN.json",
- "english_sha256": "a2bc3a9756629106426fb0fe2cd6b769b6b8453c576e8311f4dae2b56ad660d8",
- "chinese_sha256": "2644dc6f143cd15de1247150011056b018cdd427157e8b2c7caf5cfc8765ff48"
+ "english_sha256": "91679c50493e7436472193f0df1bbeea23f394f0cffc9298a23d4ae89a553687",
+ "chinese_sha256": "c7519c04a757c2cd803054701cf860469d6e8c6cb5f2188210aa12861ef579cc"
},
"pairs": [
{
"english": "README.md",
"chinese": "README.zh-CN.md",
- "english_sha256": "f835a245555081fe6b8cef930ce30e6d884af166342bb32b1f23cf8416cb7de1",
- "chinese_sha256": "94818040582045da1939bd3276d17a1a087ba8c6f5a586c80b9d9754d186ed3b"
+ "english_sha256": "d37e33be8f8557e696948fd4d772cb0a09ffdaf9af7bfb720baea077d2153a8a",
+ "chinese_sha256": "feb45b76ed2ede456d61229e38f4a077fc152d66e97cccdbc5feedc0ee5a465a"
},
{
"english": "TUTORIAL.md",
@@ -22,14 +22,14 @@
{
"english": "structured-coding/README.md",
"chinese": "structured-coding/README.zh-CN.md",
- "english_sha256": "3a90c843c21087c8190cc23bd082454f9f0bcb2d5e1eba784f133bde67b3fa36",
- "chinese_sha256": "b0287cf97eb6b84f62c2464b3bd88cdd8039a8ec988503982cc850dc6e521b6d"
+ "english_sha256": "ccb1cc10b0c17daf9da5426668f15ba89fd3f6f26e35dd6cfc960f2b37fb24c2",
+ "chinese_sha256": "a6fb530e6b8dcba43159a13668f436a7042ad79ba1054db6634d9043a9fac4b3"
},
{
"english": "structured-coding/references/agent-workflow.md",
"chinese": "structured-coding/references/agent-workflow.zh-CN.md",
- "english_sha256": "a4b7d08b0016f358863cda8089b480bf049099b1786dfdc14b49bfbf39cb2127",
- "chinese_sha256": "4a2495a38d0a525c79bfb3a3a6ba061160c7c0a153b198c77d200016e51c45e5"
+ "english_sha256": "8fc2399f9887b9a4587f5c418b6b61a02b9da19ec6096d3f375e3a232b70d4dd",
+ "chinese_sha256": "1355271e74a542cfcd3e1bf71585d5e4d6398a6dfd0e0f99bcd2ae3a42371d2e"
},
{
"english": "structured-coding/references/adaptation.md",
@@ -45,8 +45,8 @@
}
],
"specification_sha256": {
- "structured-coding/SKILL.md": "bea7c82214ef6332ba587385b0d76a71c820e05f8d9a95796ba6d16efb40f0e0",
- "structured-coding/prompts/implementation-working-rules.md": "e6c80df1f0f2af4eac4cf98d6fea13441362602c0ab02be021fa135078f02d6d",
+ "structured-coding/SKILL.md": "66170c488940105b5bd127349bd8abda9eee48c27fa4ea1f1ca1fe2879a1e36f",
+ "structured-coding/prompts/implementation-working-rules.md": "4b07b2594aadc1d0fd4d98c2af6f980695ff65dda8e3cc642c8ac95dcfafedfa",
"structured-coding/prompts/pr-design-requirements.md": "dc5d654ee5e4e2d7a7558726823eb3452167f551d7841403ac8a98c862972baa",
"structured-coding/prompts/test-ci-gate-rules.md": "ace549262e04880577248189f8ae460f18c13a6b2ecf6280d600566c2cd003e1",
"structured-coding/references/hook-contract.md": "bb4aeec01af96ea42d0fb4248e9b9e3ccf54cae8f7266f523eed57031a68d81f"