specs/
What we plan to build, written so it can be regenerated.
e.g. Codifying a Comprehensive Extended Markdown Flavor and Shared Package astro-knotsThe 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
Six 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.
prompts/
Reusable prompts the team has tuned over months.
e.g. astro-knots/prompts/author-a-specification-markdown-file-in-context-v astro-knotsblueprints/
Patterns proven enough to lift into the next project.
e.g. Build a Fundraise Deck Workspace astro-knotsreminders/
Things we keep forgetting until we wrote them down.
e.g. Preferred Stack — uv over pip, and other defaults ai-labsexplorations/
The painful debugging paths and what they taught us.
e.g. Accessing Figma through a Windsurf MCP Server lost-in-publicissues/
Failure modes worth naming so they don't recur.
e.g. Widening (and Re-Sizing) Obsidian Plugin Modals via CSS content-farm 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.
In practice, also
Real-world context-v has a long tail beyond the canonical six. Counted across the corpus, the most common extra surfaces:
- plans/ 21
- habits/ 4
- workflow/ 2
In isolation each makes sense; we just haven't fit them all into the matrix yet. The discipline tolerates the long tail — that's part of the proof.
The Proof
583 living docs. 27 projects.
One small agency's actual work over 18 months — not a theory paper. 110 mature. 263 started. 210 stubs we'll fill out with agent help. Some are specs you can fork. Some are reminders born after the third time we made the same mistake. Some are explorations that ended in "we decided not to pursue" — and those are valuable too.
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. Schema and tooling are MIT.
For developers
Fork the kit.
The collator script, the schema, the splash you're reading — all on GitHub. MIT-licensed. Treat it as a starter, not a framework.
GitHub →For practitioners
Browse the corpus.
583 files of working notes from 27 projects. Search, sort by repo, lift what's useful. The vocabulary is yours to use.
Open the corpus →For everyone else
Read the spec.
The practice, the why, and where it sits among
agents.md,
llms.txt, and
spec-kit.
Fellow travelers, not competitors.
— Build with us, build alongside us, or build your own.