agentpantry AGENTS.md

Repository Guidance

Go 1.25 single-module CLI (agentpantry) that syncs browser cookies and named secrets from a daily-driver machine (source role) to an agent machine (sink role) over an encrypted byte stream. Single binary, role chosen by subcommand. Default branch is master.

Definition of Done

Before reporting ANY change complete, run this and confirm it passes:

./scripts/verify

It runs make build, go vet ./..., and go test ./... (includes test/ integration tests).

Conditional gates not covered by the script:

• make windows if you touched anything near a _windows.go / _other.go pair (cmd/agentpantry/, internal/wincrypto)
• For security-relevant changes (parsers, framing, filesystem writes, cookie decoding): make gosec, make vuln, and the matching fuzz target, e.g. make fuzz PKG=./internal/transport FUZZ=FuzzOpen. Fuzz targets exist in internal/{transport,surface,wire,vault,wincrypto,policy}.

Report actual command results. If anything fails, quote the failure verbatim and do not claim success. CI additionally runs go test -race ./... on Linux and Windows, golangci-lint, govulncheck, and gosec; do not assume local green covers those.

Code Map

• Entry point: cmd/agentpantry/main.go. All logic under internal/: source, sink, transport (handshake, AES-256-GCM framing, replay counters), cookie, vault/cdpvault/ffvault/wincrypto (per-browser decryption), policy, surface (sink outputs), secret/secretsrc, config, doctor, keyfile, service, state, wire.
• Cross-package integration tests: test/. Copyable configs: examples/. Threat model: docs/threat-model.md.
• make package is the full release gate (test, vet, gosec, vuln, multi-platform build into dist/).

Rules

• Stating a command, flag, or API behavior? Verify it in the code or Makefile first. If you cannot find it, say so. Never invent it.
• Blocked by sandboxing, missing tool, auth, or network? Stop and report the exact blocker and the command that failed. Do not silently work around it or substitute a weaker check.
• A test, fuzz target, lint rule, or CI gate fails? Fix the code. Never weaken, skip, delete, or t.Skip it to get green. If you believe the test itself is wrong, say so and wait for confirmation.
• Touching internal/transport/handshake.go? Keep both salt-direction paths working: --stdio mode inverts who issues the handshake salt (sink sends it over TCP, source sends it over stdio). Add or update tests for both.
• Changing user-facing flow, surfaces, or doctor checks? Update the README claims to match, and bump CHANGELOG.md for releases.
• Staging files? Run git status first. psk.key, config.toml, the root agentpantry binary, dist/, memory/, and .brigade/ are gitignored on purpose. Never commit keys, configs, or runtime state, and never use git add -f on ignored paths.
• Pushing? Never. Do not push unless the user explicitly asks, and never with --no-verify if a pre-push hook exists.