Manual

This is the hands-on manual for the Claude Code setup. It shows
how to actually get work done with the subagents,
commands, and workflows:
adding features, changing existing code, fixing bugs, 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 <area> 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      # editable install (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 a bug

/explain <the failing area>          # understand the code path
/test tests/api/<area>/<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 <area>
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