Chinese mirror · Visual HTML guide · Step-by-step tutorial
Agree on the change. Let the agent build it. Bring the result back into the plan.
When this is worth it, and when it is not
This is built for sustained work on a large codebase. It earns its overhead when a change spans several PRs or sessions, when the code is big enough that an agent must audit before it edits, and when someone has to pick the work up later. For a typo, a one-file bug fix, or a throwaway prototype it is overkill: the planning documents will cost more than the change itself. Use your agent directly for those. Plans, tests, and LLM reviews can still be wrong; what this workflow adds is that their assumptions and evidence are written down where you can inspect them.
Quick start · What using it looks like · Follow one PR, then plan the next. · Going further
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.
git clone --depth 1 https://github.com/yuema137/structured-coding.gitKeep 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.
Codex:
./structured-coding/scripts/install codex --project /path/to/your-projectClaude Code:
./structured-coding/scripts/install claude-code --project /path/to/your-projectPrefix 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.
Three messages carry one feature from an idea to a reviewed PR. You approve twice; the agent does the work in between.
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: ...
The agent asks what it cannot infer, inspects your actual code, and writes the overall plan with step boundaries. Nothing is implemented yet.
Read the overall and step documents, audit the current code, and prepare the
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.
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.
A fresh session implements, validates, reviews its own logic, commits, and stops at a review handoff. You read the diff and decide whether to merge.
That is the whole loop. After a confirmed merge the agent updates the plans with what it learned, and the next PR starts from there.
A plan describes what you intend to build. It does not, on its own, tell an agent how to execute, what counts as evidence, when to ask you, or how to resume after losing context. This skill connects those decisions into one repeatable workflow.
- Plan what is knowable: You and the agent agree on the overall direction first. The agent inspects real code before detailing the next PR.
- Keep the work recoverable: The agent saves discoveries and evidence in the PR design so another session can resume without relying only on chat memory.
- Give autonomy a boundary: The agent fixes ordinary bugs and creates commits. You decide changes to the agreement and authorize merge.
Follow 01 → 06. After a confirmed merge, use the findings to design the next PR.
The agent fixes ordinary bugs; you decide changes to the agreement.
You do not need to approve every commit. You do need to own the decisions that change the agreement.
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. The contract records which endpoints you authorized — commit, push, opening the PR, CI repair — and merge is never one of them. The agent may not quietly narrow that list either: a stopping point you did not ask for is a question for you, not a cautious default it can adopt on your behalf.
A material scope change or an action outside existing authorization comes back to you with evidence and a proposal.
| Resource | What it covers |
|---|---|
| Step-by-step tutorial | The same loop on a real feature, one message at a time. |
| Workflow reference | What the agent does in each phase, and where its authority stops. |
| PR specification | What a PR design must contain before it can be approved. |
| Optional hooks | Installation, coverage, and the limits of what a hook can enforce. |
| Behavior contract | The complete target behavior, including the parts not yet shipped. |
A project can state, once, what is true of its whole codebase, so you do not repeat it in every planning conversation. Copy the template to .structured-coding/standards.md and edit one block. This file is optional: without it the defaults below apply and nothing changes. Requirements specific to a single PR stay in that PR's conversation, so this file remains a stable repository asset.
| What you set | Where | Default |
|---|---|---|
| Conventions an LLM judges | review.conventions | none; you write plain sentences |
| When those conventions are raised | review.trigger | at PR review readiness |
| Commands with a pass or fail result | checks.tools | ruff and pyright on changed files; pytest listed and off |
| When those checks apply | checks.trigger | at PR review readiness |
| Your own additions | .structured-coding/standards.local.md | may add and tighten only, never relax the team's |
Scope is set per tool because the right answer differs by tool: changed files suit ruff and pyright, and mislead for pytest, whose covering tests usually sit in files the change never touched. Tools are grouped by whether they execute your code, so pytest and mypy are recognized and still need a deliberate approval before anything runs them. Running the checks is an explicit command: each one comes back as PASS, FAIL, INCONCLUSIVE or NOT RUN, and a tool that is not installed is INCONCLUSIVE rather than a pass, because it examined nothing. Nothing runs automatically yet; there is no hook, so no commit and no merge is blocked.
Open the part relevant to your current question. Use the resource links above for the complete specifications.
Here is what the package provides.
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.
| Resource | What it provides |
|---|---|
| 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. |
| PR specification | 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. |
| Execution templates | 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. |
| Validation rules | 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. |
| Optional hook presets | The continuity preset helps preserve and recover work around compact. The checkpoints preset gives commit and review reminders. Neither supplies a merge guard. |
| Two platform packages | 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. |
What do you, the specification, the agent, and the hooks each do?
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.
How many conversations do you need?
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.
What documents does the agent maintain?
| Overall | It records the overall goal, requirements, and main steps so each PR has a clear purpose. |
| Step | It explains which PRs complete this step, their dependencies, and how to observe their integration. |
| PR design | It records audited code and the commit plan, then keeps decisions, progress, and evidence current during implementation. |
| Execution contract | It records this PR's approved scope, permitted actions, budget, and stopping conditions. |
| Handoff | It identifies the current PR, branch and HEAD, running jobs, logs, and the exact next action after recovery. |
DESIGN FROZEN protects the requirements you approved, not the entire document. The agent still records discoveries and progress. Implementation, validation, and review stay separate; each item is checked only when that work has actually been completed. If one step needs one PR, expand the step document instead of keeping two copies.
What happens at compact or resume?
Compact is the host's process of shortening conversation history to free context; it does not create a new PR. A new PR starts in a fresh implementation session, while compact or resume continues the current PR. The optional continuity preset checks recorded mechanical freshness, attempts snapshots, and supplies recovery instructions. The agent still has to keep the design and handoff accurate and actually reconcile state after recovery.
On resume, reload the current design, filled contract, and full execution rules; check the repo and existing jobs before editing. A snapshot cannot invent decisions or test results. Automatic compact must not get stuck waiting for a perfect handoff.
Optional hooks: installation, coverage, and limits
OPTIONAL CONTINUITY + CHECKPOINTS + STANDARDS · NO MERGE GUARD
Choose continuity for compact recovery, checkpoints for commit/review reminders, standards to run your declared checks after a commit, or any combination. Both are off by default. Checkpoints advises; it does not enforce commits or certify readiness. Protocol tests do not establish native event delivery or model compliance. The agent does not dynamically register its own hooks.
./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints --dry-run
./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints
./structured-coding/scripts/install codex --project /path/to/project --hooks continuity checkpoints
./structured-coding/scripts/install codex --project /path/to/project --check-hooks
./structured-coding/scripts/install codex --project /path/to/project --upgrade-registration
./structured-coding/scripts/install codex --project /path/to/project --remove-hooks checkpoints
./structured-coding/scripts/install codex --project /path/to/project --remove-hooksRun these commands from the same parent directory used for the basic installation. Replace /path/to/project with the target project's exact Git root; use claude-code instead of codex for Claude Code. Preview with --dry-run, then run the installation you chose; this list is a set of alternatives, not a sequence you must run in full. Installation adds selected presets, and removing one leaves the other usable. Bare --remove-hooks removes all hooks owned by this installer. Restart the host and inspect registration and trust in /hooks; the installer does not grant trust. Registered commands contain no path specific to your machine, so a registration committed to a shared settings file also works for your teammates, and each of them still reviews and trusts the hooks on their own machine. A registration made by an older release keeps its absolute paths and stays usable; --upgrade-registration rewrites it, which changes every command and so requires trusting the hooks again. The agent must still bind the current session, inspect staged changes before commit, and explicitly prepare its review handoff. Reminders cannot turn pending, inconclusive, or unrun checks into passes. Existing settings, skill files, and session data are preserved.
Continuity preset interface → · Checkpoints preset interface →| Function | Candidate event | Intended behavior | Shipped support |
|---|---|---|---|
| H1 · Before implementation | PreToolUse | Check approved design, contract, repo state, and recovery. Deny dependent mutations when they do not match; still allow audit/design preparation. | Not implemented |
| H2 · Before commit | PreToolUse | Check or surface diff inspection, ledger, evidence, and deviations. Repair and retry autonomously; no per-commit human gate. | Checkpoints: explicit preparation and advice for direct git commit via Bash; no enforcement |
| H3 · Before merge | PreToolUse + merge-route coverage | Require trusted explicit approval for the exact PR, target branch, and candidate HEAD, plus readiness and CI/Gate evidence. Cover CLI, API, auto-merge, and direct target-branch bypasses. | Not implemented |
| H4 · Manual compact | PreCompact: manual | Block a stale handoff until synchronized, then allow compact. | Continuity: mechanical checkpoint freshness only |
| H5 · Automatic compact | PreCompact: auto | Allow compact; save a mechanical snapshot when needed. Preserve failures as warnings and require recovery. | Continuity: bounded snapshot attempt; never intentionally blocks automatic compact |
| H6 · Compact/resume | SessionStart + mutation guard | Resolve the current PR dynamically. Reload full rules and reconcile repo/process state before continuing; do not duplicate jobs. | Continuity: session-bound PR and full-read instructions; no mutation guard or proof of recovery |
| H7 · Review readiness | Stop / completion event | Verify real completion conditions, exact-final-HEAD CI, evidence, and handoff. Readiness does not authorize merge. | Checkpoints: explicit intent and at-most-once operator notice; no automatic continuation or evidence verdict |
| H7 · After merge | Observed result / remote-state check | Confirm merge, then request and verify PR → step → overall updates. The agent writes the lessons; the next PR uses a fresh session. | Not implemented |
An event name alone does not guarantee blocking. Adapters must handle each host's protocol, trusted approval source, and tool-coverage gaps. A check after merge cannot prevent it. Read the contract's acceptance scenarios before implementing an adapter.
Example: approval for PR 12 at HEAD A does not authorize merging a later HEAD B. The implementing agent cannot turn its own “approved” field into human authorization.
Hook behavior contract →A skill, a skillset, or a plugin?
Today this is one standalone skill with supporting resources and optional hook presets. A skillset would contain several independently useful skills; a plugin can package those skills and other host integrations. Project installation stays simple. Updates are not managed, and hook registration is explicit and optional; plugin packaging remains an option for future distribution.
Detailed human guide · Step-by-step tutorial · Visual HTML guide
After cloning, open docs/index.html or docs/index.zh-CN.html in a browser. The HTML page contains the same complete tutorial and copyable messages, with the main steps visible rather than hidden in collapsed sections. GitHub's file viewer shows HTML source, not the rendered layout.
English is the authoritative source; Chinese is a synchronized mirror with English technical terms. The human explanation follows DongbeiGPT. Specifications and reusable prompts are in English.