Keystone: keeping AI-assisted software projects from drifting

The problem

AI coding assistants make a developer much faster on any single task. On a real project, over weeks and months, they cause a different problem: they do not remember the decisions, rules and hard-won lessons that came before. Each session starts fresh. The result is code that drifts away from the architecture, repeats mistakes that were already fixed, and quietly breaks rules nobody wrote down.

The context that keeps a project consistent usually lives in people’s heads, chat histories and scattered documents. None of that is available to the agent when it starts work.

What I built

Keystone keeps that context in the repository itself, in structured files that are validated against a schema, and compiles it into a task brief for the AI agent. The same inputs always produce the same output, byte for byte, so the brief can be reviewed and trusted.

• Requirements, architecture decisions, tasks, rules, learnings and known traps stored as structured, schema-validated files in the repo
• A command-line workflow: initialise, start a task, compile its context, review, close
• Deterministic indexing and compilation, so the output is identical on every run and in every environment
• A three-role review gate that must pass before a task can be closed
• 248 automated tests covering the schema, the compiler and the commands

Why it matters for clients

I use AI assistance in my own development work, and this is how I keep that fast without letting it get sloppy. It is also the clearest evidence I can offer of how I engineer: schemas, tests, deterministic behaviour and a review step before anything is called done.

Keystone was used to manage its own development from the first commit.

Built with

Node.js and TypeScript command-line tool; JSON Schema validation; YAML; architecture decision records; 248 automated tests.