From 699a0471c1f32e155fd04a1ac0a8a2baaa496106 Mon Sep 17 00:00:00 2001 From: Chris Grady <17553614+cgfixit@users.noreply.github.com> Date: Mon, 13 Jul 2026 09:22:08 -0400 Subject: [PATCH] Add Codex repo guidance and skills --- .codex/README.md | 30 ++++++++++ .codex/instructions.md | 8 +++ .codex/skills/code-optimizer/SKILL.md | 32 ++++++++++ .codex/skills/docs-runbook-sync/SKILL.md | 28 +++++++++ .codex/skills/pester-validation/SKILL.md | 46 +++++++++++++++ .../skills/proxy-maintenance-safety/SKILL.md | 29 +++++++++ AGENTS.md | 59 +++++++++++++++++++ 7 files changed, 232 insertions(+) create mode 100644 .codex/README.md create mode 100644 .codex/instructions.md create mode 100644 .codex/skills/code-optimizer/SKILL.md create mode 100644 .codex/skills/docs-runbook-sync/SKILL.md create mode 100644 .codex/skills/pester-validation/SKILL.md create mode 100644 .codex/skills/proxy-maintenance-safety/SKILL.md create mode 100644 AGENTS.md diff --git a/.codex/README.md b/.codex/README.md new file mode 100644 index 0000000..1c9edab --- /dev/null +++ b/.codex/README.md @@ -0,0 +1,30 @@ +# Codex Setup + +This directory contains repo-local Codex guidance for `cgfixit/sccm-veeam-proxy-patching`. + +## What This Repo Is + +A PowerShell 5.1-compatible maintenance helper for Veeam Backup & Replication VMware proxies during SCCM/ConfigMgr patching windows. The script disables selected VBR proxies, drains active backup tasks, remotely stops Veeam services, then starts services and re-enables proxies after patching. + +## First Files To Read + +- `AGENTS.md`: repo rules, validation commands, and safety posture. +- `README.md`: operator runbook, SCCM integration, requirements, and exit codes. +- `SECURITY.md`: vulnerability reporting and WinRM/service-account guidance. +- `sccmpatch.ps1`: production script. +- `tests/sccmpatch.Tests.ps1`: static Pester coverage. + +## Skills + +- `.codex/skills/code-optimizer/SKILL.md` +- `.codex/skills/proxy-maintenance-safety/SKILL.md` +- `.codex/skills/pester-validation/SKILL.md` +- `.codex/skills/docs-runbook-sync/SKILL.md` + +Use the smallest skill that matches the work. Most changes should need only `code-optimizer` or `pester-validation`. + +## Non-Goals + +- No live Veeam, WinRM, SCCM, or proxy operations during normal Codex validation. +- No new frameworks or dependencies for this one-script repo unless there is a concrete failing check that requires one. +- No broad rewrite of `sccmpatch.ps1` without a specific defect, measurable risk, or requested refactor. diff --git a/.codex/instructions.md b/.codex/instructions.md new file mode 100644 index 0000000..078f990 --- /dev/null +++ b/.codex/instructions.md @@ -0,0 +1,8 @@ +# Codex Runtime Instructions + +- Start with `AGENTS.md`; it is the repo contract. +- Before editing behavior, read the full `sccmpatch.ps1` flow and the matching tests. +- Default validation is static: parser check, Pester, and PSScriptAnalyzer when available. +- Never use a live proxy, VBR host, SCCM target, or WinRM command as a smoke test unless the user explicitly requests a live operational run. +- Keep production script changes PowerShell 5.1-compatible. +- Keep SCCM exit codes and README documentation in sync. diff --git a/.codex/skills/code-optimizer/SKILL.md b/.codex/skills/code-optimizer/SKILL.md new file mode 100644 index 0000000..1f9ecc4 --- /dev/null +++ b/.codex/skills/code-optimizer/SKILL.md @@ -0,0 +1,32 @@ +--- +name: code-optimizer +description: Optimize sccmpatch.ps1 while preserving Veeam proxy safety, SCCM exit codes, PowerShell 5.1 compatibility, and the repo validation path. +--- + +# Code Optimizer + +Use this skill for focused optimization or refactoring of `sccmpatch.ps1`. + +## Rules + +- Read `AGENTS.md`, `sccmpatch.ps1`, `tests/sccmpatch.Tests.ps1`, and the relevant README section first. +- Optimize one concrete issue at a time: duplicated logic, fragile null handling, slow polling, unclear error handling, or documentation drift. +- Preserve the SCCM exit-code contract unless tests and README change in the same PR. +- Preserve PowerShell 5.1 compatibility in production code. +- Do not add dependencies for simple parsing, logging, or validation. +- Do not replace static validation with live Veeam or WinRM testing. + +## Workflow + +1. State the narrow target and why it matters for production survivability. +2. Make the smallest code change that fixes the target. +3. Add or update one Pester/static assertion when behavior or contracts change. +4. Update README only when parameters, exit codes, operator steps, or failure modes change. +5. Run the parser check and Pester; run PSScriptAnalyzer if available. + +## Validation + +```powershell +pwsh -NoLogo -NoProfile -Command "$errors = $null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path './sccmpatch.ps1'), [ref]$null, [ref]$errors); if ($errors) { $errors | Format-List; exit 1 }" +pwsh -NoLogo -NoProfile -Command "Invoke-Pester -Path ./tests -Output Detailed" +``` diff --git a/.codex/skills/docs-runbook-sync/SKILL.md b/.codex/skills/docs-runbook-sync/SKILL.md new file mode 100644 index 0000000..d44a0b2 --- /dev/null +++ b/.codex/skills/docs-runbook-sync/SKILL.md @@ -0,0 +1,28 @@ +--- +name: docs-runbook-sync +description: Keep README, SECURITY, tests, and sccmpatch.ps1 aligned for SCCM/Veeam operator guidance, parameters, logs, and exit codes. +--- + +# Docs Runbook Sync + +Use this skill when script behavior, operator steps, parameters, logging, or exit codes change. + +## Sync Points + +- `README.md` must describe the current parameters, defaults, SCCM success/failure codes, and Pre/Post sequence. +- `SECURITY.md` must stay accurate for WinRM, service-account, execution-policy, and elevated-operation guidance. +- `tests/sccmpatch.Tests.ps1` must cover documented exit codes and key static safety guards. +- `sccmpatch.ps1` header comments should not contradict README operator guidance. + +## Workflow + +1. Compare `sccmpatch.ps1` parameters and exits against README tables. +2. Compare high-risk operational behavior against SECURITY guidance. +3. Update the smallest set of docs/tests needed to remove drift. +4. Run parser and Pester checks when tests or script contracts change. + +## Do Not + +- Add marketing copy. +- Add unsupported live-run claims. +- Document operator steps that the script does not actually implement. diff --git a/.codex/skills/pester-validation/SKILL.md b/.codex/skills/pester-validation/SKILL.md new file mode 100644 index 0000000..53fa4bd --- /dev/null +++ b/.codex/skills/pester-validation/SKILL.md @@ -0,0 +1,46 @@ +--- +name: pester-validation +description: Run and interpret the repo's PowerShell parser, Pester, PSScriptAnalyzer, and GitHub Actions validation for sccmpatch.ps1 changes. +--- + +# Pester Validation + +Use this skill when validating edits or diagnosing failed checks. + +## Local Checks + +Run the parser check first because it is cheap and catches syntax regressions: + +```powershell +pwsh -NoLogo -NoProfile -Command "$errors = $null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path './sccmpatch.ps1'), [ref]$null, [ref]$errors); if ($errors) { $errors | Format-List; exit 1 }" +``` + +Run Pester next: + +```powershell +pwsh -NoLogo -NoProfile -Command "Invoke-Pester -Path ./tests -Output Detailed" +``` + +If installed locally, run analyzer: + +```powershell +pwsh -NoLogo -NoProfile -Command "Invoke-ScriptAnalyzer -Path . -Recurse" +``` + +## CI Checks + +Expected workflows: + +- `Pester Tests` +- `PSScriptAnalyzer` +- `CodeQL Advanced` +- `Dependency review` on pull requests + +Use GitHub Actions logs for failures; do not infer root cause from workflow names alone. + +## Failure Handling + +- Parser failure: fix syntax first. +- Pester failure: update script or test so the documented contract is true. +- Analyzer failure: prefer changing the script over suppressing rules. +- Missing local modules: report as an environment limitation and rely on CI if the workflow has the required action/tool. diff --git a/.codex/skills/proxy-maintenance-safety/SKILL.md b/.codex/skills/proxy-maintenance-safety/SKILL.md new file mode 100644 index 0000000..149e05f --- /dev/null +++ b/.codex/skills/proxy-maintenance-safety/SKILL.md @@ -0,0 +1,29 @@ +--- +name: proxy-maintenance-safety +description: Review changes that can affect Veeam proxy drain, service stop/start, WinRM, SCCM exit codes, or backup-infrastructure availability. +--- + +# Proxy Maintenance Safety + +Use this skill for safety review of production-impacting changes. + +## Review Checklist + +- `Pre` stage disables only the selected VBR proxy objects and waits for matching active tasks to drain. +- Drain logic does not interrupt active backups or treat unrelated running tasks as safe to ignore without evidence. +- Timeout behavior exits `30` and leaves enough log evidence for SCCM operators. +- Remote service stop/start uses explicit proxy targets and does not broaden to non-target hosts. +- `Post` stage attempts service start before proxy re-enable and preserves exit `60` for re-enable failure. +- Reboot detection remains scoped to the script host, not remote proxies. +- Logs do not expose credentials, tokens, or environment secrets. +- README and tests match any changed parameter, exit code, or operator action. + +## Output + +Lead with a verdict: + +- `PASS`: no blocking production-safety issue found. +- `BLOCKED`: change can disrupt backup infrastructure, hide failure, or strand disabled proxies. +- `PARTIAL`: static evidence is acceptable, but live-environment behavior still needs operator validation. + +Keep findings file/line grounded and specific. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..18714d9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,59 @@ +# Repository Instructions + +Scope: this file applies to the whole repository. + +## Project Facts + +- This repo is a single-script PowerShell tool for SCCM/ConfigMgr-driven maintenance of Veeam VMware backup proxies. +- Production entrypoint: `sccmpatch.ps1`. +- Static tests live in `tests/sccmpatch.Tests.ps1`. +- CI runs PSScriptAnalyzer, Pester, CodeQL for Actions, and dependency review. +- The script is intended for PowerShell 5.1+ and Veeam Backup & Replication 12.3.2+. +- The operational contract is the SCCM exit-code set: `0`, `3010`, `10`, `20`, `30`, `40`, `50`, `60`, `90`, `99`. + +## Safety Rules + +- Treat `-Stage Pre`, `-Stage Post`, WinRM, Veeam proxy enable/disable, and Veeam service stop/start as production-impacting operations. +- Do not run `sccmpatch.ps1` against real proxy names, VBR servers, or production hosts unless the user explicitly asks for a live run and supplies the target environment. +- Preserve the exit-code contract unless README, tests, and SCCM guidance are updated in the same change. +- Preserve PowerShell 5.1 compatibility in `sccmpatch.ps1`. Avoid PowerShell 7-only syntax in production code. +- Do not hardcode customer hostnames, credentials, tokens, domains, IPs, or service-account names. +- Keep logs useful for SCCM troubleshooting, but do not log secrets or credential material. +- Prefer small, auditable changes. This script controls backup infrastructure; broad rewrites are high risk. + +## Validation Commands + +Use the narrowest validation that matches the change. + +```powershell +pwsh -NoLogo -NoProfile -Command "$errors = $null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path './sccmpatch.ps1'), [ref]$null, [ref]$errors); if ($errors) { $errors | Format-List; exit 1 }" +pwsh -NoLogo -NoProfile -Command "Invoke-Pester -Path ./tests -Output Detailed" +``` + +If PSScriptAnalyzer is installed locally: + +```powershell +pwsh -NoLogo -NoProfile -Command "Invoke-ScriptAnalyzer -Path . -Recurse" +``` + +For GitHub-side status: + +```powershell +gh run list --repo cgfixit/sccm-veeam-proxy-patching --limit 5 +``` + +## Codex Skills + +Repo-local skills live under `.codex/skills/`: + +- `code-optimizer`: optimize `sccmpatch.ps1` without breaking Veeam/SCCM safety contracts. +- `proxy-maintenance-safety`: review production-impacting maintenance changes. +- `pester-validation`: run and interpret parser, Pester, and analyzer checks. +- `docs-runbook-sync`: keep README, SECURITY, tests, and script behavior aligned. + +## Change Workflow + +1. Read `sccmpatch.ps1`, `tests/sccmpatch.Tests.ps1`, `README.md`, and `SECURITY.md` before changing behavior. +2. For code changes, update or add the smallest static test that would fail if the contract regresses. +3. For parameter, exit-code, log, or operational behavior changes, update README/runbook guidance in the same PR. +4. Use a branch and PR for repository changes. Do not push directly to `main` unless explicitly requested.