A project baseline
Scaffold
The baseline I start projects from — repo shape, tooling, package boundaries, how coding agents fit in, and what has to be true before launch. Written for my own repos, and open for anyone to read.
Principles
the reasoning under the defaultsDecide once, reuse everywhere
Settle toolchain basics at the baseline instead of re-deciding them in every repo.
The lightest shape that fits
Start from the smallest archetype that fits; add machinery only when a repo earns it.
Correctness over cleverness
Prefer the plain, correct implementation to the clever one.
Docs are the source of truth
The Project Docs are canonical; every assistant gets a generated wrapper, not a fork.
Deviations are recorded, not smuggled
A repo may diverge from the baseline when justified — and writes down why.
Agents are assets, not entropy
A short AGENTS.md that changes behavior without becoming documentation sludge.
Hooks stop breakage, not run CI
If hooks get slow enough that developers bypass them, the hooks are wrong.
Docs describe the present
Docs describe the current system, not the migration path taken to reach it.
The docs
Thirteen chapters, grouped by the question they answer.
Start here
Install the baseline, pick a repo shape, and settle the versions up front.
Project shape
How a repo is organized before implementation details start to sprawl.
Operations
Setup, dependency choice, deployment, and launch checks kept consistent.
Agent workflow
How the baseline guides coding agents without turning every repo into a copy of it.
For agents
The docs double as an installable Agent Skill and machine-readable surfaces. Install the skill:
npx skills@latest add howells/scaffold