specs/
What we plan to build, written so it can be regenerated.
template spec.md /cv:new specThe 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 Invitation
This isn't our IP.
The directory pattern, the file format, the practice — they're an open specification, in the spirit of the original Hyperloop paper. We thought of this; here's how it works; someone please build it, fork it, improve on it, or adopt it as-is. The kit is MPL-2.0, and what you make with it is yours.
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 →