# huytieu/cog-second-brain architecture

> Architecture diagram of the GitHub repository huytieu/cog-second-brain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huytieu/cog-second-brain
- Repository: https://github.com/huytieu/cog-second-brain

## Overview

#### 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`

Main entry points: [`.claude/skills/onboarding/SKILL.md`](https://github.com/huytieu/cog-second-brain/blob/main/.claude/skills/onboarding/SKILL.md) (Claude skill playbooks), [`.claude/skills/braindump/SKILL.md`](https://github.com/huytieu/cog-second-brain/blob/main/.claude/skills/braindump/SKILL.md) (Capture & synthesis skills), [`skills/onboarding/SKILL.md`](https://github.com/huytieu/cog-second-brain/blob/main/skills/onboarding/SKILL.md) (Plugin-standard skills), [`.claude/skills/team-brief/SKILL.md`](https://github.com/huytieu/cog-second-brain/blob/main/.claude/skills/team-brief/SKILL.md) (Team & maintenance skills)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent surfaces"]
  node_entry["Primary agent guidance<br/>agent instructions<br/>[AGENTS.md]"]
  node_claude_roots["Client-specific roots<br/>client instructions<br/>[CLAUDE.md]"]
  node_claude_skills["Claude skill playbooks<br/>skill catalog<br/>[SKILL.md]"]
  node_plugin_skills["Plugin-standard skills<br/>portable skill catalog<br/>[SKILL.md]"]
  node_gemini_commands["Gemini commands<br/>native command surface<br/>[onboarding.toml]"]
  node_capture_skills["Capture &amp; synthesis skills<br/>workflow playbooks<br/>[SKILL.md]"]
  node_team_skills["Team &amp; maintenance skills<br/>workflow playbooks<br/>[SKILL.md]"]
end

subgraph group_workflow["Orchestration"]
  node_lead_agent(("Lead agent<br/>agent runtime"))
  node_workers["Focused workers<br/>delegated agents<br/>[worker-executor.md]"]
  node_tmp_results["Worker result files<br/>ephemeral artifacts"]
  node_verifiers["Independent verifiers<br/>verification agents<br/>[task-verifier.md]"]
  node_harvest["Harvest curator<br/>learning agent<br/>[harvest-curator.md]"]
end

subgraph group_vault["User vault"]
  node_inbox_daily["Inbox &amp; daily artifacts<br/>Markdown artifacts"]
  node_projects["Project artifacts<br/>Markdown artifacts"]
  node_knowledge["Durable knowledge<br/>Markdown knowledge base"]
  node_people_crm["People CRM<br/>evidence-based profiles<br/>[README.md]"]
end

subgraph group_distribution["Distribution &amp; integrity"]
  node_updater["Framework updater<br/>update script<br/>[cog-update.sh]"]
  node_validation["Surface validation<br/>integrity check"]
  node_plugin_manifest["Plugin manifest<br/>package manifest<br/>[plugin.json]"]
end

node_integrations{{"Optional integrations<br/>external services"}}

node_entry -->|"routes clients to"| node_claude_roots
node_claude_roots -->|"loads"| node_claude_skills
node_claude_skills -.->|"is distributed as"| node_plugin_skills
node_claude_skills -.->|"core subset exposed through"| node_gemini_commands
node_claude_skills -->|"includes"| node_capture_skills
node_claude_skills -->|"includes"| node_team_skills
node_capture_skills -->|"directs"| node_lead_agent
node_team_skills -->|"directs"| node_lead_agent
node_lead_agent -->|"delegates complex work"| node_workers
node_workers -->|"writes detailed results"| node_tmp_results
node_tmp_results -->|"reviewed by path"| node_verifiers
node_verifiers -->|"returns bounded fixes"| node_lead_agent
node_verifiers -.->|"completed work informs"| node_harvest
node_capture_skills -->|"captures and writes"| node_inbox_daily
node_capture_skills -->|"creates project artifacts"| node_projects
node_inbox_daily -->|"weekly analysis and consolidation"| node_knowledge
node_projects -->|"synthesized into"| node_knowledge
node_knowledge -->|"supplies evidence"| node_people_crm
node_team_skills -.->|"optionally calls"| node_integrations
node_updater -->|"updates framework content"| node_claude_skills
node_updater -->|"updates framework content"| node_plugin_skills
node_validation -.->|"checks surface parity"| node_claude_skills
node_validation -.->|"checks surface parity"| node_plugin_skills
node_plugin_manifest -->|"packages"| node_plugin_skills

click node_entry "https://github.com/huytieu/cog-second-brain/blob/main/AGENTS.md"
click node_claude_roots "https://github.com/huytieu/cog-second-brain/blob/main/CLAUDE.md"
click node_claude_skills "https://github.com/huytieu/cog-second-brain/blob/main/.claude/skills/onboarding/SKILL.md"
click node_plugin_skills "https://github.com/huytieu/cog-second-brain/blob/main/skills/onboarding/SKILL.md"
click node_gemini_commands "https://github.com/huytieu/cog-second-brain/blob/main/.gemini/commands/onboarding.toml"
click node_capture_skills "https://github.com/huytieu/cog-second-brain/blob/main/.claude/skills/braindump/SKILL.md"
click node_team_skills "https://github.com/huytieu/cog-second-brain/blob/main/.claude/skills/team-brief/SKILL.md"
click node_workers "https://github.com/huytieu/cog-second-brain/blob/main/.claude/agents/worker-executor.md"
click node_verifiers "https://github.com/huytieu/cog-second-brain/blob/main/.claude/agents/task-verifier.md"
click node_harvest "https://github.com/huytieu/cog-second-brain/blob/main/.claude/agents/harvest-curator.md"
click node_people_crm "https://github.com/huytieu/cog-second-brain/blob/main/05-knowledge/people/README.md"
click node_updater "https://github.com/huytieu/cog-second-brain/blob/main/cog-update.sh"
click node_validation "https://github.com/huytieu/cog-second-brain/blob/main/scripts/validate-agent-surface.sh"
click node_plugin_manifest "https://github.com/huytieu/cog-second-brain/blob/main/plugin.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_claude_roots,node_claude_skills,node_plugin_skills,node_gemini_commands,node_capture_skills,node_team_skills toneBlue
class node_lead_agent,node_workers,node_tmp_results,node_verifiers,node_harvest toneAmber
class node_inbox_daily,node_projects,node_knowledge,node_people_crm toneMint
class node_updater,node_validation,node_plugin_manifest toneRose
class node_integrations toneNeutral
```

## Components

### Agent surfaces

Instructions and playbooks consumed by AI clients.

- [Primary agent guidance](https://github.com/huytieu/cog-second-brain/blob/main/AGENTS.md): agent instructions · `AGENTS.md`
- [Client-specific roots](https://github.com/huytieu/cog-second-brain/blob/main/CLAUDE.md): client instructions · `CLAUDE.md`
- [Claude skill playbooks](https://github.com/huytieu/cog-second-brain/blob/main/.claude/skills/onboarding/SKILL.md): skill catalog · Authoritative operational implementation. · `.claude/skills/onboarding/SKILL.md`
- [Plugin-standard skills](https://github.com/huytieu/cog-second-brain/blob/main/skills/onboarding/SKILL.md): portable skill catalog · `skills/onboarding/SKILL.md`
- [Gemini commands](https://github.com/huytieu/cog-second-brain/blob/main/.gemini/commands/onboarding.toml): native command surface · Exposes a core skill subset. · `.gemini/commands/onboarding.toml`
- [Capture & synthesis skills](https://github.com/huytieu/cog-second-brain/blob/main/.claude/skills/braindump/SKILL.md): workflow playbooks · Classify, create, and synthesize vault artifacts. · `.claude/skills/braindump/SKILL.md`
- [Team & maintenance skills](https://github.com/huytieu/cog-second-brain/blob/main/.claude/skills/team-brief/SKILL.md): workflow playbooks · `.claude/skills/team-brief/SKILL.md`

### Orchestration

Delegation and independent verification for complex work.

- **Lead agent**: agent runtime · Supplies reasoning, tool use, and workflow coordination.
- [Focused workers](https://github.com/huytieu/cog-second-brain/blob/main/.claude/agents/worker-executor.md): delegated agents · Collect, execute approved mutations, and publish; return result paths. · `.claude/agents/worker-executor.md`
- **Worker result files**: ephemeral artifacts · Detailed worker outputs written for path-based review.
- [Independent verifiers](https://github.com/huytieu/cog-second-brain/blob/main/.claude/agents/task-verifier.md): verification agents · Inspect artifacts rather than worker narratives. · `.claude/agents/task-verifier.md`
- [Harvest curator](https://github.com/huytieu/cog-second-brain/blob/main/.claude/agents/harvest-curator.md): learning agent · Produces proposal-only learning from completed work. · `.claude/agents/harvest-curator.md`

### User vault

Plaintext Markdown state, separated from framework files.

- **Inbox & daily artifacts**: Markdown artifacts
- **Project artifacts**: Markdown artifacts
- **Durable knowledge**: Markdown knowledge base · Receives periodic consolidation.
- [People CRM](https://github.com/huytieu/cog-second-brain/blob/main/05-knowledge/people/README.md): evidence-based profiles · Profiles enrich only with cited evidence. · `05-knowledge/people/README.md`

### Distribution & integrity

Framework update, packaging, and surface-drift controls.

- [Framework updater](https://github.com/huytieu/cog-second-brain/blob/main/cog-update.sh): update script · Replaces framework content while preserving user vault data. · `cog-update.sh`
- [Surface validation](https://github.com/huytieu/cog-second-brain/blob/main/scripts/validate-agent-surface.sh): integrity check · Prevents drift across distributed agent surfaces. · `scripts/validate-agent-surface.sh`
- [Plugin manifest](https://github.com/huytieu/cog-second-brain/blob/main/plugin.json): package manifest · `plugin.json`

### Other components

- **Optional integrations**: external services · GitHub, Linear, Slack, Git, iCloud, and other optional sources degrade gracefully.

## Connections

- Primary agent guidance → Client-specific roots: routes clients to
- Client-specific roots → Claude skill playbooks: loads
- Claude skill playbooks → Plugin-standard skills: is distributed as
- Claude skill playbooks → Gemini commands: core subset exposed through
- Claude skill playbooks → Capture & synthesis skills: includes
- Claude skill playbooks → Team & maintenance skills: includes
- Capture & synthesis skills → Lead agent: directs
- Team & maintenance skills → Lead agent: directs
- Lead agent → Focused workers: delegates complex work
- Focused workers → Worker result files: writes detailed results
- Worker result files → Independent verifiers: reviewed by path
- Independent verifiers → Lead agent: returns bounded fixes
- Independent verifiers → Harvest curator: completed work informs
- Capture & synthesis skills → Inbox & daily artifacts: captures and writes
- Capture & synthesis skills → Project artifacts: creates project artifacts
- Inbox & daily artifacts → Durable knowledge: weekly analysis and consolidation
- Project artifacts → Durable knowledge: synthesized into
- Durable knowledge → People CRM: supplies evidence
- Team & maintenance skills → Optional integrations: optionally calls
- Framework updater → Claude skill playbooks: updates framework content
- Framework updater → Plugin-standard skills: updates framework content
- Surface validation → Claude skill playbooks: checks surface parity
- Surface validation → Plugin-standard skills: checks surface parity
- Plugin manifest → Plugin-standard skills: packages