Contributing
Thanks for stopping by. noggin is a small hobby project, run in the open.
How work runs
Section titled “How work runs”- Work starts from a GitHub issue (a ticket). Open one before a big change so the shape can be agreed first.
- The cycle, in order, on mattpocock’s skills: grilling (interview only, nothing is built) → research and domain modelling as needed → plan/spec
→ TDD → code review → PR → retro. An agent building a ticket runs as the
implementersubagent (.claude/agents/implementer.md), so its brief is just the issue. - One PR per concern, kept small, built in its own worktree at
../noggin-wt/<session>/<branch>(the session’s name as ListAgents shows it, e.g. noggin-87, so two sessions never share a path;just worktrees-cleandeletes the local branches whose PR merged or closed, and their clean worktrees, with gh-poi). Open the PR against main on the first push and turn auto-merge on at once (gh pr merge --auto --squash): GitHub squash-merges it once every required check is green and every review conversation resolved. No integration or feature branches: a spec’s tickets land on main one PR at a time. Every branch on GitHub has a PR, except work on hold. - Whoever works the ticket keeps its PR green and answers each review thread (a fix, or a reply saying why not) before resolving it.
- Main is protected: a green PR with Claude’s approval is the only way in. A PR merges on the slim gate (#696, #714:
its title,
just check-light) and main runs the rest, so what main catches (the site, the workflow linters, the model, the sim, Blender) is fixed forward on main by a new PR (#283), as is the rare break two green PRs make together: a PR need not be up to date with main. Bring main into a PR as a merge (gh pr update-branch <n>, orgit fetch && git merge origin/main) only when GitHub reports a conflict, a required check was renamed or the PR needs a fix that just landed on main, and push plain commits, never a force-push: each push dismisses the approval and re-runs the review. GitHub shows no update-branch banner (the repo’s “Always suggest updating pull request branches” is off, Cansin, 2026-11-02). A Dependabot PR gets@dependabot rebase. - Every ready PR gets Claude’s review (
.github/workflows/claude-review.yml: mattpocock code-review plus ponytail): claude[bot] approves or requests changes (a bug, a spec miss, a security issue or a breach of a documented rule; ponytail suggestions never block), and the requiredReviewcheck fails with a request for changes, or when no approval lands on the head (re-run the job, #389). Its approval resolves its own threads a later push outdated (scripts/claude_approved.py). A PR that edits claude-review.yml gets no review and needs Cansin’s bypass. When main’s claude-review.yml changed since the branch’s base,Reviewrebases the branch itself and fails, and the review re-runs on the new head (#433):git pull --rebasebefore your next push. It needs theCLAUDE_CODE_OAUTH_TOKENsecret twice, for Actions and for Dependabot (whose PRs only see Dependabot secrets): runclaude setup-token, thengh secret set CLAUDE_CODE_OAUTH_TOKENandgh secret set CLAUDE_CODE_OAUTH_TOKEN --app dependabot. - A PR’s title is its squash commit, with no body (the repo’s squash message setting is blank, Cansin, 2026-11-02:
#388’s body forced v0.2.0), so semantic-release reads the title alone and a body footer never reaches main. The title is a
Conventional Commit:
type(scope): subject,type(scope)!: subjectfor a breaking change (docs/adr/0010), as @commitlint/config-conventional has it: types build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test; a subject that doesn’t start with a capital (a leading acronym goes in backticks) or end with a period; at most 100 characters. The scope is required, exactly one, derived from the repo: a tracked top-level folder (eyes,web, …), a folder in docs/ (adr,build, …),depsanddeps-dev(dev dependencies) as Dependabot writes them (main’s: a new folder is a scope once it lands). The requiredPRcheck (.github/workflows/pr-checks.yml) enforces it all with commitlint andci/commitlint.config.mjs(a bot’s title may pass 100 characters and start its subject with a capital); editing the title re-runs it. Check a title before you open the PR, at the repo’s root afternpm ci --prefix ci:ci/node_modules/.bin/commitlint --config ci/commitlint.config.mjs <<<"<title>", which lists the scopes when one is wrong. - An issue’s title is a Conventional Commit too, by the same rules, so it can become its PR’s title (#767), whoever or
whatever opens it: an automation writes a valid one from the start (Default Branch Failure’s is
fix(model): \Checks` fail on the default branch at(Model) , #791) and finds its issues by label, never by a title anyone may edit. TheIssue Titleworkflow (.github/workflows/issue-title.yml) runs main's commitlint on each issue opened or edited; an issue can't be blocked, so a failing title gets a comment with the rule and theneeds title` label, and passing removes both. - A PR’s body links its issue:
Closes #N(or Fixes/Resolves, GitHub’s closing keywords) for the issue it finishes,Refs #Nfor one it only moves along, or whose proof (measurements, screenshots from CI’s run) is not in the body yet. The requiredPRcheck (scripts/pr_issue.pyas on main) fails without one. - Issue state labels, at most one per open issue:
ready for agent(can start),in progress(picked up and not in main yet; a spec from its first ticket until its last reaches main),blocked(waits on something no issue can stand for, named in the issue: hardware, sudo, an outside party),on hold(paused by Cansin). A wait on another ticket is GitHub’s own blocked-by relationship alone, set when the ticket is filed (gh api -X POST repos/{owner}/{repo}/issues/N/dependencies/blocked_by -F issue_id=$(gh api repos/{owner}/{repo}/issues/M --jq .id)for N blocked by M); GitHub already shows the issue as blocked, so no label. An issue’s type is its Conventional Commit title, so noenhancementlabel.blockedandon holdare set by hand. The implementer setsin progresson pickup; theIssue Labelsworkflow sets it too once a PR links the issue (the backstop for a PR opened by hand), and clears every state label when the issue closes. - Releases: the whole repo has one version, noggin vX.Y.Z, and it is the git tag (docs/adr/0010, 0017;
pyproject.tomlholds a placeholder). Main releases itself: once a push to main passes Checks,Release(semantic-release,release.config.mjs) tagsvX.Y.Zand writes the GitHub release’s notes when a title merged since the last tag is a feat, fix, perf, revert or a!break (before 1.0 a break bumps the minor, the rest the patch); docs, ci, chore, build, test, style and refactor release nothing. The tag startsRelease Assets, which attaches the Core program zip; the site serves the latest docs alone, labelled with the newest tag (docs/adr/0021). No release PR, nothing committed back; tag nothing by hand. To force a release when main never quiets down: Actions > Release > Run workflow on main (gh workflow run release.yml --ref main -f bump=auto), withbumpauto(the commits decide) orpatch,minor,major(at least that bump). It runs the full Checks on main’s tip, deploys it and, once they pass, tags that commit even if main moved on meanwhile; a run that tags nothing says why in its summary (docs/adr/0017). - The workflows that open PRs, push or merge (Release, the weekly
skillsandblenderones,Review’s rebase, Dependabot Auto-merge) run as the repo’s bot App, because whatGITHUB_TOKENcreates starts no workflow: a private App on yellow-pine, installed on this repo only, with Contents, Pull requests, Issues and Workflows read and write and no webhook, its Client ID in theRELEASE_APP_CLIENT_IDvariable and its private key in theRELEASE_APP_PRIVATE_KEYsecret, set twice like Claude’s token:gh secret set RELEASE_APP_PRIVATE_KEYandgh secret set RELEASE_APP_PRIVATE_KEY --app dependabot. Its<slug>[bot]must be in claude-review.yml’sallowed_bots, or its PRs get no review. Workflows read and write is what a manual Release needs when main moved on during its run: its temporary branch is a ref at a commit with workflow files, which GitHub refuses (403) without it (the App’s settings page on GitHub, Permissions). - Skills (mattpocock’s cycle and ponytail) are pinned in
skills-lock.json. Restore them into.agents/skills(gitignored; the committed.claude/skillslinks there) withnpm ci --prefix ci, thenci/node_modules/.bin/skills experimental_install;node scripts/verify_skills.mjschecks each against itscomputedHash. - Bumps arrive as PRs and merge through checks and review like any other: the weekly
skillsworkflow re-pins the skills to upstream HEAD, the weeklyblenderone re-pins Blender to the newest stable release at least 14 days old (scripts/blender_pin.py), each from its ownskills-bumporblender-bumpbranch, opened or refreshed by peter-evans/create-pull-request (#748), and Dependabot pins actions by SHA and gets auto-merge on every PR, majors too. Bots never commit to main. - Waiting on CI: one background command that exits only on a terminal state (merged, failed, or needs a human).
gh pr checksexits 8 while any check is pending, and the sleeps cover the checks registering and auto-merge landing:sleep 60; until gh pr checks N >/dev/null; [ $? != 8 ]; do sleep 60; done; sleep 60; gh pr view N --json state,mergeStateStatus,reviewDecision. A build:gh run watch, or a loop with a sleep on its PID, which ends even when the build stops short. - Claude Code’s deny list (
permissions.denyin.claude/settings.json) refusesgit stash(work waits in commits),gh pr merge --adminand a push to main (a PR lands through auto-merge), and each heavy recipe asjust Xoruv run just X(test_derived.pyholds it to the justfile’s heavy group). It matches the command as written, so it catches a slip, not a workaround (#611); every other rule here holds because you follow it. - Main’s ruleset refuses a direct push, but an admin can still merge a PR with
gh pr merge --admin; the deny list stops agents doing that, and its push-to-main entries are only a backup. - Keep the session’s own checkout clean and detached:
.claude/hooks/sync_checkout.pyfast-forwards it to origin/main at session start and before each subagent dispatch, so subagents load main’s.claude/agents/, and blocks a dispatch once when that moved an agent’s file (retry it). A dirty or branched checkout stays put, with a warning (#577). - CI names follow GitHub’s UI: every job a Title Case name (
Fetch Skills,Model (rest)) under a kebab-case id, every step a short sentence-case imperative like itsSet up job, every workflow a Title Case name in its kebab-case file (Default Branch Failure indefault-branch-failure.yml). A run with no commit, PR or issue to title it gets arun-name, a Conventional Commit like every title:ci(ci): weekly <Workflow> <what>,ci(ci): manual <Workflow> run by <actor>, or aworkflow_run’s triggering run’s title as-is, since GitHub shows the workflow’s name beside every run (#773, #866;test_workflows.py,ci/commitlint.test.mjs). After renaming a required check, rename it in main’s ruleset too (Codefails while the ruleset names a check no gate job does: itsCheck the required checksstep, yq and comm) and rungh pr update-branchon every open PR so it reports the new name. A required check names a gate job, one without a matrix (todayPR,Checks,Fetch Skills,Review), never a matrix job (#570). - Each workflow has one header comment, right under
name:, whose first line is its one-line purpose; the site’s CI/CD page builds its table from them (docs/ci-cd.md, #425). - Vocabulary lives in
GLOSSARY.mdand the decisions indocs/adr/; use those words and record a new decision as a new ADR, numbered the next free one. When Code fails because main took that number since,git mvthe draft to the next free number and change the old number on the lines your branch added (docs/adr/0015). - Secrets (a Wi-Fi password, a token) are typed in a Terminal window (
just wififor a new network), never at Claude Code’s!prompt, which has no stdin.
- The code follows CLAUDE.md’s directives.
- The recipes live in the
justfile(docs/adr/0016;just --list). Add a new recipe beside related ones, never at the end of the file, where two PRs appending at once clash (#492). just lint(ruff and pyright) is every change’s local check, which the pre-push hookjust venvturns on runs (#714). A change to model/ (parts, geometry, MuJoCo) also passesjust linux-test <its tests>before its push:just oursand those tests in the CI base image under Docker, since Linux’s OCCT fails parts macOS’s builds (#737, #772).just check-lightis the PR gate’sCodejob:just lintand the tests not markedmodel(every test that builds or reads our parts is, and runs in theModelshards, #808). A heavy Python job an agent needs before CI (the sim, CoACD, every test, the warp maths) runs on Cansin’s GX10, never the laptop:just gx10 <command>(just gx10 uv run just test) runs the branch’s pushed commits there and streams the output;FETCHnames paths to copy back. Blender stays here and in CI (no Linux ARM64 build). When the GX10 is unreachable the recipe says so at once: run the light checks and leave the rest to CI (#888). Until #890 and #891 land,just oursand the electrical tests fail there, and with them themodeltests. Everything heavier is CI’s on main:just checkis itsCodejob (adding actionlint, zizmor and hadolint; in CI zizmor runs online and shellcheck parses the shell scripts, sojust checkskips their offline twins, #732),just check-alladds themodeltests. The heavy recipes take a machine-wide lock (scripts/heavy.py), so only one runs at a time: several at once took the Mac to ~30 GB.- CI runs on pushes to main, on ready (non-draft) PRs and weekly on main, where it runs everything and deploys nothing.
A ready PR runs the slim gate alone, within about 1.5 min (#696, #714):
PR,Review, and PR Gate (pr-gate.yml, #722):Code(just check-light), then itsChecks. Checks (checks.yml: Site, Convex, Model, the sim, Blender, the smoke) runs on main after the merge, CodeQL weekly (#728), and a red default branch files its own issue (fix(<the failed job's scope>): \Checks` fail on the default branch at( ) ), labelleddefault branch failureand found by it (#697, #745, #767, #791). Only the main session runs the full run on a branch (gh workflow run checks.yml –ref, #562), to debug a main failure; an implementer's branch runs the slim gate alone. Each workflow runs only the newest commit of a PR, so a cancelled PR run means a newer one superseded it: every workflow onpull_requestkeys itsconcurrencyon itself and the PR withcancel-in-progress(#675,test_workflows.py); one onpull_requestalone tests no event, so it lists no job every PR skips (#722). Checks, which deploys and Release waits on, never cancels: main's runs queue and each finishes, so merges minutes apart still deploy; a newer push replaces a run still waiting, never one running (#689). A run whose job failed can neither deploy nor release, so every job of Checks and PR Gate but the gate ends incancel-on-failure(.github/actions/), which cancels the rest of the run at once, and Default Branch Failure files it all the same (#769). Checks'Deploy`, Release and Release Assets never cancel a run mid-way. - The required
Checksis PR Gate’s gate (.github/workflows/pr-gate.yml, #722): it fails unlessCodepassed. Main’s Checks (.github/workflows/checks.yml, #496) ends in a gate of the same name, which fails unless every job there passed or was skipped. ItsChangesjob (dorny/paths-filter, plus cache lookups) skips the work whose inputs did not change, against main’s last commit whose Checks passed on a push (#471);test_derived.pyholds each filter to its inputs.Siteruns after Blender unless a job before it failed: it builds the deploy with the next Mech’s pictures, tests it and plays it in Chrome, once (#732). The sim’s reports are keyed on what they are made from (scripts/inputs.py, as the pictures’), so a CI edit runs no sim. Modelruns on eight shards,just mechone of their units, balanced by the seconds CI measured inmodel/durations.json, andRenderon eight, its pictures balanced by their Blender seconds there (#839);just model-durations <id>refreshes it from a run’sdurations-*artifacts. A cold parts cache is built and cut inConvex, which saves it for the shards. CI renders no picture and bakes no GLB, and no workflow uploads an artifact or release asset with the parts, their cut, a picture or a GLB: every artifact of a public repo is anyone’s (ADR 0019,test_workflows.py); the Actions cache carries them between jobs. The sim runs on the mechanical documents alone (ADR 0020), in three parts among the shards’ units (SIM_PART), whichSimmerges and thresholds (just sim-merge, #809). Its reports are never committed: main’s are on the site at /reports (ADR 0009), and a run that changes their inputs diffs its reports against main’s last in its job summary.- Each job’s slowest tests are in its run summary. On CI a test gets 15 s (pytest-timeout’s
--timeout, inCodeand theModelshards’ tests; just mech’s live checks wait on the Core’s real timers and get none), its fixtures aside (timeout_func_only): the parts a module’s tests share are built once a worker in a fixture, whose seconds show as setup. A slower test is made fast or split (parametrized: by part, member, motion or a chunk of pairs) before it merges (#808). - The jobs that need a system tool uv can’t install run in our CI images (
ci/, ADR 0009, #288) by their:maintag; every other job stays on the bare runner, since an image pull costs ~30-40 s a job. The base image carries the venv synced from uv.lock, which its jobs link as.venv(#725). Only main pushes the images, when a Dockerfile or the venv’s inputs (uv.lock, pyproject.toml, .python-version) change and weekly, uncached, before the Monday image scan (#534). No PR builds them (#729): a PR that changes a Dockerfile runs main’s images, and a broken one fails main’sCI Imagesrun, which leaves:mainas it was and files its own issue, labelleddefault branch images failure. just mechruns the Link’s live checks on the Mech stand-in (mech/), in aModelshard.- Checks’ last job,
Deploy, deploys the very artifact itsSitebuilt to GitHub Pages, once the gate passed on main’s push (#295, #310, #795), as GitHub’s Pages starter workflow does: each github-pages Deployment records the commit built and links its run. Default Branch Failure reports a red Checks run.
Licence
Section titled “Licence”noggin is licensed under PolyForm Noncommercial 1.0.0 (LICENSE.md). By contributing you agree that your contribution is licensed under the same terms, with Yellow Pine as the licensor.
Questions: hello@yellowpine.com.
noggin v0.2.26-6-g09bf9b7 · 09bf9b7