Skip to content

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 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.

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: high

These are starting budgets, not limits. The agent goes further when the work needs it, and says why.

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.

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.

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.

The agent runs these itself. You can run them too, and none of them runs a model:

Terminal window
guardlink lint .
15 claims: 0 errors, 0 warnings
(governance verbs are not checked without --since: a person may have written them)
Terminal window
guardlink status .
GuardLink Status: audit-notes
────────────────────────────────────────
Files in scope: 2
Files annotated: 2
Files unannotated: 0
Annotations: 12
Consumers read: .guardlink/report.json (current)
Verified claims: none recorded (run guardlink verify --all)
────────────────────────────────────────
Assets: 2
Threats: 2
Controls: 0
Actors: 3
Mitigations: 0
Exposures: 2

The 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.