feat: add six specialized Claude agent definitions under .claude/agents for audit, devii, docs, dry, fanout, and frontend maintenance

2026-06-13 18:34:47 +00:00
parent ede7a863b7
commit de745f7a75
107 changed files with 2611 additions and 517 deletions
@@ -0,0 +1,84 @@
+<div class="docs-content" data-render>
+# Getting started
+
+A single path from a fresh clone to a running instance and your first change. If you
+only want to call the API, jump to [Authentication](/docs/authentication.html) and the
+[API reference](/docs/conventions.html) instead - this page is for working on DevPlace
+itself.
+
+## Run it locally
+
+DevPlace is a Python package. Install it editable, then start the reloading dev server:
+
+```bash
+make install      # pip install -e .
+make dev          # uvicorn --reload on port 10500
+```
+
+Open `http://localhost:10500`. The first account you register becomes the administrator.
+`make prod` runs the two-worker production server on the same port.
+
+## Repository layout
+
+```
+devplacepy/        the application package
+  main.py          mounts routers, middleware, startup/shutdown
+  routers/         one directory per URL domain (mirrors the endpoint tree)
+  templates/       Jinja2 pages; static/ holds CSS and ES6 modules
+  database.py      SQLite via dataset; query and batch helpers
+  models.py        Pydantic Form models   schemas.py  *Out JSON models
+  services/        background + async-job services, Devii, containers
+tests/             unit / api / e2e, mirroring the route or source path
+agents/            autonomous maintenance fleet (developer tooling, off-limits)
+```
+
+## How a feature is shaped
+
+Every feature is **one data source with four faces**: the same route handler is rendered
+as HTML, served as JSON, called by the Devii assistant as a tool, and described in the API
+docs. The usual failure is changing one face and forgetting a connected one. Work in this
+order so nothing is dropped:
+
+1. **Data** - query helpers in `database.py`, a `Form` model in `models.py`, an `*Out`
+   model in `schemas.py`.
+2. **Server** - the handler in `routers/`, with the right guard (`get_current_user` for
+   public reads, `require_user`, `require_admin`); return both faces via
+   `respond(request, template, ctx, model=XOut)`.
+3. **View** - extend `base.html`; one ES6 class per file under `static/js/`.
+4. **Agent and docs** - add a Devii tool when a user could ask for the action, an
+   `endpoint()` entry in `docs_api.py`, and update `README.md` and `AGENTS.md`.
+
+## Validate before you finish
+
+Never declare work done with a broken import or a validation error:
+
+```bash
+python -c "from devplacepy.main import app"   # must import clean
+make validate                                  # Python, JS, CSS, templates
+```
+
+Run the maintenance fleet over your changed files to catch style, duplication, and
+documentation drift before review:
+
+```bash
+make maintenance        # read-only report on changed files
+make maintenance-fix    # apply fixes to changed files
+```
+
+See [Running the agents](/docs/maintenance-usage.html) for the full fleet. Tests live in
+`tests/` and run with `make test-unit`, `make test-api`, and `make test-e2e`.
+
+## Read next
+
+- [Conventions and Errors](/docs/conventions.html) - the rules every endpoint shares.
+- [Components overview](/docs/components.html) and the [design system](/docs/styles.html) -
+  the frontend building blocks and styling rules.
+- [Maintenance agents](/docs/maintenance-agents.html) - how the quality fleet keeps the
+  codebase consistent.
+{% if is_admin(user) %}
+- [Architecture overview](/docs/architecture.html) - the request pipeline, backend, and
+  frontend in depth.
+- [Development workflow](/docs/architecture-workflow.html) and
+  [Testing overview](/docs/testing.html) - the deeper contributor reference.
+{% endif %}
+</div>