# Manual This is the hands-on manual for the [Claude Code setup](/docs/claude.html). It shows how to actually get work done with the [subagents](/docs/claude-agents.html), [commands](/docs/claude-commands.html), and [workflows](/docs/claude-workflows.html): adding features, changing existing code, fixing issues, verifying, testing, reviewing, and operating the app. Read the three reference pages for the full catalogue; read this page to learn the day-to-day flow. ## Mental model The setup gives you the same capability at three levels of control. Reach for the lowest level that fits the task. | Level | Primitive | Reach for it when | |-------|-----------|-------------------| | Command | `/name` (single context) | A discrete step: orient, validate, run, scaffold one thing. | | Workflow | `/name` (deterministic multi-agent script) | A repeatable, verified pipeline: build a feature, audit the diff. | | Subagent | `@agent-<name>` | One quality dimension, ad hoc, on a slice of code. | Two rules the whole environment honors, so you never have to ask: - **No command, workflow, or subagent performs a git write.** Committing is always your manual step. - **Nothing runs the test suite except the `/test` command**, which exists precisely so that running tests is an explicit choice you make. ## The core loop Almost every change follows the same five beats. The rest of this manual is variations on it. 1. **Orient** - `/explain ` or `/trace <route>` to learn the area and its fan-out. 2. **Build** - a build workflow (`/feature`, `/endpoint`, ...) or a build command, or hand edits. 3. **Run** - `/serve`, then `/screenshot` and `/api-test` to see it work. 4. **Check** - `/validate` for static checks, `/test` for the relevant tier. 5. **Review** - `/review` over the diff before you commit. ## Before you start ``` make install # create .venv if needed, editable install + playwright (first time) /serve # start the dev server on port 10500 and confirm health ``` `/serve` launches `make dev` in the background and uses `mole` to confirm the server answers. Leave it running; the verify commands target it. ## Recipe: add a feature A feature in DevPlace fans out across nine layers (form model, output schema, data helpers, route, view, Devii tool, API docs, SEO, tests). The `/feature` workflow drives all of them, then audits and tests itself. ``` /explain the gists area # optional: understand the pattern first /feature add a bookmark button to gists, owner-scoped, with a profile tab ``` What `/feature` does, in order: maps the area and the closest existing feature, plans a per-layer change list, implements it coherently in the repo, runs the validator and an import check, audits the result in parallel (`fanout-maintainer` + `security-maintainer` + `docs-maintainer`), fixes the gaps, and writes the missing integration tests. When it finishes: ``` /screenshot /gists # see the new UI rendered, verified by falcon vision /api-test the gist bookmark endpoints /test api # run the API tier /review # verified diff review before committing ``` ## Recipe: add one endpoint, one Devii tool, or one async job When you need just one route or capability rather than a whole feature, use the narrower build workflows. Each understands the closest existing pattern, implements across the touchpoints, verifies, and writes a test. ``` /endpoint POST /gists/{slug}/star to star a gist /devii-tool a tool to list the current user's bookmarks /job-service render a project to a PDF and offer it as a download ``` For the lighter, single-file recipes, use the build commands instead: ``` /docs-page bookmarks "Bookmarks" General # a new prose docs page /audit-event gist.bookmark for the new POST route /service a digest service that emails weekly activity ``` ## Recipe: update or change existing code When you are modifying something that already exists rather than adding new surface: 1. `/trace <route or feature>` - see every layer it touches, so you change all of them together (the cardinal failure mode here is updating one layer and forgetting a connected one). 2. Make the edit - by hand, or describe it to Claude in the conversation. 3. `/validate` - confirm the validator and the app import still pass and no prose em-dash slipped in. 4. `/screenshot` and `/api-test` if it touched the UI or an endpoint. 5. `/review` - the diff is checked across every dimension with adversarial verification before you commit. > Keep changes coherent across the fan-out. If you change a route's returned JSON, > update its `*Out` schema, its template, its API docs entry, and its Devii action in > the same change. `/review` will flag a half-migrated change, but it is cheaper to > get it right the first time. `/trace` tells you the full set. ## Recipe: fix an issue ``` /explain <the failing area> # understand the code path /test tests/api//<file>.py # reproduce with the focused test, if one exists ``` Fix the root cause (not the symptom), then: ``` /validate /test <the same target> # confirm green /review ``` Never weaken a test to make it pass. If a test exposes a real defect, the fix goes in the code, not the test - the `test-maintainer` and the `/test` command both enforce this. ## Verifying your work Verification is mandatory before you call anything done. Use the layer that matches what you changed. | You changed | Verify with | |-------------|-------------| | Any source file | `/validate` (validator + app import + em-dash scan) | | An HTTP endpoint | `/api-test <endpoints>` against the running server | | A page, layout, component, or responsive rule | `/screenshot <path>` (Playwright capture + falcon vision) | | Behavior covered by tests | `/test <tier or path>` | | A whole change set | `/review` (diff review, all dimensions, verified) | `/validate` is fast and should run after every edit. `/screenshot` and `/api-test` need `/serve` running first. `/test` is the only thing that runs the suite, and only because you asked. ## Reviewing and maintaining | Goal | Use | |------|-----| | Review the current uncommitted diff before committing | `/review` | | A full, verified audit of the whole codebase | `/fleet` | | Fan the ten dimensions out interactively (check or fix) | `/maintenance`, `/maintenance fix`, `/maintenance check changed` | | One dimension, ad hoc | `@agent-security-maintainer ...`, `@agent-docs-maintainer ...` | `/review` and `/fleet` adversarially verify every finding (a second agent tries to refute it) before reporting, so they are low-noise. `/maintenance fix` applies fixes serially in canonical order so two agents never edit the same file at once. ## Understanding the codebase | Goal | Use | |------|-----| | Architecture, data flow, and gotchas for an area | `/explain ` | | Where every layer of a route or feature lives, and what is missing | `/trace <route>` | | A deep read of one quality dimension | `@agent-<dimension>-maintainer` in report mode | These are read-only; they change nothing. ## Operating the app | Goal | Use | |------|-----| | Start the dev server and confirm it is healthy | `/serve` | | Capture and describe a page | `/screenshot <path>` | | Exercise endpoints from a JSON spec | `/api-test <endpoints>` | | Manage roles, news, attachments, Devii quota, zips, forks, containers | `/cli <args>` | `/cli` confirms any destructive action (clear, prune) with you before running it, since it acts on the live database. ## What the environment enforces Every build command, workflow, and subagent is bound to the project rules, so the output already conforms: - No comments or docstrings in source (only the file header and required tool docstrings); the `retoor <retoor@molodetz.nl>` header on new files. - No em-dash characters in authored prose; full Python type hints; `pathlib` over `os`; Pydantic input with explicit max lengths. - Reuse of the shared helpers (`templating.templates`, the `database.py` batch helpers, `respond`, the avatar and user partials, and the frontend `Http` / `Poller` / `JobPoller` / `OptimisticAction` / `FloatingWindow`). - The right auth guard on every mutating route; soft deletes; owner-or-admin delete authorization; DD/MM/YYYY dates. - The validator and the app import must pass before a build step finishes. It will not commit, will not run tests outside `/test`, and will not weaken a guard or a test to make a finding disappear. ## Troubleshooting | Symptom | Cause and fix | |---------|---------------| | `/screenshot` or `/api-test` says the server is down | Run `/serve` first; if the port moved, `/serve` scans 10500-10510. | | A build workflow reports unfixed audit gaps | The fix would have degraded behavior or broken a consumer; read the stated reason and resolve it by hand, then `/validate`. | | `/review` flags a finding you believe is wrong | It already survived an adversarial refutation; re-read the cited `file:line` with its context before dismissing it. | | A workflow run seems stuck | Run `/workflows` to watch live progress, pause, or stop it. | | You want only some dimensions | `/maintenance fix security,audit`, or call a single `@agent-...-maintainer`. | ## Cheat sheet | Task | Entry point | |------|-------------| | Understand an area | `/explain` | | Map a feature's layers | `/trace` | | Build a full feature | `/feature` | | Add one route / Devii tool / job | `/endpoint` / `/devii-tool` / `/job-service` | | Add a docs page / audit event / service | `/docs-page` / `/audit-event` / `/service` | | Start the server | `/serve` | | Verify a page / endpoint | `/screenshot` / `/api-test` | | Static checks | `/validate` | | Run tests | `/test` | | Review the diff | `/review` | | Audit the whole repo | `/fleet` | | Fix one dimension across the repo | `/maintenance fix` | | Management CLI | `/cli` |