|
<div class="docs-content" data-render>
|
|
# Running the agents
|
|
|
|
This page shows how to run the [maintenance agents](/docs/maintenance-agents.html).
|
|
You do not need to know the codebase to use them. Every command below is safe to
|
|
copy and paste from the project root.
|
|
|
|
> The golden rule: **check** never changes anything, **fix** does. When in doubt,
|
|
> run check first and read the report.
|
|
|
|
## The easiest way: talk to Maestro
|
|
|
|
Maestro is the conductor. You ask in plain language and it runs the right agent for
|
|
you, then explains what it found.
|
|
|
|
```bash
|
|
make maestro
|
|
```
|
|
|
|
That opens a prompt. Try asking:
|
|
|
|
- `is my audit coverage complete?`
|
|
- `check the security of the projects router`
|
|
- `get the whole project in shape`
|
|
|
|
You can also ask a single question without opening the prompt:
|
|
|
|
```bash
|
|
python -m agents.maestro "is my documentation up to date?"
|
|
```
|
|
|
|
Maestro defaults to **check** (read-only) for questions and confirms with you
|
|
before it makes any change. When you ask it to review the whole project, it runs
|
|
each agent **once** and reuses those results to answer anything you ask next, so it
|
|
never repeats the same sweep to look something up.
|
|
|
|
## Running one agent yourself
|
|
|
|
Every agent has its own command. By default an agent **fixes** what it finds; add
|
|
`CHECK=1` to only report.
|
|
|
|
```bash
|
|
make audit-agent # find and fix audit-log gaps
|
|
make audit-agent CHECK=1 # only report them, change nothing
|
|
```
|
|
|
|
The full set of agent commands:
|
|
|
|
```bash
|
|
make security-agent # data and role security
|
|
make audit-agent # audit-log coverage
|
|
make devii-agent # Devii capability and tool visibility
|
|
make docs-agent # documentation accuracy
|
|
make fanout-agent # feature wired across every layer
|
|
make dry-agent # duplication and reuse
|
|
make style-agent # naming, headers, typing, formatting
|
|
make frontend-agent # JavaScript, components, CSS
|
|
make seo-agent # search metadata and sitemap
|
|
make test-agent # integration-test coverage
|
|
```
|
|
|
|
Add `CHECK=1` to any of them to report without changing files.
|
|
|
|
## Running the whole fleet
|
|
|
|
```bash
|
|
make agents-all # run every agent in order and fix
|
|
make agents-all CHECK=1 # run every agent in order, report only
|
|
```
|
|
|
|
This is the command to run before a release, or in a continuous-integration job
|
|
(in `CHECK=1` mode it returns a non-zero exit code if anything is wrong).
|
|
|
|
## What you see while it runs
|
|
|
|
The output is meant to be read live, so you always know what is happening:
|
|
|
|
- **A start banner** for every agent: its name, a memorable codename (like
|
|
`brave-otter`), what it is about to do, and where its report will be written.
|
|
- **A timestamp and elapsed time** on every line, so you can see how long things take.
|
|
- **A running cost** after each AI step (per call and total), with money icons.
|
|
- **A diff** of every file change as it happens, so nothing is edited silently.
|
|
- **Live command output** streamed line by line while a command runs.
|
|
|
|
## Reading the reports
|
|
|
|
Every run writes its findings to `agents/reports/`, named
|
|
`<agent>-<codename>-<date>` so a run is easy to refer to:
|
|
|
|
- `<agent>-<codename>-<date>.json` - the machine-readable findings.
|
|
- `<agent>-<codename>-<date>.md` - a readable summary grouped by file.
|
|
- `fleet-<codename>-<date>.json` - the combined report when you run the whole fleet.
|
|
|
|
A report marked `incomplete` means the run ran out of its step budget before
|
|
finishing; its findings are partial and it is worth running again.
|
|
|
|
## Validating the code yourself
|
|
|
|
The agents verify their own changes with a built-in validator that needs no extra
|
|
tools. You can run it directly any time:
|
|
|
|
```bash
|
|
make validate # check Python, JavaScript, CSS, and templates
|
|
```
|
|
|
|
## Where to go next
|
|
|
|
- [Maintenance agents](/docs/maintenance-agents.html) - what each agent does and why.
|
|
</div>
|