botica 0.14.2

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

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

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.