Co-Aligned Instruction Architecture
Coding agents that stay aligned under load
One instruction architecture for humans and agents. Eight layers, each with a single job, each one you can audit on its own.
Instructions sprawl, and alignment breaks under load.
Prompts pile up. Instruction chains grow unauditable. The more expert the contributor, the more readily they skip the procedure — because they think they don't need it. Co-Aligned takes the opposite path: one layered architecture where every layer owns a single job, and a defect always traces to exactly one of them.
Eight layers. Most general to most specific.
Each layer loads at the right moment and owns one concern. Auto-loaded layers stay budgeted so context never bloats; on-demand layers disclose only when the work calls for them.
Harness mechanics: turns, tool calls, the completion signal. Nothing about your project.
Project identity — what it is, who it serves, and where to find its jobs and checklists.
Contribution standards and the jobs each persona hires the work to do.
One persona — voice, skill routing, and scope constraints. Boundaries, not steps.
Cross-cutting protocols shared across agents: memory, coordination, approval.
The complete, imperative steps for one domain of work — no tribal knowledge required.
The data a procedure consults: templates, worked examples, lookup tables.
Binary verification at a pause point. No explanation — just confirmation.
What agents align to, and how alignment holds.
Two well-publicized ideas answer the two halves of the problem — and together they explain why the layers are shaped the way they are.
What agents align to. Every layer traces to the progress a persona seeks in a specific circumstance — not to a feature list.
How alignment holds under load. Structured instructions keep existing knowledge consistently applied — by humans and agents alike.
Two gates. One at entry, one at exit.
Checklists never teach — they confirm; if an item needs
explaining, the procedure above it is incomplete. Each gate is
wrapped in a semantic <read_do_checklist> or
<do_confirm_checklist> tag, so every pause
point in the repository is one rg search away — no
map required.
Read each item, then do it. Loads constraints into memory before the first line of work, when missing one sends everything in the wrong direction.
rg '<read_do_checklist'
Do from memory, then pause and confirm. Verifies nothing was missed before a commit, merge, or release — independent checks, no interruption mid-flow.
rg '<do_confirm_checklist'
Adopt it in three lines.
Install the skill pack. Tell Claude to set it up.
Then wire npx coaligned into your checks, so every
layer keeps its job. Read the full standard in
COALIGNED.md.