What actually lives in GitHub

Code, content, and the rules for both

The private GitHub Brain owns shared knowledge. Application code remains in its own repository. This tab displays selected teaching content from a recorded Brain revision; private goals and agent notes are excluded.

GitHub Code

Runs. Reviewed as a diff. Built and deployed by Netlify.

The part of the repo a computer executes — the actual website.

site/src/The React app: routes, components, and the data behind every tab.
site/scripts/sync-brain.pyExports the exact reviewed teaching selection from private GitHub Brain.
site/vite.config.tsPrerenders every route to plain HTML at build time — the list of pages lives here.
netlify.tomlTells Netlify to build site/ and publish dist/client. Overrides the dashboard UI.

GitHub Content

Read by agents as instructions. Never executed.

The part of the repo written for a person or an agent to read — the values and the playbook.

AGENTS.mdHow every agent should read this repository — the first file, every session.
architecture.md, org-roster.md, bots.md, security.mdThe map, the named-agent org, the Grok Bot roster, and the risk register, as text.
routines/*.mdOne file per cadence job — what it reads, what it must not do.
github-brain/governance/Principles, standards, and guides. This is where the governance paperwork and the logic actually sits — vendored into the site as a stamped, read-only copy.

Methods: how a document is updated

Every document in the governance repo — and, by the same convention, the core files in this brain — opens with frontmatter carrying an identity, so an agent cites an exact document and version instead of a paraphrase. This is the actual rule an instruction file points to when it says "cite by id."

Frontmatter fields

id: Stable, never reused, never renamed. Cited instead of a file path, because paths move and ids don't.
title: Human-readable name.
status: draft (read for direction, does not bind) → active (binds any project that references it) → superseded (kept in place, status changed, supersedes set on the replacement).
version: Semver. Bumped on every change to an active document.
updated: The date of the last change.
supersedes: The ids this document replaces, if any.
applies_to: Which projects, languages, or agent roles it binds. Empty means all.

Version bump

patch: Wording that doesn't change what's required.
minor: A new or relaxed requirement.
major: Anything that would make previously compliant work non-compliant. The one worth announcing to every project that references it.

Lifecycle

draft may be read for direction but does not bind → active binds any project that references it → superseded stays in place, with supersedes set on the replacement, so old work stays interpretable and citations don't break.

Commit message shape

A substantive commit carries the reasoning, not just the diff — see Git as a Thinking Record.

1. GOAL
What the work was trying to achieve, stated so a reader who wasn't there can follow it.
2. OBSTACLE
What got in the way — the constraint, the evidence, the tension. Specific, not "it was harder than expected."
3. DECISION
What was chosen, what was rejected, and why the alternatives lost.
4. PRINCIPLE
Which governance principle carried the weight, especially where two pulled against each other.
5. CONSEQUENCE
What's now settled, what's now open, what needs revisiting because of this.

Read the content

Every core and routine file in this repository, read straight from GitHub — plus the full governance index below.

Core

Routines

Content · brain

Agent reading conventions

AGENTS.md

How every agent should read this repository: the brain is source of truth, wires match data, humans hold the gates, and when std-grokbot-connectors changes in governance this repo's map must be copied in the same sitting.

The private GitHub Brain is authoritative for shared knowledge. Authorized agents load its startup instructions and only the relevant role and topic files at a fresh source revision. The public website is a deliberately selected teaching view, not the full private repository.

Todoist owns task state; Calendar owns commitments and availability. Drive is a stamped reading copy of selected Brain content. A repository file does not install a runtime schedule or confer tool permissions.

Keep secrets, personal goals, private notes, recordings and private identifiers out of public exports. Proposals and historical observations are distinct from approved decisions.

Every reference document, one index

What an instruction file should actually point an agent at — across both repositories.

Document	Repo	Kind	What it's for
How I Do It — Playbook	github-brain	Content · brain	The front door: what this repo is, the stack, the cadence table, and which files exist for whom.
Agent reading conventions	github-brain	Content · brain	How every agent should read this repository: the brain is source of truth, wires match data, humans hold the gates, and when std-grokbot-connectors changes in governance this repo's map must be copied in the same sitting.
Architecture	github-brain	Content · brain	The living map as text — nodes, edges, connection types, and the flows that light them up. The Map tab is built from the same model.
Org roster	github-brain	Content · brain	Named agents, nine team floors, and the Salim stop gates. Karen EA is floor lead in every channel. The Org tab is built from this file.
Roster — jobs, not companies	github-brain	Content · brain	The roster: jobs, not companies. One Grok Bot product can hold many schedules; the split is tools and prompts, not separate accounts.
Security of this loop	github-brain	Content · brain	OWASP's agentic-app risks mapped onto this specific loop: what could go wrong on each wire, and the guardrail already in place.
90-day goal cascade	github-brain	Content · routine	A quarter only works if the week serves it. Finisher technique: one primary 90-day goal, then cascade.
Evening done list	github-brain	Content · routine	End on what happened. Leftovers go back into staging or tomorrow — they do not float.
Friday reflection	github-brain	Content · routine	The reflection layer. Themes from the week’s recordings become next week’s material.
GitHub → Drive instruction sync	github-brain	Content · routine	Agents work in Git. Humans (and other bots) read Drive. The copy is stamped so it cannot quietly diverge.
Inkbox secretary	github-brain	Content · routine	A secretary may propose times. Booking waits for a human choice. The domain is allowlisted. Inkbox is the agent’s public identity — not your personal inbox.
Midday check-in	github-brain	Content · routine	Catch procrastination before the afternoon disappears.
Monday weekly goals	github-brain	Content · routine	One dated document per week. 1–3 goals, not fifteen.
Ship the public playbook	github-brain	Content · routine	The site is a teaching view. Code travels on git. The domain name travels on DNS. Mixing those wires is how a secret lands on the public internet, or how a stolen registrar steals the name.
Speak and listen	github-brain	Content · routine	Three different voice jobs. Mixing them up is how a hallway recording becomes a sent text.
Weekday morning plan	github-brain	Content · routine	Nothing from a recording goes straight onto the main list. Staging first, then a short spoken triage, then named time.
A decision-making framework for agents	github-brain	Content · principle	Thirteen principles, the tensions between them, and how an agent names the one that governed each decision.
Git as a Thinking Record	github-brain	Content · principle	Commit at decisions, carry the reasoning in the message, record what was rejected, never rewrite history.
Security Audit Agent Instructions	github-brain	Content · standard	Paste into a fresh session: an independent auditor that reports, ranks, and refuses to soften findings.
Supabase Security Checklist	github-brain	Content · standard	Row-level security on every table, keys only where they belong, every privileged action re-checked server-side.
Web Stack Architecture, Components and Costs	github-brain	Content · standard	GoDaddy, Cloudflare, GitHub, Netlify, Supabase: one job each, where the security boundaries sit, and what it costs.
Claude Code: Setup and First Project	github-brain	Content · guide	From a blank Mac to a first governance repository on GitHub, one terminal command at a time.
Fix for npm EACCES Permission Error	github-brain	Content · guide	Point npm at a folder you own instead of reaching for sudo.
VS Code: Install and Connect Claude Code	github-brain	Content · guide	Install VS Code, fix the PATH step everyone skips, and connect the Claude Code extension for inline diffs.