DevSpark's Next Evolution: Rethinking Where Knowledge Lives

A Challenge I Kept Avoiding Instead of Solving

Since I started working with spec-driven development, there's a challenge I've circled around for years without landing on a real solution: what do you actually do with a spec once it's done?

Archiving it was never actually a solution — it was avoidance dressed up as diligence, a way of not deciding while feeling like I'd decided something. Deleting it outright felt reckless, so filing it away felt like the responsible choice. But it wasn't a choice at all, just the problem kicked down the road: every completed spec I archived just sat there, one more entry in a growing pile of requirements, plans, and implementation notes that almost no one ever opened again once the feature shipped.

I tried a few different non-solutions over time — a /completed folder, a changelog entry, a note in the README — and none of them actually solved anything, because none of them addressed the real challenge: a developer picking up a six-month-old module doesn't need to know what the spec said before three rounds of revision, and an AI agent generating new code doesn't need the history of how a decision was made. It needs to know what's true right now.

That's the discovery underneath everything else in this article: a completed spec isn't something you need to do something with, in the sense of filing or archiving. It's a transaction that already cleared. The document's job was never to persist — it was to get the project from one state to the next, and once it has, hanging onto it as documentation is solving the wrong problem.

I didn't arrive at that in one step. DevSpark itself gave me two real solutions before this one, and looking back, each one was a genuine step forward that still didn't fully solve the challenge.

The First Solution: Give Completed Specs a Home

The first real solution was /devspark.release. Instead of completed specs scattered wherever they happened to land, release runs at the end of a sprint, validates that a spec's tasks are actually done — not just marked Complete while edge cases sit unchecked — and moves it to .documentation/specs/archived/ under a version-tagged path. The living specs directory stays current. The archive tells you exactly which release a spec shipped with.

That felt like real progress, because for the first time a completed spec had a defined, permanent home instead of an ad hoc one. But it was still just relocating the document. A well-organized archive of specs nobody rereads is still an archive of specs nobody rereads — it's just tidier about it.

The Second Solution: Extract the Knowledge, Then Let the Document Go

The second solution, /devspark.harvest, is the one that actually got closer to the real challenge. Harvest runs after release and does something release doesn't: before it deletes or archives anything stale, it checks whether that material contains insight worth preserving — a decision that belongs in an ADR, a rule that belongs in the constitution, a pattern that belongs in the architecture docs. Only after extraction does the source material get cleaned up.

That's the first place the framework treated a spec's value as something separable from the spec's text. It's the direct ancestor of everything in the rest of this article. But living with harvest for months exposed two things about it I hadn't fully appreciated when I built it. First, it's a sweep — something you run at sprint end, decoupled from any individual spec's own completion, which means the knowledge sits unextracted until someone remembers to run it. Second, the place it extracts to is still a handful of narrative documents — the constitution, an ADR folder, an architecture doc — and those documents have exactly the staleness problem I was trying to solve in the first place. I've written before about how much faster the constitution goes stale than I expected; harvest was proof that extracting knowledge isn't the same as keeping it current.

That's the gap I'm trying to design my way out of now. I want to be upfront about where this article actually stands: none of what follows exists in DevSpark yet. This is me working through the specifics of the next evolution, not describing something shipped — and I don't have it fully solved.

What I Think a Specification Actually Describes

Every specification I write implicitly describes two states: the application as it exists today, and the application as it should exist once the change lands. New capability, revised business rule, architectural shift, or a piece of functionality that needs to go away — the spec's entire job is to define the delta between those two points. Implementation applies that delta to the code. Once the delta has landed, the document that described it has done its work. It doesn't need to keep living as an artifact of record; git already does that job.

I resisted this framing at first because it felt like it was devaluing all the careful writing that goes into a good spec. It isn't. It's the opposite — it's taking the spec seriously enough to ask what happens after it succeeds, instead of leaving that question unanswered the way I had for years.

What I Think Needs to Survive Instead

If the spec itself is temporary, something has to be permanent, or the project has no continuity at all. The direction I keep arriving at is that only two things should persist after a specification completes:

The code — the executable system, unambiguous because it runs.

Something like a living knowledge model — I've been calling it the Project Collective in my notes, though the name matters less than getting the shape right. The idea is a representation that explains what capabilities exist, which business rules are active, what architectural decisions are in force, which patterns new work should follow, what the domain's vocabulary means.

Everything in between — plans, task breakdowns, implementation notes, review threads, the spec itself — is working material. Git keeps the history. But history and truth aren't the same thing, and only one of them should be authoritative for the next person, or agent, that needs to act on the project.

What I'm trying to avoid is recreating the exact trap traditional documentation falls into — a folder that gets bigger every quarter and less trustworthy with each addition, because nobody can tell which parts are still accurate. I want the opposite: a continuously refined answer to "what's true about this project right now," where old answers get replaced instead of stacked on top of. I know what I want it to not be. I'm less sure yet what it needs to concretely be.

The Part That's Actually Hard: Two Very Different Consumers

Here's where I keep getting stuck, and it's the part harvest never had to deal with, because harvest only ever wrote to documentation that a human would eventually read on their own schedule.

The knowledge I'm describing has to serve two very different consumers. At build time — when I'm asking an agent to draft a new spec, assemble a plan, or generate the prompt for the next unit of work — the knowledge needs to get pulled together deliberately, ahead of time, into whatever context the agent is about to reason over. That step can afford to be a little slower and a little more careful, because it happens once per spec.

At runtime — when an agent is mid-session, implementing or reviewing or answering a question — it needs to look something up right now, cheaply, without reloading everything it might conceivably need. That's a completely different access pattern, closer to a targeted lookup than a deliberate assembly step, and I don't think the same artifact format serves both well without compromise.

I don't have this solved. What I have is a set of constraints I'm trying to design against, and they pull in different directions.

What I'm Actually Trying to Solve For

When I picture this working the way I want it to, four things have to be true at once, and I haven't found a design that gets all four without trading one off against another:

More accurate prompts. The knowledge an agent works from has to reflect what's actually true right now, not a stale assumption baked into a doc six revisions ago, and not something the model half-remembers from training.

Less token usage. If every prompt has to carry the whole constitution or the whole architecture doc to be safe, that's the opposite of what I want. Small, targeted knowledge should cost less context than a big narrative file, not more.

Portability. Whatever this becomes has to work whether the agent behind it is GitHub Copilot, Claude, or something that doesn't exist yet. That rules out anything that only works because it's wired into one vendor's retrieval stack.

Transparency. A human has to be able to open a file and see exactly what an agent was given, not trust an opaque similarity score from a system nobody can audit by reading it.

The obvious instinct is to reach for embeddings and a vector store — that's the standard answer to "find the relevant knowledge cheaply." But that trades transparency for convenience, and it introduces a new kind of staleness: embeddings drift out of sync with the source text the same way documentation drifts out of sync with the code, except now there's a second system that has to be kept honest instead of one. It also isn't obviously portable — it's one more piece of infrastructure a project has to run.

The alternative I keep circling back to is closer to a plain-file ontology: small markdown or YAML objects, one canonical file per concept, loaded by convention rather than similarity search. That's honest and portable and diffable in git. What it doesn't solve on its own is which of a hundred small files is relevant to the task in front of the agent right now — and until I have a good answer for that, I haven't actually solved the token-cost or accuracy problem, I've just relocated it.

What I Think Assimilation Would Need to Do

The mechanism that would keep any of this honest is what I'm tentatively calling assimilation — the idea that it's the last phase of every specification, running immediately after implementation completes, rather than waiting for a periodic sweep the way harvest does.

The part I can describe with some confidence is the shape of the operation: assimilation would take the durable knowledge that came out of an implementation — a new capability, a changed rule, a pattern that proved itself, a decision that's now load-bearing — and merge it into whatever the knowledge store turns out to be. Concretely, that means updating an existing object, refining one that was vague, adding something new, or — the part most documentation practices never do — deprecating or removing knowledge that no longer reflects reality.

The part I can't describe with confidence yet is how automated this can actually be. Recognizing that a spec explicitly changed a stated rule is one thing — that's close to what harvest already does. Recognizing that a rule quietly shifted because of how three unrelated specs interacted with each other over the last two months is a different problem entirely, and I don't yet trust an agent to make that call unsupervised. Some version of human review probably has to stay in this loop. I just don't know how much.

The Destination I Keep Coming Back To

Whatever the knowledge store ends up being, I don't think it can be a handful of sprawling markdown files — the kind where "architecture.md" tries to cover everything from deployment topology to naming conventions to a decision made eighteen months ago that's no longer relevant. That's harvest's actual blind spot: it extracts knowledge correctly, but the destination it extracts to has the same growing-pile problem I started with, just relocated one layer downstream.

What I keep sketching instead is small, single-responsibility objects, each with one canonical home — a business rule in exactly one place, an architectural decision in exactly one place — governed by a small ontology that defines what kinds of knowledge exist and how they relate, before anyone writes a word of prose about them. I think that solves the transparency and portability problem cleanly. I don't yet think it solves the retrieval problem — deciding which handful of objects an agent actually needs for a given task, at build time or at runtime, without either missing something important or dragging in everything "just in case." That's the open question sitting underneath all of this.

Why I Think This Is the Right Shape, Even Unfinished

One thing that keeps me convinced this is worth the effort, rather than a tidier way to organize docs, is that the lifecycle of a single specification looks like a miniature version of the lifecycle of the whole project. The pattern I keep sketching on a whiteboard looks something like this:

current state → proposed future state → implementation → assimilation → new current state

A project begins as an idea, evolves through a sequence of changes, and each change updates both what the software does and what the project understands about itself. Zoom into a single feature and you're looking at the same arc. Zoom out to the entire application's history and it's the same shape, repeated at a larger scale. That kind of recursive consistency is usually a decent signal that an abstraction is describing something real — but a signal isn't proof, and I want to be honest that I haven't built enough of this to know for certain yet.

Where This Leaves Me

None of this is DevSpark today. Release and harvest are real, shipped, and doing real work. Everything past that — the delta framing, the two-consumer problem, the knowledge store, assimilation as a per-spec phase — is the next evolution I'm actively working through the specifics of, and I don't have a finished design.

What I do have is a clearer sense of the constraints: knowledge that has to serve build time and runtime differently, that has to cost less context rather than more, that has to stay portable across whatever agent I'm using next year, and that has to stay something a human can actually read and audit rather than trust blindly. If I can get all four of those at once, I think it changes how good the prompts DevSpark assembles actually are. I just haven't proven it yet.

Explore More

• Why I Built DevSpark — the origin story behind treating AI-assisted development as a discipline instead of a series of one-off chats
• DevSpark: The Evolution of AI-Assisted Software Development — how the framework itself has changed shape over time
• DevSpark: Months Later, Lessons Learned — the practitioner's check-up where I first admitted the constitution goes stale faster than expected
• Workflows as First-Class Artifacts: Defining Operations for AI — the same "give it a file, a diff, and a review" discipline applied to AI operations
• DevSpark and Agent Skills: Beyond Portable AI Capabilities — what it means for capability, not just documentation, to have a lifecycle