The source files
Semantic source lives in .cordango.yaml files, one per aggregate: an entity, a lifecycle, a role,
a screen. They’re the source of truth, and they’re meant to be read, reviewed and diffed.
Editing them directly is fine. They describe what a thing is, not how it runs.
fmt rewrites every .cordango.yaml file in canonical form, so a diff shows a change in meaning
instead of a change in whitespace or key order.
The build directories
Two, and neither is committed. cordango new writes a .gitignore that already excludes both.
.cordango/ with the leading dot holds the definition artifacts — the compiled App Definition and
its manifest. cordango build regenerates it.
generated/ holds the applications themselves, one directory per app, so a workspace with support
and billing in it builds to generated/support/ and generated/billing/. There is no --out:
where the output goes is not a decision anybody has to make twice. It’s ordinary source code and
it’s reproducible from the apps/ directory beside it, which is why it stays out of git — and
moving a directory out of the workspace is how an application leaves.
Agent instructions
cordango new writes CLAUDE.md and AGENTS.md with the same generated text. Two conventions, two
filenames. Both get written because a workspace that taught two agents different rules would end up
with source only one of them could maintain.
They teach the workflow rather than the schema. An agent arrives knowing how to find out:
That’s on purpose. Everything specific is one cordango inspect away, which keeps the instructions
from growing back into a copy of the whole schema.
Every command accepts --json. cordango help --json is how an agent discovers the command
surface without a human pasting a README into its context.
