agentleFS
Sign inStart free
alnahalnah/go-md2pdf/AGENTS.md

go-md2pdf

AGENTS.md87 starsChanged 8 months agoBSD-3-ClauseView on GitHub

Picoloom is a Go library and CLI for Markdown-to-PDF conversion. Keep boundaries stable: Useful commands: Run the safest relevant checks for the change. Prefer non-mutating checks first. Common checks:

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

22 rules. About 0 are common, 17 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈17

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Prefer small, explicit Go code over clever abstractions.

    line 7
  2. Distinctive:

    Read only task-relevant stack files.

    line 23
  3. Distinctive:

    Avoid importing CLI code from library/internal packages.

    line 43
  4. Distinctive:

    Use standard library first when reasonable.

    line 47
  5. Very specific:

    Keep context.Context as the first parameter when a function accepts context.

    line 48
  6. Very specific:

    Use panic only for programmer errors or unrecoverable initialization paths already established in the project.

    line 52
  7. Distinctive:

    Prefer consumer-side interfaces at boundaries used by tests or alternate implementations.

    line 53
  8. Distinctive:

    Do not introduce new dependencies without a clear need and validation.

    line 54
  9. Distinctive:

    Prefer cohesive files. If a file grows beyond about 500 LOC, consider splitting by responsibility.

    line 58
  10. Very specific:

    Avoid generic names such as utils, helpers, or common for new files/packages.

    line 59
  11. Distinctive:

    Keep comments short and contract-focused: inputs, outputs, side effects, edge cases.

    line 61
  12. Distinctive:

    Prefer behavior-focused tests over implementation-detail tests.

    line 65
  13. Distinctive:

    Use table-driven tests for validation, parsing, config mapping, and boundary cases.

    line 66
  14. Distinctive:

    Keep tests deterministic and avoid real external services unless explicitly required.

    line 70
  15. Distinctive:

    Run the safest relevant checks for the change.

    line 84
  16. Distinctive:

    If a command is skipped, state why.

    line 108
  17. Distinctive:

    Prefer upgrading vulnerable direct dependencies over replacing stable stack components.

    line 113
  18. Very specific:

    Do not silence govulncheck, gosec, or linter findings without documented rationale.

    line 114
  19. Distinctive:

    Keep refactors behavior-preserving unless task says otherwise.

    line 118
  20. Distinctive:

    Prefer small PR-sized changes.

    line 120
  21. Very specific:

    When renaming exported or widely-used symbols, prefer semantic tools such as gopls rename if available.

    line 121
  22. Distinctive:

    Do not rewrite architecture unless evidence shows a concrete risk.

    line 122

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

Principles

  • KISS: keep solutions simple.
  • DRY on behavior, not at the cost of unclear data structures.
  • Prefer small, explicit Go code over clever abstractions.
  • Preserve public API behavior unless the task explicitly requires a change.

Source of truth

  • Codebase root: this repository.
  • Project documentation: README.md, docs/ARCHITECTURE.md, docs/LAYOUT.md, CONTRIBUTING.md.
  • Validation commands: Makefile, .github/workflows/ci.yml, .golangci.yml, go.mod.
  • Stack references: ~/workspace/repos/ contains local source-of-truth clones named owner.repo.
  • For Go questions, prefer relevant local stack sources before web search:
    • ~/workspace/repos/golang.go for language, stdlib, tests, toolchain behavior.
    • ~/workspace/repos/golang.website for go.dev docs and release notes.
    • ~/workspace/repos/yuin.goldmark for Markdown parser behavior.
    • ~/workspace/repos/go-rod.rod for browser lifecycle, context, timeout, Rod APIs.
    • ~/workspace/repos/goccy.go-yaml for YAML behavior.
    • ~/workspace/repos/golangci.golangci-lint for lint behavior.
  • Read only task-relevant stack files. Do not bulk-audit stack.

Project architecture

Picoloom is a Go library and CLI for Markdown-to-PDF conversion.

Main areas:

  • Root package github.com/alnah/picoloom/v2: public library API, converter facade, PDF rendering, pool, public types.
  • cmd/picoloom: CLI commands, flags, config wiring, batch conversion.
  • internal/pipeline: Markdown preprocessing, Goldmark conversion, HTML injection, path rewriting.
  • internal/assets: embedded/custom styles and templates.
  • internal/config: YAML config and validation.
  • internal/process: OS process cleanup for browser lifecycle.

Keep boundaries stable:

  • Public API stays in the root package.
  • Implementation details stay under internal/.
  • CLI orchestration stays in cmd/picoloom.
  • Avoid importing CLI code from library/internal packages.

Go practices

  • Use standard library first when reasonable.
  • Keep context.Context as the first parameter when a function accepts context.
  • Propagate context to I/O, browser, and long-running operations when supported.
  • Make resource ownership explicit. Close browsers, pages, files, pools, timers, and temp resources.
  • Wrap errors with useful context and %w when callers may need errors.Is or errors.As.
  • Use panic only for programmer errors or unrecoverable initialization paths already established in the project.
  • Prefer consumer-side interfaces at boundaries used by tests or alternate implementations.
  • Do not introduce new dependencies without a clear need and validation.

Files and names

  • Prefer cohesive files. If a file grows beyond about 500 LOC, consider splitting by responsibility.
  • Avoid generic names such as utils, helpers, or common for new files/packages.
  • Names should describe responsibility and behavior.
  • Keep comments short and contract-focused: inputs, outputs, side effects, edge cases.

Testing

  • Prefer behavior-focused tests over implementation-detail tests.
  • Use table-driven tests for validation, parsing, config mapping, and boundary cases.
  • Include happy paths, failure paths, edge cases, cleanup paths, and concurrency/race paths when relevant.
  • For pipeline robustness, consider fuzz tests with small meaningful seeds.
  • For browser/PDF behavior, use integration tests with the existing integration build tag.
  • Keep tests deterministic and avoid real external services unless explicitly required.

Useful commands:

go test ./...
go test -race ./...
ROD_NO_SANDBOX=1 go test -race -tags=integration ./...
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

Validation before handoff

Run the safest relevant checks for the change. Prefer non-mutating checks first.

Common checks:

gofmt -w .
go mod verify
go vet ./...
golangci-lint run
go tool gosec ./...
govulncheck ./...
go test ./...
go test -race ./...
go build ./...

Integration checks when browser/PDF/CLI conversion is touched:

ROD_NO_SANDBOX=1 go test -race -tags=integration ./...
go build -o /tmp/picoloom ./cmd/picoloom
ROD_NO_SANDBOX=1 /tmp/picoloom convert examples/simple-report.md -o /tmp/picoloom-simple-test.pdf

If a command is skipped, state why.

Dependency and security changes

  • For dependency updates, run go mod tidy, go mod verify, tests, and govulncheck ./....
  • Prefer upgrading vulnerable direct dependencies over replacing stable stack components.
  • Do not silence govulncheck, gosec, or linter findings without documented rationale.

Refactoring

  • Keep refactors behavior-preserving unless task says otherwise.
  • Split large files by responsibility, not by arbitrary layers.
  • Prefer small PR-sized changes.
  • When renaming exported or widely-used symbols, prefer semantic tools such as gopls rename if available.
  • Do not rewrite architecture unless evidence shows a concrete risk.

Picoloom-specific cautions

  • Goldmark raw HTML remains unsafe by design. Do not enable html.WithUnsafe() without explicit security review.
  • Rod/Chrome lifecycle must avoid leaked browser processes. Preserve explicit close/kill behavior.
  • SourceDir path rewriting must preserve path traversal protection.
  • Config validation and public type validation are separate trust boundaries. Keep them aligned with tests.
  • CLI flags, config, and environment precedence must match README behavior.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free