Add customization guides for HVE Core artifacts #773
Description
Summary
Create a comprehensive customization documentation suite under docs/customization/ that provides end-to-end guidance for teams adapting HVE Core artifacts (instructions, prompts, agents, skills, collections) to their own workflows.
Motivation
HVE Core ships contributing guides (docs/contributing/) that cover upstream contribution standards and schema syntax, but there is no user-facing documentation for teams who want to customize artifacts for their own projects without contributing upstream. This gap forces teams to reverse-engineer conventions from the contributing specs or read raw source files.
A dedicated customization suite bridges this gap with tutorial-oriented, role-based guidance that meets teams where they are — from simple instruction files through full fork-and-extend scenarios.
Scope
Seven-Level Customization Spectrum
The documentation follows a progressive complexity model:
- VS Code Settings — Individual preferences, no shared files
- Instructions —
.github/copilot-instructions.mdand.instructions.mdfiles - Agents & Prompts — Multi-turn and single-shot workflows with tool restrictions
- Skills — Self-contained domain knowledge bundles with optional scripts
- Collections — Distributable packages bundling all artifact types
- Build System — Validation scripts, schema checks, plugin generation pipelines
- Fork & Extend — Full repository control when changes diverge from upstream
Deliverables
| Guide | Topic | Type |
|---|---|---|
README.md |
Central entry point with spectrum diagram and role-based navigation | overview |
instructions.md |
Instruction file authoring, applyTo targeting, instruction stacking |
how-to |
prompts.md |
Prompt lifecycle, template variables, agent delegation, mode config | how-to |
agents.md |
Agent architecture, subagent patterns, tool restrictions | how-to |
skills.md |
Skill concepts, SKILL.md anatomy, progressive disclosure model |
how-to |
collections.md |
YAML manifest format, maturity filtering, transitive subagent deps | how-to |
build-system.md |
Plugin generation pipeline, schema validation, npm scripts reference | how-to |
environment.md |
DevContainers, VS Code settings, MCP servers, coding agent environments | how-to |
forking.md |
Fork setup, upstream sync workflow, Copilot-assisted adaptation | tutorial |
team-adoption.md |
Phased adoption strategy, naming conventions, governance, success metrics | how-to |
Cross-Cutting Requirements
- Role-based navigation mapping nine HVE roles to recommended entry points
- "Accelerating with Prompt Builder" section in each guide (
/prompt-build,/prompt-analyze,/prompt-refactor) - Cross-references to corresponding
docs/contributing/guides for full schema details - Consistent YAML frontmatter (
title,description,author,ms.date,ms.topic,keywords,estimated_reading_time) - Copilot attribution footers
- Update
docs/README.mdwith a Customization section linking to all guides
Acceptance Criteria
- All 10 guides created under
docs/customization/ -
docs/README.mdupdated with Customization section and Quick Links entry - Each guide cross-references the corresponding contributing guide
- Role-based navigation table covers all nine HVE roles
- Prompt Builder integration section present in each artifact guide
- All automated checks pass (
lint:md,spell-check,lint:frontmatter,validate:skills,lint:md-links,lint:ps)