AI & Developer Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The AI and Developer Guidelines establish a unified framework for maintaining the RoundingWell care-ops-frontend repository. These standards apply to all human developers and AI agents operating within the codebase to ensure architectural consistency, security, and operational efficiency. The project utilizes a specialized stack consisting of Backbone, Marionette, Handlebars, SCSS, and Vite, managed via npm workspaces.
The guidelines prioritize Marionette patterns for view management, strictly decouple data access via a dedicated entities service, and enforce a 100% test coverage baseline. For AI agents specifically, a strict instruction hierarchy and communication protocol are defined to ensure safe and relevant code generation.
Sources: CLAUDE.md:1-12, README.md:1-15, AGENTS.md:1-12
AI Agent Operating Protocol
Instruction Hierarchy
AI agents must follow a specific priority list when processing tasks. Scoped instructions in subdirectories override general repository documentation but are subordinate to system prompts and the canonical AGENTS.md.
The diagram shows the order of precedence for instructions given to AI agents.
Sources: CLAUDE.md:14-22, AGENTS.md:14-22
Communication and Review
Agents are required to provide short, operational responses, placing actions and results before rationale. When reviewing changes, agents must prioritize repository-specific risks such as release/deploy behavior in scripts/** and data-access boundaries in src/js/entities-service/**.
Sources: CLAUDE.md:41-46, CLAUDE.md:57-70
Core Architecture and Guardrails
Development Stack
The application is built on a specific set of libraries that must be maintained without introducing new frameworks or TypeScript.
| Component | Technology |
|---|---|
| Framework | Backbone.js, Marionette.js |
| Extensions | Marionette.Toolkit, Backbone.Radio, Backbone.Store |
| Templating | Handlebars (precompiled) |
| Styling | SCSS (BEM naming convention) |
| Build Tool | Vite |
| Testing | Cypress (E2E/Component), Vitest (Unit) |
Sources: CLAUDE.md:24-30, README.md:110-150
View and Data Patterns
Developers must adhere to Marionette patterns by defining a ui hash and preferring triggers or triggerMethod over raw DOM events. All AJAX and data-fetching logic must reside within src/js/entities-service/** to maintain a clean separation of concerns.
This diagram illustrates the flow from UI interaction to data retrieval, emphasizing the role of the Entities Service.
Sources: CLAUDE.md:32-35, src/js/README.md:54-62, README.md:225-230
Code Standards and Conventions
Import Order
A strict import order is enforced to maintain module predictability and avoid circular dependencies.
- Polyfills and third-party libraries (e.g., Underscore, Marionette)
- Global SCSS or CSS modules
- Shared utilities and base classes
- Entities and service modules
- Apps and controllers
- Views and components
- Templates and final local style overrides
Sources: CLAUDE.md:48-55, src/js/README.md:4-39
Naming and Selectors
To decouple logic from presentation, specific selector prefixes and event naming conventions are required.
- JavaScript Hooks: Use
.js-*prefixed classes for DOM selection in views. Never style these hooks in SCSS. - State Selectors: Use
.is-*or.has-*for state representation (e.g.,.is-active). - Event Naming: Follow the
verb:subjectpattern (e.g.,click:saveButton) rather than action-oriented names (e.g.,save:data).
Sources: CLAUDE.md:35-36, src/scss/README.md:5-25, README.md:231-255
Handlebars Security
Data from the API is treated as hostile. Standard escaping {{ }} is mandatory. Triple-stash {{{ }}} is only permitted for trusted HTML, and the underlying data must be _.escape'd before being passed to the template.
Sources: src/js/views/README.md:12-23, CLAUDE.md:53-54
Testing and Validation
Testing Strategy
The project maintains a merged coverage baseline of 100% for statements, functions, lines, and branches.
The diagram outlines the testing components contributing to the 100% merged coverage contract.
Sources: test/README.md:1-25, CLAUDE.md:72-80
Unit Testing Guidelines
- Units: Defined as a single
.jsfile. - Location: Vitest suites must be colocated with source files (e.g.,
foo.jsandfoo.test.js). - Focus: Test public APIs and pure functions; avoid testing private implementation details or 3rd party library behavior.
Sources: src/js/utils/README.md:4-50, test/README.md:20-22
Deployment and Automation
The scripts/** directory contains critical automation for releases and deployments.
- Releases: Tag-based using the format
vYYMMDD.N. Tags are immutable. - Five9 SDK: The
packages/care-ops-five9/sdk/folder contains vendor code and a local patch. It must only be updated via theupdate-sdk.jsscript.
Sources: README.md:40-65, CLAUDE.md:58-62, packages/care-ops-five9/AGENTS.md:1-12
Summary
The "AI & Developer Guidelines" serve as the architectural anchor for the Care Ops Frontend. By strictly enforcing Marionette design patterns, a secure data-access layer via the Entities Service, and rigorous testing protocols, the project ensures long-term maintainability. For both human contributors and AI agents, adhering to these standards—specifically regarding import order, BEM styling, and event naming—is non-negotiable for project success.