{
"markdown": "# COG: The Agentic Second Brain That Actually Self-Evolves\n\n**Cognition + Obsidian + Git** — A self-evolving second brain powered by AI agents, markdown files, and version control. No database, no vendor lock-in — just `.md` files that think.\n\n[Quick Start](#quick-start) | [Skills](#skills) | [Features](#features-at-a-glance) | [FAQ](#faq) | [SETUP.md](SETUP.md)\n\n> Works with [Claude Code](https://claude.ai/download) • Antigravity • [Cursor](https://cursor.com/) • [Kiro](https://kiro.dev/) • [Gemini CLI](https://github.com/google-gemini/gemini-cli) • [OpenAI Codex](https://github.com/openai/codex) • any AI that reads markdown\n>\n> Inspired by [Garry Tan's gstack](https://github.com/garrytan/gstack) and [gbrain](https://github.com/garrytan/gbrain)\n\n```mermaid\ngraph LR\n A[You] -- natural language --> B[AI Agent]\n B -- runs --> C[33 Skills]\n C -- delegates to --> W[6 Workers]\n C -- verified by --> V[4 Read-Only Verifiers]\n C -- reads & writes --> D[.md Files]\n W -- reads & writes --> D\n V -- observes --> D\n C -- syncs with --> G[GitHub / Linear / Slack / PostHog]\n D --> E[Git]\n D --> F[iCloud]\n```\n\n## Quick Start\n\n**1. Clone & enter the repo:**\n```bash\ngit clone https://github.com/huytieu/COG-second-brain.git\ncd COG-second-brain\n```\n\n**2. Run onboarding in your agent:**\n\n| Agent | Command | How it finds skills |\n|---|---|---|\n| Claude Code | `code .` → \"Run onboarding\" | `.claude/skills/` |\n| Antigravity | Open folder → \"Run onboarding\" | `.agents/skills/` + `.agents/rules/cog.md` |\n| Cursor | Open folder → \"Run onboarding\" | `.cursor-plugin/` + `.cursorrules` |\n| Kiro | Open folder → \"setup COG\" | `.kiro/powers/` |\n| Gemini CLI | `gemini` → `/onboarding` | `GEMINI.md` + `.gemini/commands/` |\n| OpenAI Codex | `codex` → \"Run onboarding\" | `AGENTS.md` |\n| Other agents | Point at `AGENTS.md` → \"Run onboarding\" | `AGENTS.md` |\n\n**Or install via [skills.sh](https://skills.sh):**\n```bash\nnpx skills add huytieu/COG-second-brain\n```\n\nDone — COG is personalized and ready in ~2 minutes. See [SETUP.md](SETUP.md) for optional config (Git sync, iCloud, Obsidian Tasks, etc.).\n\n## Agent Support Matrix\n\nCOG ships a **full Claude Code surface**, a **full Antigravity surface**, plus **core native surfaces** for Kiro and Gemini CLI, with `AGENTS.md` as the universal fallback for Codex and other markdown-reading agents.\n\n| Surface | Current support | Notes |\n|---|---|---|\n| Claude Code | 33 native skills + 10 agents (6 workers + 4 verifiers) | Full first-class surface |\n| Antigravity | 33 skills + 10 agents (pointer-stub format) | Full surface — thin stubs in `.agents/` delegate to the `.claude/` playbooks, which stay authoritative |\n| [Agent Plugins](https://agent-plugins.org) standard | Root `plugin.json` + `skills/` (33 skills) | Spec 1.0.0 conformant; any standard-aware client loads COG as a plugin |\n| Cursor | Plugin manifest + rules | `.cursor-plugin/plugin.json` + `.cursorrules` |\n| Kiro | 7 native powers | Core workflows today |\n| Gemini CLI | 7 native commands | Core workflows today |\n| `AGENTS.md` | 33 documented commands | Universal fallback for Codex and other agents |\n\nBefore publishing or updating framework files, run `./scripts/validate-agent-surface.sh` to catch drift between manifests, docs, and shipped files. See [docs/AGENT-SUPPORT.md](docs/AGENT-SUPPORT.md) for the detailed support matrix and contributor rules.\n\n## Skills\n\n### Core Skills (Personal Knowledge)\n\n| Skill | What it does | Try saying... |\n|---|---|---|\n| **onboarding** | Personalize COG for your workflow (run first!) | \"Run onboarding\" |\n| **braindump** | Capture raw thoughts with intelligent classification | \"I need to braindump\" |\n| **daily-brief** | Verified news intelligence (7-day freshness) | \"Give me my daily brief\" |\n| **url-dump** | Save URLs with auto-extracted insights | \"Save this URL\" |\n| **weekly-checkin** | Cross-domain pattern analysis | \"Weekly review\" |\n| **knowledge-consolidation** | Build frameworks from scattered notes | \"Consolidate my knowledge\" |\n| **update-cog** | Update framework files without touching your content | \"Update COG\" |\n| **memory-hygiene** | Trust sweep of persistent memory — re-verify claims against the live environment, stamp `last_verified` + confidence | \"Audit my memories\" |\n\n### Team Intelligence Skills (for Product & Engineering Leads)\n\n| Skill | What it does | Try saying... |\n|---|---|---|\n| **team-brief** | Cross-reference GitHub + Linear + Slack + PostHog into a daily team intelligence brief with two-way Linear sync-back | \"Team brief\" / \"What did we ship?\" |\n| **meeting-transcript** | Process meeting recordings into structured decisions, action items, and team dynamics | \"Process this meeting\" |\n| **comprehensive-analysis** | Deep 7-day analysis for weekly reviews, board prep, or strategic planning (~8-12 min) | \"Weekly analysis\" / \"Board prep\" |\n\n### PM Workflow Skills (for Product Managers)\n\n| Skill | What it does | Try saying... |\n|---|---|---|\n| **create-user-story** | Create user stories with duplicate checking across Linear, GitHub Issues, or Jira | \"Create a user story for...\" |\n| **generate-prd** | Draft PRDs with approval gate before publishing to Confluence/Notion | \"Generate a PRD for...\" |\n| **generate-release-notes** | Generate release notes from GitHub milestones, Linear cycles, or manual input | \"Generate release notes for v2.1\" |\n| **export-open-issues** | Audit and export open issues from any tracker into a structured vault summary | \"Export open issues\" |\n| **publish-to-confluence** | Publish any vault markdown file to Confluence | \"Publish this to Confluence\" |\n| **update-knowledge-base** | Maintain product knowledge base from releases, features, and project changes | \"Update the knowledge base with v2.1 changes\" |\n\n> **PM Workflow:** These skills form a complete product management lifecycle: **Research** (`/auto-research`) → **PRD** (`/generate-prd`) → **Stories** (`/create-user-story`) → Development → **Release Notes** (`/generate-release-notes`) → **Knowledge Base** (`/update-knowledge-base`). Use `/export-open-issues` for audits and `/publish-to-confluence` to share externally.\n\n### Strategic Research\n\n| Skill | What it does | Try saying... |\n|---|---|---|\n| **auto-research** | Deep strategic research engine — decomposes questions into parallel research threads with multiple agents | \"Research the future of AI testing tools\" |\n\n### Content Creation\n\n| Skill | What it does | Try saying... |\n|---|---|---|\n| **content-factory** | Autonomous content pipeline — scout announcements, triage by trend momentum + your unique angle, publish with ledger dedup, hard volume caps, and screenshot-verified posting | \"Run the content factory\" |\n\n### Verification Harness\n\nOpt-in. Ask for one of these and work walks a **V**: decompose left into falsifiable criteria, build at the apex, verify right with evidence traced back to each criterion. Say nothing and none of it runs: ordinary work carries no checkpoints and no evidence ledger. Turn it on per request, or by default for build tasks with `verification_harness: on` in `00-inbox/MY-PROFILE.md`. Full lifecycle in [WORKFLOW.md](WORKFLOW.md).\n\n| Skill | What it does | Try saying... |\n|---|---|---|\n| **closed-loop** | Plan → build → component verify → integration verify → acceptance. The worker never grades its own homework; verifiers observe the artifact, not the worker's summary | \"Run this through the closed loop\" |\n| **ultragoal** | A goal too big for one session, run as a chain of phases with cross-session state and a north-star acceptance gate | \"Track this as an ultragoal\" |\n| **harvest** | Capture session learnings, stage them for approval, propose skill patches. Never writes durable knowledge unapproved | \"Harvest what we learned\" |\n| **retro** | Audit the run's checkpoints and *evidence quality*. A run can pass every gate on weak observations | \"Retro this run\" |\n| **review-cockpit** | One living doc per multi-item session: progress, per-item cards, and an approval slot you edit in place | \"Set up a review cockpit\" |\n\n### Craft Skills (Writing & Visuals)\n\n| Skill | What it does | Try saying... |\n|---|---|---|\n| **no-ai-slop** | Sharpen a draft without flattening its voice, or just detect AI-slop patterns | \"Make this less AI-sounding\" |\n| **editorial-illustrations** | Claim → geometry: derive the *right* figure from what the text argues, render it as self-contained theme-aware HTML/SVG | \"Make a diagram for this argument\" |\n| **data-forms** | 20+ chart and diagram forms with when-to-use, failure modes, and the encoding discipline that makes any of them readable | \"The bar chart is burying the point\" |\n| **museum-art** | Real public-domain artwork from museum open-access APIs instead of AI-generated or stock imagery | \"Find a hero image for this post\" |\n| **daily-journal** | A passive work journal the agent keeps for you, plus a guided reflection on request | \"Reflect on today\" |\n\n### Design Skills (Anti-Slop UI)\n\nA paired set. `taste-skill` owns first-impression surfaces, `product-ui-taste` owns surfaces people use every day. Never run both on the same component.\n\n| Skill | Owns | Try saying... |\n|---|---|---|\n| **taste-skill** | Landing pages, portfolios, marketing, editorial. States a \"Design Read\" before writing code so it stops defaulting to one house aesthetic | \"Build a landing page for this\" |\n| **product-ui-taste** | Dashboards, data tables, forms, wizards, settings, admin consoles. Budgets the frame in px first, then survives real data: overflow, long labels, empty/error/permission-denied states | \"Build the admin table for this\" |\n\n### Agents (Specialist Sessions)\n\nCOG uses a worker agent architecture inspired by [garrytan/gstack](https://github.com/garrytan/gstack) specialist sessions and [garrytan/gbrain](https://github.com/garrytan/gbrain) knowledge patterns. Workers handle data-heavy tasks cheaply (Sonnet) while the lead session does reasoning (Opus).\n\n| Agent | What it does | Model |\n|---|---|---|\n| **worker-data-collector** | Structured extraction from GitHub, Slack, Jira, Linear | Sonnet |\n| **worker-researcher** | Web research with source citations | Sonnet |\n| **worker-file-ops** | Vault file operations, metadata, profiles | Sonnet |\n| **worker-executor** | Pre-approved mutations (Jira, Linear, APIs) | Sonnet |\n| **worker-publisher** | Publishing to Slack, Confluence, Notion | Sonnet |\n| **brief-people-updater** | Batch-update people profiles from meetings/briefs | Sonnet |\n\n**Read-only verifiers** (they cannot edit files or mutate external state):\n\n| Agent | What it does | Checkpoint |\n|---|---|---|\n| **task-verifier** | Checks output against acceptance criteria by observing the artifact | CP-3v |\n| **integration-verifier** | Cross-task wiring and global acceptance | CP-4 |\n| **fix-agent** | Targeted fixes after a `FAIL:fixable` verdict; max 2 attempts | CP-3v retry |\n| **harvest-curator** | Shapes session learnings into adoption notes; propose-only | CP-7 |\n\n> Workers write results to `/tmp/` files and return only a status + path. The lead reads the file for synthesis. This eliminates slow token generation in agent output.\n>\n> Verifiers receive **paths only**, never a worker's output. Pasted context induces narrativisation: the verifier classifies the framing instead of independently reading the source.\n\n### People CRM (Knowledge-Based Team Profiles)\n\nTrack the people you work with using progressive, evidence-based profiles in `05-knowledge/people/`. Profiles auto-escalate via tiered enrichment:\n\n- **Tier 3 (Stub)** — 1 mention: name, role, one-line context\n- **Tier 2 (Moderate)** — 3+ mentions: executive snapshot, working style, strengths\n- **Tier 1 (Full)** — 8+ mentions or direct meeting: complete profile with all sections\n\nEvery observation includes a source citation with confidence level. See `05-knowledge/people/README.md` for details.\n\n### Role Packs (Personalized Recommendations)\n\nCOG matches your role during onboarding to a **role pack** that prioritizes the most relevant skills and integrations for you. Available role packs: Product Manager, Engineering Lead, Engineer, Designer, Founder, Marketer — or create your own from the template.\n\n> **New to team skills?** These require GitHub CLI (`gh`) and work best with Linear, Slack, and PostHog MCP integrations. They degrade gracefully — start with just GitHub and add integrations over time. See [SETUP.md](SETUP.md) for configuration.\n\n## The Evolution Cycle\n\n```mermaid\ngraph TD\n A[Daily: Braindump thoughts] --> B[Daily: News intelligence]\n A --> T[Daily: Team intelligence brief]\n M[Meetings: Process transcripts] --> T\n T -- syncs back to --> L[Linear / GitHub]\n B --> C[Weekly: Pattern analysis]\n T --> CA[Weekly: Comprehensive analysis]\n C --> D[Monthly: Knowledge consolidation]\n CA --> D\n D -- COG learns your patterns --> A\n R[Strategic: Auto-research] --> P[PM: Generate PRD]\n P --> S[PM: Create user stories]\n S -- after development --> RN[PM: Release notes]\n RN --> KB[PM: Update knowledge base]\n```\n\n- **Daily capture** — braindump raw thoughts; COG classifies by domain and extracts action items\n- **Daily intelligence** — personalized news briefings with verified, sourced news\n- **Daily team brief** — cross-reference GitHub, Linear, Slack, PostHog, meetings into one brief with two-way sync\n- **Meeting processing** — extract decisions, action items, and team dynamics from transcripts\n- **Weekly reflection** — pattern analysis across all domains surfaces insights you'd miss\n- **Weekly deep dive** — comprehensive analysis for board prep, retros, and strategic planning\n- **Monthly synthesis** — scattered notes become consolidated frameworks and a knowledge base\n- **Strategic research** — deep multi-agent investigation of strategic questions with real sources\n- **PM workflow** — full product lifecycle from PRD to release notes to knowledge base updates\n\n## Features at a Glance\n\n| | | |\n|---|---|---|\n| **Self-Evolving** — Learns your patterns, auto-organizes content, builds frameworks | **Self-Healing** — Rename files or restructure; cross-references update automatically | **Verification-First** — Sources required, 7-day freshness, confidence levels on all analysis |\n| **Privacy-First** — Local `.md` files, strict domain separation, no external servers | **Multi-Device** — iCloud sync to iPhone/iPad/Mac; Git for version history | **Obsidian Tasks** — `📅 YYYY-MM-DD` emoji format works with Tasks plugin dashboards |\n| **Garry Tan Inspired** — gstack specialist sessions + gbrain knowledge patterns | **Multi-Platform** — Listed on [skills.sh](https://skills.sh), [agentskill.sh](https://agentskill.sh), [cursor.directory](https://cursor.directory) | **Worker Agents** — Sonnet handles I/O, Opus handles thinking |\n| **Runtime Trust** — memory hygiene sweeps re-verify stored facts against the live environment | **Post-Condition Checks** — mutating skills observe the artifact before reporting success | **Skill Distillation** — [explore once, execute cheap](docs/SKILL-DISTILLATION.md) with small models |\n| **V-Model Closed Loop** — every criterion has a task on the left and an evidence row on the right | **Risk Lanes** — ceremony scales with blast radius | **Cross-Model Gate** — a different model family catches a different error class |\n\n## Your Vault\n\n```\nCOG-second-brain/\n├── .claude/skills/ # Claude Code skills (33)\n├── .claude/agents/ # Worker agent definitions (6)\n├── .claude/roles/ # Role packs (7) — personalized recommendations\n├── .agents/ # Antigravity (agy CLI + IDE) — pointer stubs to .claude/\n├── .kiro/powers/ # Kiro powers\n├── .gemini/commands/ # Gemini CLI commands\n├── AGENTS.md # Universal agent docs\n├── CLAUDE.md # Framework instructions\n├── 00-inbox/ # Profiles, interests, integrations\n├── 01-daily/ # Briefs & check-ins\n├── 02-personal/ # Personal braindumps (private)\n├── 03-professional/ # Professional braindumps & strategy\n├── 04-projects/ # Per-project tracking\n├── 05-knowledge/ # Consolidated insights & patterns\n│ └── people/ # People CRM profiles\n└── 06-templates/ # Document templates\n```\n\n> **Real-world results:** 120+ braindumps processed, daily briefs with 95%+ source accuracy, 5 major strategic insights discovered — zero maintenance required.\n\n## Keeping COG Updated\n\nCOG separates **framework files** (skills, docs, scripts) from **your content** (braindumps, profiles, notes). Updates never touch your personal data.\n\n| Method | Command |\n|---|---|\n| AI Agent (any) | \"Update COG\" or `/update-cog` |\n| Shell script | `./cog-update.sh` (interactive) • `--check` • `--dry-run` • `--force` |\n| Manual Git | `git fetch cog-upstream main` then checkout specific files |\n\nCheck your version: `cat COG-VERSION` \nValidate packaged surfaces: `./scripts/validate-agent-surface.sh`\n\n## FAQ\n\nWhy not just use Notion / Roam / Obsidian alone?
\n\nCOG adds self-evolving intelligence on top. It doesn't just store — it learns, analyzes, and synthesizes insights automatically.\nHow much does it cost?
\n\nCOG is free and open-source (MIT). You only pay for your AI agent's API usage.\nIs my data private?
\n\nYes. Everything is local markdown files. The AI agent's API is only called when you invoke a skill. No data stored on external servers.\nCan I customize or add skills?
\n\nYes — edit any `SKILL.md` / `POWER.md` / `AGENTS.md` file. See [SETUP.md](SETUP.md) for details on creating new skills.\nWill updating overwrite my customizations?
\n\nNo. The update process detects customized files and lets you choose per-file: keep yours, use upstream, or backup + update. Nothing is overwritten without approval.\nWhat if I don't use Git?
\n\nGit is optional but recommended for version history. COG works fine with just iCloud sync.\n