Context Vigilance
A deceptively simple framework for Human + AI collaboration that unlocks profound workflow improvements. Four directories. Two conceptual pairings. One principle: manage the context available to AI and collaborators with the same rigor you manage code.
Where This Came From
The Problem
Early adoption of AI code assistants was a massive productivity unlock -- and a massive source of frustration. Vibe coding produced spaghetti. AI can overwrite essential work without warning. Oversight over thousands of lines of code written in minutes is improbable. Prompt engineering was ad hoc. Every AI session started from zero, with no memory of the project's architecture, conventions, or hard-won decisions. Remote collaborators worked in isolation with no shared methodology, everyone hacking away with an AI Code Assistant and no shared context or organizational knowledge.
The Realization
AI collaboration needs way more context, requiring an insane level of documentation. But co-developed and co-managed, it leads to breakthroughs in productivity and consistency. Living documentation, co-developed and co-managed, is fast to write, fast to update, modular enough to fit in context windows, and structured enough to be loaded selectively. The hacker culture instinct to "just implement" doesn't work when your co-developer has no memory and makes enormous assumptions.
The Unlock
A directory called context-v/ in every project. Four subdirectories with clear roles. Two conceptual pairings that mirror how development actually works: planning (specs + prompts) and reflection (blueprints + reminders). Simple enough to explain in 30 seconds. Profound enough to change how your team ships.
Two Pairings. Two Cognitive Modes.
The breakthrough is almost too simple to promote: prompts need specs, and reminders need blueprints. Each pair serves a different cognitive mode -- planning vs. reflection -- and together they cover the full cycle of AI-augmented development.
Specs define the what and why. Prompts execute the how. Every prompt references a spec. Every spec evolves from prompt results.
Blueprints codify patterns and proprietary thinking. Reminders enforce them in-session. Born from repeat frustration, made useful by wider context.
The Four Document Types
Specs
Detailed, living specifications that define what you're building and why. Constantly updated as understanding evolves. The spec is your single source of truth -- every prompt you write fits in the context of working through a spec.
Prompts
These aren't single chat messages -- they're step-by-step, prompt-by-prompt documents. Your implementation chunked into discrete tasks that an AI assistant can handle reliably, where success at each step can be verified before moving to the next. Each prompt references specs, blueprints, and reminders. Each builds on the last.
Blueprints
Codified patterns, architectural decisions, and proprietary thinking. How your extended markdown flavor works. How your components are organized. Why your naming conventions exist. The institutional knowledge that AI needs to respect your system.
Reminders
Born from repeated frustration. We don't use React. We don't want JSX patterns. We use Astro, and Svelte for interactivity. We don't hard-validate frontmatter. Short, sharp corrections that you load into context when the AI starts drifting.
Why It Works
Specs Align Everyone Again, Better
Large teams doing spec-driven waterfall gave way to lean startups and hacker culture. AI makes specs essential in vibe coding -- great news for the veteran devs who remember when specs were the source of truth. The difference: AI writes and updates specs in seconds, not sprints. A living spec that takes 10 minutes to create prevents hours of context-less flailing.
Context Windows Have Limits
You can't feed an AI your entire codebase. But you can feed it a spec, two blueprints, and a reminder. Modular documentation designed for selective loading is the only way to give AI the right context at the right time.
AI Doesn't Learn
Every session starts from zero. The only fix is externalized memory -- documentation that can be reloaded. Context Vigilance turns your project's institutional knowledge into loadable artifacts that survive session boundaries.
It Scales to Teams
Remote collaborators, part-time contributors, and new AI sessions all face the same problem: where's the context? A context-v/ directory in every repo answers that question before it's asked.
It Composes with Tooling
The directory structure enables GitHub API rendering on websites, symlinks into Obsidian vaults for direct editing, and cross-repo content aggregation. Simple filesystem conventions unlock surprising integrations.
It's Honest About the Hype
We watched Vibe Coding → Prompt Engineering → Context Engineering. Each step was useful but incomplete. Context Vigilance is the next step: not just engineering context, but maintaining vigilance over it as a first-class concern.
Take It to the Next Level
The four core folders cover the cycle of planning and reflection. But real development has another mode entirely: journey mode -- where you don't know where you're going when you start, and your goal is simply to get there.
context-v/explorations/ Journey Mode Explorations
Some decisions can't be made from a spec. You need to research, prototype, weigh tradeoffs, and think out loud -- often with AI as a thinking partner. Explorations are documents where the destination is unclear: you're defining the parameters of a key decision, mapping an option space, or working through a technical choice that has no obvious right answer.
context-v/issues/ Journey Mode Issue Resolution
The word "debug" doesn't honor the half-day you just spent on it. Issue resolution documents capture the painful, winding path through complex troubleshooting -- the kind where three Stack Overflow tabs are open, the error message is misleading, and the root cause turns out to be something no one would have guessed.
These don't fit neatly into the planning/reflection pairing -- and that's the point. Not every development activity is a known loop. Sometimes you're bushwhacking. The value is in capturing the trail so the next person (or the next AI session) doesn't start from scratch.
Ready to Get Started?
Create a context-v/ directory in your project. Add four folders: specs/, prompts/, blueprints/, reminders/. When you're ready, add explorations/ and issues/. Start writing Markdown files. That's it.
Every document starts with simple YAML frontmatter:
---
title: "Maintain an Extended Markdown Render Pipeline"
date_created: 2026-03-30
date_modified: 2026-03-30
authors:
- Your Name
semantic_version: 0.0.1
tags:
- markdown
- rendering
- astro
---
Your content starts here. Write in Markdown.
Reference other documents with [[wikilinks]].
Include Mermaid diagrams, tables, whatever helps.