Agent Instructions

Navigation​

• Start here. Read README.md for the Repository Map, then navigate to the specific directory for your task.
• Each internal/ package and major cmd/ have their own README with key types, files, and usage. Read those before touching code.
• Do not load the entire repo. There are 26 packages and 55 CLIs — scope your reads to what you need.
• Detailed docs live in docs/manual/. Package READMEs link there; do not duplicate that content.
• Dependency graph: see docs/manual/dependency-graph.md for which packages import which.
• Phase docs for completed work are in the docs/phases docs area (source files currently follow docs/phases/PHASE*.md naming).

Project Structure​

cmd/           55 CLIs (see cmd/README.md for grouped index)
internal/      26 packages (see internal/README.md for routing table)
migrations/    SQL migrations (000N_description.up.sql / .down.sql)
docs/          Phase plans, manual, operations, examples
deploy/        Kubernetes manifests, monitoring rules
docker/        Docker Compose for local services
scripts/       Ops drills, demos

Conventions​

Types and Naming​

• Types live in types.go per package. Input/Output struct pairs for Temporal activities.
• Interfaces: descriptive nouns or -er suffix (Store, Executor, Embedder).
• Policy structs: XyzPolicy nested in config structs.
• JSON tags on all exported types (Temporal serialization).

Code Patterns​

• Activities: XyzActivity functions registered with Temporal workers.
• Stores: XyzStore interface + PostgresXyzStore implementation.
• Config: pure environment variables with CRUVERO_* prefix — no config files. See docs/manual/config-env.md.
• Migrations: sequential 000N_description.up.sql / .down.sql pairs in migrations/.

Testing​

• Test harness: internal/agenttest — provides DeterministicJSON, MockTool, golden log helpers.
• Run all tests: go test ./...
• Static checks before handoff: go vet ./..., staticcheck ./..., and golangci-lint run ./...
• Coverage quality gate: 80% minimum per package (enforced by CI with coverage-thresholds.json and scripts/check-coverage.sh).
• Run coverage gate locally: ./scripts/check-coverage.sh
• For UI/frontend changes, keep Vitest coverage thresholds at or above 80%.
• Security tests: go test -tags security ./internal/security/...
• Host sandbox tests (opt-in): CRUVERO_RUN_HOST_SANDBOX_TESTS=true go test -tags 'security integration' ./internal/security -run Host

Commits​

• Branch from dev, open PRs against main.
• Conventional commit format: feat(package): description, fix(package): description, docs: description.
• Never include Co-authored-by trailers for AI/LLM assistants.

Working Session Notes​

• Save working notes in docs/notes/ so context is recoverable after interruptions.
• After each logical piece of work, add/update:
  • docs/notes/sessions/YYYY-MM-DD-topic.md
  • docs/notes/work-log.md
  • docs/phases/INDEX.MD (link the new session note)
• Keep session notes short and decision-focused: objective, files touched, decisions, follow-ups.

Key Entry Points by Task​

Common Pitfalls​

• Temporal determinism: Workflow code (workflow.go) must be deterministic — no I/O, no randomness, no time.Now(). All side effects go in activities.
• Registry immutability: Tool registries are content-hashed and immutable once created. To change tools, create a new registry version.
• Migration numbering: Check migrations/ for the latest number before creating a new migration. Do not reuse or skip numbers.
• JSON tags: Every exported struct field used in Temporal serialization needs a json:"..." tag. Missing tags cause silent serialization failures.
• Config loading: All config is via env vars. The config.Load() function reads them at startup. Do not introduce config files.
• Test isolation: Tests using Postgres need the test database. Use agenttest harness for deterministic workflow tests.