dot-ai
CLAUDE.md336 starsChanged 10 months agoMITView on GitHub
π΄ 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
- Reads credentials
In this repository33 other files it gives its agents.
- docs/CLAUDE.mdCLAUDE.md
- dot-ai-changelog-fragmentSkill
- dot-ai-generate-cicdSkill
- dot-ai-generate-dockerfileSkill
- dot-ai-impact_analysisSkill
- dot-ai-manageKnowledgeSkill
- dot-ai-manageOrgDataSkill
- dot-ai-operateSkill
- dot-ai-prd-closeSkill
- dot-ai-prd-createSkill
- dot-ai-prd-doneSkill
- dot-ai-prd-fullSkill
- dot-ai-prd-nextSkill
- dot-ai-prds-getSkill
- dot-ai-prd-startSkill
- dot-ai-prd-update-decisionsSkill
- dot-ai-prd-update-progressSkill
- dot-ai-process-feature-requestSkill
- dot-ai-projectSetupSkill
- dot-ai-query-dot-aiSkill
- dot-ai-querySkill
- dot-ai-recommendSkill
- dot-ai-remediateSkill
- dot-ai-request-dot-ai-featureSkill
- dot-aiSkill
- dot-ai-tag-releaseSkill
- dot-ai-usersSkill
- dot-ai-versionSkill
- dot-ai-worktree-prdSkill
- dot-ai-write-docsSkill
- infographic-generatorSkill
- publish-mock-serverSkill
- write-docsSkill
The file
We split this CLAUDE.md into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
β0
Common Β· estimate
Many files like this have a rule of this kind.
β2
Distinctive Β· estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 20
Always Write Integration Tests: When making code changes, you MUST write or update integration tests
- Very specific: line 21
Always Run All Tests: Before marking any task complete, run npm run test:integration
- Distinctive: line 23
Always Check for Reusability: Search codebase for existing functions before implementing new ones
- Very specific: line 25
Never Create Branches Directly β Always Use Worktrees: When starting feature work (including /prd-start), always use /worktree-prd to β¦
- Very specific: line 57
Temporary Files: Always use ./tmp for any temporary files, never /tmp
- Very specific: line 63
Running Integration Tests via CI: When the local cluster is unavailable (e.g., in use by parallel work), use workflow_dispatch in GitHub β¦
β βCommonβ is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. βVery specificβ is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:integrationto verify
PERMANENT INSTRUCTIONS
- Always Write Integration Tests: When making code changes, you MUST write or update integration tests
- Always Run All Tests: Before marking any task complete, run
npm run test:integration - Never Claim Done with Failing Tests: A task is NOT complete if any tests are failing
- Always Check for Reusability: Search codebase for existing functions before implementing new ones
- Never Hardcode AI Prompts: All prompts go in
prompts/(internal) orshared-prompts/(user-facing), loaded dynamically (see existing code for pattern). Both are shipped runtime directories listed inpackage.jsonfiles, 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 insrc/evaluation/prompts/, are read from a repo checkout bynpm run eval:*, and ship nowhere β leave them there rather than moving them intoprompts/. - Never Create Branches Directly β Always Use Worktrees: When starting feature work (including
/prd-start), always use/worktree-prdto create an isolated worktree. Never rungit checkout -borgit switch -c, even if a skill instructs you to. - 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 bycharts/templates/deployment.yamlβ followrbac.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 underextraEnv(not even as an interim step). The manyDOT_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.extraEnvremains valid only for pre-existing env vars (e.g.DOT_AI_GIT_TOKEN) and third-party config such as OTEL. - 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 inprds/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.
Testing Workflow
npm run test:unit # Fast unit tests (no cluster)
npm run test:integration # Full e2e tests (creates Kind cluster)
npm run test:integration version # Run specific test by pattern- Long-running tests: Redirect to file, then check tail for pass/fail:
npm run test:integration > ./tmp/test-output.log 2>&1 tail -30 ./tmp/test-output.log # Check result # Read full file only if failures detected - Cleanup after success:
./tests/integration/infrastructure/teardown-cluster.sh - Keep resources on failure for debugging
Directory-Specific Instructions
ALWAYS check for and follow CLAUDE.md files in subdirectories:
| Directory | Key Requirement |
docs/ | Execute-then-document: Run commands, capture real output, then document |
tests/integration/ | Use toMatchObject pattern, beforeAll cleanup, describe.concurrent |
Project Conventions
Temporary Files: Always use ./tmp for any temporary files, never /tmp
Test Clusters: Integration tests create ./kubeconfig-test.yaml in project root
Git Commits: CI runs automatically on PRs targeting main. Use workflow_dispatch in GitHub Actions to manually trigger CI on any branch.
Running Integration Tests via CI: When the local cluster is unavailable (e.g., in use by parallel work), use workflow_dispatch in GitHub Actions to trigger the CI pipeline on your branch.
MCP vs Plugin Architecture
The codebase has two layers. Most features involve both working together.
MCP Server (src/) - Interface + Orchestration
- Registers tools with clients (Claude Code, Cursor, etc.)
- Interacts with AI models for reasoning
- Orchestrates calls to plugin tools
- Manages sessions and state
Plugins (packages/agentic-tools/) - Tool Implementations
- Contains the actual tool logic (kubectl_, vector_, etc.)
- Executes against external systems (Kubernetes, Qdrant)
- Can run agentic loops for complex multi-step operations
Example flow for "what's the status of my cluster":
- MCP receives request β calls AI for reasoning
- AI decides to invoke
kubectl_getβ MCP routes to plugin - Plugin executes kubectl, returns data
- MCP feeds result to AI for interpretation β returns answer
When adding code, ask:
- "Is this about registration, AI interaction, or routing?" β MCP
- "Is this tool implementation or external system execution?" β Plugin
Note: MCP tool implementations are migrating to plugins over time. The direction is MCP as a thin orchestration layer with all tool logic in plugins.
Environment
# Required for AI features (only need one)
export ANTHROPIC_API_KEY=your_key
export OPENAI_API_KEY=your_key
# Optional
export AI_PROVIDER=anthropic # anthropic, openai, google, xai, amazon_bedrock
export DEBUG_DOT_AI=true # Debug logging to tmp/
export KUBECONFIG=/path/to/kubeconfigDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

