# 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= HELM_BRIDGE= 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= 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 --bridge-dir --out ` 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 `//`, 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: 1. Rebase against the latest `origin/main`, implement the changes, and repeat verification. 2. Push the updated feature branch. 3. Append a round with `atgc pr resubmit ` or `atgc stack resubmit`. 4. Update the title, body and any new screenshots with `atgc pr edit `. After a feature is merged: - Fetch `origin/main`. - Confirm the work landed by checking that `git cherry origin/main ` 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.