Context from your design documents
Bravos judges code against what the application is meant to do, not only against code patterns. You can start it from what your team already wrote: PRDs, design documents and an earlier threat model, as files or links. Bravos keeps each one in the repository, drafts the app’s intent from them, and every coding agent that later works on the repository reads that intent.
A pattern scan sees nothing wrong when a sales user opens the revenue report. A rule taken from your PRD, “sales may view every report except the revenue report”, makes that a threat Bravos can place in the code and test.
What the context step produces
Section titled “What the context step produces”The bravos-context skill does this work in your agent’s session. It runs on
the Free plan.
| What | Where | Committed |
|---|---|---|
Your documents, converted to Markdown, each with an id (SRC-1, SRC-2…) |
.bravos/context/sources/, indexed in .bravos/context/sources.json |
yes |
The app’s intent: purpose, roles, crown jewels, invariants (INV-n), intended-by-design behaviour (INT-n), a “who may do what” table |
.guardlink/intent.md |
yes |
| The questions Bravos asks, with its suggested answers | .guardlink/intent-draft.json |
yes |
| Each person’s answers | .guardlink/intent-answers/<name>.json |
yes |
| A threat per invariant, with references to its rule and source document | .guardlink/definitions.* |
yes |
Each rule in intent.md names the document it came from, for example
(source: SRC-2 "Report access"). Severities are then rated against the
recorded intent, and something that looks dangerous but is intended gets an
“intended?” audit for a person to answer instead of a high rating.
Give Bravos your documents
Section titled “Give Bravos your documents”Ask your agent “learn what this app intends”, or run /bravos-context. It
asks once whether you have design documents, PRDs or an earlier threat model,
and carries on from the code and README while you find them. Paste paths or
links in the chat. The agent converts a PDF, a slide deck or a web page to
Markdown itself, with the access your session already has, and stores each
document with bravos context add.
You can store a document yourself. These captures use a short PRD and a 2025
threat model review, kept outside the audit-notes fixture repository:
bravos context add ../../design/notes-prd.md --title "Audit Notes PRD" --kind prdSRC-1 added: Audit Notes PRD (prd, 544 B) stored as .bravos/context/sources/SRC-1-audit-notes-prd.md; where the file was on this machine is not recordedEveryone with access to this repository can read what is added under .bravos/context/, and links are kept in full.Truncated after the first addition’s notice. The output then names a pre-push
check, described under What is refused, and ends with
Commit it with the team's other context: git add .bravos/context.
bravos context add ../../design/2025-threat-model.md --title "2025 threat model review" --kind threat-modelSRC-2 added: 2025 threat model review (threat-model, 412 B) stored as .bravos/context/sources/SRC-2-2025-threat-model-review.md; where the file was on this machine is not recordedCommit it with the team's other context: git add .bravos/context--kind takes prd, design, threat-model, policy, api, upstream or
other. add records who added each document from git’s user.name; with
none set it asks for --by "<your name>".
bravos context listSRC-1 prd Audit Notes PRD (544 B, Dana Lee, 2026-11-17)SRC-2 threat-model 2025 threat model review (412 B, Dana Lee, 2026-11-17)The name and date come from the person who added each document and the day they did, so yours will differ.
What is refused
Section titled “What is refused”The documents are committed for everyone with access to the repository to
read. So bravos context add refuses a document that carries a secret, a
local path or an embedded image, and names the lines:
ops-notes.md was not stored. It would be committed for the whole team to read, and it has: line 3: looks like an aws access key line 4: a macOS user folderReplace each secret with a placeholder such as <redacted>, remove local paths, describe an embedded image in words, then try again.That document was written for this capture with AWS’s published example key
and a made-up home folder. bravos context check re-checks the stored
documents, the draft and intent.md, including for sources cited but not
stored. A git pre-push check stops a push that would send one. Bravos
installs that check only in a clone with no pre-push hook of its own;
otherwise it prints the line to add to yours.
A person confirms the intent
Section titled “A person confirms the intent”The agent drafts .guardlink/intent.md from the documents, the README and the
code, with every item marked — draft, and starts annotating against that
draft straight away. It then opens the intake page with bravos review intent.
The page is pre-filled with Bravos’s suggestions and their sources. You change
what is wrong, make the calls marked “needs your call”, and press Confirm.
Teammates add their own answers with bravos review intent after pulling.
Until someone confirms, every session asks once. The agent never confirms or
declines for you. A team that chooses to go without records it under a name,
bravos context decline --by "<name>". bravos context gate says which state
the repository is in:
bravos context gateContext not recorded yet: nobody has said what this product is meant to do. Annotation goes on regardless, judged against the draft (with no intent yet, the bravos-context skill drafts one first, without waiting for answers). Ask the person once this session to confirm it on the intake page: bravos review intent. A team that chooses to go without records that by a named person: bravos context decline --by "<name>".The command exits 1 in this state. Annotation is not held back.
When the answers arrive, the agent rewrites the intent from them and rechecks the findings they change. An item you mark as intended by design is then annotated as intended, not as a finding.
Every agent then works from it
Section titled “Every agent then works from it”The intent and its rules live in the repository, so they reach every session on every machine that has Bravos:
- The session briefing carries an
Intent:line saying whether intent is recorded, still a draft, or missing. bravos-annotateandbravos-templatizeread the invariant threat ids, the intended-by-design list and the boundaries.bravos ruleslists each rule with its status: broken, retest due, unguarded, guarded but untested, not placed, or holds.bravos dashboardshows the same as Design rules.- On Team, the pre-PR gate and the PR workflow hold a pull request that changes a file a holding rule is enforced in, until its test is replayed or the PR body names the rule.
Researching someone else’s project
Section titled “Researching someone else’s project”By default bravos-context assumes you are researching software you do not
own, such as an open-source project or a vendor’s code. It drafts the intent
from upstream’s own documentation, with links, and asks only the scope
decisions: which configuration to rate against, single organisation or
multi-tenant, which attackers are in scope, and the intended-looking
behaviours upstream does not document. Say “this is our product” for the
owner interview instead.
Related
Section titled “Related”- Share Bravos with your team: what is committed, and what a teammate who clones the repository sees.
- The verification loop: where context sits before annotation and testing.

