tiagocolombo/hallmark / plugin/skills/hallmark-setup
hallmark-setup
VerifiedConfigure Hallmark for this person and repo with `hall config` - gates and the shell they run in, how worktrees are made and work is shipped, models, budgets, where claude and gh live, notifications. Use when they say "set up Hallmark", "configure hallmark", "change the gates", "use devbox/nix/mise for the checks", "change the ship command", "set a budget", "hall can't find gh", or ask what a Hallmark setting does.
Setting Hallmark up
Every Hallmark setting can be read and changed with hall config. You never
edit .hallmark.toml or the user config by hand. hall config keeps their
comments and checks each value before it writes. Don't run
hall setup --interactive: it asks its questions on a terminal, and you
can't answer them. Ask the person yourself, then set what they choose. hall init and the first hall setup ask the same questions on a terminal; from
a session they don't (there is no terminal), and --defaults says so
explicitly.
Look first
hall config list --json # every key: value, source, kind, help, allowed values
hall config list gates --json # one key, or every key under a prefix (budget, notify)
source says where a value comes from:
default: Hallmark's built-in value;repo: this repo's.hallmark.toml;user: the person's user config;env: aHALL_*variable;path: a tool found on PATH.
Detect before you ask. Read package.json, Cargo.toml, Makefile,
justfile, flake.nix, devbox.json, mise.toml and .envrc, then propose
concrete values.
Ask, in this order, one topic at a time
Propose a value and let the person confirm or change it. Skip anything they are happy with.
-
Base branch (
base): what reviews compare against. -
Gates (
gates): the checks every change must pass before review, in order. Prefer the repo's own commands (npm test,cargo test,just lint). Offer a test-strength gate too, but only when its tool is installed and the person accepts that it is slow: mutation testing of the changed code (git diff <base>...HEAD > mutants.diff && cargo mutants --in-diff mutants.diff, PIT'sscmMutationCoverage), or a coverage floor (cargo llvm-cov --fail-under-lines 90,pytest --cov=<package> --cov-fail-under=90). Gates get no base branch or diff, and are killed aftergates_timeout(20 minutes by default), so a mutation gate needs its own limit: the table form{ cmd = "<gate>", timeout = "60m" }in thegateslist, set withhall config set gates '[{ cmd = "cargo mutants …", timeout = "60m" }, "cargo test"]'. -
The gates' shell. The daemon runs gates with
sh -c, outside any shell the person entered. If the toolchain comes fromnix develop, devbox, mise or direnv, wrap each gate:nix develop --command <gate>devbox run -- <gate>mise exec -- <gate>direnv exec . <gate>(only if the.envrcis allowed at every worktree path, which direnv requires)
Offer a wrapper only if its program is installed (
command -v).The person may name another wrapper of their own.
-
Capture (
capture.mode): what happens when you edit code outside an item.gatedenies the edit and explains;askasks the person;offmeans only/hallmarkstarts items. -
Worktrees and shipping, only if they use their own tooling:
worktree, with placeholders{repo} {id} {branch} {slug} {base};branch, with{id} {slug};ship, with{branch} {id} {base} {title} {body_file} {review_file} {issue}({body_file}is the What, Why, How, Testing, How to revert and Risk description);update, with those ofship, plus{pr}and{pr_head};review_comment, which posts each review as a PR comment, with{pr} {review_file} {branch} {id} {base}; empty for none.
-
Models and budget:
budget.review_model,budget.fix_model,budget.intake_modelandbudget.librarian_model;budget.dailyandbudget.per_item: tokens such as4Mor800k, or dollars such as$15. They default to4Mand800k;noneturns a cap off (unsetting the key brings the default back);budget.<role>.max_usd, the cap on one run in dollars (role: review, fix, intake, librarian). Unset, it defaults to 6, 2, 0.10 and 0.20;nonelifts it;max_check_failures: failed checks in a row before an item is held for them (default 3).
-
Merging (
[merge], ADR 0048): whether shipped PRs merge without them.merge.modeisoff(they merge) orauto(the merger merges each ready PR, one at a time, in dependency order, and brings each PR up to date only at its turn, ADR 0050). Ask beforeauto: it is the step from a lit loop to a dark one.merge.command, with{pr} {pr_head} {branch} {base} {id} {title}. When the base branch requires an approving review, the PR's author can't give it: suggest--adminonly if they own the repo or may bypass the rule.merge.require_ci:falsemerges without waiting for CI. With--adminthat includes red CI; say so.merge.update(ADR 0051):files(default) rebases a PR whenever the base moved on a file it touches, so CI tests exactly what lands, one PR after another on shared files.conflictsrebases only when GitHub says it conflicts, and merges clean, green PRs as they are: much faster when most PRs share files (docs), and safe only if the base's CI runs on every push. Either way the merger stops when the base's tip is red (a fix for it is merged by hand), and doesn't merge while the tip's checks are still running.merge.lit: paths a person merges, as globs (.github/, release settings). Such a PR waits in the inbox, andhall retrylets it merge.merge.one_approvalandmerge.two_approvals: paths that need that many people's approvals (hall retrycounts as one, members' approving reviews on GitHub the rest) before the merger merges the PR.
-
The sandbox (
[sandbox], ADR 0053): every headless run is confined. Its file tools read only inside the run's directories and neverdeny_read. Its commands run in Claude Code's sandbox, with no network and no writes outside the worktree, temp and git directories. If the gates need more, add only that:sandbox.allow_write: caches the toolchain writes (~/.cargo,~/.cache/nix,~/.npm). Literal or~paths; globs don't match.sandbox.domains: hosts it downloads from (crates.io,registry.npmjs.org).sandbox.unix_sockets: daemons it talks to. For Nix on macOS,/private/var/run/nix-daemon.socket(the resolved path).sandbox.mode:auto(default),required(fail where there's no sandbox), oroff. Ask beforeoff.
claude_argscan't hold flags that loosen a run (--settings,--permission-mode,--dangerously-skip-permissions, …): the file is refused. -
Tools, user scope:
tools.claudeandtools.ghwhen they aren't on the PATH the daemon gets. Use absolute paths. -
Notifications, user scope:
notify.desktop,notify.phone(ntfy://ntfy.sh/<random topic>ortelegram://<token>@<chat>),notify.slackandnotify.quiet_hours(22:00-07:30). Runninghall notify testcreates a private ntfy topic if they have none.
Set what they chose
hall config set base trunk
hall config set gates "nix develop --command cargo test" "nix develop --command cargo clippy --all-targets -- -D warnings"
hall config set capture.mode ask
hall config set budget.daily 4M
hall config set claude_args -- --verbose # `--` before values that start with -
hall config set sandbox.allow_write "~/.cache/nix" "~/.cargo"
hall config set --user tools.gh /opt/homebrew/bin/gh
hall config set --user notify.quiet_hours 22:00-07:30
hall config unset budget.per_item # back to the default (800k)
hall config set budget.daily none # no daily cap
- A list takes several values, or one TOML array (
'["a", "b"]'). - A
USAGEerror names the problem and the allowed values. Fix the value, never the file. - Repo settings are written to the main checkout's
.hallmark.toml, which is development work. Tell the person to commit it. The reviewer reads review settings from the base branch, so those apply once the change is merged. hall config setrefuses inside Hallmark's headless runs, such as the fixer and the reviewer.
Repo skills
When the repo needs its own review or fix rules (N+1 queries, a migration policy, how its tests are run), write a skill in the repo. Hallmark reads it from the base branch, so it applies once merged:
| File | Followed by |
|---|---|
.hallmark/skills/principal-review/SKILL.md | the reviewer |
.hallmark/skills/hallmark-fix/SKILL.md | the fixer |
.hallmark/skills/hallmark/SKILL.md | development sessions |
It adds to Hallmark's skill. To replace it instead, put mode: replace in
the frontmatter. Keep additions concrete, with the severity each problem
gets: "An N+1 query on a list endpoint is a major." It's development work:
make it an item. hall doctor lists what the base branch has.
Extensions
Skills by other authors that Hallmark's roles can follow, embedded in hall
and credited: hall extensions --json lists them, what each role gets and
what's on. When the person wants one, such as Matt Pocock's skills:
hall extensions enable mattpocockturns it on for every role it serves;--role reviewer --role fixerfor only some.hall extensions disable mattpocock [--role …]turns roles off.- Like other repo settings, it's written to the main checkout's
.hallmark.toml: tell the person to commit it. The reply'snotesays when the reviewer will follow it. - When you mention an extension, name its author: the credit is in the reply.
Finish
Run hall doctor --json, and follow its next for anything still missing. If
the plugin or the daemon isn't set up yet, the person runs hall setup in a
terminal, or hall setup --interactive to answer the same questions there.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |