microsoft / microsoft/hve-core

Enhance context harness: ADR distillation to ARCHITECTURE.md and copilot-instructions.md initialization

Open
#857 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Summary

Two enhancements to HVE-Core's context harness that improve how architectural decisions and project structure are surfaced to AI agents.

## Motivation

Current context harness patterns carry overhead that can be reduced:
- **ADRs** accumulate as individual files but lack a consolidated current-state view, forcing agents to read and reconcile multiple documents.
- **`copilot-instructions.md`** initialization doesn't follow the emerging pattern (aligned with Vercel's findings) that the root instructions file works best as an index pointing to where information lives rather than embedding the information itself.

## Proposed Changes

### 1. ADR Distillation into ARCHITECTURE.md

Introduce tooling or a workflow step that distills accepted ADRs into a single `ARCHITECTURE.md` file representing current architectural state. This file should:

- Consolidate active decisions from individual ADR files into a single living document.
- Include or reference a visual architecture diagram (tldraw or draw.io format).
- Update automatically or via a prompted workflow when ADRs change status.

**Diagram tooling suggestion:** Evaluate adding an MCP server or skill for tldraw and/or draw.io diagram generation and editing. This would enable agents to create and maintain architecture diagrams as part of the ADR distillation workflow.

### 2. copilot-instructions.md Initialization as an Index

Update the initialization of `copilot-instructions.md` so that it serves as an index — pointing agents to documentation, skills, instructions, and conventions rather than duplicating that content inline. This aligns with findings that an index-style root file:

- Reduces context window waste from redundant content.
- Keeps the root file stable while referenced files evolve independently.
- Improves agent routing by clearly listing where each type of information lives.

The initialized file should include pointers to:
- Project structure and directory organization
- Available skills and their locations
- Instruction files and their `applyTo` scopes
- Custom agents and their purposes
- Build, test, and lint commands
- Contributing guidelines

## Acceptance Criteria

- [ ] ADR distillation produces an `ARCHITECTURE.md` from accepted ADR files
- [ ] `ARCHITECTURE.md` includes or references visual architecture diagrams
- [ ] Feasibility assessment for tldraw/draw.io MCP server or skill integration
- [ ] `copilot-instructions.md` initialization generates an index-style file
- [ ] Index references are validated against actual workspace contents

Contributor guide

Open the contributing guide

Research direction

Start by locating the existing ADR files and the copilot-instructions.md initialization workflow. Trace how accepted ADRs and workspace references are discovered, then assess diagram-tool integration before implementing the proposed workflow. Done means an ARCHITECTURE.md is produced from accepted ADRs and initialization creates an index whose references validate against the workspace.

Written by the indexing model from the issue text.

Assessment

Domain
developer-experience, documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.