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.

17.7 KB
Raw Blame

COG Second Brain — Framework Instructions

Opt-in verification harness: WORKFLOW.md · Universal surface: AGENTS.md

Response Style (ALWAYS APPLY, every agent, every deliverable)

Optimize for information gain, not apparent completeness. The failure mode is framework slop: ordinary reasoning dressed as a consulting memo. Full pattern list: .claude/skills/no-ai-slop/SKILL.md § Structural slop.

  • Start with the answer or strongest finding; no introduction announcing how you will answer.
  • Write at 80% ASD-STE100: instructions 20 words max with one instruction each, descriptive sentences 25 words max, paragraphs 6 sentences max, active voice, one term per meaning, noun clusters three words max, keep articles. Technical terms and the writer's own voice in edits stay as they are. Rules: .claude/skills/no-ai-slop/SKILL.md § Controlled-language target. An explanation for someone who did not build the thing opens with an ELI5 paragraph: three sentences, everyday words, one analogy.
  • When the goal is understanding, climb the format ladder: STE prose, then a diagram, then an HTML page, then an explainer video. Use the highest rung the content and medium support, and offer the next rung in one line when it would help. § Output format ladder in the same skill.
  • Never invent named frameworks, gates, layers, pillars, lenses, or numbered taxonomies unless they exist in the source material or the categorization materially simplifies a complex subject.
  • No sections for 1-2 paragraphs; default to continuous prose with occasional descriptive headings.
  • Headings identify subject matter ("Authentication"), never rhetorical function. Banned: "What this is not", "Why this matters", "The key insight", "The real opportunity", "The bottom line", "The deeper point", "The uncomfortable truth".
  • No straw-man contrasts ("It's not X, it's Y", "This isn't about X", "While it may seem...", "Unlike...") unless X is a position someone relevant actually holds.
  • Space proportional to importance and evidence; each paragraph must add evidence, mechanism, example, implication, counterexample, or decision.
  • Compose as finding → evidence → reasoning → decision, not principle → framework → exposition → takeaway.
  • Prefer concrete nouns over abstract labels. Stop when the useful information is exhausted.

Applies to chat answers, reports, briefs, specs, docs, and all subagent outputs.

Verification Harness (opt-in, off by default)

COG ships a V-model verification harness: decompose left (spec then plan), build at the apex, verify right with evidence traced to criterion IDs (AC-n). It does not run unless you ask for it. Ordinary work (notes, briefs, research, drafts, edits) takes no checkpoints, no lane classification, and no evidence ledger.

Three ways to turn it on:

  • By skill. /closed-loop, /ultragoal, /retro, /harvest, /review-cockpit.
  • By phrasing. "Run this through the closed loop", "verify this properly", "track this as an ultragoal", "give me an evidence trail".
  • By profile. Set verification_harness: on in 00-inbox/MY-PROFILE.md frontmatter to make the normal-lane pipeline the default for build tasks. Absent or off means opt-in per request.

Inside a harness run: checkpoints, gate classes, risk lanes, and file homes are in WORKFLOW.md; the build-verify-fix pipeline is in .claude/skills/closed-loop/SKILL.md; multi-session goals are in .claude/skills/ultragoal/SKILL.md. Those documents oblige nothing in a session that never invoked them.

Two of the harness's rules are worth applying whether or not it is on, because they cost nothing:

  • Verification means observing the artifact: curl the URL, screenshot the page, re-fetch the issue, diff the file. Never re-read a worker's own summary of it. Mandatory for external mutations; see § Skill Post-Condition Rule.
  • A worker never grades its own homework. When a fresh pair of eyes is the point (external mutations, auditable claims), the verifier is a separate read-only subagent that receives paths and criteria, never the worker's output.

Visual Verification (ALWAYS APPLY, UI/UX tasks)

Any task that implements or changes a UI/UX flow is not verified by a DOM/selector check. The DOM can be present and the pixels still wrong: overflow, misalignment, clipped text, wrong contrast, broken responsive layout, z-index overlap.

  • Capture visual evidence. Screenshot every meaningful state; record multi-step flows.
  • Actually read the image, then compare against the intended design (mock, spec wireframe, prior state, house style). Name the discrepancy; never declare pass on "element exists."
  • Fix the UI error you spot. This is part of the task, not a follow-up. Re-capture to prove it.
  • Keep the screenshots next to the deliverable. Inside a harness run they are the CP-5 acceptance evidence.

Delegation Cap (ALWAYS APPLY)

Delegation is not free: each subagent re-establishes context, re-explores, and reports back, and the lead then re-reads the report. Delegate when the payoff clearly exceeds that overhead, not by reflex.

  • Don't delegate work the lead can finish in a handful of tool calls.
  • Fan out only for genuinely independent, sizeable tracks: ≥3 unrelated items, a wide multi-source sweep, or parallel workers that would conflict on the same file.
  • If one subagent can do it, use one. Keep spawn counts low.
  • Brief precisely the first time. Avoid launch → wait → re-brief; never redo a subagent's work after it reports.
  • Independent agents launched together go in one message with multiple tool calls so they run concurrently.

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
Read-only verification, harness runs only (acceptance criteria, post-conditions) Sonnet task-verifier
Cross-task integration verify, harness runs only (CP-4) Sonnet integration-verifier
Targeted fixes after verifier FAIL:fixable Sonnet fix-agent
Harvest staging curation (propose-only) Sonnet harvest-curator
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.

Single-File Deliverable Rule — ALWAYS APPLY

The user reviews one file per run. Multi-file outputs (staging files, per-worker dumps, split reports) make review impossible.

  • Default: work in a single file. If the task fits in one file, never split it.
  • Fan-out is allowed mid-run (parallel workers must write separate staging files to avoid conflicts), but the final step always consolidates: one deliverable file with the main content (TL;DR, synthesis, plan) on top, then an ## Appendix — sources section containing each sub-file's content (or a condensed version + link if a sub-file is bulky raw data).
  • After consolidating, delete the staging files. The run folder ends with exactly one file (or zero, if the deliverable lives elsewhere).
  • Never present the user with "see files A, B, C, D" — present one file.

Fresh-Context Isolation — ALWAYS APPLY when fanning out workers

When the orchestrator dispatches multiple workers in parallel, pass each worker ONLY the digested context it needs — never paste a prior worker's raw output into the next worker's prompt. Pasted context induces narrativisation: the worker treats the preamble as "the orchestrator already framed the findings, I just classify them" instead of independently reading the source. Observed failure mode: a 5× speedup coupled with hallucinated findings and mis-cited references.


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.

Citation Verbatim & Verifier Pass — When Accuracy Matters

For skills that produce auditable claims about external sources (Slack threads, tickets, PRs, meeting transcripts — e.g. team-brief, comprehensive-analysis, auto-research), apply two additional disciplines:

  1. Verbatim quote alongside the citation. Every cited reference should carry the actual line text in backticks, not just a link. Pattern: [<short>] (<link>) — \``. If you can't quote the source verbatim, drop the claim — that's the failure mode this discipline prevents.

  2. Opt-in adversarial verifier pass before publishing. For high-stakes briefs/reviews, after the draft is assembled, spawn one worker-data-collector (Sonnet) whose only job is to re-fetch each cited URL and tag every claim Verified | Weakened | Falsified against the verbatim quote. Falsified claims are dropped; Weakened are demoted (e.g. "blocker" → "heads up"). Output contract: CLAIM <id> | <tag> | <one-sentence justification with link>.

This is opt-in per skill — not a hard rule for every output. Apply it where wrongness costs the most.


Engineering Discipline — ALWAYS APPLY

Code Comments

  • Never use decorative comment separator blocks of any kind — // ====, // ----, // ---- Section Name ----, // ----------- full-line dividers, /* ==== Section Name ==== */, etc. Use plain single-line comments and blank lines to separate sections instead.

Git

  • Never git reset --hard or git commit --amend unless the user explicitly asks. Always create new commits and push normally. If changes get wiped, recover from git reflog — do not destroy history.
  • Always commit with commitlint standards (Conventional Commits: type(scope): subject).
  • When a command requires interactive input (e.g. git rebase --continue, editor prompts), supply the non-interactive flag or set GIT_EDITOR=true / EDITOR=true / --no-edit as appropriate.

Pull Requests

  • Before opening a PR, check the repository for a PR template (e.g. .github/PULL_REQUEST_TEMPLATE.md or similar) and always follow it when composing the PR description.
  • PR review replies must be in-thread via gh api repos/{owner}/{repo}/pulls/comments/{id}/replies, never a new parent comment, then resolve the thread via the GraphQL resolveReviewThread mutation. No pleasantries ("great catch", etc.) — state what changed, which commit, and why.

Interaction

  • Read every file the user provides (images, screenshots, code, text) with the read tool before responding — never assume its contents.
  • Answer the user before acting. Explanatory questions should be answered verbally without first invoking tools or editing code. Wait for the user to explicitly request investigation, a fix, or changes.

Skill Post-Condition Rule — ALWAYS APPLY

Every skill run that mutates external state (publishes a page, deploys, posts to Slack/socials, transitions a ticket, pushes commits, fires a webhook) must end with an explicit post-condition check: fetch back or observe the mutated artifact and confirm it matches intent before reporting success.

The failure mode this prevents is confident-but-unchecked: a step returns plausible output that no downstream layer validates. Rules:

  • The check must observe the artifact, not the tool's return value (curl the URL, re-fetch the ticket, screenshot the post).
  • Read-only skills are exempt.
  • If the check fails, report the failure plainly — never report success from the mutation call alone.
  • New skills that mutate external state must include a "Verify" step in their SKILL.md.

Daily Journal (ALWAYS APPLY)

The daily journal is an ambient behavior, not a command. The trigger lives here because it has to be loaded in every session; the procedure lives in the skill (.claude/skills/daily-journal/SKILL.md).

  • After finishing a meaningful unit of work, append one entry to 01-daily/journal/YYYY-MM-DD.md (get the date with date +%F, never guess). Meaningful = shipped or committed something, produced a deliverable, made a decision, changed direction, or hit a notable blocker.
  • Create the file from the skill's template on the first entry of the day. Append only; newest entries at the bottom of the ## Log section.
  • Do NOT log trivial reads, one-line lookups, mid-task scratch work, the journal's own writes, or anything you asked to keep out. Do not announce the write — append and carry on.
  • Read the skill body for the entry format, reflect mode, and the full guardrails before the session's first write.
  • If you say to stop journaling, stop for the rest of the session and do not re-ask.

Integration Preferences

Before using any external integration in a skill, check 00-inbox/MY-INTEGRATIONS.md:

  • Active integrations: Use normally.
  • Disabled integrations: Skip silently. Do not attempt to call their tools, do not suggest setting them up, do not mention them in output.
  • Unknown integrations (not listed in either section): Ask the user if they want to set it up. If they say no, add it to the Disabled section.

Role Packs

COG uses role packs (.claude/roles/*.md) to personalize skill recommendations and integration suggestions per user role.

How role matching works

  1. During onboarding, the user's role text is matched against role_id and aliases in each role pack's YAML frontmatter.
  2. The matched role pack is stored as role_pack in 00-inbox/MY-PROFILE.md frontmatter.
  3. When suggesting skills or workflows, check the user's role_pack and order recommendations by role relevance.

Role-aware behavior

  • Skill suggestions: When a user asks "what can COG do?" or similar, prioritize skills listed in their role pack. Show role-specific explanations from the pack.
  • Integration prompts: When a skill needs an integration the user hasn't set up, check their role pack to provide role-specific context for why it matters.
  • No role pack match: If the user's role doesn't match any pack, recommend core skills (roles: [all]) and let them discover team skills organically.

Available role packs

Role packs live in .claude/roles/. New roles can be added by dropping a file following the _template.md format.

Vault Structure

User configuration files (00-inbox/)

  • MY-PROFILE.md — User info, role pack, agent mode, active projects
  • MY-INTERESTS.md — Topics for daily briefs
  • MY-INTEGRATIONS.md — Active/disabled external service integrations

Professional tracking (03-professional/)

  • COMPETITIVE-WATCHLIST.md — Companies/people being tracked

Framework files (updated via cog-update.sh or /update-cog)

  • .claude/skills/: Claude Code skills (43 skills)
  • .claude/agents/ - Worker and verifier agent definitions (10 agents)
  • .claude/roles/ — Role packs for personalized recommendations
  • .claude/lib/ - Harness helper scripts (checkpoint.sh, lane-classify.sh)
  • .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
  • 02-personal/ — Personal braindumps (private)
  • 03-professional/ — Professional braindumps and strategy
  • 04-projects/ — Per-project tracking
  • 05-knowledge/ — Consolidated insights and patterns