endandClaude Opus 5.5
0034a561ba
go install names binaries after the directory, so cmd/docs installed an ambiguous `docs` binary into $GOBIN that could clobber or be clobbered by other tools. Move it to cmd/corestack-docs, matching corestack-goose, and update goreleaser, CI, docs and usage text. Accepted ADRs keep their text and gain a dated rename note. BREAKING CHANGE: `go install go.auvem.com/corestack/cmd/docs@latest` stops resolving after the next tag; use cmd/corestack-docs. @v0.1.0 still installs the old `docs` binary. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
52 lines
4.4 KiB
Markdown
52 lines
4.4 KiB
Markdown
# AGENTS.md
|
|
|
|
## Commands
|
|
- Check: `go build ./...`, `go vet ./...`, `go test -race ./...`, `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run ./...`; from the project root, run the TODO check below.
|
|
- Generate: No code generation is configured; format with `gofmt -w .`.
|
|
- Documentation: `go run ./cmd/corestack-docs check`; create records with `go run ./cmd/corestack-docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth.
|
|
|
|
## Scope and decisions
|
|
- Before editing under a directory with its own AGENTS.md, read it. Scoped files: none currently; this root governs the repository, including nested Go modules unless nearer instructions override it.
|
|
- Explicit user instructions win; nearer scoped rules override broader rules.
|
|
- Distinguish confirmed requirements, proposed defaults and unresolved decisions; resolve material ambiguity before dependent work.
|
|
- Proposed ADRs are context, not authority; read relevant accepted decisions before changing their scope.
|
|
- Before final review and merge, reconcile affected records against the latest target branch plus the PR, following [/docs/adr/README.md](/docs/adr/README.md).
|
|
- Documentation tier: ADRs only. Create a plan only when work needs durable execution context across areas, phases or sessions; then enable the plans tier.
|
|
- In a sandbox, request required network/cache access before first codegen; on permission/cache errors retry once with that access. Never hand-edit generated output.
|
|
- Shared databases and ports may belong to other worktrees/agents; read project rules before starting, stopping or resetting them.
|
|
- Ask before lint/autofix changes that could alter runtime behavior.
|
|
- Report commands actually run and their results; never claim an unrun check passed.
|
|
- Name branches `<type>/<kebab>` without agent-name prefixes.
|
|
|
|
## Comments
|
|
- Document package/module purpose, ownership and boundaries, and every public/exported contract in native doc comments; document generated surfaces at their source.
|
|
- Explain why at invariants, auth decisions, concurrency/ordering, destructive edges and deliberate deviations; no narration, changelog comments or commented-out code.
|
|
- Use `invariant: <property>`, `authz: <who and enforcement>`, `shortcut: <limit>, <when to upgrade>` on relevant code; retain Go `Deprecated:` and Rust `// SAFETY:`.
|
|
- Every TODO needs an issue URL; reviewers recheck tagged comments on touched code.
|
|
|
|
## Project map
|
|
|
|
Go module `go.auvem.com/corestack`.
|
|
|
|
- Docs format (the spec `corestack-docs check` implements): `docs/docs-format.md`.
|
|
- Decisions live in `docs/adr/`, plans in `docs/plans/`. Records are permanent; never rename them.
|
|
- Add dependencies only to the module that needs them; heavy dependencies go in nested modules (see the [module-boundary ADR](/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md)).
|
|
|
|
## Go
|
|
- Default backend language is Go; follow existing package boundaries.
|
|
- Define interfaces at the consumer only when a second implementation or a test seam needs one.
|
|
- Wrap contextual errors with `%w`; inspect causes with `errors.Is`/`errors.As`.
|
|
- Do not add package-level mutable state or `init` side effects.
|
|
- Put `context.Context` first in parameters; never store it in a struct.
|
|
- Give every goroutine an owner and a shutdown path.
|
|
- Run `gofmt`, `go vet ./...`, tests and the project's configured linter from the owning module.
|
|
- Use `.golangci.yml` (revive exported/package-comments); the pinned linter command is listed above.
|
|
|
|
## TODO check
|
|
|
|
Run from the project root (also enforced in CI):
|
|
|
|
```sh
|
|
find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
|
|
```
|