Imported from wtulloch/kb-base (
AGENTS.md). Install upstream withnpx skills add wtulloch/kb-base. Copyright stays with the author.
Engagement Knowledge Base
This repository is a filesystem knowledge base for a single engagement. It aggregates the people, systems, decisions, events, and artefacts of the engagement into one linked, token-efficient store an agent can reconstruct the full picture from.
Engagement-specific facts (what this engagement is, who the customer is, the goals, scope,
and timeline) do not live in this file. They live in 00-project/ as entity files. To stand
up a new knowledge base, run the initialise-knowledge-base
skill, which interviews you and generates those files. See README.md for the spin-up flow.
Project Operating Principle
Minimum Description Length. Encode the engagement so an agent reconstructs the full picture from the smallest number of tokens. Entities are the codebook (each fact described once). Events and cross-references are pointers. Every rule below (stable slugs, datetime-prefixed events, link-don't-restate, tables over repeated Label: value, no decorative markdown) exists to shorten the encoding without losing a fact.
Definitions
Event: something that happens at a point in time. Entity: something that exists over a period of time, with properties that may change. People, teams, systems, domain concepts, and the project itself are all entities.
Understanding the Core Model of the Filesystem Knowledge-Base
- Entities: long-lived nouns (a person, a team, a system, a domain concept, the project itself). One canonical file per entity, edited in place over time. Filename is a stable slug that never changes (e.g.
people/<group-or-team>/<firstname>-<lastname>.md,systems/<system-name>.md). - Events: point-in-time happenings (a meeting, an email, a chat, a status update, a deck version). Append-only, never rewritten after the fact. Filename is datetime-prefixed
YYYYMMDD-HHMM-<slug>.mdso lexicographic sort matches chronological order. - Links: how entities and events connect. Event → Entity (always; this is how DRY is enforced). Entity → Entity for relationships. Relative markdown only:
[text](relative/path.md). Never wiki-links.
Philosophy
- DRY is enforced by making entities the only place facts live. Events link to entities rather than restating them. If you find yourself describing a person inside a meeting note, stop, that belongs in the person's entity file and the meeting note links to it.
- Token efficiency. No
**bold**, no decorative markdown. Plain prose, dashes, code fences. Avoid filler and restated context. - No em-dashes, ever. Use commas, full stops, parentheses, or rewrite.
- One fact, one home. Never duplicate a fact between two files. Link to the canonical entity.
- Entity slugs are stable once verified:
firstname-lastnamefor people,kebab-casefor teams, systems, and concepts. If an early capture is wrong, apply a one-time correction and record it in the related event. - No abbreviations in slugs. All file and directory slugs use full descriptive words.
ai-foundry-methodnotafm,design-thinkingnotdt. The slug should convey the content's identity without opening the file. - Events are append-only and datetime-prefixed:
YYYYMMDD-HHMM-<slug>.md. Use-0000when the exact time is unknown. Do not rewrite history. When source artefacts exist, events may use folder shapeYYYYMMDD-HHMM-<slug>/with source and derived files inside. - No wiki-links. Relative markdown links only (direction rules live in the core model above).
- No spaces in filenames for authored content. Use hyphens. Raw source files (PDFs, DOCX, images) retain their original filenames.
- No catch-all files (INBOX.md, TRIAGE.md, FUNNEL.md). New content lands directly in its semantically correct location. If the correct destination is unclear, ask. Directories are not scaffolded ahead of use; create a directory only when its first real file lands.
- Never invent information. Only restate, rearrange, or link facts that exist in the source. If unsure about a fact, ask.
- The result of change in an entity is a direct relationship from event. If an event occurs, an entity is created or updated, and the event links to the entity. If an entity changes as a result of an event, link the event to the updated entity and update the entity file in place. Never create a new entity file for an existing entity.
- Events carry frontmatter.
datealways.attendees:for synchronous events.source:(durable URL preferred) andsource-type:when the content was captured upstream. Allowedsource-type:values areloop,email,teams-chat,copilot-recap,transcript,file,external-tool,agent-interview. Optional provenance fields arelocal-source:,source-system:,source-access-tool:,source-locator:,last-verified:,internet-message-id:,sender:,sent-at:,subject:. Communication events may includedeliverables:to link canonical artefacts andvisibility:to declare sharing scope. - Channels classify by medium, not authoring tool. A Loop page that recaps a meeting is a meeting event with the Loop URL in
source:. Reservecommunication-channels/loop/for Loop pages that are the atomic artifact (no upstream meeting or email). meetings/covers every synchronous verbal exchange, formal or informal, customer-facing or internal. Slug carries the flavour (-demo,-catch-up,-walkthrough,-workshop,-interview,-prep-sync). Nocustomer-conversations/orconversations/subchannel.- For WorkIQ-derived email events, keep
source-type: emailand setsource:to the mailbox URL used by the capturer when available. - Treat mailbox URLs as user-scoped convenience links. The Outlook ItemID in
source:is not a cross-user stable identifier and may differ across recipients. - For cross-user stable provenance on email events, include
internet-message-id:when available. Addsender:,sent-at:, andsubject:when needed for human verification. - Use source preservation Pattern A/B/C. Pattern A: source stored locally beside the event in
source/. Pattern B: external source with local copy, store bothsource:andlocal-source:. Pattern C: external source without local copy, store durable locator metadata (source-system:,source-access-tool:,source-locator:,last-verified:). Never create fake local sources. 08-deliverables/is the canonical home for artefacts. Communication events in06-communication-channels/link to artefacts throughdeliverables:and do not restate artefact content.tmp/is staging only. After ingestion, move artefacts to event-localsource/orsource-docs/.- KB layering precedence is narrowest to broadest: engagement, customer, studio, wider organisation. If a narrower-scope write contradicts a broader fact, confirm with the user before persisting.
- External search policy is engagement-specific and declared in
00-project/project.md. Local KB sources are preferred before broad external search unless the policy states otherwise. - Source freshness is explicit. If a source may be stale, warn inline and offer refresh in the same turn.
- Visibility is explicit for shared artefacts and events. Use tiers: engagement team, account technical case-by-case, studio leadership, wider organisation index-only, partners sanitised, customer sanitised/reviewed.
00-project/terminology.mdis the canonical glossary. When using or encountering engagement-specific terminology, consult this file first. When a new term is discovered or an existing definition is clarified through events, update the glossary in place. Terms that have a standalone entity file in04-concepts/or03-systems/link from the glossary row to that entity rather than restating the definition.- Bilingual content is optional and language-agnostic. When an engagement needs paired-language files, emit a linked pair
<slug>-<lang-a>.md/<slug>-<lang-b>.md(for events,YYYYMMDD-HHMM-<slug>-<lang>.md), each carryinglanguage:andpair:frontmatter pointing at its counterpart. The-Bilingualswitch onscripts/new-event.ps1andscripts/new-entity.ps1scaffolds such a pair.
Information Sources
Registry of live channels agents may draw on in addition to artefacts already in the KB. Append new rows as sources come online. Persistence of any captured-relevant content follows rule 13 (frontmatter), rule 14 (medium classification), and rule 19 (source preservation patterns).
| Source | Kind | URL | KB destination when relevant |
|---|
Relevance handling for these sources:
- Mixed content is expected. A team chat channel carries project signal (decisions, status, links, plans, file shares, action items) alongside banter, social chat, gifs, and unrelated tangents. Neither relevance nor irrelevance is the default.
- Ask, do not assume. When a message or thread could plausibly belong in the KB and the call is not obvious, ask the user before capturing. Err toward asking rather than guessing in either direction.
- Once judged relevant, capture per the destination column above and the rules it references. Do not restate channel chatter; link the permalink and summarise only what the engagement needs.
Skills
Reusable cognitive workflows live in .github/skills/<name>/SKILL.md.
| Skill | Purpose | Triggers |
|---|---|---|
| initialise-knowledge-base | Interview the user and generate a customised KB (00-project seeds, .env, friction log) |
"set up a new knowledge base", "initialise the KB", "spin up a KB" |
| conversation-insights | Analyse session and conversations/ history; propose new CLI recipes, skills, agents, or AGENTS.md rules |
"review the workflow", "what should we automate" |
| friction-analysis | Categorise and fix entries in friction/friction.jsonl; evolve the CLI and council |
"analyse friction", "fix the friction log" |
| open-questions | Add and manage engagement open questions | "add the following question", "something I need to ask" |
Friction and continuous improvement
The KB self-improves through a friction loop. Friction is anything that costs extra effort during KB work: failed or awkward ingestion, agent council gaps, git/PR-flow problems, missing CLI recipes, unclear rules, stale sources, or repeated manual steps.
- When friction occurs, append one JSON line to
friction/friction.jsonl(usejust friction-log <step> <category> <title> <error> <fix>). Schema:timestamp(ISO-8601),step,category(one ofingestion|agent|git|pr|cli|docs|other),title,error(or null),fix_applied(or null),suggested_improvement(or null). - If a routine operation has no
justrecipe, log it as friction with categorycliand propose a recipe. - Run the friction-analysis skill periodically to categorise, find patterns, and fix systemic items by editing the
justfile,scripts/, agents, or this file. Fixes append atype: resolutionline. - Capture notable sessions with
just conversation, then run conversation-insights to turn pain points into tooling. - After any major task, offer to kick off a conversation analysis (conversation-insights) to capture friction and propose tooling. Do not run it unprompted; ask, and proceed only on confirmation.
CLI (justfile)
justfile at the repo root used for routine, deterministic operations. Run just to list recipes. Requires just and PowerShell 7 (pwsh, cross-platform: Windows, Linux, macOS). Engagement-specific config (git repo name, ADO org URI) is read from .env (copy .env.example). Key recipes: init (point at the initialise skill / scaffold .env), meeting|email|teams-chat <slug> and event <channel> <slug> (scaffold rule-7 events), entity <folder> <slug> (scaffold an entity), conversation (session record), friction-log|friction-show|friction-stats, spell (cspell), branch <purpose> <slug>, pr "title" "summary", pr-complete <id>, ship <purpose> <slug> "title" "summary" (full PR flow), sync, ado-comment <id> <htmlfile>, ado-status-files, tracker-log <file> <since>. PR recipes use az repos. Prefer recipes over ad-hoc commands; gaps are logged as friction.
Layout
Target shape the KB grows into. Entity paths (stable slugs) are fixed; event paths under communication-channels/, design-thinking/, deliverables/ follow the YYYYMMDD-HHMM-<slug>.md rule. Directories are not scaffolded ahead of use.
Markdown files inside the subfolders contain frontmatter describing their content and their use. Samples of files that might appear in folders are included in the structure below. Do not limit to this structure - suggest and implement additional folders as required.
/
00-project/ ← the engagement itself as an entity (generated by the initialise skill)
project.md ← the engagement entity: name, purpose, about the customer, external search policy
business-drivers.md ← why the engagement exists, the outcomes sought
success-criteria.md ← measures of success
scope.md ← what is in and out of scope
timeline.md ← key dates and milestones
risks-and-issues.md ← canonical risk register
open-questions.md ← implementation open questions (see the open-questions skill)
onboarding.md ← how to get started on the engagement
terminology.md ← canonical glossary (rule 26)
decisions/ ← ADRs, numbered not dated
0001-<decision-slug>.md
01-people/ ← a directory of people involved in the project
<organisation-or-team>/
<firstname-lastname>.md
02-organisations/ ← external organisations involved in the engagement
03-systems/ ← technical entities
04-concepts/ ← domain glossary, one file per term
05-brands/ ← brand entities relevant to the engagement
06-communication-channels/ ← events, one directory per medium (rules 13-14)
emails/
teams-chats/
meetings/ ← every synchronous verbal exchange; slug carries the flavour
retros/
status-updates/ ← periodic status reports
news/ ← external news items (press, market updates)
loop/ ← Loop pages that are the atomic artifact (no upstream meeting or email)
07-design-thinking/ ← DT workshop artifacts
08-deliverables/ ← canonical versioned artifacts; folder-shaped when multiple forms exist (md, pdf, pptx)
knowledge-sources/ ← source registry cards and freshness metadata
09-tasks/
open/
done/
source-docs/ ← documents we should keep that were the source of summaries, actions and KB updates
friction/ ← append-only JSONL friction log driving continuous improvement
friction.jsonl
conversations/ ← session records analysed by the conversation-insights skill
scripts/ ← PowerShell helpers invoked by the justfile (new-event, new-entity, new-conversation, log-friction, kb-pr, post-ado-comment)
justfile ← deterministic CLI complementing the agent council
tmp/ ← .gitignored staging folder for temp imports; after ingestion artefacts leave tmp and move to event-local source or source-docs