microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/architecture/README.md
87lines · modecode
| 1 | --- |
| 2 | title: Architecture Overview |
| 3 | description: HVE Core system design and component relationships |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-02-19 |
| 6 | ms.topic: concept |
| 7 | --- |
| 8 | |
| 9 | HVE Core provides a Copilot customization framework that enables teams to extend GitHub Copilot with project-specific context, workflows, and automation. The framework organizes reusable AI artifacts, development scripts, and documentation into a cohesive system that integrates with VS Code and GitHub workflows. |
| 10 | |
| 11 | ## System Architecture |
| 12 | |
| 13 | The following diagram illustrates the primary components and their relationships: |
| 14 | |
| 15 | ```mermaid |
| 16 | graph TD |
| 17 | EXT[Extension] --> AGENTS[Agents] |
| 18 | EXT --> PROMPTS[Prompts] |
| 19 | EXT --> INSTRUCTIONS[Instructions] |
| 20 | EXT --> SKILLS[Skills] |
| 21 | SCRIPTS[Scripts] --> LINTING[Linting] |
| 22 | SCRIPTS --> SECURITY[Security] |
| 23 | SCRIPTS --> PLUGINS[Plugins] |
| 24 | DOCS[Documentation] --> GUIDES[User Guides] |
| 25 | DOCS --> ARCH[Architecture] |
| 26 | ``` |
| 27 | |
| 28 | ## Component Summary |
| 29 | |
| 30 | | Component | Location | Purpose | |
| 31 | |---------------------|----------------------------|-------------------------------------------------------------------------------| |
| 32 | | Extension | `extension/` | VS Code extension providing contribution points for AI artifacts | |
| 33 | | Scripts | `scripts/` | PowerShell automation for linting, security validation, and plugin generation | |
| 34 | | Documentation | `docs/` | User guides, architecture docs, and contribution guidelines | |
| 35 | | GitHub Assets | `.github/` | Workflows, instructions, prompts, agents, skills, and issue templates | |
| 36 | | Dev Container | `.devcontainer/` | Codespaces and local container development environment | |
| 37 | | Frontmatter Schema | `scripts/linting/schemas/` | JSON schemas for AI artifact validation | |
| 38 | | GitHub Workflows | `.github/workflows/` | CI/CD pipelines for validation, security, and release automation | |
| 39 | | Access Control | `.github/CODEOWNERS` | Path-based review requirements and ownership | |
| 40 | | MCP Configuration | `.vscode/mcp.json` | Model Context Protocol server definitions | |
| 41 | | Plugins | `plugins/` | Generated Copilot CLI plugin output from collection manifests | |
| 42 | | Test Infrastructure | `scripts/tests/` | Pester test suites with fixtures and mocks | |
| 43 | |
| 44 | ## Core Subsystems |
| 45 | |
| 46 | ### Extension |
| 47 | |
| 48 | The VS Code extension serves as the integration layer between HVE Core artifacts and the Copilot experience. It registers contribution points that allow Copilot to discover and use agents, prompts, instructions, and skills defined within the repository. The extension follows VS Code extension packaging conventions and includes its own README and license. |
| 49 | |
| 50 | ### Scripts |
| 51 | |
| 52 | Automation scripts handle quality assurance and development workflows. The scripts directory organizes functionality into specialized subdirectories: |
| 53 | |
| 54 | * Linting scripts validate markdown formatting, link integrity, YAML structure, and PowerShell code quality |
| 55 | * Security scripts verify dependency pinning and SHA staleness for workflow actions |
| 56 | * Plugin scripts generate Copilot CLI plugins from collection manifests |
| 57 | * Library modules provide shared utilities like verified downloads |
| 58 | |
| 59 | ### Plugins |
| 60 | |
| 61 | Collection manifests in `collections/` define bundles of agents, prompts, instructions, and skills. Running `npm run plugin:generate` produces the `plugins/` directory, which contains generated output organized by collection ID. Files under `plugins/` are not edited directly. See [scripts/plugins/README.md](../../scripts/plugins/README.md) for the generation pipeline. |
| 62 | |
| 63 | ### Documentation |
| 64 | |
| 65 | User-facing documentation guides teams through installation, configuration, and effective use of the framework. The RPI (Researcher, Planner, Implementor) methodology documentation helps teams structure their AI-assisted development workflows. Contributing guides explain how to author AI artifacts that follow project conventions. |
| 66 | |
| 67 | ### GitHub Assets |
| 68 | |
| 69 | The `.github/` directory contains workflow definitions, issue templates, and the AI artifacts that define Copilot behavior. Instructions files provide context-specific guidance that Copilot applies when working with certain file types or directories. Agents define specialized personas for different tasks. Prompts offer reusable starting points for common operations. All artifact types are organized into `{collection-id}` subdirectories by convention (e.g., `.github/agents/hve-core/`, `.github/instructions/coding-standards/`). |
| 70 | |
| 71 | Skills package executable utilities with cross-platform scripts and domain-specific guidance; each skill is self-contained with a SKILL.md file describing capabilities and usage patterns. By convention, skills are organized under `.github/skills/{collection-id}/{skill-name}/`. |
| 72 | |
| 73 | ## Package Relationships |
| 74 | |
| 75 | Components interact through well-defined boundaries. The extension registers contribution points for agents, prompts, and instructions, making them available to Copilot Chat. Skills use a separate discovery mechanism: Copilot scans `.github/skills/{collection-id}/` subdirectories by convention for `SKILL.md` files that describe executable capabilities. Scripts operate independently of the extension but share configuration files like `PSScriptAnalyzer.psd1` and schema definitions in `scripts/linting/schemas/`. |
| 76 | |
| 77 | Documentation references both the extension capabilities and script utilities, providing guidance on how to use each component effectively. The tracking directory (`.copilot-tracking/`) serves as a workspace for AI-assisted workflows, storing work item discoveries, plan artifacts, and change records that bridge human and AI collaboration. |
| 78 | |
| 79 | GitHub workflows orchestrate script execution for continuous integration, running linting and security checks on pull requests. The extension packaging scripts prepare the VS Code extension for distribution, bundling required assets and generating the installable VSIX package. |
| 80 | |
| 81 | ## Further Reading |
| 82 | |
| 83 | * [AI Artifacts Architecture](ai-artifacts.md) - Four-tier artifact delegation model |
| 84 | * [Build Workflows](workflows.md) - GitHub Actions CI/CD pipeline architecture |
| 85 | * [Testing Architecture](testing.md) - PowerShell Pester test infrastructure |
| 86 | |
| 87 | 🤖 *Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.* |
| 88 | |