Maintaining contract sidecars
Status: Implemented, not yet released. Target release: 0.4.0, together with contract sidecars.
Problem
Contract sidecars let a contract carry a JSON Schema and example payloads, and AG checks that they agree. AG deliberately does not read source code, so it cannot write or refresh them. Someone has to: in practice, the coding agent following the bundled skill.
This specification describes when the agent creates sidecars, where their contents come from, and how they stay current. It changes the bundled skill and the modeling guide, not the toolkit's code.
Which nodes get sidecars
Give a sidecar to a contract, data_object or artifact node only when it has a concrete data shape that crosses a boundary: an API payload, an event, a stored record, a file format, structured command output.
Do not invent schemas for behavioral contracts: rules about exit codes, ordering, idempotency, authority or limits. Express those in the node's description and with preserves, constrained_by and guarded_by relationships. Such nodes stay in ag summary's withoutSchema list, which is expected.
Where the contents come from
Prefer, in order:
- A schema the project already produces. Reference the generated file directly if the build emits one (OpenAPI components, protobuf descriptors converted to JSON Schema, Zod's
z.toJSONSchema, Pydantic'smodel_json_schema,ts-json-schema-generator). Do not copy it; a copy drifts. If the project has a generator but does not run it, propose adding it to the build rather than generating once by hand. - A schema written from the implementation's types. Read the types, records or structs that define the data, and write the schema to match. Mention the source type in the node's description or a design reference, so the next reader knows what to compare against.
- A schema written from the design. For proposed work with no code, write the schema from the requirements, as in the task-manager example. Mark the node
proposed.
For examples, prefer real output captured from running the code or its tests, then test fixtures, then hand-written examples. Keep examples small and realistic. Never include secrets, credentials or personal data; replace them with obviously fake values.
When to create and update them
During bootstrap, after the first useful graph exists, add sidecars for the contracts most likely to be changed or misunderstood. Do not block the first record on complete coverage.
During everyday changes, when ag context returns a contract with sidecars and the change touches that data shape, update the schema and examples in the same change as the code. If the schema is generated by the build, run the build. Then run ag validate.
For a global backfill, which an existing project needs once, run ag summary, work through the withoutSchema list, and decide for each node whether it has a data shape (add sidecars) or is behavioral (leave it). AG's own graph is backfilled this way as part of 0.4.0.
Keeping them honest
Sidecar validation shows only that the schema and examples agree. Where the project has tests, the strongest safeguard is a test that runs the real code and validates its output against the sidecar schema; suggest one when a contract is important. Report sidecar validation with the other declaration checks, separately from behavioral tests, as the skill already requires.
Changes to make
SKILL.md: add the bootstrap, everyday-change and backfill steps above in a few sentences each.- The modeling guide: add when to give a node sidecars, where contents come from, the default file locations, and the behavioral-contract exception.
- Bump the skill version with the toolkit.
Open questions
- Should the skill suggest adding a sidecar-conformance test automatically, or only when the user asks about drift?