Enter fullscreen mode

Before 0.10, AgentScaffold treated every project as its own MCP universe. A monorepo with five services meant five server entries, five processes, five graph handles, and five copies of the generated guidance — and it put the agent in the position of choosing which server to ask. That is not a decision an agent should be making. Plan numbers and file paths are not unique across projects; answering from the wrong one looks exactly like answering from the right one.

0.10 collapses that topology into a single project-aware server. You register the roots you care about, install one MCP entry, and each call resolves its own project from the path being worked on. Alongside that, generated guidance and mutable graph state stop being copied into every project root, and the diagnostics that tell you whether the migration actually worked ship in the same release rather than the next one.

Concretely:

pip install --upgrade "agentscaffold[all]"
scaffold project register ~/work/api
scaffold project register ~/work/web
scaffold mcp install --migrate
scaffold doctor

One server that resolves the project for you

A single MCP server now serves the whole workspace. Register each root with scaffold project register; install the client entry once with scaffold mcp install. The call carries a working path, the server resolves which registered project owns it, and governance and graph reads scope to that project by default. Widen explicitly with --project or --all-projects when the task is genuinely cross-cutting.

A few design choices that are easy to miss and expensive to get wrong:

Registering a root and installing the server are separate commands. Widening what a server is allowed to read should never be a side effect of onboarding a project.
When a call cannot be attributed to a project, the server refuses rather than guessing. A wrong project's answer is worse than no answer, because nothing about it looks wrong — your plan 12 and my plan 12 are both plausible.
--migrate collapses legacy per-project entries in the shared client config and leaves unrelated servers alone. Per-repo .cursor/mcp.json files are not touched, because those are often committed; delete any carrying an agentscaffold entry — scaffold doctor lists them for you — then restart the client. Do that on 0.10.2 or newer: before that, scaffold agents generate-all would write the file straight back, so the last step of this upgrade quietly undid the first.

If you are upgrading from 0.9.x across several repos, the path is: register each repo, run scaffold mcp install --migrate, clean up leftover per-repo entries, restart the client, and re-index. Findings, backlog items, and sessions survive the schema rebuild.

Graph state moves out of the source tree

For registered workspaces, the graph now resolves under your platform state directory, keyed by workspace id, instead of accumulating as .scaffold/graph.duckdb inside every checkout. An unregistered lone repo keeps the historical in-tree location; nothing forces a layout change on you.

Upgrading never relocates an existing database. An in-tree graph always wins over an empty state directory, because flipping a default is not a migration — silently re-resolving would index from scratch and orphan the populated database. Move it deliberately with scaffold workspace migrate-state --apply, which copies, verifies by hash, and only then removes. Dry run is the default. Quit the MCP client first; the command refuses to start while another process holds the database.

Diagnostics that ship with the change they diagnose

The registration change and the state migration are the kind of work that fails quietly if you ship them without a way to ask whether they worked. scaffold doctor lands in the same release for that reason.

It only reads. It never repairs, creates, or migrates, so it is safe to run against a setup you already believe is broken. It exits zero whatever it finds, which makes it safe in a shell profile or a git hook; --strict is the gate to put in CI. --tools calls every MCP tool once and reports how each behaved, answering a different question from the configuration checks: not whether the wiring looks right, but whether the tools respond. Write tools are skipped unless you pass --include-writes, which runs them against a disposable scratch project so your real graph is never touched. A graph held by another process reports as busy rather than as a failure — an index running in the next terminal is routine, and a diagnostic that treats that as a defect stops being trusted.

scaffold gc reclaims state left behind by workspaces that no longer exist. Dry run by default; --apply is the deliberate act.

What else landed

A few changes that would otherwise get buried under the headline:

Relative Python imports now produce IMPORTS edges. Impact analysis walks those edges to answer what else a change affects; missing ones make the blast radius look smaller than it is. The graph schema version moves from 9 to 10 so existing graphs heal through the normal preserving rebuild on the next index rather than staying quietly incomplete.
Finding extraction anchors [CATEGORY] tokens to the start of a line, where a real finding marker sits. Ordinary prose that happened to mention one no longer manufactures garbled rows. scaffold graph prune --malformed-findings clears rows already written, from both the graph and the artifact re-indexing restores from.
scaffold_validate with check="layers" is implemented. It enforces the layering rule your AGENTS.md states — a component consumes the layer below it and does not bypass intermediate ones — and returns not_evaluable when the graph does not contain enough to answer, rather than reporting a clean bill of health on the strength of having looked at nothing.
All 31 MCP tools are specified in the interface contract, including the begin/complete lifecycle pair and the five write tools.
The point releases through 0.10.5 hardened the upgrade path and the write tools. The generate-all collision above, graph locks stranded by processes that died holding them, and resolve tools that reported a miss as a success. The CHANGELOG has the specifics; none of it changes the shape of anything described here.

The first scaffold index after upgrading rebuilds rather than incrementally updating. Governance data is exported before the rebuild and re-imported after; if the export fails, the rebuild aborts and the existing graph is left intact.

Try it

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

Multi-repo upgrade notes are in the docs. If your preferred workflow is "figure it out as we go," the gates will feel like friction — which is the point, not a bug I haven't gotten around to fixing.

To learn more about Agentscaffold check out this article: https://dev.to/dr_data/agentscaffold-memory-peer-review-and-continuous-improvement-for-ai-coding-agents-43fb

The repo, with full docs, is at github.com/drobbster/agentscaffold. If you've got design suggestions, start a conversation.