V-COS — Vagner's Cognitive Operating System
A governance layer for AI-native projects that stops them from degrading over time.
Context engineering at the level of a whole project — not a single prompt. The tools you already use solve pieces: memory-bank files keep context, spec-driven kits bound execution, sub-agents add specialization. None of them stitches it into one coherent system that keeps the project from decaying. V-COS is that stitch.
Building with AI is easy. Keeping it coherent across dozens of sessions is not.
If you build with an AI coding agent — Claude Code, Cursor, or anything similar — you know the slow decay. Every session starts a little colder. The agent contradicts a decision you documented last week. Your CLAUDE.md swells to 600 lines of mixed philosophy, stack notes, and API routes that the agent loads in full and uses in part. Context bleeds. Nobody is checking whether the agent went beyond what you asked.
None of this is an AI problem. It's a governance problem. V-COS is the layer that fixes it.
Where this came from
V-COS wasn't designed in the abstract. It was extracted from a real product.
I'm a solo founder. I built and operate a production SaaS — a business copilot — with AI as my co-developer, across more than 25 development cycles. Squads of AI agents, a product-facing agent talking to real users, and continuous co-development sessions. At that volume, the decay above isn't an annoyance — it's the thing that quietly kills the project.
V-COS is the system that kept it coherent. It's not theory. It's what worked, written down.
The five problems it solves
1. Context decay between sessions. Without a declared protocol for what to load, the agent starts cold every time. V-COS defines an explicit document hierarchy plus a dedicated hot-memory file, so the agent knows exactly what to read and in what order.
2. Implicit hierarchy. When two documents conflict and no rule says which wins, the system fails silently. V-COS makes the hierarchy explicit: most specific wins, hot memory is the authority on current state.
3. Cognitive content mixed with technical reference. The agent shouldn't load database schemas to reason about strategy. V-COS separates always-loaded cognitive documents from on-demand reference.
4. No self-evaluation. Agents make unrequested refactors and touch files outside scope. V-COS embeds a self-evaluation checklist into the governance docs — applied before any delivery, not as a suggestion but as infrastructure.
5. No session protocol. Session close shouldn't depend on you remembering to ask for a state update. V-COS makes the close protocol mandatory and proactive — the agent updates hot memory because it's instructed to, not because it was reminded.
How it works — three layers
┌─────────────────────────────────────────────────┐
│ LAYER 1 — DOCUMENT GOVERNANCE │
│ Hierarchy · Protocol · Memory · Evaluation │
├─────────────────────────────────────────────────┤
│ LAYER 2 — SKILLS ARCHITECTURE │
│ IDE skills · Squad skills · Taxonomy │
├─────────────────────────────────────────────────┤
│ LAYER 3 — AGENT GOVERNANCE │
│ Design · Specialization · Orchestration │
└─────────────────────────────────────────────────┘
Layers 1 and 2 are LLM-agnostic — they work with any model. Layer 3 ships with reference implementations for Claude Code, with principles that transfer to any multi-agent framework.
[Full architecture → docs/02-architecture.md]
What V-COS is not
- Not an agent execution framework. It doesn't replace LangChain, CrewAI, or similar. It governs them.
- Not a project methodology. It doesn't replace Scrum, Shape Up, or Kanban. It sits underneath them.
- Not a memory solution. It doesn't replace RAG or vector stores. It's the governance that makes them coherent.
V-COS is the governance layer that makes all of those work together over time.
Start in one hour
The minimum viable setup is four files:
your-project/
├── AGENTS.md ← entry point: hierarchy + protocol + self-evaluation
├── CLAUDE.md ← cognitive: project context + known pitfalls
├── CYCLE-CURRENT.md ← hot memory: active work + current state
└── docs/
├── REFERENCE.md ← technical reference, loaded on demand
└── CYCLE-ARCHIVE.md ← closed-cycle history
Copy the templates from templates/, adapt them to your project, and point your agent at AGENTS.md as the first file it reads.
[Full setup guide → docs/]
What's in this repo
v-cos/
├── docs/ # the framework in depth — five problems, three layers, harness, spec-driven
├── templates/ # copy-and-adapt files: AGENTS, CLAUDE, CYCLE-CURRENT/ARCHIVE, REFERENCE,
│ # decisions, context-skill, agent + agents/ (reference sub-agents)
├── skills/ # starter skill pack — agnostic, ready-to-adapt (Layer 2)
├── implementations/ # how to wire it to Claude Code, Cursor, or any tool
└── examples/ # V-Strategy — the production project V-COS was extracted from
Tool-agnostic by design
V-COS is a set of principles, not a tool lock-in. The reference implementation uses Claude Code, but the concepts map to any AI coding agent:
implementations/claude-code.md— the reference implementation (what I actually run)implementations/cursor.md— adapting to Cursorimplementations/generic.md— the concepts for any tool
The eight principles
V-COS rests on eight governance principles that hold regardless of project, stack, or scale. A few:
- Explicit hierarchy, never implicit. If two documents conflict and no resolution rule is declared, the system fails silently.
- Hot memory is living memory, not a diary. The active state file reflects only the present and the next step. Completed work moves to the archive.
- Self-evaluation is infrastructure, not a suggestion. If the checklist isn't written into the governance docs, it doesn't exist for a cold agent.
- The system serves the human, not the other way around. Governance exists to reduce friction, not create ceremony. V-COS should be invisible when it works.
[All eight → PRINCIPLES.md]
Proof of use
V-COS runs in production today, governing the development of a real SaaS product across 25+ cycles — IDE agent, AI squads, and a user-facing product agent, operated by one person. The examples/ directory documents how the framework is applied in practice.
Contributing
V-COS is open source and evolving. It's a living system — the same way it treats hot memory. If you adopt it and find a gap, a missing pattern, or a better way to express a principle, open an issue or a PR. Patterns that prove themselves across real projects make their way into the core.
License
[MIT] — see LICENSE.
Author
Vagner Firmino — solo founder & indie hacker, building V-Strategy.
V-COS was extracted from the cognitive infrastructure built in production for V-Strategy. It's not theory — it's what worked.