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 rawgit switchin 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.createorfm 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 asfm 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.envin the runner's config directory, so every checkout and worktree starts warm;fm env.set KEY --scope=sharedwrites 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-inputand--dry-runas 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'stests/carries the package's name (workshop_seeds.py), since every tests directory shares onepythonpath; 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 = truein 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 itsworkshop.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).