HVE Core Team Usage Recipes: Artifact Flow, Contracts, and Reuse

[jsburckhardt]

Context

Using HVE Core across projects and hacks, the agents, extensions, and skill-based building blocks have been extremely useful for research, security planning, and RPI-style workflows.

The Core Challenge

The open question isn't just where generated files should live—it's what the expected team operating model is for consuming, shaping, persisting, and reusing agent-produced artifacts over time.

Today's gap:

• Outputs are often written to scratch/tracking locations that are .gitignore'd — fine for individual exploration
• In collaborative settings, teams need research, decisions, work packages, and rationale to be visible, reviewable, linked to delivery workflows, and discoverable by both people and agents

What Teams Need Guidance On

1. Artifact contracts — Where do decision records, research, specs, and plans live?
2. Delivery integration — How do artifacts relate to GitHub Issues or Azure DevOps work items?
3. Agent assumptions — What assets can agents/workflows assume already exist?
4. Ephemeral vs. persistent — What gets promoted into source control vs. what stays scratch?

Suggested: Recipe-Style Guidance

Positioned as opinionated guidance, not a mandate, covering:

• Bootstrapping — How a project can bootstrap and customize an agentic setup
• Skills as building blocks — How skills act as the unit of execution and knowledge, compose into workflows/triggers
• Configuration over embedding — How project-specific opinions (folder structure, naming, security) are externalized through config rather than baked into skills
• Augmentation patterns — How teams augment HVE Core with external agent assets reshaped into the project's conventions, rather than just "install an extension" or "copy files into a repo"

A Concrete Example Flow

Research → Decision Record/ADR → Implementation → Tracked Work

Showing:

• What artifacts are promoted to source control vs. remain ephemeral
• How agents rediscover and build on prior artifacts
• How this reduces confusion without over-opinionating the tool

Why This Matters

This guidance would:

• Make HVE Core easier for customer teams to adopt for the first time
• Reflect the broader shift from isolated agent outputs toward configurable, composable, team-oriented agent systems

[katriendg]

Thanks @jsburckhardt for starting this thread, this is so much to the point. We need to provide more guidance, now that HVE Core starts to reach a more and more stable baseline.

Especially the approach with the recipe-style guidance, adaptability to ensuring agents and instructions get enforced repo or org specific conventions. Based on your experience, do you see a first area where we could actively document and maybe follow a concrete example? The docs have some information about extensibility, but it's probably still very much high level. A real example that walks users through a problem setting, how it was solved by extending HVE Core would be very welcome.

I do also want to note we are experimenting with some forms of extensibility around security and other planners, @WilliamBerryiii has experiments going. But I also believe we can move forward in parallel and no need to wait for other models of extensibility.

[chris-buckley]

Thanks @katriendg. @coatsy, @jsburckhardt and I have been looking at this through the project knowledge base lens, and I think the first concrete example should be a project knowledge base bootstrap recipe.

The reason is simple. A lot of teams hit the same problem as soon as HVE Core starts helping with real project work. The agents can research, plan, write decisions, create tasks, and produce useful files. Then the team has to answer the less exciting question that actually makes the whole thing useful.

Where does this knowledge live so people and agents can trust it next week?

That feels like a good recipe because it touches most of the things you called out. Artifact contracts, delivery integration, agent assumptions, review, and the split between scratch work and durable project memory.

Bootstrap a project knowledge base

Use this recipe when a team is starting a unit of work inside a project and wants agents to work from shared project knowledge instead of scattered notes. That unit of work might be a discovery workshop, hack stream, sprint, feature slice, design activity, or early delivery thread.

I think the project frame matters. The knowledge base should not try to become the whole organisation, the whole customer account, or every related industry pattern. It should give the team a working memory for the unit of work they are actually delivering, while still making it possible to link up to broader customer, industry, organisation, and public knowledge when that helps.

Two ideas seem important here.

First, knowledge needs a process.
Bring material in, make it queryable, then generate useful outputs from it.

Second, knowledge needs levels.
Some knowledge belongs in the current project. Some belongs one level up, such as customer context, industry context, organisation context, or public shared guidance.
A project KB should be able to use those layers without copying all of them into every project.

The recipe should help the team set up a repo-local knowledge base that supports four loops.

1. Ingest

   • Bring notes, transcripts, research, workshop outputs, decisions, risks, and generated files into a known intake area.
   • Keep provenance with every source.
   • Ask an agent to classify the source, extract durable facts, mark uncertainty, and propose updates.
   • Keep raw or sensitive material out of durable project memory when the project rules require that.

2. Review

   • Decide when ingestion can go straight to main and when it needs a branch and PR.
   • Use direct commits for low-risk, single-threaded capture.
   • Use branches and PRs when multiple streams are working in parallel, when interpretation could be wrong, or when bad extraction would pollute later outputs.
   • Treat the PR as a review of project memory, not just a file diff.

3. Query

   • Let agents answer questions from the curated knowledge base instead of rereading every raw source.
   • Require answers to point back to the knowledge or source file they depend on.
   • Keep uncertainty visible, especially for people, roles, dates, numbers, problem statements, and customer commitments.

4. Generate

   • Generate summaries, decision records, ADRs, requirements, risks, work items, slides, and stakeholder updates from the curated knowledge.
   • Store canonical artifacts in one durable place.
   • Record when something was sent, presented, reviewed, or approved separately from the artifact itself.

I would avoid making the first version too prescriptive about folders. Teams will have different rules. What matters more is that each area has a job and agents know what they can rely on.

One possible starter contract could look like this.

project               scope, timeline, risks, open questions, and decisions
people                project people grouped by organisation or team
organisations         customer, partner, and supplier entities
systems               technical systems, products, services, and platforms
concepts              domain language and project-specific terms
events-and-communication meetings, workshops, emails, chats, status updates, and related records
artifacts             highly usable outputs that provide durable context

The contract gives agents a few simple rules.

• where to look for reviewed knowledge
• where to stage proposed changes
• what needs provenance
• what can stay temporary
• what needs review before it becomes project memory
• where generated artifacts belong

The source handling matters more than I first thought. The starter recipe should say that source material needs a durable home or durable pointer, but I would not make that a top-level folder in the first version. A transcript can sit beside the meeting it produced. A source that stays outside the repo can be referenced through a stable locator and access method. The derived Markdown is the interpretation. The source remains the authority.

I would also make artifacts a first-class area. These are highly usable outputs that provide durable context for the project, not just files produced along the way. If a workshop summary, proposal, deck, or readout has more than one form, such as Markdown plus PDF plus PowerPoint, it should become a folder. Event and communication records should link to the exact artifact file that was sent or presented. They should not restate the artifact content.

A lot of useful knowledge also comes from the agent interviewing a user after the fact. I would treat that like any other source-backed event or artefact. The Q and A is source material, and the distilled output is derived from it. The layout does not need a special top-level area for that.

There is one more piece I would include. Many teams need to publish selected knowledge somewhere else later, such as a wiki, issue tracker, portfolio dashboard, SharePoint site, or other reporting tool. I think that should be treated as an adapter over the project knowledge base.

The project knowledge base should serve the people and agents doing the work. Publication adapters can reshape selected parts of it for other audiences.

That would make this a concrete example of configuration over embedding.

• HVE Core provides the recipe, agent expectations, review modes, and starter prompts.
• The project config decides naming, source retention, security rules, branching policy, and which generated outputs matter.
• Teams start lean and add specialist agents or skills only when the project needs them.

If this feels useful, I can see the first doc being small.

1. When to use this recipe
2. A starter contract for project knowledge
3. The ingest to review to query to generate loop
4. Direct commit versus PR guidance
5. Provenance and sensitive data guardrails
6. Agent and prompt examples that use the contract
7. A publication adapter example for external systems

The main value is that it gives teams somewhere practical to start. It also gives HVE Core a real example of how teams extend the tool into a working project setup without forcing every project to use the same structure.

[chaosdinosaur]

Building on what @jsburckhardt framed, what @katriendg asked for, and @chris-buckley's detailed knowledge base proposal — one thing that stood out to me is whether the guidance could go beyond documentation and become something agents discover on their own. Thought it might be worth exploring.

The Question That Keeps Coming Up

The discussion so far points toward documentation recipes: opinionated guidance teams follow to organize knowledge. That makes sense as a starting point. But one friction point worth considering — if agents can't discover the knowledge base automatically, teams still end up telling agents "look here first" every session. Over time that erodes adoption.

Two Paths Worth Considering

	Docs Recipe Only	Root Config + Instructions Bridge
Agent discovery	Manual — user tells agent where to look	Automatic — instructions bridge loads every interaction
Graduation	Manual — user copies artifacts	Agent-suggested — "promote this to knowledge/research/?"
Machine-parseable	No	Yes — validatable, parseable by skills
Bootstrap	Read docs, create folders	One command generates config + structure
Implementation cost	1 PR	3-4 PRs
Compound value	Linear	Agents build on accumulated knowledge over time

These don't have to compete. A recipe doc explains the why. A config file could make it work at runtime. The question is whether the runtime layer is worth the extra investment.

What a Root Config Could Look Like

Something like a .hve-project.yml at workspace root:

version: 1

knowledge:
  root: knowledge/
  areas:
    decisions:
      path: knowledge/decisions/
      graduation_from: .copilot-tracking/adrs/
    context:
      path: knowledge/context/
    research:
      path: knowledge/research/
      graduation_from: .copilot-tracking/research/
    artifacts:
      path: knowledge/artifacts/

agents:
  lookup_before_generate: true
  staging: .copilot-tracking/
  graduation_review: pr

provenance:
  require_source: true

A thin .github/instructions/project-knowledge.instructions.md with applyTo: '**' could bridge it into agent behavior using the existing discovery mechanism. No new tooling needed for the bridge itself — it would use the same glob-based loading that every other instructions file uses.

How Agent Behavior Could Change

Without config (today): Agent gets task → searches codebase → generates output → writes to .copilot-tracking/ → next session starts fresh.

With config: Instructions bridge auto-loads → agent reads .hve-project.yml → checks knowledge/ areas for prior work on the topic → builds on it → suggests graduation when complete.

This could address @chris-buckley's "query loop" — agents answering from curated knowledge instead of re-reading every raw source — without requiring a full indexing system upfront. The instructions bridge + existing read_file capabilities might be enough for a first pass.

Mapping to @chris-buckley's Model

His ingest → review → query → generate loop could map onto this:

Loop	Possible Implementation
Ingest	Agent writes to .copilot-tracking/ (already works today)
Review	Config's graduation_review: pr tells agents to use PRs for promotion
Query	lookup_before_generate: true + knowledge area paths = agents check before generating
Generate	Agents produce outputs, suggest graduation to configured knowledge/ paths

His 7-area contract could become a starter set of 4 areas: entries in the YAML. Teams add more areas by editing the config — no code changes, no new instructions, just YAML.

A Possible Phased Path

Phase 1 (fast): Recipe doc in docs/recipes/ explaining the pattern. Gets the concepts in front of teams immediately.

Phase 2 (medium): .hve-project.yml schema + instructions bridge + validation script. Agents start respecting the config.

Phase 3 (later): Bootstrap skill that generates the config, folder structure, and bridge file from a single interaction. First-run experience becomes: "bootstrap my project knowledge base" → done.

Why This Might Be Worth Exploring Beyond Docs Alone

Docs alone keep the knowledge base as a team convention — something humans maintain and agents ignore until told otherwise. A config file could make it an agent contract — something agents discover, respect, and actively participate in maintaining. That's the difference between "we documented a folder structure" and "agents accumulate and build on project knowledge over time."

The compound value would show up in week 3, not week 1. By then, agents would have enough accumulated context in knowledge/ that they stop asking questions the team already answered.

Curious what others think — especially whether the config layer feels like the right abstraction or whether there's a simpler mechanism that gets the same agent-discoverability benefit.