AgentScaffold 0.15

I wrote a good operating manual for my agent. It had hard prohibitions, approval gates, a review process, the lot. The agent, on a busy afternoon, did not read it.

That was the uncomfortable discovery of the last couple of months. Everything I had built assumed a rules file in the repo would be loaded, read, and followed. Sometimes it was. Sometimes the editor skipped it, or the project lived in a folder the editor didn't treat as the workspace root, or the file belonged to another team and I wasn't allowed to touch it. A process that depends on the agent happening to read a file is a suggestion, not a process.

This post covers what came after that, between 0.12 and 0.15. I'll start with a short version of what AgentScaffold is for anyone new, then go through what changed and what each change was solving.

What AgentScaffold is, for new readers

The shortest way I can put it: AgentScaffold is the project manager your coding agent doesn't have.

Picture asking an agent to change how a service retries failed jobs. On its own, it reads a few files, settles on a theory, and starts editing. It will be fluent and confident the whole way, and it won't tell you where it was guessing.

Now put AgentScaffold underneath. Before touching anything, the agent asks the project where things stand: what's in flight, what's blocked, whether a plan already covers this. The change gets written down as a plan, and the plan gets challenged by a reviewer that can see the project's graph, so the objection is specific. This function has callers in three modules the plan never mentions. A finding from two months ago says the last retry change broke the nightly job. Then the code is written and checked against the plan, and a retrospective records what surprised everyone. The lessons go into the rules the next review runs against, so the same mistake gets harder to make twice.

All of that lives in the project itself. Code, plans, decisions, review findings and learnings sit in one knowledge graph that the agent queries through MCP tools. It's a Python package (pip install agentscaffold) that works with Cursor, Claude Code, Windsurf, or anything else that speaks the protocol, with a CLI for the parts that should be deterministic.

I don't think the weak link in agent-assisted development is the model. It's that nothing around the model remembers, reviews, or learns. I made that argument at length in the first post, so I won't repeat it here. This one is about what's changed since.

Making sure the process reaches the agent

This was the biggest change, and it came from the problem I opened with.

The server now hands the agent the working procedure itself, in the connection handshake: start a session, orient, route by intent, close the session. It doesn't matter whether any rules file reached the editor. If the agent connects, it gets the procedure.

The governance manual, the part of AGENTS.md that you write and own, gets the same treatment. Instead of hoping the agent read all of it, the server delivers the sections that apply at the moment they apply. Ask to review a plan and the review rules come back with the review. Start implementing and the approval gates come back with the implementation. And approval is now enforced, not just documented: a plan that needs sign-off will not start until one is recorded.

Two smaller pieces support this. You can install guidance and hooks from your home directory, with nothing written into the repository, which matters when the project sits inside a monorepo you don't control. And edit hooks now refuse changes to paths you've marked read-only, so "don't touch the architecture doc" is something the environment enforces.

The same instinct fixed some quieter problems. Working sessions used to live forever, so one session had quietly collected seven weeks of decisions from unrelated chats. Now they expire after a stretch of idleness. Orient also stopped trusting the workflow diary over the plans themselves, and it tells you when the diary is stale or contradicts a plan file. A status report that is confidently out of date is worse than none, which is exactly the failure this tool exists to prevent.

Reviews that remember

Memory is only useful if the review can see it. The graph already held earlier findings, learnings, and architecture decisions, but a review of a plan didn't go looking for the ones about the same files.

Now it does. When you review a plan, the review surfaces what the project has already said about the files that plan touches: findings that were raised, lessons that were learned, decisions that govern the area. Impact analysis shows the same history next to the callers. The question "have we been here before?" gets answered at the moment it matters, which is before the code exists.

I did try something clever here, and it didn't work. The obvious next step was semantic search over that history, matching findings by meaning instead of by file. I ran a study on it before deciding whether to turn it on. Semantic retrieval found things the structural matching missed, so recall went up sharply. But the precision wasn't good enough, which means a reviewer would be handed a lot of plausible-looking noise. So it stays off by default. I'd rather ship the boring version that is right than the impressive version that makes people stop reading the list.

Working where you don't own the root

A lot of real code lives in repositories shared with other teams. Several changes in this stretch were about that.

A project in a subfolder of a large repository now resolves imports written from the repository root, which previously showed up as unresolved edges. If part of your project lives elsewhere in the repo, you can point at it with a glob and it gets indexed as yours. And the generators no longer write a router into a workspace file you don't control. Each of these started as a small paper cut from one user's setup and would have been invisible to me on a single-repo project.

Knowing what you actually run

This is the part I find most interesting, because it extends the graph from "what the code is" to "what the project runs."

Most projects past a certain age have jobs, services, and workflows that nobody can fully list. Something is paused and everyone has forgotten. Something is deprecated and still scheduled. Something has no owner because the person who wrote it moved on. A plan changes a file and nobody realizes three jobs read it.

0.13 added a system inventory. It is a file that lists the runtime components, with an owner plan, a layer, and a lifecycle: experimental, active, paused, deprecated. Collectors build it from the files that already exist, Prefect deployments, compose files, CI workflows, so you aren't typing a spreadsheet. The components go into the graph, so asking what a file touches now includes the jobs that run it. A plan that touches a paused or deprecated component gets challenged in review, and orient reports lifecycle debt: reviews that expired, deprecations that dragged on.

That version was too much work to keep true, and I found out by using it. I turned it on for the first real project I had. The first pass missed 39 of its 103 components until I fixed a collector path by hand, and then it reported 103 errors, because nothing had an owner, a layer, or a real start date. Getting it running took four hand-made changes the package should have made for me. A tool that asks you to fill in a form for every component is a tool that gets abandoned.

0.14 is the fix, and the idea behind it is simple: declare by exception. You write only decisions, such as pausing a job or deprecating a service. Everything else is derived. Start dates come from git history. Owners come from the plan whose file list created the component, or from a one-line label you put on the service itself. Layers come from the owning plan. The derived values live in a machine-owned file, like a lockfile next to a manifest, so the file you review stays quiet.

Adoption is one command, scaffold inventory enable. It edits the config, writes the files that are missing, runs the first pass, and tells you what it did. A scheduled workflow runs a monthly architecture review and keeps one issue open while there is debt, so the review happens whether or not someone remembers it.

On the same project, starting from scratch, it now finds 104 components, zero errors from missing fields, a real start date for every one, and an owner for every scheduled job. It also flags the 30 components it still can't place, with a one-line fix for each. I like that it says so. That list is the honest edge of what can be derived, and clearing it is how "everything maps" becomes true instead of assumed.

A note on what went wrong while building this: my own test suite was green while the real project found two bugs those tests never would have. One was a service whose command was only flags, reported as a missing file. The other was a mismatch between what the review packet returned and what the contract said it would. The lesson is the one I keep relearning: run the thing on a real project early, not last.

Claude Code was told to use tools it did not have

0.15 is a smaller release than 0.14, and it came from the same kind of miss. I had a user on Claude Code who followed the install steps. The hooks landed. The session text told the agent to start a session, orient, and read the routing policy. Then the agent either reported missing tools or quietly went back to grep. Nothing had registered the MCP server with Claude. scaffold mcp install wrote Cursor's config and stopped. scaffold doctor looked at that file, saw one healthy entry, and said the registration was fine.

That is the failure I keep writing about. The process was present as instructions and absent as tools.

0.15 registers the server for the client you actually have. scaffold mcp install still writes Cursor's ~/.cursor/mcp.json. When Claude Code is installed it also runs claude mcp add --scope user, which is Claude's own way of recording a server for every project. It does not open ~/.claude.json, and it does not drop a project .mcp.json into the repo. A project file would hide the user-level server. --client cursor or --client claude picks one client when you do not want both.

Doctor now checks each client. A healthy Cursor file no longer hides a missing Claude server. If a local or project entry of the same name outranks the user one, it says so.

The session text had a second problem. Cursor gets a long always-on routing rule. Claude Code will not take that much text from a session hook. Past a limit it saves the text to a file and shows the agent a short preview, which would have dropped the part that says what to do. So Claude gets a shorter routing body, the project pointer, and a plain note about what a missing tool list means. Five tools stay loaded even when Claude defers the rest: start a session, orient, end the session, callers, and blast radius. On each prompt, if your wording matches a known request, the hook names the tool to call before grep. The other tools are still there. Claude finds them by search instead of carrying every schema on every turn.

One difference I left on purpose: the tools that write to the graph still ask permission in Claude Code, including starting and ending a session. The read-only tools do not. I would rather a finding get a prompt than have every graph write run silently.

If you have both editors open on the same project, you now have two server processes on one graph file. A read during an index waits a moment and then asks you to retry. That is the honest limit of the file. It is not a second database.

Whether it is worth the overhead

I run an eval harness that compares an agent using AgentScaffold with one that reads files and greps. The latest run covers 125 scenarios. When the agent routes through the tools, I see about 39% fewer tokens and 84% fewer calls. Agents don't always take the tool, so the replay-adjusted view is closer to 31% and 68%, and about 28% and 61% if you also require the answer to stay as good. I'd quote the lower pair.

Token savings dropped from the 43% I quoted in the last release post to 39%, and it's worth saying why. Responses carry more now: the earlier findings, learnings, and decisions about a file. A baseline that reads files would never find those at all. I'll take a response that costs a little more and includes the thing you needed.

If your project is small and the work is a weekend, a good rules file is enough and you shouldn't take on a graph. This starts to pay off when grep stops being a plan, when the work outlives one chat, and when more than one person or agent has to share the same memory. It is still early and it will push back on "we'll figure out the process later." That is on purpose.

Try it

New project:

pip install "agentscaffold[all]”
cd my-project
scaffold init
scaffold index —embeddings

scaffold mcp install                       # Cursor & Claude Code when it is installed
scaffold mcp install --client cursor       # Cursor only
scaffold mcp install --client claude       # Claude Code only

Upgrading an existing install:

pip install --upgrade "agentscaffold[all]”
# uv tool users: uv tool install -U "agentscaffold[all]”
scaffold agents hooks                      # regenerate hooks, once per project
scaffold agents generate-all               # refresh routing so agents see the new tools
scaffold index
scaffold mcp install                       # Cursor, and Claude Code when it is installed
scaffold mcp install --client cursor       # Cursor only
scaffold mcp install --client claude       # Claude Code only
scaffold inventory enable                  # optional: turn on the system inventory

With no --client, the install registers every client it finds. Pass --client when you want one of them. Then restart the editor, not just the MCP server. No graph rebuild for 0.15.

If you'd rather watch than read, here is a tour of a fresh project and a longer walkthrough of orientation, review, and a first implementation step:

Code and docs are at github.com/drobbster/agentscaffold. If I'm aiming at the wrong problem, I'd rather hear that than guess.