microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
.github/copilot-instructions.md
96lines · modecode
| 1 | --- |
| 2 | description: 'Comprehensive coding guidelines and instructions for hve-core' |
| 3 | --- |
| 4 | |
| 5 | # General Instructions |
| 6 | |
| 7 | Items in the Highest Priority Rules section from attached instructions files override any conflicting guidance. |
| 8 | |
| 9 | <!-- <highest-priority-rules> --> |
| 10 | ## Priority Rules |
| 11 | |
| 12 | * Conventions and styling from the codebase take precedence for all changes. |
| 13 | * Instructions files not already attached are read before deciding on edits. |
| 14 | * Breaking changes are acceptable. |
| 15 | * Backward-compatibility layers or legacy support are added only when explicitly requested. |
| 16 | * Tests, scripts, and one-off markdown docs are created or modified only when explicitly requested. |
| 17 | |
| 18 | Rules for comments: |
| 19 | |
| 20 | * Remain brief and factual, describing behavior, intent, invariants, and edge cases. |
| 21 | * Thought processes, step-by-step reasoning, and narrative comments do not appear in code. |
| 22 | * Comments that contradict current behavior are removed or updated. |
| 23 | * Temporal markers (phase references, dates, task IDs) are removed from code files during any edit. |
| 24 | |
| 25 | Rules for fixing errors: |
| 26 | |
| 27 | * Proactively fix any problem encountered while working in the codebase, even when unrelated to the original request. |
| 28 | * Root-cause fixes are preferred over symptom-only patches. |
| 29 | * Further investigation of the codebase or through tools is always allowed. |
| 30 | <!-- </highest-priority-rules> --> |
| 31 | |
| 32 | <!-- <project-structure> --> |
| 33 | ## Project Structure |
| 34 | |
| 35 | This repository contains documentation, scripts, and tooling for the HVE (Hyper Velocity Engineering) Core project. |
| 36 | |
| 37 | ### Directory Organization |
| 38 | |
| 39 | The project is organized into these main areas: |
| 40 | |
| 41 | * Documentation (`docs/`) - Getting started guides, templates, RPI workflow documentation, and contribution guidelines. |
| 42 | * Scripts (`scripts/`) - Automation for linting, security validation, extension packaging, and development tools. |
| 43 | * Skills (`.github/skills/`) - Self-contained skill packages with scripts and documentation. |
| 44 | * Extension (`extension/`) - VS Code extension source and packaging. |
| 45 | * GitHub Configuration (`.github/`) - Workflows, instructions, prompts, agents, and issue templates. |
| 46 | * Logs (`logs/`) - Output from validation and analysis scripts. |
| 47 | |
| 48 | ### Scripts Organization |
| 49 | |
| 50 | Scripts are organized by function: |
| 51 | |
| 52 | * Development Tools (`scripts/dev-tools/`) - PR reference generation utilities. |
| 53 | * Extension (`scripts/extension/`) - Extension packaging and preparation. |
| 54 | * Linting (`scripts/linting/`) - Markdown validation, link checking, frontmatter validation, and PowerShell analysis. |
| 55 | * Security (`scripts/security/`) - Dependency pinning validation and SHA staleness checks. |
| 56 | * Library (`scripts/lib/`) - Shared utilities such as verified downloads. |
| 57 | |
| 58 | ### Skills Organization |
| 59 | |
| 60 | Skills are self-contained packages providing guidance and utilities: |
| 61 | |
| 62 | ### Documentation Structure |
| 63 | |
| 64 | * Getting Started (`docs/getting-started/`) - Installation and first workflow guides with multiple setup methods. |
| 65 | * RPI (`docs/rpi/`) - Task researcher, planner, and implementor workflow documentation. |
| 66 | * Contributing (`docs/contributing/`) - Guidelines for instructions, prompts, agents, and AI artifacts. |
| 67 | * Templates (`docs/templates/`) - Templates for custom agents, instructions, and prompts. |
| 68 | |
| 69 | ### Copilot Tracking |
| 70 | |
| 71 | The `.copilot-tracking/` directory (gitignored) contains AI-assisted workflow artifacts: |
| 72 | |
| 73 | * Work Items (`.copilot-tracking/workitems/`) - ADO work item discovery and planning. |
| 74 | * Pull Requests (`.copilot-tracking/pr/`) - PR reference generation, handoff, and review tracking. |
| 75 | * Changes (`.copilot-tracking/changes/`) - Change tracking and implementation logs. |
| 76 | * Plans (`.copilot-tracking/plans/`) - Task planning documents. |
| 77 | * Details (`.copilot-tracking/details/`) - Task plan implementation details. |
| 78 | * Research (`.copilot-tracking/research/`) - Technical research findings. |
| 79 | * Subagent (`.copilot-tracking/subagent/`) - Subagent research outputs organized by date. |
| 80 | * ADRs (`.copilot-tracking/adrs/`) - Architecture Decision Record drafts. |
| 81 | * BRD Sessions (`.copilot-tracking/brd-sessions/`) - Business requirements document session state. |
| 82 | * PRD Sessions (`.copilot-tracking/prd-sessions/`) - Product requirements document session state. |
| 83 | * GitHub Issues (`.copilot-tracking/github-issues/`) - GitHub issue search and tracking logs. |
| 84 | * Prompts (`.copilot-tracking/prompts/`) - Generated implementation prompts. |
| 85 | |
| 86 | All tracking files use markdown format with frontmatter and follow patterns from `.github/instructions/ado-*.instructions.md`. |
| 87 | <!-- </project-structure> --> |
| 88 | |
| 89 | <!-- <script-operations> --> |
| 90 | ## Script Operations |
| 91 | |
| 92 | * Scripts follow instructions provided by the codebase for convention and standards. |
| 93 | * Scripts used by the codebase have an `npm run` script for ease of use. |
| 94 | |
| 95 | PowerShell scripts follow PSScriptAnalyzer rules from `PSScriptAnalyzer.psd1` and include proper comment-based help. Validation runs via `npm run psscriptanalyzer` with results output to `logs/`. |
| 96 | <!-- </script-operations> --> |
| 97 | |