Most “AI adoption” plans for a large engineering org quietly assume the easy case: a small team, a frontier model with a huge context window, and a greenfield repo. Reality is the opposite. You have five different roles who don’t share a workflow, dozens of repositories, a JVM-heavy multi-module estate with stream-processing and dataflow tooling bolted on, and — because security said so — an open-weight model served through a shared, OpenAI-compatible gateway with a usable context budget somewhere between 32K and 128K tokens, not a million.
This is a blueprint for that case. It is written for the person who has to decide whether to do this and answer for it in a quarter: an engineering leader, not a prompt tinkerer. It comes out of a real, adversarially-reviewed design for moving a cross-functional corporate team to spec-driven development (SDD) with an agent in the loop. Company specifics are stripped out; the shape and the trade-offs are intact.
TL;DR. Neither a spec tool nor an agent-skills library is sufficient alone. Combine them: a pinned spec-lifecycle tool for what to build, a handful of vendored execution-discipline skills for how to build it, and — the load-bearing idea — deterministic code, not prompts, enforces every rule that must never break. Ship it through explicit commands, colocate specs with code, treat requirements as durable and plans as disposable, and roll it out opt-in → default → required, gated on voluntary adoption. Add zero new services to the inner loop.
The problem, stated honestly
A team of analysts, developers, manual testers, SDETs, and DevOps engineers wants AI to make each role’s work simpler. The environment sets hard boundaries:
- The model is a given. An open-weight coding model (think DeepSeek/Qwen-class) behind a shared gateway you don’t control. Plan for the 32K floor and route only the heaviest work to a 128K tier. This single constraint invalidates most “just give the agent the whole repo” advice.
- Open-source only, product-agnostic. No external SaaS in the inner loop; the org is migrating its tracker and wiki to internal tools that speak MCP, so nothing can hard-depend on today’s vendor.
- Minimal friction is the #1 goal. If AI adds ceremony — new tools to learn, more typing, a second place to update — it fails regardless of how clever it is. Nobody changes their primary tool. Nobody’s typing volume goes up.
And a sobering fact worth saying out loud to your stakeholders: there are no credible published enterprise SDD outcome numbers. Anyone selling you a “3× faster” figure is selling. You will have to baseline and measure your own. The design below is built so you can.
Why the obvious answers fail
Two tempting shortcuts, each half a solution:
- “Just adopt a spec tool.” Spec-lifecycle tools give you a clean way to write and evolve capability specs. But the popular ones have zero test-or-verify discipline in their apply step — the agent writes code and declares victory. On a mid-tier model, that is exactly where things go wrong.
- “Just give everyone an agent-skills library.” Skills libraries encode execution discipline — test-first, verify-before-done, systematic debugging. But they have no spec lifecycle and, critically, their auto-trigger mechanisms are tuned for frontier models. On a constrained gateway model, “the agent will notice it should use the skill” is not a plan; in live testing it simply doesn’t fire reliably.
The answer is not to pick one. It is to combine them by selective vendoring — take the spec lifecycle from one, vendor four to six discipline skills from the other, and bridge them with a small set of your own commands. Which brings us to the one principle that makes the whole thing safe.
The load-bearing idea: prompts advise, code enforces
The agent proposes. Deterministic code disposes. Every rule you actually care about — a size budget, a schema, a contract that must match live code, a test that must pass — is enforced by a script that runs the same way every time, not by a sentence in a prompt that a model may or may not honor today.
Prompts and skills are advisory. They shape the agent’s behavior, and on a good day that’s enough. But you never bet correctness on a good day. So the architecture puts a deterministic validation layer between the agent’s output and your repository, and a held-out CI layer the agent cannot see or edit as a backstop. This is the difference between “we told the AI to keep the docs in sync” and “the build fails if the docs drift.” Only the second one survives contact with a real org.
The blueprint in four layers
Think of the system as four layers, top to bottom the flow of authority:
| Layer | What lives here | Who owns it |
|---|---|---|
| L3 — CI enforcement | Held-out checks the agent can’t see or edit: contract tests, schema-compatibility, migration lint. The backstop of last resort. | Platform / SDET |
| L2 — Execution discipline | Vendored skills (tiered test-first for slow JVM builds, verify-before-done, systematic debugging, code review) plus the “disposer” — one deterministic verify script. | The team, in each repo |
| L1 — Spec lifecycle | Living capability specs + delta changes, colocated in each repo; a thin central store for cross-repo contracts. | Analysts + developers |
| L0 — Model & bridges | The gateway model, MCP connections to tracker/wiki, local clones of every repo. Given; you only tune client-side settings. | Given |
Two rules govern all of it: (a) every must-never-break rule is enforced by code, not prose (L2 and L3); (b) every agent workflow is entered by an explicit command, never by hoping auto-trigger fires. Explicit commands are also auditable — you can see exactly what ran.
The five decisions that decide adoption
Architecture diagrams don’t determine whether people use the thing. These five choices do.
1. Explicit commands, never auto-trigger
On a constrained model, explicit invocation is the only mechanism proven reliable. It’s also the auditable one. Six verbs carry the entire methodology — one to turn a story into a spec, one to generate a plan, one to implement task-by-task with evidence, plus review, test-plan, and autotest generation.
2. The spec is written once, consumed four times
This is the structural win. An analyst and the agent turn a story into a spec with concrete given/when/then scenarios — once. That same spec then drives the developer’s plan, the developer’s tests, the manual tester’s checklist, and the SDET’s autotest skeletons. Nobody reverse-engineers scope four times. The analyst becomes an interviewee and editor instead of a document typist and never has to touch git.
3. Specs colocated with code, not in a central wiki
A spec lives in the repo where its implementing PR lands, so spec and code merge in one pull request, revert together, and version with release branches for free. A central store holds only cross-repo contracts and a thin index that points at repos — it is navigation, never authority. Centralize the specs themselves and you have re-invented wiki-rot with extra steps.
4. Requirements durable, plans disposable
Requirements are written at story time and kept alive. Design docs and task lists are generated at the moment implementation starts and thrown away after — regenerating them is cheap with an agent, and it collapses the window in which a plan can go stale. Stop treating generated artifacts as precious. The source is the input; the map can always be re-drawn.
5. Honest scope exceptions
Some things don’t fit and pretending they do destroys trust. Visual dataflow logic on a canvas has no fast test loop and its semantics are invisible in exports — so it stays spec-narrative plus human review, explicitly out of the TDD scope. A methodology that admits its own boundaries is one engineers will believe.
The disposer: one script, four triggers
The heart of L2 is a single, fully-offline verify script, ordered cheap-to-expensive: size caps → schema checks → link/anchor checks → contract-snippet verification against live source → regenerate-and-diff the indexes → structural lint with a remediation hint on every error. The same script runs in four places — the agent’s own post-write self-check, a pre-commit hook, on demand, and as the CI backstop — so feedback lands at write time, not three hours later in CI.
Its contract with the agent is deliberately strict, borrowed from write-boundary designs in the agent-tooling world: hard limits live in version-controlled schemas, and violations are rejected with a remediation message — never silently trimmed or auto-fixed. “index.md is 320/300 lines — split the module detail into a module map” teaches the model to self-correct. Repeated failures trip a circuit breaker that stops and asks a human instead of looping.
There is a one-line acceptance test for the entire design:
If a repo’s index can be wrong while its CI is green, the design has failed.
Rolling it out without a mutiny
Adoption research is unambiguous on two points: top-down provisioning creates access, not motivation, and mandating a practice before people want it backfires. So the rollout earns each step.
| Phase | What happens | Gate to advance |
|---|---|---|
| 0 — Baseline & foundation (4–6 wks) | Store, index, disposer, and pre-commit hooks live in 2–3 pilot repos. Capture the baseline — delivery metrics from existing data plus an anonymous developer-experience pulse. | Metrics queryable; a champion has run one real story end-to-end. |
| 1 — Opt-in pilot (6–12 wks) | Real stories flow through it; weekly office hours; an internal demo day (visibility is the adoption lever). | ≥60% of pilot changes use the flow voluntarily for 4 straight weeks, indexes stay green with no human effort, satisfaction ≥ baseline. |
| 2 — Default, with an exception path | SDD becomes the default for feature work — mechanical checks blocking, the process default-not-mandated. | >80% voluntary adoption, lead time flat-or-improving, review time per PR not inflating. |
| 3 — Required-with-exceptions | Spec artifacts required for feature-class changes; exceptions logged and the escape hatch stays forever. | Sunset clause: two consecutive quarters of attributable delivery degradation → de-mandate back to default. |
The single most important number is voluntary adoption. Mandating only ratifies a reality that already exists.
How you’ll know it actually worked
Measure teams, never individuals. Baseline before you start.
- Voluntary flow adoption — archived changes ÷ feature merges. Anti-gaming check: the spec commit must precede the implementation commit.
- The delivery five — lead time, deploy frequency, change-failure rate, time-to-restore, and rework rate (the AI-era addition — AI amplifies system health and raises instability, so watch the second-order effects).
- Review time per PR — held flat as a guardrail. Throughput inflates exactly when review becomes the bottleneck; if PRs get faster to write but slower to review, you’ve moved the pain, not removed it.
- Developer-experience pulse — satisfaction, flow, review quality. Perceptual, required, and never a gate: self-reported speedups are notoriously unreliable.
And the anti-metrics, the ones that quietly poison a program: lines of code, percent-AI-written, individual acceptance rates, individual rankings. Track any of those and you’ll optimize for exactly the wrong behavior.
The honest risk register
- Index rot becomes the new wiki-rot — mitigated by making 100% of index content generated and failing CI on drift. This is the whole ballgame; see the acceptance test above.
- The mid-tier model underperforms the spec tool’s frontier tuning — mitigated by the L2 discipline skills, the disposer, and keeping every change small. Add golden-set regression suites for your commands so a silent gateway model swap can’t degrade you unnoticed.
- Developer identity shift → resistance — the deepest risk. Mitigated by opt-in per story, real escape hatches, champions acting as mentors, framing the work as spec authorship rather than “the AI writes the code,” and team-level metrics only.
- Cross-repo work has no atomic merge and blows the context budget — accepted and deferred: a manual checklist first, the 128K tier for the rare cross-cut, and no multi-repo orchestration until there’s proven need.
The upgrade path (don’t start here)
The minimal footprint is deliberately tiny: one pinned spec CLI, three small static binaries, a handful of scripts, and markdown. No services, no databases, nothing to operate. Once that is stable, the highest-value additions — ranked by value per unit of operational burden — are cross-repo code search with symbol navigation (the biggest agent-quality gain on a large Java estate), golden-set prompt regression testing, and near-free cost/latency telemetry via the agent’s built-in OTLP export. A catalog UI is a luxury you defer until org scale forces it, not a starting point.
What to steal on Monday
- Draw the line between advice and enforcement. List every rule you’d hate to see broken. For each, decide: is this a prompt (advisory) or a script (enforced)? Anything that must never break belongs in code.
- Write the disposer before the prompts. One offline script with hard caps and remediation hints, wired into pre-commit and CI, will do more for output quality than any amount of prompt engineering.
- Colocate specs with code. Atomic spec+code PRs give you free versioning and free revert. Resist the central wiki.
- Gate the rollout on voluntary adoption, and baseline first. Opt-in until >80% choose it. Measure teams, never people. Publish your own numbers — nobody else has credible ones.
The goal was never “AI writes our code.” It’s a system where the agent can move fast because a deterministic boundary guarantees it can’t quietly break the things that matter. Model proposes; code disposes.
Built on two excellent open-source projects — OpenSpec for the spec lifecycle and the Superpowers skills framework for execution discipline. The blueprint above is the result of combining them for a constrained enterprise environment and hardening the seams where each, alone, falls short.