The agent brief

Pro. For “what should my AI assistant tell me after a scan?”

The brief is a short summary of a scan, the same shape every time, for an AI assistant to pass on as it is. Penthera’s rules fill it; no model is involved.

Section	What is in it
Verdict	`Fix now`, `Review` or `Nothing to fix`, with the counts
Act on	Findings that need a change: where, why, the fix, the rule id
Check first	Heuristic and low findings, and what a dependency can do
Likely noise	Hits in files git ignores, generated build output or test fixtures, one line per group
Not checked	What the scan did not read. Always shown, so a short brief is not read as “safe”
Next	Up to three commands, and the path of the full report

Findings that repeat collapse into one line: two advisories for one Node.js pin, or the same rule in 16 build files. Every finding is counted once. The full list stays in the JSON and Markdown reports.

Get it

Where	How
A scan, in a terminal	`penthera --repo . --brief`
A scan, from an agent	Nothing to add: with no terminal on stdout, a scan prints the brief instead of the terminal report. `PENTHERA_BRIEF=0` turns that off; CI keeps the terminal report
A report file	`penthera --repo . --audience agent --markdown reports/brief.md`
JSON	The `brief` field of `-o report.json` (schema `penthera.brief/1`)
Several scans in one	`penthera brief reports/repo.json reports/deps.json reports/agents.json`
MCP	The text of every tool result is the brief; `structuredContent.brief` holds the object

penthera --repo . -o reports/repo.json
penthera deps . -o reports/deps.json
penthera agents . -o reports/agents.json
penthera brief reports/repo.json reports/deps.json reports/agents.json

penthera brief --json prints the merged brief as JSON. penthera brief reads only the files you name and runs no scan.

How an assistant should reply

The MCP server and the Agent Skill ask the assistant to:

Pass the brief on in its order, with the verdict line and section names.
Not move a finding between sections, change a severity or drop a group.
Put anything it checked itself under a last section, My read, and say what it looked at. That section is the assistant’s view, not Penthera’s.
Ask before changing files.

Which section a finding goes in

The first matching rule wins:

Likely noise: the file is local only (git ignores it), in generated output (.next*, dist, build, out, __pycache__, coverage), or a test fixture.
An info finding goes to Next if it names a command, or to Not checked if it says something was not found or not run.
Check first: confidence potential or needs-human-review, severity low, or a dependency capability.
Act on: everything else.

The design is in docs/research/spec-agent-brief.md.

I'm new

I use AI coding tools

I run it in CI

Evidence for an auditor

Research and method

Compared

The project

Brief

The agent brief

Get it

How an assistant should reply

Which section a finding goes in

​The agent brief

​Get it

​How an assistant should reply

​Which section a finding goes in

The agent brief

Get it

How an assistant should reply

Which section a finding goes in