This file is generated by npm run agents:to_agentsmd from the canonical Claude Code guidance.
# Additional Conventions Beyond the Built-in Functions
As this project's AI coding tool, you must follow the additional conventions below, in addition to the built-in functions.
# Vivaa Monorepo
Prefer skills over documentation. Conventions live in `.claude/skills/`. This file captures cross-cutting rules only.
## Skill Types
Skills follow a naming convention that signals how they're used:
- **`codechange-*`** — Step-by-step guides for a specific type of code modification (e.g., adding a migration, creating an API endpoint). Invoked when performing that kind of change.
- **`workflow-*`** — Multi-step orchestration guides for work that spans apps or PRs (e.g., adding a new primitive end-to-end). Invoked when planning or executing that workflow.
- **`reference-*`** — Domain-specific knowledge that is too detailed for CLAUDE.md but reused across multiple skills. **Not invoked directly** — referenced as a dependency by codechange and workflow skills. Read the reference when a dependent skill lists it under `## Dependencies`. Examples: observability conventions, cloud CLI command catalogs.
- **`skillbuilder-*`** — Meta-skills for creating new skills of a given type.
### Dependencies Between Skills
Codechange and workflow skills may declare a `## Dependencies` section listing reference skills they depend on. When you invoke a skill that has dependencies, also read the referenced skills to inform your work. Reference skills are shared context — they avoid duplicating the same conventions across multiple codechange skills.
## Feature Development Workflows
Single-PR one-off features (fixes, small updates, etc) can be handled as one-offs. Use the appropriate skill(s), or if it's not something captured by any specific skills consider looking over whichever skills seems closest to glean best practices, but allow yourself to be flexible.
Multi-PR features follow a phased approach:
1. **Branch**: `feature/{name}` from main
2. **Plan**: Create `llm-usage-notes/features/{YYYY-MM-DD}-{name}/plan.md` with high-level spec, ordered phases, which apps/skills each phase touches. Consult workflow skills (e.g., `workflow-new-primitive`) when applicable.
3. **Phase0 (optional)**: Plan-only PR as RFC. Recommended for complex features.
4. **Phase branches**: `feature/{name}/phase{N}/{app}-{slug}` for each PR
- `{slug}` matches codechange skill (e.g., `add-migration`, `model`) or is descriptive
- Phase-specific planning goes in PR description under a collapsible `<details>` section
5. **PR scope**: One app per PR unless bundling is necessary
6. **Order**: Migrations → backend → frontend (zero-downtime safe)
7. **Iterate**: PR feedback updates planning docs and skills
8. **NEVER MERGE A PR**: The user is responsible for merging the PR once approval has been granted, and should let you know when to update and advance to the next phase.
## Pull Requests
**All PRs MUST be created in draft mode.** Use the `/pr` command, which handles description generation and runs `gh pr create --draft`. Never create a non-draft PR.
## Healthcare Security
This is a healthcare system handling PHI. Security is a cross-cutting concern:
- **No PHI in logs.** Patient data must be sanitized from all log output.
- **Encryption:** PHI encrypted at rest and in transit.
- **Access controls:** Practice-level data isolation. RBAC enforced on every endpoint.
- **Input validation:** All external input validated and sanitized. SQL injection, XSS, and injection attacks prevented.
- **Sensitive data:** Passwords hashed. API keys in environment variables, never in code. Secrets masked in logs.
Use the `/review` command for a structured security-aware code review.
## General Tips
- Each session should at start confirm the nature of the work being done, and should confirm (a) what branches already exist with respect to that work, and (b) what branch is currently checked out.
- Make it a point to read PR feedback, and consider whether it may be worth it to update skills to capture what's being recommended more generally.
- If a complex unit of work seems to deviate significantly from the guidance provided by existing skills, consider prompting the user to create a new skill.
- **Pre-commit self-check:** Before presenting code or creating a commit, re-read the relevant CLAUDE.md files and verify each convention was followed. Pay particular attention to styling conventions (sx prop names, spacing units, component choices) and truthiness checks (`isDefined`/`isTruthy`), which are easy to forget mid-implementation.
## Coding Conventions
### Plain Dates
APIs return plain dates as `2020-04-20T00:00:00Z`. Browsers west of UTC interpret this as the previous day (off-by-one bugs).
**For plain date fields (birthdays, anniversaries):**
- Use `moment.utc(dateOfBirth)` or `momentTz(dateOfBirth).tz('utc')`
- Never `new Date(plainDate)`, `parseISO(plainDate)`, or `moment(plainDate)`
### Truthiness
Use `isDefined`/`isTruthy` from common utils:
- `isDefined(value)` — `value !== null && value !== undefined`
- `isTruthy(value)` — truthy check that correctly handles `false`
- `isTruthy(obj?.length)` not `obj && obj.length > 0`
- `if (!isDefined(data)) return null` not `if (!data) return <></>`