I soon will maintain this project with custom self made agents specifically for this platform to ensure quality.

I made a perfect agent a while ago and decided to let make claude make a bunch of versions of it to help me maintain the application consistently. Specific agents are always better than multi purpose. They will execute their task perfectly.

They do have all the knowledge of CLAUDE.md, AGENTS.md, README.md and every page under https://pravda.education/docs. This will guarantee success.

Here is the implementation plan that is generated based on my requirements:

agents.md - Autonomous Maintenance Agent Suite

This document is the design specification for a fleet of autonomous maintenance
agents that continuously enforce DevPlace's quality, consistency, reusability,
DRY principle, security and role rules, audit coverage, Devii capability parity,
and documentation accuracy. It is a companion to CLAUDE.md and AGENTS.md.

The fleet is not built yet. This file specifies what to build and how. The
single proven asset that every agent specializes is agents/agent.py, a
self-contained asynchronous ReAct agent that is already in the repository and
works well.

---

1. Purpose and scope

Every feature in DevPlace is one data source fanning out into several consumers.
A single route is rendered as HTML, served as JSON, called by the Devii agent,
documented in the API docs, audited, indexed for SEO, and described in
README.md, AGENTS.md, and CLAUDE.md. The cardinal failure mode is changing
one layer and forgetting a connected one: a route gains a field but the *Out
schema does not, a mutation ships without an audit record, an admin endpoint is
exposed to Devii members, a new mechanic is never documented.

A human cannot hold the whole fan-out in working memory across a codebase this
large. The maintenance fleet does. Each agent owns one cross-cutting dimension,
sweeps the entire repository for violations of that dimension, and either reports
them (CI gate) or fixes them autonomously and verifies the result.

Two facts shape every design decision below:

1. The codebase is huge. No agent may load the whole repository into one
   context. Every agent shards its target set and fans out with the parallel
   primitives that agent.py already provides.

2. The agents must be fully autonomous and deliver great quality. The default
   mode writes fixes and verifies them. A read-only mode exists for CI, but the
   product is an agent that corrects the repository without supervision.

What "great quality" means for these agents

• A fix never breaks the build. Every agent inherits a verification gate that
  runs hawk . and a clean application import after any edit, and refuses to
  declare success if either fails.
• A fix is minimal and idiomatic. Agents match the surrounding code's naming,
  comment density (none), and structure, exactly as CLAUDE.md requires of any
  contributor.
• A run is idempotent. Re-running an agent on an already-clean repository yields
  zero findings and zero edits.
• A run is auditable. Every run writes a machine-readable report and a human
  summary, so an operator can see precisely what changed and why.

---

2. Design principles

2.1 Shared core, thin agents

agents/agent.py is refactored into an importable agents/core/ package. Each
maintenance agent is a small module that supplies a specialized system prompt and
a handful of domain tools, then runs the proven loop. There is exactly one
engine. A bug in the loop, the LLM backend, or the tool dispatch is fixed in one
place and every agent benefits. This honors the CLAUDE.md rule that forbids
code duplication, while still satisfying the requirement that each agent be a
modified version of the proven agent.

2.2 Fix-default, check-capable

Every agent accepts --fix and --check.

• --fix (default): the agent edits source, runs its verification gate, and
  exits non-zero only when a finding could not be fixed or verification failed.
• --check: the agent reports findings without editing and exits non-zero when
  any finding exists. This is the CI gate.

2.3 Shard the huge codebase

No agent reads the whole repository at once. The shared sharding pattern
(Section 3.4) partitions an agent's scope into independent units (typically one
per router or per domain) and dispatches a sub-agent per unit using the existing
spawn / swarm / delegate primitives. BM25 retrieve locates relevant code
rather than reading everything. The top-level agent only synthesizes the
sub-agent reports.

2.4 Verify before declaring done

Every agent inherits the verification gate from core. After any file
modification it runs hawk . and python -c "from devplacepy.main import app".
Frontend-touching agents additionally balance-check JavaScript, CSS, and HTML via
hawk. The loop rejects a final answer that changed files without a successful
verification, exactly as agent.py does today (react_loop verification gate).

2.5 Honor the rules they enforce

The agents obey every CLAUDE.md rule they police: no git write operations, no
test runs unless the user explicitly asks, confirmation-gated destructive
operations, no em-dash, the mandatory retoor <retoor@molodetz.nl> file header,
no comments or docstrings in source. An agent that emitted a comment while
fixing a comment violation would be incoherent.

2.6 Every run leaves an artifact

Each run writes agents/reports/<agent>-<date>.json (machine-readable findings)
and agents/reports/<agent>-<date>.md (human summary). The orchestrator
aggregates these into one consolidated report.

---

3. Shared architecture

3.1 The core extraction

agents/agent.py (currently a single ~2330-line file) is decomposed into a
package. The line references below point at the current monolith so the
extraction is mechanical.

agents/
  core/
    __init__.py     # re-exports the public surface (tool, react_loop, AgentState, run_once)
    llm.py          # Backend dataclass, get_backends, llm_call, _call_backend        (agent.py 638-988)
    tools.py        # @tool registry, _build_function_payload, coerce/validate,
                    # execute_tool_call, _summarize_tool_result                        (agent.py 990-1094, 2066-2109)
    loop.py         # AgentState, react_loop, compact_messages, context_size gate      (agent.py 1149-1158, 2030-2206)
    fs_tools.py     # read_file, read_lines, write_file, create_file, edit_file,
                    # patch_file, list_dir, glob_files, grep, find_symbol,
                    # _record_read, _record_modification, _mutation_guard              (agent.py 1208-1510)
    exec_tools.py   # run_command, verify, stream_subprocess                           (agent.py 830-882, 1512-1560)
    web_tools.py    # web_search, deep_search, ai_search, fetch_url, download_file,
                    # describe_image, ChromeStealthClient                              (agent.py 1-636, 1560-1760)
    swarm.py        # delegate, spawn, swarm_wait/result/tail/kill/cleanup,
                    # CorpusIndex, retrieve                                            (agent.py 1760-2001)
    render.py       # MarkdownRenderer                                                 (agent.py 711-814)
    runner.py       # run_once, interactive, the shared argparse surface, amain        (agent.py 2247-2329)
    prompts.py      # the OPERATING PROTOCOL system prompt as a reusable template      (agent.py 2209-2245)
  base.py           # MaintenanceAgent base class (Section 3.2)
  agent.py          # thin shim: imports core, keeps the original general-purpose CLI working

The original agent.py keeps working as a general single-task agent. Its body
becomes a thin import of core.runner. This is verified by python agents/agent.py "echo hello" still running after the extraction.

The LLM backend, env vars, and fallback chain are inherited verbatim from
core/llm.py: the molodetz gateway is primary
(https://openai.app.molodetz.nl/v1, model molodetz, vision-capable), and
deepseek is the text-only fallback via DEEPSEEK_API_KEY. No agent reimplements
LLM access.

3.2 The MaintenanceAgent contract

agents/base.py defines the base class every specialist subclasses. It is the
only abstraction the agents share beyond core.

class MaintenanceAgent:
    name: str                       # "security", "audit", ...
    description: str                # one line, shown in --help and reports

    def system_prompt(self) -> str:
        # built on core.prompts.OPERATING_PROTOCOL plus the domain mandate,
        # detection rules, and fix rules of this agent
        ...

    def scope(self) -> list[ScopeUnit]:
        # the independent units this agent shards over, each a (label, globs,
        # focus) triple - typically one per router or per domain
        ...

    extra_tools: list                # domain tools registered on top of the core toolset

    def report(self, findings: list[Finding]) -> int:
        # writes agents/reports/<name>-<date>.{json,md}, returns the exit code
        ...

Shared behavior provided by the base class, identical for all agents:

• The CLI surface, parsed once in core/runner.py and reused by every agent:
  --check / --fix (default --fix), --scope <unit> (restrict to one shard
  for debugging), --max-iter, --no-color, -v/--verbose.
• A report_finding(severity, dimension, file, line, rule, message) tool
  registered on every agent, so the agent emits structured findings during a
  --check run without editing files, and the base class derives the exit code
  from the accumulated findings.
• The mode-aware mutation policy: in --check mode the core file-writing tools
  are disabled (they return a "check mode, reporting only" status), so an agent
  physically cannot edit in check mode.
• The verification gate wiring (Section 2.4).
• Report writing.

3.3 The report artifact

A finding is a flat record:

{
  "agent": "audit",
  "severity": "error",            // error | warning | info
  "dimension": "audit-coverage",
  "file": "devplacepy/routers/polls.py",
  "line": 88,
  "rule": "mutation-without-record",
  "message": "POST /polls/{uid}/vote writes polls.update but calls no audit.record",
  "fixed": true,
  "fix_summary": "added audit.record(request, 'poll.vote.cast', ...) after the update"
}

The JSON report is { "agent", "mode", "started_at", "finished_at", "findings": [...], "summary": { "errors", "warnings", "fixed", "unfixed" } }. The markdown
report is the same data rendered as a readable table grouped by file.

3.4 The sharding pattern (used by every agent)

This is the single mechanism that lets one agent cover the whole repository
without exhausting its context. It is documented once and reused.

1. The agent's first plan() call partitions scope() into N independent units.
2. For each unit it spawn()s a sub-agent with a focused sub-prompt: "Apply the
   <dimension> rules to <unit globs> only. Report findings; fix them if mode is
   fix; do not touch files outside this unit."
3. The top-level agent collects results with swarm_result / swarm_wait and
   tails progress with swarm_tail.
4. The top-level agent merges the sub-reports, deduplicates cross-unit findings,
   runs one final repository-wide verification (hawk ., app import), and writes
   the consolidated report.

Sub-agents that only need to locate code use BM25 retrieve rather than reading
whole directories. Edits within a unit are serialized inside that unit's
sub-agent so two sub-agents never write the same file; the scope partition is by
file, so units are disjoint by construction.

3.5 Exit-code contract

• --check: exit 0 only if there are zero findings; otherwise exit 1.
• --fix: exit 0 if every finding was fixed and final verification passed;
  exit 1 if any finding could not be fixed or verification failed.

The orchestrator returns the max severity exit code across the fleet.

---

4. The agent roster

Each agent below follows the same shape: Mandate, Scope, Detection (grounded in
real symbols and files), Fix, Domain knowledge it must carry, Custom tools,
Verification, Guardrails.

The first four are the agents the project owner named. The next six close the
remaining maintenance dimensions. Then comes the deterministic batch
orchestrator, and finally Maestro, the single conversational agent you talk to
that conducts all the others.

4.1 SecurityAgent - data and role security checker

Mandate. Guarantee that every state-changing action is correctly
authorized, every private resource is gated by the single canonical predicate,
every file mutation is read-only-guarded, and the input and output boundaries are
sanitized.

Scope. All of devplacepy/routers/, devplacepy/content.py,
devplacepy/project_files.py, devplacepy/models.py, devplacepy/utils.py,
devplacepy/services/devii/actions/, static/js/components/ContentRenderer.js,
devplacepy/seo.py. Sharded one router or module per unit.

Detection.

• Every @router.post / @router.put / @router.delete has the correct guard:
  require_user for member writes, require_admin for admin writes, or an
  explicit ownership comparison resource["user_uid"] == user["uid"] before
  edit and delete. A POST with no guard is an error finding.
• Every private-project read surface flows through the single
  content.can_view_project(project, user) predicate and none re-implements the
  owner-or-admin check inline. The surfaces to confirm are project detail, the
  file routes via project_files._load_viewable_project, zip enqueue, the
  listing, the profile project list, and the sitemap.
• Every file-mutating entrypoint in project_files.py calls
  project_files._guard_writable(project_uid). Any new mutating function that
  skips it is an error.
• Devii irreversible and destructive actions are present in the dispatcher's
  CONFIRM_REQUIRED set, and destructive shell commands match
  dispatcher.DESTRUCTIVE_COMMAND. A new mutating Devii action absent from the
  confirm set is an error.
• Input is Pydantic-validated with explicit max lengths (models.py Form
  models), uploads and downloads are slugified, and path traversal is blocked via
  pathlib rather than string joins.
• Passwords are hashed with pbkdf2_sha256 via passlib; no plaintext or weak
  hashing path exists.
• Capability URLs (zip and fork status and download) stay scoped only by the
  unguessable uuid7 and never widen to owner-bypassing lookups.
• The XSS control is intact: DOMPurify.sanitize runs on raw marked output in
  ContentRenderer.js before media injection and fails closed, and seo.py
_json_ld_dumps escapes <, >, & in JSON-LD.

Fix. Insert the missing guard, route the read through can_view_project,
add _guard_writable at the top of the mutating function, add the action to the
confirm set, add the missing max length or validator, or restore the sanitize
step.

Domain knowledge. content.can_view_project,
project_files._guard_writable and _load_viewable_project,
utils.require_user / require_admin, the dispatcher CONFIRM_REQUIRED and
DESTRUCTIVE_COMMAND sets, the models.py form conventions, the auth hashing in
utils.py.

Custom tools. list_mutating_routes(router_path) (parses decorators and
guards), find_read_surfaces(resource) (greps for project reads not flowing
through can_view_project).

Verification. hawk ., app import. Because security fixes can change
behavior, every SecurityAgent fix is also annotated in the report with the
before and after guard so an operator can review.

Guardrails. Never weaken a guard to make a finding disappear. If a route
intentionally has no guard (a documented public read), the agent records an
info finding and leaves it.

4.2 DocsAgent - documentation coverage and role-aware show/hide maintainer

Mandate. Keep CLAUDE.md, AGENTS.md, README.md, and the /docs pages in
exact agreement with the source, and keep role-based visibility consistent so
admin material is shown to admins and hidden from members and guests at both the
page and the section level.

Scope. CLAUDE.md, AGENTS.md, README.md,
devplacepy/routers/docs.py (DOCS_PAGES), devplacepy/docs_api.py,
devplacepy/docs_prose.py, devplacepy/docs_search.py,
templates/docs/*.html, cross-referenced against devplacepy/routers/*.py.

Detection.

• Every public or authenticated REST route has a docs_api.endpoint() entry in
  the correct group, with params and a sample_response. A documented route
  whose params drifted from the actual Form model is an error.
• Every prose page's factual claims match the code it describes (routes, env
  vars, defaults, behavior). A stale claim is an error.
• README.md reflects the current routes, env vars, dependencies, and
  user-visible features. AGENTS.md has a domain section for every mechanic.
  CLAUDE.md is updated only when a new architectural rule appears.
• Role-aware visibility uses the real mechanism found in code and uses it
  consistently:
  • Page level: admin-only pages carry "admin": True in their DOCS_PAGES
    entry. The router filters the sidebar to visible_pages = [p for p in DOCS_PAGES if not p.get("admin") or is_admin] and returns a 404 for a non-admin
    requesting an admin page, while docs_search still indexes admin pages for
    admins. An admin page missing the flag (so it leaks into the member sidebar)
    or a member page wrongly flagged admin is an error.
  • Section level within a page: prose templates receive the user context
    through docs_prose.render_prose and gate admin sections with Jinja
    {% if user %} / {% if user.role == 'admin' %}. Admin-only material in a
    page that is itself public must sit inside such a guard. Unguarded admin
    material on a public page is an error.

Fix. Add or repair the endpoint() entry, rewrite the stale prose,
add the missing README.md / AGENTS.md section, add the "admin": True flag,
or wrap the leaking section in the correct Jinja guard.

Domain knowledge. The DOCS_PAGES entry shape and admin / section
options, the docs_api.endpoint() signature and API_GROUPS structure
(including the admin group flag), docs_prose.render_prose and its user
context, the docs_search admin-aware indexing, and the server-side prose
rendering convention (markdown inside data-render is escaped, live demos sit
outside it).

Custom tools. route_inventory() (all routes with method, path, guard),
doc_inventory() (all endpoint() ids and prose slugs), diff_docs_vs_code()
(the join that surfaces undocumented routes and stale docs).

Verification. hawk ., app import, and a render check that every touched
prose template still renders (docs_prose.render_prose(slug, ctx) does not
raise).

Guardrails. DocsAgent never invents behavior. If code and docs disagree, the
source is authoritative and the docs are corrected to match the code, never the
reverse.

4.3 AuditAgent - audit log coverage maintainer

Mandate. Guarantee that every state-changing action in the application emits
a correct audit record according to the rules, that the event catalogue is
complete, and that denials and failures are logged with the right result.

Scope. All of devplacepy/routers/, devplacepy/content.py,
devplacepy/project_files.py, devplacepy/utils.py, the background services
under devplacepy/services/, the CLI, the Devii dispatcher, and the catalogue
file events.md. Sharded one mutation domain per unit.

Detection.

• Any mutation lacking an audit record on its success path is an error. A
  mutation is a @router.post / @router.put / @router.delete, a .insert /
  .update / .delete DB write, or a background-service, scheduler, or CLI
  state change. The record is audit.record(request, ...) in request contexts or
  audit.record_system(...) in request-less contexts.
• Guard and denial branches missing result="denied", and failure branches
  missing result="failure", are errors. Authentication failures and
  authorization denials must be logged.
• Event keys used in code but absent from events.md are errors, and a new
  domain not mapped in categories.category_for is an error.
• Double-counting is an error: the HTTP path and the Devii agent path for the
  same mutation must be disjoint (the dispatcher _audit_mechanic hook covers
  the agent path; the route covers the HTTP path), and a record gated on the
  action (so a logging failure would block the action) is an error - recording is
  always best-effort, wrapped in try/except, and never raises into the caller.

Fix. Add the recorder call at the mutation point with the correct event key,
origin, via_agent, and result, never gating the action on it; extend
events.md with the new key in the right domain; extend category_for for a new
domain; route the call through the existing DRY choke point (content.py, the
project_files.py helpers, routers/containers.py _audit_instance, the Devii
dispatcher._audit_mechanic) rather than scattering new call sites.

Domain knowledge. The services/audit/ package (store, categories,
record, query, service), the two recorder signatures
record(request, event_key, ...) and record_system(event_key, ...), the link
builders (actor, target, parent, project, ...), category_for and the
CATEGORY_BY_PREFIX table, the events.md catalogue of 155 keys across 26
domains and its naming convention {domain}.{action}[.{qualifier}], the allowed
result (success / failure / denied), origin, actor_kind, and
via_agent values, and the rule that Devii reuses the HTTP mutation's key with
origin=devii and via_agent=1 rather than minting a new key.

Custom tools. mutation_sites(module) (DB writes and mutating routes),
audit_sites(module) (existing recorder calls), catalogue_keys() (keys parsed
from events.md), code_keys() (event keys referenced in source), so the agent
diffs mutations against recorders and code keys against the catalogue.

Verification. hawk ., app import, and a catalogue consistency check
(every code key is in events.md, every events.md key has a category_for
mapping).

Guardrails. AuditAgent never removes an existing audit call to silence a
double-count finding without first confirming the two paths are genuinely
disjoint. It never makes the audited action depend on the recorder.

4.4 DeviiAgent - Devii capability and role-gated tool-list maintainer

Mandate. Guarantee that Devii can perform, via REST, everything the site
offers to the logged-in user's role, and that the tool list presented to a given
user exposes only the tools that user's role is permitted to call. A non-admin
must not even see that admin tools exist.

Scope. All of devplacepy/routers/ (the REST surface),
devplacepy/services/devii/actions/ (the catalog and per-handler action
modules), devplacepy/services/devii/registry.py, the dispatcher, and
devplacepy/services/devii/actions/spec.py.

Detection.

• Enumerate every REST route across routers/*.py and diff against
  CATALOG.by_name(). Every route a user could reasonably ask Devii to perform
  has a corresponding Action. A user-facing capability with no Devii action is
  a finding (severity depends on whether it is a read or a mutation).
• Each Action's requires_auth and requires_admin flags exactly match its
  route's guard. An admin-guarded route exposed as a non-admin Devii action is a
  security-grade error; a public route wrongly marked requires_auth=True is a
  capability gap.
• Catalog.tool_schemas_for(authenticated, is_admin) and the dispatcher's
  AuthRequiredError together guarantee role correctness: the schema for an
  admin tool is withheld from a non-admin (it is not in the returned list), and
  the dispatcher still raises AuthRequiredError if a non-admin names it anyway.
  The agent confirms both halves hold for every action. A tool whose schema leaks
  to the wrong role is an error.
• Irreversible Devii actions are in CONFIRM_REQUIRED.

Fix. Add the missing Action entry in the correct handler module with the
right method, path, requires_auth, and requires_admin; correct a
misaligned auth flag; and hand the documentation of the new tool to DocsAgent
(or add the docs_api entry directly when running standalone).

Domain knowledge. The Action dataclass in spec.py and its fields
(requires_auth, requires_admin, handler, method, path, read_only),
the 16 handler kinds, Catalog.tool_schemas_for filtering logic, the dispatcher
requires_auth / requires_admin enforcement raising AuthRequiredError, the
registry.py catalog assembly from the 14 action sources, and the
session-level tool_schemas_for(self.client.authenticated, is_admin) wiring.

Custom tools. route_inventory() (shared with DocsAgent), action_inventory() (every Action with its flags), role_visibility_matrix() (for each
role, the exact tool list tool_schemas_for returns, used to assert no admin
tool appears for a non-admin).

Verification. hawk ., app import, and a role-matrix assertion: for the
guest, member, and admin roles, the computed tool list contains no action whose
flags exceed that role.

Guardrails. DeviiAgent never grants a member access to an admin capability to
close a parity gap. Parity is bounded by role: the correct fix for an
admin-only capability with no member action is to leave it admin-only.

4.5 FeatureFanoutAgent - cross-layer completeness checker (the keystone)

Mandate. Enforce the CLAUDE.md "Anatomy of a feature" checklist as an
agent: for each route, every layer of the fan-out exists and agrees.

Scope. devplacepy/routers/, devplacepy/models.py,
devplacepy/schemas.py, devplacepy/services/devii/actions/catalog.py,
devplacepy/docs_api.py, devplacepy/seo.py, README.md, AGENTS.md.

Detection. For each route:

• Input has a models.py Form model declared as data: Annotated[SomeForm, Form()] (or a documented raw-form exception for file uploads).
• If the route serves JSON via respond(..., model=XOut), every context key the
  route returns exists on XOut. A key returned but absent from the schema is
  silently dropped and is an error.
• The route returns HTML and JSON through respond (or pure JSON via
  JSONResponse) consistently.
• A catalog.py Action exists if the route is something a user could ask Devii
  to do (delegated to DeviiAgent's inventory).
• A docs_api.py entry exists for every public or authenticated endpoint
  (delegated to DocsAgent's inventory).
• Public pages build base_seo_context (delegated to SeoAgent's inventory).
• README.md and AGENTS.md mention the feature.

Fix. Add the missing Form, add the missing key to the *Out schema, switch
the handler to respond, or trigger the responsible specialist's fix. This agent
is the umbrella: it cross-references the inventories produced by DeviiAgent,
DocsAgent, and SeoAgent and catches the "added a route but forgot the schema, the
tool, or the docs" class that no single specialist owns end to end.

Domain knowledge. The respond(request, template, ctx, model=XOut) helper
and its silent-drop behavior, the models.py / schemas.py conventions, the
feature workflow ordering in CLAUDE.md.

Custom tools. fanout_matrix() (one row per route, one column per layer,
each cell present or missing), which is the report's core artifact.

Verification. hawk ., app import, and a schema round-trip check that every
respond(model=XOut) route's returned keys validate against XOut.

Guardrails. When a layer is intentionally absent (an internal route with no
public docs, a route Devii should never call), the agent records an info
finding with the rationale rather than fabricating the layer.

4.6 DryAgent - duplication and reuse enforcement

Mandate. Eliminate duplicated logic and re-implementations of the canonical
shared utilities.

Scope. All of devplacepy/ and static/js/, templates/.

Detection.

• Backend: inline N+1 loops where a batch helper exists (get_users_by_uids,
  get_comment_counts_by_post_uids, get_vote_counts, load_comments,
  build_pagination, _in_clause); per-router Jinja2Templates instead of the
  shared templating.templates; inline avatar or user links instead of the
  _avatar_link.html / _user_link.html partials.
• Frontend: hand-rolled fetch instead of Http; bespoke polling instead of
  Poller; bespoke job polling instead of JobPoller; click-to-POST controllers
  not extending OptimisticAction; floating windows not extending
  FloatingWindow.
• General: blocks of duplicated logic that should be extracted into a shared
  helper (detected by structural similarity, then confirmed by the LLM).

Fix. Replace the call site with the existing utility, or extract a new shared
helper and route the duplicate call sites through it. Extractions follow the
project's small-files structure.

Domain knowledge. The catalogue of shared utilities in CLAUDE.md and
AGENTS.md ("Shared frontend utilities (DRY)"), the batch helpers in
database.py, the partials, the single templates instance.

Custom tools. duplication_clusters(scope) (groups structurally similar
spans), utility_bypass(util) (finds call sites that reimplement a known
utility).

Verification. hawk ., app import, and for frontend changes the JS parse
check. Behavior must not change; DryAgent reports a behavior-risk note on any
extraction that is not a pure move.

Guardrails. DryAgent never merges two spans that only look alike but differ
semantically. When similarity is below a confidence threshold it reports an
info finding for human review rather than auto-extracting.

4.7 StyleAgent - coding-rule compliance

Mandate. Enforce the explicit CLAUDE.md and AGENTS.md coding rules across
all source.

Scope. All of devplacepy/, static/js/, static/css/, templates/, the
CLI, and the agents package itself.

Detection (mostly deterministic, regex and AST).

• Forbidden naming prefixes and suffixes: _new, _old, _current, _prev,
  _next (outside iteration), _temp, _tmp, _v1/_v2/_v3, better_,
  best_, simple_, my_, the_, _data, _info, and the rest of the
  forbidden list.
• No comments or docstrings in source files.
• No em-dash anywhere (neither the character nor its HTML entity); use a hyphen.
• Full typing coverage on Python function signatures and variables.
• pathlib instead of the os module for paths.
• A fixed-key dict that should be a dataclass.
• No version pinning anywhere (pyproject, requirements, or inline).
• The mandatory retoor <retoor@molodetz.nl> header as the first line, in the
  correct comment style for the language, except where a shebang must lead.
• No magic numbers; named constants instead.
• No warnings.

Fix. Rename the symbol to an intent-revealing name (the LLM resolves the
intended meaning from context), strip the comment or docstring, replace the
em-dash, add the type annotation, convert os.path to pathlib, convert the
dict to a dataclass, remove the version pin, add the header, or name the
constant. Renames propagate to all references within the touched scope.

Domain knowledge. The full forbidden-name list and the good-name examples in
CLAUDE.md, the language style defaults (snake_case Python, camelCase JS), the
header rule.

Custom tools. forbidden_names(scope), missing_headers(scope),
emdash_scan(scope), magic_numbers(scope) - deterministic scanners whose
output the LLM then resolves into concrete renames and rewrites.

Verification. hawk ., app import, JS parse for frontend files. A rename is
verified by confirming the symbol no longer resolves at its old name and the
build is clean.

Guardrails. StyleAgent only touches code it is already editing for a finding;
it does not opportunistically restyle untouched code (the CLAUDE.md "refactor
only code that you touch" rule). A rename that would change a public API symbol is
reported, not auto-applied.

4.8 FrontendAgent - ES6, component, and CSS consistency

Mandate. Keep the frontend conformant to the project's strict ES6 and
component rules.

Scope. static/js/, static/js/components/, static/css/, the CDN script
tags in templates/base.html.

Detection.

• One class per ES6 module, instantiated and reachable via the global app,
  with Application.js as the root.
• Custom dp- components extend Component, self-register via
  customElements.define at the bottom of their file, render into the light DOM
  (no shadow root so global CSS applies), and inject their own CSS <link> on
  instantiation if absent.
• CSS uses variables (the design tokens), and pages are responsive down to very
  small phones.
• CDN scripts in base.html use defer or type="module" so the Playwright
  domcontentloaded wait does not time out.

Fix. Split a multi-class module, add the missing customElements.define,
remove a shadow root, add the dynamic CSS link injection, replace a hard-coded
color with a token, or add defer to a CDN script.

Domain knowledge. The Component base and its attr / boolAttr /
intAttr helpers, the components/index.js aggregation imported by
Application.js, the singletons (app.dialog, app.toast, app.contextMenu,
app.lightbox), the CSS token system.

Custom tools. module_class_count(file), component_contract(file) (checks
extends, define, light DOM, CSS link), css_token_usage(file).

Verification. hawk . JS, CSS, and HTML balance checks, app import.
Visual judgement (does the page look right) is out of scope for auto-fix and is
recorded as a finding; a future hook can attach falcon screenshot verification.

Guardrails. FrontendAgent does not introduce a JS framework, NPM, or a build
step (forbidden by CLAUDE.md). It works in plain ES6 modules only.

4.9 SeoAgent - SEO and sitemap coverage

Mandate. Ensure every public page is correctly described for search and
indexed where appropriate.

Scope. devplacepy/routers/, devplacepy/seo.py, devplacepy/routers/seo.py, templates/base.html.

Detection.

• Every public page builds base_seo_context(request, ...) and merges it into
  the template response.
• The right JSON-LD schema is emitted (WebSite, BreadcrumbList,
  DiscussionForumPosting, ProfilePage, SoftwareApplication).
• meta_robots is set, and the noindex rules hold (auth, messages,
  notifications are noindex,nofollow; profiles with fewer than two posts are
  noindex,follow).
• Indexable public pages appear in the routers/seo.py sitemap.

Fix. Add the missing base_seo_context call, the JSON-LD schema, the robots
directive, or the sitemap entry.

Domain knowledge. seo.base_seo_context and the schema generators, the
base.html SEO context keys, the robots.txt and sitemap.xml routes, the
JSON-LD escaping in _json_ld_dumps.

Custom tools. public_pages() (GET routes that render a page),
seo_inventory() (pages with base_seo_context), sitemap_inventory().

Verification. hawk ., app import, and a fetch-free render check that the
touched pages expose the expected SEO context keys.

Guardrails. SeoAgent never indexes a private or auth-gated page.

4.10 TestAgent - integration-test coverage

Mandate. Keep integration-test coverage in step with the routes and
features, writing tests that follow the project's required patterns.

Scope. tests/, cross-referenced against devplacepy/routers/.

Detection. Routes and features with no corresponding test in
tests/test_{area}.py. The project prefers integration tests over unit tests
and tests the interface and API.

Fix. Write the missing integration test following the required patterns:
every page.goto and page.wait_for_url passes wait_until="domcontentloaded";
selectors are scoped; a test that flips a global site_settings value restores it
in try/finally; the shared fixtures (alice, bob, app_server) are used.

Domain knowledge. The fixture stack (app_server, browser_context, page,
alice, bob), the required Playwright patterns, the _xdist_port isolation,
the DEVPLACE_DISABLE_SERVICES test mode.

Custom tools. untested_routes() (routes with no test referencing their
path), test_pattern_lint(file) (flags missing domcontentloaded, unscoped
selectors, unrestored globals).

Verification. hawk . and a clean import of the new test module. TestAgent
has a hard guardrail: it writes tests but never runs the suite unless the user
explicitly asks, in line with CLAUDE.md. Validation is by import only.

Guardrails. Never run make test or pytest. Never weaken an existing test
to make it pass.

4.11 Orchestrator - fleet runner

Mandate. Run the whole fleet, aggregate every report, and return one exit
code.

Behavior. Runs the agents in dependency order so cheap deterministic passes
precede expensive cross-layer passes:

1. StyleAgent, DryAgent (local, deterministic, reduce noise for later agents).
2. SecurityAgent, AuditAgent, DeviiAgent, SeoAgent (per-dimension correctness).
3. FeatureFanoutAgent (cross-layer, consumes the inventories above).
4. DocsAgent, TestAgent (describe and cover the now-correct surface).

It supports running a subset (--only security,audit) and --check across the
whole fleet. It merges the per-agent JSON reports into
agents/reports/fleet-<date>.json and a consolidated markdown summary, and
returns the max severity exit code.

Guardrails. The orchestrator runs one final repository-wide verification
(hawk ., app import) after the fleet completes and fails if the repository is
not green, even if every individual agent reported success.

4.12 Maestro - the conversational conductor (the single front door)

Mandate. Be the one agent the operator talks to. Maestro understands a
plain-language request about the project's health, decides which specialist or
combination of specialists answers it, runs them, and explains the result in
plain language. The operator never has to remember which agent owns which
dimension or which Makefile target to type; they talk to Maestro and Maestro
masters the rest.

Maestro is distinct from the Orchestrator. The Orchestrator (4.11) is a
deterministic, non-interactive batch executor wired into make agents-all and
CI: it runs a fixed, dependency-ordered fleet and returns an exit code. Maestro
is the interactive, human-facing conductor: it interprets intent, invokes one
specialist, several specialists, or the whole Orchestrator as appropriate, holds
a conversation across requests, and reasons about the findings. The Orchestrator
runs; Maestro talks and decides what to run.

Scope. Maestro implements no detection or fix logic of its own. Its scope is
the fleet itself. It owns routing, scoping, sequencing, and explanation; the
specialists own the work.

Interaction model. Maestro runs in the interactive REPL provided by
core/runner.py (interactive()), holding conversation context across turns. A
typical session:

• "Is my audit coverage complete?" - Maestro runs AuditAgent in --check,
  summarizes the findings, and offers to fix them.
• "Fix the docs for the projects router." - Maestro runs DocsAgent in --fix
  with --scope projects, then reports what changed.
• "Get the whole project in shape." - Maestro confirms, then invokes the
  Orchestrator (--fix) and relays the consolidated report.
• "Why did the security agent flag /projects/{slug}/fork?" - Maestro reads the
  last SecurityAgent report and explains the specific finding without re-running
  anything.
• "Just the read-only checks, no edits." - Maestro runs the relevant specialists
  in --check across the requested scope.

Routing logic. Maestro maps the request to the dimension and the agents:
security and role questions to SecurityAgent; audit and event-log questions to
AuditAgent; Devii capability and tool-visibility questions to DeviiAgent;
documentation and role-based show/hide questions to DocsAgent; "did I wire the
whole feature" questions to FeatureFanoutAgent; duplication and reuse to
DryAgent; naming, headers, em-dash, typing to StyleAgent; ES6 and component and
CSS to FrontendAgent; SEO and sitemap to SeoAgent; test coverage to TestAgent;
and any "everything" request to the Orchestrator. Ambiguous requests are
clarified in conversation before anything runs.

Mode policy. A conversational query defaults to --check (read-only,
explanatory). A fix runs only on an explicit instruction to fix. A repository-wide
fix (the Orchestrator in --fix) is confirmed with the operator before it
writes, in line with the destructive-operation guardrail. Maestro never silently
edits in answer to a question.

Custom tools. Each specialist is exposed to Maestro as a callable tool
(run_security, run_audit, run_devii, run_docs, run_fanout, run_dry,
run_style, run_frontend, run_seo, run_tests), each implemented by
spawning that agent's module with the requested mode and scope and collecting
its report via swarm_result; plus run_fleet (invokes the Orchestrator),
read_report(agent) (loads the latest agents/reports/<agent>-<date>.json to
answer follow-ups without re-running), and explain_finding(report, id) (turns a
structured finding into a plain-language explanation with the relevant code
reference). Maestro reuses the read-only core tools (read_file, grep,
retrieve) to ground its explanations in the actual source.

Domain knowledge. The roster and each agent's mandate and scope (this
document), the report artifact schema (Section 3.3), and the Makefile surface
(Section 5), so Maestro can translate between operator intent, the right agent,
and the right invocation.

Verification. Maestro itself does not modify source, so it carries no
verification gate of its own. Every fix it triggers runs inside the specialist it
called, which carries the gate; Maestro surfaces that specialist's verification
result verbatim and never reports success the specialist did not report.

Guardrails. Maestro confirms before any run that writes. It never bypasses a
specialist's own guardrails (it cannot make TestAgent run the suite, cannot make
DeviiAgent grant a member an admin capability, cannot make any agent perform a
git write). It never fabricates a finding; every claim it makes is backed by a
specialist report or a direct source read.

---

5. Makefile design

A target per agent plus the fleet runner. Each honors a CHECK toggle and writes
to agents/reports/.

CHECK ?=
MODE := $(if $(CHECK),--check,--fix)

.PHONY: security-agent audit-agent devii-agent docs-agent fanout-agent \
        dry-agent style-agent frontend-agent seo-agent test-agent \
        agents-all maestro

security-agent:
	python -m agents.security $(MODE)

audit-agent:
	python -m agents.audit $(MODE)

devii-agent:
	python -m agents.devii $(MODE)

docs-agent:
	python -m agents.docs $(MODE)

fanout-agent:
	python -m agents.fanout $(MODE)

dry-agent:
	python -m agents.dry $(MODE)

style-agent:
	python -m agents.style $(MODE)

frontend-agent:
	python -m agents.frontend $(MODE)

seo-agent:
	python -m agents.seo $(MODE)

test-agent:
	python -m agents.test_coverage $(MODE)

agents-all:
	python -m agents.orchestrator $(MODE)

maestro:
	python -m agents.maestro

Usage:

make security-agent           # autonomous fix (default)
make security-agent CHECK=1   # report only, non-zero exit on findings
make agents-all               # fix the whole fleet
make agents-all CHECK=1       # CI gate across the fleet
make maestro                  # talk to the conductor; it runs the rest

python -m agents.<name> resolves through agents/__main__.py, which maps the
module name to its MaintenanceAgent subclass and invokes the shared runner.
The maestro target opens the interactive conductor instead of running a single
dimension; it takes no CHECK toggle because it decides mode per request in
conversation (a one-shot prompt may also be passed as
python -m agents.maestro "is my audit coverage complete?"). Reports land in
agents/reports/.

---

6. Directory layout (final)

agents/
  __init__.py
  __main__.py          # dispatch python -m agents.<name> to the right agent
  agent.py             # preserved general-purpose CLI, now a thin shim over core
  base.py              # MaintenanceAgent contract
  core/
    __init__.py
    llm.py
    tools.py
    loop.py
    fs_tools.py
    exec_tools.py
    web_tools.py
    swarm.py
    render.py
    runner.py
    prompts.py
  security.py          # SecurityAgent
  audit.py             # AuditAgent
  devii.py             # DeviiAgent
  docs.py              # DocsAgent
  fanout.py            # FeatureFanoutAgent
  dry.py               # DryAgent
  style.py             # StyleAgent
  frontend.py          # FrontendAgent
  seo.py               # SeoAgent
  test_coverage.py     # TestAgent
  orchestrator.py      # Orchestrator (deterministic batch fleet runner)
  maestro.py           # Maestro (conversational conductor, the single front door)
  reports/             # <agent>-<date>.{json,md}, fleet-<date>.{json,md}

---

7. Build order and phasing

When the fleet is built (a later task, not this one), the recommended sequence
is:

1. Extract core/ from agent.py and prove the original CLI still works
   (python agents/agent.py "echo hello"). End green on hawk . and a clean app
   import.
2. Add base.py, the report_finding tool, the shared runner CLI, and the
   Makefile scaffold, validated with one trivial placeholder agent.
3. Build the four named agents (Security, Audit, Devii, Docs), each first in
   --check mode against the live repository to confirm its detection, then with
   --fix enabled.
4. Build FeatureFanout and the remaining specialists (Dry, Style, Frontend,
   Seo, Test).
5. Build the orchestrator and wire the dependency-ordered fleet run.
6. Build Maestro last, once the specialists and the orchestrator exist and
   produce reports, since Maestro routes to them and reads their artifacts.

Each phase ends green on hawk . and a clean application import.

---

8. Guardrails (apply to every agent)

• No git write operations of any kind.
• Destructive edits are confirmation-gated; an agent never deletes or overwrites
  a file it did not create without surfacing the conflict first.
• The test suite is never run unless the user explicitly asks; TestAgent writes
  tests but validates by import only.
• Agents obey the same CLAUDE.md rules they enforce: no comments, no em-dash,
  the retoor header, intent-revealing names.
• Best-effort and fail-closed: an agent bug must never corrupt source. Every
  write passes the verification gate, and the file-writing tools keep a
  per-file backup so a failed verification rolls the edit back.
• Idempotent: re-running an agent on a repository it has already fixed yields
  zero findings and zero edits.