Start here — reading and amending the KB
Onboarding — reading and amending the KB
This is the front door. Read this first, whether you are human or an AI agent.
What this is
The company knowledge base: every pattern, component, infrastructure choice, DSL element, copy rule, decision, audience fact, regulation decode, market analysis, and framework idea in one git-canonical repo. Humans write markdown; scripts/compile.py projects it to machine/*.dsl; AI agents read only the projections and cite entries as kb:<id>.
Reading (published site)
- Site: https://kb-site-64r.pages.dev — behind Cloudflare Access (Google login; allow-listed emails only).
- The index lists every entry grouped by type; each entry page renders the full markdown.
- Agents: read
machine/index.dslfirst, then only themachine/<type>.dslfiles the task needs, then the full doc. Never read the whole repo.
Amending (the only write path)
All changes arrive via pull request — never push to the default branch (SEC-02). The workflow:
- Clone the repo; read
AGENTS.md,SPEC.md,types.dsl. - Search
machine/index.dsl— amend an existing entry rather than duplicating. - Pick the directory matching the type (directory name = type name). Never invent one.
- Read
instructions/ai/<type>.mdand followtemplates/<type>.md. - One entry per file; file name = entry id; flat frontmatter (
id, type, title, status, owner, updated+ optionalrelates, uses). - Never include secrets (SEC-01) — the compiler rejects them.
- Run
python3 scripts/compile.pyin the same commit as the content change.machine/is generated — never hand-edit it. - Verify:
python3 scripts/compile.py --checkand the unit tests. - Open a PR; CI runs the drift gate.
The installable agent skill skills/knowledge-base/SKILL.md encodes this exact workflow for Claude Code / Cursor / Devin.
Install the agent skills
Skills live in skills/<name>/SKILL.md in this repo. Install by copying the skill folder into your agent's skills directory (e.g. .agents/skills/ in a project, or your agent's global skills path):
# from a clone of this repo
cp -r skills/knowledge-base skills/learner-retro .agents/skills/Or from the zip: unzip and place each folder so <skills-dir>/knowledge-base/SKILL.md and <skills-dir>/learner-retro/SKILL.md exist.
| skill | use |
|---|---|
knowledge-base | author or amend KB entries — enforces the compile gate and PR-only workflow |
learner-retro | extract learnings (rules, acceptance criteria, DoD gaps) from finished work into KB entries, high-level to detailed |
Type map
| type | dir | use for |
|---|---|---|
| onboarding | onboarding/ | front-door guides (this entry) |
| industry | industry/ | segment-specific knowledge (regulatory landscape, buyer, GTM) |
| factory | factory/ | monorepo system topics (pipeline, harness, infra seams) |
| product | product/ | product commitments: ACs, pricing, beat-market, notify-market |
| pattern | patterns/ | UI layout archetypes |
| component | components/ | reusable UI components |
| infrastructure | infrastructure/ | infra/tooling with configs |
| dsl | dsl/ | DSL language elements (qform/qapp/flow) |
| copy | copy/ | copy/text guidance per channel |
| decision | decisions/ | architecture/product decisions |
| context | context/ | brand voice, audiences, product facts |
| regulation | regulations/ | decoded instruments, traceable criteria |
| market | market/ | competitor/pricing/positioning analyses |
| framework | frameworks/ | reusable architecture ideas from shipped code |
| skills | skills/ | agent-skill catalog: triggers, contract, version, install |
| instructions | instructions/ | meta-docs about the KB itself |
Sources
- AGENTS.md, SPEC.md (v1.9), types.dsl, skills/knowledge-base/SKILL.md
- decisions/edge-via-seam.md (publishing architecture)
- factory/infra/cloudflare/kb-site/ (Terraform: Pages project, Access wall, R2 bucket)