cordon-starter

The scaffold every Severino repo begins from. Lean enough to become any kind of project, but it ships with the standing cornerstones already wired: the Cordon emit-once command-surface contract, a green-gating CI, automated releases (release-please), the branch→PR→review→merge workflow, and one command that applies branch protection + repo security.

It is not a generator. It's a small, opinionated tree you copy and prune — and the parts that would otherwise drift (the contract JSON, the describe.sh machinery) are sourced from your toolchain, not vendored.

Start a new repo from it

Quickest path: click Use this template on GitHub for a fresh repo with clean history. Or copy the tree locally and prune:

No manual cordon setup needed — scripts/check.sh resolves the engine from a local cordon checkout, the repo's pinned cordon-spec devDependency, or the published npm package via npx — in that order. A fresh machine runs the gate with no download step and nothing written to ~/.zshrc.

cp -R "$PROJECTS_HOME/cordon-starter" "$PROJECTS_HOME/<repo>"
cd "$PROJECTS_HOME/<repo>"
rm -rf .git && git init -b main          # fresh history
scripts/setup-hooks.sh                    # local guardrails + commit template — works offline

# make it yours — keep ONE emitter track, prune the other
#   bash repo:  mv bin/example-tool bin/<repo>   ; rm bin/example-node contract/example-node.json
#   node repo:  mv bin/example-node bin/<repo>   ; rm bin/example-tool contract/example-tool.json
mv bin/example-tool bin/<repo>           # then rewrite its describe_spec / typed spec
$EDITOR AGENTS.md README.md              # delete what you don't need
rm -f contract/example-*.json            # drop the unused track's golden(s)

bin/<repo> --describe > contract/<repo>.json   # generate the golden contract (either track)
scripts/check.sh                          # shellcheck + drift + conformance

git add -A && git commit -m "Initial commit"
gh repo create joeseverino/<repo> --private --source=. --push
scripts/setup-governance.sh               # protect main + security settings

From here on: git fetch origin && git checkout -b <feature> origin/main, never commit to main. See AGENTS.md.

What's in the box

path	what it is
AGENTS.md (+ CLAUDE.md symlink)	the cornerstone playbook — read first
bin/example-tool	the bash track: a runnable Cordon-emitting tool; copy its describe_spec() (declare-a-DSL)
bin/example-node + package.json	the Node track: a one-file emitter that derives the surface from package.json scripts (via cordon's emitters/node) and declares only each command's blast radius; copy both for a Node/TS repo
contract/example-tool.json, contract/example-node.json	the committed golden contracts (emitted, never hand-edited)
.github/workflows/ci.yml	three lines calling cordon's reusable gate — the required cordon / gate check
.github/workflows/release.yml	three lines calling cordon's reusable release — the cordon / release check; cuts versions + GitHub Releases via release-please
version.txt	the version source for the default simple release-type; bump-managed by release-please
scripts/try.sh	smoke test — run it to watch the contract work end to end
scripts/check.sh	the gate — the identical wrapper every cordon repo ships; runs cordon's checks engine over cordon.checks.json. Pre-push, CI, and you all run it (--json for AI)
scripts/_lib.sh	in-repo presentation (palette + banner/step/run); sourced by try.sh, no external dep
scripts/gen-readme.mjs	renders the README CLI reference from contract/*.json — the README is a render of the contract (zero deps, drift-gated)
.githooks/ + scripts/setup-hooks.sh	local guardrails: pre-commit blocks main, commit-msg blocks AI attribution, pre-push runs the gate, and it wires commit.template
scripts/setup-governance.sh	GitHub-side branch protection (required cordon / gate, enforce_admins) + security via gh api
.github/dependabot.yml	keeps pinned Actions current; uncomment your language ecosystem (pip/npm)
.editorconfig	shared editor defaults (LF, final newline, 4-space / 2 for web)
.gitmessage	commit template — solo-authored guidance (wired by setup-hooks.sh)
docs/CORNERSTONES.md	the full checklist, one line per standard
optional/base.css	design-token seed from jseverino.com — opt in for frontends

The contract, in one breath

A tool declares its surface once in describe_spec(). The human -h text and the machine --describe JSON are two pure renders of that one declaration, so they can't disagree. Every command carries an effect (read < local_write < vault_write < remote_write < deploy) so an agent can risk-gate before it acts. The canonical emitter lives at "$TOOLS_HOME/lib/describe.sh" — this starter sources it, never copies it.

^{Diagram source: cordon / docs/diagrams/emit-once.mmd, pre-rendered with diagram.}

Full standard: jseverino.com/schemas/cordon-v4.json and the cordon spec repo.

Command reference (generated)

The block below is rendered from contract/*.json by scripts/gen-readme.mjs — the README's command surface is a render of the contract, not a hand-kept copy. The gate runs gen-readme.mjs --check, so editing it by hand (or letting it drift from the tool) fails CI. This is the "render many" idea applied to the README itself; every repo derived from the starter inherits it.

^{"Render many" made concrete: one Cordon contract rendered as a generated README command reference — exactly what scripts/gen-readme.mjs produces below. Source: cordon / docs/images/diagram-generated-readme.png.}

example-tool

effect: read

Replace me: one line on what this tool does.

Options

flag	value	required	help
-n, --dry-run	no	no	Show what would happen; write nothing

Arguments

arg	required	help
name	yes	The thing to act on

Examples

• example-tool widget — acts on 'widget'
• example-tool -n widget — dry run

---

example-node

effect: read

Replace me: one line on what this repo does.

Commands

command	effect	summary
build	local_write
deploy	deploy

License

MIT © Joe Severino