- Applies to: all AI agents operating in this repository
- Canonical reference:
/AGENTS.md
Start here. Read the target, direct callers, and recent changes before editing; use the nearest current implementation as the pattern. Load references by task:
| Task or changed path | Read |
|---|---|
| App, View, template, or style work | JavaScript conventions and the owning feature |
| Marionette framework contracts | Skill setup and app integrations |
| Test authoring, review, or coverage | Validation, test evidence |
scripts/** |
Script rules |
packages/care-ops-five9/** |
SDK rules |
| Routing infrastructure or route definitions | Local routing contract |
| Data access, entities, or entity services | Entity service contract |
| Release, artifact, or environment setup | Development setup, deployment contract |
- System and developer instructions
/AGENTS.md- Scoped
AGENTS.mdfiles in subdirectories - Agent-specific companion docs such as
.github/copilot-instructions.md - General repo documentation
- Stack: Backbone, Marionette, Handlebars, SCSS, Vite, Cypress, npm workspaces.
- Core app code lives in
src/js/**; styles live insrc/scss/**; shared packages live inpackages/**. - Component Cypress specs live beside their owners as
src/**/*.component.cy.js. - E2E Cypress specs live beside their owners as
src/**/*.e2e.cy.js. - Fixtures and Cypress support files live in
test/fixtures/**andtest/support/**. - Repo aliases map
js/*tosrc/js/*injsconfig.jsonandvite.config.js.
- Stay in JavaScript. Do not introduce TypeScript or a new framework.
- Underscore is the default data-manipulation API, including where native equivalents exist. Do not replace it mechanically or flag its use as outdated.
- Define parent-owned template element selectors in the View's
uihash and access them throughgetUI; do not scatter selector queries through View methods. Do not bind a CollectionView'suito dynamic child View DOM: bound queries are snapshots. Keep child selectors and DOM mutation with their owning View. For UI binding behavior, seenode_modules/marionette/docs/api/shared/view-bindings.md#ui-bindings. - Prefer View
triggersoverevents, andtriggerMethodovertrigger. - Prefer composition when sharing application behavior: owned child apps for independent UI lifetimes, focused objects for stateful coordination, and functions for stateless work. Keep each domain's startup, refresh, and error policy explicit. Avoid application base classes that orchestrate subclass hooks or mixins that implicitly depend on the consuming app's fields. Modest duplication is preferable to a configurable lifecycle engine. Inheritance remains appropriate for a genuine specialization with a small, stable contract, such as a shared layout View.
- Choose app boundaries around independently managed UI or asynchronous workflows, not the existing directory or ownership tree. Let a visual app own a complete View in one Region; compose its internal controls as Views and focused objects rather than borrowing several regions from its parent. Give child apps explicit regions, data sources, and events rather than the parent layout View or callbacks that navigate its view tree. The page coordinates siblings and handles host destruction; Views own DOM, responsive layout, and focus within their own elements. Treat host lifetime, Application lifetime, and request lifetime separately: losing a host must invalidate its effects even when Application teardown is still pending.
- Keep
preinitializeandinitializeavailable as safe extension points on generic components. Put mandatory internal setup in the constructor when it must run even if a subclass defines either hook. - In async
prepareStart, pass the signal to requests and callsignal.throwIfAborted()after awaits before manually starting children or performing additional side effects. Superseded startup resolvesfalse; it does not undo manual work. - Colocate app-specific views, templates, SCSS, state, and Cypress specs under
src/js/apps/<domain>/<app>/**. - Keep domain-shared UI under
src/js/apps/<domain>/shared/**and cross-domain reusable UI undersrc/js/components/**. - Route data access through
src/js/entities-service/**instead of introducing ad hoc fetch logic elsewhere. - Import SCSS from the module that renders the view. Use BEM naming and do not style
.js-*hooks. - Keep feature flags easy to remove. Prefer guard-clause style branching.
- Never use
silent: trueto suppress model/state notifications. Seed initial values before observers attach, or compute a complete update and apply it with a normalset; use lifecycle ownership for cleanup. - Avoid prototype-method
.call()/.apply()chains outside constructor delegation. Prefer lifecycle hooks, supported extension points, or shared helpers; retain a parent-method call only when its behavior is required and no suitable hook exists. - Reuse existing utilities and workspace packages before adding dependencies.
- Internal fetch helpers require the options passed by their current callers. Do not restore hypothetical no-options consumers or removed configuration variants without finding an active caller.
- Use i18n keys that match the repo's existing formatjs-style naming.
Keep the reach of a change proportionate to the requested behavior. Follow behavior and state ownership, not file counts or directory boundaries. Shared changes are appropriate when the shared owner is responsible for the behavior; reuse existing contracts where they fit without hiding coupling in feature code or introducing a general framework just to accommodate one requirement.
Before implementing a change that introduces or materially changes any of the following, write a short impact note and carry it into the PR description's Impact section:
- State or coordination between owners, including shared events and subscriptions.
- Lifecycle responsibilities that cross owners: one owner announcing its startup or teardown for another, or taking over another's startup, cancellation, or cleanup.
- Behavior or persisted decisions derived from the current page, navigation, or browsing history.
- Effects on other consumers, on users for whom the feature is not enabled, or on global UI.
- Feature-specific policy placed in shared code, such as attribution, permissions, timing, or fallback behavior.
Name the behavior/state owner, affected producers and consumers, changed contracts, and relevant lifecycle or failure handling. Explain why the reach is needed and how changed and unaffected paths will be checked. Keep the note proportionate: a few sentences usually suffice; ordinary local changes that preserve existing contracts need no architectural essay. These triggers call for inspection and explanation, not automatic rejection of shared changes.
If implementation or review feedback expands the reach, update the note before continuing the expansion. For unresolved material scope, product, or ownership decisions, ask the requester when one is present; otherwise record the open decision in the PR's Impact section. Leave the affected change unimplemented until the decision is resolved, and continue independent work. Review feedback alone does not authorize broader behavior.
Use the upstream Marionette plugin's marionette skill for framework work.
After npm ci, run npm run setup:agents to expose the installed skill through
project-local links. Repeating setup is safe; it checks source presence and
preserves existing work. It does not verify package versions or documentation.
See setup and client verification for discovery limits.
If the plugin is unavailable, read the installed skill at
node_modules/marionette/skills/marionette/SKILL.md. It routes to documentation
matching this application's installed package and explains how to verify the
hosted documentation MCP. Plugin setup is documented in the installed
node_modules/marionette/docs/tooling.md#agent-installation.
Keep framework API and lifecycle guidance upstream. The integration choices below belong to this application.
- Runtime: the shared named exports from
marionette;src/js/base/setup.jsregisters Backbone for DataApi and StateApi, and Morphdom for DomApi. DOM event delegation uses Marionette's native default. - Renderer:
src/js/i18n/index.jsregisters the Handlebars renderer with@intltemplate data.src/js/app.jsimports both setup modules before app consumers. - Events/routing: use
Radiofrommarionette. The localsrc/js/base/event-router.jsextendsBackbone.Router;Backbone.historyowns URL/history handling. AppFrame and the local RouterApp/SubRouterApp classes own feature selection and loading; seesrc/js/base/routing.mdfor app policy. - Ownership entrypoint:
src/js/app.jsowns the#rootRegion, RootView, and bootstrap/dialer/app-frame child Applications. It configures shared popup Regions and owns its document/window listeners. Follow each feature's existing owner. - Patient lists: Schedule and Worklist keep their page controls and sidebar separate
from the results Application. Each page and results app extends
Appdirectly; shared selection and sidebar objects live undersrc/js/apps/patients/shared. Loading, grouping, sorting, and error policy stay with their feature. Page controls remain active while results load. - Verification: run this repo's commands from the root using the boundaries in Validation below; generic units use component specs, app flows use E2E.
These are deliberate, settled decisions. Do not suggest "modernizing" them in generated code, and do not flag them as issues, tech debt, or risks in review.
- The Backbone + Marionette stack is the permanent direction. The team maintains Marionette and Radio upstream. Never propose a framework migration or describe the stack as legacy.
- Marionette Radio stays synchronous. Do not propose Promise normalization, async middleware, or typed wrappers around Radio.
- String-based Radio request names (e.g.
'fetch:actions:model') are intentional: they keep test stubbing and console debugging trivial. Do not propose typed or constant-based replacements. - JavaScript, not TypeScript, per the guardrails above. Do not flag missing type annotations.
- Keep responses short and operational.
- Put actions and results before rationale.
- Avoid preamble, filler, and repetition.
- Explain only when tradeoffs, failures, uncertainty, or required evidence make it necessary.
- The import order and worked example is canonical for import ordering; load it when changing or reviewing imports.
- Within third-party imports, place
hbsfromhandlebars-inline-precompilebefore imports frommarionette. - Keep shared SCSS modules before every JavaScript dependency that may transitively import styles. Keep explicit domain SCSS after those JavaScript dependencies so domain rules win without added specificity.
- Handlebars spacing should stay tight and consistent:
{{ value }}and{{#if}}{{else}}{{/if}}. - Use
{{{ }}}only for trusted HTML. - Keep attribute order predictable in templates: class, id or name, src or for or type or href or value, title or alt, role or aria-*, then boolean attributes.
- Keep selectors shallow and prefer new blocks to deep nesting.
packages/care-ops-five9/sdk/**contains downloaded vendor code plus a local patch. Update it throughpackages/care-ops-five9/update-sdk.js, not by hand.scripts/**drives release, artifact, and deploy flows. Preserve CLI flags, output shape, and release semantics when editing.- Workspace packages under
packages/**are shared entry points for the app. Treat public APIs as stable unless the task explicitly changes them.
- Review the requested diff at its current head and inspect relevant callers. Read-only review permits authorized non-mutating checks and reproduction; source edits and publication require separate authorization.
- Put findings first, ordered by severity, with file/line evidence, triggering conditions, and impact. Report open questions and meaningful verification limits rather than unsupported defects.
- Compare the current-head diff with the declared impact using Change Reach. Trace relevant producers, consumers, and lifecycle owners; do not rely on the description or changed-path list alone. If a material change is undeclared or the note is stale, identify the missing behavior and consequence rather than treating missing prose as a correctness defect.
- Distinguish demonstrated defects from unresolved decisions and verification gaps. Report material boundary problems with evidence and severity; shared edits, abstractions, or file counts alone are not findings. Do not manufacture an architectural finding or rank one above a more severe correctness issue. Passing tests do not settle whether the behavioral reach is appropriate.
- Use the installed package's
node_modules/marionette/docs/api/application.mdfor preparation, cancellation, restart, and teardown contracts, andnode_modules/marionette/docs/api/shared/events.mdfor event ownership. Check the actual application callers against those contracts; the app-level reminders above also apply to reviewers without installed dependencies. - Put repo-specific risks first:
scripts/**release and deploy behaviorpackages/care-ops-five9/sdk/**and the SDK wrapper flowsrc/js/entities-service/**data-access boundaries- Marionette view patterns such as
ui,triggers, and scoped DOM behavior - template and SCSS coupling
- Keep review output concise and operational; use existing checks tied to the current head and authorized non-mutating reproduction to resolve evidence gaps.
- Review is most useful for non-trivial diffs, risky refactors, shared package changes, release or deploy changes, and behavior changes that may not be caught by lint.
- Review is less useful for tiny mechanical edits, pure copy changes, or changes where tests and lint already provide the meaningful signal.
- Use conventional-commit subjects,
type(scope): summarywith the scope optional — e.g.feat,fix,chore,refactor,perf,docs,test,build,ci,revert. - Keep PR descriptions short and operational, consistent with the Communication rules above.
- Open AI-authored PRs as ready for review, not as drafts.
- Apply the
ci:defer-cypresslabel when opening an AI-authored PR. The label keeps the required CircleCI workflow pending atCypress deferred - approve to runwhile normal review and revision continue. - Do not apply the label to ordinary human-authored PRs. Their Cypress jobs run automatically on every revision as usual.
- When review feedback is resolved, approve the CircleCI hold to run the full E2E, component, and coverage jobs for the current commit.
- Never merge while Cypress is held or without a passing Cypress result for the current commit. A new commit requires a new approval and Cypress result.
- Read
.circleci/README.mdbefore changing CircleCI pipeline definitions, config paths, or schedule triggers.
-
Cover behavior that users can exercise through the UI with E2E tests. Do not substitute component tests that stub application methods or state for those flows; reserve component tests for behavior that cannot be meaningfully exercised through the UI. Prefer extending an existing E2E scenario for the same flow; add a separate
specifyonly when the scenario needs its own isolation. -
Keep test changes focused on the edited behavior; do not combine coverage work with unrelated test consolidation. Match surrounding Cypress style: one command per line in chained steps, blank lines between steps, scoped
get/find, jQuery DOM subjects, and fixture callbacks that mutatefxthen return it. Do not wrap queued Cypress commands in unnecessarycy.then; useCypress.Promisefor explicit response gates. -
For changed application code, inspect branch coverage from E2E. Investigate unreachable branches as dead code and remove unsupported paths rather than adding synthetic app-method tests or coverage ignores. Generic/base contracts and services may use component tests. Do not add or broaden Istanbul ignores, coverage exclusions, or lower thresholds to make coverage pass. A defensive branch being difficult to test is not an exemption: obtain explicit maintainer approval for each proposed ignore, with its reachability analysis and reason. Removing a guard without a failing test does not prove it redundant; establish the supported caller and lifecycle contract first.
-
Require meaningful assertions for the changed behavior, not just execution of its lines or branches. For a new or changed regression test, make a narrow, reversible break in the targeted behavior and confirm the test fails at the intended assertion; restore the implementation and confirm it passes. A setup error, timeout before the assertion, or unrelated failure is not proof. Record the break, failing assertion, and restored result; keep this proof local and scoped; a broad mutation campaign requires its own agreed scope.
-
Keep regression setup small and specific: reuse established fixtures and helpers, and add only the gates or observations required to prove the contract. Feature-disabled fixtures must still be valid complete responses; omitting fields used by the enabled path can make a removed guard fail in setup instead of at the assertion.
-
Use realistic user-reachable E2E setup for UI behavior. Do not fabricate DOM geometry, force application state, or invoke private app methods to make a branch execute. For asynchronous absence, scrolling/focus, and lifecycle transitions, follow the evidence requirements in
test/README.md. -
Use
npm run lintfor code changes that affect files covered by the repo lint setup. -
Test the current product contract, not its implementation history. When a control, class, route, or behavior is removed, delete tests whose only purpose is to prove the obsolete implementation remains absent. Keep negative assertions only when absence is a current user-facing contract, such as permissions, availability, filtering, deletion, or a state transition.
-
Do not make incidental presentation a Cypress contract. Avoid exact assertions for alignment, spacing, typography, dimensions, colors, or computed CSS unless the presentation itself communicates product state or the geometry proves functional behavior such as a breakpoint mode, overflow prevention, reachability, popup direction, or layout stability during a state change.
-
Keep related Cypress scenarios consolidated when their setup can be reset explicitly. Do not recommend splitting solely because an earlier assertion failure skips later steps; that is normal test behavior. Flag actual leaked intercepts, clocks, or exception handlers instead.
-
During review, flag newly added visual assertions that would fail for an equally valid design implementation without changing state or behavior. Use design review or manual visual inspection for ordinary visual fidelity.
-
Iterate with single specs; they are much faster than the full suites:
- Component:
npx cypress run --component --spec src/js/base/routerapp.component.cy.js - E2E: build and serve the test app once (
npm run build -- --mode test, thennpx vite preview -m testin the background to serve on port 8090), thennpx cypress run --spec src/js/apps/<domain>/<app>/<spec>.e2e.cy.js - Do not pass
--specthroughnpm run coverage:e2e; npm appends it after the script'sexit, so the full suite still runs unfiltered and the script then exits 1 (exit: too many arguments).
- Component:
-
Before claiming UI behavior is validated, run the full suite relevant to the change:
npm run coverage:componentfor component behaviornpm run coverage:e2efor app flowsnpm run coverageruns both; do not stack it with the individual commands.
-
For full coverage verification, require 100% lines and branches across the complete configured aggregate scope, with covered/total counts and zero uncovered locations. A changed-file report or component-only report is not full coverage. Preserve the configured scope; see
test/README.mdfor collection boundaries and clean-run evidence. -
Report focused checks, full local validation, and remote verification separately, with commands, scope, exact tested commit, and any uncommitted changes. Remote results must match the current PR head and include all required workers and coverage finalization; a prior head's green result is stale.
-
Never claim validation passed unless you actually ran the command. Documentation-only changes need only appropriate cheap documentation checks; they do not establish runtime validation.
npm run dev— blocking dev server; not a validation step.npm run test— opens the interactive Cypress runner; never run it non-interactively (it hangs). Agents validate with the headless commands below instead.npm run lintnpm run coverage:component— headless, agent-safe.npm run coverage:e2e— headless, agent-safe; builds and serves the test app itself.npm run coverage— full suite, slow; headless.npm run stop— kills vite and clears its cache.
AGENTS.mdis the canonical source for repo-wide AI guidance and delegates scoped details to named references, including import ordering.- Companion docs should summarize or scope rules, not restate them with conflicting details.
- Copilot prompt surfaces intentionally inline a small subset of rules that they must see locally, such as import order and review-output constraints.
- Prefer deleting stale AI docs over maintaining low-signal indexes or checklists.
- This repo intentionally does not maintain a dedicated AI-doc audit script. Keep AI docs accurate through same-patch updates, targeted repo inspection, AI review when warranted, and human review.
- When an AI review comment is noise or an agent makes a repo-specific mistake these docs should have prevented, patch the doc that failed in the next related change rather than letting the failure repeat.