ciaobot
AGENTS.md11 starsChanged 10 days agoApache-2.0View on GitHub
You are working on the Ciaobot app repository. This is the only agent rules file; Claude Code and opencode both load it. Before changing code: - Read the relevant sections of docs/ARCHITECTURE.md (system design) and docs/DEVELOPMENT.md (dev workflow). Both are 150–320 KB: search them, do not load them whole. - Before changing the PWA, read web/README.md and DESIGN.md, and keep DESIGN.md's tokens and interaction principles aligned with the code. - Keep changes scoped and covered by tests. - Do not…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository63 other files it gives its agents.
- ciao-dev-installSkill
- ciao-release-notesSkill
- ciao-releaseSkill
- ciao-upkeepSkill
- gws-sharedSkill
- gws-workflow-email-to-taskSkill
- gws-workflow-file-announceSkill
- gws-workflow-meeting-prepSkill
- gws-workflowSkill
- gws-workflow-standup-reportSkill
- gws-workflow-weekly-digestSkill
- persona-content-creatorSkill
- persona-customer-supportSkill
- persona-event-coordinatorSkill
- persona-exec-assistantSkill
- persona-hr-coordinatorSkill
- persona-it-adminSkill
- persona-project-managerSkill
- persona-researcherSkill
- persona-sales-opsSkill
- persona-team-leadSkill
- prSkill
- recipe-backup-sheet-as-csvSkill
- recipe-batch-invite-to-eventSkill
- recipe-block-focus-timeSkill
- recipe-bulk-download-folderSkill
- recipe-collect-form-responsesSkill
- recipe-compare-sheet-tabsSkill
- recipe-copy-sheet-for-new-monthSkill
- recipe-create-classroom-courseSkill
- recipe-create-doc-from-templateSkill
- recipe-create-events-from-sheetSkill
- recipe-create-expense-trackerSkill
- recipe-create-feedback-formSkill
- recipe-create-gmail-filterSkill
- recipe-create-meet-spaceSkill
- recipe-create-presentationSkill
- recipe-create-shared-driveSkill
- recipe-create-task-listSkill
- recipe-create-vacation-responderSkill
- recipe-draft-email-from-docSkill
- recipe-email-drive-linkSkill
- recipe-find-free-timeSkill
- recipe-find-large-filesSkill
- recipe-forward-labeled-emailsSkill
- recipe-generate-report-from-sheetSkill
- recipe-label-and-archive-emailsSkill
- recipe-log-deal-updateSkill
- recipe-organize-drive-folderSkill
- recipe-plan-weekly-scheduleSkill
- recipe-post-mortem-setupSkill
- recipe-reschedule-meetingSkill
- recipe-review-meet-participantsSkill
- recipe-review-overdue-tasksSkill
- recipe-save-email-attachmentsSkill
- recipe-save-email-to-docSkill
- recipe-schedule-recurring-eventSkill
- recipe-send-team-announcementSkill
- recipe-share-doc-and-notifySkill
- recipe-share-event-materialsSkill
- The first 60 shown.
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
18 rules. About 1 is common, 8 are distinctive, and 9 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 7
Read the relevant sections of docs/ARCHITECTURE.md (system design) and docs/DEVELOPMENT.md (dev workflow).
- Very specific: line 10
Before changing the PWA, read web/README.md and DESIGN.md, and keep DESIGN.md's tokens and interaction principles aligned with the code.
- Distinctive: line 12
Keep changes scoped and covered by tests.
- Distinctive: line 13
Do not add fallbacks or compatibility shims.
- Distinctive: line 17
Avoid new environment variables.
- Common: line 21
Do not commit secrets, private workspace data, or operator credentials.
- Very specific: line 41
Keep /api/* behind the signed session cookie, keep every /ws/* handshake same-origin-gated, and keep the loopback-only set …
- Distinctive: line 59
Run focused tests for the changed behavior.
- Distinctive: line 60
Run every gate CI blocks on before pushing, not just the tests.
- Very specific: line 92
Run one full backend suite and one frontend run at a time, here and in any gate script.
- Distinctive: line 124
Restarting the service: Never restart the running engine yourself.
- Very specific: line 136
Removing a background job: Add its id to job_runs.RETIRED_JOBS, or the debug report keeps listing its stale last run.
- Very specific: line 146
All pull requests target develop.
- Distinctive: line 147
Use plain, factual engineering notes in commits and pull requests.
- Very specific: line 167
Before planning, read docs/DEVELOPMENT.md, plus web/README.md and DESIGN.md for anything under web/.
- Very specific: line 172
After merging a batch into develop, watch the post-merge push run (gh run list --workflow ci.yml --branch develop --event push --limit 1).
- Very specific: line 177
Before queuing a PR whose diff touches path handling, the filesystem, subprocesses or Windows code, add the windows-full label and push …
- Distinctive: line 214
When you find a bug, test failure or worthwhile enhancement, explain it to the user and suggest filing it:
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ciao Contributor Guide
You are working on the Ciaobot app repository. This is the only agent rules file; Claude Code and opencode both load it.
Before changing code:
- Read the relevant sections of
docs/ARCHITECTURE.md(system design) anddocs/DEVELOPMENT.md(dev workflow). Both are 150–320 KB: search them, do not load them whole. - Before changing the PWA, read
web/README.mdandDESIGN.md, and keep DESIGN.md's tokens and interaction principles aligned with the code. - Keep changes scoped and covered by tests.
- Do not add fallbacks or compatibility shims. Delete dead or superseded code outright rather than leaving a code path "just in case". When removing a fallback would break an install that people already have, stop and ask the maintainer before removing it.
- Avoid new environment variables. Hardcode a sensible default as a
constant; if a value truly must vary per user, make it a Settings option
instead. Add an env var only when nothing else can work (secrets,
install paths, test isolation), and document it in
INTEGRATIONS.md. - Do not commit secrets, private workspace data, or operator credentials.
Project shape
- Backend: Python 3.12, Starlette + uvicorn. Frontend: Vue 3 + Vite + Pinia +
TypeScript in
web/. ciao/cli.pyis theciaoCLI;ciao/main.pyis the server entry.ciao/web/app.pylists every route as an explicitRoute(...); handlers live inciao/web/routes_*.py.ciao/providers/holdsclaude.py(Claude Agent SDK),opencode.pyand the sharedbase.py. One-shot model calls go throughproviders/oneshot.py; there is no Messages API and no provider-enforced structured output, so validate model JSON locally.ciao/stock/holds generic assets shipped in the wheel (skills, commands, schedules, workspace templates). User vaults and runtime data belong in a separate workspace, never in this repo.web/src/:components/(one SFC per pane, Settings panels insettings/),stores/(Pinia),composables/,lib/(pure helpers, no Vue imports). Tests sit in__tests__/beside the code, or asfoo.test.tsnext tolib/foo.ts.npm run buildwrites intociao/web/static/, which is gitignored.- There is no client/host split any more: one engine, one origin, one session.
Keep
/api/*behind the signed session cookie, keep every/ws/*handshake same-origin-gated, and keep the loopback-only set (_LOOPBACK_ONLY_APIinciao/web/auth.py) gated on the TCP peer. The boundary audit is indocs/REMOTE_BOUNDARY.md.
Commands
.venv/bin/pytest tests/test_x.py -q # focused; use the venv, not pytest on PATH
.venv/bin/pytest -n auto tests/ # full backend suite, about a minute
.venv/bin/mypy ciao
cd web && npm test # vitest
cd web && npm run build # vue-tsc + vite build
cd web && npm run test:e2e # Playwright
ciao dev # backend :8543 + Vite :5173
scripts/dev-commands.sh all # typecheck, coverage, lint, auditVerification
- Run focused tests for the changed behavior.
- Run every gate CI blocks on before pushing, not just the tests. CI's
blocking steps are, in order:
mypy ciao, which is easy to forget and fails the whole job. Watch forno-any-return: an attribute typedAny(for instance one wired after construction) makes any call on it returnAny, so returning that call straight out of a typed function is an error. Annotate the local instead.pytest -n auto tests/, the full suite, before claiming backend work is complete. A fake object in an unrelated test can break on a new attribute (adding a field to the/ws/eventssnapshot broketests/test_ws_auth.py, whoseSimpleNamespacestub had no such attribute), so a green focused run proves nothing about the suite.cd web && npm test, the full frontend suite. Needs Node >= 22.22.2;npx viteston an older Node silently skips component files while printing green. The floor is set by jsdom and lives in three places that must agree:web/package.jsonengines,SUPPORTED_RANGEinweb/scripts/check-node.mjs, anddocs/DEVELOPMENT.md.cd web && npm run buildafter frontend changes. PRs intodeveloprun these on Linux (linux-serverfor the backend,linux-webfor vitest and the build, in parallel). On Windows a develop PR runs only the fast gates: every module importing andpython -m mypy ciao(natively win32, so a POSIX-only call such asos.getuidorsignal.SIGHUPoutside a platform branch fails it). The Windowspytestandnpm testsuites and the macOS job (browser tests and an engine cold-start) run on the push todevelopafter merge and on release PRs intomain, so a PR going green is not proof those will. Path handling is the usual Windows break (ciao\xvsciao/x): compare paths withPath/as_posix(), not string literals. A test that hands a path to code that checks it is absolute builds it fromtmp_path:/nonexistent/xhas no drive and is relative on Windows.pip-audit,npm auditandnpm run lintare advisory in CI (|| true). Lint is still worth running; it just will not fail the build for you.
- Run one full backend suite and one frontend run at a time, here and in any
gate script. Two concurrent suites starve the machine and time out the 20 s
component tests (
SettingsFsScope), which reads as a red gate. A single failure is re-run (--lf) before it is called red. Timing tests assert relative behaviour with a small absolute allowance, not a fixed millisecond budget a loaded machine can miss. - Assert a guard where it acts, not only in the finished output. When a change bounds, redacts, filters or fences untrusted text, the test should observe the value at that seam (what is handed to the fence, filter or builder), and an ordering-sensitive filter needs more inputs than its limit so that reversing "filter then limit" fails the test.
- Some docs are checked by tests, so new code often needs a doc edit:
- a new route in
app.pygoes inPWA_API.md. A new POST/PATCH/DELETE/api/*route also needs an entry under## Agent recipesthere, or a place inBROWSER_OR_INTERNAL_ROUTESintests/test_pwa_api_docs.py; - a new
CIAO_*env var goes inINTEGRATIONS.md(tests/test_env_vars_documented.py); - a new module under
ciao/goes indocs/ARCHITECTURE.md's repo layout (tests/test_architecture_doc.py); - Windows installer or service changes go in
docs/WINDOWS.md(tests/test_windows_docs.py).
- a new route in
- For UI changes, verify keyboard focus, browser zoom, and 44px mobile touch targets. Every new feature must be visually inspected in the browser before pushing.
- Workspace shortcuts map unmodified
1–9to the visible sidebar order and must remain inert while a text field is focused. The Settings keyboard shortcuts card can disable or rebind them; preferences are shared through the engine. Enter-to-send is also shared, but touch keyboards always insert a newline. Preserve picker precedence and IME composition handling. - OpenCode provider changes must preserve the V2-only 2.0.16+ contract. Replay the V2 fixtures and run one tiny real turn against the installed OpenCode 2.x server; do not restore V1 route or response-shape fallbacks.
Common mistakes
- Restarting the service. Never restart the running engine yourself; it cuts off the PWA session you may be talking through. The user deploys from Settings.
- Treating this checkout as the live install. An installed engine runs its own released copy. Never apply a develop-only migration or schema change to a live workspace.
- Scripts run outside pytest.
tests/conftest.pypoints home,CIAO_MEMORY_DIRand LaunchAgents attmp_path. A harness outside pytest must setCIAO_MEMORY_DIRandCIAO_LAUNCH_AGENTS_DIRitself, or it overwrites the real index and LaunchAgent. - Deleting a module.
mypy(ignore_missing_imports = true) and pytest both stay green on leftover imports, function-local ones especially. Grep for the module name and import everyciaomodule before calling it done. - Removing a background job. Add its id to
job_runs.RETIRED_JOBS, or the debug report keeps listing its stale last run. - Worktrees.
web/node_modulesdoes not come along; symlink it from the main checkout and delete the symlink beforegit add, since.gitignoredoes not match a symlink. - Shared checkout. Other agents may be editing
developat the same time. Work on a branch offdevelop, preferably in a worktree, and checkgit statusfor files you did not touch before committing.
Branching and releases
- All pull requests target
develop. Only the admin creates releases fromdevelop. - Use plain, factual engineering notes in commits and pull requests.
docs/UPKEEP.mdis the watchlist of topics we keep an eye on, with the last-checked date and the decision. Add a row in whatever PR you are already in when you notice something worth watching; a stale date on an unchecked row is worse than no date. The checks themselves are in the/ciao-upkeepskill./ciao-releasedoes not fix things: a defect found during a release becomes an issue, fixed ondevelopbefore the next cut.
Loop engineering notes
Facts the user-level loop-engineering skill (~/.claude/skills) reads from
this file; the gates are the ones under Verification.
- PR target is
develop.Closes #Ndoes not auto-close on a develop merge; close issues explicitly: "Merged into develop via #<PR>(<sha>). Ships in the next release." - Branch prefix:
raffaelefarinaro/issue-<N>-<slug>. - Gates run from a worktree with the main checkout's venv, which is an
editable install of
~/repos/ciaobot: always setPYTHONPATH=$PWD(PYTHONPATH=$PWD ~/repos/ciaobot/.venv/bin/python -m pytest -n auto tests/). - Symlink
web/node_modules(anddesktop/runtimewhendesktop/changes) from the main checkout; delete both before every push. - Before planning, read
docs/DEVELOPMENT.md, plusweb/README.mdandDESIGN.mdfor anything underweb/. - New issues:
[Bug]→ labelbug,[Feature]→enhancement(see theciao-supportskill).report-labelled issues are auto-opened and may be noise: flag, don't drop.not_readyissues are skipped by the backlog loop. - After merging a batch into
develop, watch the post-merge push run (gh run list --workflow ci.yml --branch develop --event push --limit 1). The Windows suites and the macOS job run only there. If it goes red, open abugissue naming the failing tests and the merge that broke them, and fix it before merging more on top./ciao-releasewill not cut over a red run. Before queuing a PR whose diff touches path handling, the filesystem, subprocesses or Windows code, add thewindows-fulllabel and push once, so the full Windows suites run on the PR instead of after merge. - Hands-on device testing (a real Windows or macOS install) is for diffs that
touch the installers (
scripts/install*.sh,scripts/install.ps1), the service or scheduled-task code, engine update/migration, ordesktop/. Other issues rely on CI. - Security-sensitive diffs (ship fan-out plus a PR-scoped security review):
auth, secrets,
/apior/wsroutes,docs/REMOTE_BOUNDARY.md,desktop/(also run thedesktop/src-tauricommands indocs/DEVELOPMENT.md), release plumbing. - There is no
/code-reviewcommand for reviewer workers; review fromgit diff origin/develop...HEAD. - Other sessions merge into
developall day, so use the skill's serial merge queue. Thegates.shfor this repo runs, from the worktree root:PYTHONPATH=$PWD ~/repos/ciaobot/.venv/bin/python -m mypy ciao, the same with--platform win32,PYTHONPATH=$PWD ~/repos/ciaobot/.venv/bin/python -m pytest -n auto tests/(re-run only--lfbefore calling it red; latency tests flake under load), and, after symlinkingweb/node_modules,npm testandnpm run buildinweb/(remove the symlink afterwards). When the diff touchesweb/, it also runsnpm run test:e2eafter the build: the Playwright suite runs in CI only on the macOS job after merge, so a renamed button a spec still looks for reachesdevelopred (#2279). The terminal-renderer specs neednpm run build:harnessfirst. PWA_API.md,DESIGN.md(the Home paragraph),web/README.mdanddocs/ARCHITECTURE.mdare appended to by most PRs and conflict when two land together. Resolve by keeping both sides.- An engine booted inside a worktree can push memory-backup commits
(
backup <ts>Z,<branch> session commit <ts>) to the branch. Comparegit ls-remote origin <branch>with the reported sha and drop strays with--force-with-lease. - Live
ciao eval tasksruns (docs/TASK_EVAL.md) import the checkout under test through an editable venv. Run them from a detached worktree with its own venv, never from an issue worktree: the merge queue removes that worktree and every later run in the batch errors.
Reporting issues
When you find a bug, test failure or worthwhile enhancement, explain it to the user and suggest filing it:
gh issue create --repo raffaelefarinaro/ciaobot --title "[Agent] Brief summary" --body "Problem, repro steps, code locations, logs."<!-- ciao:memory:start cap=3000 -->Agent memory
<!-- ciao:memory:end --><!-- ciao:profile:start cap=1375 -->User profile
<!-- ciao:profile:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

