@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Write a hound JSON spec and run it against the running dev server to verify API endpoints (status, partial body match, headers).
|
||||
argument-hint: <endpoints or feature to test>
|
||||
allowed-tools: Bash(mole *), Bash(hound *), Write, Read
|
||||
---
|
||||
API-test: **$ARGUMENTS**
|
||||
|
||||
1. Confirm the server: `mole check http://localhost:10500`. If it is down, tell me to run `/serve` first and stop.
|
||||
2. Write a hound spec to `/tmp/dp_api_test.json` in the form:
|
||||
`{"tests": [{"name": "...", "method": "GET", "path": "/api/...", "expect_status": 200, "expect_body": {...}, "expect_headers": {"content-type": "json"}}]}`
|
||||
covering the endpoints I named. `expect_status` is exact, `expect_body` is a partial dict match, `expect_headers` is a case-insensitive substring match. For authenticated routes, include the session or `X-API-KEY` header as needed.
|
||||
3. Run `hound /tmp/dp_api_test.json --base-url http://localhost:10500`.
|
||||
4. Report pass or fail per test with the response detail. All tests must pass for API work to be complete.
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
description: Add an audit-log event end to end - the events.md catalogue key, the category_for mapping, and the recorder call at the mutation point.
|
||||
argument-hint: <event.key for which mutation>
|
||||
allowed-tools: Read, Grep, Edit, Bash(python *)
|
||||
---
|
||||
Add the audit event for: **$ARGUMENTS**
|
||||
|
||||
Follow the audit-log design (`devplacepy/services/audit/`); confirm against the source first.
|
||||
|
||||
1. Pick or extend the event key in `events.md` (the authoritative catalogue at the repo root) in the correct domain.
|
||||
2. If it is a NEW domain, extend `category_for` in `devplacepy/services/audit/categories.py`.
|
||||
3. Call the recorder on the mutation's success path: `audit.record(request, event_key, ...)` in HTTP or WebSocket handlers, or `audit.record_system(event_key, ...)` in request-less contexts (services, jobs, CLI). On a guard or denial branch pass `result="denied"`; on a failure branch pass `result="failure"`.
|
||||
4. Route through the existing DRY choke point when one applies (`content.py`, the `project_files.py` helpers, `routers/containers.py` `_audit_instance`, the Devii dispatcher `_audit_mechanic`) instead of scattering call sites. The HTTP path and the Devii path for one mutation must stay disjoint (no double counting).
|
||||
5. Recording is best-effort: wrap nothing the caller depends on, and NEVER gate the audited action on the record succeeding.
|
||||
6. Validate with `python -m agents.validator` on the touched files and `python -c "from devplacepy.main import app"`.
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
description: Run the devplace management CLI with guidance on its subcommands (roles, api keys, news, attachments, devii quota, zips, forks, containers).
|
||||
argument-hint: <role|apikey|news|attachments|devii|zips|forks|containers ...>
|
||||
allowed-tools: Bash(devplace *)
|
||||
---
|
||||
Run: `devplace $ARGUMENTS`
|
||||
|
||||
The `devplace` CLI (entry point `devplacepy.cli:main`) exposes:
|
||||
|
||||
- `role get <username>` / `role set <username> <member|admin>`
|
||||
- `apikey get <username>` / `apikey reset <username>` / `apikey backfill`
|
||||
- `news clear` / `news sanitize`
|
||||
- `attachments prune`
|
||||
- `devii reset-quota <username>` / `devii reset-quota --guests` / `devii reset-quota --all`
|
||||
- `zips prune` / `zips clear`
|
||||
- `forks prune` / `forks clear`
|
||||
- `containers list` / `reconcile` / `prune` / `prune-builds` / `gc-workspaces`
|
||||
|
||||
If `$ARGUMENTS` is empty, run `devplace --help` and summarize the available commands. Otherwise run the requested command and report its output. These act on the live database; for anything destructive (clear, prune), state exactly what will be removed and confirm with me before running it.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Scaffold a new prose docs page - create the template under templates/docs/ and register it in routers/docs/pages.py, then validate.
|
||||
argument-hint: <slug> "<title>" [section] [admin]
|
||||
allowed-tools: Read, Grep, Edit, Write, Bash(python *)
|
||||
---
|
||||
Add a new prose docs page: **$ARGUMENTS**
|
||||
|
||||
Follow the docs convention exactly (confirm against `devplacepy/routers/docs/pages.py` and `devplacepy/routers/docs/views.py` first):
|
||||
|
||||
1. Create `devplacepy/templates/docs/<slug>.html` as a prose page: one `<div class="docs-content" data-render> ... </div>` containing GitHub-flavored markdown. The page is rendered server-side. Any example component markup INSIDE the data-render block must be HTML-escaped (`<dp-...>`); a live demo, if any, goes in a SEPARATE block OUTSIDE the data-render div with its own `<script type="module">`.
|
||||
2. Register it in `DOCS_PAGES` in `devplacepy/routers/docs/pages.py`: `{"slug": "<slug>", "title": "<title>", "kind": "prose", "section": SECTION_*}`. Add `"admin": True` for an admin-only page. If a new section is needed, add a `SECTION_*` constant and place it in the correct `AUDIENCES` group.
|
||||
3. Write accurate, professional content - confirm every factual claim against the source. No em-dashes, no AI disclaimers, dates as DD/MM/YYYY.
|
||||
4. Validate: run `python -m agents.validator` on the new template and on `pages.py`, run `python -c "from devplacepy.main import app"`, and confirm the slug is registered with no duplicate.
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
description: Explain a DevPlace subsystem, route, or file - read the relevant AGENTS.md section and the code, then summarize architecture, data flow, invariants, and entry points. Read-only.
|
||||
argument-hint: <area, route, or file>
|
||||
allowed-tools: Read, Grep, Glob, Bash(git log:*)
|
||||
---
|
||||
Orient me on: **$ARGUMENTS**
|
||||
|
||||
Investigate before explaining; confirm every claim against the source.
|
||||
|
||||
1. Locate the code: the router under `devplacepy/routers/`, the template under `devplacepy/templates/`, data helpers in `devplacepy/database.py`, schemas in `devplacepy/schemas.py`, and any service under `devplacepy/services/`.
|
||||
2. Read the matching domain section in `AGENTS.md` (the long-form companion) and the relevant part of `CLAUDE.md`.
|
||||
3. Trace the data flow: input model (`models.py`) -> router handler + guard -> data helper -> response (HTML via `respond` + template, JSON via the `*Out` schema), plus the Devii action (`catalog.py`) and API docs (`docs_api.py`) where present.
|
||||
|
||||
Then give a tight explanation:
|
||||
- What it does and where it lives, with `file:line` references.
|
||||
- The request pipeline and data flow.
|
||||
- Key invariants and gotchas (pull these from AGENTS.md).
|
||||
- The fan-out: which of the nine feature layers exist for it.
|
||||
|
||||
Do not modify anything.
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
description: Run the DevPlace maintenance agent fleet (10 quality dimensions) in check or fix mode, optionally scoped to changed files or a subset.
|
||||
argument-hint: "[check|fix] [changed] [comma,list,of,dimensions]"
|
||||
---
|
||||
|
||||
You are orchestrating the DevPlace maintenance fleet, the native Claude Code mirror of the `agents/` Python fleet. Each dimension is a project subagent under `.claude/agents/`. The fleet enforces ten independent quality dimensions across the `devplacepy/` package and `tests/`.
|
||||
|
||||
## Dimension to subagent map
|
||||
| Dimension | Subagent | Enforces |
|
||||
|-----------|----------|----------|
|
||||
| style | `style-maintainer` | CLAUDE.md/AGENTS.md coding rules (context-aware names, em-dash, typing, pathlib, headers) |
|
||||
| dry | `dry-maintainer` | duplication and reuse of canonical shared utilities |
|
||||
| security | `security-maintainer` | auth guards, project visibility, read-only guards, input validation, XSS |
|
||||
| audit | `audit-maintainer` | audit-log coverage and event catalogue |
|
||||
| devii | `devii-maintainer` | Devii route parity and role-gated tool visibility |
|
||||
| seo | `seo-maintainer` | SEO context, JSON-LD, robots, sitemap |
|
||||
| frontend | `frontend-maintainer` | ES6, dp- components, CSS tokens, deferred CDN scripts |
|
||||
| fanout | `fanout-maintainer` | cross-layer feature completeness |
|
||||
| docs | `docs-maintainer` | docs coverage and role-aware show/hide |
|
||||
| test | `test-maintainer` | integration-test coverage |
|
||||
|
||||
The canonical run order (matches `agents/fleet.py`) is: **style, dry, security, audit, devii, seo, frontend, fanout, docs, test**.
|
||||
|
||||
## Parse the arguments
|
||||
Arguments: `$ARGUMENTS`
|
||||
|
||||
- **Mode**: `fix` anywhere in the arguments means FIX mode; otherwise default to CHECK mode (read-only report).
|
||||
- **changed**: the word `changed` means scope the run to only the files git reports as modified or new under `devplacepy/` and `tests/`. Compute that set first with `git status --porcelain` and keep existing paths whose first segment is `devplacepy/` or `tests/`. If the set is empty, report "nothing to do" and stop. Pass the explicit file list into each subagent's prompt so it reports/fixes only within that set (it may still read other files for cross-reference).
|
||||
- **Subset**: any comma-separated dimension names (e.g. `security,docs`) restrict the run to those dimensions in canonical order. With no subset, run all ten.
|
||||
|
||||
## Execute
|
||||
1. Resolve the dimension list and mode from the arguments above.
|
||||
2. **CHECK mode**: launch every selected subagent concurrently (one `Agent` call per dimension in a single message). Each subagent runs read-only and returns its findings report. Tell each subagent explicitly: "Operate in REPORT mode. Do not modify any file." If `changed`, append the file list and: "Restrict findings to these files."
|
||||
3. **FIX mode**: launch the selected subagents **one at a time in canonical order** (never in parallel - parallel edits to the same file would conflict). Tell each: "Operate in FIX mode: apply minimal root-cause fixes per your doctrine, then run `python -m agents.validator .` and confirm it passes." Wait for each to finish before starting the next. If `changed`, append the file list and: "Restrict fixes to these files."
|
||||
4. Each subagent's final message is its report; it is not shown to the user directly, so collect them.
|
||||
|
||||
## Report
|
||||
After the fleet finishes, present a single consolidated summary to the user:
|
||||
- A table: dimension, error count, warning count, info count, and (fix mode) fixed count.
|
||||
- Then the notable findings grouped by dimension, each as `severity file:line - rule - message`.
|
||||
- A closing line with totals and, in fix mode, the validator result.
|
||||
|
||||
Do not run the test suite. Do not perform any git write operation.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Visually verify a page on the running dev server - capture it with Playwright, then describe it with falcon (AI vision). The mandatory visual check for any UI change.
|
||||
argument-hint: <path e.g. /feed>
|
||||
allowed-tools: Bash(mole *), Bash(falcon *), Bash(python *), Write, Read
|
||||
---
|
||||
Visually verify the page: **$ARGUMENTS** (default `/` if empty)
|
||||
|
||||
1. Confirm the server is alive: `mole check http://localhost:10500`. If it is down, tell me to run `/serve` first and stop.
|
||||
2. Capture the page with the installed Playwright (chromium, headless). Write and run a short Python snippet that navigates to `http://localhost:10500$ARGUMENTS` with `wait_until="domcontentloaded"` and saves a PNG to `/tmp/dp_shot.png` (sanitize any path into the filename).
|
||||
3. Describe it: `falcon describe /tmp/dp_shot.png`.
|
||||
4. Compare the AI description against the expected UI for that page and report whether it matches, with the screenshot path. If it does not match the intent, say what is wrong.
|
||||
|
||||
This is the required visual verification for any layout, styling, component, or responsive change.
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
description: Start the DevPlace dev server in the background and confirm it is healthy on port 10500.
|
||||
allowed-tools: Bash(make dev*), Bash(mole *), Bash(sleep *)
|
||||
---
|
||||
Start the dev server and verify it is up.
|
||||
|
||||
1. Launch `make dev` as a background process (uvicorn with reload on port 10500).
|
||||
2. Wait a few seconds for startup, then run `mole check http://localhost:10500` to confirm it responds.
|
||||
3. Report the URL `http://localhost:10500` and the health result. If port 10500 is busy or the check fails, run `mole scan localhost --ports 10500-10510` to locate the live port.
|
||||
|
||||
Leave the server running for the rest of the session. Do not start the production target (`make prod`).
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
description: Add a background BaseService - the service class with config_fields and run_once, registration in main.py, init_db columns if it stores state, and docs.
|
||||
argument-hint: <what the service should do>
|
||||
allowed-tools: Read, Grep, Edit, Write, Bash(python *)
|
||||
---
|
||||
Add a background service: **$ARGUMENTS**
|
||||
|
||||
Mirror an existing service - read `devplacepy/services/base.py` (BaseService) and `NewsService` first.
|
||||
|
||||
1. Create `devplacepy/services/<name>_service.py` extending `BaseService`: declare `config_fields` (the `ConfigField` specs are rendered on `/admin/services`), and implement `async def run_once(self) -> None` with extensive INFO and DEBUG logging and specific (not bare) exception handling. Full type hints; no comments or docstrings.
|
||||
2. If it stores state, ensure the table columns and indexes in `init_db()` (dataset auto-syncs the schema; `CREATE INDEX IF NOT EXISTS`; if the table is soft-deletable, write born-live `deleted_at`/`deleted_by` on insert and add the index).
|
||||
3. Register it in `main.py` startup: `service_manager.register(YourService())`, under the same `DEVPLACE_DISABLE_SERVICES` guard as the others. It then auto-appears on `/admin/services`.
|
||||
4. If it calls an LLM, default its endpoint to `config.INTERNAL_GATEWAY_URL` and authenticate with the internal gateway key, like the other AI consumers.
|
||||
5. Emit audit events via `record_system` for any state change it makes.
|
||||
6. Document it in `AGENTS.md` (Background services section) and in `README.md` if user-visible.
|
||||
7. Validate with `python -m agents.validator` on the touched files and `python -c "from devplacepy.main import app"`.
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
description: Run DevPlace tests - the sanctioned explicit-ask path. Run a tier, a file, or a single test with the correct flags. The agents never run tests themselves; this command is how you ask.
|
||||
argument-hint: [unit|api|e2e|all|<path::test_name>]
|
||||
allowed-tools: Bash(make test*), Bash(python -m pytest *), Read
|
||||
---
|
||||
Run the requested tests: **$ARGUMENTS**
|
||||
|
||||
Mapping:
|
||||
- `unit` -> `make test-unit`
|
||||
- `api` -> `make test-api`
|
||||
- `e2e` -> `make test-e2e`
|
||||
- `all` or empty -> `make test`
|
||||
- a path like `tests/api/posts/create.py::test_x` -> `python -m pytest <that> -v --tb=line -x`
|
||||
|
||||
Tests run serially on port 10501 with a tempfile SQLite DB and `DEVPLACE_DISABLE_SERVICES=1`. This command is the one sanctioned way to run them (the subagents and workflows never do).
|
||||
|
||||
Report results clearly. On a failure, show the relevant output, and if a browser (e2e) test failed, point me at the screenshot under `/tmp/devplace_test_screenshots/`. Never weaken a test to make it pass; if a test reveals a real bug, report it - do not edit the test.
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
description: Trace a DevPlace route or feature across the full nine-layer fan-out and report where each layer lives and which are missing. Read-only.
|
||||
argument-hint: <route path or feature name>
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
Trace the complete fan-out for: **$ARGUMENTS**
|
||||
|
||||
Locate each layer and report it as `layer -> file:line`, or `MISSING`:
|
||||
|
||||
1. Form model - `devplacepy/models.py`
|
||||
2. Output schema (`*Out`) - `devplacepy/schemas.py`
|
||||
3. Data helper(s) - `devplacepy/database.py`
|
||||
4. Route handler + guard, and its mount - `devplacepy/routers/...` + `devplacepy/main.py`
|
||||
5. Template + CSS + JS - `devplacepy/templates/`, `devplacepy/static/`
|
||||
6. Devii action - `devplacepy/services/devii/actions/catalog.py`
|
||||
7. API docs entry - `devplacepy/docs_api.py`
|
||||
8. SEO context / sitemap - `devplacepy/seo.py`, `devplacepy/routers/seo.py`
|
||||
9. Tests - `tests/{api,e2e,unit}/<path>.py`
|
||||
10. Docs prose (if any) - `devplacepy/routers/docs/pages.py` + template
|
||||
|
||||
End with the MISSING layers this feature ought to have, judged by the fanout rules. An intentionally absent layer is fine - note why. Do not modify anything.
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
description: Run the mandatory DevPlace pre-completion verification on changed files - the validator, the app import, and an em-dash scan. Zero errors required. Never runs the test suite.
|
||||
allowed-tools: Bash(python *), Bash(hawk *), Bash(git status:*), Bash(git diff:*), Read, Grep
|
||||
---
|
||||
Changed files in the working tree:
|
||||
!`git status --porcelain`
|
||||
|
||||
Verify the work is complete and correct, following the DevPlace verification rule (zero tolerance):
|
||||
|
||||
1. For each changed or new file under `devplacepy/` or `tests/`, run `python -m agents.validator <file>` (it covers Python, JavaScript, CSS, and HTML/Jinja). Every file must report clean.
|
||||
2. Run `python -c "from devplacepy.main import app"` - it must import with no error.
|
||||
3. Grep the changed files for em-dash characters (U+2014 and U+2013) that are authored prose, and report any. Leave em-dashes that are data (replace/maketrans/regex targets, fixtures) untouched.
|
||||
4. Report a PASS or FAIL summary with the exact failures.
|
||||
|
||||
Do not run the test suite. Do not perform any git write.
|
||||
Reference in New Issue
Block a user