Follow DEVELOPER_GUIDE.md for development conventions.
- Preserve behavior unless the user specifically authorizes a change.
- Refactoring or simplifying architecture does not authorize behavioral improvements or pre-existing bug fixes.
- Establish and verify existing edit/shared-state, persistence, refresh, validation, failure and navigation contracts.
- Do not rewrite tests or scenarios to justify changed behavior; leave work incomplete if parity is unresolved and report to user.
- Fix regressions while retaining the authorized implementation. Ask before a broad rollback.
- Keep changes focused. Before substantive renames, file moves, broad rewrites or other unrequested churn, ask with the proposed change, reason and smaller alternative. General refactoring instructions do not authorize that churn; specific approval persists.
- Rules go in this repo, never only in agent memory.
- Check the existing rules first so each rule is stated once.
- When retiring or consolidating a skill or doc, carry over every standing rule that still applies. Before editing, ask with the rules you propose to carry over (and where), and the content you propose to drop as specific to finished work.
- Preserve existing and imported documentation wording and structure. Change it only for factual corrections, necessary task-related updates or an explicitly requested rewrite; do not condense, reorganize or restyle it merely to improve presentation.
- We run Quepid in Docker primarily, don't run Rails and other build tasks locally.
- To set up the environment use:
bin/setup_docker. - Follow DEVELOPER_GUIDE.md — Running the app for the established startup workflow (
bin/docker s/bin/docker q).- Start the server when needed without asking for confirmation; reuse it when running.
- Do not change developer scripts or Compose configuration to work around agent execution mistakes.
- Do not stop (you may restart) the dev server unless the user explicitly asks. Leave it running across tasks.
- When a correction or lesson applies to how you work in this repo, fix it in the actual project file it belongs to (this file, a skill's
SKILL.md, a doc) — not only in your own private memory. - Complete requested batches, not convenient slices.
- When the user says to do the next step in an execution plan, execute the entire first incomplete batch and its acceptance criteria.
- A preparatory subtask is not completion. Do not present partial work as done, offer a commit message, or move the plan forward until all gates pass.
- If a concrete blocker prevents completion, record the exact blocker and smallest safe prerequisite in the plan, report that the batch is incomplete, and stop at that boundary.
- When the user says “continue”, “do it”, or “do more”, keep working through the current end-to-end batch and its verification gates.
- Do not stop after one extracted method, helper, or test to ask for another instruction, provide a commit message, or imply completion.
- Give progress updates at meaningful boundaries; only hand back when the batch is complete, or when a concrete blocker has been recorded and reported.
- Do not stage or unstage changes; ask before cherry-picking or merging.
- The user stages their own changes.
git cherry-pickis permitted only after asking for and receiving approval for the specific commits, including its index changes.git merge(e.g. bringingorigin/maininto a branch) is permitted only after asking for and receiving approval for that merge. Once approved, resolving its conflicts may usegit add/git rmon the merge's own paths. Ask rather than working around the rule with plumbing (git merge-treeplus a hand-writtenMERGE_HEAD): that leaves main's new files untracked, so agit commit -asilently drops them from the merge.- These exceptions do not authorize other index operations: no
git add,git rm,git mv,git reset,git restore --staged,git stashorgit stash pop, including to "undo" an accidental change to the index. - Files may show up staged without you doing anything, because the editor or the user staged them. Leave them alone and don't comment on what is staged.
- If you need a file removed, delete it with plain
rm. If you need to test old code, copy files to the scratchpad and back instead of stashing.
- Commit messages must describe the staged patch.
- Before proposing a commit message, inspect
git status --short,git diff --cached --stat, and the fullgit diff --cached(including staged renames and deletions); do not infer the commit scope from the latest task or from uncommitted changes.
- Before proposing a commit message, inspect
- In general, prefer using a single agent and not spawning sub-agents unless it will make a big difference. Even then, ask before spawning.
- Check before starting Docker.
- Inspect
docker compose ps -a appand the configured host port. The existing wrapper usesdocker compose run, so a healthy server may be namedquepid-app-run-*; an emptydocker compose ps appdoes not prove the server is stopped. Identify and reuse the actual server container. - The three app instances are permanent (current :3000, historical :3001, diff baseline :3003; see Screenshot capture and diffing).
- If the current server's container exists but is stopped, restart it with
docker start <name>. Only when no current-server container exists at all, create one withbin/docker q, without asking for confirmation. - Don't use
bin/docker sfor this: it runs with--rm, so stopping it deletes the container. Never invoke startup again just to run a command or test. Leave the server running across tasks. lsof -nP -iTCP:${APP_PORT:-3000} -sTCP:LISTEN.- A port-3000 bind error is not permission to stop anything, retry, or create a throwaway app. Resolve the exact owner and report it.
- Inspect
- Run commands inside the existing server container.
- Use
docker compose exec appfor the Compose service container, ordocker exec <actual-server-container-name>for a server started bybin/docker s/q. For example, run Rails tests in that container rather than starting a new app-run container. - While the diff baseline runs,
docker compose exec appcan land inquepid_app_ui_diff, which mounts../quepid-ui-diff-worktreeand its own database. Confirm the container mounting this checkout at/srv/appand usedocker exec <that-name>instead.
- Use
- For an authorized server image update, preserve the inspected startup command. Compose does not retain command overrides from a previous
run; the dev server usesforeman s -f Procfile.dev. Reuse the wrapper startup command with--no-depswhen dependency configuration has changed, so an app runtime update cannot also recreate a database service. - Wait for tests and other commands in the server container to finish before restarting it; a restart terminates those checks.
- Keep
appimmediately afterdocker compose execso the command matches the approved Docker execution rule. For environment overrides, usedocker compose exec app env KEY=value command ...; do not put-e KEY=valuebeforeapp. - Never use
bin/docker r,b, orc, or any otherdocker compose run, for agent commands.- Those wrappers create new throwaway containers. Use
execin the actual server so installed tools remain available throughout the session. - Restart a stopped server container rather than creating a new one. A new container is never the fallback, including when it is missing gems or other dependencies.
- Those wrappers create new throwaway containers. Use
- Container recreation between server sessions is acceptable; preserve host-mounted or volume-backed data.
- Do not pull images, rebuild Docker images, or run setup unnecessarily.
- If multiple servers exist, report their exact names and ask before stopping them.
- If Docker reports permission denied while connecting to its socket, rerun the same in-scope command once with the execution tool's elevated Docker-socket permission. Do not work around the failure with another container. If the elevated retry also fails, report the permission blocker and continue only with non-Docker checks that are safe and relevant.
- After CSS or vendor JS changes make sure you rebuild:
docker compose exec app yarn build# full frontend builddocker compose exec app yarn build:css# core.css / application.css onlydocker compose exec app yarn build:core# core case JS bundle
- Repository skills use the portable Agent Skills format: one
<skill>/SKILL.mdwith YAML front matter and instructions. - The source of truth is
.agents/skills/, the shared project skill directory used by Codex, Cursor, and Gemini;.claude/skillsis a symlink to it for Claude Code. - When adding or changing a skill, edit the file under
.agents/skills/and keep its instructions tool-agnostic unless a tool-specific step is essential.
- The core app uses Rails-rendered HTML, vanilla JS, StimulusJS, and Hotwire.
- JavaScript should own behavior, state, and genuinely dynamic repeated content only; do not put a mostly-static page or modal's HTML into
innerHTMLtemplate strings. - If a dynamic modal needs a shell, render the shell in ERB and populate its targets.
- Some features deliberately differ between the case workspace and the Rails pages (e.g.
share-case-corevsshare-case). Do not collapse them into one partial or interaction model without an explicit product decision; see Per-surface contracts.- Shared building blocks are fine when each surface keeps its own UX. Do not make one surface match the other unless asked. Verify and screenshot both surfaces; neither is the source of truth for the other.
- We are currently using Rails 8.1.4.1 and Ruby 4.0.7.
- Tests for Ruby are written in Minitest.
- Long-running work uses ActiveJob + SolidQueue, ActionCable pushes state to the frontend.
- Solr JSONP forces the case page to HTTP while the rest may be HTTPS. When touching
CoreControlleror SSL config, make sure to take this into consideration.- A protocol switch reloads the case page carrying try/wizard state in URL params (
searchEngine,searchUrl,apiMethod,fieldSpec), whichCoreController#populate_from_paramsrestores onto the try. Keep that round trip working.
- A protocol switch reloads the case page carrying try/wizard state in URL params (
- Turbo navigation: Drive is the default on ordinary Rails management/admin pages.
- Follow DEVELOPER_GUIDE.md — Turbo navigation for form responses, confirmations, caching, and opt-outs.
- The case workspace and standalone analytics retain full-page boundaries; see Turbo on the case page before changing either lifecycle.
- Use Node.js 26.x everywhere; follow the development prerequisites for the supported runtime and keep version selectors, Docker images, CI and Node type definitions aligned.
- Use yarn instead of npm for package management.
- When a change removes the last caller of a module, service or event, delete it in the same change: the module, its specs, and any emitters or listeners left with nothing on the other end. Do not leave unreachable code.
- Run JavaScript unit tests via
docker compose exec app yarn test:unit(Vitest — specs intest/javascript/, mirroringapp/javascript/, not colocated). - If a missing platform-specific native dependency prevents tests from starting, restore the locked dependencies inside the existing server container (
yarn install --frozen-lockfile --check-files) and rerun the checks before reporting a blocker. - Lint modern JS via
docker compose exec app yarn lint:jsordocker compose exec app rails test:eslint(seedocs/js_tooling.md). - Vitest PR policy: see DEVELOPER_GUIDE.md's "Vitest" section.
- Property-based tests (fast-check): when you add or materially change a pure
utils/orapi/function with a crisp invariant (round trip, aggregation, payload builder, ordering/concurrency), add or extendtest/javascript/utils/<module>_properties.test.js. Followdocs/js_tooling.md— "Property-based tests". Before finishing one, temporarily break the code under test and confirm the property fails, then restore it. Pin any shrunk counterexample as a plain example test. Don't use them for controllers or DOM code, and don't loosen a failing property without understanding its counterexample. - Cross-language contracts (Ruby ↔ JS): share a fixture under
test/fixtures/files/read by both Minitest and Vitest rather than adding a Ruby property-testing gem. If you changeCsvExportor the CSV import/export utilities, updatecsv_round_trip_cases.jsonand run both suites. - Mutation testing is always incremental: keep
incremental: trueinstryker.config.mjs(cachetmp/stryker-tmp/incremental.json); don't delete it or pass--forceunless asked, other than the single-file re-check indocs/js_tooling.md.
- Run Rails tests via
docker compose exec app rails test. - Before a Rails suite or fixture-loading check, inspect running test processes in the server container. Do not run concurrent suites against the same test database; wait for the existing run or use a disposable database with an explicit
RAILS_ENV=testand distinctDB_NAME, then remove only that database. - Scratch Ruby checks that load
test_helpermust explicitly setRAILS_ENV=testin the container command and verify it before loading fixtures; the server container inheritsRAILS_ENV=development. - Ruby mutation testing (Mutant,
config/mutant.yml) is always incremental: runbundle exec mutant run --since origin/main(compare againstorigin/, never localmain), inside the existing server container withRAILS_ENV=test. Mutant 0.17 has no cross-run result cache, so after a test-only edit re-run just the subjects that had survivors (--start-subject/--ignore-subject) and don't repeat whole-subject runs. Use a fullmutant run 'Subject*'only for a first baseline of unchanged code, and say so. Subjects are selected bycover 'Subject*'in the test class;jobs: 1because workers share the test database.
- Lint CSS via
docker compose exec app yarn lint:cssandyarn format:css:check, ordocker compose exec app rails test:stylelint(Stylelint + Prettier; config:.stylelintrc.json).
- For separate concurrent Playwright invocations, use distinct artifact/report directories and isolate writable auth/test state. Serialize invocations only while those resources remain shared; this does not restrict workers within one invocation.
- Run Playwright E2E tests via
docker compose exec app yarn test:e2e, withdocker compose exec app npx playwright install chromiumonce. Requires the app already running (see Docker above). - This is a separate, checked-in test suite under
test/playwright/— not the same thing as the Playwright MCP interactive tool described below. See DEVELOPER_GUIDE.md's "Playwright E2E" section for env vars and full details. - A spec for a changed flow performs its key action (share, save, import, rate → score badge updates), not only opening the modal. Add or extend one when none does.
- Any spec that creates a row in the shared dev DB (a user, a team, a case) must delete it in a
test.afterAll— See DEVELOPER_GUIDE.md's "Playwright E2E" section for the cleanup pattern to copy.
- Use the
manual-testingskill to run, sample, compare and record scenarios. - Before starting work that touches a tracked path, or when asked to do a manual testing pass: run
bin/manual_test_status(plainruby, no Docker/Rails boot needed) to see what's due — never run, stale (>policy.default_max_age_days, default 90), or whosepathschanged (committed or uncommitted) sincelast_run. - After changing code, check whether any tracked
pathsmatch your diff (bin/manual_test_statuswill surface it as "uncommitted changes in ..."). - Age-expired scenarios (flagged solely because
last_runis pastdefault_max_age_days, with no path change involved) are also yours to act on, not just report: when a session touching this repo notices one viabin/manual_test_status, drive it through Playwright MCP and updatetracking.ymlin that same session — don't wait to be asked, and don't leave it sitting as a report for a human to run later. - Feature parity, not just staleness: the checks above only re-verify scenarios that already exist. When a PR adds, removes, or materially changes user-facing functionality, also update the prose itself, in the same PR:
- add a new numbered scenario (with
paths) for new functionality, - delete/mark obsolete the scenario for removed functionality,
- and revise steps/expected-results for changed behavior.
- add a new numbered scenario (with
- Documentation goes in the
docsdirectory, not a topleveldocdirectory. - Keep provenance tags and the migration skill until remaining work is classified and closed. Archive completed plans only after their acceptance criteria pass; retain links to unresolved criteria and historical evidence.
- Every actionable item in
docs/todo/todo.mdmust carry a provenance marker:[MIGRATION]for defects introduced by or required to complete AngularJS removal,[MIGRATION-FOLLOWUP]for related cleanup that is not necessarily a regression, and[PREEXISTING]for defects that predate the removal. When reviewing migration work, use these markers to keep pre-existing defects out of the migration-fix scope; preserve or update the marker when moving or splitting an item. - To understand the data model used by Quepid, consult
./docs/data_mapping.md. - To understand how the application is built, consult
./docs/app_structure.md. - Documentation audience and authority: human-facing guides (DEVELOPER_GUIDE.md and dedicated guides under
docs/) are authoritative for shared development workflows and conventions. AGENTS.md and skills link to those guides rather than restating their rules. Agent-specific execution, approval, scope and recovery rules belong in AGENTS.md or.agents/skills/**/SKILL.md. - State the rule, not the incident. When you add a rule to a doc because something went wrong (a bug, a leak, a broken baseline), write the rule and, if genuinely non-obvious, why it holds — not a blow-by-blow of the specific occurrence (dates, counts, "this bit us on..."). Specifics like "16 leaked users" or a timestamp rot the moment the underlying state changes and read as clutter to a later reader who has no way to verify or care about that instance. Only keep instance detail when it's load-bearing — e.g. it teaches a non-obvious edge case the rule alone wouldn't convey.
- Before writing or reviewing Rails code (queries, validations, controllers, concerns, naming), follow AI coding style guide.
- Instead of treating true/false parameters as strings in controller methods use our helper
archived = deserialize_bool_param(params[:archived])to make them booleans. - Urls generated should never start with / as we need relative links.
- In Ruby we say
credentials?versushas_credentials?for predicates. - Prefer BS5 spacing utilities over one-off margins.
- We use .css, we do not use .scss.
Quepid does not use one global JS style. Write new code to modern conventions (below); do not reformat older lines or unrelated sections just to normalize style.
Modern JS (app/javascript/) — .prettierrc.json; full tooling in docs/js_tooling.md:
- Double quotes, no semicolons, no trailing commas (
trailingComma: "none"). - Prettier formats the whole lint scope (see
config/javascript_lint_scope.mjs) and runs in pre-commit. Before committing JS:docker compose exec app yarn format:js:checkanddocker compose exec app yarn lint:js. - ESLint covers the wider modern tree (
controllers/,modules/, entry bundles, etc.) and the JavaScript tests undertest/javascript/; follow the conventions above when you add specs.- Pre-commit runs ESLint and Prettier on staged files — run them yourself before finishing:
docker compose exec app npx eslint app/javascript/path/to/file.jsor tree-widedocker compose exec app yarn lint:jsandyarn format:js:check.
- Pre-commit runs ESLint and Prettier on staged files — run them yourself before finishing:
- Do not fall back to legacy habits (
var, semicolons) on Stimulus/importmap code. - Importmap bare paths —
import { apiFetch } from "api/fetch", not relative../api/.... Vitest resolvescontrollers/,utils/,stores/,api/, andmodules/by directory; only a new vendored package needs avitest.config.jsalias.
Ruby — .rubocop.yml (opposite comma rule from JS):
- Multiline hashes require a trailing comma (
Style/TrailingCommaInHashLiteral: comma). - Table-style hash alignment (
Layout/HashAlignment: table).
Stimulus / HTTP — DEVELOPER_GUIDE.md § Stimulus HTTP conventions:
- Server-owned URLs (
data-*-url-value,formTarget.action, or a*-url-template-valuewith a named placeholder for browser-only ids); JSON through theapi/jsonverb helpers (getJson/postJson/putJson/patchJson/deleteJson),apiFetchonly for non-JSON. See the guide section. getQuepidRootUrl()only when the server cannot pass the URL (e.g. redirect after import).
Vitest — vi.resetModules() + fresh import() for module singletons; @hotwired/stimulus is stubbed via test/javascript/support/stimulus_stub.js.
Playwright (test/playwright/*.ts) — TypeScript; linted by ESLint (typescript-eslint, eslint-plugin-playwright) and type-checked with docker compose exec app yarn typecheck:e2e; Prettier-formatted with the rest of the format:js scope.
- The core case UI (
app/views/layouts/application.html.erbcase branch,_case_head/_case_workspace) loadscore.css: npm Bootstrap 5 first, thenbase.css(page skin shared withapplication.css) and Quepid layers (core-additions.css— case-specific layout and skin, including selectors that use Bootstrap classes;navbar-brand.css— navbar brand skin;core-overrides.css— Bootstrap and Tom Select component overrides, including buttons, forms, tabs, modals and popovers.). - The core Stimulus/runtime bundle and
bootstrap_globalsprovide BS5window.bootstrapfor popovers, tooltips, dropdowns, accordion, tabs, modals, and similar. - The rest of the UI, admin included, loads BS5 via
application.css. Apart frombase.css,fonts.cssandnavbar-brand.css, the two are separate stylesheet worlds. When you add or change BS5-driven UI oncore(or more rules incore-overrides.css), use the existing core Bootstrap helpers/controllers as patterns and expect these traps: - Root
font-sizeand rem-based BS5 defaults.core-additions.csssetshtml { font-size: 87.5% }oncore(1rem = 14px, Bootstrap 3's base), so every rem-based BS5 default renders smaller than upstream.- Where a BS5 widget needs an exact size, override the relevant
--bs-*vars with px in compat CSS, and verify computed styles. Do not change root font-size casually without checking the wholecorestack.
- Where a BS5 widget needs an exact size, override the relevant
- Earlier-layer rules can win on shared selectors (e.g.
.popover { padding: 1px }from an old patch while BS5 puts padding on.popover-header/.popover-body). Reset bleed-through properties explicitly in the compat CSS. - Verify visually. Some of these traps produce invisible-but-present failures (popover element in DOM,
aria-describedbyset, but nothing visible). Static analysis won't catch them. Use Playwright MCP (or have the user screenshot DevTools' Computed panel for the popover element) and confirmdisplay,opacity,font-size, andtransformare sensible.
For the comparison viewer and capture history workflow, see Screenshot capture and diffing.
Run the Playwright MCP server with --isolated (e.g. claude mcp add playwright -s local -- npx @playwright/mcp@latest --isolated --output-dir <repo>/.playwright-mcp).
Each session then gets its own temporary browser profile, so several sessions
can drive browsers at once; each signs in afresh, and cookies don't persist
between sessions. Without --isolated, every session shares one persistent
profile, which Chrome locks to a single browser, and a second session fails
with "Browser is already in use". If that still happens (an older session
started before the change), don't skip required browser verification: ask the
user before stopping the browser holding that profile, stop only that one, and
record the blocker if permission is declined. A standalone Playwright script
launching its own headless browser is a fallback for captures, not for
interactive scenario steps.
Check the active client's MCP launch arguments include --isolated; repository
instructions alone do not configure the MCP server.
When a browser task finishes or stops at a blocker, call browser_close to
release that session's browser before handing back. Keep it open during ongoing
work across turns, and never close another session's browser without permission.
For any user-visible change, prove the behavior with Playwright MCP screenshots — never substitute prose or memory. App: http://localhost:3000; sign in with quepid+realisticactivity@o19s.com / password.
For a UI change, run the representative native Playwright visual suite following Routine visual regression checks. Refresh selected Current screen-history entries when capturing manual or migration evidence; historical source changes alone do not require renewing the corpus. Archive captures alone do not complete an explicitly requested Current update. If the original account or fixture is unavailable or unsuitable, use an equivalent account or fixture for the same scenario/state, document the differences, and record the new Current capture following Screen capture history. For a selected evidence refresh, do not leave Current stale solely because fixtures differ.
Apply the incremental sampling policy in DEVELOPER_GUIDE.md — Manual testing tracker to the captured flows. Use the actual running server's configured host port when it differs from the example URL.
The Playwright MCP tools may be exposed as deferred tools rather than a direct namespace. In that case, discover mcp__playwright__* from the tool catalog and invoke them through the tool orchestrator; do not treat an empty computer-surface/browser inventory as proof that Playwright is unavailable. Start with mcp__playwright__browser_tabs (action: "list"), then use the browser snapshot/click/fill/screenshot tools for the required flow.
Follow Screenshot capture and diffing — Comparison baselines and its capture and verification conventions.
When asked to review code, do not use subagents. Review the code in the conversation for bugs, errors, bad practices, regressions, lost functionality, and overengineering.
Review from these perspectives:
- modern Ruby on Rails, including Hotwire and Stimulus
- pragmatic engineering
- QA and regression risk
Report actionable findings first, ordered by severity, with file and line references when possible. If no issues are found, say so and summarize the verification performed.