microsoft / microsoft/hve-core
docs: add project knowledge base bootstrap recipe
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
### Issue Description
HVE Core users would benefit from a practical docs recipe for bootstrapping a project knowledge base: a source-backed, repository-shaped memory for a project, engagement, product, or workstream.
The recipe should explain how a project KB can model durable project context so humans and agents can work from a shared current understanding. The core pattern is:
```text
events -> update entities -> entities ground future work
```
In this model, events such as meetings, emails, chats, workshops, research captures, and agent sessions are not just notes. They are evidence that can update longer-lived project entities such as people, organizations, systems, concepts, decisions, risks, deliverables, and assets.
The proposed first contribution is a docs-first recipe that covers:
- What a project KB is and when to use one.
- How a project KB can live as a separate repository and be referenced by one or more working repositories.
- A starter folder model for durable project context, including project, people, organizations, systems, concepts, events, decisions, risks, deliverables, and assets.
- The event-to-entity update loop and why it matters for agent-assisted project continuity.
- Basic guardrails for source-backed updates, maintainability, stale facts, conflicting concepts, and misplaced files.
- A lightweight example showing a working repository pointing to a separate KB repository.
Suggested example shape, illustrative only:
```text
workspace/
|-- working-repo/
| |-- src/
| |-- docs/
| `-- .hve-project.yml # points agents to the KB
|
`-- knowledge-base-repo/
|-- project/
|-- people/
|-- organizations/
|-- systems/
|-- concepts/
|-- events/
|-- decisions/
|-- risks/
|-- deliverables/
`-- assets/
```
This issue should stay scoped to the initial docs recipe. It should not require a scaffold generator, bootstrap skill, schema, automation, or `.hve-project.yml` implementation in the first PR, although the recipe can identify those as possible follow-on work if maintainers agree.
### Additional Context
This proposal follows from GitHub Discussion #1250, "HVE Core Team Usage Recipes: Artifact Flow, Contracts, and Reuse."
The likely docs home may be under `docs/customization/`, alongside existing guidance for team adoption and artifact customization, but maintainers should confirm the preferred placement before implementation.
Acceptance criteria for the first PR:
- The docs page defines a project KB and explains when a team should use one.
- The docs page describes the separate-repository model and how a working repository can reference the KB.
- The docs page includes a starter taxonomy for project, people, organizations, systems, concepts, events, decisions, risks, deliverables, and assets.
- The docs page explains the event-to-entity update loop.
- The docs page includes basic source-backed maintenance guardrails.
- The contribution remains documentation-only unless maintainers explicitly ask for implementation work.
- The changed docs pass the relevant markdown, spelling, frontmatter, and link checks.
Contributor guide
Research direction
Start by reviewing the existing guidance under docs/customization/ and the repository's relevant Markdown, spelling, frontmatter, and link checks. Add a documentation-only recipe covering the project KB definition, separate-repository model, starter taxonomy, event-to-entity loop, and source-backed maintenance guardrails. Done means all listed acceptance criteria are addressed and the documentation checks pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100