Botica: recetas, alquimia y artilugios
_{Recipes and standards for projects: deterministic rules, templates, and design decisions.}

---

Documentation: https://collectiveai-team.github.io/botica/

Source Code: https://github.com/collectiveai-team/botica

---

Botica is a linter and a set of recipes for the repositories of a team.

• botica lint runs rules over the files of a project: the built-in catalog, and the rules that the project writes in .botica/rules/. Each rule checks a written standard. It never calls a model or the network, and it runs as a command, a hook of prek, a job of CI and a language server.
• botica recipe install sets up a repository of some kind: the selection of rules in botica.toml, the hooks of prek, the workflows of GitHub Actions, the agent skills and the lines of .gitignore. It adds what is missing, and a file that exists is not replaced.
• Judgment rules cover what no deterministic check can express. Botica exports them to AGENTS.md and to the rubric of abide, the judge, and filters what the judge reports with the same configuration and comments.

Most rules read Python, TypeScript and JavaScript, a few read Go and Rust, and the rest read the files of any project: their names, their size, the layout of the folders, the commit messages.

Install

Botica is one binary, published on PyPI as the wheel botica. It runs without Python.

uvx botica lint            # run it once, without installing
uv tool install botica     # or keep it installed

From a checkout: cargo build --release -p botica-cli, and the binary is target/release/botica.

Use

botica lint                    # the active rules over the current directory
botica lint --diff origin/main # only the findings on the lines that a branch adds
botica rules --all             # every rule, whether it is active, and why
botica explain no-utils        # what a rule asks, and how it is configured here

botica lint exits with 1 when a finding is an error and with 2 when the run fails. A configuration is botica.toml, or [tool.botica] in pyproject.toml:

select = ["file-size-guard", "no-utils", "log-no-print"]

[rules.file-size-guard]
warn = 500
max = 900

A comment silences one finding, with its reason:

print(report)  # noqa: BTLOG002 -- the output of the command

The guide has every command and key, the baseline of known findings, the editor (Neovim, Helix, Emacs) and the hooks and CI.

Set up a repository

From the root of the repository, with uv and npx on the PATH:

uvx botica recipe install base base-python agent-claude-code ci-python repo-public

Recipe	What it adds
base	any repository: the rules about any file and about lockfiles, the skills, .gitignore, the hooks of prek, the workflow of abide, the sections of AGENTS.md
base-python	a Python project: the rules about Python code and pyproject.toml, the Python hooks and the dev tools
full-python	base-python and ci-python
base-go	a Go module: the rules about Go code, .golangci.yml, golangci-lint and go mod tidy in prek, and govulncheck in the manual stage of prek
full-go	base-go and ci-go
base-rust	a Rust crate or workspace: the rules about Rust code, the cooldown of Cargo, and cargo fmt, clippy and cargo-shear in prek
full-rust	base-rust and ci-rust
base-node	a TypeScript or JavaScript project: the rules about its code, Biome, ESLint for JSDoc, tsc and knip in prek, the cooldown of pnpm, and those packages in package.json
full-node	base-node and ci-node
agent-claude-code, agent-codex, agent-opencode	the configuration and the skills of an agent
ci, ci-python, ci-node, ci-go, ci-rust	the workflows of GitHub Actions for commits and for an ecosystem
repo-public, repo-private	the workflows that fit the visibility of the repository
ci-publish, ci-docker, ci-dependency-review, ci-automerge-public, ci-automerge-private, ci-botica-update, secrets-varlock	one workflow or tool each
iac-terraform	Terraform or OpenTofu: the hooks of terraform fmt, terraform validate, tflint and trivy, and the workflow that runs them and checkov
security	code that issues or checks credentials: the rules of CES-121

botica recipe list prints them with their steps, and botica recipe check says how the repository differs from them. A file that exists is left as it is and reported pending. Commit skills-lock.json afterwards: npx skills experimental_install restores .agents/skills/ from it. Recipes describes each step, and a project adds its own recipes in recipes/.

Extend

A project writes its rules in .botica/rules/<catalog>/, and botica rules new writes the folder of one:

botica rules new structure/no-eval --kind ast-grep --language python --catalog .botica/rules/acme
botica rules conform .botica/rules/acme   # the rule over its fixtures

• A pattern rule is a YAML pattern over the syntax tree of a file.
• An extension is a program that answers the protocol of botica over stdin and stdout. The SDKs are Python (botica.sdk, in the wheel), Node, Go and Rust.
• An external rule is enforced by another tool, and botica checks that its configuration is there.
• A judgment rule is a question for abide, calibrated with botica rules test --judge abide.

Extend has a first rule, its fixtures, the protocol and the SDKs.

This repository

Folder	What it holds
crates/	the Rust workspace of botica
catalog/	what the binary embeds: the built-in rules, the topics of botica refs, the recipes
standards/	the text of each standard, standards/<set>/<number>-<slug>.md; the CES are the standards of Collective
sdk/	the SDKs of the extension protocol
skills/	the agent skills that the recipe base installs
website/	the site: the manual, the standards, the rules and the references
distribution/	the mirror botica-pre-commit for prek
docs/adr/	the design decisions

A change to a standard is a pull request with the file of the standard and the folders of its rules; the steps are in Propose or change a standard. docs/develop.md has the commands to build and test botica, and docs/botica-release.md the release.

The skills of this repository

The recipe base installs them with npx skills add collectiveai-team/botica, beside the skills of Matt Pocock that its [[skills]] step pins to a tag. The skills are under skills/, and the [[skills]] steps of catalog/recipes/base.toml list the ones it installs.

npx skills add and skills update overwrite the installed copies in place, so local edits go in this repository's skills/, not in .agents/skills.

License

MIT, in LICENSE.