COG-second-brain: a markdown vault with a verification harness bolted on
Self-evolving second brain with 33 AI skills, 10 agents, and people CRM. Closed-loop harness: a V-model verification lifecycle where the worker never grades its own homework. Plus paired anti-slop design skills for marketing and product UI. Works with Claude Code, Cursor, Kiro, Gemini CLI, Codex.
At a glance
- What is it?
- COG is an MIT-licensed collection of 33 AI skills, 10 agents and a people CRM that stores everything as .md files in Git. Its distinguishing feature is an opt-in V-model harness where read-only verifiers check the work of the agents that produced it.
- Who is it for?
- Adopt COG if you already keep notes in markdown and want agent workflows that leave a Git diff behind, and if you are willing to run the verification harness deliberately rather than assume it protects every task.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly HTML, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What COG is trying to fix, and for whom
Most personal knowledge tools ask you to move your notes into a database, a proprietary workspace, or a hosted service. COG takes the opposite position. The README describes the stack as 'Cognition + Obsidian + Git' and states that there is no database and no vendor lock-in, only .md files that the agents read and write. The repository's primary language is HTML, which tells you the shipped artifacts are largely agent-facing documents and manifests rather than a compiled application. That is the whole pitch: your vault stays a folder of markdown, and the intelligence lives in skill definitions that any markdown-reading agent can follow.
The target user is narrower than the tag list suggests. There are skill groups for personal capture (braindump, url-dump, weekly-checkin), for product managers (create-user-story, generate-prd, generate-release-notes, publish-to-confluence), and for engineering leads (team-brief, meeting-transcript, comprehensive-analysis). The team-brief skill cross-references GitHub, Linear, Slack and PostHog and syncs back to Linear. So COG assumes you already have those accounts and that your agent can reach them. A solo user with no Linear workspace gets a smaller subset. The people CRM and the Obsidian topic tag point at someone who keeps relationship notes alongside work notes and wants an agent to maintain both.
The V-model harness: workers build, read-only verifiers check
The interesting design decision is the closed loop. The README's mermaid diagram shows skills delegating to 6 workers and being verified by 4 read-only verifiers, with the verifiers observing the same .md files the workers write. The harness section describes the flow as a V: decompose the request leftward into falsifiable criteria, build at the apex, then verify rightward with evidence traced back to each criterion. The phrase the project uses for the alternative is that the worker never grades its own homework.
Two details matter more than the diagram. First, the harness is opt-in. The README states plainly that if you say nothing, none of it runs and ordinary work carries no verification. So the loop is a mode you invoke, not a property of the system. Second, the verifiers are described as read-only, which is the mechanism that keeps the check independent: they can inspect the vault and the evidence but cannot edit the artifacts they are judging. Whether that read-only status is enforced by tool permissions or by convention is not spelled out in the supplied material, and that distinction decides how much the guarantee is worth. If it is convention, a capable agent can still write; if it is a permission boundary, the separation is structural. The repository does not say which, so treat the claim as a design intent to confirm in your own setup.
Getting it running: two install paths and a validation script
The README gives two routes. The manual one is a clone followed by an onboarding prompt inside your agent:
git clone https://github.com/huytieu/COG-second-brain.git cd COG-second-brain
The second route uses the skills.sh registry:
npx skills add huytieu/COG-second-brain
The onboarding command differs per agent, and this is where the repository's surface fragmentation becomes visible. Claude Code uses code . followed by 'Run onboarding' and reads .claude/skills/. Antigravity reads .agents/skills/ plus .agents/rules/cog.md. Cursor reads .cursor-plugin/ plus .cursorrules. Kiro uses 'setup COG' against .kiro/powers/. Gemini CLI uses /onboarding against GEMINI.md and .gemini/commands/. OpenAI Codex uses AGENTS.md. The README claims personalization completes in about two minutes, and SETUP.md covers optional configuration for Git sync, iCloud and Obsidian Tasks.
One command is worth running before you trust any of it. The README instructs contributors to run ./scripts/validate-agent-surface.sh before publishing or updating framework files, to catch drift between manifests, docs and shipped files. That script is effectively a self-audit of whether the surfaces you think you installed are the surfaces that exist. Run it on your own checkout rather than assuming the published matrix matches the files.
The surface matrix is honest, and that honesty is a limitation
The support matrix is the least promotional part of the README, and it should shape your expectations. Only Claude Code and Antigravity are described as full surfaces with 33 skills and 10 agents. Antigravity's coverage is implemented as pointer stubs in .agents/ that delegate to the .claude/ playbooks, which the README says stay authoritative. That means Antigravity users are running Claude Code's definitions through a thin indirection layer, not a parallel implementation.
Kiro and Gemini CLI get 7 native powers and 7 native commands respectively, described as core workflows today. Cursor gets a plugin manifest plus rules. Codex and other agents fall back to AGENTS.md, which documents 33 commands but is a document, not a loader. There is also a root plugin.json declared conformant with the Agent Plugins 1.0.0 specification, so any standard-aware client can load COG as a plugin. The practical consequence: if your team is standardized on Cursor or Kiro, you are not getting the same product as a Claude Code user, and the README says so rather than hiding it. Anyone evaluating COG for a mixed-tool team should read docs/AGENT-SUPPORT.md before making promises about parity.
Where the design is thin: verification scope and memory trust
The verification harness is the differentiator, and it is also the part with the most unanswered questions. Because it is opt-in, the default state of the system is unverified. A user who installs COG, runs onboarding and then works normally gets no verifier pass at all. Nothing in the README suggests the harness runs automatically on high-stakes skills like generate-prd or publish-to-confluence, which are exactly the tasks where an independent check would matter most. That is a gap between the marketing framing ('closed-loop harness') and the default behaviour.
The memory-hygiene skill points at the same problem from another angle. It performs a trust sweep of persistent memory, re-verifying claims against the live environment and stamping last_verified plus a confidence value. The existence of that skill is an admission that stored agent memory drifts and needs periodic re-checking against reality. If you skip it, your vault accumulates claims that were true when written and are silently wrong later. COG gives you the tool to detect that; it does not schedule it for you. Similarly, content-factory claims ledger deduplication, hard volume caps and screenshot-verified posting, which are sensible guards, but the README does not describe what happens when a cap is hit or a screenshot check fails. Treat those as behaviours to observe rather than guarantees to rely on.
How it differs from a plain Obsidian vault with a chat plugin
The obvious alternative is an Obsidian vault plus a general-purpose assistant that can read and write files. The difference is not the storage format, which is identical, but the packaging of procedure. COG ships named skills with defined inputs, defined outputs and, in the harness case, defined verification steps. A generic assistant asked to 'write a PRD' improvises a structure each time. COG's generate-prd skill has an approval gate before publishing to Confluence or Notion, and the PM workflow chains research, PRD, stories, release notes and knowledge base updates into a named sequence.
The second difference is cross-tool reach. A chat plugin lives inside one application. COG ships surfaces for Claude Code, Antigravity, Cursor, Kiro, Gemini CLI and Codex, plus the Agent Plugins standard, so the same skill definitions travel with you. The cost of that portability is the fragmentation described above: the same skill count does not mean the same capability on every client. The third difference is the verification layer, which a generic assistant simply does not have. If you never invoke the harness, that advantage disappears and COG reduces to a well-organized prompt library in a Git repository, which may still be worth it, but it is a different product.
Maintenance cost, licensing and what to check first
COG is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement with few obligations, but it is not legal advice and the repository's own notices should be read directly if you plan to redistribute framework files inside a company. The licence covers the framework; it does not cover whatever your agent sends to GitHub, Linear, Slack, PostHog, Confluence or Notion, and those integrations are where your data actually leaves the machine.
Maintenance has two distinct costs. The first is upstream churn. The release history shows v3.8.0 introducing the closed-loop harness, v3.8.1 adding paired anti-slop design skills for marketing and product UI, and v3.10.0 introducing the Agent Plugins standard, all within roughly a month. The update-cog skill exists specifically to update framework files without touching your content, which is the right shape for that problem, but it also means the project expects you to keep pulling. The second cost is surface drift. With six agent clients, a plugin specification and a fallback document, the manifests and the shipped files can disagree, which is why validate-agent-surface.sh exists. Before adopting, run that script, read docs/AGENT-SUPPORT.md for your client, and decide whether the opt-in harness is something your team will actually invoke on the tasks that matter.
Editorial conclusion
Adopt COG if you already keep notes in markdown and want agent workflows that leave a Git diff behind, and if you are willing to run the verification harness deliberately rather than assume it protects every task. Do not adopt it if you need a database-backed knowledge system with enforced schemas, or if you expect the agent surface to behave identically in Cursor and Kiro: the repository's own support matrix describes full surfaces only for Claude Code and Antigravity, with Kiro and Gemini CLI limited to 7 native powers and commands each. Verify three things before committing: run ./scripts/validate-agent-surface.sh to see whether the manifests, docs and shipped files agree in your checkout; read docs/AGENT-SUPPORT.md to confirm your agent is in the first-class column; and confirm that the verifier agents are read-only in your configuration, because the entire verification claim rests on workers not grading their own output.
Community notes