agentleFS
schmitthubschmitthub/clawker/.agents/skills/dev-checks/SKILL.md

dev-checks

Skill59 starsChanged 12 days agoMITView on GitHub

Use when building clawker, running unit or integration tests, changing dependencies or pins, regenerating docs, mocks, or embeds, installing hooks, or completing work.

  • Installs packages

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 3 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run commands from the repository root unless a command specifies another path.

    line 8
  2. Distinctive:

    Do not bypass Git hooks with flags, environment variables, configuration overrides, or Git plumbing commands.

    line 43
  3. Very specific:

    All external dependencies pinned to exact versions with integrity verification.

    line 65
  4. Very specific:

    Add a failing regression test before a bug fix or new behavior.

    line 83
  5. Very specific:

    Run the affected unit packages with go test, explicit package paths, and -count=1.

    line 85
  6. Very specific:

    Run make test and golangci-lint run --config .golangci.yml ./....

    line 86
  7. Very specific:

    Before a commit, check embed availability, then run make pre-commit.

    line 88
  8. Distinctive:

    Update the README and the relevant package AGENTS.md when their content changes.

    line 92
  9. Very specific:

    Update the Serena design and architecture memories if the design changes.

    line 93
  10. Very specific:

    If the command tree or config schema changes, run the gen-docs command, then make docs-check.

    line 94
  11. Very specific:

    After bug fixes or features, check clawker-plugin/skills/clawker-support/reference/known-issues.md.

    line 95
  12. Very specific:

    Keep current rules in module memories and retained plan, research, and history records in their own topics.

    line 96

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

dev-checks

Run commands from the repository root unless a command specifies another path.

Commands

PurposeCommand
Build the CLI with existing embedsgo build -o bin/clawker ./cmd/clawker
Build all required binary embedsmake clawker (see below; not routine)
Unit suite without Dockermake test
Focused unit examplego test ./internal/storage/... -count=1
Daemon and agent unit checksmake test-clawkerd
Race checks, uncached results, coveragemake test-ci
Lint with the repository configgolangci-lint run --config .golangci.yml ./...
Install Git hooks (once after clone)bash scripts/install-hooks.sh
Run all hooksmake pre-commit
Generate CLI docs and config schemasgo run ./cmd/gen-docs --doc-path docs --markdown --website --schemas
Check generated docsmake docs-check
Local Mintlify previewnpx mintlify dev --docs-directory docs
Check Serena references, if its CLI is installedserena memories check
Whail golden regenerationGOLDEN_UPDATE=1 go test ./pkg/whail/whailtest/... -run TestSeedRecordedScenarios -v

Host checks need the host Docker daemon or kernel capabilities:

PurposeCommand
CLI integration testsmake test-e2e (go test ./test/e2e/... -v -timeout 10m). Stop live agent containers first: the harness refuses to run while they exist.
Docker/BuildKit integration testsmake test-whail (go test ./test/whail/... -v -timeout 5m)
Unit plus both integration suitesmake test-all (stop live agent containers first, as for make test-e2e)
Privileged BPF tests on Linuxmake test-bpf
Socket server root tests on Linuxmake test-root (in the dev container: go test -c, then run the binary in a Docker container)
  • When CLAWKER_AGENT is set, never run go test ./...: the e2e suite tears down the host CP. Use make test or explicit unit package paths. The same applies to targets that pass ./... to the test runner: test-coverage, clawker-test-coverage, clawker-test-short. Report host checks as pending until results exist.
  • Format changed Go files with gofmt -w and their paths.
  • Generate mocks with moq through //go:generate; run go generate ./... from the owning package. Never edit generated mocks.
  • make pre-commit can change module and license files. Review its diff.
  • Do not bypass Git hooks with flags, environment variables, configuration overrides, or Git plumbing commands.

make clawker — only when embeds are missing

make clawker builds the //go:embed binaries the prek go-test hook needs. It is slow and fills build caches — never run it reflexively before a commit. make test (and so make pre-commit, whose prek go-test hook runs make test) builds missing embed binaries itself through its prerequisite targets. Check first; build only if a binary is missing:

ls clawkerd/embed/assets/clawkerd \
   controlplane/manager/assets/clawkercp \
   controlplane/manager/assets/ebpf-manager \
   controlplane/manager/assets/bpffs-delegate \
   controlplane/firewall/assets/coredns-clawker \
   internal/cmd/container/shared/assets/idmap-mount \
  || make clawker

(Paths are the Makefile's CLAWKERD_BINARY/CP_BINARY/EBPF_BINARY/BPFFS_DELEGATE_BINARY/COREDNS_BINARY/IDMAP_MOUNT_BINARY vars — check there if this list drifts.)

Embeds persist for the container's lifetime — they are only absent in a fresh container. Editing Go source does not invalidate them for hook purposes.

Security: Version Pinning

All external dependencies pinned to exact versions with integrity verification. Never use @latest or floating tags.

ContextPinning requirementExample
Dockerfile base imagesSHA256 digestFROM golang:1.26@sha256:abc...
CI workflow actionsSHA commit hashuses: actions/checkout@a1b2c3d...
Pre-commit hooksSHA commit hashrev: 83d9cd68... # frozen: v8.30.1
Container images in codeSHA256 digestDefaultGoBuilderImage = "golang:...@sha256:..."
Go tool installsExact version or SHAgo install tool@v2.0.1

All @sha256: pins must be multi-arch manifest lists (application/vnd.oci.image.index.v1+json). Verify with docker buildx imagetools inspect. Firewall stack binaries are built fresh from pinned BPF toolchain inputs — BPF_APT_DEPS in the Makefile pins clang/llvm/libbpf-dev/linux-libc-dev versions; CI runs sudo make bpf-deps on its pinned Ubuntu runner (see .github/workflows/), while Dockerfile.controlplane provides the same path for macOS devs. Nothing generated is committed.

Completion checks

Select checks from the changed behavior. Record the commands, results, and any checks that remain unavailable.

Code changes:

  1. Add a failing regression test before a bug fix or new behavior. Use the responsible package and observable result. Put integration tests in test/*/. Test helpers: .agents/skills/writing-tests/SKILL.md.
  2. Format changed Go files. Regenerate affected moq mocks from their owner package.
  3. Run the affected unit packages with go test, explicit package paths, and -count=1.
  4. Run make test and golangci-lint run --config .golangci.yml ./....
  5. For Docker behavior, complete the relevant host integration checks. For BPF behavior, include the privileged host checks. Unit success does not prove live container behavior.
  6. Before a commit, check embed availability, then run make pre-commit. Review any files changed by hooks.

Documentation and records:

  • Update the README and the relevant package AGENTS.md when their content changes. Keep each CLAUDE.md link relative.
  • Update the Serena design and architecture memories if the design changes. Update Mintlify pages in docs/ for user-facing behavior; see docs/AGENTS.md. Generated CLI reference pages are never edited by hand.
  • If the command tree or config schema changes, run the gen-docs command, then make docs-check.
  • After bug fixes or features, check clawker-plugin/skills/clawker-support/reference/known-issues.md. Fixes there are committed in the clawker-plugin submodule, then the submodule pointer is bumped here.
  • Keep current rules in module memories and retained plan, research, and history records in their own topics; follow the Serena memory_maintenance memory.
  • For agent instruction and memory changes, check files and formats only. Do not run application tests, install or run Claude Code, or make model API calls. The commit hook and the PR lint workflow run the agent layout check; do not run it by hand. Run serena memories check when available; otherwise check the local graph and report that limit.
  • For all changes, run git diff --check and inspect the final diff.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.