Skip to content

AGENTS.md

Latest commit

 

History

History
159 lines (133 loc) · 13.3 KB

AGENTS.md

File metadata and controls

159 lines (133 loc) · 13.3 KB
Raw

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.

Selecting an Accordo rail

The application answers questions about itself through a small set of rails — few tools, distinct jobs. When one of the questions below is the question in front of you, run its rail rather than assembling the answer from find, grep and source reading: hand-assembly is slower, and it tends to fail by inventing a capability the application does not have (docs/APPLICATION_INSPECTION.md).

The question in front of you Rail Command
What has this project actually composed? SEE npm run crm -- app inspect --json
Is this plan valid, and still true of this application? PLAN npm run crm -- solution check <plan.json>
What is inconsistent or stale in this checkout? CHECK npm run crm -- project doctor --json
I need a minimal new package starting point. BUILD npm run crm -- package scaffold <name>
Does this one package conform to the framework? CHECK npm run crm -- package test <dir> --json
Is the whole project technically healthy? PROVE npm run crm -- project verify --json
Does this business journey actually work? PROVE npm run crm -- scenario run <scenario> --json
Is every requirement of the plan actually proven? PROVE npm run crm -- solution verify <plan.json> --evidence <evidence.json>
Will this refactor preserve behaviour? PRESERVE characterization — tests/characterization/, npm run characterize:intelligence

The selection rule. Use the smallest rail that directly answers the current question. Do not chain rails automatically, and no rail — app inspect included — is an obligatory first step. Escalate only when the next question needs a stronger kind of evidence: what exists → inspect · internally consistent → doctor · technical health proven → project verify · this journey proven → scenario run · the plan proven complete → solution verify.

The boundaries between neighbouring rails:

  • app inspect describes what exists — composition, capabilities, records, actions, policies, providers — never health, domain correctness or runtime state.
  • project doctor diagnoses source consistency and drift; it makes no claim about business behaviour.
  • solution check asks whether the plan still matches the application (PLAN_STALE), not whether it is implemented: it can exit 0 on a plan nobody has built a line of.
  • project verify proves technical health by orchestrating existing authorities — conformance, the doctor, the project's declared scripts; it runs no business scenario and maps no requirement to proof.
  • scenario run proves one named business journey with linked evidence; it is not whole-project health, and it promotes no JTBD row.
  • solution verify maps every plan requirement to machine-checked proof and may honestly exit 1 with work unproven; it executes no plan and writes nothing.
  • package scaffold writes a minimal conforming skeleton with no invented domain semantics — dry-run by default, --apply to write.
  • package test proves framework conformance by composing the package into a real application, never domain correctness; package validate checks only that the declaration is structurally valid, so a conformance question ends at test.
  • characterization freezes a domain's externally observable behaviour before a boundary-preserving refactor, and replays it after.

SEE, PLAN, BUILD, CHECK, PROVE and PRESERVE are the agent's internal labels for its own next action. A user states a goal and never needs to know a rail exists; for goal-shaped work, the Skills choose the rails.

This section appears verbatim in both AGENTS.md and CLAUDE.md, because each is the file a different harness loads at session start. If the copies disagree, AGENTS.md is canonical. Parity is kept by hand — diff the two sections when editing either.

Parallel coding agents

Several agents may work on one milestone at once. Three rules, because breaking any of them has already cost this repository a wave of published numbers:

  1. One worktree per agent, outside the repository. git worktree add ../<repo>-worktrees/<name> — a sibling directory, never a path inside the checkout, so no agent's build output, temporary database or generated site lands in another agent's tree.
  2. One branch owner per worktree. The agent that owns a branch is the only one that commits to it. An agent that needs another agent's change waits for the merge or rebases onto it; it does not reach into a worktree it does not own.
  3. One final integrator reconciles shared truth. Every wave ends with a single pass over the files every branch touches — docs/PROJECT_STATUS.md, site/claims.json, the JTBD matrix, the roadmaps — because a merge that resolves a conflict in a measured record silently discards a measurement. That is not hypothetical: a branch re-measured site/claims.json, the merge kept main's older block, and the ledger ran a whole wave behind the suite with every gate green. npm run gtm:check now fails on that particular drift (scripts/measurement.js), and the integrator pass is what catches the rest.

Sequenced in docs/QUALITY_GATES.md §1.11.

Coding conventions

  • Node.js ESM and standard-library-first JavaScript.
  • Use // @ts-check and JSDoc for public APIs.
  • Prefer small explicit functions over hidden metaprogramming.
  • Return domain objects, not raw SQLite rows with encoded JSON.
  • Use cents for monetary values and ISO 4217 currency codes.
  • Use ISO-8601 UTC timestamps.
  • Log MCP diagnostics only to stderr; stdout is reserved for JSON-RPC.

Definition of done

  • behavior works end-to-end;
  • tests cover happy path and policy boundary;
  • trace and audit are visible;
  • no direct table mutation outside module services;
  • documentation is sufficient for another coding agent to continue;
  • every claim in the docs, the ADR, the PR body and the JTBD matrix traces to a merged test — a capability and its limitation are stated in the same breath.

The DX Simplicity Gate

Before adding a new agent-facing command, tool, contract or namespace, answer these in the PR. Canonical rule and full rationale: docs/strategy/CODING_AGENT_DX_NORTH_STAR.md.

Goal-first outside, rigorous inside. New internal complexity is justified only if it reduces perceived user or agent complexity, or measurably improves reliability or evidence.

  • name the concrete agent failure mode it prevents — the failure, not the capability;
  • prove existing primitives are insufficient, having tried to extend one;
  • minimise semantic overlap: two commands answering nearly the same question is worse than one that answers it completely;
  • keep it deferred or on-demand unless every session needs it;
  • preserve portability — behaviour belongs in the CLI, a JSON contract, the Package Contract, canonical Skill semantics or the Quality Gates, never in harness-specific logic;
  • ship machine-readable evidence of its value: an exit code, a contract-versioned document, a fingerprint, a measured number;
  • if the capability is horizontal, update the Compatibility Backfill Rule and the Legacy Alignment Matrix in the same PR;
  • show the end-user goal flow gets simpler, not more manual. "The agent now has one more thing to run" fails the first bullet.

Code review rules

  • Flag any API/MCP handler that executes SQL directly.
  • Flag any mutation without actor context and audit event.
  • Flag AI-generated business decisions that are not encoded as explicit policy or approval.
  • Flag money represented as floating-point currency amounts.
  • Flag domain-specific business behavior added to packages/core without the ADR-018 justification.
  • Flag a JTBD row promoted without linked evidence, or a document claiming a capability the tests do not prove.
  • Flag a new agent-facing command, tool or contract that does not clear the DX Simplicity Gate above.