Skip to content

Rules

The workshop's rules

The base extension's fragment: only the rules the workshop itself enforces. A repository's own facts (identity, intent, layout beyond the workspace shape) live in its CLAUDE.project.md, which always loads last and wins.

The gate

fm check runs every check the mounted extensions register, in parallel; the gate section below names them for this workspace. Run it before every commit; CI runs the same command. On a machine it gates what the working tree changed since the nearest tree its record proves, and records the tree, so a proved tree runs nothing; --full runs everything. Nothing on the merge path may wait on a person; a service reached with a configured token (an index, a registry, a remote) is allowed. The gate's verdict is its exit code, and a PreToolUse hook (fm hooks.pre-bash) refuses a footman command piped into head/tail and a push of a branch that conflicts with origin/main.

Working conventions

  • Exceptional cases and fallbacks are tested before happy paths: a broken happy path announces itself in daily use, a broken fallback hides until the day it is the only path left. A fallback without a test forcing it is untested code.

  • Everything through fm: a job with a verb goes through the verb, never the tool it wraps, because the verb carries the guards the raw call skips. Branch switching shows why: a workflow verb pairs every switch with an alignment against origin and names the commits it supersedes, where a raw git switch in a shared checkout strands unpushed work silently. A job no verb covers marks a missing verb: file the issue rather than script around it.

  • Development goes through issues: file one (fm issue.create or fm start "title"), work it in its worktree, and let the merge close it. Branches follow <kind>/<number>-<slug> so the close wires itself. A change that belongs to no issue (a note, a small fix) starts as fm start <kind>/<slug>; its submit closes nothing.
  • Worktrees (fm start) live under the runner's data directory (worktrees/<repo>/), outside every repository, and a merge takes its worktree with it. Ad-hoc agent sessions may still use .claude/worktrees/.
  • Person-wide configuration and tokens live in .repo.shared.env in the runner's config directory, so every checkout and worktree starts warm; fm env.set KEY --scope=shared writes it.
  • Failure reasons are printed verbatim, never read as booleans.
  • Whether a person is there is one question with one answer: livery.footman.attended(), which knows --no-input and --dry-run as well as the terminal. A module that imports the runner never asks the terminal itself, because a hand-rolled check ignores those flags in silence, and the layering lint refuses one. What a workspace builds, importing no runner, is its own business.
  • Never pipe the output of a command whose verdict you depend on: a pipe replaces its exit code with the filter's and truncates the failing lines. Redirect to a file and slice the file instead.
  • Every workflow verb is idempotent: re-running it is the recovery procedure.
  • Phases land daily, gate-green, mergeable alone.
  • A phase acceptance that ships deferred keeps an open line in the plan note until the evidence lands. "Shipped" with a silent deferral hides the gap exactly where the next reader trusts the record.
  • A contract clause that code enforces gets a pinning test before its implementation is replaced: name the properties the old code enforced, pin them, then replace it. A property living only in the contract's prose does not survive a refactor.
  • A warning or anomaly found live during other work gets an issue the same day, with a body an outsider can read. A patch where it was noticed leaves every other arm carrying the same fault.
  • The release train owns versions, tags, and receipts. No hand stamps, no hand tags; an out-of-band claim (name-squatting on an index included) is recorded as debt in the plan the day it is made, and the gate refuses a release tag that is not an annotated train receipt.
  • Notes in notes/ describe current state; decisions carry dates in each note's decision record. A note is updated in the same change as the code it describes, or it is wrong. Two changes that both append to a note merge by union (the rendered .gitattributes), so an integrate never stops on a note; the merged note is read once before it ships, since two edits of one line land both.

Commits and tags

The commit convention, machine-read by the release train: subjects are type(scope): subject with types feat, fix, docs, chore, refactor, test; a ! before the colon or a BREAKING CHANGE: footer marks a break. Versions follow footman's practice: after 1.0 a break bumps major, a feature minor, everything else patch; before 1.0 a feature bumps minor (breaks ride along) and everything else is a patch. fm release.prepare <path> derives the bump and the entry through git-cliff, per the package's rendered cliff.toml, from the commits since the last release tag.

Conventional prefixes (feat:, fix:, docs:, chore:, refactor:, test:), imperative subject, body only when the subject cannot carry it. No attribution trailers. fm commit <type> "<subject>" writes one, deriving the scope from the change and gating first. Commit and push only when asked. Tags are release tags, <path>/v<semver>, immutable and pushed alone.

Layering

Dependencies point only downward; the workspace's layering lint (livery.workshop.verify_workspace) enforces the contract graph. The importable namespace is PEP 420: never create a namespace-level __init__.py.

Interfaces and typing

This is the final form; there are no typing clean-up passes later.

  • Public is what a package's __init__ re-exports in __all__. Every other module is underscore-named. A test pins both.
  • Test modules are named by their path (pytest's importlib mode), so two packages may both have a tests/test_lifecycle.py, and a test module never imports another. A helper module in a package's tests/ carries the package's name (workshop_seeds.py), since every tests directory shares one pythonpath; the session refuses to start otherwise, naming the module and the name it wants. A function a test hands to a spawned process lives in such a helper.
  • The type checkers the workspace lists gate, none advisory: pyrefly, ty, mypy strict on the namespace (linux, darwin, and win32), and basedpyright with warnings as errors. With [phases.typecomplete.basedpyright] enabled = true in the root contract, basedpyright also requires every public API to be 100% type-complete.
  • A suppression is narrow, inline with the code, and carries a reason: # type: ignore[code]. Pyright-only suppressions use # pyright: ignore[...] so mypy's unused-ignore check stays honest.

Docstrings

  • Google style only: Args, Returns, Raises, Yields, Attributes. The lint phase enforces the convention.
  • No RST anywhere. Not in docstrings, not in comments.
  • The voice and word rules of the imported guidance fragments apply to docstrings the same as to every other published sentence.
  • Refer to other objects by their full public import path, wrapped as a reference ([livery.forge.Forge][]), so generated API docs cross-link them across packages; a bare dotted path stays plain text.

Workspace shape

  • packages/<name>/: one package, discovered by its workshop.toml.
  • packages/<name>/docs/: plain markdown, the seed of the rendered per-package site. Write it as that site, never as scratch.
  • tasks.py: plugin("livery.workshop"), the whole dev loop.
  • workshop.toml: the workspace contract (extensions, forge, runners).