proto-fleet

Use when adding, fixing, or reviewing Playwright E2E coverage in the block/proto-fleet monorepo, especially after a feature is already implemented. Covers scenario design, spec and page-object changes, local env-aware verification, simulator-safe cleanup, and follow-up on E2E PR comments or CI failures.

Use when editing files under `plugin/asicrs/`, `sdk/rust/`, or `server/sdk/v1/pb/` (which the asicrs build also consumes). The ASIC-rs plugin is a Rust binary built via Docker and cached against an `.asicrs-platform` marker; source changes that bypass `just _asicrs-build` or `just rebuild-plugin asicrs` will leave the loaded plugin stale.

Use when editing `buf.yaml`, `buf.lock`, or any `buf.gen.yaml` (root, server, or SDK). Generator plugin versions in `buf.gen.yaml` are tightly coupled to the generated code consumers (Connect-RPC client, sqlc, SDK shapes); a version bump can produce a large unrelated diff and break downstream code that relies on specific output shapes.

Use when editing files under `client/src/shared/`, `client/src/protoOS/`, or `client/src/protoFleet/`. Enforces app-import boundaries (`shared/` cannot import apps; `protoOS` and `protoFleet` cannot import each other) and the no-new-`console.log` rule (`console.error` and the existing build-version logger are fine).

Use when editing `server/sqlc/queries/**/*.sql`, `server/sqlc.yaml`, or creating a new `server/migrations/*.sql` file. sqlc query and schema source changes require running `just gen` so `server/generated/sqlc/` stays in sync. Edits to *existing* migration files are owned by the `migration-immutability` skill instead.

Use when editing `server/docker-compose.yaml` or `server/docker-compose.base.yaml`, or when troubleshooting a `just dev` startup. Proto Fleet requires Docker host networking on macOS/Windows; service definitions split between `base` (shared) and the runtime override file.

Use when editing `server/fake-antminer/` or `server/fake-proto-rig/`. These are test doubles consumed by `tests/plugin-contract/`, the E2E suites, and the local `just dev` stack — behavior changes here ripple silently into all three surfaces.

Use when editing any `go.mod` or `go.sum` under `server/`, `plugin/`, or `tests/`, or when modifying root `go.work` / `go.work.sum`. Module dependency changes require running `go work sync` from the repo root so workspace lock data stays consistent.

Use when a shell command in this repo fails with "command not found" for `just`, `buf`, `golangci-lint`, `goimports`, `lefthook`, `ruff`, or any other developer tool. The repo pins its toolchain via Hermit (`.hermit/`); the tools exist on disk but only resolve after the Hermit environment is activated.

Use when about to run `git commit --no-verify`, `git commit -n`, `git push --no-verify`, or any command that bypasses the `lefthook` hooks configured in `lefthook.yml`. Pre-commit hooks (formatting, lint, ruff, buf-lint) and pre-push hooks (typecheck, golangci-lint) catch real problems; bypassing them shifts the failure to CI and produces noisier PRs.

Use when modifying an existing `server/migrations/*.sql` file already on `main`. Deployed migrations are immutable — `golang-migrate` skips already-applied versions, so editing one in place silently desyncs schemas across environments. Corrective changes must go in a new migration.

Use when editing or creating files under `docs/plans/` (TDDs, PRDs, lightweight plans). Enforces frontmatter (`title`, `date`, `status`, `type`) and the `draft → proposed → accepted → implementing → completed | cancelled` status lifecycle.

Use when editing miner-protocol code under `plugin/proto/`, `plugin/antminer/`, or `plugin/virtual/`, or when changing test fixtures consumed by `tests/plugin-contract/`. The contract suite is the canonical check that a plugin still meets the miner driver contract; it is Docker-heavy and easy to skip, but plugin behavior regressions only surface here.

Use when editing any `.proto` file under `proto/` or `server/sdk/v1/pb/`, or modifying root/server `buf.yaml`, `buf.gen.yaml`, or `buf.lock`. Protobuf changes require regenerating Go, TypeScript, and SDK code via `just gen`; without it, server handlers, client API hooks, SDK consumers, and plugins compile against stale shapes.

Use whenever the user changes any source under `packages/proto-python-gen/` (Python source, `setup.sh`, `requirements.txt`, `bin/`) or edits `scripts/pip-config.sh` (which gets bundled). The Python proto generator ships as a versioned tarball that Hermit consumes; if source changes but the tarball isn't rebuilt and committed, downstream consumers silently use the stale generator.