DEV Community: Dave

AgentScaffold 0.10.5: One MCP Server To Rule Them All (Or Just Your Workspace)

Dave — Thu, 13 Aug 2026 17:36:54 +0000

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.

AgentScaffold: Memory, Peer Review, and Continuous Improvement for AI Coding Agents

Dave — Thu, 23 Jul 2026 05:38:36 +0000

An AI coding agent will never tell you it's guessing. It doesn't hedge before a wrong answer, doesn't slow down when it's about to break something three modules away, doesn't leave a nervous comment admitting it isn't sure about this part. Right or catastrophically wrong, it hands you the same clean, confident, well-commented code at the same steady cadence — because in a language model, confidence tracks how plausible the next token looks, not whether the design actually holds up. There's no tell. That single property — fluent output with nothing calibrated underneath it — is what makes a capable agent genuinely dangerous on a real codebase, and it's the problem I built AgentScaffold to manage.

Three structural gaps make that dangerous in practice. First, an agent has no durable memory across the boundaries that matter: a new session, a compacted context window, a teammate's agent picking up the same repo tomorrow. Inside a single conversation it holds context fine; cross one of those seams and it starts over, cheerfully re-deriving everything it worked out yesterday. Second, left to its own devices it approaches each plan a little differently, with none of the consistent rigor a seasoned engineer brings — not out of laziness, but because nothing in the loop requires it. Third, it doesn't learn: catch a mistake on plan 12 and the same class of mistake turns up, refreshed and just as confident, on plan 40. Nothing carries the lesson forward.

My career spans thirteen years as an industrial engineer at Boeing and the last eight-plus years as a data scientist in capacity engineering at Salesforce and Dropbox. A mindset that I learned as an industrial engineer that has persisted across the arc of my career is a systems-level mindset — the habit of spotting poorly designed processes and the toll they take on a system's time and resources, how the absence of standards lets variation creep in, and how, without a governance framework, mistakes accumulate both visibly and invisibly until they erode the outcome the original design was meant to deliver. Building software with an AI agent is just another process, and today's agentic tools run it without standards or a governance framework — failing in all three of those ways at once. AgentScaffold is a governance framework built to solve for them: memory so the agent stops losing state, peer review so mistakes are caught before they ship, and a continuous improvement loop so the standards tighten over time instead of slipping.

Concretely, it's a Python package (pip install agentscaffold). It runs as an MCP server, so it works with Cursor, Claude Code, Windsurf, or anything else that speaks the protocol, and it ships a CLI for the parts that should be deterministic and boring.

Layer 1: Memory — a knowledge graph, not a scrollback buffer

scaffold index parses your repository into a DuckDB + DuckPGQ property graph. Tree-sitter handles eight languages — Python, TypeScript, JavaScript, Go, Rust, Java, C, and C++ — pulling out functions, classes, methods, and interfaces along with the IMPORTS and CALLS edges between them. It's a real graph, not a glorified tag file: on the order of twenty node types and forty edge types, because it doesn't stop at code.

What makes it more than a fancy ctags is that the same index ingests your governance artifacts — plans, interface contracts, ADRs, spikes, studies, review findings, backlog items — and wires them to the code they describe. A review finding isn't a sentence buried in a chat log nobody will scroll back to; it's a node attached to the exact file and function it concerns. Ask "where did we leave off, and what's blocked?" and the agent pulls recent plans, open findings, and next steps in a single MCP call — instead of reading three dozen files to reconstruct the state it had yesterday and then lost.

A few graph engineering details:

Incremental indexing is honest about cost. Every file carries a SHA-256 content hash, and a (mtime, size) prefilter skips unchanged files without bothering to re-hash them. Edge re-resolution is scoped to the files that changed plus their direct importers — not a full-repo rebuild every time you hit save.
Search degrades gracefully. Hybrid search fuses structural matches with semantic ones (all-MiniLM-L6-v2, 384-dim, merged by reciprocal rank fusion). Skip the embeddings extra and it falls back to keyword search — and says so, rather than quietly handing you worse results and letting you assume they're good.
It refuses to confuse "unknown" with "no." Call and import edges exist only for the parsed languages, so Markdown, YAML, and shell are structurally invisible. When an impact query comes back empty, the tools label it unconfirmed, not unused, and hand you a grep fallback. Zero callers means "I didn't find any," not "there are none." A product that exists because agents are overconfident does not get to be overconfident about what's safe to delete.

Module structure comes from the Leiden algorithm (via graspologic), which clusters tightly-coupled files so you can see where your real boundaries are instead of guessing at them from the directory tree.

Layer 2: Peer review — your digital sprint team ready to call BS, before the code exists

Here's the part people skip when they run agents without any governance around them. An agent reviewing its own implementation plan isn't a review — it's the same model grading its own homework, with the exact blind spots that wrote the homework, and it awards itself full marks every time. What a plan needs before implementation is what any decent design review needs: someone else in the room poking at the assumptions, the edge cases, the error paths, and the integration points — not to win an argument, but to catch the thing you can't see precisely because you're the one who wrote it.

AgentScaffold runs two such reviews before a line of code exists. A devil's-advocate review goes after the riskiest assumptions and the ways the plan could fail quietly. An expansion review hunts the missing edge cases, the undocumented error paths, and the consumers the file-impact map conveniently forgot. Install a domain pack — there are ten: trading, mlops, data-engineering, infrastructure, api-services, webapp, mobile, embedded, game-dev, research — and a specialist reviewer shows up with standards and prompts tuned to the field. The trading pack's quant architect review catches the look-ahead bias in a backtest that trains on data the strategy wouldn't have had at trade time; the webapp reviewer flags the accessibility and performance problems everyone plans to fix later. And because the reviews are grounded in the graph, a challenge reads "src/data/router.py has 5 importers not in your impact map," not "consider possible downstream effects."

Then the findings stick around. Record one and it becomes a ReviewFinding node linked to the plan and the file, ranked by severity, resurfacing in every future review of that plan until someone actually resolves it. The next session — different agent, fresh window, no memory of this morning — starts from "this risk is known and open" instead of rediscovering it the hard way. A caught risk should only cost you once.

Layer 3: Continuous improvement — the loop that sharpens the reviewer

This is the layer I'd keep if I had to throw out the other two, and it comes straight out of the industrial-engineering playbook: you don't just fix the defect, you fix the process that let the defect through, so the same class of mistake can't walk in the same way twice.

After implementation, a post-implementation review compares what got built against what was planned — an actual diff, not a satisfied nod. A retrospective records what worked, what took longer than the plan assumed, and what nobody saw coming, into a learnings_tracker. Then the part that actually matters: those learnings get folded back into the artifacts the next plan's review runs against. A recurring process mistake becomes a line in AGENTS.md. A structural gap becomes a change to the plan template. A risk pattern that keeps reappearing becomes a new question in the devil's-advocate prompt itself. A coding mistake becomes a line in an implementation standard.

In full transparency, the loop is process-driven, not a magic self-rewriter. The lifecycle tools own the graph state — they write the findings, stamp the plan as reviewed, hand back a structured retro — and the agent, with you in the loop, updates the files. The framework supplies the ratchet and the checklist; it does not quietly rewrite your rulebook behind your back. Plan, do, check, act — where "act" lands as a concrete diff against the agent's own operating rules instead of a good intention nobody revisits. You do have to build the habit: read the learnings tracker every week and actually integrate what's in it. It's a process, but it works.

What actually lands in your repo

"Governance framework" sounds like a binder nobody opens. In practice it's a set of templates, standards, and the rules that tell an agent how to use them. A template does for knowledge work exactly what a standard does on a production line: it removes variation. When every plan, decision, and experiment is captured the same way, the agent can't quietly skip the step it finds inconvenient, and the next person — or the next session — always knows where to look and what "done" means. scaffold init writes into your project:

Plan templates (feature, bugfix, refactor) — a plan can't leave draft without a file-impact map, a test plan, execution steps, and a rollback plan. This is the standard that quietly ends "I'll figure out testing later."
A spike template — for high-uncertainty work: a time-boxed investigation that pressure-tests the risky assumption before you commit to a full plan, and forces an explicit proceed / pivot / defer call instead of a hopeful "seems fine."
A study template — for experiments, A/B tests, and ablations: hypothesis, variants, metrics, conclusion. The result becomes a durable Study in the graph instead of a number that scrolls out of a notebook and is never seen again.
An ADR template — architecture decision records that capture the decision, the alternatives you weighed, and why. Six months later, when someone asks "why on earth did we build it this way," there's an answer — and the graph can trace which ADR governs which plan.
Review prompts — the devil's-advocate, expansion, and retrospective scripts the reviewers work from, and the same files the improvement loop sharpens over time.
Implementation standards for errors, logging, config, and testing, so the agent five sessions from now isn't reinventing your logging convention from scratch.
Agent rules and state — AGENTS.md plus platform-specific .cursor/rules, CLAUDE.md, and .windsurfrules, so Cursor, Claude Code, and Windsurf all read one operating manual; plus workflow_state.md, backlog.md, and learnings_tracker.md, so context survives a session boundary the same way the code graph does.

None of this clobbers what you've already written: generated content lives in managed blocks, existing files get appended to, and the graph's runtime artifacts are added to .gitignore for you.

If you'd rather see it than read a file tree, here's a short tour of a freshly initialized project — the folders and files scaffold init creates, and how the governance layer and the graph backend actually fit together:

The honest numbers, and when this package isn’t for you

The efficiency case is real, with caveats. In the eval harness, when the agent routes through the tools the way it's supposed to, the raw reduction is about 46% fewer tokens and 84% fewer tool calls on tasks like orientation, impact analysis, and full plan review. Adjust for the fact that agents don't always take the paved road — sometimes they grep around a tool that would've answered in one call — and the replay-behavioral view is closer to 37% / 68%. Quality-adjusted, it lands around 33% / 61%. Those lower numbers are the honest ones, and they're the first thing I'd check if someone else were selling me this.

And it isn't magic. The savings come from the agent reading one structured answer instead of re-grepping and re-reading files to rebuild state it already had — which also means less context burned, and less of the window pressure that triggers the compaction-and-amnesia cycle this whole thing exists to prevent.

You also might not need it. Solo, on a small, short-lived project, a well-written rules file gets you most of the way there, and the indexing and lifecycle overhead won't pay for itself. The value compounds with scale (impact analysis past the point where grep stops being trustworthy), with time (memory that accumulates instead of resetting), and with teams (shared contracts and findings that per-developer rules can't give you). It's alpha, and it's opinionated about process. 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.

Try it

bash pip install "agentscaffold[all]" cd my-project scaffold init # templates, standards, agent rules, MCP wiring scaffold index --embeddings # build the knowledge graph (with semantic search) scaffold mcp # start the MCP server (or use the generated mcp.json)

Commands only tell you so much. Here's a hands-on tour on a fictional app called Appalicious — orientation, impact analysis, a pre-implementation review that records a finding, decision history, and the first implementation step. A quick walkthrough of the core tools and the collaboration protocol that governs the development workflow:

One parting thought: AgentScaffold is designed to be a governance framework that grows with you. If you leverage it correctly, your dev patterns can be learned and the standards and rules can be adapted to your preferences as you use it.

The repo, with full docs, is at https://github.com/drobbster/agentscaffold. If you have any design suggestions reach out, start a conversation.