Coast Standards

Engineering rules for software built with AI coding agents, and the checks that enforce
them. Point an agent at this repository, or install it into a project, and the agent
knows how to work: what must stay DRY, where user-facing text lives, which imports are
forbidden, what a review must return, and what a commit or push is refused for.

How this repo came to be

Scroll down if you don't care.... :)

Hi there, I'm Abbey. I am an iOS engineer (Intel/Mastercard) turned psuedo-short-lived system architect (Rivian) turned product manager (Rivian). I'm now teaching product strategy to both technical and non-technical folks, for FREE through my social venture Up Coast Leaders.

This project started in July 2026 when I first started using AI to code. I was a late bloomer because for the previous 18 months I had been building the free product strategy course and the companion workbook and doing it right took time! Because I was late, I didn't START until Fable. On the coding side I had played around a little bit with Replit, and I had plenty of experience using it as a non-technical user for research, projections, and drafting reports, so I knew going into it that it was going to piss me off big time when it broke what to me seem like simple rules.

Y'know...like having one source of truth or not hard-coding things.

Before I even started coding, because I didn't want to be influenced by my experience with the AI, I documented everything that I felt makes a code base a good code base. I spent hours upon hours having a meeting with my Granola transcriber listing out everything I thought was important and how I would design a system of controls. It was kind of a dream come true, FINALLY all coding rules were up to me and no negotiating anything with my team! Muwahahahah!!!

I then had Claude add all OWASP recommendations and after that I had it search the developer communities for the platforms these standards cover in order to surface up platform specific community recommended coding rules and guidelines.

Everything in this repo is written by Claude, so yes the language is sometimes flowery or without purpose but it's AI talking to AI. This repo isn't for you, it's for your AI, so I decided to do an experiment and see if I could be completely hands off the actual code.

So far that experiment has paid off!

Using these coding standards, since Fable was released (2 months ago), I have built:

• 3 iOS apps,
• a learning and course platform,
• a webapp,
• a mac app,
• a feedback system that takes reports from beta testers and fixes them in Claude automatically, and
• this development tool

I do believe that completing a feature most likely takes more tokens now. Often at the end of work the push will be blocked because a rule was not followed so there is rework done. But it is automatic, I don't manage it, and I suspect that in the long run less credits are used because there are less regressions, less bugs, less skipped work. In either case, even if it is still more credits, I am happier with the experience and the speed than I am when I try to use Claude without it.

I assume this can be used with other AI coding systems however I have only used Claude so it hasn't been tested.

Okay let's get into it!

Last updated: 2026-09-09

Engineering rules for software built with AI coding agents, and the checks that enforce
them. Point an agent at this repository, or install it into a project, and the agent
knows how to work: what must stay DRY, where user-facing text lives, which imports are
forbidden, what a review must return, and what a commit or push is refused for.

The rules were extracted from building Coast, a macOS app that runs an
AI software team, and from the projects it builds. Coast is the reference implementation:
it installs this repository into every project it creates, and its own repository is held
by the same checks.

Three parts:

• rules/ — the corpus, with its own index. Numbered files that apply to every project, type files for
  services and pipelines, and one checkable rule document per platform (iOS, macOS,
  Android, React Native, Web, Python). Every rule names the check that holds it.
• enforcement/ — the checks. A standard-library Python scanner with per-platform
  signature tables, a doc-comment check, a verifier that counts how many rules a check
  holds, shipped linter configs, three git hooks, hooks for Claude Code sessions, and
  adopt.py, which installs all of it into any project in one command.
• docs/ — the public documentation for someone installing this into their product,
  in plain words.

📖 Documentation with search: up-coast.github.io/coast-standards/ — the
rules, the guides and the enforcement notes as one searchable site.

Installing this into your own project? Start with the
quickstart — ten minutes, one command to fetch the newest
release, one to install it. The steps further down this page are the same work in
longer form, for someone who wants to see what the installer does before running it.

Source-available, not open source: see License below, and
CONTRIBUTING.md to change a rule or a check.

Layout

How to adopt in a new project

1. Decide the project's type from rules/PROJECT-TYPES.md (app · backend · data/ML ·
   library/CLI) — a project with a frontend and an API is two types, one per part — and
   name it in the project's CLAUDE.md so no session has to guess which rules apply.
2. Copy TEMPLATE-CLAUDE.md content into the project's CLAUDE.md and fill in the blanks.
   The installer writes its own block into CLAUDE.md either way; do this when you want
   the fuller template around it.
3. The installer does this for you when the project has no docs/domain-rules.md: it
   copies the matching rules/platform/domain-rules-<platform>.md there. Do it by hand
   only to start from a different platform's document. Either way, edit it to fit — delete
   inapplicable sections, add product-specific rules, and keep every rule checkable: a
   reviewer must be able to answer "does this change break the rule — yes or no?".
4. Recommended, not required: install the BuilderOS skills (see "Built on BuilderOS"
   below), npx skills add BuildGreatProducts/builder-os. Some rules are written to sit on
   top of the Claude Code build loop, design-better and design-system, and read best
   with them present. No check depends on them: nothing is refused if you skip this.
5. The numbered files in rules/ are read in place — reference this repo's path from the
   project CLAUDE.md rather than copying them, so improvements land everywhere at once.
6. Run python3 enforcement/adopt.py <project-dir> --measure-tools (--dry-run first if
   you like). The installer can be run from a fetched release rather than a clone: the
   quickstart has the one command that fetches the newest release
   into ~/.cache/coast-standards/<version>/. It installs the checks under .coast/checks/, the
   three git hooks under .githooks/ with core.hooksPath set, the Claude Code session
   hooks (.coast/hooks/claude-hook.py and .claude/settings.json), the platform's
   linter seeds, docs/domain-rules.md when the project has none, the baselines and the
   config under .coast/, and the standards block in the project's CLAUDE.md with the
   "enforced by a check" number. A first install at a terminal asks the on/off questions
   once — one screen each for the rules, the push-gate seats and the session hooks, every
   default on, Enter takes them all — and writes the answers to .coast/config.json; --yes
   skips the questions, --init asks them again, --owner "Pat Lee" --product "Example App"
   fills the names every refusal sentence uses. --measure-tools builds the project once so an existing repository's
   warnings, formatter and linter findings — and a missing test target — start as
   baselines instead of refusing the first push. Re-run it to take a newer version — it
   replaces governed files, keeps anything you edited, lowers a baseline that fell, and
   changes nothing when nothing changed, and --release <version> (or latest) fetches
   another release and installs from it.
7. Install the programs the checks run — your platform's linter, formatter and test
   runner, plus jscpd — before your first push, which is where a missing one is
   refused. The list per platform is in the quickstart; the pinned
   versions and what each is used for are in enforcement/TOOLCHAIN.md.

How enforcement works, in one screen

Every rule in rules/ ends with a [check: …] tag naming what holds it, and the tag
puts the rule in one of five bins — machine (a check refuses the change: the scanner,
the linter with the shipped config, a tool the push gate runs, a hook), partly (a
machine check and a reviewer share it), advisory (the scanner reports it, nothing
fails), reviewer (only a mind can judge it; every review returns a row per rule with
evidence), process (held by the pipeline or by a person). verify_rules.py counts the
bins and fails the commit when a rule names no check or names one nothing runs; the
corpus stands at enforced by a check 170 of 643 (4 September 2026), and each project's
own number comes from its docs/domain-rules.md.

A rule whose check a person switched off in .coast/config.json is counted as switched
off, never as enforced: the number reads "24 of 74 (3 switched off)", because the number
is honest or it is nothing.

What refuses, and where: .githooks/pre-commit (the scanner on the staged diff — added
lines only, in seconds), .githooks/commit-msg (a subject under 100 characters; an agent
session's commit names its model), .githooks/pre-push (build, tests, lint, format, the
scanner on everything added since the remote and on the whole tree, the doc-comment count,
jscpd, the protected-main ruleset — each on what the push changed: a push of documents
alone runs none of the code checks, a push of code runs the linters on the changed files
and the tests of the modules that depend on them), and the Claude Code hooks in .claude/settings.json
(no edits to the files that define the checks, no cd X && … chains, no infrastructure
commands, no --no-verify or force-push, the staged scan before a commit, the scanner on
every edited file, no ending a turn with unpushed work).

An existing repository adopts without a rewrite day: the counts of what it already
violates — the scanner's ratchets, the build's warnings, the formatter's and linter's
findings, a missing test target — are written once to .coast/ratchet-baseline.json with
a 90-day deadline. A change may lower a count, never raise it; past the deadline the check
blocks. Never --no-verify; the governed files are not an agent's to edit.

Built on BuilderOS

The product-side skills these rules assume come from
BuilderOS by Build Great Products (MIT).
Planning a product, running the build loop, designing well and generating a design
system are solved problems there, and the skills work. There is no reason to redo that
work here, so this repository does not copy them. Install them once, and keep them
current from the source:

npx skills add BuildGreatProducts/builder-os

Three of them are named by the rules: build-loop-claude-code (the build → review → test
→ fix loop in the git-process rules), design-better (the craft layer under the design
rules) and design-system (token generation). The rest are worth having too.

Releases

Every release is a semantic version in CHECKS-VERSION, a git tag v<number>, and an
entry in CHANGELOG.md; the release workflow refuses a tag that does not match the file
or has no changelog entry, then publishes a GitHub release with that entry. Each project
holds its own copy of the rules and the checks, like a dependency, and records the
release it carries in .coast/standards-version. Nobody needs a clone to adopt: the
installer is fetched from the newest release tarball, and any installed copy can fetch
another release with --release. Contributors clone the repository; adopters do not.

License

Coast Standards is source-available under its own license, LICENSE.md,
not an open-source license. In plain words: you may use it, including in a business,
to build and ship your own software, and you may share it unchanged with the notice
kept. You may change the copies the installer puts in your project, because that is
how it works. You may not sell it, publish a changed version as the standards, or
build a product or service whose main value comes from it, such as an assistant or a
checking service wrapped around the rules and checks. Contributions are welcome and
become part of the standards under the same license. The reason for the choice: the
rules are meant to be adopted as written, and the checks are the product.

Provenance

• The numbered rules/ files were extracted from the rules Coast's own development
  followed: its agent context, its capture log of decisions, and its design-conformance
  rulings. Each rule keeps its origin story where one exists, so the reason travels with
  the rule.
• The five app-platform files in rules/platform/ (iOS, macOS, Android, React Native,
  Web) are the corpus Coast ships into the projects it builds. Each carries a version
  stamp on its first line (<!-- coast-rules-version: N -->): a project's copy is never
  auto-updated. Coast offers a newer version with the changes in plain words, and the
  founder takes it with an explicit click.
• The numbered rules/ files are NOT all universal. They were extracted from an app
  project, and several assume a screen. PROJECT-TYPES.md says exactly which apply to
  which kind of project; the app-only files carry an applicability header.
• rules/platform/domain-rules-python.md (Python backends and services) was written for
  backend work and is not part of the corpus Coast ships, which covers mobile and web
  targets only. If Coast ever ships a Python target, the two must be reconciled.
• rules/08-auditing-and-completeness.md was written from a real completeness-sweep
  failure it describes.

Newer decisions win: when a rule here conflicts with a newer instruction from the owner of
the project, the newer instruction wins, and the fix is to update this repository in the
same session rather than leave the stale rule standing.