From 9f2596f03d75aa9fe406d34c50dbf5d5a5b386ee Mon Sep 17 00:00:00 2001 From: lpsm-dev Date: Thu, 16 Jul 2026 17:40:55 -0300 Subject: [PATCH] docs: add llms.txt, AGENTS.md and CLAUDE.md - AGENTS.md: machine-facing contributor guide (layout, build/test/lint commands, hard constraints: CC<=10, github-slugger anchors, v2 module path caveat, conventional commits, definition of done) - CLAUDE.md: imports AGENTS.md via @AGENTS.md plus Claude-specific notes - llms.txt: llmstxt.org-format project summary with command reference and links to docs and source Co-Authored-By: Claude --- AGENTS.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 20 +++++++++++++ llms.txt | 52 ++++++++++++++++++++++++++++++++++ 3 files changed, 157 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 llms.txt diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0327a70 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,85 @@ +# AGENTS.md + +Guidance for AI coding agents working in this repository. Human contributors +should read [CONTRIBUTING.md](CONTRIBUTING.md); this file is the machine-facing +counterpart. + +## What this project is + +`gtoc` is a single-binary CLI, written in Go, that generates and maintains a +table of contents in Markdown files. It reads the headings of a file, builds a +hierarchical index with GitHub-compatible anchors, and writes it back between +HTML markers — idempotently. + +Module path: `github.com/lpsm-dev/gtoc`. + +## Layout + +| Path | Responsibility | +| ------------------------ | ------------------------------------------------------------- | +| `main.go` | Entry point; delegates to `cmd.Execute`. | +| `cmd/` | Cobra commands: `generate`, `analyze`, `upgrade`, `version`. | +| `internal/generator/` | Heading extraction, anchor slugging, TOC assembly and file update. Pure, well-tested core. | +| `internal/logger/` | Thin wrapper over `charm.land/log/v2`. | +| `.github/workflows/` | CI (`ci.yaml`), release (`goreleaser.yaml`, `_release.yaml`). | + +The `generate` command enumerates headings into a TOC; the `analyze` command +adds README best-practice markers and a "back to top" link at the end of each +top-level (`#`) section. The `upgrade` command self-updates from GitHub +releases. + +## Build, test, lint + +The project uses [Task](https://taskfile.dev) and [Devbox](https://www.jetify.com/devbox), +but plain `go` works everywhere. Prefer the raw commands in automation: + +```bash +go build ./... # or: task go:build +go test ./... # or: task go:test +go vet ./... # or: task go:vet +gofmt -l cmd internal # must print nothing +golangci-lint run ./... # or: task go:lint +``` + +`task go:all` runs fmt, vet, lint, test and build in sequence. + +## Non-negotiable rules + +- **Cyclomatic complexity ≤ 10 per function.** Enforced by `golangci-lint` + (`gocyclo`, `min-complexity: 10` in `.golangci.yml`). New code must comply; + do not raise the threshold. +- **Functions ≤ 100 lines**, prefer small single-purpose helpers. +- **All code, comments and identifiers in English.** +- **`gofmt`-clean, `go vet`-clean, zero linter warnings.** +- **Tests must stay green** (`go test ./...`) and new behavior needs new tests. + The `internal/generator` package is the core — keep its coverage high. +- **No unnecessary dependencies.** The core uses only the standard library. +- **Anchors follow GitHub's github-slugger algorithm**: preserve Unicode + letters/accents, do not collapse consecutive hyphens, and suffix duplicate + slugs with `-1`, `-2`, … Changing this breaks existing anchors — add a test + first. +- **Go module major bumps (v2+) are not routine.** Charm modules relocate their + import path on major versions (e.g. `charm.land/glamour/v2`), so a bare + `go.mod` bump breaks the build. Update the import sites and verify a full + build before merging. + +## Commits and releases + +- **Conventional Commits**: `type(scope): description`, lowercase, imperative, + no trailing period. Types: `feat`, `fix`, `refactor`, `docs`, `test`, + `chore`, `ci`, `perf`. Breaking changes use `feat!:` or a `BREAKING CHANGE:` + footer. +- Keep commits small and single-concern. +- Releases are driven by `semantic-release` and GoReleaser off `main`; never + hand-edit the changelog. + +## Definition of done + +Before proposing a change as complete, confirm locally: + +1. `go build ./...` succeeds. +2. `go test ./...` passes. +3. `go vet ./...` and `gofmt -l cmd internal` are clean. +4. `golangci-lint run ./...` reports no issues (complexity included). +5. If the change affects TOC output, regenerate this repo's `README.md` with + the built binary to confirm behavior end to end. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..73f4b09 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,20 @@ +# CLAUDE.md + +This file guides Claude Code (and other Claude-based agents) when working in +this repository. The full, tool-agnostic contribution guidance lives in +[AGENTS.md](AGENTS.md); this file imports it so both stay in sync. + +@AGENTS.md + +## Claude-specific notes + +- Treat the rules in `AGENTS.md` as hard constraints, not suggestions — in + particular the cyclomatic-complexity ≤ 10 guardrail and the GitHub-compatible + anchor algorithm. +- Prefer editing `internal/generator` behavior behind its existing tests: change + a test to describe the new behavior first, then make it pass. +- After any change that affects TOC output, dogfood it: build the binary and run + `gtoc generate README.md` to verify the real result, not just unit tests. +- When touching dependencies, remember Go v2+ modules may move their import path + (e.g. `charm.land/glamour/v2`, `charm.land/log/v2`); update imports and run a + full `go build ./...` before concluding. diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..4262afa --- /dev/null +++ b/llms.txt @@ -0,0 +1,52 @@ +# gtoc + +> gtoc is a single-binary Go CLI that generates and maintains a table of +> contents in Markdown files. It reads a file's headings, builds a hierarchical +> index with GitHub-compatible anchors (Unicode/accents preserved, duplicate +> headings suffixed `-1`, `-2`, …), and writes it back between HTML markers, +> idempotently. + +The tool targets README and documentation upkeep: instead of maintaining a +table of contents by hand, `gtoc generate ` rebuilds it from the actual +headings. A companion `gtoc analyze` command adds README best-practice markers +and a "back to top" link at the end of every top-level section, and +`gtoc upgrade` self-updates the binary from GitHub releases. + +Module path: `github.com/lpsm-dev/gtoc`. Language: Go (1.25+). License: see +[LICENSE](LICENSE). + +## Commands + +- `generate [file]`: rebuild the TOC for a Markdown file. Flags: `--file`, + `--depth` (max heading level, 0 = unlimited), `--exclude` (comma-separated + heading texts, case-insensitive substring), `--dry-run`, `--pretty`. +- `analyze`: add `BEGIN_DOCS`/`END_DOCS` markers, a `readme-top` anchor, and a + "back to top" link after each `#` section. Flag: `--file` (default + `README.md`). +- `upgrade`: download and install the latest GitHub release for the current + OS/arch, verifying the published SHA-256 checksum. Flags: `--force`, + `--endpoint`. +- `version`: print the binary version and Go/OS/arch build info. + +## Documentation + +- [README.md](README.md): overview, installation and usage (Portuguese). +- [README_en.md](README_en.md): the same, in English. +- [CONTRIBUTING.md](CONTRIBUTING.md): human contributor guide. +- [AGENTS.md](AGENTS.md): guidance and hard constraints for AI coding agents. + +## Source + +- [main.go](main.go): entry point. +- [cmd/](cmd): Cobra command definitions (`generate`, `analyze`, `upgrade`, `version`). +- [internal/generator/generator.go](internal/generator/generator.go): heading + extraction, GitHub-compatible anchor slugging, and TOC assembly — the core + logic, and the best starting point for understanding the tool. +- [internal/logger/logger.go](internal/logger/logger.go): logging wrapper. + +## Conventions + +- Conventional Commits; releases via semantic-release and GoReleaser off `main`. +- Cyclomatic complexity ≤ 10 per function, enforced by golangci-lint (gocyclo). +- Standard-library-only core; GitHub-compatible anchors must not change without + a test.