agent-crm AGENTS.md

Repository guidance

Product intent

This repository is an agent-native CRM framework. Preserve the separation between deterministic CRM state and AI-assisted development/orchestration.

Required workflow

1. Read PRODUCT.md, ARCHITECTURE.md, DECISIONS.md and the relevant module files before changing code. Before product, positioning, roadmap or public-distribution decisions, read docs/strategy/MASTER_PLAN.md first; for implementation details, ARCHITECTURE.md and DECISIONS.md remain authoritative.
2. For a multi-file feature or significant refactor, create and maintain an ExecPlan under docs/plans/ following .agent/PLANS.md.
3. Use public module services and named workflows. Never mutate CRM tables from API, MCP or UI code.
4. Any write operation must retain validation, audit and trace.
5. Keep MCP write tools narrow; destructive or code-generating tools must default to dry-run or require an explicit apply flag.
6. Do not add a production dependency unless it removes more complexity than it adds; record the reason in DECISIONS.md.
7. Run npm run verify before considering work complete.
8. Update TASKS.md and relevant docs when behavior changes.
9. Domain-package work requires the build-custom-domain-package skill (.claude/skills/build-custom-domain-package/SKILL.md, mirrored at .agents/skills/build-custom-domain-package/SKILL.md) and docs/PACKAGE_AUTHORING.md. A package imports only packages/core/index.js, reaches another package only through a declared capability, and is registered by one static import in packages/domains/generated/index.js. A single custom object is a module, not a package.
10. Follow docs/QUALITY_GATES.md for every feature PR, and use the adversarial-review skill for any milestone review or pre-merge review task (.claude/skills/adversarial-review/SKILL.md, mirrored at .agents/skills/adversarial-review/SKILL.md). A milestone that skipped the review is unreviewed, not finished.
11. Respect the core budget rule (ADR-018): new domain-specific business behavior does not go into packages/core unless it is first proven to be a reusable runtime capability. A PR that adds a domain concept to core must say which runtime capability it is and why a domain package cannot own it.
12. Read docs/PROJECT_STATUS.md for what is true in the repository today — merged milestone, the commit the public numbers were measured at, open PRs, production blockers — and update it in the same PR as a milestone merge. Do not put volatile status in MASTER_PLAN.md. It carries no test count: a count is measured into site/claims.json measuredAgainst by node scripts/measure-suite.js --apply and cited from there (ADR-027). Typing one into any document under docs/ fails npm run gtm:check.
13. To learn what an application actually has, run npm run crm -- app inspect --json rather than assembling it from source and prose (docs/APPLICATION_INSPECTION.md). Read valid, then problems[], then limitations[] — every limitation is a hard boundary on what you may claim. It reads checked-in source only: it opens no database, contacts no provider, and reports no runtime or authorization state.
14. Compatibility Backfill Rule. When you add or change a horizontal capability — one every domain could use, such as the package seam, a declared capability contract, module evolution, an evidence discipline or an agent-facing surface — record every existing domain's status against it in docs/architecture/LEGACY_ALIGNMENT_MATRIX.md in the same PR, using aligned | partial | deferred | not_applicable | needs_extraction with a one-line reason. Declaring the gap is required; closing it in the same PR is not. Do not refactor a legacy domain to close a row: extraction is sequenced work (docs/architecture/LEGACY_ALIGNMENT_MATRIX.md), not something a feature PR does on the way past.
15. A Solution Plan is a checked file with a contract, not prose with headings (docs/SOLUTION_PLAN.md). Write it, record the app inspect report it was written against, and run npm run crm -- solution check <plan.json> before writing code and again before the review — a plan bound to a composition that has since moved reports PLAN_STALE. A plan never carries a command: nothing in this framework executes one, and the validator refuses it.
16. Parallel coding agents. Each agent works in its own sibling worktree outside the repository, owns exactly one branch, and one final integrator reconciles the shared truth. The three rules are in Parallel coding agents below.
17. The Repository Truth Contract (ADR-039). A sentence in a current document that states what the framework does or does not do is bound to a fact generated from an executable authority, and cited by stable fact id — <!-- truth: spine.managed_jobs_service.implemented=absent -->. Existing gates compare documents to documents, and that is exactly how a whole set of them stayed consistently wrong together after Production Spine v1. npm run repo:truth -- --check runs on every push and pull request as its own step in the public-claims CI job; run it locally when a PR moves a product boundary, a rail, a package contract or the spine, and if a fact moved, run npm run repo:truth and commit the regenerated docs/repository-truth.json in the same PR. It is a repository-maintenance script, not a rail and not a product command: it adds nothing to the surface budget and never leaves this repository. Rules and boundaries: docs/REPOSITORY_TRUTH.md, docs/QUALITY_GATES.md §6.1.