Home / Docs / Contribute through a verified workbench

Contributor guide

Contribute through a verified workbench

Build without installing, preserve concurrent work and land evidence-backed changes.

Pre-release. Reviewed October 23, 2026. This review covers code behavior, not a packaged release or provider certification.

Repository access and prerequisites

The public repository decision remains separate. These instructions are for an authorized checkout; no unavailable clone URL is offered. Use the Go toolchain pinned in go.mod. Native app work also needs the selected Xcode toolchain and the repository's menubar/swiftpm.sh wrapper.

Run non-installing checks first

make build
./commandem version
./commandem --help
go test ./...
go vet ./...

These compile and test local source. For a separately coordinated standard app install, COMMANDEM_SWIFT_JOBS=2 ./menubar/build.sh release install requests two SwiftPM jobs without a separate prebuild. Unset or empty keeps the default; the option does not bound frontend-internal WMO threads. make install and app release-install commands change shared artifacts; coordinate them separately. Some tests are platform-specific; report skips and failures explicitly.

Normal landing can invoke the repository’s post-merge hooks and update shared artifacts. The Go hook path uses make install-native for this machine; a separately coordinated make install remains the Universal distribution build. Both refuse a linked worktree by default. A passing source check is not proof that either install ran.

Isolate concurrent changes

  1. Read AGENTS.md and canonical CLAUDE.md.
  2. Inspect commandem workbench ls PROJECT. When another session may be active, create/use your durable workbench.
  3. Make one coherent change with regression evidence. Keep the roadmap current in that workbench's project alias.
  4. Run mandatory hooks and land each verified slice. Never bypass a gate or stash another agent's changes to save time.

Explain the causal chain

Record trigger, evidence, named mechanism, change, measured effect and confidence. Preserve failed controls and incomplete acceptance. Public contributions use the approved review process; existing CI is pull-request/manual, not a promise that every push ran a server gate.

Recipes, plugins and adapters

Recipes render prompts, plugins execute code and skills supply instructions. Start with the catalog and review their distinct permissions. A new adapter must explain unavailable/degraded capabilities, identity, retries and receipts before claiming two-way integration.

Never publish private code, credentials or research artifacts without explicit approval. See private security reporting.