build-system.md

Plugin Generation Pipeline

The plugin generation pipeline transforms collection manifests into distributable plugin output. The plugin:generate script runs two stages:

1. Generate-Plugins.ps1 reads each collections/*.collection.yml manifest and produces output files under plugins/. Each collection gets its own subdirectory (e.g., plugins/hve-core/, plugins/ado/).

2. plugin:postprocess applies markdownlint auto-fixes (markdownlint-cli2 --fix) and aligns markdown table columns (markdown-table-formatter) across the generated plugins/** and collections/*.md output.

Run the full pipeline with a single command:

npm run plugin:generate

Schema Validation System

YAML frontmatter in markdown files is validated against JSON schemas stored in scripts/linting/schemas/. The validation system uses glob-based pattern matching to determine which schema applies to each file.

Schema Files

Schema	Applies To
docs-frontmatter.schema.json	docs/**/*.md
instruction-frontmatter.schema.json	.github/**/*.instructions.md
agent-frontmatter.schema.json	.github/**/*.agent.md
prompt-frontmatter.schema.json	.github/**/*.prompt.md
skill-frontmatter.schema.json	.github/skills/**/SKILL.md
chatmode-frontmatter.schema.json	.github/**/*.chatmode.md
collection-manifest.schema.json	Collection YAML manifests
root-community-frontmatter.schema.json	Root files (README, CONTRIBUTING)
base-frontmatter.schema.json	Default fallback

Pattern Mapping

The scripts/linting/schemas/schema-mapping.json file defines the glob-to-schema mapping. Patterns are evaluated from most specific to least specific, and the first match determines the schema. When no pattern matches, base-frontmatter.schema.json applies as the default.

Adding Custom Schemas

To add validation for a new file type:

1. Create a JSON schema file in scripts/linting/schemas/
2. Add a mapping entry to schema-mapping.json with the glob pattern, scope name, and schema filename
3. Run npm run lint:frontmatter to verify the new schema validates correctly

npm Scripts Reference

All validation, formatting, and testing operations run through npm scripts defined in package.json. The table below groups scripts by purpose. These tables are representative of the most commonly used scripts rather than an exhaustive list; consult package.json for the complete set.

Linting

Script	Command	Description
lint:all	npm run lint:all	Runs all linters in sequence
lint:md	npm run lint:md	Markdown linting via markdownlint-cli2
lint:md:fix	npm run lint:md:fix	Markdown linting with auto-fix
lint:ps	npm run lint:ps	PowerShell analysis via PSScriptAnalyzer
lint:yaml	npm run lint:yaml	YAML syntax and structure validation
lint:links	npm run lint:links	Link language checking
lint:md-links	npm run lint:md-links	Markdown link target validation
lint:frontmatter	npm run lint:frontmatter	Frontmatter schema validation
lint:json	npm run lint:json	JSON syntax validation
lint:adr-consistency	npm run lint:adr-consistency	ADR structure and consistency checks
lint:collections-metadata	npm run lint:collections-metadata	Collection manifest validation
lint:marketplace	npm run lint:marketplace	Marketplace manifest validation
lint:hooks	npm run lint:hooks	Hook manifest validation
lint:version-consistency	npm run lint:version-consistency	GitHub Action version consistency
lint:permissions	npm run lint:permissions	Workflow permissions validation
lint:models	npm run lint:models	Model reference validation against catalog

Validation

Script	Command	Description
validate:copyright	npm run validate:copyright	Copyright header presence check
validate:skills	npm run validate:skills	Skill directory structure validation

Formatting

Script	Command	Description
format:tables	npm run format:tables	Markdown table column alignment

Testing

Script	Command	Description
test:ps	npm run test:ps	PowerShell Pester test suite

Plugin and Extension

Script	Command	Description
plugin:generate	npm run plugin:generate	Generate plugins, auto-fix markdown, format tables
plugin:validate	npm run plugin:validate	Validate collection metadata (alias)
extension:prepare	npm run extension:prepare	Prepare VS Code extension for packaging
extension:prepare:prerelease	npm run extension:prepare:prerelease	Prepare extension for pre-release
extension:package	npm run extension:package	Package VS Code extension
extension:package:prerelease	npm run extension:package:prerelease	Package extension as pre-release

Linting Pipeline

The lint:all script chains every linter in a fixed sequence:

1. format:tables aligns markdown table columns
2. lint:md checks markdown style rules (.markdownlint.json)
3. lint:ps analyzes PowerShell scripts (PSScriptAnalyzer.psd1)
4. lint:yaml validates YAML file syntax
5. lint:json validates JSON syntax
6. lint:links checks link text language patterns
7. lint:frontmatter validates YAML frontmatter against schemas
8. lint:adr-consistency checks ADR structure and consistency rules
9. lint:collections-metadata confirms collection manifest integrity
10. lint:marketplace validates marketplace manifest
11. lint:hooks validates hook manifests
12. lint:version-consistency checks GitHub Action version alignment
13. lint:permissions validates workflow permissions
14. lint:dependency-pinning checks dependencies are pinned to fixed versions
15. lint:ps-module-pins checks PowerShell module versions are pinned
16. lint:py lints Python scripts via Invoke-PythonLint.ps1
17. validate:skills verifies skill directory structure
18. lint:ai-artifacts validates planner AI artifacts
19. lint:models validates model references against the catalog
20. validate:devcontainer-lockfile checks devcontainer lockfile integrity
21. eval:lint:vally lints Vally eval specs
22. eval:lint:schema validates eval schema conformance
23. eval:lint:text checks eval text content
24. eval:lint:safety validates eval safety stimuli

Each linter outputs results to logs/ for inspection. Run individual linters for faster feedback during development:

npm run lint:md -- docs/customization/collections.md

CI Validation

Pull request validation runs linters in parallel CI jobs. Each job executes one or more npm scripts from the list above. To reproduce CI checks locally, run the same npm scripts against your changed files.

Full local validation:

npm run lint:all

Targeted validation for specific files:

npm run lint:md -- path/to/changed-file.md
npm run lint:frontmatter

Customizing Validation

Markdown Rules

Configure markdownlint rules in .markdownlint.json at the repository root. Each rule maps to a markdownlint rule ID (e.g., MD013 for line length). Disable rules by setting them to false, or customize parameters such as line length limits.

PowerShell Analysis

PSScriptAnalyzer rules are configured in scripts/linting/PSScriptAnalyzer.psd1. Add or exclude rules to match your team's PowerShell coding standards. Run analysis with:

npm run lint:ps

Results appear in logs/psscriptanalyzer-results.json and logs/psscriptanalyzer-summary.json.

Custom Validation Scripts

Add new validation scripts to scripts/linting/ and register them as npm scripts in package.json. Follow the existing pattern: scripts accept file paths or glob patterns as input and write structured results to logs/.

To include a new linter in the full pipeline, add it to the lint:all chain in package.json.

Role Scenarios

Northwind Traders' SRE/Operations lead runs npm run lint:all as a pre-push hook to catch markdown formatting issues, broken links, and frontmatter schema violations before they reach CI. When a new deployment instruction file needs custom frontmatter fields, the lead adds a schema to scripts/linting/schemas/ and registers the pattern in schema-mapping.json.

Adventure Works' security architect extends the validation pipeline with a custom script that checks instruction files for required security disclaimer sections. The script follows the existing pattern of writing JSON results to logs/ and integrates into the lint:all chain through package.json.

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