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.

Quick Start | Skills | Features | FAQ | SETUP.md

Works with Claude Code • Antigravity • Cursor • Kiro • Gemini CLI • OpenAI Codex • any AI that reads markdown

Inspired by Garry Tan's gstack and gbrain

graph LR
    A[You] -- natural language --> B[AI Agent]
    B -- runs --> C[33 Skills]
    C -- delegates to --> W[6 Workers]
    C -- verified by --> V[4 Read-Only Verifiers]
    C -- reads & writes --> D[.md Files]
    W -- reads & writes --> D
    V -- observes --> D
    C -- syncs with --> G[GitHub / Linear / Slack / PostHog]
    D --> E[Git]
    D --> F[iCloud]

New to COG? Watch the 2-minute walkthrough to see it in action.

1. Clone & enter the repo:

git clone https://github.com/huytieu/COG-second-brain.git
cd COG-second-brain

2. Run onboarding in your agent:

Or install via skills.sh:

npx skills add huytieu/COG-second-brain

Done — COG is personalized and ready in ~2 minutes. See SETUP.md for optional config (Git sync, iCloud, Obsidian Tasks, etc.).

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

Before 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 for the detailed support matrix and contributor rules.

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.

The enforcement layer that keeps every other skill honest. Work walks a V: decompose left into falsifiable criteria, build at the apex, verify right with evidence traced back to each criterion. Full lifecycle in WORKFLOW.md.

A paired set. taste-skill owns first-impression surfaces, product-ui-taste owns surfaces people use every day. Never run both on the same component.

COG uses a worker agent architecture inspired by garrytan/gstack specialist sessions and garrytan/gbrain knowledge patterns. Workers handle data-heavy tasks cheaply (Sonnet) while the lead session does reasoning (Opus).

Read-only verifiers (they cannot edit files or mutate external state):

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.

Verifiers receive paths only, never a worker's output. Pasted context induces narrativisation: the verifier classifies the framing instead of independently reading the source.

Track the people you work with using progressive, evidence-based profiles in 05-knowledge/people/. Profiles auto-escalate via tiered enrichment:

• Tier 3 (Stub) — 1 mention: name, role, one-line context
• Tier 2 (Moderate) — 3+ mentions: executive snapshot, working style, strengths
• Tier 1 (Full) — 8+ mentions or direct meeting: complete profile with all sections

Every observation includes a source citation with confidence level. See 05-knowledge/people/README.md for details.

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

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 for configuration.

graph TD
    A[Daily: Braindump thoughts] --> B[Daily: News intelligence]
    A --> T[Daily: Team intelligence brief]
    M[Meetings: Process transcripts] --> T
    T -- syncs back to --> L[Linear / GitHub]
    B --> C[Weekly: Pattern analysis]
    T --> CA[Weekly: Comprehensive analysis]
    C --> D[Monthly: Knowledge consolidation]
    CA --> D
    D -- COG learns your patterns --> A
    R[Strategic: Auto-research] --> P[PM: Generate PRD]
    P --> S[PM: Create user stories]
    S -- after development --> RN[PM: Release notes]
    RN --> KB[PM: Update knowledge base]

• Daily capture — braindump raw thoughts; COG classifies by domain and extracts action items
• Daily intelligence — personalized news briefings with verified, sourced news
• Daily team brief — cross-reference GitHub, Linear, Slack, PostHog, meetings into one brief with two-way sync
• Meeting processing — extract decisions, action items, and team dynamics from transcripts
• Weekly reflection — pattern analysis across all domains surfaces insights you'd miss
• Weekly deep dive — comprehensive analysis for board prep, retros, and strategic planning
• Monthly synthesis — scattered notes become consolidated frameworks and a knowledge base
• Strategic research — deep multi-agent investigation of strategic questions with real sources
• PM workflow — full product lifecycle from PRD to release notes to knowledge base updates

COG-second-brain/
├── .claude/skills/          # Claude Code skills (33)
├── .claude/agents/          # Worker agent definitions (6)
├── .claude/roles/           # Role packs (7) — personalized recommendations
├── .agents/                 # Antigravity (agy CLI + IDE) — pointer stubs to .claude/
├── .kiro/powers/            # Kiro powers
├── .gemini/commands/        # Gemini CLI commands
├── AGENTS.md                # Universal agent docs
├── CLAUDE.md                # Framework instructions
├── 00-inbox/                # Profiles, interests, integrations
├── 01-daily/                # Briefs & check-ins
├── 02-personal/             # Personal braindumps (private)
├── 03-professional/         # Professional braindumps & strategy
├── 04-projects/             # Per-project tracking
├── 05-knowledge/            # Consolidated insights & patterns
│   └── people/              # People CRM profiles
└── 06-templates/            # Document templates

Real-world results: 120+ braindumps processed, daily briefs with 95%+ source accuracy, 5 major strategic insights discovered — zero maintenance required.

COG separates framework files (skills, docs, scripts) from your content (braindumps, profiles, notes). Updates never touch your personal data.

Check your version: cat COG-VERSION
Validate packaged surfaces: ./scripts/validate-agent-surface.sh

• Gemini CLI + OpenAI Codex support (shipped in v3.1)
• Upstream update system (shipped in v3.2)
• Role packs & integration discovery (shipped in v3.3)
• PM workflow skills & auto-research (shipped in v3.4)
• Worker agents, people CRM & specialist sessions (shipped in v3.5)
• Loop engineering for iterative skills (shipped in v3.6)
• Runtime trust: memory hygiene, post-condition checks, verifier pass, content factory (shipped in v3.7)
• Web interface for knowledge graph visualization
• Mobile-first commands (optimized for Obsidian mobile)
• Team collaboration features (with privacy preservation)
• Integration with calendar/task management tools

Built with Claude Code, Cursor, Kiro, Gemini CLI, OpenAI Codex, and Obsidian.

Key inspirations:

• Garry Tan's gstack — specialist sessions, clear operating gears, repo-local skill distribution. COG's worker agent architecture and model routing borrow directly from gstack's explicit mode separation.
• Garry Tan's gbrain — Compiled Truth + Timeline pattern, tiered enrichment for people profiles, brain-first lookup protocol. COG's people CRM and knowledge-first approach are adapted from gbrain's design.
• Zettelkasten — atomic, interlinked notes as the foundation of knowledge
• Building a Second Brain (Tiago Forte) — PARA organization, progressive summarization
• GTD (David Allen) — capture everything, process systematically

TL;DR: Clone, run onboarding, braindump daily. COG evolves with you — just .md files, any AI agent, zero maintenance.