helm #

Using atgc #

When doing repo operations, always use the global install of atgc. atgc agent is compiled into the binary and provides an up-to-date view of the current version's capabilities.

Building in a worktree #

A fresh worktree has no target/, so its first build compiles the whole dependency tree before it can run a single test — and rusqlite builds a bundled libsqlite3, which is C and takes minutes on its own. Several agents doing that at once is what puts this machine under load.

Always -j 2. A full-parallel build has taken this machine down.
A worktree keeps its target/ after the branch merges and these run to gigabytes — this one reached 3.8GB beside the main checkout's 2.2GB. Remove the worktree when the branch lands, not just the branch.

Running the tests #

Most of the suite is ordinary cargo test. Three things are not:

The conformance and oracle tests are #[ignore]d and need a MegaMek install and a bridge dump: HELM_MEGAMEK=<install> HELM_BRIDGE=<dump> cargo test -p helm-bv --test conformance -- --ignored. HELM_BV_BLESS=1 re-records conformance.txt, and a commit that moves a figure should say why.
tests/performance.rs is release only — an unoptimised build has a different shape, not just a different speed, and is printed rather than checked. HELM_PERF_BLESS=1 re-records performance.txt.
tests/mekset_install.rs in helm-unitfile resolves every design against a real release's own art: HELM_MEGAMEK=<install> cargo test -p helm-unitfile -- --ignored. It is the check that says a bucket sync of the art tree is complete, so run it when the pinned MegaMek moves.
crates/helm-wasm/smoke.mjs drives the wasm boundary from Node, which is the only thing that exercises the interface a browser calls through. Build the module first: cargo build -p helm-wasm --target wasm32-unknown-unknown --release.
crates/helm-wasm/wire.mjs is the same boundary over the whole library rather than one design: helm wire-check --megamek <dir> --bridge-dir <dir> --out <bundle> writes what a page would be handed and what this build says the answers are, and the script scores every design twice - fresh and damaged - and fails on any disagreement. About 40 seconds to build the bundle and 8 to check it.

Never read test fixtures out of a MegaMek install's logs/ directory. That is MegaMek's own scratch, rewritten by anything that starts it — including bridge/dump.sh — so a case covered today can vanish tomorrow with nothing in this repository changing.

Deploying #

scripts/deploy.sh builds the wasm, the index and the catalogue and puts them in the assets bucket under <ref>/<megamek>/, then writes releases.helm in infra. It applies nothing — the apply is infra's, and jmm runs it.

A prefix is written once. Never overwrite one, and never reach for a CloudFront invalidation: a rebuild is a new ref, which is what makes the immutable cache header true.
The index and the catalogue need a bridge dump, so they need Docker. scripts/fetch-megamek.sh gets the release; bridge/dump.sh gets the dump.
A dump from anywhere else is not interchangeable. ~/.cache/mul-build holds one from a different dumper whose catalogue is missing flags the rules read: battle value conformance against it is 29.6% rather than 99.0%, and helm force under-scores an Atlas by 122 points. If a figure looks wrong, check which dump produced it before reading the arithmetic.

Feature branch workflow #

If asked to do work, unless directly instructed otherwise, do not make changes to the user's top-level git checkout. All of your work will be on feature branches and inside git worktrees.

To start work on a feature branch:

Run git fetch origin main
Create the branch and its worktree: git worktree add -b claude/short-feature-name .claude/worktrees/short-feature-name origin/main
Enter the worktree so that all commands run inside of it
Double check that the repo-local .git/config [user] section has an ATProto @- handle as a name and its did:plc as an email. If it does not, run atgc repo configure

While doing work, be a good neighbor to humans and agents on your machine:

Do not restart, reload, or otherwise modify the configuration of shared services.
If you need temporary folders or other artifacts that exist outside your worktree (such as Docker images), reduce conflicts by tagging them with your current branch and/or SHA.
Check available system resources before running expensive commands (memory or CPU).

Make sure your work includes a "maintenance budget" for code directly related to your current feature:

Reducing duplicated or dead code
Adding new debug log lines and similar observability
Updating documentation pages or test suites
Checking off completed issues in TODO.md

Structure your commits for human review:

Break work into logical commits, typically 1-5 for an average feature.
Use Conventional Commits, including adding "!" indicators for breaking behavior changes.
Don't write more than 1 short sentence + 1 short paragraph into a commit body.

Confirm your work is acceptable before submitting a PR:

Run git fetch origin main, rebase onto it, and fix any conflicts
Ensure that all prek feedback has been fixed
Run the tests your change affects, and confirm they pass

When writing any PRs, updates to PRs, or comments on PRs:

The PR title should be simple and descriptive, and should use Conventional Commits.
The PR body should be three paragraphs at most. Focus on a concise, descriptive explanation of what changed. Avoid commentary on implementation details or future work.
The PR body should contain a before/after screenshot if the change has a visible effect (UI, rendered output, a CLI's printed text). Attach this with Markdown image syntax and a local image path: the atgc commands will upload it for you. The file does not need to be committed anywhere, and each image must be under 1 MB or the command refuses it before sending anything.

When your work is ready for review, you must create a pull request. Do not report your work as "done" until you:

Push the feature branch to the origin.
If the branch is one reviewable change, submit it via atgc pr create
If the branch holds several logically separate changes, or changes that must land in a given order, use atgc stack create instead. It opens one PR per change, each with its own screenshots. atgc stack resubmit reconciles the chain after any rebase, amend or reorder.
Post the Tangled PR link for the user to review.

When review feedback arrives, submit a new round of work. Follow these steps for each round:

Rebase against the latest origin/main, implement the changes, and repeat verification.
Push the updated feature branch.
Append a round with atgc pr resubmit <pr> or atgc stack resubmit.
Update the title, body and any new screenshots with atgc pr edit <pr>.

After a feature is merged:

Fetch origin/main.
Confirm the work landed by checking that git cherry origin/main <branch> prints no + lines.
Clean up your own worktree.
Delete both the local and the remote feature branch, passing -D to account for the patch-based workflow.
Leave any temporary artifacts (like Docker images). Another agent may be using them, and they are a shared cache.