README.md

August 13, 2026 · View on GitHub

Computes deterministic activation fingerprints for VS Code Copilot custom agents and asserts cold-start byte budgets via Pester.

Purpose

The harness models how VS Code Copilot loads a custom agent at activation time and measures the resulting context payload (agent file + every file pulled in via #file: directives or applyTo auto-attach). It produces a JSON-serializable fingerprint that can be diffed across refactors to prove that intended size reductions actually shipped and that no instruction file silently re-attached.

Public Surface

Get-AgentActivationFingerprint -AgentPath <string> -ScenarioName <string> [-RepoRoot <string>]

Returns:

@{
  ScenarioName   = '<scenario>'
  AgentBytes     = <int>
  ColdStartBytes = <int>           # total bytes loaded for this scenario
  LoadedFiles    = @(@{ Path = '<repo-relative>'; Bytes = <int> })
  Hash           = '<sha256 hex>'  # over deterministic Path:Bytes tuples
}

Scenarios

Scenario	Models	Loads
`CleanWorkspace`	Cold start with no editor file matching any `applyTo` glob.	Agent file + every `#file:` directive in the agent body.
`SteadyState`	Editor working inside `.copilot-tracking/adr-plans/`.	`CleanWorkspace` payload + every instruction whose `applyTo` covers ADR working directories.
`GovernEntry`	Agent transitioning into the Govern lifecycle phase.	`SteadyState` payload + `#file:` references in Lifecycle Dispatch Table rows tagged `Govern`.
`AdoptTemplate`	Agent operating in adopt-template entry mode (Table B).	`SteadyState` payload + `#file:` references in Table B rows tagged `Ingest`, `Normalize`, `Derive`, or `Fill`.

Byte-Budget Contract

The cold-start payload (CleanWorkspace.ColdStartBytes) is the gating budget for every agent governed by this harness. Budgets are declared as a range in budgets.json rather than a single number, so that growth in shared instruction files does not fail an unrelated change:

Band	Meaning	Suite result
At or below `target`	Within design intent.	Pass
Above `target`, at ceiling	Within tolerance; absorbs growth in shared instruction files.	Pass with warning
Above `ceiling`	Budget violation.	Fail

Pre-refactor baseline for @adr-creation is approximately 84 KB and recorded in baseline.json.
Post-refactor target is 44,000 bytes with a ceiling of 48,000 bytes.
Every range entry carries a rationale explaining why the ceiling sits above the target. The suite asserts that the rationale is present and that ceiling is not below target.
The Pester suite under scripts/tests/agents/activation-harness/ also fails when an instruction file expected to remain off cold start (for example adr-handoff.instructions.md, adr-byo-template.instructions.md) appears in LoadedFiles.

Raise a ceiling only when the growth comes from a shared file the agent does not own. Growth caused by the agent's own design belongs below target.

Usage

Run the full suite via the npm wrapper:

npm run test:activation

This suite validates the activation contract, including cold-start byte budget, lifecycle load-set composition, scenario distinctness, and runner artifacts. It does not fail on exact baseline.json hash or byte-count drift.

Drive the module directly:

Import-Module ./scripts/agents/activation-harness/Get-AgentActivationFingerprint.psm1 -Force
Get-AgentActivationFingerprint `
    -AgentPath '.github/agents/project-planning/adr-creation.agent.md' `
    -ScenarioName 'CleanWorkspace'

Regenerating `baseline.json`

baseline.json is the exact snapshot reference for explicit drift audits. After an intentional change to the agent, to any instruction file it loads, or to any skill file pulled into its load-set (for example an adr-author skill script or asset reached via #file:), use the scripted checks rather than hand-editing the file:

# Drift check with no writes. Exits 1 when the snapshot is out of date.
npm run test:activation:baseline:check

# Recapture the baseline with byte-identical formatting
npm run test:activation:baseline

Note

Any change to ADR agent, instruction, or skill files that the harness loads can invalidate baseline.json. Run npm run test:activation:baseline:check when you need an exact no-write snapshot audit. Run npm run test:activation:baseline only when the drift is intentional and the committed reference should be refreshed.

Workflow:

Make the intentional change to the agent, instruction, or skill files.
Run npm run test:activation to confirm the behavior and invariant suite still passes.
Run npm run test:activation:baseline:check when the PR needs an exact snapshot drift audit.
Run npm run test:activation:baseline to rewrite baseline.json when the drift is intentional.
Commit the baseline update alongside the originating agent, instruction, or skill change.

Files

Get-AgentActivationFingerprint.psm1: public module exposing the single fingerprint function.
Update-AgentActivationBaseline.ps1: regenerates baseline.json deterministically; supports -DryRun for CI drift gating.
baseline.json: pre-refactor reference fingerprints across all four scenarios for @adr-creation.
budgets.json: per-agent, per-scenario cold-start byte ranges with target, ceiling, and rationale.
README.md: this document.

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