Maintain the adapter.
Preserve the method.

A useful contribution starts with a reproducible boundary.

1. Describe the actual behavior

   Open an issue or pull request with expected versus observed behavior, the library version, artifact release/commit, selected profile, and a minimal reproduction. Redact credentials, private project content, provider responses, and personal data.

2. Change the adapter, not a second copy of HVE Squad

   Keep charters, skills, and instructions in their upstream projects. Changes here should acquire and interpret released contracts, implement native host mechanisms, or improve tests and documentation. A new capability needs real implementation, not only prompt text.

3. Prove both success and refusal paths

   Use scripted IChatClient tests for deterministic behavior. Include denial, unanswered input, missing roster roles, changed evidence, interrupted execution, and invalid state where relevant. Keep live-model evaluations distinct from contract tests.

4. Make the review easy

   Keep the change focused, update affected docs and runnable examples, and explain compatibility or state implications. Do not put generated packages, credentials, or customer state into a pull request. Use the repository's private security-reporting mechanism if available for sensitive findings rather than publishing exploitable details in an issue.

The repository uses .NET analyzers and treats warnings as errors. Preserve that baseline and avoid suppressions that merely hide broken contracts.

Build, test, and pack locally

Set-Location C:\Solutions\hve-squad-maf
dotnet restore HveSquad.AgentFramework.slnx
dotnet build HveSquad.AgentFramework.slnx --configuration Release
dotnet test HveSquad.AgentFramework.slnx --configuration Release
dotnet pack src\HveSquad.AgentFramework --configuration Release --output artifacts

The pack command produces artifacts\HveSquad.AgentFramework.0.1.0-preview.1.nupkg at the current preview version. It does not publish anything. Validate both the project reference and the local package feed consumption path before changing packaging.

Exercise the real released contracts

Install Git and APM 0.18.0, then run the release-compatibility category. These checks use a scripted model rather than paid inference, but need network for release acquisition.

$env:HVE_SQUAD_RELEASE_VERSION = "v0.16.2"
$env:HVE_SQUAD_REQUIRE_RELEASE_TESTS = "true"
dotnet test tests\HveSquad.AgentFramework.Tests `
  --configuration Release --filter Category=ReleaseCompatibility

$env:HVE_SQUAD_RELEASE_VERSION = "latest"
dotnet test tests\HveSquad.AgentFramework.Tests `
  --configuration Release --filter Category=ReleaseCompatibility

Remove-Item Env:\HVE_SQUAD_RELEASE_VERSION
Remove-Item Env:\HVE_SQUAD_REQUIRE_RELEASE_TESTS

For an already installed artifact tree, use HVE_SQUAD_RELEASE_ROOT pointing to the directory containing .github and .agents. Unset conflicting selectors when switching test modes. A passing contract suite is not a claim about live-model quality, all provider adapters, deployment safety, or full Copilot parity.

Two independent update streams

• Keep the known-good release test and the latest-stable test. Update the known pin only after reviewing the new contract and testing default/full-profile behavior.
• Do not upgrade an existing project's native conversation silently. Preserve its original release, fingerprint, and roster, or design an explicit reviewed migration.
• Review Dependabot PRs for GitHub Actions and NuGet. Scheduled update proposals do not imply automatic merge or release approval.
• Keep third-party actions pinned to reviewed commit SHAs and tool versions controlled. Review permission changes, new egress, and output publication separately.
• Update these docs when catalog names, source semantics, callbacks, effect rules, sample flags, or workflow names change.

Workflow inventory and activation

Workflow files define intended checks. They do not prove a successful run, enable repository settings, or provide a security certification. Inspect the actual Actions results and repository feature availability.

Repository setup is still a human action

• Allow the intended Actions and verify required checks complete before adding them to branch protection or rulesets. Workflow YAML does not activate those rulesets.
• Enable dependency graph and code-scanning features where the repository's visibility and plan support them. CodeQL has its own analysis/upload path.
• Enable GitHub secret scanning and push protection where available. Checkov's secrets scan complements those repository features; it does not enable or replace them.
• Checkov and Zizmor always retain scan reports. Their code-scanning uploads are opt-in through the repository Actions variable SECURITY_SARIF_UPLOAD=true on trusted main runs. Review availability and publication policy before enabling it.
• Review findings and scan execution errors. A suppressed check, missing feed, or failed analyzer must not be represented as a clean result.
• Do not publish public score badges or claim a score without a real configured publication policy and observed assessment.

Publish a version to NuGet.org

This is the maintainer procedure for making the library available to other application developers. Preview does not mean source-only: a prerelease such as 0.1.0-preview.1 can be published to NuGet.org and installed by exact version. It stays marked prerelease until you intentionally publish a stable version.

1. Establish the package owner

1. Create or sign in to a NuGet.org account. GitHub repository ownership does not create NuGet ownership.
2. Check whether HveSquad.AgentFramework is available or already owned by your account/organization. Do not assume a package ID is reserved because a project file has that name. If another owner holds it, resolve ownership or choose a different ID before publishing.
3. For a team-owned package, choose the intended NuGet organization and add the appropriate owners. Review who can publish new versions. The Authors metadata field is not the access-control list.

2. Choose the integration version, not the HVE artifact version

For the first publication, keep 0.1.0-preview.1 if it is still unused and accurately represents the candidate. For the next publication, update the project file to a new unused version, update release notes and documentation, then review and commit those changes. An already published package ID/version cannot be overwritten or recycled. A new upstream artifact release does not automatically publish a new library version.

Before packing, review the package ID, description, authors, license, repository URL, README rendering, and supported runtime contract. Use absolute public URLs for any README assets/links that do not render in NuGet's preview. Test the package through the local-feed consumer path. Do not bundle credentials, case data, build reports, or acquired upstream artifacts into the package.

3. Build and identify the exact candidate

Run from a clean, reviewed integration checkout. The commands read the effective library version rather than accidentally pushing every package left in artifacts. Complete the known-release and latest-stable compatibility commands above before publication; check the security workflows for the same commit.

Set-Location C:\Solutions\hve-squad-maf
$ErrorActionPreference = "Stop"
$project = "src\HveSquad.AgentFramework\HveSquad.AgentFramework.csproj"
$changes = git status --porcelain
if ($LASTEXITCODE -ne 0 -or $changes) {
    throw "Prepare a clean, reviewed commit before packaging for publication."
}
$commit = git rev-parse HEAD
if ($LASTEXITCODE -ne 0) { throw "Cannot resolve the release commit." }
$version = (dotnet msbuild $project -nologo -getProperty:Version).Trim()
if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($version)) {
    throw "Cannot resolve the NuGet package version."
}
$output = Join-Path $PWD "artifacts\$version"
if (Test-Path -LiteralPath $output) {
    throw "Candidate output already exists. Inspect it before deliberately rebuilding."
}

dotnet test HveSquad.AgentFramework.slnx --configuration Release --nologo
if ($LASTEXITCODE -ne 0) { throw "Build or tests failed." }
dotnet pack $project --configuration Release --output $output `
    -p:ContinuousIntegrationBuild=true -p:RepositoryCommit=$commit
if ($LASTEXITCODE -ne 0) { throw "Package creation failed." }

$package = Join-Path $output "HveSquad.AgentFramework.$version.nupkg"
if (-not (Test-Path -LiteralPath $package)) { throw "Expected package is missing." }
Get-Item -LiteralPath $package | Select-Object Name, Length
Get-FileHash -LiteralPath $package -Algorithm SHA256

Retain the candidate's commit, version and SHA-256 for the release record. Inspect the package manifest and files, and install that candidate into a separate consumer app. If you changed the package ID, update the expected filename and every consumer command accordingly. Do not publish an older root-level package merely because it has the right-looking name.

4. Publish through the portal or CLI

Portal route, suitable for the first release: open NuGet.org Upload, choose the exact candidate .nupkg, review ownership, metadata, dependencies and README preview, then select Submit only when ready to publish. This requires no API key in your terminal. The portal can also upload later versions of a package you own.

CLI route: create a short-expiry NuGet API key scoped to HveSquad.AgentFramework. The first publication needs permission to push a new package; later keys should be limited to pushing new versions of that package. Have a secret manager inject NUGET_API_KEY into this process without echoing it, writing it in source, or typing its value into shell history.

The following uses the environment-variable support in NuGet 7.6 / .NET SDK 10.0.300 or later, avoiding an API key in command-line arguments. It uses $package from the preparation step in the same PowerShell session. Older SDK users should use the portal or upgrade, not add a credential literal to the command.

if ([string]::IsNullOrWhiteSpace($env:NUGET_API_KEY)) {
    throw "Provision a package-scoped NUGET_API_KEY securely before publication."
}
if (-not $package -or -not (Test-Path -LiteralPath $package)) {
    throw "Prepare and verify the exact candidate package first."
}
try {
    dotnet nuget push $package --source https://api.nuget.org/v3/index.json
    if ($LASTEXITCODE -ne 0) { throw "NuGet rejected the publication." }
}
finally {
    Remove-Item Env:\NUGET_API_KEY -ErrorAction SilentlyContinue
}

No wildcard or --skip-duplicate is used: a conflict is not proof that this candidate was published. If a version already exists, inspect it and choose a new version for different bytes. Unlisting a bad release does not make its version reusable.

5. Verify availability, then give consumers the package command

Wait for NuGet validation and indexing. Check the package's Manage Packages status and the version-specific page; use a fresh consumer to restore the exact version from NuGet.org without the local candidate feed. Package validation failure or indexing delay is not a reason to claim success. Once 0.1.0-preview.1 has actually been published and validated, the consumer path becomes:

dotnet add C:\apps\BidPortal\BidPortal.csproj package HveSquad.AgentFramework `
    --version 0.1.0-preview.1 --source https://api.nuget.org/v3/index.json

Replace the example application path and version with real ones. Consumers then use AddHveSquad or SquadRuntime.CreateAsync in their existing .NET/MAF app; they no longer need to clone this integration repository. They still provide a compatible model client, host callbacks and case storage, plus Git/APM during upstream artifact acquisition or an explicitly provisioned complete artifact tree. There is no required Copilot plugin, Copilot subscription or separate HVE Squad MCP server.

After successful publication, update the site and README to distinguish a published prerelease from an unpublished preview. Record the NuGet version, source commit and tested HVE artifact release in the release notes. A GitHub tag or release is useful provenance, but never a substitute for checking NuGet.

6. Optional automation with trusted publishing

The manual procedure above works without adding a publishing workflow. For repeatable CI publication, NuGet trusted publishing can exchange GitHub OIDC identity for a short-lived API key. No publishing workflow is installed by this documentation change. A future publish-nuget.yml must be reviewed before enabling its external write.

1. Create the protected GitHub environment and restrict authorized branches/tags and reviewers. Use a manually dispatched, immutable release candidate; never publish from pull-request code.
2. On NuGet.org, open your account's Trusted Publishing settings and create the matching scoped policy. The NuGet profile username is not necessarily the GitHub username or an email address.
3. Build and validate the exact candidate in an unprivileged job. After environment approval, grant only the publishing job id-token: write and the permissions needed to obtain that candidate.
4. Use the official NuGet/login action pinned to a reviewed commit. Its user input identifies the NuGet profile; exchange OIDC shortly before publication. Supply the returned temporary key through NUGET_API_KEY on the push step, using a sufficiently recent .NET SDK.
5. Push one explicitly selected package, reject duplicate-version surprises, and verify registry publication before marking the release complete. Keep Pages deployment, artifact acquisition and NuGet publishing as separate operations.

Sources: Microsoft's NuGet publication guide, trusted publishing setup, and dotnet nuget push reference.

Activate and maintain GitHub Pages

1. Review the public content

   The site consists of top-level docs\*.html, shared docs\assets, and .nojekyll. It has no build dependencies, external fonts, CDNs, analytics, or runtime credentials. Keep project data, reports, and native state out of the published surface.

2. Enable publishing in GitHub

   In the repository, open Settings → Pages → Build and deployment and set Source: GitHub Actions. Review the github-pages environment and its deployment protections. These settings are not activated merely by adding workflow files.

3. Run the Pages workflow from main

   docs.yml stages only top-level HTML and permitted assets, creates a static Pages artifact, and deploys it. The configure-pages step expects Pages to be enabled already. Review the run and use its actual deployment URL.

4. Check the project-path deployment

   The expected project URL, once enabled and successfully deployed, is https://peter-n91.github.io/hve-squad-maf/. This is an expected URL, not a claim that the site is already live. Relative links keep navigation and assets working under /hve-squad-maf/.

Documentation change checklist

• Maintain all seven pages and the shared navigation together. Mark only the current page with aria-current="page".
• Use relative local links such as assets/site.css, not root paths such as /assets/site.css.
• Check light/dark themes, keyboard navigation, mobile menu, skip link, copy feedback, code overflow, and heading structure. All reading and navigation must remain available without JavaScript.
• Keep the original community logo and disclosure. It is a family-inspired MAF variant, not an official Microsoft mark or endorsement.
• Compare copyable commands and API examples to the sample and source. Distinguish future designs from implemented features.
• Test every page and local anchor before deployment. No Node-based site generator or package installation is required for these static files.