forked from retoor/devplacepy
feat: add autonomous maintenance agent fleet with shared engine and validator
Add the `agents/` directory containing a fleet of autonomous AI maintenance agents for codebase consistency, including a shared async engine (`agent.py`), a dependency-free validator (`validator.py`), and specialized agents for security, audit, docs, style, frontend, SEO, test coverage, and more. Wire the fleet into the Makefile with `--fix`/`--check` modes, document the architecture in `AGENTS.md`, `CLAUDE.md`, and `README.md`, and enforce a hard rule that the `agents/` directory itself is off-limits to any code modification to preserve detection data.
This commit is contained in:
@@ -22,6 +22,7 @@ SECTION_SERVICES = "Services"
|
||||
SECTION_ARCH = "Architecture"
|
||||
SECTION_TESTING = "Testing"
|
||||
SECTION_PROD = "Production"
|
||||
SECTION_MAINTENANCE = "Maintenance agents"
|
||||
|
||||
DOCS_PAGES = [
|
||||
# General - how to use the site and Devii (everyone)
|
||||
@@ -44,6 +45,19 @@ DOCS_PAGES = [
|
||||
"kind": "prose",
|
||||
"section": SECTION_GENERAL,
|
||||
},
|
||||
# Maintenance agents - the self-maintaining quality fleet (public)
|
||||
{
|
||||
"slug": "maintenance-agents",
|
||||
"title": "Maintenance agents",
|
||||
"kind": "prose",
|
||||
"section": SECTION_MAINTENANCE,
|
||||
},
|
||||
{
|
||||
"slug": "maintenance-usage",
|
||||
"title": "Running the agents",
|
||||
"kind": "prose",
|
||||
"section": SECTION_MAINTENANCE,
|
||||
},
|
||||
# Components - custom HTML web components with live examples (everyone)
|
||||
{
|
||||
"slug": "components",
|
||||
|
||||
@@ -304,3 +304,58 @@
|
||||
gap: 0.375rem;
|
||||
}
|
||||
}
|
||||
|
||||
.landing-bots-intro {
|
||||
max-width: 760px;
|
||||
margin: 0 0 1.5rem;
|
||||
color: var(--text-secondary);
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.landing-bots-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
|
||||
gap: 1rem;
|
||||
}
|
||||
|
||||
.landing-bot-card {
|
||||
background: var(--bg-card);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: var(--radius-xl);
|
||||
padding: 1.25rem;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.5rem;
|
||||
}
|
||||
|
||||
.landing-bot-card:hover {
|
||||
transform: translateY(-2px);
|
||||
box-shadow: var(--shadow-lg);
|
||||
}
|
||||
|
||||
.landing-bot-card-lead {
|
||||
border-color: var(--accent);
|
||||
}
|
||||
|
||||
.landing-bot-icon {
|
||||
font-size: 1.75rem;
|
||||
}
|
||||
|
||||
.landing-bot-card h3 {
|
||||
margin: 0;
|
||||
color: var(--text-primary);
|
||||
font-size: 1.05rem;
|
||||
}
|
||||
|
||||
.landing-bot-card p {
|
||||
margin: 0;
|
||||
color: var(--text-secondary);
|
||||
font-size: 0.9rem;
|
||||
line-height: 1.5;
|
||||
}
|
||||
|
||||
@media (max-width: 480px) {
|
||||
.landing-bots-grid {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
<div class="docs-content" data-render>
|
||||
# Maintenance agents
|
||||
|
||||
DevPlace is **self-maintaining**. Alongside the site you use, a fleet of
|
||||
autonomous AI agents continuously reviews the codebase for security, audit
|
||||
coverage, documentation accuracy, and code quality, then fixes what it finds and
|
||||
proves the build still works.
|
||||
|
||||
This page explains what the fleet is and what each agent does. The companion page,
|
||||
[Running the agents](/docs/maintenance-usage.html), shows exactly how to run them,
|
||||
with copy-paste commands.
|
||||
|
||||
> New here? You do not need to know the codebase. Talk to **Maestro**, the
|
||||
> conductor, in plain language ("is my audit coverage complete?") and it runs the
|
||||
> right agent for you and explains the result.
|
||||
|
||||
## How it works in one minute
|
||||
|
||||
- Each agent owns **one quality dimension** and sweeps the whole repository for
|
||||
problems in that dimension only.
|
||||
- Every agent has two modes: **check** (report only, changes nothing) and **fix**
|
||||
(correct the problem, then verify the build).
|
||||
- After any change, an agent runs a built-in **validator** (Python, JavaScript,
|
||||
CSS, and HTML/templates) plus an application import, and refuses to finish if the
|
||||
build is broken.
|
||||
- Every run writes a small **report** (a JSON file and a readable summary) so you
|
||||
can see exactly what was found and fixed.
|
||||
|
||||
## Meet the fleet
|
||||
|
||||
| Agent | What it watches |
|
||||
|-------|-----------------|
|
||||
| **Maestro** | The conductor you talk to. It picks the right agent (or the whole fleet) and explains the result. |
|
||||
| **Security** | Every route is correctly authorized; private data and admin actions are protected; user input is validated. |
|
||||
| **Audit** | Every action that changes data leaves an audit-log entry, including denials and failures. |
|
||||
| **Devii** | The Devii assistant can do everything the site offers for your role, and only shows tools your role is allowed to use. |
|
||||
| **Docs** | CLAUDE.md, AGENTS.md, README, and these docs pages stay in step with the code, shown to the right audience. |
|
||||
| **Feature completeness** | A new feature is wired all the way through: form, JSON schema, Devii tool, API docs, SEO, and README. |
|
||||
| **Duplication** | Shared helpers are reused instead of copy-pasted logic. |
|
||||
| **Style** | Naming, headers, typing, and formatting follow the project rules. |
|
||||
| **Frontend** | JavaScript modules, web components, and CSS follow the project's strict structure. |
|
||||
| **SEO** | Public pages carry the right search metadata and appear in the sitemap. |
|
||||
| **Tests** | Routes without an integration test get one written (the agent never runs the suite itself). |
|
||||
|
||||
## One directory they never touch
|
||||
|
||||
The agents leave their own home alone. The `agents/` directory holds the agents'
|
||||
source, which deliberately contains the very patterns they search for (special
|
||||
characters, example bad names, dangerous command text) as **detection data**, not
|
||||
as mistakes. Scanning it would flag false problems, and fixing those would break
|
||||
the agents. So every agent run hard-blocks any change under `agents/`, and the
|
||||
agents are told never to read or scan it. The directory is off-limits to every
|
||||
checker and cleanup, by design.
|
||||
|
||||
## Why this exists
|
||||
|
||||
A single feature in DevPlace touches many layers at once: a route is rendered as a
|
||||
page, served as JSON, exposed to the Devii assistant, written into the API docs,
|
||||
audited, and indexed for search. It is easy for a human to change one layer and
|
||||
forget a connected one. The fleet exists to catch exactly that, on every dimension,
|
||||
across the whole project, without anyone having to remember the full map.
|
||||
|
||||
## Where to go next
|
||||
|
||||
- [Running the agents](/docs/maintenance-usage.html) - the commands, with examples.
|
||||
- [Devii Assistant](/docs/devii.html) - the in-app assistant the Devii agent keeps honest.
|
||||
</div>
|
||||
@@ -0,0 +1,92 @@
|
||||
<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.
|
||||
|
||||
## 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).
|
||||
|
||||
## Reading the reports
|
||||
|
||||
Every run writes its findings to `agents/reports/`:
|
||||
|
||||
- `<agent>-<date>.json` - the machine-readable findings.
|
||||
- `<agent>-<date>.md` - a readable summary grouped by file.
|
||||
- `fleet-<date>.json` - the combined report when you run the whole fleet.
|
||||
|
||||
## 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>
|
||||
@@ -114,6 +114,46 @@
|
||||
</section>
|
||||
{% endif %}
|
||||
|
||||
<section class="landing-section landing-bots">
|
||||
<div class="landing-section-header">
|
||||
<h2>Self-Maintaining by Design</h2>
|
||||
<a href="/docs/maintenance-agents.html" class="landing-section-link">How it works →</a>
|
||||
</div>
|
||||
<p class="landing-bots-intro">DevPlace keeps its own house in order. A fleet of autonomous AI agents continuously reviews the codebase for security, audit coverage, documentation accuracy, and code quality, then fixes what it finds and proves the build still works. You talk to one conductor, Maestro, and it runs the rest.</p>
|
||||
<div class="landing-bots-grid">
|
||||
<div class="landing-bot-card landing-bot-card-lead">
|
||||
<div class="landing-bot-icon">🎼</div>
|
||||
<h3>Maestro</h3>
|
||||
<p>The conductor you talk to in plain language. It decides which agent to run and explains the result.</p>
|
||||
</div>
|
||||
<div class="landing-bot-card">
|
||||
<div class="landing-bot-icon">🛡</div>
|
||||
<h3>Security</h3>
|
||||
<p>Checks every route guard, ownership rule, and input limit across the app.</p>
|
||||
</div>
|
||||
<div class="landing-bot-card">
|
||||
<div class="landing-bot-icon">📜</div>
|
||||
<h3>Audit</h3>
|
||||
<p>Confirms every action that changes data leaves an audit trail.</p>
|
||||
</div>
|
||||
<div class="landing-bot-card">
|
||||
<div class="landing-bot-icon">📚</div>
|
||||
<h3>Docs</h3>
|
||||
<p>Keeps the documentation in step with the code, for the right audience.</p>
|
||||
</div>
|
||||
<div class="landing-bot-card">
|
||||
<div class="landing-bot-icon">♻</div>
|
||||
<h3>Quality</h3>
|
||||
<p>Removes duplication and enforces the project's naming and style rules.</p>
|
||||
</div>
|
||||
<div class="landing-bot-card">
|
||||
<div class="landing-bot-icon">🧪</div>
|
||||
<h3>Tests</h3>
|
||||
<p>Spots routes with no integration test and writes the missing coverage.</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<footer class="landing-footer">
|
||||
{% include "_footer_links.html" %}
|
||||
</footer>
|
||||
|
||||
Reference in New Issue
Block a user