New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Automated setup skill that configures hum in a repo and proves the setup on a scratch copy.

GitHub stars
38
View on GitHub

What it does

  • Adds the hum skill and a hooks.json hook for setting up or changing hum in this repo
  • Reads the repo, proposes every setting, and asks you only what you alone hold
  • Writes .hum/hum.json and adds a check tool's ignore line for the slot folder you approve
  • Proves the configuration on a scratch copy before it is applied to your repository

Work items become Claude Code agent runs, on your Mac or in CI. The repo's own checks decide what they can, a path's risk level decides who reviews, and only what nothing settles becomes a question to you.

Add marketplace

/plugin marketplace add saadshahd/moo.md

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install hum@moo.md

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Read first, then ask. Every question leads with what the repo showed and a proposal to accept or change.

Read

Run bunx hum setup scan (the pinned engine: bun add --exact @moo.md/hum@<version> first if package.json has none). It prints the scan, a proposal for each setting, the waiting states, how many open issues the label map covers, and gitIdentity: the name and email hum will commit as, read from your git config. Where the base requires signed commits, GitHub makes hum's commits and credits them to the token's account instead: yours on a Mac, the App's bot in CI. If gitIdentity.found is false, stop: tell the owner to set the missing keys with git config --global <key> "<value>" and ask nothing more. Answer nothing from the scan that the repo already says.

Ask

Ask in this order. One question per turn, each with its proposal. Where a question is open-ended, call hope:elicit; where the answer is a rule others must apply the same way, call hope:anchor; where a setting steers unattended work, call hope:target.

AskProposal comes fromThe answer sets
Where runs happen: your Mac, CI, or boththe scan: CI workflows, a service unit; with roundup Todos, your Mac alone, as setup refuses CIrunPlaces
Where items, questions and answers live: GitHub issues, markdown files in itemsDir, or roundup Todosintegrations in the proposal: GitHub where the repo has open issues or an issue template. An issue is ready once it carries readyLabel; hum leaves one a person is assigned to, or an open pull request closes. Offer roundup where RUPD_SOCKET is set in this shell: a Todo is ready once it is open and unblocked in the root Workstream roundupWorkstream names, where the owner puts what hum should build; hum moves each Todo it takes into a Workstream of its own, "# ", and files its follow-ups back into the named one integrations, roundupWorkstream
Which commands a change must passCI jobs on pull requests, else package scripts, after the lockfile install a fresh clone needschecks
Whether every change lands through a pull request, even where the base takes a pushthe base's rules, from gh api repos/<owner>/<repo>/rules/branches/<base>: where they require status checks and no pull request, a push from a token that may bypass them skips the checks; propose true there, else falsealwaysPullRequest
Which label a pull request needs when it grows some fileslabelGates in the proposal: a repo label a job quotes, in a workflow that runs again when a pull request gets a label. Read that job. Where it fails a pull request that grows the bytes of some files and lacks the label, write one entry per set of files it sums apart, with globs that match exactly those filesgrowthLabels
For CI runs: the repo's setting "Allow GitHub Actions to create and approve pull requests"workflowsMayOpenPullRequests in the scan; if off, ask the owner to turn it on and never change it yourself; null where the scan could not read it, as anyone but a repo admin cannot: ask the owner to check itnothing written
For CI runs: the runner, job container and env the wake's jobs run withwakeJob in the proposal: the job that runs Claude Code, else the pull request job; drop env only that job uses. The image needs git, node and npm; one that runs as root needs IS_SANDBOX set to 1 in ciEnv. An env value that reads a secret reaches only the step that runs humciRunner, ciContainer, ciEnv
For CI runs, when the owner names a runner GitHub does not host and isPublicRepo in the scan is not false: whether wakes may run therethe proposal never names one; such a machine keeps what a job leaves, so a process a run started could outlive the work job and reach the next job there, which holds GitHub's token; recommend ephemeral runners"ownRunnerOnPublicRepo": true beside hum in the answers, only on the owner's yes
For CI runs: how Claude Code signs inwakeJob.ciClaudeAuth: the CLAUDE_CODE_OAUTH_TOKEN secret, or env where ciEnv carries the credentials, such as a gateway's settingsciClaudeAuth
For CI runs: how a pull request's required checks starta pull request opened with the workflow token starts no workflows, and dispatching the check workflow does not satisfy the required check; ask for a GitHub App with contents, issues and pull requests write, whose two secrets wakeJob.pullRequestToken names where a workflow already mints a token, or a fine-grained token's secretpullRequestToken
One question per waiting state: after how many hours it times out, and so goes to its leadsTo statewaits in the scanwaitHours
What each folder's risk isfolder history and namespaths, strictPaths
Which paths hold data or secretsthe scan's matchesstrictPaths
How many merged changes judge a fix or a measurethe shipped windowschangeLabels.fixWindow, measureWindow
Which label means which kindissue-template labels and repo labelskindLabels
Which kind an item takes when no label and no Kind: line name onethe work source: where its items never carry labels, as roundup Todos, the kind most of them are; else null, so the cheap model call picks and asks when unsuredefaultKind
Services and setup each run slot needscompose file, env script, install commandrunSlots
One question per check tool that reads the pool folder, where run slots are on and the pool lies inside the checkout: the tool's ignore line for the poolslots are on where runSlots.enabled is true or integrations names roundup; the pool is runSlots.pool as settled: the proposal's, unless .hum/hum.json or the owner names another; each command in checks, as the paragraph below reads itthe tool's ignore entry for the pool, written in that tool's own config, outside the answers file, only on the owner's yes
Whether items with no touches: line run beside others, and how many times a change another run beat to the same files is built againthe work source: where items never name their files, as roundup Todos, run them side by side with one rebuild; else keep them aloneundeclaredRunsAlone, conflictRebuilds
Which files every review reads beside the diffthe repo's rules files, such as AGENTS.md; an item adds its own on a reads: a, b linereviewReads
When ciClaudeAuth is oauth-token: the date the CI token expires, after claude setup-tokenonly the owner holds ita reminder the owner keeps

A check run from the checkout can walk every slot in the pool: .git/info/exclude hides the pool from git, and a tool skips it only where it honours that file or a rule in its config does. For each command in checks, follow it through package scripts and wrappers to its tool, then read each config the command loads, and the tool's defaults and docs, for whether the tool walks the pool. A tool given its files or folders by name does not. One whose defaults and configs show it takes every folder they do not skip by name does. One whose handling of .git/info/exclude they leave open goes to the probe: add /<pool>/ to .git/info/exclude, run git worktree add --detach <pool>/probe origin/<base> (the base branch the scan ran with), break in it one file for each tool you probe, run each command from the checkout, and count a path under the pool in its output as the tool reading the pool. Then run git worktree remove --force <pool>/probe; leave the exclude line, which hum adds itself. For each config whose tool reads the pool, name the config file and propose the one entry that config uses to skip a path.

Say what the labels cover: "kindLabels covers N of M open issues; the rest get defaultKind, or where it is null the fallback kind and one question."

Where runs include CI and isPublicRepo is not false, tell the owner that anyone can read refs/hum/state, where each wake keeps hum's state: plans, answers and the output of failed checks.

Where runs include CI, tell the owner what a wake's three jobs hold. gather and publish hold GitHub's token and run hum from npm, with none of the repo's code. work runs the runs and the repo's checks with no GitHub token, but it holds the Actions token its artifact upload needs, so a run there could write the Actions cache on the default branch for any workflow that restores it. Publish checks that the commit identity commits each new commit and writes it, unless a rebase kept the author of a commit gather handed on, but the work job writes those names itself: what holds against a hostile work job is that publish writes only hum's own branches and places every change from its own diff and config.

Write

  1. Write the answers as JSON: { "hum": {settings}, "waitHours": { "kind/state": hours }, "schemaVersion": 3 }. Where integrations names roundup, set runSlots.enabled to true: every run there is a Rail row in a run slot.
  2. Run bunx hum setup write --answers <file>. A refusal writes nothing: relay its message, which names the fix. Where integrations names roundup, write prints program in place of a service unit. Only the owner may name the Project's program, so hand them that step whole: open program.open, enter each of program.fields as printed, a blank Folder left blank, then program.start. roundup then runs hum serve, starts it again after any exit, and shows hum's status on its row; while the Program differs from what setup printed, the row names the difference and no worker starts. hum serve builds every open Todo in the root Workstream roundupWorkstream names. Make that Workstream where the Project lacks it; the owner puts there the Todos hum should build. hum serve restarts hum work after a crash or an update.
  3. Run bunx hum setup measure to record each model's pass rate, so a check that cannot yet be trusted reports instead of gating. Tell the owner: once a role file or a judge's prompt changes, the Mac worker measures that judge again, spending live calls, and writes the new rate into .hum/hum.json. The old rate gates until then, and in CI until they commit the file.
  4. Run bunx hum setup prove. Add --item only after the owner agrees to the live calls it spends.

End by stating what is now written, which proofs passed, and which were skipped and why.

From the saadshahd/moo.md README

skills.sh

Why introduce friction? Because YOU the human end up being the world model. The agent is just your hands.

moo/hope doesn't build, and doesn't author your code, rules, or taste. It works alongside build tooling like superpowers.

One idea runs through every layer: agents at the pace you think.

Installation (30-second setup)

1. Get the skills

curl -fsSL https://saadshahd.github.io/moo.md/install.sh | sh

One line works out what your machine has. Run it again to update.

  • Claude Code gets the hope, hold and hunch plugins, managed bundles that update when I ship, and the hold:Plain output style. A session already open needs /reload-plugins.
  • Codex, Cursor, Copilot, Gemini CLI and opencode get the same skills as files in ~/.agents/skills, copied by skills.sh and yours to edit.
  • Both on one machine get both. Claude Code does not read ~/.agents, so no skill lands twice.
Claude Code: what this runs
claude plugin install hope --marketplace saadshahd/moo.md --scope user
claude plugin install hold --marketplace saadshahd/moo.md --scope user
claude plugin install hunch --marketplace saadshahd/moo.md --scope user
claude plugin marketplace update moo.md
claude plugin update hope@moo.md
claude plugin update hold@moo.md
claude plugin update hunch@moo.md

Then it edits ~/.claude/settings.json and keeps every other key. It sets "outputStyle": "hold:Plain", and "autoUpdate": true in the moo.md entry of extraKnownMarketplaces, since Claude Code leaves auto-update off for marketplaces Anthropic does not run.

hope is the decision loop, and the reason to be here. hold is comprehension at your own pace, and its hold:Plain output style keeps replies short. hunch is experiments that graduate or die. One more layer ships from the same marketplace: sound@moo.md, code taste as installable rules, and the current best tool for a need.

Codex, Cursor, Copilot, and other agents: what this runs

When your home folder holds .codex, .cursor, .copilot, .gemini or .config/opencode:

npx --yes skills@latest add saadshahd/moo.md/hope --global --agent universal --skill '*' --yes
npx --yes skills@latest add saadshahd/moo.md/hold --global --agent universal --skill '*' --yes
npx --yes skills@latest add saadshahd/moo.md/hunch --global --agent universal --skill '*' --yes

hope and hold arrive whole: their skills call each other by name, and a missing one stops the skill that called it.

They land as ordinary files you own — flat, and without the plugin prefix, so hope:intent arrives as intent and hold:grasp as grasp. Watch for collisions with skills you already have. Running the line again replaces them, your edits included.

For an agent that reads its own folder, such as Windsurf or Goose, or to add sound, pick the skills and the agents yourself:

npx skills@latest add saadshahd/moo.md

2. Run the loop

/hope:full <your seed>

Or run the stages directly — /hope:intent <your seed>, then /hope:shape <your intent>.

A loop

The loop is pure decision work. You drive it slowly, in your own context.

Every piece of work starts as a raw <seed>, the rough thing you fully typed. It is the one artifact that is fully yours.

/intent and /shape do not make the seed more honest. They make it explicit and specified. Each surfaces a decision as an interactive question, every choice previewed, a few at a time, and you answer. Every added detail stays yours because you chose it. /intent turns the <seed> into a confirmed statement of what you want. /shape turns that <work order> into a chosen approach before any code exists.

The outcome is short enough to carry comfortably outside the context window.

The loop

An anchor

freeze anchors the work to what is observed, not what you remember. When a stage depends on state that lives outside the repo — a service, a database, a queue, live logs — that state keeps moving, and memory of it goes stale the moment you look away.

freeze snaps the slice your work touches into one immutable value: every fact observed live or named as an open gap, never inferred. The stages decide against a fact, not a guess. It is the ground the other three stand on — and repo-local work skips it.

freeze

A mode

router is the line between deciding and doing.

You keep every decision. The session spawns agents and verifies their output, doing no work itself — only tactical, observable work fans out: implement, test, verify, audit, explore.

This is also what stops compaction from silently rewriting your context. The verbose doing never enters your main thread, so it can never quietly mutate what you decided.

Deciding stays, doing leaves

Overview

The trapLayerGuard
AI fills in your decisions/hope:intent & /hope:shapeinteractive questions, each choice previewed
compaction mutates & drifts your context/hope:routerdoing stays out, deciding stays in
stale or remembered external state/hope:freezesnapshot facts, never infer

Reading

Details

Marketplace
saadshahd/moo.md
Source
hum
Category
Automation
Keywords
hum, work items, agent runs, checks, background

More from saadshahd/moo.md

All 6