Engineering Notes
Short notes on what we have shipped and how it works — the registry, the control plane, the build path, documents and skills.
The registry is the source of truth
Agent definitions, skills, APIs, architecture principles, data models, components, integrations and policies now live as org-scoped registry entries. Every write is a new version; each entry has an owner, a lifecycle from proposed through active to retired, and a list of what uses it.
Governance as a checkpoint, not a review
When work deviates from an organisation principle, a checkpoint card appears inline in the wizard, in grooming or in the squad room. It names the rule, the deviation and the approver. The outcome is a rejection, a scoped time-boxed dispensation or a relaxation of the principle — and it writes an ADR and updates the registry.
One build path, one pull request
A story build is dispatched to a queue and runs in an isolated job that clones the module repository, runs the architect, developer and tester over one working tree, commits, pushes and opens a single pull request. Checkpoints are written as it goes, so closing the browser does not lose the build.
Reporting honestly after the merge
Once a pull request merges, a verification pipeline runs the test matrix against a baseline held per module and environment. A test type that timed out or was skipped is reported as exactly that — it does not quietly count as verified.
Documents and diagrams with references and versions
Specs, stories, ADRs, architecture views and policies are Markdown documents edited in the product, with typed references between them, versions and an approval workflow. Diagrams are draw.io, versioned and referenced by id, and ERDs are generated deterministically from the data models in the registry.
MCP servers become skills
An MCP server is registered as a skill source, its tools discovered and installed as skills; a published API registry entry generates a skill and its HTTP tools the same way. Agents attach skills rather than raw tools, and credentials are resolved per call from a binding that holds only an opaque reference.