microsoft / microsoft/hve-core

docs: add project knowledge base bootstrap recipe

Open Beginner friendly
#1,862 0 comments 0 reactions 0 assignees View on GitHub
documentation needs-triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.