agentleFS
maximilianfalcomaximilianfalco/messhall/CLAUDE.md

messhall

CLAUDE.md1 starsChanged 34 days agoMITView on GitHub

Repo rules for Messhall. The global ~/CLAUDE.md still applies; these add to it or override it where stated.

The file

We split this CLAUDE.md into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Commit and PR titles are title-only conventional commits.

    line 22
  2. Very specific:

    Every PR carries QA proof.

    line 28
  3. Very specific:

    Write in the owner's voice: lowercase starts, dont not don't, we not I, no em dashes, no semicolons.

    line 29

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

Repo rules for Messhall. The global ~/CLAUDE.md still applies; these add to it or override it where stated.

Read first

  • The plan lives in the gitignored personal-dev-notes.md under "Plan (moved out of the repo)". It is the source of truth for scope and decisions, and its "Engineering standards" section is binding for every change. Read that file first; worktrees link it in.
  • CRITICAL.md names the code trees that hold the trust promise (the Host/Origin guard, the agent and human keys, the human-seat routes). Changes there wait for the owner to merge and run on the strongest model.
  • The messhall-control skill (.claude/skills/messhall-control/) is how work gets verified: pnpm messhall-dev check before any commit, the matching messhall-dev command as evidence, and a feature map row for every surface.
  • The messhall-pickup-any-work skill (.claude/skills/messhall-pickup-any-work/) is how work gets picked: claim a row in the job queue, build it in its own worktree, close the row. Spawned with no brief? Run that skill.
  • The using-messhall skill (.claude/skills/using-messhall/) is how an agent takes part in a room: converse, ask, answer, hand over, not just status lines. Spawned agents read it before joining.
  • The messhall-tape-qa skill (.claude/skills/messhall-tape-qa/) is how QA proof gets recorded: one vhs tape per case, uploaded with pnpm messhall-dev qa-upload, a table in the PR.

Branches, commits, pushes

  • main is the only long-lived branch. Never build on it.
  • One branch per job, named after the slice: f1/store, f2/mcp-tools. Commit on the branch as often as useful (this overrides the global "no automatic commits" rule for this repo).
  • Work runs in git worktrees under .worktrees/<name> (gitignored): git worktree add .worktrees/f1-store -b f1/store --no-track origin/main, then pnpm install and link personal-dev-notes.md in. Remove the worktree after the merge.
  • Pushing your own job branch and opening its PR, once pnpm messhall-dev check is green, needs no ask: the owner okays it up front for every job in this repo (this overrides the global "never push unless told" rule here). Never push main, another agent's branch or a force push.
  • Push a branch once, when the gate is green. Open the PR, let CI run once, then squash-merge with gh pr merge <n> --squash --admin (never a merge commit or a rebase onto main). main has a ruleset: PRs only, squash only, one code owner review, signed commits, no force push. The owner merges through the admin bypass, which is why --admin is needed. When main moves under an open branch, git merge origin/main into it. Never rebase or force-push a pushed branch.
  • Merge without asking when CI is green, except PRs that touch a CRITICAL.md tree (they get the human veto label): those wait for the owner.
  • Commit and PR titles are title-only conventional commits. No bodies, no AI credit.
  • Job queue row ids live in the queue and the vault only. Never write them in commits, PR titles or bodies, or any tracked file. Name the thing instead: "the room store".

PRs

  • Fill every section of .github/pull_request_template.md. The One Liner is plain words. Key Decisions lists every decided by agent, veto here item. Never tick checkboxes meant for the owner, never tag anyone, never reference other PRs by number.
  • Every PR carries QA proof. CLI, daemon and MCP work gets a vhs recording (demo/tapes/, rules in demo/tapes/README.md); the Mac app gets screenshots. Images go to the qa-assets branch under pr-<n>/ and into a | case | recording | table at the end of "QA and Testing".
  • Write in the owner's voice: lowercase starts, dont not don't, we not I, no em dashes, no semicolons.

Data

  • Everything is local. The daemon binds 127.0.0.1, nothing goes to a cloud, and no room data ever lives in the repo.
  • The daemon is the only SQLite writer. The CLI and the Mac app talk to the daemon, never to the database file.
  • The agent key and the human key are files in the data dir with mode 0600. Never print them, log them or paste them in chat.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.