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 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 that review before a line of code exists. A devil's-advocate pass 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 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.