---
description: 'Comprehensive coding guidelines and instructions for hve-core'
---

# General Instructions

Items in the Highest Priority Rules section from attached instructions files override any conflicting guidance.

<!-- <highest-priority-rules> -->
## Priority Rules

* Conventions and styling from the codebase take precedence for all changes.
* Instructions files not already attached are read before deciding on edits.
* Breaking changes are acceptable.
* Backward-compatibility layers or legacy support are added only when explicitly requested.
* Tests, scripts, and one-off markdown docs are created or modified only when explicitly requested.

Rules for comments:

* Remain brief and factual, describing behavior, intent, invariants, and edge cases.
* Thought processes, step-by-step reasoning, and narrative comments do not appear in code.
* Comments that contradict current behavior are removed or updated.
* Temporal markers (phase references, dates, task IDs) are removed from code files during any edit.

Rules for markdown frontmatter:

* When editing any Markdown file whose frontmatter already contains an `ms.date` field, update that field to today's date.
* Format the date using ISO 8601 (`YYYY-MM-DD`), matching the existing `ms.date` convention.

Rules for human review checkboxes:

* Agents never check or mark complete any human review checkbox (for example, `- [ ] Reviewed and validated by a qualified human reviewer`). Only a human may convert `[ ]` to `[x]` on review checkboxes.
* Backlog managers must verify that all human review checkboxes are checked before processing artifacts into a backlog. If any checkbox is unchecked, halt processing and inform the user that human review is required first.

Rules for fixing errors:

* Proactively fix any problem encountered while working in the codebase, even when unrelated to the original request.
* Root-cause fixes are preferred over symptom-only patches.
* Further investigation of the codebase or through tools is always allowed.
<!-- </highest-priority-rules> -->

<!-- <project-structure> -->
## Project Structure

This repository contains documentation, scripts, and tooling for the HVE (Hyper Velocity Engineering) Core project.

### Directory Organization

The project is organized into these main areas:

* Documentation (`docs/`) - Getting started guides, templates, RPI workflow documentation, and contribution guidelines.
* Scripts (`scripts/`) - Automation for linting, security validation, extension packaging, and development tools.
* Skills (`.github/skills/{collection-id}/`) - Self-contained skill packages, by convention organized by collection.
* Extension (`extension/`) - VS Code extension source and packaging.
* GitHub Configuration (`.github/`) - Workflows, instructions, prompts, agents, and issue templates, typically organized into `{collection-id}` subdirectories.
* Collections (`collections/`) - YAML and markdown manifests defining bundled sets of agents, prompts, instructions, and skills.
* Logs (`logs/`) - Output from validation and analysis scripts.

### Scripts Organization

Scripts are organized by function:

* Collections (`scripts/collections/`) - Collection validation and shared helper modules.
* Extension (`scripts/extension/`) - Extension packaging and preparation.
* Linting (`scripts/linting/`) - Markdown validation, link checking, frontmatter validation, model reference validation, and PowerShell analysis.
* Devcontainer (`scripts/devcontainer/`) - Lockfile integrity validation and infrastructure change log generation.
* Security (`scripts/security/`) - Dependency pinning validation, SHA staleness checks, and action version consistency.
* Library (`scripts/lib/`) - Shared utilities such as verified downloads.
* Plugins (`scripts/plugins/`) - Plugin generation and marketplace validation.

### Skills Organization

By convention, skills are self-contained packages organized under `.github/skills/{collection-id}/{skill-name}/`. Each skill folder contains a `SKILL.md` file with domain-specific instructions, and may include other markdown files that are referenced by `SKILL.md` along with `scripts/`, `references/`, `assets/`, or other subdirectories.

### Documentation Structure

* HVE Guide (`docs/hve-guide/`) - Project lifecycle stages and role-specific guides.
  * Lifecycle (`docs/hve-guide/lifecycle/`) - AI-assisted project lifecycle stage documentation.
  * Roles (`docs/hve-guide/roles/`) - Role-specific guides for engineers, leads, architects, and other contributors.
* Getting Started (`docs/getting-started/`) - Installation and first workflow guides with multiple setup methods.
* RPI (`docs/rpi/`) - Task researcher, planner, and implementor workflow documentation.
* Contributing (`docs/contributing/`) - Guidelines for instructions, prompts, agents, and AI artifacts.
* Templates (`docs/templates/`) - Templates for custom agents, instructions, and prompts.

### Documentation Templates

Templates for agent and prompt outputs are stored in `docs/templates/`:

* `docs/templates/full-review-output-format.md` - Code review full output format.
* `docs/templates/standards-review-output-format.md` - Standards review output format.
* `docs/templates/engineering-fundamentals.md` - Engineering fundamentals reference.
* `docs/templates/user-journey-template.md` - User journey template.
* `docs/templates/adr-template-solutions.md` - Architecture decision record template.
* `docs/templates/rca-template.md` - Root cause analysis template.

The canonical Business Requirements Document template lives in `.github/skills/project-planning/requirements-author/templates/brd/brd-full.md` as part of the `requirements-author` skill.

### Copilot Tracking

The `.copilot-tracking/` directory (gitignored) contains AI-assisted workflow artifacts:

* Work Items (`.copilot-tracking/workitems/`) - ADO work item discovery and planning.
* Pull Requests (`.copilot-tracking/pr/`) - PR reference generation, handoff, and review tracking.
* Changes (`.copilot-tracking/changes/`) - Change tracking and implementation logs.
* Plans (`.copilot-tracking/plans/`) - Task implementation plans and planning logs.
* Details (`.copilot-tracking/details/`) - Task plan implementation details.
* Research (`.copilot-tracking/research/`) - Technical research findings and subagent research outputs.
* Reviews (`.copilot-tracking/reviews/`) - Review logs and validation findings.
* ADRs (`.copilot-tracking/adrs/`) - Architecture Decision Record drafts.
* BRD Sessions (`.copilot-tracking/brd-sessions/`) - Business requirements document session state.
* PRD Sessions (`.copilot-tracking/prd-sessions/`) - Product requirements document session state.
* GitHub Issues (`.copilot-tracking/github-issues/`) - GitHub issue search, triage, and workflow tracking.
* Sandbox (`.copilot-tracking/sandbox/`) - Prompt testing sandbox environments.
* Prompts (`.copilot-tracking/prompts/`) - Prompt updater tracking files.
* Documentation (`.copilot-tracking/documentation/`) - Documentation workflow session tracking.
* Memory (`.copilot-tracking/memory/`) - Cross-session memory files.
* Challenges (`.copilot-tracking/challenges/`) - Challenge session Q&A logs, unresolved items, and scope records from Task Challenger sessions.

All tracking files use markdown format with frontmatter and follow patterns from `.github/instructions/ado/ado-*.instructions.md`.

### Agents and Subagents

By convention, custom agents are organized under `.github/agents/{collection-id}/`. Each collection typically places its agents in a dedicated subdirectory (e.g., `.github/agents/hve-core/`, `.github/agents/ado/`). Subagents are typically organized under `.github/agents/{collection-id}/subagents/`.
Parent agents reference subagents using glob paths like `.github/agents/**/researcher-subagent.agent.md` so resolution works regardless of nesting depth.

Collection manifests in `collections/` define bundles of agents, prompts, instructions, and skills:

* Each collection has a YAML file (`*.collection.yml`) listing items with `path` and `kind` fields, and a markdown file (`*.collection.md`) describing the collection.
* Collections must include all subagent dependencies used by their referenced custom agents. When a parent agent declares subagents in its `agents:` frontmatter, those subagent files must appear in the collection YAML.
* When adding, updating, or removing prompt instructions, custom agents, subagents, or skills, update all affected `collections/*.collection.yml` and `collections/*.collection.md` files.
* After any change to collection YAML or markdown files, run `npm run plugin:generate` to regenerate plugin outputs under `plugins/`. Do not edit `plugins/` files directly.
* After any change to collection YAML or markdown files, also run `npm run extension:prepare` and `npm run extension:prepare:prerelease` to regenerate the per-collection extension READMEs and `package.*.json` manifests under `extension/`. Both regenerators are idempotent and exit 0 when inputs are unchanged.
* Run `npm run plugin:validate` to confirm collection metadata is correct.
<!-- </project-structure> -->

<!-- <script-operations> -->
## Script Operations

* Scripts follow instructions provided by the codebase for convention and standards.
* Scripts used by the codebase have an `npm run` script for ease of use.
* Files under the root `plugins/` directory are generated outputs and are not edited directly.
* Regenerate plugin outputs using `npm run plugin:generate`; this also runs `lint:md:fix` and `format:tables` as post-processing. Markdown files under `plugins/` can be symlinked or generated, so direct edits can cause conflicts and non-durable changes.
* Artifacts at the root of `.github/agents/`, `.github/instructions/`, `.github/prompts/`, or `.github/skills/` (without a subdirectory) are repo-specific and excluded from collection manifests, plugin generation, and extension packaging. Validation enforces this rule.

PowerShell scripts follow PSScriptAnalyzer rules from `scripts/linting/PSScriptAnalyzer.psd1` and include proper comment-based help. Validation runs via `npm run lint:ps` with results output to `logs/`.

### Commit Message Scopes

Commit message scopes map to repository directories:

* `(agents)` = `.github/agents/`
* `(prompts)` = `.github/prompts/`
* `(instructions)` = `.github/instructions/`
* `(skills)` = `.github/skills/`
* `(templates)` = `.github/ISSUE_TEMPLATE/`
* `(workflows)` = `.github/workflows/`
* `(extension)` = `extension/`
* `(scripts)` = `scripts/`
* `(docs)` = `docs/`
* `(collections)` = `collections/`
* `(adrs)` = Architecture Decision Records
* `(settings)` = Configuration files (`.vscode/`, linter configs)
* `(build)` = Build system and dependencies
* `(ci)` = CI/CD configuration changes

### Frontmatter Schema Validation

Frontmatter schemas are stored in `scripts/linting/schemas/`. Schema-to-file mapping is defined in `scripts/linting/schemas/schema-mapping.json`. Run `npm run validate:frontmatter` or `pwsh scripts/linting/Validate-MarkdownFrontmatter.ps1` to validate.

### PowerShell Conventions

* Copyright header validation: `scripts/linting/Test-CopyrightHeaders.ps1` (also used by bash scripts).
* Shared CI helpers module: `scripts/lib/Modules/CIHelpers.psm1`.
* Test directories follow the pattern `scripts/tests/{category}/Test-*.Tests.ps1`.
* Test organization mirrors source: `scripts/linting/` tests live in `scripts/tests/linting/`, `scripts/security/` tests live in `scripts/tests/security/`.

### Documentation Operations

The Documentation agent scans these directories for documentation coverage analysis:

* `docs/` - Primary documentation tree.
* `scripts/` - Script-level markdown files and inline documentation.
* `extension/` - Extension packaging documentation.
* `.github/` - Agent, prompt, instruction, and skill documentation.

Validation commands for documentation quality:

* `npm run lint:md` - Markdown linting.
* `npm run lint:frontmatter` - Frontmatter validation.
* `npm run lint:md-links` - Markdown link checking.
* Parse JSON output from `logs/` when available for structured validation results.
<!-- </script-operations> -->

<!-- <coding-agent-environment> -->
## Coding Agent Environment

Copilot Coding Agent uses a cloud-based GitHub Actions environment, separate from the local devcontainer. The `.github/workflows/copilot-setup-steps.yml` workflow pre-installs tools to match devcontainer capabilities.

### Pre-installed Tools

* Node.js 24 with npm dependencies from `package.json`
* Python 3.11
* uv and uvx for Python package management and skill dependency sync
* PowerShell 7 with PSScriptAnalyzer, PowerShell-Yaml, and Pester 5.7.1 modules
* shellcheck for bash script validation (pre-installed on ubuntu-latest)
* actionlint for GitHub Actions workflow validation
* cosign for artifact manifest signing

### Using npm Scripts

Agents should use npm scripts for all validation:

* `npm run lint:md` - Markdown linting
* `npm run lint:ps` - PowerShell analysis
* `npm run lint:yaml` - YAML validation
* `npm run lint:frontmatter` - Frontmatter validation
* `npm run lint:links` - Link language checking
* `npm run lint:md-links` - Markdown link checking
* `npm run lint:collections-metadata` - Collection metadata validation
* `npm run lint:version-consistency` - Action version consistency
* `npm run lint:marketplace` - Marketplace validation
* `npm run lint:py` - Python linting via ruff
* `npm run lint:models` - Model reference validation against catalog
* `npm run lint:models:refresh` - Refresh model catalog from upstream documentation
* `npm run lint:permissions` - Workflow permissions validation
* `npm run lint:dependency-pinning` - Dependency pinning and SHA staleness validation
* `npm run lint:all` - Run all linters (chains `format:tables`, `lint:md`, `lint:ps`, `lint:yaml`, `lint:json`, `lint:links`, `lint:frontmatter`, `lint:adr-consistency`, `lint:collections-metadata`, `lint:marketplace`, `lint:version-consistency`, `lint:permissions`, `lint:dependency-pinning`, `lint:ps-module-pins`, `lint:py`, `validate:skills`, `lint:ai-artifacts`, `lint:models`, `eval:lint:vally`, `eval:lint:schema`, `eval:lint:text`, `eval:lint:safety`, and `validate:devcontainer-lockfile`)
* `npm run validate:copyright` - Copyright header validation
* `npm run validate:devcontainer-lockfile` - Devcontainer lockfile integrity validation
* `npm run validate:devcontainer-changelog` - Devcontainer infrastructure change summary
* `npm run validate:skills` - Skill structure validation
* `npm run spell-check` - Spelling validation
* `npm run format:tables` - Markdown table formatting
* `npm run test:ps` - PowerShell tests
* `npm run test:py` - Python tests via pytest

### PowerShell Testing

PowerShell tests run exclusively through `npm run test:ps`. Never invoke Pester or test scripts directly.

Run specific tests by passing a `-TestPath` argument:

```bash
npm run test:ps -- -TestPath "scripts/tests/linting/"
npm run test:ps -- -TestPath "scripts/tests/security/Test-DependencyPinning.Tests.ps1"
```

Test results are always written to the `logs/` directory:

* `logs/pester-summary.json` - Overall pass/fail counts, duration, and result status.
* `logs/pester-failures.json` - Failure details including test name, file path, error message, and stack trace.

#### Inline execution protocol

Pipe output through `tail` to capture the summary:

```bash
npm run test:ps 2>&1 | tail -20
npm run test:ps -- -TestPath "scripts/tests/linting/" 2>&1 | tail -20
```

After the command completes, read `logs/pester-summary.json` to confirm overall status. If failures exist, read `logs/pester-failures.json` to identify which tests failed and why. If `logs/pester-summary.json` does not exist, review the terminal output for startup errors. Use tools that include ignored files when searching the `logs/` directory since it is gitignored.

### Python Skill Configuration

Python skills include a `pyproject.toml` validated by `validate:skills` via `Test-PythonSkillConfig`. Required and recommended sections:

* `[tool.ruff]` - Required. Enables `lint:py` compatibility across all Python skills.
* `[tool.ruff.lint]` - Recommended. Configures rule selection (e.g., `select = ["E", "F", "I", "W"]`).
* `[tool.pytest.ini_options]` - Required when the skill contains a `tests/` directory.
* `tests/fuzz_harness.py` - Required when the skill contains a `tests/` directory. Polyglot Atheris fuzz harness for OSSF Scorecard compliance.
* `fuzz` dependency group with `atheris>=3.0` - Required alongside `fuzz_harness.py`. Kept separate from `dev` (no macOS wheels).
* `python_files = ["test_*.py", "fuzz_harness.py"]` in `[tool.pytest.ini_options]` - Required alongside `fuzz_harness.py`. Enables pytest discovery.
* `ruff` in dev dependencies - Recommended. Ensures the linter is available in the skill's virtual environment.

### Environment Synchronization

The `copilot-setup-steps.yml` and `.devcontainer/scripts/on-create.sh` share most tools but differ intentionally: gitleaks is devcontainer-only (not needed during agent-driven development). When adding or removing tools in either environment, evaluate whether both need the change and update accordingly.
<!-- </coding-agent-environment> -->

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.
