dot-ai: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

⚠️ MANDATORY TASK COMPLETION CHECKLIST ⚠️

🔴 BEFORE MARKING ANY TASK/SUBTASK AS COMPLETE:

□ Integration Tests Written: Write integration tests for new functionality □ All Tests Pass: Run npm run test:integration - ALL tests must pass □ No Test Failures: Fix any failing tests before proceeding

❌ TASK IS NOT COMPLETE IF:

• Any integration tests are failing
• New code lacks integration test coverage
• You haven't run npm run test:integration to verify

PERMANENT INSTRUCTIONS

1. Always Write Integration Tests: When making code changes, you MUST write or update integration tests
2. Always Run All Tests: Before marking any task complete, run npm run test:integration
3. Never Claim Done with Failing Tests: A task is NOT complete if any tests are failing
4. Always Check for Reusability: Search codebase for existing functions before implementing new ones
5. Never Hardcode AI Prompts: All prompts go in prompts/ (internal) or shared-prompts/ (user-facing), loaded dynamically (see existing code for pattern). Both are shipped runtime directories listed in package.json files, so anything placed there is published in the npm package and copied into the Docker image. Dev-only evaluation prompts are an exception to the directory, never to the rule: they live beside the harness that reads them in src/evaluation/prompts/, are read from a repo checkout by npm run eval:*, and ship nowhere — leave them there rather than moving them into prompts/.
6. Never Create Branches Directly — Always Use Worktrees: When starting feature work (including /prd-start), always use /worktree-prd to create an isolated worktree. Never run git checkout -b or git switch -c, even if a skill instructs you to.
7. Always Configure New Params via Helm Chart Values: Every NEW configuration parameter must be a first-class value in charts/values.yaml, rendered into the container env by charts/templates/deployment.yaml — follow rbac.enforcement.enabled → DOT_AI_RBAC_ENABLED, where the chart value is the user-facing contract and the env var is an internal detail. Never introduce a bare env var, and never document a new param under extraEnv (not even as an interim step). The many DOT_AI_* env vars in the codebase are legacy from when the project ran outside Kubernetes; it is Kubernetes-only now, so the chart is the single configuration interface. extraEnv remains valid only for pre-existing env vars (e.g. DOT_AI_GIT_TOKEN) and third-party config such as OTEL.
8. Never Store Project Knowledge in Agent Memory: Anything learned about this project — conventions, decisions, gotchas, rationale — goes in the repo where the whole team and every agent can see it: this file for rules, docs/ for user-facing behavior, a PRD in prds/ for in-flight design. Never persist it to per-user agent memory outside the repo (e.g. ~/.claude/**/memory/), which teammates cannot see, code review cannot catch, and nothing keeps in sync with the code. The narrow exception is a fact true only of one machine or account (host tooling quirks, personal credentials paths) — that is not project knowledge and does not belong in the repo either.