kb-base

Imported from wtulloch/kb-base (AGENTS.md). Install upstream with npx 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>.md so 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

1. 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.
2. Token efficiency. No **bold**, no decorative markdown. Plain prose, dashes, code fences. Avoid filler and restated context.
3. No em-dashes, ever. Use commas, full stops, parentheses, or rewrite.
4. One fact, one home. Never duplicate a fact between two files. Link to the canonical entity.
5. Entity slugs are stable once verified: firstname-lastname for people, kebab-case for teams, systems, and concepts. If an early capture is wrong, apply a one-time correction and record it in the related event.
6. No abbreviations in slugs. All file and directory slugs use full descriptive words. ai-foundry-method not afm, design-thinking not dt. The slug should convey the content's identity without opening the file.
7. Events are append-only and datetime-prefixed: YYYYMMDD-HHMM-<slug>.md. Use -0000 when the exact time is unknown. Do not rewrite history. When source artefacts exist, events may use folder shape YYYYMMDD-HHMM-<slug>/ with source and derived files inside.
8. No wiki-links. Relative markdown links only (direction rules live in the core model above).
9. No spaces in filenames for authored content. Use hyphens. Raw source files (PDFs, DOCX, images) retain their original filenames.
10. 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.
11. Never invent information. Only restate, rearrange, or link facts that exist in the source. If unsure about a fact, ask.
12. 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.
13. Events carry frontmatter. date always. attendees: for synchronous events. source: (durable URL preferred) and source-type: when the content was captured upstream. Allowed source-type: values are loop, email, teams-chat, copilot-recap, transcript, file, external-tool, agent-interview. Optional provenance fields are local-source:, source-system:, source-access-tool:, source-locator:, last-verified:, internet-message-id:, sender:, sent-at:, subject:. Communication events may include deliverables: to link canonical artefacts and visibility: to declare sharing scope.
14. Channels classify by medium, not authoring tool. A Loop page that recaps a meeting is a meeting event with the Loop URL in source:. Reserve communication-channels/loop/ for Loop pages that are the atomic artifact (no upstream meeting or email).
15. 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). No customer-conversations/ or conversations/ subchannel.
16. For WorkIQ-derived email events, keep source-type: email and set source: to the mailbox URL used by the capturer when available.
17. 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.
18. For cross-user stable provenance on email events, include internet-message-id: when available. Add sender:, sent-at:, and subject: when needed for human verification.
19. 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 both source: and local-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.
20. 08-deliverables/ is the canonical home for artefacts. Communication events in 06-communication-channels/ link to artefacts through deliverables: and do not restate artefact content.
21. tmp/ is staging only. After ingestion, move artefacts to event-local source/ or source-docs/.
22. 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.
23. 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.
24. Source freshness is explicit. If a source may be stale, warn inline and offer refresh in the same turn.
25. 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.
26. 00-project/terminology.md is 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 in 04-concepts/ or 03-systems/ link from the glossary row to that entity rather than restating the definition.
27. 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 carrying language: and pair: frontmatter pointing at its counterpart. The -Bilingual switch on scripts/new-event.ps1 and scripts/new-entity.ps1 scaffolds 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).

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.

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 (use just friction-log <step> <category> <title> <error> <fix>). Schema: timestamp (ISO-8601), step, category (one of ingestion|agent|git|pr|cli|docs|other), title, error (or null), fix_applied (or null), suggested_improvement (or null).
• If a routine operation has no just recipe, log it as friction with category cli and 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 a type: resolution line.
• 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