specs/
What we plan to build, written so it can be regenerated.
template spec.md /cv:new specThe whole idea
OKF CompliantA dead simple, highly flexible, surprisingly effective pattern for context & memory.
Just add a folder to every repo: context-v/
your-repo/ ├── src/ ├── README.md └── context-v/ ← markdown, in git ├── specs/ ├── explorations/ ├── reminders/ └── …
The Hook
Treat context with the same vigilance as code — and the context becomes the parent to the code.
Most coding agents fail not because the code is hard, but because the context is missing. You hand the agent a problem; it doesn't know your conventions, your prior decisions, the mistakes you made last quarter. So it guesses.
Treat context with vigilance — versioned, reviewed, cross-linked — and something flips. Code becomes regenerable. A bug fix compresses from days to minutes. Migrating across languages goes from "we'll plan a quarter for that" to "we did it Tuesday afternoon." The agent didn't get smarter. It finally has the ground it needed to stand on.
Try:
The Practice
Eight folders. Three cognitive modes.
Every file is written for three readers: the human editing it, the agent loading it as context tomorrow, and the public reader who lands on it cold. Frontmatter is a contract. Cross-links are how attention navigates a tree too big for any one head.
plans/
Sequenced, scoped work plans, between a spec and a prompt.
template plan.md /cv:new planprompts/
Step-by-step implementation, each step checkable before the next.
template prompt.md /cv:new promptblueprints/
Patterns proven enough to lift into the next project.
template blueprint.md /cv:new blueprintreminders/
Things we keep forgetting until we wrote them down.
template reminder.md /cv:new reminderagent-skills/
Executable know-how agents load and follow, not just read.
pattern Skills born next to the code they serve <name>/SKILL.mdexplorations/
Research where the destination isn't clear yet.
template exploration.md /cv:new explorationissues/
The painful debugging paths and what they taught us.
template issue.md /cv:new issue
Modes
- Prep Deciding what to build before we build it.
- Reflection Codifying what works and what doesn't after we built it.
- Journey Capturing research and the painful debugging paths along the way.
Experimental tier
Five folders the practice is actively trialing. Their shape is deliberately not yet enforced — divergence between repos is expected and surfaced, not normalized. This is the on-ramp every canonical folder took: plans/ and agent-skills/ both started here.
- loops/ Your own process, written down once, so an agent runs it the same way every time.
- handoffs/ End-of-session state, so the next session resumes without re-deriving it.
- decisions/ The moment intent changed: what, when, why, and the alternatives passed over.
- habits/ Recurring upkeep with a trigger and a scope: "Maintain X across Y."
- contracts/ Not suggestions: standing rules for agents, or exact interfaces data must follow.
In practice, also
- extra/scratch, gitignored
- sitemap/what exists where
- config.mdwhich tool fills each role
Real-world context-v grows a long tail beyond the canonical eight. In isolation each folder makes sense; the discipline tolerates the tail and promotes what earns it: assimilation, not enforcement. See it at scale in the corpus.
The Flow
Our recommended flow.
Explore until the question is clear, decide, write the spec, plan it, then build:
as a team with /cv:loop, or solo with
/cv:implement. Then reflect, and
what the cycle taught you becomes issues, and from there reminders, blueprints, and
agent skills the next cycle starts with.
The Patterns
What years of context-v files taught us.
Some conventions settled into canon. Some are still experiments. Each one says why it exists, so you can decide whether it fits your work.
The Questions
Fair questions.
Doesn't all that context overload the context window, raise token costs, and slow the agent down?
It doesn't for us, because we don't autoload it. A context-v folder sits on disk until something asks for it. Context reaches the agent four ways, roughly in order of how often:
-
Pointed at.
A handoff doc in
context-v/handoffs/, or a reference to the specific docs the task needs. The agent loads those, and nothing else. - Found. The agent's own ripgrep and find scans turn up what it needs almost every time.
- Mapped. Our more complex repos keep Graphify output the agent can use to find what it needs when loading docs by hand falls short, which is rare.
- Queried. Every context-v file is regularly rolled up into a corpus at the pseudomonorepo root, then pushed into a Chroma vector database that every project reaches over MCP. Agents query it when it's relevant.
Without hard checks that block a merge when docs and code drift apart, how do the docs stay true?
They drift a little, and that's fine. We assume the implementation will diverge somewhat from its context-v docs, and treat that as natural rather than as a failure to block.
The date fields in the frontmatter make hard checks mostly moot. A doc that's old and hasn't been modified or versioned recently isn't autoloaded into a session, so in practice it doesn't collide with current work.
During Reflect, we update the docs a cycle used to match what was
actually built. Some projects also keep a sitemap/ folder,
and we're trying a mirrors/ folder that describes the
current state of the code and application.
We haven't tried a fully automated software factory that builds and maintains code with no human oversight, and we're not sure it's a good idea yet. Still, each iteration gets faster and better with less oversight than the last. So maybe we're heading that way anyway.
"Code becomes regenerable" is a bold claim. Have you actually regenerated something real?
Sort of. From the context-v docs, we've upgraded tech stacks, migrated between stacks and languages, and decomposed a monolith into a federated architecture. Each took two or three passes, with almost no prompt engineering beyond "Please rebuild this."
Don't agents get worse with more context? With 13 folders, indexes, and handoffs, how do you keep what they read in check?
Most of it never gets read in a given session, since nothing is autoloaded (see the first question). Where we do see trouble is when a long session truly fills the context window. The model gets something like anxiety, the closest human analogy: iteration slows, mistakes increase, and randomness creeps in.
So we stop implementing, co-write a handoff doc, close the session, and start fresh. It works, for reasons we don't fully understand, a bit like rebooting an old Windows PC.
The Invitation
A common pattern, openly shared.
We've used this context-v pattern across 40+ repos. We like it: for us it has worked better than popular variants like Spec Kit and OpenSpec. Steal what you like, abandon what you don't. Make it your own. MPL-2.0 license.
For developers
Install the plugin.
Two commands in Claude Code, or copy the skills into any agent that reads them. No server, no database, no config.
Get started →For practitioners
Read the patterns.
21 conventions and experiments, each with its reason. Lift what's useful. The vocabulary is yours to use.
The patterns →For the curious
See it at scale.
Our own work: 1,000+ context-v docs across 40 projects, in
the corpus. Fellow travelers:
agents.md,
llms.txt,
spec-kit.
— Build with us, build alongside us, or build your own. GitHub →