messhall-pickup-any-work
Skill1 starsChanged 35 days agoMITView on GitHub
Pick up the next open job from Messhall's local job queue and work it end to end in its own worktree. Use it when spawned with no other brief, or on "pick up any work", "take a job", "what's open", "work the queue", "claim <id>". Optional argument narrows the pick, a job id, a lane (A, B, C) or a slice (f0, f1). Claims the row before any work, sets up the worktree, builds per the repo rules, opens the PR with QA proof, merges, closes the row.
- Installs packages
- Commits and pushes
In this repository6 other files it gives its agents.
- docs/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- messhall-controlSkill
- messhall-tape-qaSkill
- musterSkill
- using-messhallSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 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.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 29
If claim refuses, someone else has it or it is still blocked.
- Very specific: line 58
If the agent never takes its seat, the daemon kills the session and spawn releases the row.
- Very specific: line 63
Never post as human: no messhall say, never read the human key, never call a human-seat route.
- Very specific: line 83
Read files, run pnpm test or git log in that worktree to learn the real shape (a table, a zod schema, a helper's signature) and adapt to it.
- Distinctive: line 84
Never commit, stash or check out in another job's worktree.
- Very specific: line 85
If you build on unmerged work, say which branch in the PR description and merge origin/main into your branch once it merges.
- Very specific: line 86
If the other job is done and merged, git merge origin/main in your worktree and take the merged code instead.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill 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.
Files
Messhall: pick up any work
The queue is a markdown note outside the repo. Its path is the Job queue line in the gitignored personal-dev-notes.md at the repo root. Never write that path into any tracked file. JOB-QUEUE.md at the repo root explains the format for anyone setting up their own.
The note has three job tables (Research, Decisions, Builds). The scripts read all of them. Two scripts do the fragile parts. Run them from the main checkout or any worktree; both resolve the main checkout, so every agent edits the same note:
| Script | Does |
scripts/queue.py path | prints the queue note's path |
scripts/queue.py show [--all] | open jobs whose Needs are all done, across every table (or every row) |
scripts/queue.py claim <id> "<owner>" <worktree> | flips the row to claimed, refuses if it is not open or still blocked |
scripts/queue.py release <id> | hands a job back if you cannot finish it |
scripts/queue.py done <id> <pr-url> "<evidence>" | flips the row to done, clears Worktree, appends a dated line to the end of the Done log |
scripts/worktree.sh <branch> | creates or reuses .worktrees/<branch with / as -> from origin/main with --no-track, runs pnpm install, symlinks personal-dev-notes.md to the main checkout's, prints the path |
The loop
- Read
CLAUDE.md,personal-dev-notes.md("Plan (moved out of the repo)": "Engineering standards" plus the feature's section and every "Decided" line in it) and the feature map in.claude/skills/messhall-control/references/feature-map.md. - Pick.
python3 .claude/skills/messhall-pickup-any-work/scripts/queue.py show. Take the first ready row that matches the argument, if any. Prefer a build over a decision, and prefer the job that unblocks the most rows (the queue's "Start here today" section says which). Never take two. - Claim. Owner is
agent <YYYY-MM-DD HH:MM> <branch>. Worktree is.worktrees/<branch with / as ->. A decision with no branch uses the worktree of the first build that names it in Needs.
Ifpython3 .claude/skills/messhall-pickup-any-work/scripts/queue.py claim <id> "agent 2026-10-06 14:10 f1/store" .worktrees/f1-storeclaimrefuses, someone else has it or it is still blocked. Runshowagain and pick another. - Worktree.
bash .claude/skills/messhall-pickup-any-work/scripts/worktree.sh <branch>, thencdto the path it prints. Everything from here runs inside the worktree. - Decisions. A decision ticket lives in the tickets folder named in
personal-dev-notes.md. When the user is in the session, resolve it with them, one question at a time with a recommendation. When spawned alone, take the recommendation already in the ticket, or the simplest option a demo can show. Write the answer into the plan inpersonal-dev-notes.mdas plain decision text with no process notes (never a "Decided by agent" line in any tracked file), and into the ticket (status: done, a## Answersection whose first line isDecided by agent, veto on the PR, which stays in the vault). Flag it for veto in the PR body's Key Decisions section only. Close the row withdoneand carry straight on into the build it unblocks, claiming that row too. - Build per
messhall-control: feature map row first with statusbuilding, TDD (/tdd),pnpm messhall-dev checkgreen, run the row's Verify command and keep the evidence, flip the row tobuilt. Commit as often as useful on the branch. Push once (git push -u origin HEAD, later roundsgit push: the worker settings allow exactly these two). - PR with
/my-pr, filling every section of.github/pull_request_template.md(One Liner in plain words, Changes as intent not diff, Impact, Key Decisions & Notes with anydecided by agent, veto hereitems, QA and Testing with themesshall-devevidence). Every PR carries QA proof viamesshall-tape-qa: CLI, daemon and MCP work gets a vhs recording, the Mac app gets screenshots. Upload them withpnpm -s messhall-dev qa-upload <pr> <files...>, which prints one url per file, and end "QA and Testing" with a| case | recording |(or| case | screenshot |) table. - Role instructions win. A seated agent follows the instructions its role carries (
my_role). When they hold a review gate (the exampledocs/briefs/worker.mddoes), it beats the merge step below. - Merge when CI is green (and approved, when your role instructions say so). Run
pnpm -s messhall-dev merge <n>. It refuses a PR with thehuman vetolabel or any file on main'sCRITICAL.mdlist, even before theCritical pathsworkflow labels it: then STOP, the PR waits for the owner. Otherwise it runsgh pr merge <n> --squash --adminpinned to the head it checked (themainruleset wants a code owner review, and the owner's admin bypass is how a green PR merges) and deletes the PR's head branch. Never rungh pr mergeby hand:--adminskips the label. Ifmainmoved while you built,git fetch origin && git merge origin/maininto your branch and resolve the conflicts there (never rebase or force-push a pushed branch), because a conflicting PR never gets a CI run. - Close.
queue.py done <id> <pr-url> "<one line: what shipped and how it was verified>". A seated worker runs this itself, it does not wait for the orchestrator. Then update the main checkout:git pull,pnpm install --frozen-lockfile,make install. When the merge touchedcontracts/orsrc/, alsomesshall start, so the daemon runs the new code and wakes every spawned seat. When it touchedcontracts/orapp/, alsomake appthere, quit the running Messhall andopen app/build/Messhall.app, so the human's app speaks the new contract. Remove the worktree after the merge from the main checkout withmake app-clean WORKTREE=.worktrees/<name> && git worktree remove .worktrees/<name>, so no app build stays running or registered. Leave it in place while a PR waits for the owner, and since the owner may merge it outside the room, which rings nothing, loopwaitand checkgh pr view <n> --json stateeach time it returns, then close the row once it saysMERGED.
Spawning seated agents
A subagent with no messhall tools works out of sight. pnpm messhall-dev spawn instead runs a real Claude Code session that sits in the room the whole time, so the human sees it, reads its progress and can ring it mid-job. It is a thin wrapper on the product spawner (messhall spawn): it adds the queue row, the branch and the worktree, and the daemon starts and seats the agent.
pnpm messhall-dev spawn <id> --dry-run # print the claim, worktree, spawn and role instructions
pnpm messhall-dev spawn <id> --brief <file> # claim, worktree, then seat claude there
pnpm messhall-dev spawn <id> --assign worker --instructions docs/briefs/worker.md # seated as worker from its first call
pnpm messhall-dev spawn <id> --assign worker --instructions docs/briefs/worker.md --reviewer reviewer-2 # review gate names reviewer-2
pnpm messhall-dev spawn agent --as reviewer-1 # a seat with no row, in the main checkout
pnpm messhall-dev flock # same as messhall flock: room, seat, role, presence, process, tmux session
pnpm messhall-dev flock stop <id or name> # stop one, then queue.py release <id> if a row is unfinishedspawn <id>refuses a row that is notopenor still waits on a need, so it follows the same rules asclaim. It claims the row and makes the worktree before the spawn, so the agent skips those steps. If the spawn is refused or the worktree fails, the row goes back to open.- Flags:
--room dev(where the agent sits),--model opus,--brief <file>(the row's brief, else the pickup skill),--assign <role>(the role it holds from its first call,unassignedby default),--reviewer <name>(with--instructions: names that reviewer in the review gate in place of@reviewer-1),--dry-run. A seat takes--as <name>. - Every seated agent joins as its branch slug (
f8/spawnsits asf8-spawn) or its--asname, posts a hello line, reads its role withmy_roleand follows it, asks@orchestrator what is my role?after 2 minutes if still unassigned, and callsmy_roleagain whenever a role line mentions it. Only the human seat or a member whose role isorchestratorcan change roles, and only the human makes an orchestrator (the name alone gives no role). - The row, branch and worktree reach the agent only through its role instructions (the
--instructionstext with@reviewer-1swapped under--reviewer, then id, branch, claimed worktree, brief or pickup skill, and leave to runqueue.py done <id>itself). The daemon's seat prompt holds no job words. docs/briefs/worker.md(the review gate),reviewer.mdandorchestrator.mdare example instructions the orchestrator owns, may edit per room and passes withassign_role.- It targets the real daemon and room on purpose, as the human with the human key, so it is the owner's tool: an agent tries it only against a scratch daemon (
--url/data dir env). Watch one withtmux attach -t messhall_<room>_<name>. Mention it from the room to steer it. - If the agent never takes its seat, the daemon kills the session and
spawnreleases the row.
Never speak as the human
- Talk in a room only through your own MCP seat (
join,post,wait).messhall postandmesshall-dev agentjoin as a script, so the room shows you asscript, notclaude. - Never post as
human: nomesshall say, never read the human key, never call a human-seat route. Ahumanline carries the owner's authority, so an agent faking one breaks the trust model. - To try a surface, use your own name on the real daemon or a scratch daemon (
pnpm messhall-dev daemon, and--urlon the command you test).
Review gate (the example worker and reviewer instructions)
- Once CI is green the worker posts
ready for review: <PR url> @reviewer-1and ends its turn until the doorbell rings (or callswaitwith no doorbell). - The reviewer pulls the PR into
.worktrees/review-<n>(detached), runspnpm messhall-dev check, reads the PR body and its QA proof, reviews againstCLAUDE.md,CRITICAL.md, the plan's engineering standards and themock-anand-reviewlens, then posts a numbered list (blockers and should-fix, no nits, under 1,500 chars) mentioning the worker and files the same as a GitHub review. It never writes code, pushes or merges. - The worker fixes every finding, pushes and posts
round N: <PR url> @reviewer-1. It merges only afterapproved @<worker> <PR url>or a human go. - Round 3 without approval: the reviewer posts
@human stuck on <PR url>, round 3and both stop on that PR. - With two reviewers the named one answers.
pnpm messhall-dev reviewsmarks a requeststaleafter 10 minutes with no answer, and the other reviewer takes it. - A PR that touches a
CRITICAL.mdtree still waits for the human after approval.
Queue ids stay in the queue
Row ids never appear in commits, PR titles or bodies, CRITICAL.md, the feature map or any tracked file. Write "the room store" or "the doorbell decision" instead. The queue note and the vault tickets are the only places ids belong.
Cross-checking another lane
Your job may depend on unmerged code. The queue's Worktree column says where every claimed job lives, and git worktree list shows the rest.
- Read files, run
pnpm testorgit login that worktree to learn the real shape (a table, a zod schema, a helper's signature) and adapt to it. - Never commit, stash or check out in another job's worktree.
- If you build on unmerged work, say which branch in the PR description and merge
origin/maininto your branch once it merges. If it changed under you, adapt on your branch, do not edit theirs. - If the other job is
doneand merged,git merge origin/mainin your worktree and take the merged code instead.
If you get stuck
Release the job (queue.py release <id>) with a line in the reply saying why, so the next agent does not repeat the dead end. Never leave a row claimed with nobody on it.
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
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.

