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
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- clawkerd/AGENTS.mdAGENTS.md
- controlplane/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- test/AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- agent-filesSkill
- audit-memorySkill
- cli-outputSkill
- firewall-uatSkill
- initiativeSkill
- monitoring-checksSkill
- store-editorSkill
- test-hunterSkill
- wizard-commandsSkill
- writing-testsSkill
- code-reviewSkill
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
- Distinctive: line 8
Run commands from the repository root unless a command specifies another path.
- Distinctive: line 43
Do not bypass Git hooks with flags, environment variables, configuration overrides, or Git plumbing commands.
- Very specific: line 65
All external dependencies pinned to exact versions with integrity verification.
- Very specific: line 83
Add a failing regression test before a bug fix or new behavior.
- Very specific: line 85
Run the affected unit packages with go test, explicit package paths, and -count=1.
- Very specific: line 86
Run make test and golangci-lint run --config .golangci.yml ./....
- Very specific: line 88
Before a commit, check embed availability, then run make pre-commit.
- Distinctive: line 92
Update the README and the relevant package AGENTS.md when their content changes.
- Very specific: line 93
Update the Serena design and architecture memories if the design changes.
- Very specific: line 94
If the command tree or config schema changes, run the gen-docs command, then make docs-check.
- Very specific: line 95
After bug fixes or features, check clawker-plugin/skills/clawker-support/reference/known-issues.md.
- Very specific: line 96
Keep current rules in module memories and retained plan, research, and history records in their own topics.
≈ “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.
Files
dev-checks
Run commands from the repository root unless a command specifies another path.
Commands
| Purpose | Command |
| Build the CLI with existing embeds | go build -o bin/clawker ./cmd/clawker |
| Build all required binary embeds | make clawker (see below; not routine) |
| Unit suite without Docker | make test |
| Focused unit example | go test ./internal/storage/... -count=1 |
| Daemon and agent unit checks | make test-clawkerd |
| Race checks, uncached results, coverage | make test-ci |
| Lint with the repository config | golangci-lint run --config .golangci.yml ./... |
| Install Git hooks (once after clone) | bash scripts/install-hooks.sh |
| Run all hooks | make pre-commit |
| Generate CLI docs and config schemas | go run ./cmd/gen-docs --doc-path docs --markdown --website --schemas |
| Check generated docs | make docs-check |
| Local Mintlify preview | npx mintlify dev --docs-directory docs |
| Check Serena references, if its CLI is installed | serena memories check |
| Whail golden regeneration | GOLDEN_UPDATE=1 go test ./pkg/whail/whailtest/... -run TestSeedRecordedScenarios -v |
Host checks need the host Docker daemon or kernel capabilities:
| Purpose | Command |
| CLI integration tests | make 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 tests | make test-whail (go test ./test/whail/... -v -timeout 5m) |
| Unit plus both integration suites | make test-all (stop live agent containers first, as for make test-e2e) |
| Privileged BPF tests on Linux | make test-bpf |
| Socket server root tests on Linux | make test-root (in the dev container: go test -c, then run the binary in a Docker container) |
- When
CLAWKER_AGENTis set, never rungo test ./...: the e2e suite tears down the host CP. Usemake testor 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 -wand their paths. - Generate mocks with
moqthrough//go:generate; rungo generate ./...from the owning package. Never edit generated mocks. make pre-commitcan 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.
| Context | Pinning requirement | Example |
| Dockerfile base images | SHA256 digest | FROM golang:1.26@sha256:abc... |
| CI workflow actions | SHA commit hash | uses: actions/checkout@a1b2c3d... |
| Pre-commit hooks | SHA commit hash | rev: 83d9cd68... # frozen: v8.30.1 |
| Container images in code | SHA256 digest | DefaultGoBuilderImage = "golang:...@sha256:..." |
| Go tool installs | Exact version or SHA | go 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:
- 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. - Format changed Go files. Regenerate affected moq mocks from their owner package.
- Run the affected unit packages with
go test, explicit package paths, and-count=1. - Run
make testandgolangci-lint run --config .golangci.yml ./.... - 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.
- 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.mdwhen their content changes. Keep eachCLAUDE.mdlink relative. - Update the Serena
designandarchitecturememories if the design changes. Update Mintlify pages indocs/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_maintenancememory. - 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 checkwhen available; otherwise check the local graph and report that limit. - For all changes, run
git diff --checkand inspect the final diff.
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
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.

