Your first pack¶
In this tutorial you build a pack called myteam with one skill for Protocol Buffers, install it
into your AI tools, and check that Gatework will load it for .proto files. It takes about 15
minutes. You need Python 3.11+ and git.
A pack is a folder or repo of your own, layered on top of brainrc, so you never edit brainrc
itself (packs). This tutorial works from a clone of brainrc so it can run the same
commands CI does; with the installed command, type brainrc where it says
python3 scripts/brainrc.py, and put packs.local.toml in ~/.config/brainrc/.
Run every command from the brainrc clone unless a step says otherwise. CI runs steps 1-4 of this
page on every change (scripts/check_tutorial.py), so they stay accurate.
1. Clone brainrc, install it, and check it¶
git clone <this-repo> ~/brainrc
cd ~/brainrc
python3 scripts/brainrc.py apply
python3 scripts/brainrc.py validate
apply fetches the default pack, Gatework, and installs brainrc and Gatework into
your AI tools. validate should then print a line starting with OK:
that counts skills, agents, and commands.
2. Create the pack¶
new pack writes a pack that validates, then checks it. --yes takes the defaults; without it,
in a terminal, it asks for the prefix, the tools you'll edit the pack with, and a ticket system.
python3 scripts/brainrc.py new pack myteam --to ~/src/myteam-ai-pack --yes
You should see OK: with (packs: gatework, myteam) at the end: brainrc, the default pack it
fetched in step 1, and yours. The pack's pack.toml sets its prefix, myteam-, which keeps
your item names apart from everyone else's, and requires_core, the brainrc versions it works
with. The pack also has a facts skill, myteam-facts, a rule that points at it, tripwires, tests
and a CI workflow (what each file is for).
3. Add a domain skill¶
A domain skill, one for a single stack, has four sections: how to validate offline,
conventions, a review checklist, and what never to do without approval. The description is
what makes an AI tool load it, and the [[extensions.gatework.domains]] row tells Gatework which
files load it.
mkdir -p ~/src/myteam-ai-pack/skills/myteam-protobuf
cat > ~/src/myteam-ai-pack/skills/myteam-protobuf/SKILL.md <<'EOF'
---
name: myteam-protobuf
description: Protocol Buffers schemas for myteam services. Validation, conventions, and a review checklist for *.proto and buf.yaml. Use when changing or reviewing protobuf files.
---
# myteam-protobuf
## Validate (offline)
~~~bash
buf lint
buf breaking --against '.git#branch=main'
~~~
## Conventions
- One package per directory, named after the service and version (`myteam.billing.v1`).
- Never reuse or renumber a field. Reserve removed numbers and names.
## Review checklist
- A field changed type or number: that breaks every existing client.
- New required semantics on an existing message: needs a new version.
## Never without approval
- Publishing generated code or pushing to a schema registry.
EOF
cat >> ~/src/myteam-ai-pack/pack.toml <<'EOF'
[[extensions.gatework.domains]]
files = "`*.proto`, `buf.yaml`"
skills = ["myteam-protobuf"]
EOF
python3 scripts/brainrc.py validate --pack ~/src/myteam-ai-pack
validate should print OK: again. A common mistake is a skill without the prefix. validate
then names it, for example myteam:skills/protobuf: pack skills must start with `myteam-`.
4. Enable and install it¶
Packs are enabled per machine in packs.local.toml, which git ignores. status is a dry run
and apply writes.
cat > packs.local.toml <<'EOF'
[myteam]
path = "~/src/myteam-ai-pack"
EOF
python3 scripts/brainrc.py status
python3 scripts/brainrc.py apply
python3 scripts/brainrc.py status | grep 'Everything in sync.'
The first status lists CREATE lines, including ones for myteam-protobuf and myteam-facts
in each harness's skills directory. After apply, status prints Everything in sync.
5. Check what your AI tools now see¶
ls ~/.claude/skills/myteam-protobuf
grep myteam ~/.config/brainrc/extensions.md
python3 scripts/brainrc.py tokens | grep myteam
You should see SKILL.md, a Domains row for `*.proto`, `buf.yaml` naming
myteam-protobuf, and the skill's cost in tokens. Gatework reads that Domains row at the
start of every ticket, so a ticket touching a .proto file now loads your skill.
6. Put the pack under version control¶
cd ~/src/myteam-ai-pack
git init -q
git add .
git -c user.name=you -c user.email=you@example.com commit -qm "Add myteam pack"
Push it, and the CI workflow new pack wrote (.github/workflows/validate.yml) checks the pack
on every push with the validate-pack action, against the brainrc version it pins
(Validate a pack in its own CI). Move that pin, and
requires_core, when you test against a newer brainrc.
Next steps¶
- examples/pack-acme shows every other pack feature: an intake context skill, a ticket connector, Deliver checks, rules, commands, and tripwires.
- Packs is the full pack reference.
- To share the pack with a repo's agents instead of one machine, list it in the repo's
brainrc.toml(team setup). - To add a domain skill to Gatework for everyone instead, open a pull request on
brainrc/gatework: the skill goes in
skills/<stack>/with a row in the Domains table ofskills/brainrc-gatework/SKILL.md.