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.
Python agent-loopagent-pluginsagent-skillsagenticai-agentsclaude-codeclosed-loopcursorgarry-tangbraingstackknowledge-managementloop-engineeringobsidianpeople-crmproductivitysecond-brainself-evolvingverification-harnessworker-agents
Add worker agents, people CRM, and specialist sessions (v3.5.0)
Huy Tieu3777622e9595
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 sectionsdiff --git a/.claude/agents/worker-executor.md b/.claude/agents/worker-executor.mdnew file mode 100644index 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 themdiff --git a/.claude/agents/worker-file-ops.md b/.claude/agents/worker-file-ops.mdnew file mode 100644index 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-knowledgediff --git a/.claude/agents/worker-publisher.md b/.claude/agents/worker-publisher.mdnew file mode 100644index 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 othersdiff --git a/.claude/agents/worker-researcher.md b/.claude/agents/worker-researcher.mdnew file mode 100644index 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 assessmentdiff --git a/.github/MARKETPLACE.md b/.github/MARKETPLACE.mdindex 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.mddiff --git a/05-knowledge/people/README.md b/05-knowledge/people/README.mdnew file mode 100644index 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 informationdiff --git a/06-templates/people-profile-template.md b/06-templates/people-profile-template.mdnew file mode 100644index 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.mdindex 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.mdindex 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-Researchdiff --git a/CLAUDE.md b/CLAUDE.mdindex 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 PreferencesBefore 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-insdiff --git a/COG-VERSION b/COG-VERSIONindex 1809198..1545d96 100644--- a/COG-VERSION+++ b/COG-VERSION@@ -1 +1 @@-3.4.0+3.5.0diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 conventions3. **Documentation**: Update README.md if adding major features@@ -68,6 +77,7 @@ Before submitting:2. Ensure it works with existing commands3. Verify it doesn't break existing functionality4. 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 triggersdiff --git a/README.md b/README.mdindex db551b2..12a528b 100644--- a/README.md+++ b/README.md@@ -10,7 +10,9 @@graph LRA[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 --> DC -- syncs with --> G[GitHub / Linear / Slack / PostHog]D --> E[Git]D --> F[iCloud]@@ -38,6 +40,19 @@ cd COG-second-brainDone — 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) • `--check` • `--dry-run` • `--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.mdindex 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 Need1. **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 workflowThat'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 changed3. 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.shindex 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 messageset -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 messageHow it works:1. Adds/fetches the upstream remote (cog-upstream)2. Compares each framework file against the upstream version3. 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 modifiedSafe 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 ]]; docase "$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 ;;esacdone@@ -208,6 +256,11 @@ main() {exit 1fi+ 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" ]]; thenerr "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 || trueexit 0fi@@ -374,6 +433,7 @@ main() {echo ""if [[ $updated -gt 0 ]]; then+ run_validator || trueinfo "Review changes with ${BOLD}git diff${RESET}, then commit when ready:"echo " git add -A && git commit -m \"Update COG framework to v${uv}\""fidiff --git a/docs/AGENT-SUPPORT.md b/docs/AGENT-SUPPORT.mdnew file mode 100644index 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.jsonindex 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.shnew file mode 100755index 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)"