Skip to content

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.

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.

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:

Terminal window
bravos context add ../../design/notes-prd.md --title "Audit Notes PRD" --kind prd
SRC-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 recorded
Everyone 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.

Terminal window
bravos context add ../../design/2025-threat-model.md --title "2025 threat model review" --kind threat-model
SRC-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 recorded
Commit 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>".

Terminal window
bravos context list
SRC-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.

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

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:

Terminal window
bravos context gate
Context 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.

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-annotate and bravos-templatize read the invariant threat ids, the intended-by-design list and the boundaries.
  • bravos rules lists each rule with its status: broken, retest due, unguarded, guarded but untested, not placed, or holds. bravos dashboard shows 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.

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.