agent-crm

# Accordo

> **Describe your sales process to your coding agent; own the CRM it builds.**

An open-source framework that Claude Code, Codex and Gemini CLI use to generate a CRM
application as code you own — deterministic workflows, policy-gated human approvals,
audit and trace built in.

The name is chosen and the domain registered. `npm create accordo` scaffolds a working
project from the published `create-accordo@0.1.0`; the `accordo` package itself remains
an empty `0.0.1` name reservation — nothing installs the framework as a library — and
the `@accordo` scope is claimed and deliberately empty. No trademark screen has been run, and the project is
not deployable to production. What that means precisely is in
[Where it stops](#where-it-stops), which is worth reading before the rest.

```text
Business request
      ↓  "Renewals of €50,000 or more need a manager's sign-off."
Claude Code / Codex
      ↓  reads AGENTS.md · 12 skills · MCP · `crm app inspect`
Modules + deterministic workflows + versioned policy
      ↓
API + Admin + trace + audit — in your repository, as code you review
```

---

## When to reach for Accordo

- **Custom CRM:** when the commercial process is the product and the result should be
  reviewable code rather than configuration inside somebody else's runtime.
- **[Customer Hub](https://accordo.dev/concepts/customer-hub.html):** when “hub” means one
  local commercial record chain with governed actions. Accordo does not ingest sources or
  resolve customer identities like a CDP.
- **[Smart CRM](https://accordo.dev/concepts/smart-crm.html):** when a coding agent should
  compose the application while versioned policy and named humans retain business decisions.
  It is agent-built software, not an autonomous decision-maker.
- **[CDP + CRM](https://accordo.dev/concepts/cdp-plus-crm.html):** when an external CDP owns
  ingestion, identity resolution and audiences, and Accordo owns the deterministic CRM
  process layer beside it. Accordo ships no CDP, connector, importer or sync runtime.

Those adjacent terms are retrieval paths, not extra capability claims. The checked
[recommendation map](docs/strategy/RECOMMENDATION_MAP.md) binds each one to what the
framework proves and where it stops.

---

## Why this exists

Every CRM eventually asks you to bend your process to fit its model. The two usual escapes
both cost something:

- **Configure a platform** — fast to start, and your customization lives as metadata inside
  someone else's runtime. When the ceiling arrives, you fork a monorepo.
- **Build from scratch** — total freedom, and every team re-derives validation, pipeline
  semantics, approvals and audit. Usually late, usually under pressure.

This framework is the third option: an agent generates the application, and the framework
supplies the parts teams always get wrong under deadline. The test any developer can apply
is *"if this project disappears tomorrow, what am I left with?"* Here the answer is: a Node
application in your repository, with no third-party runtime dependencies and a SQLite file
any client can open.

## What is proven

Each line below is bound to a merged test. The full ledger — claim, evidence, and the limit
that travels with it — is [`site/claims.json`](site/claims.json), and the review discipline
behind it is [`docs/QUALITY_GATES.md`](docs/QUALITY_GATES.md).

| Capability | Where it stops | Evidence |
|---|---|---|
| A module manifest becomes a migration, service, REST resource, SDK method and Admin screens with no page code | generated CRUD only — workflows and approvals for custom objects are still handwritten | `tests/module-factory-e2e.test.js`, `tests/generated-api-e2e.test.js`, `tests/admin-modules.test.js` |
| Generated objects reference each other: foreign key, runtime target validation, Admin selector | generated-to-generated many-to-one only; no many-to-many, inverse collections or cascade | `tests/reference-fields-e2e.test.js` |
| Deterministic approval policy: a renewal at or above the threshold waits for a named human | the built-in renewal object and one value threshold | `tests/workflow.test.js`, `tests/api.test.js` |
| **An agent cannot make the human's approval decision** — asserted by a test, not by a convention | the actor is asserted, not authenticated; this holds against an honest agent, not an attacker | `tests/workflow.test.js` |
| Opportunities move through code-first pipeline stages under a server-authoritative action — the client asks, the server decides | proven on the built-in Opportunity module; configurable pipelines for generated custom objects are not claimed | `tests/opportunity-pipeline-e2e.test.js`, `tests/pipeline-contract.test.js` |
| Lead capture, enrichment, explainable versioned scoring, deterministic routing, qualification, conversion | enrichment runs against a fixture provider; no real data source is wired | `tests/lead-intelligence-e2e.test.js`, `tests/lead-conversion-e2e.test.js` |
| Server-priced composite quotes, immutable quote versions, versioned discount policy with approval | fixture catalog provider; integer cents with no FX — currencies are never summed | `tests/commercial-e2e.test.js` |
| Signature envelope → verified events → signed-artifact evidence → exactly one immutable Order | fixture signature provider, test-only webhook key, provider-reported artifact hash | `tests/signature-order-e2e.test.js` |
| Order activation into Contract, immutable version, Subscription and pending obligations | nothing bills, renews, amends or cancels; there is no scheduler | `tests/contracts-activation-e2e.test.js` |
| Delivery handover into a project with work packages, milestones and an optional partner; human-driven execution | nothing schedules, staffs, accepts or bills; deliverables do not exist as objects | `tests/delivery-handover-e2e.test.js`, `tests/delivery-execution-e2e.test.js` |
| Append-only time and expense evidence, costed by a versioned policy, with a reproducible contribution estimate | deliberately not a margin: no revenue recognition, no COGS, no ARR/MRR, no FX | `tests/delivery-economics-e2e.test.js` |
| A customer-authored domain package attaches and detaches with the kernel fingerprint unchanged | the scaffold that starts one writes an empty package and nothing else; no registry, no publication, no sandboxing — package code runs with the host's authority | `tests/package-contract.test.js`, `tests/custom-package-e2e.test.js` |
| `accordo package scaffold <name>` — a minimal, empty, conforming local package, written atomically, dry-run by default | it invents no business logic, composes nothing, verifies no global identity uniqueness and installs or publishes nothing | `tests/package-scaffold.test.js`, `tests/package-test-command.test.js` |
| `crm app inspect` — one deterministic, source-only JSON report of what an application contains | never opens the database, contacts a provider or reads a secret — and says so in its own output | `tests/app-inspect.test.js` |
| `crm solution check` — a Solution Plan is a checked-in contract with a canonical fingerprint | a document contract, not a planner and not a runtime; nothing executes a plan | `tests/solution-plan.test.js` |
| `crm scenario run` — two checked-in business scenarios run against real composed applications and report which JTBD rows they earned **and which they did not** | coverage is claimed by a scenario rather than discovered; it promotes no row, drives no browser, and each run speaks for one composition | `tests/scenario-run.test.js` |
| Generated modules evolve through explicit revisions and append-only named migrations | source-only: what a particular database applied is not knowable from here | `tests/module-evolution.test.js` |

**The whole suite runs on every push**, together with the smoke test. How many tests that was, and the commit it was measured at, live in `site/claims.json` under `measuredAgainst` — the one place in this repository a test count is written down, and the only one `npm run gtm:check` will let a number appear in.

## Run it

Node.js 22.16 or newer. There are no third-party runtime dependencies and no build step.

```bash
npm run tour     # compose the whole application and inspect it
npm run verify   # source checks, then the whole test suite
npm run falsify  # break five rules on purpose and watch the suite catch them
npm run demo     # the approval slice, end to end
npm run dev      # http://localhost:4000
```

`npm run tour` is the fastest way to see what this actually is. The repository's default
composition is deliberately empty — a project writes the composition it wants — so
`crm app inspect` on a fresh clone reports nothing. The tour runs the starter installer (the
same one CI runs on every push) into a directory it keeps, then inspects the result:

```text
  modules       76        resources     71        policies       7
  packages       9        actions       64        providers      1

  production posture — local development only: no authentication, tenancy or RBAC
                       exists, and actor headers are not identity
```

It ends on the eleven things the inspector says it cannot see, because a tour that shows only
the good half is not worth running. `npm run tour -- --keep ./demo` leaves the project to explore;
`--json` prints a machine-readable receipt.

`npm run falsify` is the other direction. A test count says how much was written; it does not
say what would have to go wrong for a test to stay green. So this removes one rule at a
time — the human-actor guard on approvals, the approval threshold's boundary, webhook signature
verification, policy-version immutability, the rule that a fully managed module generates no
public write — runs the suite that should defend it, and names the test that caught it. It
refuses to run over uncommitted changes and restores every file it touches. Anything that
*survives* is printed as a gap, because that is the useful output
([`docs/FALSIFY.md`](docs/FALSIFY.md