Writing Your First Contract

The five commands make more sense as a sequence than as a reference list, so here's what running them actually looks like on a repo that has never seen cdad before.

Start in the repo root with cdad check. It runs its static scan, then walks you through the legibility questionnaire for a handful of capabilities it found, four questions each. A couple of minutes later you have a score, a band, andcdad-report.md sitting in the repo. Don't worry if the score is low. A low score is just an accurate starting point, and most first runs land somewhere in the middle.

Next, cdad roadmap. It reads that same report and asks two more questions per capability: how critical is it, and how often does it actually get touched. Multiply those against the tribal knowledge density the check step already surfaced and you get a ranked list in cdad-roadmap.md. Whatever lands at the top is usually the capability where nobody quite remembers why a certain edge case exists, which is exactly the kind of thing worth writing down before it's forgotten entirely.

Take that top capability and hand its ID to cdad init. If it's payments/retries/schedule-retry, that's what you type, and the command scaffolds contract.yaml,contract.json, and contract.md undercdad/payments/retries/schedule-retry/, prompting you for the details as it goes. This is where you write down what the capability actually promises, what it needs to run, and just as important, what it deliberately doesn't do. That last part is often the piece nobody's written down anywhere else.

Before you commit any of it, run cdad validate --all --strict. It checks the schema, the versioning, and whether the generated files still line up with the contract itself. If this is your first contract in the repo, it's also worth runningcdad validate --install-hook once, so every commit after this one gets checked automatically instead of relying on someone remembering to run it by hand.

Finally, cdad graph. On a repo with exactly one contract, the graph won't look like much yet, and that's fine. The value shows up as more contracts get added and you can actually see how payments/retries/schedule-retry connects to whatever calls it. Run cdad check again down the road and you'll have a second score to compare against the first, which is the real measure of whether any of this was worth doing.

cdad check
cdad roadmap
cdad init payments/retries/schedule-retry
cdad validate --all --strict
cdad graph