Annotate a repository
The threat model is GuardLink annotations, in external .gal sidecars or
inline source comments according to the repository’s configured mode. Bravos’s
bravos-annotate skill has the agent in your session write them, and
guardlink’s gates decide whether they are good enough. This page covers how to
ask for that and how to check the result.
Before you start, Bravos must be in the repository: Build your first threat model.
Ask for a slice
Section titled “Ask for a slice”Ask the agent “annotate this repository”, or run /bravos-annotate ($bravos-annotate
in Codex). By default the skill takes a budgeted slice of five files. It skips
files teammates have in open pull requests, follows guardlink’s own annotation
playbook, and runs the lint gate until it reports 0 errors. The briefing
names the annotation mode; new installations leave the default to GuardLink.
Before the first commit of a session the skill asks whether to commit or leave
the changes for review, unless you already asked for commits.
The playbooks are guardlink’s: bravos setup installs them as
guardlink-annotate-* skills beside Bravos’s own. What each verb means and where it goes is in the
guardlink docs.
Change the budget
Section titled “Change the budget”Every skill reads one effort dial: low, medium (the default), high or max. Say
it (“annotate at high”), or put a line in AGENTS.md or CLAUDE.md:
bravos effort: highThese are starting budgets, not limits. The agent goes further when the work needs it, and says why.
Annotate what you changed
Section titled “Annotate what you changed”After writing security-relevant code, ask “annotate what I changed”. The skill
reviews changed behavior even inside an already annotated handler, traces
callers and affected controls, then reconciles flows, boundaries and reach
claims to the same evidence bar and runs the same gate. With
autopilot on (bravos setup --autopilot, Team plan), an end-of-turn check sends
the agent back once when changed code has no annotation, so you do not have to
ask.
You may not need to ask at all. While coverage is under 100%, each new session
asks the agent to start one annotation slice in a background subagent beside
what you asked. It writes annotations only, never code, and commits only as
your commits answer allows. bravos prefs set annotate off --by "<your name>"
switches it off for the clone, and BRAVOS_AUTO_ANNOTATE=off for one session.
Annotation does not wait for the intake
Section titled “Annotation does not wait for the intake”With no confirmed intent, the agent drafts what the app is for, writes it to
.guardlink/intent.md with every item marked — draft, and annotates against
that draft from the first session. It asks a person to confirm the draft, and
rechecks what their answers change. See
context from your design documents.
Cover the whole repository
Section titled “Cover the whole repository”Coverage to a goal is a campaign, a paid feature with a 30-day no-card trial. Ask “annotate until
coverage is 100%”, or run /bravos-campaign. It plans disjoint batches, runs
one subagent per batch each round, gates every batch, rests between rounds and
stops at the goal or when you stop it. It reports before-and-after numbers.
Check what was written
Section titled “Check what was written”The agent runs these itself. You can run them too, and none of them runs a model:
guardlink lint .15 claims: 0 errors, 0 warnings(governance verbs are not checked without --since: a person may have written them)guardlink status .GuardLink Status: audit-notes────────────────────────────────────────Files in scope: 2 Files annotated: 2 Files unannotated: 0Annotations: 12Consumers read: .guardlink/report.json (current)Verified claims: none recorded (run guardlink verify --all)────────────────────────────────────────Assets: 2Threats: 2Controls: 0Actors: 3Mitigations: 0Exposures: 2The status output is truncated after exposures. These captures use the
audit-notes fixture: one Flask file with a note search and an export route,
annotated in external sidecars, with GuardLink 2.7.1. The two exposures remain
hypotheses; annotation validation does not test them.
In external mode, the agent also runs guardlink parse . -o .guardlink/report.json
after changing sidecars. That export is what the code graph, the dashboard and
CI read; Consumers read says whether it is current.
What the agent never writes
Section titled “What the agent never writes”- Ask the code graph: annotation is sharper with reach to go on.
- Run SAST: the analyzer reads the annotations, so annotate first.

