|
<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 # fix: run every agent in dependency order
|
|
make agents-all CHECK=1 # report only: run the whole fleet at once
|
|
```
|
|
|
|
Because reporting changes nothing, **`CHECK=1` runs every agent concurrently** for a
|
|
fast, read-only health check of the whole project. A **fix** run goes one agent at a
|
|
time in dependency order, so file changes never collide.
|
|
|
|
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).
|
|
|
|
## Checking only what you changed
|
|
|
|
While you work, you usually only want the fleet to look at the files you just
|
|
touched, not the whole project. These two targets run the whole fleet but limit it
|
|
to the files git reports as modified or new (untracked) under `devplacepy/` and
|
|
`tests/`, so a sweep takes seconds instead of minutes:
|
|
|
|
```bash
|
|
make maintenance # report only, all agents at once, just your changed files
|
|
make maintenance-fix # fix, just your changed files
|
|
```
|
|
|
|
`make maintenance` is read-only and concurrent, exactly like `make agents-all
|
|
CHECK=1` but narrowed to your work in progress. `make maintenance-fix` fixes, and a
|
|
built-in safety rule guarantees it can only edit the files in that changed set,
|
|
never anything else. If nothing under `devplacepy/` or `tests/` has changed, the run
|
|
prints "nothing to do" and exits cleanly. The same scope is available on a single
|
|
agent with the `--changed` flag, for example `python -m agents.security --changed`.
|
|
|
|
## 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>
|