diff --git a/docs/customization/README.md b/docs/customization/README.md index e80c13ad1..2892ba23f 100644 --- a/docs/customization/README.md +++ b/docs/customization/README.md @@ -2,7 +2,7 @@ title: Customizing HVE Core description: Overview of customization approaches from lightweight settings to full fork-and-extend, with role-based entry points author: Microsoft -ms.date: 2026-07-16 +ms.date: 2026-07-29 ms.topic: overview keywords: - customization @@ -121,6 +121,7 @@ Each HVE role benefits from different customization techniques. The table below 8. [Environment Customization](environment.md): DevContainers, VS Code settings, MCP servers 9. [Team Adoption and Governance](team-adoption.md): Governance, naming, onboarding, change management 10. [Local Telemetry](local-telemetry.md): Enable local telemetry, review capture and storage schema mechanics, and generate reports +11. [Bootstrapping a Project Knowledge Base](project-knowledge-base.md): Source-backed project memory that grounds humans and agents in a shared current understanding ## Related Resources diff --git a/docs/customization/project-knowledge-base.md b/docs/customization/project-knowledge-base.md new file mode 100644 index 000000000..1e25d71df --- /dev/null +++ b/docs/customization/project-knowledge-base.md @@ -0,0 +1,177 @@ +--- +title: Bootstrapping a Project Knowledge Base +description: Create a source-backed, repository-shaped project memory that grounds humans and agents in a shared current understanding +author: Microsoft +ms.date: 2026-07-29 +ms.topic: how-to +keywords: + - knowledge base + - project memory + - context engineering + - agent grounding +estimated_reading_time: 6 +--- + +## What a Project Knowledge Base Is + +A project knowledge base (project KB) is a source-backed, repository-shaped +memory for a project, engagement, product, or workstream. It models the +durable context of the work, including the people, organizations, systems, +concepts, decisions, risks, deliverables, and assets involved, so humans and +agents can work from a shared current understanding. + +A project KB is not the same as the `docs/` folder in a working repository. +Working-repo docs describe the thing being built. The project KB carries the +context needed to understand why it is being built, who it affects, what has +already been decided, and what an agent should read before generating new +work. + +## When to Use One + +A project KB earns its maintenance cost when one or more of these hold: + +* The work spans multiple repositories that need the same shared context. +* The project runs long enough that decisions, stakeholders, and constraints + change while people rotate in and out. +* Agents assist with planning, drafting, or implementation and need grounding + beyond the source code, such as who owns a system or why a decision stands. +* Meetings, emails, and workshops carry facts that would otherwise live only + in individual memory or scattered note files. + +For a short-lived, single-repo effort with a stable team, a well-kept `docs/` +folder is usually enough. + +## Separate Repository Model + +A project KB works best as its own Git repository, cloned beside, mounted +into, or referenced from one or more working repositories: + +```text +workspace/ +|-- working-repo/ +| |-- src/ +| `-- docs/ +| +`-- knowledge-base-repo/ + |-- project/ + |-- people/ + |-- organizations/ + |-- systems/ + |-- concepts/ + |-- events/ + |-- decisions/ + |-- risks/ + |-- deliverables/ + `-- assets/ +``` + +Separation buys three things: + +* Portability. The same KB can ground several working repositories without + duplication. +* Access control. Project context often has a different audience than source + code, and a separate repository can carry its own permissions. +* Focus. The code repository stays about building the thing; the KB carries + the shared understanding around it. + +## Starter Taxonomy + +Each top-level directory holds one kind of durable context: + +| Directory | Holds | +|------------------|---------------------------------------------------------------------------| +| `project/` | Scope, timeline, workstreams, goals, success criteria, open questions | +| `people/` | Stakeholders, roles, responsibilities, preferences, availability | +| `organizations/` | Customers, partners, vendors, internal teams | +| `systems/` | Applications, platforms, data stores, integrations, technical constraints | +| `concepts/` | Domain language, business concepts, policies, processes, patterns | +| `events/` | Meetings, emails, chats, workshops, research captures, agent sessions | +| `decisions/` | Architectural, delivery, product, or process decisions | +| `risks/` | Known risks, assumptions, mitigations, unresolved uncertainty | +| `deliverables/` | Proposals, readouts, decks, summaries, designs, plans | +| `assets/` | Source files, diagrams, media, templates, supporting material | + +Treat the taxonomy as a starting point. Add directories only when content +demands them, and keep one clear admission rule per directory so contributors +and agents know where each fact belongs. + +## The Event-to-Entity Update Loop + +The core pattern that keeps a project KB current: + +```text +events -> update entities -> entities ground future work +``` + +```mermaid +graph LR + A["Events
(meetings, emails, workshops)"] --> B["Entity updates
(people, systems, decisions, risks)"] + B --> C["Grounded future work
(humans and agents)"] + C --> A +``` + +In this model a meeting is not just meeting notes. It is evidence that may +update a person profile, a system description, a project risk, a decision +record, or a concept definition. For example, a design review where a +stakeholder changes roles and a latency constraint is agreed should produce +three writes: the event capture under `events/`, an updated role on the +person's profile under `people/`, and a new constraint on the relevant page +under `systems/`. + +This loop is what makes the KB useful for agent-assisted continuity. An agent +that reads current entities inherits the accumulated judgment of every prior +event without replaying the events themselves. + +## Referencing the KB from a Working Repository + +Use an instructions file to point agents at the KB. With the KB cloned as a +peer of the working repository: + +```markdown +--- +applyTo: '**' +--- + +# Project knowledge + +Before planning or generating work, read the project knowledge base cloned at +`../knowledge-base-repo/`. Treat it as the source of truth for people, +systems, decisions, and open risks. When new evidence contradicts it, propose +a KB update rather than working from the stale fact. +``` + +Saved as `.github/instructions/project-knowledge.instructions.md`, this +grounds every Copilot conversation in the working repository. See +[Customizing with Instructions](instructions.md) for the mechanism. + +## Maintenance Guardrails + +Folder structure alone does not keep a KB trustworthy. Apply these rules from +day one: + +* Source-backed updates only. Every entity fact should trace to an event + capture or an external source. Restructure and summarize what sources say; + never invent detail the sources do not contain. +* Date-stamp decaying facts. Roles, availability, and status change; a fact + with a date can be judged, an undated fact must be re-verified. +* One canonical page per concept. When two pages describe the same thing, + merge them rather than letting definitions fork. +* No catch-all files. Inbox-style dumping grounds accumulate facts that never + reach the entity they should update. If a fact has no clear home, that is a + taxonomy conversation, not a triage file. +* Curate on a cadence. Schedule a recurring pass, human or agent-assisted, to + find stale facts, misplaced files, and conflicting concepts before they + erode trust in the KB. + +## Possible Follow-On Work + +This recipe is deliberately documentation-only. If teams find the pattern +useful, natural extensions include a scaffold generator or bootstrap skill for +the starter taxonomy, schema validation for entity frontmatter, and a curator +agent that automates the maintenance pass. Each of those should be its own +proposal. + + +*🤖 Crafted with precision by ✨Copilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* +