Show HN: V-COS – Governance layer that keeps AI coding agents coherent

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

2 Commits

2 Commits

docs

docs

examples/v-strategy

examples/v-strategy

implementations

implementations

skills

skills

templates

templates

.markdownlint.json

.markdownlint.json

INSTALL.md

INSTALL.md

LICENSE

LICENSE

PRINCIPLES.md

PRINCIPLES.md

README.md

README.md

install.sh

install.sh

Repository files navigation

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.

1. 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.

1. 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.

1. 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.

1. 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 Cursor

implementations/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.

Connect: X · LinkedIn.

V-COS was extracted from the cognitive infrastructure built in production for V-Strategy. It's not theory — it's what worked.

About

A governance layer that keeps AI-native projects from decaying over time — context engineering at the project level, for Claude Code, Cursor, or any AI coding agent.

v-strategy.com.br/

Topics

framework

multi-agent

developer-tools

cursor

governance

ai-agents

claude

llm

prompt-engineering

ai-governance

ai-native

agentic

coding-agents

ai-coding

agent-orchestration

claude-code

spec-driven-development

context-engineering

harness-engineering

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases 1

V-COS v1.0 — Governance layer for AI-native projects

Latest

Jun 14, 2026

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Shell 100.0%