Skip to content

Self-evolving second brain with 35 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.

Add worker agents, people CRM, and specialist sessions (v3.5.0)

Huy Tieu3777622e9595
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index bdd2f49..4fb74ab 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "cog-second-brain",
- "version": "3.4.0",
- "description": "A self-evolving second brain system using Claude Code, Obsidian markdown files, and Git version control. Features specialized AI agents for knowledge management, daily intelligence briefings, and strategic insights extraction.",
+ "version": "3.5.0",
+ "description": "A self-evolving second brain built on Obsidian markdown, Git, and multi-agent skill surfaces for Claude Code, Kiro, Gemini CLI, Codex, and other markdown-reading assistants.",
"author": {
"name": "Huy Tieu",
"url": "https://github.com/huytieu"
@@ -64,6 +64,21 @@
"path": ".claude/skills/url-dump/SKILL.md",
"description": "Quick capture URLs with automatic content extraction, insights, and categorization into knowledge booklets"
},
+ {
+ "name": "team-brief",
+ "path": ".claude/skills/team-brief/SKILL.md",
+ "description": "Cross-reference GitHub, Linear, Slack, PostHog, meetings, and braindumps into a daily team intelligence brief with Linear sync-back"
+ },
+ {
+ "name": "meeting-transcript",
+ "path": ".claude/skills/meeting-transcript/SKILL.md",
+ "description": "Process meeting recordings into structured decisions, action items, and team dynamics"
+ },
+ {
+ "name": "comprehensive-analysis",
+ "path": ".claude/skills/comprehensive-analysis/SKILL.md",
+ "description": "Deep 7-day analysis for weekly reviews, board prep, or strategic planning"
+ },
{
"name": "update-cog",
"path": ".claude/skills/update-cog/SKILL.md",
@@ -107,7 +122,7 @@
],
"metadata": {
"pluginRoot": ".",
- "architecture": "claude-agent-skills",
+ "architecture": "multi-agent-skill-pack",
"features": [
"Self-evolving intelligence with pattern recognition",
"Self-healing system with auto-updating cross-references",
@@ -116,21 +131,32 @@
"Plain text markdown files (no database, no vendor lock-in)",
"Multi-device sync via iCloud (iPhone, iPad, Mac)",
"Git version control for tracking thinking evolution",
- "Progressive disclosure for efficient context usage"
+ "Agent-surface validator for manifest/docs consistency",
+ "Worker agent architecture with model routing (Sonnet workers, Opus lead)",
+ "People CRM with tiered enrichment and evidence-based profiles"
],
"requirements": {
"obsidian": "Recommended for markdown file management",
- "git": "Optional but recommended for version control",
- "claudeCode": "Required for AI agent functionality"
+ "git": "Optional but recommended for version control and safe updates",
+ "claudeCode": "Recommended for the full 17-skill native experience",
+ "kiro": "Optional - ships 7 native core powers",
+ "geminiCli": "Optional - ships 7 native core commands",
+ "agentsMd": "Universal fallback surface for Codex and other markdown-reading agents"
},
"installation": {
- "quickStart": "Clone repo into Obsidian vault, copy .claude directory, run /onboarding",
- "setupTime": "3-5 minutes",
- "onboardingTime": "2 minutes"
+ "quickStart": "Clone the repo, cd into COG-second-brain, then run onboarding in your agent of choice",
+ "setupTime": "2-5 minutes",
+ "onboardingTime": "2 minutes",
+ "validation": "Run ./scripts/validate-agent-surface.sh before publishing or after framework updates"
},
"directoryStructure": {
- ".claude/skills": "10 specialized agent skills",
+ ".claude/skills": "17 Claude Code skills (full surface)",
+ ".claude/agents": "6 worker agent definitions for specialist sessions",
".claude/roles": "7 role packs for personalized skill and integration recommendations",
+ ".kiro/powers": "7 Kiro powers (core workflows)",
+ ".gemini/commands": "7 Gemini CLI commands (core workflows)",
+ ".gemini/skills": "Detailed Gemini command playbooks",
+ "AGENTS.md": "Universal command surface for Codex and other agents",
"00-inbox": "Temporary processing area with profile and interests files",
"01-daily": "Daily briefs and check-ins",
"02-personal": "Personal domain (strict privacy)",
@@ -141,10 +167,17 @@
"skillArchitecture": {
"type": "agent-skills",
"skills": 17,
+ "workerAgents": 6,
"rolePacks": 7,
"invocation": "model-invoked",
"progressiveDisclosure": true,
- "description": "Self-contained skills that combine orchestration and specialized processing using Claude's progressive disclosure pattern"
+ "nativeSurfaces": {
+ "claudeCode": 17,
+ "kiro": 7,
+ "geminiCli": 7,
+ "agentsMd": 17
+ },
+ "description": "Self-contained skills with worker agent delegation, full Claude Code surface, core native Kiro/Gemini surfaces, and AGENTS.md as the universal fallback"
}
}
}
diff --git a/.claude/agents/brief-people-updater.md b/.claude/agents/brief-people-updater.md
new file mode 100644
index 0000000..b5e48e5
--- /dev/null
+++ b/.claude/agents/brief-people-updater.md
@@ -0,0 +1,34 @@
+---
+name: brief-people-updater
+description: Update people profiles in 05-knowledge/people/ with new information from brief data, meetings, or Slack
+model: sonnet
+---
+
+You are a people profile updater. You receive a list of new observations about team members and update their profiles.
+
+## Instructions
+1. For each person in the provided list, check if `05-knowledge/people/<firstname-lastname>.md` exists
+2. If exists: read the file, append new observations under the appropriate section in the Timeline
+3. If not exists: create a new profile using the template in `06-templates/people-profile-template.md`
+4. Never overwrite existing content — only append or update specific fields
+
+## What to update
+- Role/team changes
+- Working style observations from meetings
+- Collaboration dynamics (who works well with whom)
+- Technical strengths observed from PRs or discussions
+- Communication patterns from Slack
+- Decisions they made or influenced
+
+## What NOT to include
+- Personal/private information
+- Negative judgments or gossip
+- Speculation about motivations
+- Anything you wouldn't share with the person themselves
+
+## Citation format
+Every observation must include a source citation:
+`[Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: high|medium|low]`
+
+## Output
+Report back: which profiles were created/updated, with a count of new observations added.
diff --git a/.claude/agents/worker-data-collector.md b/.claude/agents/worker-data-collector.md
new file mode 100644
index 0000000..64f9ad0
--- /dev/null
+++ b/.claude/agents/worker-data-collector.md
@@ -0,0 +1,26 @@
+---
+name: worker-data-collector
+description: Collect data from GitHub, Slack, Jira, Linear, or file system. Structured extraction only — no synthesis.
+model: sonnet
+---
+
+You are a data collector. Your job is fast, accurate, structured extraction. Never synthesize or editorialize — just return clean data.
+
+## Capabilities
+- **GitHub**: Run `gh` CLI commands (PR lists, issue lists, commit history)
+- **Slack**: Use Slack MCP tools to read channels and threads (load via ToolSearch)
+- **Jira**: Use Atlassian MCP tools for JQL queries and issue details (load via ToolSearch)
+- **Linear**: Use Linear MCP tools for issues, initiatives, projects (load via ToolSearch)
+- **Files**: Read vault files via Glob + Read, extract structured data
+
+## Output Rule
+- **Always write results to a file** at `/tmp/{task-slug}.md` using the Write tool
+- Return ONLY a short status + file path, e.g.: `"OK: /tmp/slack-data.md (47 messages, 12 threads)"`
+- Never return large text as your output — generating thousands of tokens is extremely slow
+- The orchestrator will read your file via the Read tool
+
+## Rules
+- Always load MCP tools via ToolSearch before calling them
+- If a query fails, report the error and continue with others
+- Never fabricate data
+- Structure your output file with clear markdown sections
diff --git a/.claude/agents/worker-executor.md b/.claude/agents/worker-executor.md
new file mode 100644
index 0000000..6805b20
--- /dev/null
+++ b/.claude/agents/worker-executor.md
@@ -0,0 +1,25 @@
+---
+name: worker-executor
+description: Execute pre-approved mutations — Jira transitions, Linear updates, API calls, build commands.
+model: sonnet
+---
+
+You are an execution worker. You receive a list of pre-approved actions and execute them. You do NOT decide what to do — the lead already decided.
+
+## Capabilities
+- **Jira**: Transition issues, add comments, link PRs (via Atlassian MCP)
+- **Linear**: Update issues, post status updates, create attachments (via Linear MCP)
+- **GitHub**: Create issues, add comments (via `gh` CLI)
+- **API calls**: Execute curl commands for webhooks, APIs
+
+## Output Rule
+- If results are large (API responses > 2K tokens), **write to `/tmp/{task-slug}.md`** and return only a short status + file path
+- For small results (success/failure confirmations), return inline
+- Never generate thousands of tokens as output text — it's extremely slow
+
+## Rules
+- Execute exactly what's specified — no improvisation
+- Report back: what succeeded, what failed (with error details)
+- If an action fails, continue with remaining actions
+- Never make destructive changes unless explicitly listed
+- Load MCP tools via ToolSearch before using them
diff --git a/.claude/agents/worker-file-ops.md b/.claude/agents/worker-file-ops.md
new file mode 100644
index 0000000..c707651
--- /dev/null
+++ b/.claude/agents/worker-file-ops.md
@@ -0,0 +1,26 @@
+---
+name: worker-file-ops
+description: Read, write, and organize vault files. Metadata updates, file moves, profile updates.
+model: sonnet
+---
+
+You are a file operations worker. Read, write, organize, and maintain vault files with correct formatting.
+
+## Capabilities
+- Read and parse markdown files with YAML frontmatter
+- Write new files with proper vault conventions
+- Update YAML frontmatter fields
+- Move/organize files between vault directories
+- Update people profiles in `05-knowledge/people/`
+
+## Output Rule
+- If returning extracted data or read results > 2K tokens, **write to `/tmp/{task-slug}.md`** and return only the file path
+- For confirmations of writes/moves, return inline
+
+## Rules
+- Preserve existing frontmatter when updating files
+- Use proper Obsidian linking format: `[[path/to/file|Display Name]]`
+- Date format: YYYY-MM-DD
+- Never overwrite files without reading them first
+- When updating profiles, append — don't overwrite existing content
+- Follow domain classification: 01-daily, 02-personal, 03-professional, 04-projects, 05-knowledge
diff --git a/.claude/agents/worker-publisher.md b/.claude/agents/worker-publisher.md
new file mode 100644
index 0000000..e37e48f
--- /dev/null
+++ b/.claude/agents/worker-publisher.md
@@ -0,0 +1,37 @@
+---
+name: worker-publisher
+description: Execute publishing operations — Slack, Confluence, Notion, webhooks. Receives final content and posts it.
+model: sonnet
+---
+
+You are a publishing executor. You receive final, approved content and publish it to the specified platform.
+
+## Platforms
+
+### Slack
+1. Load Slack MCP tools via ToolSearch
+2. Post message to specified channel(s)
+3. Return confirmation
+
+### Confluence
+1. Load Atlassian MCP tools via ToolSearch
+2. Create or update page via `mcp__claude_ai_Atlassian__createConfluencePage` or `mcp__claude_ai_Atlassian__updateConfluencePage`
+3. Return page URL
+
+### Notion
+1. Load Notion MCP tools via ToolSearch
+2. Create or update page
+3. Return page URL
+
+### Webhooks
+1. POST to provided webhook URL with JSON payload via curl
+2. Return response status
+
+## Output Rule
+- Publisher output is typically short (URLs, confirmations) — return inline
+- If publishing multiple items, write a summary to `/tmp/{publish-task}.md` and return the path
+
+## Rules
+- Never modify content — publish exactly what's given
+- Report success/failure for each platform
+- If one platform fails, continue with others
diff --git a/.claude/agents/worker-researcher.md b/.claude/agents/worker-researcher.md
new file mode 100644
index 0000000..aad2a42
--- /dev/null
+++ b/.claude/agents/worker-researcher.md
@@ -0,0 +1,25 @@
+---
+name: worker-researcher
+description: Web research agent. Searches, fetches URLs, extracts facts and evidence. No synthesis — just structured findings.
+model: sonnet
+---
+
+You are a research data gatherer. Search the web, fetch pages, and extract relevant facts. Return structured evidence — the lead will synthesize.
+
+## Capabilities
+- **WebSearch**: Find relevant sources for any topic
+- **WebFetch**: Read specific URLs and extract content
+- **File reads**: Check existing vault knowledge for context before searching
+
+## Output Rule
+- **Always write findings to a file** at `/tmp/{research-topic}.md` using the Write tool
+- Return ONLY a short status + file path, e.g.: `"OK: /tmp/research-competitor-analysis.md (5 sources, 23 findings)"`
+- Never return large research text as your output — the orchestrator will read the file
+
+## Rules
+- Always cite sources with URLs
+- Distinguish facts from opinions
+- Flag conflicting information across sources
+- If a search returns nothing useful, say so — don't pad
+- Extract specific data points, quotes, and evidence
+- Note publication dates for recency assessment
diff --git a/.github/MARKETPLACE.md b/.github/MARKETPLACE.md
index 6448ebf..aa9afb0 100644
--- a/.github/MARKETPLACE.md
+++ b/.github/MARKETPLACE.md
@@ -1,162 +1,81 @@
-# Publishing COG to Claude Code Plugin Marketplaces
-
-This guide explains how to publish COG to Claude Code plugin marketplaces.
-
-## What's Included
-
-COG is now marketplace-compatible with the following files:
-
-- **`plugin.json`** - Complete plugin manifest with all commands, agents, and metadata
-- **`marketplace-entry.json`** - Example marketplace entry for marketplace maintainers
-
-## Plugin Manifest (`plugin.json`)
-
-The `plugin.json` file contains:
-
-### Required Fields
-- `name`: "cog-second-brain" (plugin identifier)
-- `version`: "1.0.0" (semantic versioning)
-- `description`: Full description of COG's capabilities
-
-### Metadata
-- `author`: Author information with GitHub URL
-- `homepage`: GitHub repository URL
-- `repository`: Git repository details
-- `license`: "MIT"
-- `keywords`: Search keywords for discoverability
-- `category`: "productivity"
-- `tags`: Additional categorization tags
-
-### Components
-
-#### Skills (6 total)
-1. `onboarding` - Personalization workflow
-2. `daily-brief` - News intelligence
-3. `braindump` - Thought capture
-4. `weekly-checkin` - Pattern analysis
-5. `knowledge-consolidation` - Framework building
-6. `url-dump` - Quick URL capture with auto-extraction
-
-### Extended Metadata
-- `features`: List of key COG features
-- `requirements`: Prerequisites (Obsidian, Git, Claude Code)
-- `installation`: Quick start guide
-- `directoryStructure`: Vault organization
-
-## Marketplace Entry (`marketplace-entry.json`)
-
-This is what marketplace maintainers would add to their marketplace catalog:
-
-```json
-{
- "name": "cog-second-brain",
- "source": "https://github.com/huytieu/COG-second-brain",
- "owner": {
- "name": "Huy Tieu",
- "email": "[email protected]",
- "url": "https://github.com/huytieu"
- },
- "description": "Self-evolving second brain with AI agents for knowledge management",
- "version": "1.0.0"
-}
-```
-
-## How to Publish
+# Publishing COG to Claude Code Marketplaces
-### Option 1: Submit to Official Claude Code Marketplace
+This guide covers the packaging metadata and release checks for publishing COG.
-1. Wait for Anthropic to launch the official Claude Code plugin marketplace
-2. Follow their submission process (to be announced)
-3. Provide the GitHub repository URL: `https://github.com/huytieu/COG-second-brain`
+## Packaged Metadata
-### Option 2: Third-Party Marketplace
+COG ships marketplace metadata in two files:
-If a third-party marketplace exists:
+- **`.claude-plugin/plugin.json`** — canonical manifest for the packaged Claude Code surface
+- **`marketplace-entry.json`** — lightweight catalog entry for marketplace maintainers
-1. **Fork or contact the marketplace repository**
-2. **Add the marketplace entry** to their catalog file
-3. **Submit a pull request** with:
- - Your `marketplace-entry.json` content
- - Link to your repository
- - Verification that `plugin.json` exists and is valid
+Current packaged version: **3.4.1**
-### Option 3: Self-Hosted Marketplace
+## Surface Model
-Create your own marketplace JSON file:
+COG is a **multi-agent package**, not a single-surface plugin:
-```json
-{
- "marketplaces": [
- {
- "name": "cog-second-brain",
- "source": "https://github.com/huytieu/COG-second-brain",
- "owner": {
- "name": "Huy Tieu",
- "email": "[email protected]",
- "url": "https://github.com/huytieu"
- },
- "version": "1.0.0"
- }
- ]
-}
-```
+| Surface | Coverage |
+|---|---:|
+| Claude Code (`.claude/skills/`) | 17 native skills |
+| Universal docs (`AGENTS.md`) | 17 documented commands |
+| Kiro (`.kiro/powers/`) | 7 core powers |
+| Gemini CLI (`.gemini/commands/`) | 7 core commands |
-Host this file publicly and users can add your marketplace URL to their Claude Code settings.
+For the detailed contract, see [`docs/AGENT-SUPPORT.md`](../docs/AGENT-SUPPORT.md).
-## Validation
+## Before You Publish
-To validate your plugin manifest:
+Run the packaging validator from the repo root:
```bash
-# Check JSON syntax
-cat .claude-plugin/plugin.json | python3 -m json.tool > /dev/null && echo "✓ JSON is valid"
-
-# Verify all skill files exist
-ls .claude/skills/onboarding/SKILL.md
-ls .claude/skills/daily-brief/SKILL.md
-ls .claude/skills/braindump/SKILL.md
-ls .claude/skills/weekly-checkin/SKILL.md
-ls .claude/skills/knowledge-consolidation/SKILL.md
-ls .claude/skills/url-dump/SKILL.md
+./scripts/validate-agent-surface.sh
```
-All paths should exist relative to the repository root.
+This catches the most common release mistakes:
+- invalid JSON in manifests
+- skill paths listed in the manifest but missing on disk
+- plugin skill counts drifting from `.claude/skills/`
+- `AGENTS.md` missing commands that the manifest claims to ship
+- wrong `AGENTS.md` filename casing in packaging docs
+- version mismatches across `COG-VERSION`, `plugin.json`, and `marketplace-entry.json`
-## Installation for Users
+## Manual Validation Commands
-Once published to a marketplace, users can install COG:
+If you want extra spot checks:
-### Via Marketplace (Future)
-1. Open Claude Code in their Obsidian vault
-2. Open plugin marketplace interface
-3. Search for "cog-second-brain"
-4. Click install
-5. Run `/onboarding` to personalize
-
-### Via Manual Installation (Current)
```bash
-cd /path/to/your/obsidian-vault
-git clone https://github.com/huytieu/COG-second-brain.git
-cp -r COG-second-brain/.claude .
-cp COG-second-brain/plugin.json .
+python3 -m json.tool .claude-plugin/plugin.json > /dev/null
+python3 -m json.tool marketplace-entry.json > /dev/null
+find .claude/skills -name SKILL.md | wc -l
+find .kiro/powers -name POWER.md | wc -l
+find .gemini/commands -type f | wc -l
```
-## Versioning
+## Installation Guidance for Marketplace Descriptions
-COG follows semantic versioning:
+Preferred install flow:
-- **Major** (1.0.0): Breaking changes (architecture overhaul)
-- **Minor** (1.1.0): New features (new commands/agents)
-- **Patch** (1.0.1): Bug fixes, documentation
+```bash
+git clone https://github.com/huytieu/COG-second-brain.git
+cd COG-second-brain
+# Open in Claude Code, Kiro, Gemini CLI, Codex, or another AGENTS-compatible agent
+```
-Update both `plugin.json` and `marketplace-entry.json` when releasing new versions.
+Do **not** describe installation as copying only `.claude/` into another folder — COG is a full vault/repo layout, not just a loose skill pack.
-## Support and Issues
+## Release Checklist
-- Report bugs: https://github.com/huytieu/COG-second-brain/issues
-- Discussions: https://github.com/huytieu/COG-second-brain/discussions
-- Documentation: https://github.com/huytieu/COG-second-brain/wiki
+1. Bump `COG-VERSION`
+2. Update `.claude-plugin/plugin.json`
+3. Update `marketplace-entry.json`
+4. Update `CHANGELOG.md`
+5. Add any new framework files to `FRAMEWORK_FILES` in `cog-update.sh`
+6. Run `./scripts/validate-agent-surface.sh`
+7. Smoke test onboarding from a clean clone
-## License
+## Support Links
-COG is licensed under MIT - free for personal and commercial use.
+- Issues: https://github.com/huytieu/COG-second-brain/issues
+- Discussions: https://github.com/huytieu/COG-second-brain/discussions
+- Setup guide: https://github.com/huytieu/COG-second-brain/blob/main/SETUP.md
diff --git a/05-knowledge/people/README.md b/05-knowledge/people/README.md
new file mode 100644
index 0000000..472ac30
--- /dev/null
+++ b/05-knowledge/people/README.md
@@ -0,0 +1,77 @@
+# People CRM — Knowledge Base
+
+This directory contains structured profiles for people you work with. Each profile tracks observations, working patterns, and collaboration notes — built progressively from meetings, Slack, PRs, and daily interactions.
+
+## Design Principles
+
+- **Neutral & Professional** — content you'd share with the person themselves
+- **Observation-based** — only what's evidenced by actual work, messages, contributions
+- **Progressive** — don't fill everything at once; details emerge naturally over time
+- **No gossip or judgment** — focus on working patterns and collaboration effectiveness
+- **Append-only timeline** — history is never rewritten, only added to
+
+## File Naming
+
+`<firstname>-<lastname>.md` (lowercase, hyphenated)
+
+Examples: `jane-doe.md`, `vu-lam.md`, `alex-martins.md`
+
+## Profile Structure
+
+Each profile has two layers:
+
+### 1. Compiled Truth (Current State)
+The top section reflects the current best understanding. Updated when new evidence changes the picture.
+
+- **Executive Snapshot** — 2-3 high-confidence bullet points
+- **Role & Responsibilities** — what they own/scope
+- **Working Style** — communication and collaboration patterns
+- **Strengths** — observed strengths tied to evidence
+- **Collaboration Notes** — how to work effectively with this person
+- **Open Threads** — unresolved questions or uncertain claims
+
+### 2. Timeline (Append-Only History)
+Reverse-chronological dated entries. Never deleted, only appended.
+
+Each entry includes:
+- What happened or was observed
+- Source citation: `[Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: high|medium|low]`
+
+## Tiered Enrichment
+
+Profiles auto-escalate based on interaction density (inspired by [garrytan/gbrain](https://github.com/garrytan/gbrain)):
+
+| Tier | Trigger | What gets created |
+|------|---------|-------------------|
+| **Tier 3 — Stub** | 1 mention in a meeting or brief | Name, role, one-line context |
+| **Tier 2 — Moderate** | 3+ cross-source mentions | Executive snapshot, working style, strengths |
+| **Tier 1 — Full** | Direct meeting or 8+ mentions | Complete profile with all sections filled |
+
+Don't force a full profile on first encounter. Let it build naturally.
+
+## Creating New Profiles
+
+Use the template at `06-templates/people-profile-template.md` or run the `brief-people-updater` agent.
+
+## Automated Updates
+
+The `brief-people-updater` agent (`.claude/agents/brief-people-updater.md`) can batch-update profiles from:
+- Meeting transcripts
+- Team brief data
+- Slack observations
+- PR activity
+
+It follows the same rules: append-only, evidence-based, no judgments.
+
+## Citation Format
+
+Every factual claim must include a source:
+
+```
+[Source: [[04-projects/true-platform/meetings/2026-04-01-standup]] | 2026-04-01 | confidence: high]
+```
+
+Confidence levels:
+- **high** — direct observation, explicit statement, or official announcement
+- **medium** — inferred from patterns across multiple interactions
+- **low** — single data point or secondhand information
diff --git a/06-templates/people-profile-template.md b/06-templates/people-profile-template.md
new file mode 100644
index 0000000..d17f886
--- /dev/null
+++ b/06-templates/people-profile-template.md
@@ -0,0 +1,41 @@
+---
+type: reference
+domain: shared
+updated: "YYYY-MM-DD"
+tags:
+ - people
+ - crm
+---
+
+# {{full-name}}
+
+## Compiled Truth
+
+### Executive Snapshot
+- [Current high-confidence summary point] [Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: high]
+- [Current high-confidence summary point] [Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: high]
+
+### Role & Responsibilities
+- [What they currently own/scope] [Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: high]
+
+### Working Style
+- [Communication and collaboration patterns] [Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: medium]
+
+### Strengths
+- [Observed strengths tied to evidence] [Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: medium]
+
+### Collaboration Notes
+- [How to work effectively with this person] [Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: medium]
+
+### Open Threads
+- [Unresolved question / uncertain claim] [Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: low]
+
+---
+
+## Timeline (Append-Only)
+
+### YYYY-MM-DD
+- [What happened, concise factual update] [Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: high]
+
+### YYYY-MM-DD
+- [What changed / what was observed] [Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: medium]
diff --git a/AGENTS.md b/AGENTS.md
index 5b39be5..56756b7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -210,6 +210,76 @@ This document defines the available commands/skills for AI agents interacting wi
---
+### /team-brief
+
+**Description:** Generate a daily team intelligence brief by cross-referencing Linear, Slack, GitHub, PostHog, meetings, and braindumps — then sync the resulting intelligence back into Linear.
+
+**Triggers:**
+- `/team-brief`
+- "team brief"
+- "what did we ship?"
+- "daily team update"
+- "summarize the team's progress"
+
+**Purpose:** Build an evidence-backed operating brief for product and engineering leads by combining multiple sources of truth, highlighting blockers and momentum, and writing the most important updates back to Linear.
+
+**What it does:**
+1. Pulls active initiatives, projects, and issues from Linear
+2. Cross-references GitHub PRs, Slack discussions, meetings, PostHog, and braindumps
+3. Summarizes shipped work, in-progress work, risks, and signals that matter
+4. Writes initiative status updates and issue/project sync-backs into Linear where appropriate
+5. Produces a concise brief with a Linear sync report
+
+**Output location:** `03-professional/team-briefs/team-brief-YYYY-MM-DD.md`
+
+---
+
+### /meeting-transcript
+
+**Description:** Process meeting transcripts into structured decisions, action items, and strategic themes.
+
+**Triggers:**
+- `/meeting-transcript`
+- "process this meeting"
+- "analyze this transcript"
+- "summarize this meeting"
+- "meeting notes from transcript"
+
+**Purpose:** Turn noisy transcripts into clean decision records, action items, and key strategic signals without losing the substance of the conversation.
+
+**What it does:**
+1. Cleans transcript noise and identifies speakers/topics
+2. Extracts decisions, action items, unresolved questions, and strategic themes
+3. Highlights stakeholder concerns, alignment, and follow-up needs
+4. Formats the result into a reusable meeting note
+
+**Output location:** `03-professional/meetings/meeting-transcript-YYYY-MM-DD-[slug].md`
+
+---
+
+### /comprehensive-analysis
+
+**Description:** Run a deep 7-day product, team, and strategy analysis for weekly reviews, board prep, or planning.
+
+**Triggers:**
+- `/comprehensive-analysis`
+- "weekly analysis"
+- "board prep"
+- "comprehensive analysis"
+- "deep weekly review"
+
+**Purpose:** Synthesize the last week across product, engineering, customer signals, and strategy into a single high-signal analysis for leaders.
+
+**What it does:**
+1. Reviews recent team briefs, meetings, project artifacts, and external signals
+2. Identifies what shipped, what changed, what is blocked, and what needs leadership attention
+3. Surfaces trends, risks, opportunities, and recommended actions
+4. Produces an executive-ready synthesis with confidence levels and open questions
+
+**Output location:** `03-professional/analysis/comprehensive-analysis-YYYY-MM-DD.md`
+
+---
+
### /update-cog
**Description:** Check for and apply upstream COG framework updates without touching personal content.
@@ -420,10 +490,48 @@ The following 6 skills form a complete product management lifecycle:
---
+## Worker Agents
+
+COG includes 6 specialized worker agents (`.claude/agents/`) that handle data-heavy tasks using Sonnet while the lead session (Opus) handles reasoning and synthesis. Inspired by [garrytan/gstack](https://github.com/garrytan/gstack) specialist sessions and [garrytan/gbrain](https://github.com/garrytan/gbrain) knowledge patterns.
+
+| Agent | What it does | When it's used |
+|---|---|---|
+| **worker-data-collector** | Structured extraction from GitHub, Slack, Jira, Linear, or files | Team briefs, issue audits, data gathering |
+| **worker-researcher** | Web research with source citations and evidence | Auto-research threads, daily brief sourcing |
+| **worker-file-ops** | Vault reads/writes, metadata, profile updates | Knowledge consolidation, profile maintenance |
+| **worker-executor** | Pre-approved mutations (Jira transitions, Linear updates) | Team brief sync-back, issue management |
+| **worker-publisher** | Publishing to Slack, Confluence, Notion, webhooks | Brief publishing, wiki sync |
+| **brief-people-updater** | Batch-update people profiles from meetings/briefs | After team briefs, meeting processing |
+
+**Key rule:** Workers write results to `/tmp/{task-slug}.md` and return only a short status + file path. The lead session reads the file for synthesis.
+
+---
+
+## People CRM
+
+COG tracks the people you work with using progressive, evidence-based profiles stored in `05-knowledge/people/`.
+
+**Profile structure:** Each person has a two-layer file:
+1. **Compiled Truth** (top) — current best understanding, updated as evidence changes
+2. **Timeline** (bottom) — append-only dated entries with source citations
+
+**Tiered enrichment** — profiles auto-escalate:
+- **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
+
+**Citation format:** Every observation must include:
+`[Source: [[path/to/source-note]] | YYYY-MM-DD | confidence: high|medium|low]`
+
+Create profiles manually using the template at `06-templates/people-profile-template.md` or run the `brief-people-updater` agent for batch updates.
+
+---
+
## Vault Structure
```
COG-second-brain/
+├── .claude/agents/ # Worker agent definitions (6)
├── .claude/roles/ # Role packs for personalized recommendations
├── 00-inbox/ # Landing zone, profile files
│ ├── MY-PROFILE.md # User profile with role pack (created by onboarding)
@@ -446,9 +554,10 @@ COG-second-brain/
├── 05-knowledge/ # Consolidated knowledge
│ ├── consolidated/ # Frameworks and reports
│ ├── patterns/ # Identified patterns
+│ ├── people/ # People CRM profiles
│ ├── timeline/ # Thinking evolution
│ └── booklets/ # URL bookmarks by category
-└── 06-templates/ # Document templates
+└── 06-templates/ # Document templates (incl. people profile)
```
---
@@ -489,9 +598,10 @@ Available packs: Product Manager, Engineering Lead, Engineer, Designer, Founder,
## Version & Updates
-COG tracks its version in `COG-VERSION` (currently 3.3.0). To check for updates:
+COG tracks its version in `COG-VERSION` (currently 3.5.0). To check for updates:
- Run `/update-cog` in any supported agent
- Or use the shell script: `./cog-update.sh --check`
+- Validate packaged agent surfaces with `./scripts/validate-agent-surface.sh`
Updates only touch framework files (skills, docs, scripts) — your personal content is never modified.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4eb540d..0e57a07 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,56 @@
All notable changes to COG (Cognition + Obsidian + Git) will be documented in this file.
+## [3.5.0] - 2026-04-16
+
+### Specialist Sessions, People CRM & Worker Agents
+
+COG now includes 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), a people CRM system with tiered enrichment for progressive team knowledge, and operational protocols that make multi-agent workflows faster and more reliable.
+
+### Added
+
+#### Worker Agent Architecture (`.claude/agents/`)
+- **`worker-data-collector`** — Structured extraction from GitHub, Slack, Jira, Linear, or file system (Sonnet)
+- **`worker-researcher`** — Web research with source citations and evidence extraction (Sonnet)
+- **`worker-file-ops`** — Vault file operations, metadata updates, profile maintenance (Sonnet)
+- **`worker-executor`** — Pre-approved mutations: Jira transitions, Linear updates, API calls (Sonnet)
+- **`worker-publisher`** — Publishing to Slack, Confluence, Notion, webhooks (Sonnet)
+- **`brief-people-updater`** — Batch-update people profiles from meetings, briefs, and Slack data (Sonnet)
+
+#### People CRM System
+- **`05-knowledge/people/README.md`** — People CRM documentation with design principles, file naming, citation format
+- **`06-templates/people-profile-template.md`** — Two-layer profile template (Compiled Truth + append-only Timeline)
+- Progressive, evidence-based profiles built from meetings, Slack, PRs, and daily interactions
+- Mandatory source citations with confidence levels (high/medium/low)
+
+#### Operational Protocols in CLAUDE.md
+- **Model Routing** — Sonnet workers for data collection/publishing, Opus lead for reasoning/synthesis
+- **Worker Output Rule** — Workers write to `/tmp/` files and return only a status + path (eliminates slow token generation)
+- **Brain-First Knowledge Protocol** — Read `05-knowledge/` before answering people/project/strategy questions
+- **Citation Rule** — Source attribution required for factual statements in durable notes
+
+### Changed (includes v3.4.1 packaging fixes)
+
+- **`README.md`** — Added Worker Agents section, People CRM section, updated vault structure and mermaid diagrams, added agent support matrix
+- **`AGENTS.md`** — Added Worker Agents documentation, People CRM commands, updated vault structure with people/ and agents/
+- **`SETUP.md`** — Added worker agents and people CRM to directory structure, updated skill counts
+- **`CLAUDE.md`** — Major additions: model routing, worker output rule, brain-first protocol, citation rule, knowledge system in vault structure
+- **`CONTRIBUTING.md`** — Added agent contribution guidelines and coding conventions for `.claude/agents/`
+- **`.claude-plugin/plugin.json`** — Bumped version, added agents metadata, updated architecture description
+- **`marketplace-entry.json`** — Bumped version to 3.5.0
+- **`cog-update.sh`** — Added 8 new framework files (6 agents + people README + profile template)
+- **`COG-VERSION`** — Bumped 3.4.0 → 3.5.0
+- **`docs/AGENT-SUPPORT.md`** — Canonical support matrix for all agent surfaces
+- **`scripts/validate-agent-surface.sh`** — Release/install validator
+- **`.github/MARKETPLACE.md`** — Rewritten for current package model
+
+### Design Decisions
+- **gstack-inspired specialist lanes**: Capture, Synthesis, Publishing, Team Intelligence, Repo Maintenance — clear operating gears instead of one generic agent session
+- **Sonnet for I/O, Opus for thinking**: Workers handle data-heavy tasks cheaply and in parallel; the lead session does reasoning and editorial judgment
+- **File-based worker output**: Writing to `/tmp/` then reading is instant; generating thousands of tokens as agent output takes minutes
+- **People profiles are append-only**: Timeline history is never rewritten — only the Compiled Truth section updates as understanding evolves
+- **Citation-first culture**: Every factual claim in knowledge notes traces to a source with confidence level
+
## [3.4.0] - 2026-03-12
### PM Workflow Skills & Auto-Research
diff --git a/CLAUDE.md b/CLAUDE.md
index 2f41c45..9f23ae9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,5 +1,69 @@
# COG Second Brain — Framework Instructions
+## Model Routing — ALWAYS APPLY
+
+When spawning subagents, use the correct model for the task:
+
+| Task type | Model | Agent definition |
+|-----------|-------|-----------------|
+| Data collection (GitHub, Slack, Jira, Linear, file reads) | **Sonnet** | `worker-data-collector` |
+| Web research (search, fetch URLs, extract facts) | **Sonnet** | `worker-researcher` |
+| Publishing (Slack, Confluence, Notion, webhooks) | **Sonnet** | `worker-publisher` |
+| File operations (vault reads/writes, metadata, profiles) | **Sonnet** | `worker-file-ops` |
+| Pre-approved mutations (Jira transitions, Linear updates, API calls) | **Sonnet** | `worker-executor` |
+| People profile updates from brief/meeting data | **Sonnet** | `brief-people-updater` |
+| Reasoning, synthesis, cross-referencing, writing | **Opus** | Lead session (no delegation) |
+| Editorial judgment, tone, strategic decisions | **Opus** | Lead session (no delegation) |
+
+**Rule:** If a task doesn't require reasoning or judgment, delegate it to a Sonnet worker. The lead session (Opus) handles thinking, synthesis, and writing only.
+
+Agent definitions live in `.claude/agents/`.
+
+### Worker Output Rule — ALWAYS APPLY
+
+Workers must **write results to a file** and return only a short status + file path. Never have a worker return large text as output.
+
+| Output size | What to do |
+|------------|------------|
+| < 2K tokens | Return inline (short status, confirmation, error) |
+| >= 2K tokens | Write to `/tmp/{task-slug}-{context}.md`, return path |
+
+**Why:** Generating thousands of tokens as agent output is sequential and extremely slow. Writing to file is instant. The orchestrator or next agent reads the file via the Read tool.
+
+**Pattern:**
+```
+# Worker prompt must include:
+"Write your results to /tmp/{descriptive-name}.md and return ONLY a short status message with the file path."
+
+# Worker returns:
+"OK: /tmp/slack-data.md (gathered 47 messages, 12 threads)"
+
+# Orchestrator reads:
+Read("/tmp/slack-data.md")
+```
+
+**Applies to:** All `worker-*` agents, all `brief-*` agents, any subagent that collects, extracts, or processes data.
+
+---
+
+## Brain-First Knowledge Protocol (MUST APPLY)
+
+Before answering any question about people, projects, strategy, decisions, or historical context:
+1. Read relevant notes from `05-knowledge/` first (especially `05-knowledge/people/` for people questions).
+2. If project-specific, also read related files in `04-projects/<project>/`.
+3. Only then synthesize an answer.
+
+If the user corrects a factual statement, write/update the correction in the relevant knowledge note immediately.
+
+### Citation Rule
+For factual statements written into durable notes (`05-knowledge/**`, people profiles, consolidated docs), include source attribution inline:
+
+`[Source: [[path/to/note]] | YYYY-MM-DD | confidence: high|medium|low]`
+
+Use one citation per distinct factual claim block where practical.
+
+---
+
## Integration Preferences
Before using any external integration in a skill, check `00-inbox/MY-INTEGRATIONS.md`:
@@ -37,11 +101,19 @@ Role packs live in `.claude/roles/`. New roles can be added by dropping a file f
### Framework files (updated via `cog-update.sh` or `/update-cog`)
- `.claude/skills/` — Claude Code skills (17 skills)
+- `.claude/agents/` — Worker agent definitions (6 agents)
- `.claude/roles/` — Role packs for personalized recommendations
- `.kiro/powers/` — Kiro powers
- `.gemini/commands/` — Gemini CLI commands
- `AGENTS.md` — Universal agent documentation
+### Knowledge system (`05-knowledge/`)
+- `people/` — People CRM profiles (progressive, evidence-based)
+- `consolidated/` — Frameworks and synthesis documents
+- `patterns/` — Identified patterns
+- `timeline/` — Thinking evolution
+- `booklets/` — URL bookmarks by category
+
### Content directories (never touched by updates)
- `00-inbox/` — Profiles, interests, integrations
- `01-daily/` — Briefs and check-ins
diff --git a/COG-VERSION b/COG-VERSION
index 1809198..1545d96 100644
--- a/COG-VERSION
+++ b/COG-VERSION
@@ -1 +1 @@
-3.4.0
+3.5.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 903a3c1..735cacd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,13 +41,22 @@ We welcome ideas for new features or improvements:
- Add a changelog entry in `CHANGELOG.md`
- If adding a new file, add it to the `FRAMEWORK_FILES` array in `cog-update.sh`
- Update `marketplace-entry.json` and `.claude-plugin/plugin.json` version fields
+ - Keep the support matrix truthful in `README.md`, `SETUP.md`, `AGENTS.md`, and `docs/AGENT-SUPPORT.md`
+ - Run `./scripts/validate-agent-surface.sh` before opening the PR
#### Making Changes
-1. **Skills**: New skills should be added in all supported formats:
- - `.claude/skills/[name]/SKILL.md` - Claude Code format (include `roles` and `integrations` in frontmatter)
- - `.kiro/powers/cog-[name]/POWER.md` - Kiro format
- - Update `agents.md` - Universal documentation
+1. **Worker Agents**: New agents should be added to `.claude/agents/` with this format:
+ - YAML frontmatter with `name`, `description`, and `model` (use `sonnet` for I/O tasks, `opus` only if reasoning is required)
+ - Clear capability list and output rule
+ - Add the file to `FRAMEWORK_FILES` in `cog-update.sh`
+ - Document in `AGENTS.md` under "Worker Agents"
+2. **Skills**: New skills should be added in every surface that claims to support them:
+ - `.claude/skills/[name]/SKILL.md` - Claude Code format (required; include `roles` and `integrations` in frontmatter)
+ - `AGENTS.md` - Universal documentation (required)
+ - `.claude-plugin/plugin.json` - Packaged skill manifest (required)
+ - `.kiro/powers/cog-[name]/POWER.md` - Kiro format (if Kiro supports the skill)
+ - `.gemini/commands/[name].toml` + `.gemini/skills/[name].md` - Gemini CLI format (if Gemini supports the skill)
- If the skill is role-specific, add it to relevant role packs in `.claude/roles/`
2. **Templates**: Follow existing YAML frontmatter conventions
3. **Documentation**: Update README.md if adding major features
@@ -68,6 +77,7 @@ Before submitting:
2. Ensure it works with existing commands
3. Verify it doesn't break existing functionality
4. Check that documentation is accurate
+5. Run `./scripts/validate-agent-surface.sh` for packaging/manifest consistency
#### Submitting
@@ -152,7 +162,30 @@ keywords: ["keyword1", "keyword2", "keyword3"]
[Step-by-step process]
```
-### Universal Documentation (`agents.md`)
+### Worker Agents (`.claude/agents/[name].md`)
+
+```markdown
+---
+name: worker-name
+description: What this worker does
+model: sonnet
+---
+
+You are a [role]. Your job is [single responsibility].
+
+## Capabilities
+- **Source**: What it can access
+
+## Output Rule
+- Always write results to `/tmp/{task-slug}.md`
+- Return ONLY a short status + file path
+
+## Rules
+- Never fabricate data
+- [domain-specific rules]
+```
+
+### Universal Documentation (`AGENTS.md`)
Add new skills under "## Available Commands" with:
- Command name and triggers
diff --git a/README.md b/README.md
index db551b2..12a528b 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,9 @@
graph LR
A[You] -- natural language --> B[AI Agent]
B -- runs --> C[17 Skills]
+ C -- delegates to --> W[6 Worker Agents]
C -- reads & writes --> D[.md Files]
+ W -- reads & writes --> D
C -- syncs with --> G[GitHub / Linear / Slack / PostHog]
D --> E[Git]
D --> F[iCloud]
@@ -38,6 +40,19 @@ cd COG-second-brain
Done — COG is personalized and ready in ~2 minutes. See [SETUP.md](SETUP.md) for optional config (Git sync, iCloud, Obsidian Tasks, etc.).
+## Agent Support Matrix
+
+COG ships a **full Claude Code surface** plus **core native surfaces** for Kiro and Gemini CLI, with `AGENTS.md` as the universal fallback for Codex and other markdown-reading agents.
+
+| Surface | Current support | Notes |
+|---|---|---|
+| Claude Code | 17 native skills | Full first-class surface |
+| Kiro | 7 native powers | Core workflows today |
+| Gemini CLI | 7 native commands | Core workflows today |
+| `AGENTS.md` | 17 documented commands | Universal fallback for Codex and other 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](docs/AGENT-SUPPORT.md) for the detailed support matrix and contributor rules.
+
## Skills
### Core Skills (Personal Knowledge)
@@ -79,6 +94,31 @@ Done — COG is personalized and ready in ~2 minutes. See [SETUP.md](SETUP.md) f
|---|---|---|
| **auto-research** | Deep strategic research engine — decomposes questions into parallel research threads with multiple agents | "Research the future of AI testing tools" |
+### Worker Agents (Specialist Sessions)
+
+COG 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).
+
+| Agent | What it does | Model |
+|---|---|---|
+| **worker-data-collector** | Structured extraction from GitHub, Slack, Jira, Linear | Sonnet |
+| **worker-researcher** | Web research with source citations | Sonnet |
+| **worker-file-ops** | Vault file operations, metadata, profiles | Sonnet |
+| **worker-executor** | Pre-approved mutations (Jira, Linear, APIs) | Sonnet |
+| **worker-publisher** | Publishing to Slack, Confluence, Notion | Sonnet |
+| **brief-people-updater** | Batch-update people profiles from meetings/briefs | Sonnet |
+
+> 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.
+
+### People CRM (Knowledge-Based Team Profiles)
+
+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.
+
### Role Packs (Personalized Recommendations)
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.
@@ -126,6 +166,7 @@ graph TD
```
COG-second-brain/
├── .claude/skills/ # Claude Code skills (17)
+├── .claude/agents/ # Worker agent definitions (6)
├── .claude/roles/ # Role packs (7) — personalized recommendations
├── .kiro/powers/ # Kiro powers
├── .gemini/commands/ # Gemini CLI commands
@@ -136,7 +177,9 @@ COG-second-brain/
├── 02-personal/ # Personal braindumps (private)
├── 03-professional/ # Professional braindumps & strategy
├── 04-projects/ # Per-project tracking
-└── 05-knowledge/ # Consolidated insights & patterns
+├── 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.
@@ -151,7 +194,8 @@ COG separates **framework files** (skills, docs, scripts) from **your content**
| Shell script | `./cog-update.sh` (interactive) &bull; `--check` &bull; `--dry-run` &bull; `--force` |
| Manual Git | `git fetch cog-upstream main` then checkout specific files |
-Check your version: `cat COG-VERSION`
+Check your version: `cat COG-VERSION`
+Validate packaged surfaces: `./scripts/validate-agent-surface.sh`
## FAQ
@@ -191,6 +235,7 @@ Git is optional but recommended for version history. COG works fine with just iC
- [x] ~~Upstream update system~~ (shipped in v3.2)
- [x] ~~Role packs & integration discovery~~ (shipped in v3.3)
- [x] ~~PM workflow skills & auto-research~~ (shipped in v3.4)
+- [x] ~~Worker agents, people CRM & specialist sessions~~ (shipped in v3.5)
- [ ] Web interface for knowledge graph visualization
- [ ] Mobile-first commands (optimized for Obsidian mobile)
- [ ] Team collaboration features (with privacy preservation)
diff --git a/SETUP.md b/SETUP.md
index c5b0ad4..0d15bcb 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -7,9 +7,10 @@ Complete step-by-step instructions for setting up your COG (Cognition + Obsidian
### What You Need
1. **AI Agent** (choose one or more):
- - [Claude Code](https://claude.ai/download) - Uses `.claude/skills/`
- - [Kiro](https://kiro.dev/) - Uses `.kiro/powers/`
- - Any OpenAI-compatible agent - Uses `agents.md`
+ - [Claude Code](https://claude.ai/download) - Uses `.claude/skills/` (full 17-skill native surface)
+ - [Kiro](https://kiro.dev/) - Uses `.kiro/powers/` (7 core native powers)
+ - [Gemini CLI](https://github.com/google-gemini/gemini-cli) - Uses `GEMINI.md` + `.gemini/commands/` (7 core native commands)
+ - Any OpenAI-compatible or markdown-reading agent - Uses `AGENTS.md`
2. **Obsidian** ([Download here](https://obsidian.md/)) - Recommended (optional)
3. **Git** - Already on your system if you can run clone commands
@@ -35,18 +36,20 @@ code .
- Kiro will activate the cog-onboarding power
**Other Agents:**
-- Point the agent to `agents.md` for skill documentation
+- Point the agent to `AGENTS.md` for skill documentation
- Ask it to run the onboarding workflow
That's it! You now have a working second brain.
**What just happened?**
- The cloned `COG-second-brain` folder IS your second brain
-- 17 AI skills are available in multiple formats:
- - `.claude/skills/` - For Claude Code
- - `.kiro/powers/` - For Kiro
- - `agents.md` - For any agent
+- COG now exposes a clear multi-agent support matrix:
+ - `.claude/skills/` - 17 Claude Code skills (full surface)
+ - `.kiro/powers/` - 7 Kiro powers (core workflows)
+ - `.gemini/commands/` + `.gemini/skills/` - 7 Gemini CLI commands (core workflows)
+ - `AGENTS.md` - 17 documented commands for Codex and other agents
- Onboarding will create your personalized directory structure
+- You can validate the packaged agent surfaces anytime with `./scripts/validate-agent-surface.sh`
**Optional: Use with Obsidian**
@@ -124,8 +127,9 @@ After running onboarding, you'll have this structure:
```
COG-second-brain/ # This is your second brain folder
-├── agents.md # Universal agent documentation
+├── AGENTS.md # Universal agent documentation
├── .claude/
+│ ├── agents/ # 6 worker agent definitions
│ ├── roles/ # 7 role packs for personalized recommendations
│ └── skills/ # 17 Claude Code skills
│ ├── onboarding/
@@ -142,13 +146,17 @@ COG-second-brain/ # This is your second brain folder
│ ├── publish-to-confluence/
│ └── update-knowledge-base/
├── .kiro/
-│ └── powers/ # 6 Kiro powers
+│ └── powers/ # 7 Kiro powers (core workflows)
│ ├── cog-onboarding/
│ ├── cog-braindump/
│ ├── cog-daily-brief/
│ ├── cog-weekly-checkin/
│ ├── cog-knowledge-consolidation/
-│ └── cog-url-dump/
+│ ├── cog-url-dump/
+│ └── cog-update/
+├── .gemini/
+│ ├── commands/ # 7 Gemini CLI commands (core workflows)
+│ └── skills/ # Detailed Gemini command playbooks
├── CLAUDE.md # Framework instructions (role packs, integrations)
├── 00-inbox/ # Profiles, interests, integrations (created by onboarding)
├── 01-daily/ # Daily briefs and check-ins
@@ -162,9 +170,10 @@ COG-second-brain/ # This is your second brain folder
├── 05-knowledge/ # Consolidated insights
│ ├── consolidated/
│ ├── patterns/
+│ ├── people/ # People CRM profiles
│ ├── booklets/ # URL bookmarks
│ └── timeline/
-└── 06-templates/ # Markdown templates
+└── 06-templates/ # Markdown templates (incl. people profile)
```
## Optional: Advanced Configuration
@@ -309,14 +318,22 @@ touch .kiro/powers/my-power/POWER.md
### For Other Agents
-Edit `agents.md` to add or modify skill documentation. This file serves as universal documentation that any AI agent can read.
+Edit `AGENTS.md` to add or modify skill documentation. This file serves as universal documentation that any AI agent can read.
### Keeping Skills in Sync
-When you modify a skill, update all formats:
-1. `.claude/skills/[name]/SKILL.md` - Claude Code
-2. `.kiro/powers/cog-[name]/POWER.md` - Kiro
-3. `agents.md` - Universal documentation
+When you modify a skill, update every shipped surface that claims to support it:
+1. `.claude/skills/[name]/SKILL.md` - Claude Code (required)
+2. `AGENTS.md` - Universal documentation (required)
+3. `.claude-plugin/plugin.json` - Marketplace/package manifest (required)
+4. `.kiro/powers/cog-[name]/POWER.md` - Kiro (if that surface supports the skill)
+5. `.gemini/commands/[name].toml` + `.gemini/skills/[name].md` - Gemini CLI (if that surface supports the skill)
+6. `README.md` / `SETUP.md` / `docs/AGENT-SUPPORT.md` - support matrix docs when counts or support levels change
+
+After changes, run:
+```bash
+./scripts/validate-agent-surface.sh
+```
## Troubleshooting
@@ -336,8 +353,9 @@ When you modify a skill, update all formats:
3. Try mentioning specific keywords from the power's `keywords` list
**Solutions for Other Agents:**
-1. Ensure `agents.md` exists in the root folder
-2. Point the agent to read `agents.md` for available commands
+1. Ensure `AGENTS.md` exists in the root folder
+2. Point the agent to read `AGENTS.md` for available commands
+3. Run `./scripts/validate-agent-surface.sh` to confirm packaged docs and manifests are aligned
### Files Saving to Wrong Location
@@ -431,6 +449,7 @@ The agent will:
2. Show what's changed
3. Let you approve updates per-file (with backup option for customized files)
4. Apply updates and suggest a commit
+5. Recommend validating packaged surfaces before you publish or share the updated framework
### Method 2: Shell Script
@@ -446,6 +465,12 @@ The agent will:
# Update everything without prompting
./cog-update.sh --force
+
+# Run packaging/support-surface validation only
+./cog-update.sh --validate
+
+# Or run the validator directly
+./scripts/validate-agent-surface.sh
```
### Method 3: Manual Git
@@ -473,7 +498,7 @@ git add -A && git commit -m "Update COG framework to v$(cat COG-VERSION)"
| Skills (`.claude/skills/`, `.kiro/powers/`, `.gemini/`) | `00-inbox/` (profiles, notes) |
| Docs (`README.md`, `SETUP.md`, `AGENTS.md`, etc.) | `01-daily/` (briefs, checkins) |
| Scripts (`cog-update.sh`) | `02-personal/` (braindumps) |
-| Config (`.gitignore`, `plugin.json`) | `03-professional/` (braindumps) |
+| Config (`.gitignore`, `.claude-plugin/plugin.json`, `marketplace-entry.json`) | `03-professional/` (braindumps) |
| Version (`COG-VERSION`) | `04-projects/` (project files) |
| | `05-knowledge/` (consolidated) |
| | `06-templates/` (your templates) |
diff --git a/cog-update.sh b/cog-update.sh
index a9df6a8..cf54817 100755
--- a/cog-update.sh
+++ b/cog-update.sh
@@ -7,6 +7,7 @@
# ./cog-update.sh --check Check for available updates (no changes)
# ./cog-update.sh --dry-run Show what would change (no changes)
# ./cog-update.sh --force Update all framework files without prompting
+# ./cog-update.sh --validate Run packaging validator only
# ./cog-update.sh --help Show this help message
set -euo pipefail
@@ -16,6 +17,7 @@ REMOTE_NAME="cog-upstream"
REMOTE_URL="https://github.com/huytieu/COG-second-brain.git"
BRANCH="main"
VERSION_FILE="COG-VERSION"
+VALIDATOR_SCRIPT="scripts/validate-agent-surface.sh"
# Framework files — these are safe to overwrite (your content is never in this list)
FRAMEWORK_FILES=(
@@ -29,6 +31,9 @@ FRAMEWORK_FILES=(
"LICENSE"
"COG-VERSION"
"cog-update.sh"
+ "docs/AGENT-SUPPORT.md"
+ ".github/MARKETPLACE.md"
+ "scripts/validate-agent-surface.sh"
# Claude Code skills
".claude/skills/onboarding/SKILL.md"
@@ -58,6 +63,18 @@ FRAMEWORK_FILES=(
".claude/roles/founder.md"
".claude/roles/marketer.md"
+ # Worker agents
+ ".claude/agents/worker-data-collector.md"
+ ".claude/agents/worker-researcher.md"
+ ".claude/agents/worker-file-ops.md"
+ ".claude/agents/worker-executor.md"
+ ".claude/agents/worker-publisher.md"
+ ".claude/agents/brief-people-updater.md"
+
+ # People CRM
+ "05-knowledge/people/README.md"
+ "06-templates/people-profile-template.md"
+
# Framework config
"CLAUDE.md"
@@ -119,13 +136,16 @@ Usage:
./cog-update.sh --check Check for available updates (no changes)
./cog-update.sh --dry-run Show what would change (no changes)
./cog-update.sh --force Update all framework files without prompting
+ ./cog-update.sh --validate Run packaging validator only
./cog-update.sh --help Show this help message
How it works:
1. Adds/fetches the upstream remote (cog-upstream)
2. Compares each framework file against the upstream version
3. Offers to update changed files (interactive mode) or updates all (--force)
- 4. Your content folders (00-inbox, 01-daily, etc.) are NEVER modified
+ 4. Warns if your working tree is already dirty before replacing framework files
+ 5. Runs the packaging validator after updates when available
+ 6. Your content folders (00-inbox, 01-daily, etc.) are NEVER modified
Safe to run anytime — your notes, profiles, and braindumps are never touched.
EOF
@@ -188,16 +208,44 @@ backup_file() {
fi
}
+worktree_is_dirty() {
+ [[ -n "$(git status --porcelain)" ]]
+}
+
+warn_if_dirty() {
+ if worktree_is_dirty; then
+ warn "Your working tree has uncommitted changes. Framework updates are still safe, but review carefully before committing."
+ fi
+}
+
+run_validator() {
+ if [[ -x "$VALIDATOR_SCRIPT" ]]; then
+ echo ""
+ info "Running ${BOLD}${VALIDATOR_SCRIPT}${RESET}..."
+ if "$VALIDATOR_SCRIPT"; then
+ ok "Packaging validation passed"
+ return 0
+ else
+ warn "Packaging validation reported issues. Review before committing."
+ return 1
+ fi
+ else
+ warn "Validator not found at ${VALIDATOR_SCRIPT}; skipping packaging validation"
+ return 0
+ fi
+}
+
# ── Main logic ───────────────────────────────────────────────────────
main() {
local mode="interactive"
while [[ $# -gt 0 ]]; do
case "$1" in
- --check) mode="check"; shift ;;
- --dry-run) mode="dry-run"; shift ;;
- --force) mode="force"; shift ;;
- --help|-h) usage; exit 0 ;;
+ --check) mode="check"; shift ;;
+ --dry-run) mode="dry-run"; shift ;;
+ --force) mode="force"; shift ;;
+ --validate) mode="validate"; shift ;;
+ --help|-h) usage; exit 0 ;;
*) err "Unknown option: $1"; usage; exit 1 ;;
esac
done
@@ -208,6 +256,11 @@ main() {
exit 1
fi
+ if [[ "$mode" == "validate" ]]; then
+ run_validator
+ exit $?
+ fi
+
echo ""
echo -e "${BOLD}COG Upstream Update${RESET}"
echo -e "─────────────────────"
@@ -223,6 +276,11 @@ main() {
info "Upstream version: ${BOLD}${uv}${RESET}"
echo ""
+ if [[ "$mode" == "interactive" || "$mode" == "force" ]]; then
+ warn_if_dirty
+ [[ -n "$(git status --porcelain)" ]] && echo ""
+ fi
+
if [[ "$uv" == "unknown" ]]; then
err "Could not read upstream version. Check your internet connection."
exit 1
@@ -297,6 +355,7 @@ main() {
echo ""
ok "Updated ${updated} file(s) to v${uv}"
info "Backups saved as *.backup-YYYYMMDD-HHMMSS alongside originals"
+ run_validator || true
exit 0
fi
@@ -374,6 +433,7 @@ main() {
echo ""
if [[ $updated -gt 0 ]]; then
+ run_validator || true
info "Review changes with ${BOLD}git diff${RESET}, then commit when ready:"
echo " git add -A && git commit -m \"Update COG framework to v${uv}\""
fi
diff --git a/docs/AGENT-SUPPORT.md b/docs/AGENT-SUPPORT.md
new file mode 100644
index 0000000..dc7325e
--- /dev/null
+++ b/docs/AGENT-SUPPORT.md
@@ -0,0 +1,89 @@
+# COG Agent Support Matrix
+
+COG intentionally ships **multiple agent surfaces**. They are not all identical.
+
+This document is the packaging contract: it tells contributors and maintainers which surfaces are first-class today, which ones are partial, and what must stay in sync before publishing a release.
+
+## Current Support Matrix
+
+| Surface | Shipped format | Coverage | Status |
+|---|---|---:|---|
+| Claude Code | `.claude/skills/*/SKILL.md` | 17 skills | Full native surface |
+| Universal agent docs | `AGENTS.md` | 17 commands | Full documented fallback |
+| Kiro | `.kiro/powers/*/POWER.md` | 7 powers | Core workflows only |
+| Gemini CLI | `.gemini/commands/*.toml` + `.gemini/skills/*.md` | 7 commands | Core workflows only |
+
+## What “Full” vs “Core” Means
+
+### Full surfaces
+These surfaces should expose the complete public COG command set:
+- `onboarding`
+- `braindump`
+- `daily-brief`
+- `weekly-checkin`
+- `knowledge-consolidation`
+- `url-dump`
+- `team-brief`
+- `meeting-transcript`
+- `comprehensive-analysis`
+- `update-cog`
+- `auto-research`
+- `create-user-story`
+- `generate-prd`
+- `generate-release-notes`
+- `export-open-issues`
+- `publish-to-confluence`
+- `update-knowledge-base`
+
+Today, **Claude Code** and **`AGENTS.md`** are the full surfaces.
+
+### Core surfaces
+These surfaces intentionally cover the most common personal workflows first:
+- `onboarding`
+- `braindump`
+- `daily-brief`
+- `weekly-checkin`
+- `knowledge-consolidation`
+- `url-dump`
+- `update-cog`
+
+Today, **Kiro** and **Gemini CLI** are core surfaces.
+
+## Packaging Rules
+
+If you add, remove, rename, or materially change a public COG skill:
+
+1. Update the **Claude skill** in `.claude/skills/`
+2. Update **`AGENTS.md`** for the universal surface
+3. Update **`.claude-plugin/plugin.json`** so marketplace metadata stays truthful
+4. Update **README / SETUP / this file** if counts or support levels change
+5. If the skill is supported natively in Kiro or Gemini, update those files too
+6. Add new framework files to `FRAMEWORK_FILES` in `cog-update.sh`
+7. Run `./scripts/validate-agent-surface.sh`
+
+## Validation
+
+Run this before tagging a release, opening a packaging PR, or after using `./cog-update.sh`:
+
+```bash
+./scripts/validate-agent-surface.sh
+```
+
+The validator checks:
+- manifest JSON validity
+- declared skill paths in `.claude-plugin/plugin.json`
+- plugin skill count vs actual shipped Claude skills
+- `AGENTS.md` coverage for all manifest skills
+- common packaging drift like `agents.md` vs `AGENTS.md`
+
+## Safe Update Workflow
+
+Recommended maintainer flow:
+
+```bash
+./cog-update.sh --check
+./cog-update.sh
+./scripts/validate-agent-surface.sh
+```
+
+If you have local framework customizations, prefer interactive update mode so you can backup per-file before replacing anything.
diff --git a/marketplace-entry.json b/marketplace-entry.json
index eb0eae3..9265069 100644
--- a/marketplace-entry.json
+++ b/marketplace-entry.json
@@ -6,6 +6,6 @@
"email": "[email protected]",
"url": "https://github.com/huytieu"
},
- "description": "Self-evolving second brain with AI agents for knowledge management",
- "version": "3.4.0"
+ "description": "Self-evolving second brain with multi-agent surfaces for Claude Code, Kiro, Gemini CLI, and AGENTS-compatible assistants",
+ "version": "3.5.0"
}
diff --git a/scripts/validate-agent-surface.sh b/scripts/validate-agent-surface.sh
new file mode 100755
index 0000000..d4e51bd
--- /dev/null
+++ b/scripts/validate-agent-surface.sh
@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+RESET='\033[0m'
+
+info() { echo -e "${CYAN}ℹ${RESET} $*"; }
+ok() { echo -e "${GREEN}✓${RESET} $*"; }
+warn() { echo -e "${YELLOW}⚠${RESET} $*"; }
+err() { echo -e "${RED}✗${RESET} $*" >&2; }
+
+failures=0
+warnings=0
+
+record_failure() {
+ err "$*"
+ failures=$((failures + 1))
+}
+
+record_warning() {
+ warn "$*"
+ warnings=$((warnings + 1))
+}
+
+if ! command -v python3 >/dev/null 2>&1; then
+ record_failure "python3 is required for validation"
+ exit 1
+fi
+
+info "Validating packaged agent surfaces from $ROOT_DIR"
+
+if python3 -m json.tool .claude-plugin/plugin.json >/dev/null 2>&1; then
+ ok ".claude-plugin/plugin.json is valid JSON"
+else
+ record_failure ".claude-plugin/plugin.json is not valid JSON"
+fi
+
+if python3 -m json.tool marketplace-entry.json >/dev/null 2>&1; then
+ ok "marketplace-entry.json is valid JSON"
+else
+ record_failure "marketplace-entry.json is not valid JSON"
+fi
+
+manifest_tmp="$(mktemp)"
+python3 - <<'PY' > "$manifest_tmp"
+import json
+with open('.claude-plugin/plugin.json') as f:
+ data = json.load(f)
+for skill in data.get('skills', []):
+ print(f"{skill['name']}\t{skill['path']}")
+PY
+
+manifest_count=$(wc -l < "$manifest_tmp" | tr -d ' ')
+claude_skill_count=$(find .claude/skills -name SKILL.md | wc -l | tr -d ' ')
+
+if [[ "$manifest_count" == "$claude_skill_count" ]]; then
+ ok "Plugin manifest skill count matches shipped Claude skills ($manifest_count)"
+else
+ record_failure "Plugin manifest declares $manifest_count skills but .claude/skills contains $claude_skill_count SKILL.md files"
+fi
+
+while IFS=$'\t' read -r name path; do
+ [[ -z "$name" ]] && continue
+
+ if [[ -f "$path" ]]; then
+ ok "Manifest path exists for $name → $path"
+ else
+ record_failure "Manifest path missing for $name → $path"
+ fi
+
+ if grep -Fq "### /$name" AGENTS.md; then
+ ok "AGENTS.md documents /$name"
+ else
+ record_failure "AGENTS.md is missing /$name"
+ fi
+done < "$manifest_tmp"
+
+rm -f "$manifest_tmp"
+
+plugin_version=$(python3 - <<'PY'
+import json
+with open('.claude-plugin/plugin.json') as f:
+ print(json.load(f)['version'])
+PY
+)
+marketplace_version=$(python3 - <<'PY'
+import json
+with open('marketplace-entry.json') as f:
+ print(json.load(f)['version'])
+PY
+)
+cog_version=$(tr -d '[:space:]' < COG-VERSION)
+
+if [[ "$plugin_version" == "$marketplace_version" && "$plugin_version" == "$cog_version" ]]; then
+ ok "Version is aligned across plugin.json, marketplace-entry.json, and COG-VERSION ($cog_version)"
+else
+ record_failure "Version mismatch: plugin.json=$plugin_version marketplace-entry.json=$marketplace_version COG-VERSION=$cog_version"
+fi
+
+if rg -n "agents\.md" README.md SETUP.md CONTRIBUTING.md .github/MARKETPLACE.md >/dev/null 2>&1; then
+ record_failure "Found lowercase 'agents.md' references in packaging docs; use AGENTS.md consistently"
+else
+ ok "Packaging docs consistently use AGENTS.md casing"
+fi
+
+kiro_count=$(find .kiro/powers -name POWER.md | wc -l | tr -d ' ')
+gemini_commands_count=$(find .gemini/commands -type f | wc -l | tr -d ' ')
+gemini_skills_count=$(find .gemini/skills -type f | wc -l | tr -d ' ')
+
+if [[ "$kiro_count" == "7" ]]; then
+ ok "Kiro core surface count is $kiro_count"
+else
+ record_warning "Expected 7 Kiro powers, found $kiro_count"
+fi
+
+if [[ "$gemini_commands_count" == "7" && "$gemini_skills_count" == "7" ]]; then
+ ok "Gemini core surface counts are aligned (commands=$gemini_commands_count, skills=$gemini_skills_count)"
+else
+ record_warning "Expected 7 Gemini commands and 7 Gemini skills, found commands=$gemini_commands_count skills=$gemini_skills_count"
+fi
+
+if [[ -f docs/AGENT-SUPPORT.md ]]; then
+ ok "docs/AGENT-SUPPORT.md exists"
+else
+ record_failure "docs/AGENT-SUPPORT.md is missing"
+fi
+
+if [[ $failures -gt 0 ]]; then
+ echo
+ err "Validation failed with $failures error(s) and $warnings warning(s)"
+ exit 1
+fi
+
+echo
+ok "Validation passed with $warnings warning(s)"