| name | coaligned-setup |
| description | Bootstrap the Co-Aligned instruction architecture in a repository. Use when a repo has no layered agent instructions yet, when adopting the Co-Aligned standard, or when wiring the `coaligned` checks into the repository so instruction layers, jobs, and invariants stay enforced.
|
Set Up the Co-Aligned Architecture
Stand up the
Co-Aligned
instruction architecture in a repository: the root identity and jobs files, the
invariant directory, and the coaligned checks that keep them honest.
Run this once per repository. For ongoing work use the sibling skills:
coaligned-layer for instruction layers,
coaligned-jtbd for jobs,
coaligned-invariant for custom rules, and
coaligned-audit for the maintenance loop.
When to Use
- A repository has no layered agent instructions yet
- Adopting the Co-Aligned standard in an existing repository
- Wiring the
coaligned checks into a repository's check command and CI
Checklists
<read_do_checklist goal="Internalize the architecture before scaffolding">
</read_do_checklist>
<do_confirm_checklist goal="Verify the architecture stands before committing">
</do_confirm_checklist>
Process
Step 1: Decide the jobs structure
The jobs layer (L2) has two shapes. Pick by how the repo is packaged, not by
preference.
- Single static
JTBD.md — the repo is one unit (one deployable, one
library, a monolith). Author Big Hire entries directly in JTBD.md. No
generation.
- Generated
.jobs blocks — the repo is genuinely many packages, each
with its own package.json. Each package declares jobs in its manifest;
coaligned jtbd --fix generates the catalog and job blocks into the
README and root JTBD.md.
When in doubt, choose the static file — fewer moving parts. See
references/structure-decision.md.
Step 2: Create the root layers (L1, L2)
Create the auto-loaded identity and on-demand standards files. Keep each within
its cap (L1 ≤ 192 lines; L2 ≤ 320 lines).
-
CLAUDE.md (L1) — project identity: what the repo is, who it serves,
where things live, and how to route to skills. Orientation, not procedure.
The L1 property is that it surfaces the discovery conventions, so include a
brief Jobs and Checklists section naming where jobs live and how jobs and
checklists are found with rg. Copy the starter and adapt its first line to
the jobs shape from Step 1:
cat .claude/skills/coaligned-setup/assets/jobs-and-checklists.md
Keep the tag names verbatim — they are the discovery contract contributors
and the coaligned checks rely on.
-
CONTRIBUTING.md (L2) — contribution standards: the architectural
invariants, the quality commands, security policy, and the universal
checklists.
-
JTBD.md (L2) — the jobs, per Step 1. Use coaligned-jtbd to author
entries to spec.
Do not restate one file in another. CLAUDE.md orients; CONTRIBUTING.md governs.
Step 3: Create the invariant directory
Create .coaligned/invariants/ and seed it with the starter rule. The
directory is where the repo's own declarative checks live; coaligned invariants discovers every *.rules.mjs under it, so an empty directory
enforces nothing and the wired check has nothing to prove.
Copy the bundled starter rule verbatim so every new repo begins with one live
invariant:
cp .claude/skills/coaligned-setup/assets/no-conflict-markers.rules.mjs \
.coaligned/invariants/
no-conflict-markers fails any tracked
file that carries a leftover git merge-conflict marker. It is generic by
design — language-agnostic, zero-configuration, and firing only on an
unambiguous defect — so it holds in any consuming repository from the first
commit. It also proves the pipeline end to end: the directory is discovered, a
module loads, and a planted marker fails the check.
Add repo-specific rules on top with
coaligned-invariant; keep or remove the
starter once the repo has invariants of its own.
Point CONTRIBUTING.md at this layer so contributors can find and extend it:
where the rules live (.coaligned/invariants/*.rules.mjs), the coaligned invariants command that runs them, and
coaligned-invariant for authoring a rule.
This is the invariant tooling — distinct from the architectural
non-negotiables CONTRIBUTING.md already states in prose.
Step 4: Wire the checks into the repository
Wire the check into the repository's check command and CI so every layer, job,
and invariant is enforced before merge. The CLI exposes four entry points:
coaligned # instructions + jtbd (and invariants if present)
coaligned instructions # layer length and checklist caps only
coaligned jtbd --fix # regenerate stale catalog and job blocks
coaligned invariants # the repo's own rule modules
Invoke it through an entry point the run environment can resolve. A clean CI
runner has nothing on PATH and no workspace to resolve a bare coaligned
against, so wire the registry-resolvable form — the published CLI package run
through the repository's package manager — and record that concrete command in
CONTRIBUTING.md. Use the same command in the lint/check task and the CI job;
never one that only resolves on a contributor's pre-provisioned machine.
Step 5: Verify the bootstrap
Verify the wired check the way CI runs it, from a clean dependency resolution. A
coaligned already on your PATH masks an invocation that cannot resolve on a
fresh runner — so confirm the repository's check command passes on a clean
checkout, not just in your shell. A clean run means the layers fit their caps
and the jobs validate; fix any finding before committing, routing by subcommand
the same way coaligned-audit does.
Documentation
