Codex
./structured-coding/scripts/install codex --project /path/to/your-projectYou 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.
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 workflow for this feature. First agree with me on
-requirements, module-level direction, and overall step boundaries; then detail
-the current step. Work on planning for now.
+06Your first feature, from installation to the next PR
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.
1. Open the planning conversation and explain the result you want.
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.
+First agree with me on requirements, module-level direction, and overall
+step boundaries; then detail the current step. Work on planning for now.
Requirements: ...
Before you move onBefore moving on, you should be able to explain the goal and main steps in your own words. Ask the agent to rewrite anything you cannot review; you do not have to author its design document yourself.
2. Ask the same planning agent to detail only the next PR.
The overall plan describes the feature and its main steps. A step plan explains which PRs fit together. The current PR design goes deeper: the agent reads real code and callers before naming the files, functions, commits, and checks. Later PRs can remain less detailed because this implementation may reveal new facts. The PR requirements define the detailed format. Ask the agent to follow that complete specification; you do not need to reconstruct the template yourself.
For the alphabetical-order PR, acceptance must observe the reader visiting [a, b, c], not just a configuration value being stored. Ask for a check that would fail if a caller silently dropped the option. Each commit needs separate implementation, validation, and logic-review items. If a step needs only one PR, the agent can expand the step document in place instead of maintaining a duplicate.
Read the overall and step documents, audit the current code, and prepare the
-PR 01a design doc and filled execution contract. Follow the original PR
-requirements for the commit checklist. Separate implementation, validation,
-and review, and prepare the design for my approval.
Before you move onThe agent should give you the real PR design path and a filled execution contract. Agree where these records live and which, if any, belong in Git. Private planning notes and raw logs do not automatically belong in the published product.
3. Review the agreement and explicitly approve this PR.
Check what changes, what stays unchanged, what is excluded, and what observable result will count as done. The execution contract should also say whether the agent may commit, push a branch, open or update a PR, and repair CI, and where it must stop. These are separate permissions; asking for local implementation alone does not authorize publication.
When the design matches your intent, explicitly approve that concrete design and contract. The agent records DESIGN FROZEN and the approval reference. Freeze protects the agreed scope, invariants, and acceptance, not the whole file: the agent must still update discoveries, progress, and evidence. Approval of implementation is not approval to merge.
For authorized validation, existing subscription-covered usage does not need another provider/account or billing question. Metered API calls and separately charged usage need applicable spending authorization. Existing time limits, quotas, and explicit restrictions still apply; the agent must not switch accounts or enable paid fallback to evade them. Separate approval requirements for real training still apply when the task has them.
Before you move onAsk for a kickoff that identifies the approved design, filled contract, implementation base, next action, and stopping condition. Do not copy a template containing unresolved paths into execution and assume it is ready.
4. Open a fresh implementation conversation for this PR.
Start a genuinely new conversation in the same target project. Do not just rename the planning conversation. Invoke the skill again and give it the kickoff with the actual paths. The new agent does not need the entire planning chat: it needs the durable agreement and the source files that establish current state.
Before editing, the agent must read the approved design, filled contract, and complete execution and test rules. It checks the branch, HEAD, existing edits, merged prerequisites, and relevant running jobs. It preserves unrelated work. If you explicitly enabled a preset, it also reads that preset's interface and binds this session to the current PR; it must not assume installation selected an active PR for it.
Execute PR 01a. The approved DESIGN FROZEN document is docs/plan/pr-01a.md,
-and the filled contract is docs/plan/pr-01a-contract.md.
-Use structured-coding. Read Implementation Working Rules and TEST / CI / GATE
-in full, reconcile actual state, and begin.
+PR 01a design doc and filled execution contract. Use structured-coding:
+start from its SKILL.md entrypoint and load what the PR design row lists.
+Follow the original PR requirements for the commit checklist. Separate
+implementation, validation, and review, and prepare the design for my
+approval.
Before you move onThe agent should give you the real PR design path and a filled execution contract. Agree where these records live and which, if any, belong in Git. Private planning notes and raw logs do not automatically belong in the published product.
3. Review the agreement and explicitly approve this PR.
Check what changes, what stays unchanged, what is excluded, and what observable result will count as done. The execution contract should also say whether the agent may commit, push a branch, open or update a PR, and repair CI, and where it must stop. These are separate permissions; asking for local implementation alone does not authorize publication.
When the design matches your intent, explicitly approve that concrete design and contract. The agent records DESIGN FROZEN and the approval reference. Freeze protects the agreed scope, invariants, and acceptance, not the whole file: the agent must still update discoveries, progress, and evidence. Approval of implementation is not approval to merge.
For authorized validation, existing subscription-covered usage does not need another provider/account or billing question. Metered API calls and separately charged usage need applicable spending authorization. Existing time limits, quotas, and explicit restrictions still apply; the agent must not switch accounts or enable paid fallback to evade them. Separate approval requirements for real training still apply when the task has them.
Before you move onAsk for a kickoff that identifies the approved design, filled contract, implementation base, next action, and stopping condition. Do not copy a template containing unresolved paths into execution and assume it is ready.
4. Open a fresh implementation conversation for this PR.
Start a genuinely new conversation in the same target project. Do not just rename the planning conversation. Invoke the skill again and give it the kickoff with the actual paths. The new agent does not need the entire planning chat: it needs the durable agreement and the source files that establish current state.
Before editing, the agent must re-read the skill entrypoint and its execute row, then the approved design, filled contract, and complete execution and test rules. It checks the branch, HEAD, existing edits, merged prerequisites, and relevant running jobs. It preserves unrelated work. If you explicitly enabled a preset, it also reads that preset's interface and binds this session to the current PR; it must not assume installation selected an active PR for it.
Execute PR 01a. The approved DESIGN FROZEN document is
+.structured-coding/plans/order-flag/pr-01a.md, and the filled contract is
+.structured-coding/plans/order-flag/pr-01a-contract.md.
+Use structured-coding: read its SKILL.md entrypoint, then the complete
+resources its execute row lists, including Implementation Working Rules and
+TEST / CI / GATE in full. Reconcile actual state, and begin.
Continue autonomously to READY FOR OPERATOR REVIEW under the contract.
Do not merge.
Before you move onConfirm that the agent is working on the intended PR and has loaded the approved paths. The kickoff delegates execution within the contract; it does not grant extra host permissions or enable hooks.
5. Let the agent complete the agreed implementation loop.
The agent implements a coherent piece, runs relevant checks, reviews the logic and callers, records what happened, and commits. A Unit test failure or an extra caller inside the agreed scope normally means investigate, fix, and continue. It should not ask you to approve every commit. If branch publication and PR/CI work are authorized, it continues through those steps too.
You step in when the proposed solution changes a frozen requirement, public interface, material scope, or approved budget. The agent should bring evidence and a concrete choice, not merely say it is blocked. Review that choice before the dependent work proceeds.
If the conversation reaches compact, you are still working on the same PR. Before manual compact, the agent updates its design and handoff. After compact or resume, it rereads the full rules and checks actual Git and process state. A running test must be checked before launching a duplicate. Continuity helps with mechanical checks and recovery instructions; it does not write a correct semantic handoff for the agent.
Before you move onYou should be able to ask for the current milestone, evidence, and next action and get an answer grounded in saved records. A hook notice is not proof that the agent performed a review or completed a test.
6. Review the finished PR, then decide whether to merge.
For an authorized PR workflow, READY FOR OPERATOR REVIEW means the agreed implementation, validation, and logic review are complete, the PR is published or updated, and required CI passes on its exact final HEAD. HEAD identifies the current commit. A green result for an earlier commit does not prove a later edit passed.
Read the diff alongside the promised behavior, deviations, test evidence, and remaining limits. If something is wrong, request repairs in the same implementation conversation. The agent should update the evidence and final-head CI before handing it back. You can use a separate reviewer agent, but the workflow does not require another conversation for review.
When satisfied, explicitly authorize merging the specific PR and reviewed candidate. Without that approval, the agent stops at review readiness. The shipped presets do not provide a merge guard, so this boundary remains an instruction and any separately configured host/repository protection. A local-only contract has a local endpoint; the agent must not pretend it created or validated a remote PR.
Before you move onAfter an authorized merge, require confirmation of the actual remote result and merge commit. A merge command being requested is not the same as a completed merge.
7. Update the plans before starting the next PR.
After merge is confirmed, ask the agent to mark the current PR merged, update its parent step, and update the overall plan. The updates should record both completed work and discoveries that change what comes next. Hooks do not currently verify this post-merge planning work.
For example, the alphabetical-order implementation may reveal that resume stores only a filename. A later PR may need a clearer way to identify the next occurrence of a repeated filename. Bring that discovery into the next PR's design instead of continuing from an old assumption.
Return to your planning conversation, or open a new planning conversation that reads the updated files. Detail and approve the next PR, then start another fresh implementation conversation. The previous PR's agent may finish its records and prepare a handoff; it must not quietly begin implementing the next PR in the old context.
Before you move onOne PR is finished when its result and implications are recorded, not merely when a merge notification appears. You now repeat the same cycle with a smaller amount of uncertainty.
07Where you step in.
You do not need to approve every commit. You do need to own the decisions that change the agreement.
- 01
Set the goal
You explain the goal and limits.
- 02
Approve the design
You approve this PR's boundaries.
- 03
Review the result
You review evidence before merge.
After design approval, the agent investigates, implements, validates, reviews, records, and commits. If PR and CI work are authorized, it completes those too without waiting for you to prompt each step.A material scope change or an action outside existing authorization comes back to you with evidence and a proposal.
diff --git a/docs/index.zh-CN.html b/docs/index.zh-CN.html
index df5c317..a81303d 100644
--- a/docs/index.zh-CN.html
+++ b/docs/index.zh-CN.html
@@ -19,16 +19,22 @@
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 保存的接续说明，告诉恢复后的会话：做到哪儿了、什么还在跑、下一步是什么。
-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 workflow for this feature. First agree with me on
-requirements, module-level direction, and overall step boundaries; then detail
-the current step. Work on planning for now.
+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.
+First agree with me on requirements, module-level direction, and overall
+step boundaries; then detail the current step. Work on planning for now.
Requirements: ...
进入下一步前，确认这件事进入下一步前，你应该能用自己的话讲清楚目标和主要步骤。哪里看不懂，就让 agent 重写到你能 review 为止，不需要你替它写 design doc。
2. 让同一个 planning agent 细化下一个 PR。
Overall plan 讲整个功能和主要步骤，step plan 讲几个 PR 怎么配合，当前 PR design 才深入到具体修改。Agent 先读真实 code 和调用方，再写要改的文件、函数、commit 和检查。后面的 PR 可以先粗一些，因为这次 implementation 可能会带来新发现。 具体格式由 PR requirements 管；你让 agent 按完整 specification 准备，不需要自己重新拼一份模板。
字母排序这个 PR，验收要观察 reader 是否真的按 [a, b, c] 读取，不能只检查配置里存进了一个值。你可以要求：如果某个调用方漏传了选项，这个检查必须失败。每个 commit 的 implementation、validation 和逻辑 review 要分别记录。一个 step 如果只需要一个 PR，就把 step doc 直接展开，不用再维护一份重复计划。
Read the overall and step documents, audit the current code, and prepare the
-PR 01a design doc and filled execution contract. Follow the original PR
-requirements for the commit checklist. Separate implementation, validation,
-and review, and prepare the design for my approval.
进入下一步前，确认这件事Agent 应该交给你真实的 PR design 路径和填好的 execution contract。一起确定这些记录放在哪儿、哪些需要进 Git。私下的 planning 笔记和原始 log，不会因为产生了就自动成为对外发布的内容。
3. Review 这份约定，明确批准当前 PR。
你要看清楚：这次改什么、保留什么、不做什么，以及观察到什么结果才算完成。Execution contract 还得写明，agent 能不能 commit、push branch、创建或更新 PR、修复 CI，以及应该停在哪儿。这些是不同的授权。只让它在本地实现，不代表允许它发布到远程。
Design 符合你的意思后，明确批准这份具体的 design 和 contract。Agent 再记录 DESIGN FROZEN 和批准依据。Freeze 固定的是已约定的 scope、invariants 和验收要求，不是把整份文件锁住。新发现、进度和证据仍然要接着写。批准 implementation，也不等于批准 merge。
已授权的验证，现有 subscription 能覆盖，就不用再问一次 provider、账户或费用。按量计费 API 和其他额外收费，需要适用的费用授权。已有时间限制、配额和明确约束仍然有效；agent 不能为了绕过限制就换账户或启用付费 fallback。任务如果另有真实 training 的授权要求，也仍然要遵守。
进入下一步前，确认这件事让 agent 准备一份 kickoff，写清已批准的 design、填好的 contract、implementation base、下一步和停止条件。不要把还留着占位路径的模板直接粘过去，就当 execution 已经准备好了。
4. 为这个 PR 新开一个 implementation 会话。
在同一个目标项目里，真正新开一个会话，不是给 planning 会话改个名字。重新调用 skill，把带真实路径的 kickoff 发过去。新的 agent 不需要整段 planning 聊天记录，但需要已经保存的约定，以及能确认当前状态的源文件。
修改前，agent 必须读已批准的 design、填好的 contract，以及完整的 execution 和 test rules。它还要检查 branch、HEAD、已有改动、前置 PR 是否 merge，以及相关 job 是否仍在运行。无关改动要保留。如果你明确启用了某个 preset，它还要读对应说明，把当前 session 绑定到这个 PR。安装了 hook，不等于已经替它选好了当前 PR。
Execute PR 01a. The approved DESIGN FROZEN document is docs/plan/pr-01a.md,
-and the filled contract is docs/plan/pr-01a-contract.md.
-Use structured-coding. Read Implementation Working Rules and TEST / CI / GATE
-in full, reconcile actual state, and begin.
+PR 01a design doc and filled execution contract. Use structured-coding:
+start from its SKILL.md entrypoint and load what the PR design row lists.
+Follow the original PR requirements for the commit checklist. Separate
+implementation, validation, and review, and prepare the design for my
+approval.
进入下一步前，确认这件事Agent 应该交给你真实的 PR design 路径和填好的 execution contract。一起确定这些记录放在哪儿、哪些需要进 Git。私下的 planning 笔记和原始 log，不会因为产生了就自动成为对外发布的内容。
3. Review 这份约定，明确批准当前 PR。
你要看清楚：这次改什么、保留什么、不做什么，以及观察到什么结果才算完成。Execution contract 还得写明，agent 能不能 commit、push branch、创建或更新 PR、修复 CI，以及应该停在哪儿。这些是不同的授权。只让它在本地实现，不代表允许它发布到远程。
Design 符合你的意思后，明确批准这份具体的 design 和 contract。Agent 再记录 DESIGN FROZEN 和批准依据。Freeze 固定的是已约定的 scope、invariants 和验收要求，不是把整份文件锁住。新发现、进度和证据仍然要接着写。批准 implementation，也不等于批准 merge。
已授权的验证，现有 subscription 能覆盖，就不用再问一次 provider、账户或费用。按量计费 API 和其他额外收费，需要适用的费用授权。已有时间限制、配额和明确约束仍然有效；agent 不能为了绕过限制就换账户或启用付费 fallback。任务如果另有真实 training 的授权要求，也仍然要遵守。
进入下一步前，确认这件事让 agent 准备一份 kickoff，写清已批准的 design、填好的 contract、implementation base、下一步和停止条件。不要把还留着占位路径的模板直接粘过去，就当 execution 已经准备好了。
4. 为这个 PR 新开一个 implementation 会话。
在同一个目标项目里，真正新开一个会话，不是给 planning 会话改个名字。重新调用 skill，把带真实路径的 kickoff 发过去。新的 agent 不需要整段 planning 聊天记录，但需要已经保存的约定，以及能确认当前状态的源文件。
修改前，agent 必须先重读 skill entrypoint 和它的 execute 行，再读已批准的 design、填好的 contract，以及完整的 execution 和 test rules。它还要检查 branch、HEAD、已有改动、前置 PR 是否 merge，以及相关 job 是否仍在运行。无关改动要保留。如果你明确启用了某个 preset，它还要读对应说明，把当前 session 绑定到这个 PR。安装了 hook，不等于已经替它选好了当前 PR。
Execute PR 01a. The approved DESIGN FROZEN document is
+.structured-coding/plans/order-flag/pr-01a.md, and the filled contract is
+.structured-coding/plans/order-flag/pr-01a-contract.md.
+Use structured-coding: read its SKILL.md entrypoint, then the complete
+resources its execute row lists, including Implementation Working Rules and
+TEST / CI / GATE in full. Reconcile actual state, and begin.
Continue autonomously to READY FOR OPERATOR REVIEW under the contract.
Do not merge.
进入下一步前，确认这件事确认 agent 找对了 PR，也读到了已批准的真实路径。Kickoff 让它在 contract 范围内执行，不会额外授予 host 权限，也不会替你启用 hook。
5. 让 agent 把约定范围内的实现循环做完。
Agent 做完一块有意义的修改，运行相关检查，review 逻辑和调用方，记录结果，然后 commit。Unit test 失败，或者在约定范围内发现漏掉的调用方，通常就是查原因、修复、继续。不该每个 commit 都来问你一次。发布 branch、创建 PR 和处理 CI 已经授权的话，它也应该接着做完。
需要你回来决定的是：解决办法要改变已冻结的要求、public interface、重要 scope，或者超出批准预算。Agent 应该带上证据和具体选择，而不是只说一句卡住了。你决定以后，它才能继续受影响的工作。
聊到需要 compact 时，做的还是同一个 PR。手动 compact 前，agent 更新 design 和 handoff。Compact 或 resume 后，它重新读完整规则，核对真实 Git 状态和 process 状态。原来有 test 在跑，就先检查它，别直接再开一份。Continuity 能帮助做机械检查、提供恢复指令，但不会替 agent 写出语义正确的 handoff。
进入下一步前，确认这件事你问当前做到哪一步、有什么证据、接下来做什么，agent 应该能根据已保存的记录回答。收到 hook 提醒，不代表它已经 review，也不代表某个 test 已完成。
6. Review 做完的 PR，再决定是否 merge。
对于已授权的 PR 工作流，READY FOR OPERATOR REVIEW 表示约定的 implementation、validation 和逻辑 review 已完成，PR 已创建或更新，而且准确最终 HEAD 的必需 CI 已通过。HEAD 标识当前 commit。旧 commit 的 CI 绿了，不能证明后来又改的内容也通过了。
你把 diff 和原先答应交付的行为对起来，看偏离原因、test evidence 和剩余限制。有问题，就在原 implementation 会话里要求修复。Agent 要更新证据和最终 HEAD 的 CI，再交回来。你可以另找一个 reviewer agent，但工作流不要求必须为 review 多开一个会话。
满意后，明确授权 merge 这个 PR 和你 review 过的版本。没拿到这份授权，agent 就停在可 review 的状态。目前提供的 preset 没有 merge guard，所以这条边界仍靠指令，以及另外配置的 host 或 repo 保护来维持。Contract 如果只授权本地工作，就按本地终点交付，不能假装已经创建或验证了远程 PR。
进入下一步前，确认这件事授权 merge 后，要确认远程确实完成了，并拿到 merge commit。发起了 merge 请求，不等于 merge 已经成功。
7. 更新计划，再开始下一个 PR。
确认 merge 后，让 agent 把当前 PR 标为已 merge，再更新所属 step，最后更新 overall plan。不光写完成了什么，还要写这次发现会怎样影响后面的工作。目前 hook 不会验证这些 merge 后的 planning 更新。
比如实现字母排序时，发现 resume 只保存一个文件名。后面的 PR 可能需要更明确地标识：同名文件重复出现时，下次到底从哪一次继续。把这个发现带进下一个 PR design，别沿着已经过时的假设接着做。
你可以回原 planning 会话，也可以新开一个，让它读更新后的文件。细化并批准下一个 PR，再开新的 implementation 会话。上一个 PR 的 agent 可以把记录补完、准备交接，但不能在旧 context 里悄悄开始实现下一个 PR。
进入下一步前，确认这件事一个 PR 的收尾，不只是收到 merge 通知，还要把结果和对后续工作的影响写下来。接着重复这套流程时，你就比上次少了一些没弄清楚的问题。
07你在哪些地方参与？
不用每次 commit 都点头。但会改变约定的决定，得由你来做。
- 01
定目标
你说清楚目标和限制。
- 02
批准设计
你确认这次允许改什么。
- 03
review 结果
你检查证据，再决定 merge。
设计批准以后，agent 自己调查、实现、验证、review、记录并 commit。PR 和 CI 工作如果已经授权，它也会继续做完，不用你一步一步催。遇到实质性范围变化，或者现有授权以外的操作，agent 带着证据和方案回来找你。
diff --git a/scripts/hook_install.py b/scripts/hook_install.py
index 0230745..8813165 100644
--- a/scripts/hook_install.py
+++ b/scripts/hook_install.py
@@ -516,7 +516,16 @@ def replace(path, expected, replacement):
def verify_skill(plan):
source = ROOT / "structured-coding"
- dependencies = {"scripts/continuity.py", "references/continuity.md"}
+ # The entrypoint set is required for every preset: a hook that names
+ # SKILL.md is worthless if the installed copy lacks it or predates the
+ # routing the hook points at.
+ dependencies = {
+ "SKILL.md",
+ "references/agent-workflow.md",
+ "references/adaptation.md",
+ "scripts/continuity.py",
+ "references/continuity.md",
+ }
selected = plan.get("presets", ("continuity",))
if "checkpoints" in selected or "standards" in selected:
dependencies.update({"scripts/checkpoints.py", "references/checkpoints.md"})
diff --git a/scripts/test_continuity.py b/scripts/test_continuity.py
index 3a159c3..bb26161 100644
--- a/scripts/test_continuity.py
+++ b/scripts/test_continuity.py
@@ -3,6 +3,7 @@
import importlib.util
import json
import os
+import shutil
import subprocess
import sys
import tempfile
@@ -117,11 +118,21 @@ def payload(self, mode, session=None):
),
}
- def event(self, mode, host="codex", session=None, raw=None, cwd=None):
+ def skill_copy(self, remove=()):
+ """A relocated installation, so a message must resolve its own paths."""
+ destination = self.root / "installed"
+ if not destination.exists():
+ shutil.copytree(hook_install.ROOT / "structured-coding", destination)
+ for relative in remove:
+ (destination / relative).unlink()
+ return destination / "scripts/continuity.py"
+
+ def event(self, mode, host="codex", session=None, raw=None, cwd=None,
+ script=RUNTIME):
result = subprocess.run(
[
sys.executable,
- str(RUNTIME),
+ str(script),
"event",
"--host",
host,
@@ -401,6 +412,44 @@ def test_sessions_are_isolated_and_resume_requires_full_reads(self):
self.assertIn(value, message)
self.assertNotIn("Initial design.md", message)
+ def context(self, script=RUNTIME):
+ return self.event("session-start", script=script)[0]["hookSpecificOutput"][
+ "additionalContext"
+ ]
+
+ def test_session_start_names_the_installed_entrypoint_absolutely(self):
+ relocated = self.skill_copy()
+ self.assertNotEqual(relocated.parents[1], RUNTIME.parents[1])
+ for script in (RUNTIME, relocated):
+ with self.subTest(script=str(script), state="unbound"):
+ expected = str(script.resolve().parents[1] / "SKILL.md")
+ self.assertTrue(Path(expected).is_absolute())
+ message = self.context(script)
+ self.assertIn(expected, message)
+ self.assertIn("required", message)
+ self.activate()
+ for script in (RUNTIME, relocated):
+ with self.subTest(script=str(script), state="recovery"):
+ expected = str(script.resolve().parents[1] / "SKILL.md")
+ message = self.context(script)
+ self.assertIn(expected, message)
+ # The message claims the entrypoint is the first file listed, so
+ # assert it against the bound documents too, not only the prompts.
+ for later in ("design.md", "implementation-working-rules.md"):
+ self.assertLess(message.index(expected), message.index(later))
+
+ def test_absent_entrypoint_is_omitted_rather_than_fabricated(self):
+ script = self.skill_copy(remove=("SKILL.md",))
+ absent = str(script.resolve().parents[1] / "SKILL.md")
+ unbound = self.context(script)
+ self.assertNotIn(absent, unbound)
+ self.assertIn("no PR is bound", unbound)
+ self.activate()
+ recovery = self.context(script)
+ self.assertNotIn(absent, recovery)
+ self.assertIn("IN FULL", recovery)
+ self.assertIn("implementation-working-rules.md", recovery)
+
def test_changed_branch_cannot_reuse_checkpoint(self):
self.activate()
self.checkpoint()
diff --git a/scripts/test_hook_presets.py b/scripts/test_hook_presets.py
index 1163bdf..9d56d6f 100644
--- a/scripts/test_hook_presets.py
+++ b/scripts/test_hook_presets.py
@@ -453,6 +453,25 @@ def test_stale_noop_plan_concurrent_installer_and_selected_dependencies(self):
hooks.verify_skill(plan)
self.assertEqual(path.read_text(), "customized")
+ def test_entrypoint_files_are_part_of_a_complete_installation(self):
+ plan = self.install("codex", ["continuity"])
+ for relative in (
+ "SKILL.md",
+ "references/agent-workflow.md",
+ "references/adaptation.md",
+ ):
+ with self.subTest(relative=relative):
+ path = plan["skill"] / relative
+ original = path.read_bytes()
+ path.unlink()
+ with self.assertRaisesRegex(ValueError, "update the skill"):
+ hooks.verify_skill(plan)
+ with self.assertRaisesRegex(ValueError, "update the skill"):
+ hooks.doctor("codex", self.project)
+ path.write_bytes(original)
+ # Restoring every file leaves the installation reporting healthy again.
+ self.assertIn("Installed presets", hooks.doctor("codex", self.project))
+
def test_redirected_journal_or_metadata_never_written(self):
plan = self.install("codex", ["continuity"])
target = self.root / "keep"
diff --git a/structured-coding/README.md b/structured-coding/README.md
index 2666d71..e2a10f4 100644
--- a/structured-coding/README.md
+++ b/structured-coding/README.md
@@ -27,9 +27,11 @@ Three messages carry one feature from an idea to a reviewed PR. You approve twic
### 1. Plan the feature
```text
-Use the structured-coding workflow for this feature. First agree with me on
-requirements, module-level direction, and overall step boundaries; then detail
-the current step. Work on planning for now.
+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.
+First agree with me on requirements, module-level direction, and overall
+step boundaries; then detail the current step. Work on planning for now.
Requirements: ...
```
@@ -39,9 +41,11 @@ The agent asks what it cannot infer, inspects your actual code, and writes the o
```text
Read the overall and step documents, audit the current code, and prepare the
-PR 01a design doc and filled execution contract. Follow the original PR
-requirements for the commit checklist. Separate implementation, validation,
-and review, and prepare the design for my approval.
+PR 01a design doc and filled execution contract. Use structured-coding:
+start from its SKILL.md entrypoint and load what the PR design row lists.
+Follow the original PR requirements for the commit checklist. Separate
+implementation, validation, and review, and prepare the design for my
+approval.
```
You get a PR design with an audited commit plan and a filled execution contract. Read it, ask for changes, and approve it once it describes what you actually want built.
@@ -49,10 +53,12 @@ You get a PR design with an audited commit plan and a filled execution contract.
### 3. Execute after approval, in a fresh session
```text
-Execute PR 01a. The approved DESIGN FROZEN document is docs/plan/pr-01a.md,
-and the filled contract is docs/plan/pr-01a-contract.md.
-Use structured-coding. Read Implementation Working Rules and TEST / CI / GATE
-in full, reconcile actual state, and begin.
+Execute PR 01a. The approved DESIGN FROZEN document is
+.structured-coding/plans/order-flag/pr-01a.md, and the filled contract is
+.structured-coding/plans/order-flag/pr-01a-contract.md.
+Use structured-coding: read its SKILL.md entrypoint, then the complete
+resources its execute row lists, including Implementation Working Rules and
+TEST / CI / GATE in full. Reconcile actual state, and begin.
Continue autonomously to READY FOR OPERATOR REVIEW under the contract.
Do not merge.
```
@@ -116,9 +122,11 @@ Open your target project in your chosen agent host. Invoke $structured-coding in
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.
```text
-Use the structured-coding workflow for this feature. First agree with me on
-requirements, module-level direction, and overall step boundaries; then detail
-the current step. Work on planning for now.
+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.
+First agree with me on requirements, module-level direction, and overall
+step boundaries; then detail the current step. Work on planning for now.
Requirements: ...
```
@@ -134,9 +142,11 @@ For the alphabetical-order PR, acceptance must observe the reader visiting [a, b
```text
Read the overall and step documents, audit the current code, and prepare the
-PR 01a design doc and filled execution contract. Follow the original PR
-requirements for the commit checklist. Separate implementation, validation,
-and review, and prepare the design for my approval.
+PR 01a design doc and filled execution contract. Use structured-coding:
+start from its SKILL.md entrypoint and load what the PR design row lists.
+Follow the original PR requirements for the commit checklist. Separate
+implementation, validation, and review, and prepare the design for my
+approval.
```
**Before you move on**
@@ -159,13 +169,15 @@ Ask for a kickoff that identifies the approved design, filled contract, implemen
Start a genuinely new conversation in the same target project. Do not just rename the planning conversation. Invoke the skill again and give it the kickoff with the actual paths. The new agent does not need the entire planning chat: it needs the durable agreement and the source files that establish current state.
-Before editing, the agent must read the approved design, filled contract, and complete execution and test rules. It checks the branch, HEAD, existing edits, merged prerequisites, and relevant running jobs. It preserves unrelated work. If you explicitly enabled a preset, it also reads that preset's interface and binds this session to the current PR; it must not assume installation selected an active PR for it.
+Before editing, the agent must re-read the skill entrypoint and its execute row, then the approved design, filled contract, and complete execution and test rules. It checks the branch, HEAD, existing edits, merged prerequisites, and relevant running jobs. It preserves unrelated work. If you explicitly enabled a preset, it also reads that preset's interface and binds this session to the current PR; it must not assume installation selected an active PR for it.
```text
-Execute PR 01a. The approved DESIGN FROZEN document is docs/plan/pr-01a.md,
-and the filled contract is docs/plan/pr-01a-contract.md.
-Use structured-coding. Read Implementation Working Rules and TEST / CI / GATE
-in full, reconcile actual state, and begin.
+Execute PR 01a. The approved DESIGN FROZEN document is
+.structured-coding/plans/order-flag/pr-01a.md, and the filled contract is
+.structured-coding/plans/order-flag/pr-01a-contract.md.
+Use structured-coding: read its SKILL.md entrypoint, then the complete
+resources its execute row lists, including Implementation Working Rules and
+TEST / CI / GATE in full. Reconcile actual state, and begin.
Continue autonomously to READY FOR OPERATOR REVIEW under the contract.
Do not merge.
```
diff --git a/structured-coding/README.zh-CN.md b/structured-coding/README.zh-CN.md
index 82ad56f..8441f2f 100644
--- a/structured-coding/README.zh-CN.md
+++ b/structured-coding/README.zh-CN.md
@@ -27,9 +27,11 @@ Codex 的请求开头加 $structured-coding，Claude Code 加 /structured-coding
### 1. 规划 feature
```text
-Use the structured-coding workflow for this feature. First agree with me on
-requirements, module-level direction, and overall step boundaries; then detail
-the current step. Work on planning for now.
+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.
+First agree with me on requirements, module-level direction, and overall
+step boundaries; then detail the current step. Work on planning for now.
Requirements: ...
```
@@ -39,9 +41,11 @@ Agent 会问它推断不出来的东西，检查你真实的代码，然后写
```text
Read the overall and step documents, audit the current code, and prepare the
-PR 01a design doc and filled execution contract. Follow the original PR
-requirements for the commit checklist. Separate implementation, validation,
-and review, and prepare the design for my approval.
+PR 01a design doc and filled execution contract. Use structured-coding:
+start from its SKILL.md entrypoint and load what the PR design row lists.
+Follow the original PR requirements for the commit checklist. Separate
+implementation, validation, and review, and prepare the design for my
+approval.
```
你会拿到一份 PR 设计：经过代码审计的 commit 计划，加一份填好的执行 contract。读它、要求修改，等它确实描述了你想要的东西再批准。
@@ -49,10 +53,12 @@ and review, and prepare the design for my approval.
### 3. 批准后，用新 session 执行
```text
-Execute PR 01a. The approved DESIGN FROZEN document is docs/plan/pr-01a.md,
-and the filled contract is docs/plan/pr-01a-contract.md.
-Use structured-coding. Read Implementation Working Rules and TEST / CI / GATE
-in full, reconcile actual state, and begin.
+Execute PR 01a. The approved DESIGN FROZEN document is
+.structured-coding/plans/order-flag/pr-01a.md, and the filled contract is
+.structured-coding/plans/order-flag/pr-01a-contract.md.
+Use structured-coding: read its SKILL.md entrypoint, then the complete
+resources its execute row lists, including Implementation Working Rules and
+TEST / CI / GATE in full. Reconcile actual state, and begin.
Continue autonomously to READY FOR OPERATOR REVIEW under the contract.
Do not merge.
```
@@ -116,9 +122,11 @@ Specification 是写下来的要求，不是一个盯着所有操作的程序。
拿这个例子来说，你要说明：输入是 [c, a, b]，启用字母排序后应按 [a, b, c] 读取；不开这个选项，旧行为必须不变。也要说清楚这次不做什么，比如这个 PR 先不改 resume 机制。Agent 应该先检查 repo，把未确定的产品问题问清楚，再提出整体方向。你说的是做计划，它就不能直接开始 implementation。
```text
-Use the structured-coding workflow for this feature. First agree with me on
-requirements, module-level direction, and overall step boundaries; then detail
-the current step. Work on planning for now.
+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.
+First agree with me on requirements, module-level direction, and overall
+step boundaries; then detail the current step. Work on planning for now.
Requirements: ...
```
@@ -134,9 +142,11 @@ Overall plan 讲整个功能和主要步骤，step plan 讲几个 PR 怎么配
```text
Read the overall and step documents, audit the current code, and prepare the
-PR 01a design doc and filled execution contract. Follow the original PR
-requirements for the commit checklist. Separate implementation, validation,
-and review, and prepare the design for my approval.
+PR 01a design doc and filled execution contract. Use structured-coding:
+start from its SKILL.md entrypoint and load what the PR design row lists.
+Follow the original PR requirements for the commit checklist. Separate
+implementation, validation, and review, and prepare the design for my
+approval.
```
**进入下一步前，确认这件事**
@@ -159,13 +169,15 @@ Design 符合你的意思后，明确批准这份具体的 design 和 contract
在同一个目标项目里，真正新开一个会话，不是给 planning 会话改个名字。重新调用 skill，把带真实路径的 kickoff 发过去。新的 agent 不需要整段 planning 聊天记录，但需要已经保存的约定，以及能确认当前状态的源文件。
-修改前，agent 必须读已批准的 design、填好的 contract，以及完整的 execution 和 test rules。它还要检查 branch、HEAD、已有改动、前置 PR 是否 merge，以及相关 job 是否仍在运行。无关改动要保留。如果你明确启用了某个 preset，它还要读对应说明，把当前 session 绑定到这个 PR。安装了 hook，不等于已经替它选好了当前 PR。
+修改前，agent 必须先重读 skill entrypoint 和它的 execute 行，再读已批准的 design、填好的 contract，以及完整的 execution 和 test rules。它还要检查 branch、HEAD、已有改动、前置 PR 是否 merge，以及相关 job 是否仍在运行。无关改动要保留。如果你明确启用了某个 preset，它还要读对应说明，把当前 session 绑定到这个 PR。安装了 hook，不等于已经替它选好了当前 PR。
```text
-Execute PR 01a. The approved DESIGN FROZEN document is docs/plan/pr-01a.md,
-and the filled contract is docs/plan/pr-01a-contract.md.
-Use structured-coding. Read Implementation Working Rules and TEST / CI / GATE
-in full, reconcile actual state, and begin.
+Execute PR 01a. The approved DESIGN FROZEN document is
+.structured-coding/plans/order-flag/pr-01a.md, and the filled contract is
+.structured-coding/plans/order-flag/pr-01a-contract.md.
+Use structured-coding: read its SKILL.md entrypoint, then the complete
+resources its execute row lists, including Implementation Working Rules and
+TEST / CI / GATE in full. Reconcile actual state, and begin.
Continue autonomously to READY FOR OPERATOR REVIEW under the contract.
Do not merge.
```
diff --git a/structured-coding/SKILL.md b/structured-coding/SKILL.md
index a2bf0ec..2ca2070 100644
--- a/structured-coding/SKILL.md
+++ b/structured-coding/SKILL.md
@@ -24,6 +24,8 @@ Read [agent-workflow.md](references/agent-workflow.md) and [adaptation.md](refer
| Project standards | [standards contract](references/standards.md), only when `.structured-coding/standards.md` exists in the target project | Apply the project's declared review conventions and check ownership; the helper reports, it does not enforce |
| Hook design / integration | [hook contract](references/hook-contract.md); [platform notes](references/platforms.md); [continuity preset](references/continuity.md) and [checkpoints preset](references/checkpoints.md), only when explicitly enabled | Read only explicitly enabled preset interfaces; further integration only when requested |
+This table is the required resource list for the phase; do not assemble one from the prompt names a request happens to mention. Before stating that work does or does not comply with this workflow, read the rule being cited, in this session: the routing rules live here and in [agent-workflow.md](references/agent-workflow.md), not in the long prompts, and recalling them from an earlier session is not evidence.
+
The original long prompts are deliberately preserved. Do not replace them with this entrypoint or a summary during execution. Resolve relative resource links against this skill directory, not the target repository.
## Essential operating rules
@@ -32,7 +34,7 @@ The original long prompts are deliberately preserved. Do not replace them with t
2. Plan overall → step → PR. If a step needs one PR, expand the step document in place into the PR design; keep one authority for that work.
3. Every PR supplies a meaningful integration checkpoint. Each planned commit tracks implementation, deterministic validation, and LLM logic review separately with `[ ]` / `[x]` and evidence.
4. Require a user-approved `DESIGN FROZEN` header and an authorized implementation contract before starting implementation. Freeze scope, invariants, and acceptance; keep progress, evidence, and bounded discoveries live.
-5. Start each new PR in a fresh implementation session. Resume after compaction as the same PR. Recover repository/process truth and re-read the current PR design and execution rules before editing.
+5. Start each new PR in a fresh implementation session. Resume after compaction as the same PR. Recover repository/process truth and re-read the current PR design and execution rules before editing. A session that is new, replacing another, or a delegated agent re-reads this entrypoint and its current phase row first; that is a session boundary, not something to repeat every turn.
6. Within the approved contract, investigate, implement, run sufficient validation, review, update the ledger, and create semantic commits autonomously. Commit inspection is a checkpoint, not a request for approval.
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.
diff --git a/structured-coding/references/continuity.md b/structured-coding/references/continuity.md
index 23f7bc4..4aa016d 100644
--- a/structured-coding/references/continuity.md
+++ b/structured-coding/references/continuity.md
@@ -117,6 +117,7 @@ The hook does not query GitHub to discover that a PR was closed or merged.
| Manual `PreCompact` | Compare current state to the session's explicit checkpoint; deny stale/missing checkpoints or unreadable bound state, with a repair message | Tests mechanical freshness, not handoff quality |
| Automatic `PreCompact` | Attempt a bounded mechanical snapshot; record `recovery_required` and warnings; return without blocking compact even on failure | Disk/host failures can prevent saving; stderr warns, and resume always requests recovery |
| `SessionStart` | For a bound session, inject its current PR and absolute document/rule paths with full-read and actual-state reconciliation instructions | No full prompt replay, mutation interception, process inspection, or claim that recovery was completed |
+| `SessionStart`, either state | Name the installed `SKILL.md` by absolute path, so a session that did not plan this work is told where the phase resource list is | Names the entrypoint; does not deliver it, and an absent entrypoint is omitted rather than guessed. Reaching a session is not reading |
| Unbound or explicitly closed session | Unbound/closed compact proceeds; session start explains the absent/closed binding | Does not impose this workflow on unrelated work |
Codex manual denial uses `continue: false` with `stopReason`. Claude Code uses
diff --git a/structured-coding/scripts/continuity.py b/structured-coding/scripts/continuity.py
index 4c7247b..0e1af90 100644
--- a/structured-coding/scripts/continuity.py
+++ b/structured-coding/scripts/continuity.py
@@ -235,6 +235,19 @@ def active_record(repository, directory, host, session):
return record
+def entrypoint():
+ """The installed entrypoint, absolute, or None when it is absent or unreadable.
+
+ Named rather than replayed: a session-start message cannot deliver the
+ routing table, only say where it is.
+ """
+ path = Path(__file__).resolve().parents[1] / "SKILL.md"
+ try:
+ return path if path.is_file() else None
+ except OSError:
+ return None
+
+
def context(message):
return {
"hookSpecificOutput": {
@@ -296,9 +309,18 @@ def event(project, host, mode, payload):
invocation = f"{helper} activate --host {host} --project {shlex.quote(str(repository.root))} --session {shlex.quote(session)}"
if not active_path.exists():
if mode == "session-start":
+ routing = entrypoint()
return context(
"Structured Coding continuity is installed, but no PR is bound to this session. "
- "Ordinary work is unaffected. If executing a Structured Coding PR, read the installed "
+ "Ordinary work is unaffected. "
+ + (
+ f"If this session does Structured Coding work of any kind, read {routing} first and then "
+ "the complete resources its table lists for the current phase; that table is the required "
+ "list, and this message does not replay it. "
+ if routing
+ else ""
+ )
+ + "If executing a Structured Coding PR, read the installed "
"references/continuity.md and explicitly bind its current design, contract, and handoff. "
f"Start with: {invocation} --pr PR_ID --design PATH --contract PATH --handoff PATH. "
"Do not infer authorization or reuse another session's PR."
@@ -362,12 +384,19 @@ def event(project, host, mode, payload):
str(skill / "prompts" / name)
for name in ("implementation-working-rules.md", "test-ci-gate-rules.md")
]
+ routing = entrypoint()
+ # First in the whole list, because a recovering session is exactly the case
+ # that reads the documents and prompts and skips the routing rules neither
+ # of them contains.
+ lead = [str(routing)] if routing else []
return context(
f"Structured Coding: RECOVERY REQUIRED for PR {active['pr']}. {warning}"
f"Worktree: {repository.root}; bound branch: {active['branch']}; current HEAD: {identity['head']}. "
"Read these files IN FULL before further implementation (this message does not replay their contents): "
- + json.dumps(documents + rules, ensure_ascii=True)
- + ". Reconcile actual Git state, handoff checkpoint/next actions, and known jobs/logs; "
+ + json.dumps(lead + documents + rules, ensure_ascii=True)
+ + ". The entrypoint, when present, is the first of them: re-read it and its current phase row, then "
+ "whatever that row requires and this session has not read. "
+ "Reconcile actual Git state, handoff checkpoint/next actions, and known jobs/logs; "
"reuse existing jobs. Confirm the PR is still active; remote closure/merge is not checked by this hook. "
"Do not invent decisions, test results, or approval. Follow the filled contract and stopping conditions. "
"This preset does not enforce full reads or prevent mutations/merges. After reconciliation and "
diff --git a/translations.json b/translations.json
index 28d269f..92a7423 100644
--- a/translations.json
+++ b/translations.json
@@ -3,27 +3,27 @@
"presentation_source_pair": {
"english": "docs/content.en.json",
"chinese": "docs/content.zh-CN.json",
- "english_sha256": "134e958f2c914435b757584b16169141427c2a9ad1f4091e024c6c19d5927451",
- "chinese_sha256": "a8eee06738196a2000f7016cd822cb7c172c0ccade49b5a9011d25f99714e526"
+ "english_sha256": "7a8d58ad68e56ad6f3ef10aac60df01dca2256fd237474544ceb313f7bb09440",
+ "chinese_sha256": "9a66f3193d5358db7c1fed532eed3ac0e05203e7ce46a7f4c61d6dbf93adbcfa"
},
"pairs": [
{
"english": "README.md",
"chinese": "README.zh-CN.md",
- "english_sha256": "7e4fcb667638ec5d3300db5ae269d9f4b2c2eab6544c9c73c2d59cc4eeb1cb39",
- "chinese_sha256": "d54503afa062fcb488bb55bdbc1af463455a2d44d7baf62424878cb5a55483c4"
+ "english_sha256": "1d07bec1eaec7cadb56aadb241d16c19310dd2fe6789108e3add477fb0679fbb",
+ "chinese_sha256": "54ec6dde48b5d04e404b54de0221ae3e07862f913534e45355bb35beb46d5cb8"
},
{
"english": "TUTORIAL.md",
"chinese": "TUTORIAL.zh-CN.md",
- "english_sha256": "24e158e97d983e13b077024762d18152a4a99e0cfa6c20f589e5647fd9bf3b2f",
- "chinese_sha256": "b9cc1510f76878a9dd119842e87c7b69f046f071b1a6fbe19c1cd869a058c04c"
+ "english_sha256": "22995baecd9d47a314cea80150805ee7cac6ba2d46e5db6a8daa2ca1b643a576",
+ "chinese_sha256": "3edb560f63ce536d8681f688234540552fabc4bfb50e3268bdb15f75a5b6261b"
},
{
"english": "structured-coding/README.md",
"chinese": "structured-coding/README.zh-CN.md",
- "english_sha256": "1cd4b7df7a6dfbfe32c0f694d7a07fa9cc2c98e9a2bb210d51838fbdeec09d8e",
- "chinese_sha256": "7f7ccbeaef3aa966b4a7b7cf6de4590b94554dc906a7b48dbcad618cc5e14dac"
+ "english_sha256": "37d48efbef1a3c8fb1d0d74608aae14e7c7e24c9651bd7dcc302b2579052a6c9",
+ "chinese_sha256": "64f4d8d32c41d0ee55407cdc90ae90e8b5e4c762a1d920c3449bc94de5c5fc67"
},
{
"english": "structured-coding/references/agent-workflow.md",
@@ -45,7 +45,7 @@
}
],
"specification_sha256": {
- "structured-coding/SKILL.md": "bbfa75b6f56f04754799b5c7a0199008663ba4346630a483340182544fa7af37",
+ "structured-coding/SKILL.md": "bea7c82214ef6332ba587385b0d76a71c820e05f8d9a95796ba6d16efb40f0e0",
"structured-coding/prompts/implementation-working-rules.md": "7caa1d829fcdb0741b3b621918d6058352adcacf6c8bfee5267e37d2850debcf",
"structured-coding/prompts/pr-design-requirements.md": "dc5d654ee5e4e2d7a7558726823eb3452167f551d7841403ac8a98c862972baa",
"structured-coding/prompts/test-ci-gate-rules.md": "ace549262e04880577248189f8ae460f18c13a6b2ecf6280d600566c2cd003e1",