Build System and Validation

Plugin Generation Pipeline

The plugin generation pipeline transforms collection manifests into distributable plugin output. It runs in three 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. lint:md:fix applies markdownlint auto-fixes to generated markdown files.

3. format:tables aligns markdown table columns in generated output.

Run the full pipeline with a single command:

npm run plugin:generate

IMPORTANT

Files under plugins/ are generated output. Do not edit them directly. Changes made to plugin files are overwritten on the next generation run.

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.

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:collections-metadata	npm run lint:collections-metadata	Collection manifest validation
lint:marketplace	npm run lint:marketplace	Marketplace manifest validation
lint:version-consistency	npm run lint:version-consistency	GitHub Action version consistency
lint:permissions	npm run lint:permissions	Workflow permissions validation

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:links checks link text language patterns
6. lint:frontmatter validates YAML frontmatter against schemas
7. lint:collections-metadata confirms collection manifest integrity
8. lint:marketplace validates marketplace manifest
9. lint:version-consistency checks GitHub Action version alignment
10. lint:permissions validates workflow permissions
11. validate:skills verifies skill directory structure

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

TIP

Run lint:all before pushing to catch issues that CI would flag. Individual linters provide faster feedback when you know which validation applies to your changes.

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.