huytieu/cog-second-brain

Purpose and Runtime Model

COG is a local-first, markdown-based “second brain” framework. AI coding/agent clients interpret skill playbooks, read and mutate a vault, and optionally call external integrations; Git and optional iCloud provide persistence/sync. There is no application server or database. Primary entry guidance is AGENTS.md, with client-specific roots in CLAUDE.md, GEMINI.md, and .cursorrules.

Agent-Surface Distribution

The authoritative full implementation is the Claude surface: skills and specialist-agent playbooks under .claude/skills/ and .claude/agents/. Equivalent plugin-standard skills are shipped under skills/; Antigravity has pointer stubs in .agents/; Kiro and Gemini expose a core subset via native command formats.

• .claude/skills/onboarding/SKILL.md

• skills/onboarding/SKILL.md

• .gemini/commands/onboarding.toml

Vault as the Data Boundary

User state is plaintext Markdown organized as a PARA-like vault. Skills classify incoming material, write daily/project/knowledge artifacts, and later synthesize those artifacts. Framework instructions and user content are intentionally separated so updates can replace framework files without overwriting personal data.

• 00-inbox/

• 01-daily/briefs/

• 02-personal/braindumps/

• 03-professional/braindumps/

• 04-projects/

• 05-knowledge/

Skill-Orchestrated Workflows

Skills are declarative operational entry points rather than executable application modules. They cover capture and synthesis (braindump, briefs, consolidation), team/product workflows, research, content production, and framework maintenance. The agent client supplies reasoning and tool execution; each playbook controls artifact locations, evidence expectations, and mutation rules.

• .claude/skills/braindump/SKILL.md

• .claude/skills/team-brief/SKILL.md

• .claude/skills/knowledge-consolidation/SKILL.md

• .claude/skills/update-cog/SKILL.md

Worker and Verification Pipeline

Complex work is delegated from a lead agent to focused workers. Workers perform I/O-heavy collection, research, file operations, approved external mutations, or publishing, writing detailed results to /tmp and returning a path. Independent verifiers inspect artifacts by path rather than worker narratives; fixes are bounded and harvested learning is proposal-only. This establishes a V-model: criteria/planning → build → component verification → integration/acceptance.

• .claude/agents/worker-data-collector.md

• .claude/agents/worker-executor.md

• .claude/agents/task-verifier.md

• .claude/agents/integration-verifier.md

• .claude/agents/harvest-curator.md

Knowledge Evolution and CRM

Capture and intelligence artifacts feed weekly analysis and periodic consolidation into durable knowledge. The people CRM is a specialized knowledge subsystem: profiles progressively enrich based on evidence and citations, rather than treating observations as unqualified facts.

• .claude/skills/weekly-checkin/SKILL.md

• .claude/skills/memory-hygiene/SKILL.md

• 05-knowledge/consolidated/

• 05-knowledge/people/README.md

• 06-templates/people-profile-template.md

External Boundaries, Updates, and Integrity

Optional integrations include GitHub, Linear, Slack, PostHog, Jira, Confluence, Notion, museum open-data APIs, Git, and iCloud; skills should degrade when integrations are absent. cog-update.sh updates framework content while preserving vault data. Packaging manifests expose the plugin, while validation prevents drift across distribution surfaces.

• cog-update.sh

• scripts/validate-agent-surface.sh

• plugin.json

• .claude-plugin/plugin.json

• docs/AGENT-SUPPORT.md