Agent Guidelines

Spec-First Workflow

• Read specs/README.md before any feature work.
• Assume specs describe intent, not implementation.
• Verify reality in the codebase before claiming something exists.
• Implement to spec patterns and data shapes; update specs only when asked.
• When Writting specs, NEVER follow Test Driven Development practices. Write the spec first and stop.
• For programming tasks, always load Test Driven Development skill.

Testing and Quality Gates

• Follow Test Driven Development practices: write failing tests before implementation.
• Local suite: make quality.
• Targeted runs:
  • make lint|test|test-e2e|test-race|coverage|mutation|security|arch.
• Coverage gate: min 90%.
• Run the full Go test suite with make test (includes test/e2e).
• Run only the end-to-end tests with make test-e2e.
• Execute mutation testing with make mutation ONLY in final stages of the task development. NEVER execute mutation testing during the Test Driven Development process.

Build and Run

• Build the CLI binary: make build.
• Run from source (no build): make run ARGS='<command> [flags]'.
• Get help for available targets: make help.

Tooling Expectations

• Go version: 1.25 (see go.mod).
• Mutation testing tool: gremlins.
• Lint and security via golangci-lint, govulncheck, go-sec, go-arch-lint, go-fmt.

Implementation Guidance

• Keep scans deterministic and reproducible.
• Skip binary/oversized files per spec; record skipped file stats.
• Treat match text as sensitive; avoid logging it in console.
• When multiple code paths do similar work with small variations, consolidate into shared services with request structs.