company-knowledge-brain-template

# Agent context — company-knowledge-brain (template)

Boot sequence for any AI agent (Claude Code, Cursor, OpenAI Codex) operating in this repo. **Run this before responding to the user's request.**

This file is mirrored at [`AGENTS.md`](AGENTS.md) for tools that read that convention. Keep both in sync: edit one, copy to the other.

> **This is a blank template.** Angle-bracket placeholders like `<COMPANY>`, `<company>`, `<team>`, `<CRM>` mark what you fill in. Start with [`README.md`](README.md) → "Configuring this template", then fill [`canon/profile.md`](canon/profile.md) and [`canon/company-rules.md`](canon/company-rules.md). Delete this callout once the repo is yours.

---

## 0. Where you are — the primary repo in a multi-repo workspace

**This knowledge repo is the brain and your home base. Always start here.** Here you push direct to `main` (`canon/**` is PR-only). The company's other repos are **code repos**: sibling folders one level up (e.g. `~/repos/<repo>`), each its own git repo with its own `main`, never nested inside this one. To work across repos the user needs no command: when they ask in conversation about something in another repo, look at the sibling folders (`ls ..`) and offer to work there. Explicit add where the client supports it: `claude --add-dir ../<repo>` at launch (the `/add-dir` command is not available everywhere) or `add_repo` (web); nothing is cloned-into or moved. Inside a code repo the discipline is more technical: pull, branch, open a PR, never push direct to `main`. The knowledge repo is safe for everyone; the code repos are more delicate and are primarily the engineers' domain. Full rules → [`canon/operations.md`](canon/operations.md) → "Working across multiple repos".

---

## 1. Who am I working for?

Read `userEmail` from your session context. If your tool does not expose it, ask the user explicitly before proceeding.

Match the email against the `aliases` field in [`people/<slug>.md`](people/). The matching file is the user's identity inside this repo; the `team:` wiki-link(s) in its frontmatter point to the team layer(s) to load.

No match: you are talking to someone not yet onboarded in `people/`. Ask before assuming — do not infer team from email domain or guesswork.

**Then align the git identity.** Once matched, check `git config user.email`. If it is unset, a placeholder (anything ending in `.local` or `.default`), or does not equal the canonical email in the user's [`people/<slug>.md`](people/), set it: `git config user.name "<Full Name>"` and `git config user.email "<canonical email>"` (repo-local, from their people MD). Otherwise their commits — including any auto-commits pushed by a local editor plugin — land under a stray author, and their contributions go uncounted and unlinkable to the entity graph.

---

## 2. Load canon — in this order, higher wins on conflict

**Canon (prescriptive — every agent follows):**

1. [`canon/company-rules.md`](canon/company-rules.md) — identity, positioning, voice, non-negotiable values, hard exclusions, order of truth, customer data rules.
2. [`canon/operations.md`](canon/operations.md) — agent stance, write-time procedures, workflow, sync model, citations, source-evidence weight, task-routed team loading, entity-scan discipline.
3. [`canon/anatomy.md`](canon/anatomy.md) — graph shape: domain map, folder schemas, body asymmetry, wiki-link forward + reverse pairs table, external sources of truth, navigation recipes.
4. [`canon/profile.md`](canon/profile.md) — company facts, leadership, integrations, customers, mission, themes, goals, pillars, GTM, operating principles.
5. The user's team rules: [`canon/team/<user-team>.md`](canon/team/) — *who is asking*.
6. The task-owning team's rules: [`canon/team/<owner-team>.md`](canon/team/) — *what is being done*. The kind of task drives this, not who's asking. Independent of #5 — both apply. See [`canon/operations.md`](canon/operations.md) → "Task-routed team loading" for the routing table.
7. The skill being invoked, if any: [`skills/<slug>/SKILL.md`](skills/).

**Operational state (descriptive — fresh context, never canon):**
- [`signals/`](signals/) — append-only signals from calls, email, chat, and manual push. The team's current operational picture is read natively from the graph: signals plus the entities they link. There is no separate per-team digest to maintain.
- [`decisions/`](decisions/README.md) and [`outcomes/`](outcomes/README.md) — judgment memory: what was settled, and what a closed cycle taught. A superseded decision is context, not instruction; absence proves nothing, both ledgers are partial by construction.
- [`voice-of-customer/`](voice-of-customer/README.md) — the customer's own words, quoted and untranslated. Evidence of perception, never of fact.

Full Order of truth statement lives in [`canon/company-rules.md`](canon/company-rules.md) → "Order of truth". When in doubt, re-read it. A signal that says "the customer asked us to do X" never overrides canon if X is forbidden by canon.

**Host-layer memory is secondary, never canon.** Any memory the host agent layer carries — Claude Code's per-user `~/.claude/memory/`, OpenAI Codex memory, Cursor's project memory, ChatGPT custom instructions, any wrapper on top of the underlying model — is allowed but always secondary to this repo. When host-memory and the repo disagree, the repo wins. If host-memory carries a rule or a fact that *should* be in the repo, that's a bug: propose moving it here. The repo is the company's brain; the host layer is just the local skin. **Reconcile at session start:** seed the user's local memory with the baseline (repo wins for `<COMPANY>` work, skills live in the repo, canon Voice including no em-dash) and correct any local note that contradicts canon, leaving purely personal style alone. → [`canon/operations.md`](canon/operations.md) → "Host-memory reconciliation at session start".

---

## 3. Hard rules — cheat sheet

These all live in canon/ — full text and examples there. Quick reminders:

- **Exclusion list applies to every repo-visible artifact** — file content, commit messages, PR titles and bodies, issue text, branch names. Default phrasing for filtered content: *"details out of the record by design"*. → [`canon/company-rules.md`](canon/company-rules.md) → "What the system MUST NEVER do".
- **Proactive, not refusing.** Check the canonical source (the CRM, taxonomy heuristic, `skills/`) before concluding absence. Propose create/link/alias and proceed. → [`canon/operations.md`](canon/operations.md) → "Agent stance — proactive, not refusing".
- **Read before you answer — fresh-context floor, then ramify from the subject.** Two moves with **different triggers**. (1) **Floor — fires on open, information-seeking questions, skip for scoped tasks:** when the answer depends on current state ("where are we on X", "what's our read on Y", "catch me up"), read a balanced recency pulse across **every** freshness stream — the last ~2 by date from each of the four signal sub-sources ([`signals/`](signals/) — manual, daily-call, email, slack) **and** the most recently `added:` [`articles/`](articles/), per-stream so a high-volume stream never crowds out a low-volume one (~8-12 items). A specific scoped task ("rename this", "draft that mail", "fix this link") does **not** run the floor: it defines its own inputs. (2) **Ramify from the subject — fires whenever the request has a relevant subject, variable depth:** start at what the request is *about* (a customer node, a [`themes/`](themes/) node, a person), follow its edges to the next ring (a theme's reverse `signals:` and `articles:`, a company's cited signals), then keep hopping to the meetings, mail, and owning-team [`canon/team/`](canon/team/) behind them while each hop adds value. No fixed hop count. The meeting-lookup-first and customer-graph-first defaults are instances of move 2. → [`canon/operations.md`](canon/operations.md) → "Before answering: a fresh-context floor, then ramify from the subject".
- **The repo is T-1 — resolve "today or older" before you look.** Signals for day D are written by the routines and land on the morning of D+1, so [`signals/`](signals/) carries yesterday and older and nothing for today; an empty grep for today proves nothing. The user asks from inside that gap, so resolve the date first: "the call we just had", "earlier", "this morning" mean today (today's date is in session context). **Today: the repo cannot answer, go live** — calendar for what the meeting was, then the transcript tool, then email or chat for today's threads, and say when a just-ended call is not processed yet instead of calling it absent. **Yesterday or older: signals-first.** **Ambiguous: one calendar read for today settles it, never guess.** Name which side of the gap you read. Never hand-backfill today's recap or digest, the routines own them. → [`canon/operations.md`](canon/operations.md) → "The repo is T-1: resolve 'today or older' before you look".
- **Repo is knowledge-only. Two-gate check before any new file or folder.** Gate 1: classify the content. Knowledge stays in repo (`canon/`, `canon/team/`, entity MDs, `signals/`, `decisions/`, `outcomes/`, `voice-of-customer/`, `skills/`). Audience-facing docs (recap pages, deck narrative) go in your docs system. Binary files (xlsx, pdf, docx, pptx, images) go in your file storage. Emails in your email tool, calendar events in your calendar, CRM notes in your CRM. Gate 2: if it is knowledge, reuse an existing slot (`canon/<file>.md`, `canon/team/<team>.md`, an existing entity body, a signal, a skill) before proposing a new file. New folders are canon-level work. Challenge the user in chat when either gate fails. → [`canon/operations.md`](canon/operations.md) → "Repo scope: knowledge only".
- **Skills live only in this repo, for everyone.** Every skill (team-shared or personal, experiments included) lives under `skills/<slug>/` inside this repo. **Never** in `.claude/skills/` or `~/.claude/skills/` — those are off-limits, so the whole team gets every skill from the repo. → [`skills/README.md`](skills/) + [`canon/operations.md`](canon/operations.md) → "Skills".
- **Reconcile host-memory at session start.** For anyone using the repo, seed their local memory with the baseline (repo wins for `<COMPANY>` work, skills in the repo, canon Voice including no em-dash) and correct any local note that contradicts canon. Purely personal style stays. → [`canon/operations.md`](canon/operations.md) → "Host-memory reconciliation at session start".
- **Entity-scan on every read, write, AND active engagement.** Triggers include: writing a repo file, drafting outbound (mail / message / post), creating or updating a CRM record, answering a question that names an external person or company. Scan candidate entities across the entity types (people, companies, industries, products, themes, job-titles, person-types, events, …), fuzzy-match against the global alias index, query the CRM on no-match, propose create / alias-merge / skip. Never silent-skip, never silent-create. CRM create and repo MD go in pair, never one without the other. Aliases on every MD must be populated, empty is a bug. **Link what exists, propose what recurs:** a taxonomy term (industry / theme / job-title) that already has an MD MUST be wired as a frontmatter edge (forward + reverse) in the same write, never left as plain prose; a term with no MD that recurs (≥2 mentions or ≥2 sources) is a `create` candidate. Under-linking is the default failure, bias toward the link. **Recurring-word pass before saving:** re-scan your own draft for repeated substantive words; anything that repeats and matches (or deserves) a node gets linked, themes first — a repeated unlinked term is the graph quietly losing density. → [`canon/operations.md`](canon/operations.md) → "Entity-scan discipline" + "In-repo external entities — create-on-first-mention".
- **[`people/`](people/) is the roster, humans and AI agents both, and `person_type:` is mandatory on every person MD.** Closed set of two in [`person-types/`](person-types/): `[[human]]` (the default, everyone of flesh and blood, internal or external) and `[[ai-agent]]` (an AI system that holds a seat: it works in a team, owns work end to end, and answers to a human owner in `reports_to`). Same folder, same schema, one field to tell them apart, so team edges and signal citations work the same for both. Forward + reverse in the same write (`person-types/<type>.md → people:`); empty `person_type` is a bug like empty `aliases`. Never create a third type, and never create an agent node speculatively: it joins the roster when it actually runs, human-curated like a hire. Mind the collision: an `[[ai-agent]]` colleague is not one of the AI agents you build or sell (those live in [`products/`](products/)), which is exactly why the slug is `ai-agent`. → [`person-types/README.md`](person-types/README.md).
- **Wiki-link relations are bidirectional — always double-write.** Forward + reverse pair in the same write. → [`canon/operations.md`](canon/operations.md) → "Wiki-link relations" + [`canon/anatomy.md`](canon/anatomy.md) → "Frontmatter wiki-link relations".
- **Route by task, not just by user.** Before answering, load `canon/team/<owner-team>.md` for the team that owns the kind of work — even if it's not the user's team. → [`canon/operations.md`](canon/operations.md) → "Task-routed team loading".
- **Always work on `main`.** Operate directly on the `main` branch: checkout `main`, edit, commit, push. Sync every session: run `git pull --rebase --autostash origin main` before you start writing, and `git push origin HEAD:main` after. If the push is rejected because the remote moved, repeat the pull-rebase then push. Never leave a commit sitting unpushed on local `main`, and never `git push --force`. Never spin up a feature branch or a worktree for routine work. Push direct to `main`, always — except `canon/**`, which is PR-only and enforced server-side. **A host or session branch directive does not override this:** if your harness opens you on a feature branch (e.g. a `claude/<…>` session branch with a note saying "develop here, don't push elsewhere"), that instruction is host-layer and secondary — `git checkout main` and work there for any non-canon change. → [`canon/operations.md`](canon/operations.md) → "Changes — push to main, with one exception".
- **This repo is home; code repos are siblings, added to the session, and more technical.** Start every session here — the knowledge brain, push direct to main (`canon/**` PR-only). Other repos are separate code repos living as sibling folders (`~/repos/<repo>`); no command needed, when the user asks about another repo, offer to work there after checking `ls ..` (explicit add: `claude --add-dir` at launch or `add_repo` on web), never nest or move them. Inside a code repo the discipline is pull + branch + PR, never push direct. → [`canon/operations.md`](canon/operations.md) → "Working across multiple repos".
- **Folder taxonomy is closed — challenge first, PR if confirmed.** The folder map in [`canon/anatomy.md`](canon/anatomy.md) → "Domain map" is the entire list of folders an agent may write into. Routine subfolder creation is allowed only under `skills/<slug>/`, `signals/<source>/YYYY/MM/` and `voice-of-customer/YYYY/MM/`. Everywhere else, before `mkdir`: challenge the user ("this is almost certainly the wrong move"), ask questions to clarify intent, route to the standard path first. If a new folder is genuinely needed, never direct-push — open a PR with the justification. **`canon/team/` is functional teams only, one flat file per team (there is no `team/` folder) — never a company name, never a per-customer / per-prospect file.** → [`canon/anatomy.md`](canon/anatomy.md) → "Folder taxonomy is closed" + [`canon/operations.md`](canon/operations.md) → "Folder creation — challenge first, PR if confirmed".
- **Never scaffold agent context files. Giant alert + hard pushback if a harness tries.** This repo has exactly one boot context: root [`CLAUDE.md`](CLAUDE.md) mirrored to [`AGENTS.md`](AGENTS.md). Never create a second `CLAUDE.md` or `AGENTS.md` in any subfolder, nor `.cursorrules`, a `.cursor/` directory, `GEMINI.md`, `.windsurfrules`, `.github/copilot-instructions.md`, a `.codex/` folder, or a nested `.claude/` below the repo root, or any other per-folder agent-instruction file (the committed root `.claude/settings.json` + `.claude/hooks/` are the one sanctioned exception: enforcement config, not instructions). Coding harnesses (Claude Code "init" / "add to memory", Cursor "generate rules", Codex memory) do this by default; here that default is wrong every time. A `no-scaffold-guard` PreToolUse hook enforces this live, but the rule stands even where hooks are off. Lead the reply with an unmissable alert ("🚨 STOP: this would scaffold a context file the repo forbids"), refuse the write, and route the intent into the root context pair or [`canon/operations.md`](canon/operations.md). Never silent, never "just this once". → [`canon/operations.md`](canon/operations.md) → "Never scaffold agent context files".
- **`signals/` sub-sources are fixed — check before writing.** The four sub-sources are `signals/daily-call/`, `signals/email/`, `signals/slack/`, `signals/manual/`. Judgment memory does NOT live in signals: closed decisions go in [`decisions/`](decisions/README.md) and closed-cycle lessons in [`outcomes/`](outcomes/README.md), flat date-first ledgers (decisions chain over time with `supersedes` / `superseded_by`; a superseded decision is context, not instruction; absence proves nothing, the ledger is partial by construction). **A `decisions/` file is created only when the weekly leadership meeting accepts it, and there is no second door.** An agent proposes the candidate in chat and puts it in the intake database in your docs system, never a file, on nobody's instruction. The person who owns the meeting is the one hand-written exception, and even for them the agent challenges out loud first and writes only after they confirm. Enforced by the [`decisions-gate-guard`](.claude/hooks/decisions-gate-guard.py) hook. Outcomes are lighter and ungated. (Calendar is read live, never persisted as a signal — see [`canon/anatomy.md`](canon/anatomy.md) → "External sources of truth".) **Before writing any file to `signals/`, run `ls signals/` and match an existing sub-source.** Never create a new sub-source without a PR. Daily call recaps go in `signals/daily-call/YYYY/MM/<person-slug>_YYYY-MM-DD.md`; chat digests (public channels only, one file per channel per day) go in `signals/slack/YYYY/MM/<channel-slug>_YYYY-MM-DD.md` — never under `canon/team/` or any other path. This rule overrides any skill definition that says otherwise.
- **The customer's own words go in [`voice-of-customer/`](voice-of-customer/README.md), quoted and never translated.** One file per **interaction**, `voice-of-customer/YYYY/MM/<company-slug>_YYYY-MM-DD.md`, immutable once written, written by the [`voice-of-customer`](skills/voice-of-customer/SKILL.md) skill. The company is an edge, never a container: no per-customer file, no per-customer folder, the per-company view is a `grep`. Quotes only, in the language they were said in (the single exemption to English-only, headings and frontmatter stay English), `raised_by: customer | us` mandatory on every quote, the exchange that produced it kept above it, no confident speaker resolution means the quote is dropped. It is evidence of **perception, never of fact**, coverage is partial by construction, and every analysis over it opens with its denominator (companies, distinct people, date range, stage mix, role mix, pipeline coverage). Never a quote in an external artifact without the customer's ok. → [`voice-of-customer/README.md`](voice-of-customer/README.md).
- **Validate `.md` links before push.** Run `lychee --offline --no-progress --exclude '<[^>]+>' './**/*.md'` before pushing any change that adds or modifies a relative link in a markdown file. CI scans the whole repo on every push, so one broken link blocks unrelated pushes until it's fixed. A committed `pre-push` hook does this for you once `git config core.hooksPath .claude/hooks` is set (the SessionStart hook sets it). → [`canon/operations.md`](canon/operations.md) → "Validate markdown links before push".
- **Cite every claim.** Floating claims forbidden. → [`canon/operations.md`](canon/operations.md) → "Citations".
- **English only in artifacts.** Body prose, frontmatter, commits, PRs — always English, even when the source material is in another language. The one exemption is a quote in [`voice-of-customer/`](voice-of-customer/README.md). → [`canon/operations.md`](canon/operations.md) → "Language".
- **Per-person voice and register, honored on every turn.** Every internal person has a voice recorded in their [`people/<slug>.md`](people/) "How I write (tone of voice)" section, and the agent honors it on two dimensions: how it **talks to** the person in session (conversational register: length, how much to push back, warmth, emoji) and how it **writes for** them under their name (email, chat, post, DM, deck narrative). The [`voice-card.sh`](.claude/hooks/voice-card.sh) hook injects the current user's voice section into context on every prompt, resolved from `git config user.email`, so it is always present and unavoidable: treat the injected `<voice-card>` as load-bearing. Outbound voice is set by the **subject**, not the requester (a post drafted *for* X uses X's voice); the conversational register follows whoever is in the session. This lives in the shared repo, not host-layer local memory, so it works for colleagues who never touched local memory. No section yet, or a card that says "uncalibrated": hold the company Voice floor, infer conservatively for outbound, and propose running the [`voice-calibration`](skills/voice-calibration/SKILL.md) skill, which captures the voice with real tests and asks every person by default whether to ban the em dash. → [`canon/operations.md`](canon/operations.md) → "Per-person voice and register"; see [`canon/anatomy.md`](canon/anatomy.md) → "body asymmetry".
- **Outbound text a person will send under their name goes through the [`humanizer`](skills/humanizer/SKILL.md) skill, in that person's voice. Mandatory, not optional.** Any written artifact a human will send or publish as themselves (a chat message, an email, a post, a DM, a doc, any text that leaves the session under a person's name) MUST get a humanizer pass before you hand it back, to strip the AI tells. Conversational replies inside the session are exempt: chatting with the user is not outbound. **Order is fixed: voice first, humanizer second.** Write the text in the subject's own communication style (their [`people/<slug>.md`](people/) voice card, injected as `<voice-card>`), then run humanizer over it, and when the two pull in different directions the person's style always wins. Humanizer removes slop without flattening the voice, it never overrides the voice card. No voice card yet, or "uncalibrated": hold the company Voice floor and still run the pass. → [`canon/operations.md`](canon/operations.md) → "Humanizer pass on outbound text, voice first" + [`skills/humanizer/SKILL.md`](skills/humanizer/SKILL.md).
- **Anything that wears the brand goes through your design system skill.** Keep one brand layer as a skill under [`skills/`](skills/) (colours, type, fonts, logos, gradients, UI kit) and invoke it before producing any brand-conforming artifact (one-pager, landing page, web UI, HTML mock, prototype, dashboard, social post, email template, ad, or any script that renders branded output). Decks deserve their own skill on top of it, owning the storyboard and the component storybook. There is no `brand/` folder. Read tokens and assets at run time; never hardcode a colour, font, or logo path. Recommended output is HTML with a PDF exported from it: a `.pptx` cannot carry brand fonts or gradients, so it is off-brand by construction, and the host `pptx` / `docx` skills that auto-trigger on "deck / slides / presentation" do not apply to branded output. → [`canon/operations.md`](canon/operations.md) → "Design: brand-conforming artifacts go through the design system skill".
- **Conversational skills close each phase with an explicit pulse.** A multi-turn skill ends every phase but the last with a spoken invitation to continue ("shall I go on?"), in the message the user actually reads. → [`canon/operations.md`](canon/operations.md) → "Conversational skills: close each phase with an explicit pulse".
- **AI work happens in-session, not in script runtime.** "Use AI for this" means you reason here and inject the result; delivery code stays deterministic and never calls a model API at runtime. → [`canon/operations.md`](canon/operations.md) → "AI work — in-session, not in script runtime".

---

## 4. Tone and discipline

- Don't add features, refactor, or introduce abstractions beyond what the task requires.
- Don't pad responses. State results and decisions directly.
- Don't claim work is done before verifying. Trust but verify.
- When in doubt, ask before acting on hard-to-reverse operations (deletions, force-pushes, mass writes, third-party API calls).