In April 2026, I started experimenting with a Customer Care AI chat. It became a tiny CRM passion project, and the experience led me to think about what should survive a coding-agent session.

A conversation could accumulate useful understanding: what the product was meant to do, why a decision had been made, which part of the code owned a responsibility, and what still needed attention. I wanted that understanding to remain useful when I returned in another session or continued with another tool.

That question became the starting point for Contract Graph Dev Kit, which I call Contract Graph throughout this article.

Giving context a home

My first concern was persistence. If useful context lived only in a conversation, the next session would need some way to recover it. Recording it in the repository made it available alongside the code.

But saving context raised another question: how would an agent find the relevant part as the project grew?

A document can preserve a decision and still become difficult to use. A plan can explain how a feature was developed while gradually losing its value as a description of the current system. Keeping everything leaves the next reader to decide what still applies.

I wanted context to have an owner, a purpose and a route from the wider project into the part being changed.

Software boundaries as the starting point

Software contracts offered a useful way to think about this. A unit has a responsibility, an interface its callers use, dependencies and promises it must preserve. Those ideas have a long history in software engineering; my interest was in making them useful to agents working across sessions on a changing repository.

The word contract does not need to mean only an executable precondition or an API definition. A repository document can describe the purpose and promises of an owned software boundary. It can tell a reader what belongs there, what its neighbours may rely on, and which narrower responsibility to inspect next.

Markdown can express that idea. The Contract Graph Dev Kit uses schema-backed YAML so tools can inspect the declared fields and relationships consistently. The conceptual role of a contract and the format used by this implementation are separate choices.

Connecting those contracts produces a graph. Parent and child relationships decompose the system; dependency links connect responsibilities across that hierarchy.

For a change, the intended route is:

request
  → responsible contract
  → relevant child and dependency context
  → implementation and tests
  → updated contracts and verification

The graph gives the agent a starting point and guidance on where to read next. Relevant code reading remains necessary.

Keeping the map current

Persistent context creates a maintenance obligation. A contract that describes yesterday's code can send a later session in the wrong direction.

This is why Contract Graph grew into a framework with a delivery workflow around the graph. Planning, implementation, review and completion need to account for the affected contracts as well as the code.

Spec Kit influenced my thinking about structured work. In my own use, it also prompted questions about how much procedure and documentation I wanted to maintain. I chose a small set of lifecycle skills to organise that work. Their number alone says little about their effectiveness: the amount of context they require, their consistency and their maintenance cost still matter.

That experience explains my design choices. A comparison with Spec Kit today would need to account for the version, process and task being compared; its current toolkit has a broader scope than its specification-driven workflow alone.

Making room for discovery

A plan works best when the desired outcome is sufficiently understood. Product work also involves discovering what to build by trying a working experience.

I wanted someone directing development to be able to use a prototype, give feedback and agree an experience before every implementation detail was settled. Prototyping therefore became another entry into the same delivery process.

The framework now supports both exploration through prototypes and delivery organised around Sprint or Epic outcomes. Once a working result is accepted, completion still needs the relevant tests, documentation and contract maintenance.

The aim is to help the person directing the work agree outcomes and judge results, while giving the agent enough structure to carry the work through.

What remains after the work

A completed change should leave useful understanding in the places future work will find it.

Project intent belongs in the maintained project context. A boundary's current promises belong in its contract. Behaviour needs relevant tests, and explanations belong in documentation written for their readers.

Temporary plans and progress records can then be retired when their useful knowledge and required evidence have been preserved, subject to the repository's retention needs. Removing a plan is only helpful if its necessary meaning survives.

This is the continuity I am trying to support: the next session inherits an updated account of the system and the state of the work.

Contract Graph in my own projects

I now use Contract Graph across several substantial projects. In that work, I have not observed the drift that originally concerned me. Having a maintained account of responsibilities, project intent and decisions available across sessions gives me reassurance as development continues.

That is my experience of using the framework in ongoing development, and it is why I continue to invest in it.

Contract Graph Dev Kit is an open-source framework for agentic software development, with repository-native contracts as a graph at its core. It combines that graph with planning, execution, review and completion procedures. At the time of writing, the project has reached version 1.1.0.

Its verification tools check properties of the authored graph, including valid declarations, reciprocal composition relationships, reachability and referenced surface paths. Source inspection supplies evidence for an author to review.

Graph validation, source inspection, behavioural tests and review each contribute different evidence. The contract guide explains the scope of the available checks.

Continuing to develop the idea

Coding agents have improved considerably since I began this work. I continue to refine Contract Graph alongside them, with the same focus on carrying project understanding through changes, sessions and tools.

My own projects provide an ongoing setting for that development. I am interested in how other people apply the approach, which parts help them, and what their experience suggests improving.

I am sharing Contract Graph because it has become a useful part of how I organise agentic development. The project is open source so others can explore the approach, use it in their own work and contribute to its evolution.

Watch the Contract Graph introduction, explore the project website, or read the source code.