sherlock/docs/conventions.md

Conventions

Rules that govern this repo. Anything that becomes load-bearing belongs here, in conventions.md, never in a section appended to another doc.

Repository layout

cmd/                    one subdir per shippable binary; package main only
internal/               every other package; never imported outside this module
internal/agent/profiles built-in TOML profiles, embedded with //go:embed
docs/                   one topic per file (see "Docs" below)
plan.md                 the long-form design doc; source-of-truth for phasing
README.md               TOC only

No top-level pkg/ until we have an external consumer.

Go

• Module path: gitea.alexandru.macocian.me/Charlie/sherlock.
• Target Go toolchain: go 1.23 (pin via go.mod's go directive).
• One package main per cmd/<binary>/. No multiple-main-files trickery.
• Every other package has a top-of-file Package <name> ... doc comment in doc.go.
• No third-party deps in Phase 0. Phase 1+ deps must be added with a one-line justification in the PR description.

Docs

• README.md is TOC only. One-line description + a bulleted index of docs/*.md.
• One topic per file under docs/. Never append a new section to an existing doc to cover a new concern; create docs/<new-topic>.md and link it from README.md.
• plan.md is the long-form design + phasing doc. It is allowed to be long.
• Cross-link aggressively: every doc should link to the other docs whose concerns it touches.
• ASCII diagrams over images. Diagrams live next to the prose that explains them.

Naming

• Binaries are kebab-case (sherlock-broker, gitea-mcp).
• Built-in agent profiles match the agent's canonical CLI name (copilot, claude, aider).
• Service registry files match the service's canonical name (gitea.toml, grafana.toml).
• Env vars are <SERVICE>_TOKEN (e.g. GITEA_TOKEN, GSSH_TOKEN).

Extensibility invariants

• Agent extensibility: adding a new agent CLI MUST be a TOML drop-in under ~/.config/sherlock/agents.d/. If a code change is required, the design has drifted — fix the abstraction in internal/agent/, don't accept the code change.
• Service extensibility: adding a new downstream service MUST be a TOML drop-in under ~/.config/sherlock/services.d/ + (optionally) a new cmd/<service>-mcp/ binary. The broker itself does not learn about individual services in Go code.

Commits

• Conventional-ish: area: short imperative (e.g. broker: persist tokens with age, docs: add gssh-integration).
• One logical change per commit. CI must pass on every commit on main.

CI

• .gitea/workflows/ci.yaml runs on every push + PR. It runs go vet, go test -race, go build. No other gates.
• No deploy pipeline — sherlock is operator-installed via go install. Release artifacts (binaries to the gitea registry / releases) land in Phase 5 if at all.

Security

• No secrets in this repo, ever. Not in tests, not in fixtures, not in comments.
• The operator's per-service credentials live in ~/.config/sherlock/, encrypted at rest. Mechanism is decided at the start of Phase 1; this doc will gain a link to the new docs/storage.md then.