winutil/AGENTS.md

AGENTS.md

Drop-in operating instructions for coding agents. Read this file before every task.

Working code only. Finish the job. Plausibility is not correctness.

This repository follows the AGENTS.md convention: these instructions are for Codex, Claude Code, Cursor, Windsurf, Copilot, Aider, Devin, Amp, and other coding agents that read AGENTS.md.

0. Non-Negotiables

These rules override everything else in this file when in conflict:

1. Do not edit winutil.ps1 directly. It is generated build output. Change source files and compile.
2. Do not commit winutil.ps1. It is ignored locally and generated by GitHub Actions for releases.
3. Never fabricate. Do not invent file paths, function names, command output, test results, commit hashes, or API behavior. Read the file or run the command.
4. Disagree when the premise is wrong. Say what is wrong before acting on it.
5. Stop when genuinely ambiguous. If two interpretations would produce materially different diffs, ask before editing.
6. Touch only what the task requires. No drive-by refactors, formatting sweeps, or unrelated cleanup.
7. Verify before saying done. A plausible-looking diff is not proof.

1. Project Context

WinUtil is a Windows PowerShell utility with a WPF interface. The repository is maintained as modular source, but the distributed artifact is one compiled PowerShell script.

Stack

• Language: Windows PowerShell / PowerShell.
• UI: WPF via xaml/inputXML.xaml.
• Configuration: JSON files under config/.
• Tests: Pester tests under pester/.
• Lint: PowerShell Script Analyzer with settings in lint/PSScriptAnalyser.ps1.
• Docs: Hugo site under docs/.
• Release artifact: generated root winutil.ps1.

Key Commands

• Compile:

  .\Compile.ps1
  

• Compile and run GUI:

  .\Compile.ps1 -Run
  

• Run tests:

  Import-Module Pester -RequiredVersion 5.8.0 -Force
  Invoke-Pester -Path 'pester/*.Tests.ps1' -Output Detailed
  

• Run Script Analyzer with project settings when available:

  Invoke-ScriptAnalyzer -Path . -Settings .\lint\PSScriptAnalyser.ps1 -Recurse
  

Prefer the narrowest useful verification while iterating. Use the full relevant check before finishing.

2. Source Of Truth

Make durable changes only in files consumed by Compile.ps1 or in documentation/test files:

• scripts/start.ps1 for startup/bootstrap code.
• functions/public/*.ps1 for UI-facing and user-facing workflows.
• functions/private/*.ps1 for internal helpers.
• config/*.json for applications, tweaks, features, DNS, presets, navigation, themes, and related declarative data.
• xaml/inputXML.xaml for the WPF UI layout.
• tools/autounattend.xml for the embedded unattended Windows setup template.
• scripts/main.ps1 for the final entrypoint and GUI initialization logic appended during compile.
• pester/*.Tests.ps1 for automated checks.
• docs/ for Hugo documentation.

If behavior changes require the compiled script to change, update these source files and run .\Compile.ps1 only to verify generation.

3. Build Model

Compile.ps1 combines the repository sources into winutil.ps1 in this order:

1. Read scripts/start.ps1 and replace #{replaceme} with the current yy.MM.dd build date.
2. Append every file under functions/ recursively.
3. Convert each config/*.json file into embedded $sync.configs objects.
4. Special-case config/applications.json so keys receive the WPFInstall prefix in compiled config.
5. Embed xaml/inputXML.xaml into $inputXML.
6. Embed tools/autounattend.xml into $WinUtilAutounattendXml.
7. Append scripts/main.ps1.
8. Write the result to root winutil.ps1.

Because the final script is concatenated, do not rely on runtime module imports or source-relative dot-sourcing unless the compiled script will also contain the required code/data.

4. Before Editing

• State the plan in one or two sentences before editing. For non-trivial work, include the verification you intend to run.
• Read the files you will touch and the files that call them.
• Match existing patterns even when a different greenfield design would be cleaner.
• Surface assumptions when they affect behavior, compatibility, or user data.
• If two approaches have meaningful tradeoffs, name them before choosing. Trivial tasks can proceed directly.

5. Coding Guidelines

• Prefer the minimum code that solves the stated problem.
• Keep PowerShell functions in one function file when practical, with the file name matching the primary function name.
• Use approved PowerShell verb-noun names and follow the existing WPF / WinUtil naming conventions.
• Keep UI event handler names aligned with XAML element names. A button named WPFExampleButton is typically handled by Invoke-WPFExampleButton.
• Use $sync for shared state and UI references, consistent with the existing runspace model.
• Update WPF controls through the UI dispatcher when running work in a background runspace.
• Keep config-driven features in JSON when they fit the existing schema instead of hard-coding lists in PowerShell.
• Preserve undo/original-state data for tweaks so users can reverse changes.
• Do not add abstractions, configurability, hooks, or "future extensibility" unless the task needs them now.
• Clean up orphans created by your own changes, such as unused variables or functions made obsolete by the edit.
• Avoid broad formatting-only edits, especially in JSON config files, XAML, docs, and generated output.

6. Runtime And Safety Rules

• WinUtil performs system-level Windows changes. Treat registry, services, AppX removal, package manager, Windows Update, ISO, and unattended setup changes as high-risk.
• Prefer existing helper functions for WinGet, Chocolatey, registry, services, progress, and UI updates.
• Keep tweaks reversible where the schema supports it by including original values or original states.
• Never modify a user's original ISO in-place; follow existing copy/mount/export patterns.
• Avoid storing credentials, secrets, or machine-specific paths in repo files.
• Preserve logging and user feedback patterns for long-running or destructive operations.

7. Surgical Changes

• Do not improve adjacent code, comments, formatting, imports, or docs unless required.
• Do not refactor working code because you are already in the file.
• Do not delete pre-existing dead code unless asked; mention it in the summary if relevant.
• Keep diffs reviewable. Every changed line should trace to the user's request.
• If a change starts spreading across unrelated areas, pause and reassess the plan.

8. Verification

Define success in terms that can be checked, then check it.

• For compile/build changes, run .\Compile.ps1.
• For GUI behavior changes, run .\Compile.ps1 -Run when practical and verify the affected path manually.
• For config changes, run the compile check and relevant Pester tests.
• For function changes, run the relevant Pester tests or add/update focused tests when practical.
• For docs-only changes, proofread the changed files and skip runtime tests unless docs generation is affected.
• Read command output. Do not report tests as passing unless they actually passed.
• If verification fails, fix the cause rather than weakening the test.

If a check cannot be run, say exactly why and what residual risk remains.

9. Generated Files And Git Hygiene

• Treat local winutil.ps1 changes as disposable compile output.
• Never stage or commit winutil.ps1, docs/public/, docs/resources/, binary/, editor folders, or other ignored build artifacts.
• Do not remove .gitignore rules that keep generated artifacts out of Git.
• Before finishing, check git status --short and separate your changes from pre-existing user changes.
• Do not revert user changes unless explicitly asked.
• Commit messages, when requested, should be descriptive: short subject under 72 characters, body explaining why when needed.

10. Documentation Expectations

• Update docs/content/ when user-facing behavior changes.
• Update developer docs when architecture, build flow, config schema, or contribution workflow changes.
• Keep README changes brief and high-level.
• Put detailed user and developer documentation under docs/.
• Keep SPEC.md aligned with build/runtime contract changes.

11. Communication Style

• Be direct and concise. Start with the answer or action.
• No flattery, filler, ceremonial closings, or fake certainty.
• Use bullets only when they improve scanning.
• Report what changed, how it was verified, and anything not done.
• If the user asks for a review, lead with findings and file/line references.

12. When To Ask

Ask before proceeding when:

• The request has two plausible interpretations and the choice materially changes behavior or files touched.
• The change affects release generation, generated artifacts, migrations, or high-risk Windows behavior in a way the user did not specify.
• You need credentials, secrets, production resources, or access you do not have.
• The user's stated goal conflicts with the literal request.

Proceed without asking when:

• The task is trivial and reversible.
• Ambiguity can be resolved by reading the code or running a local command.
• The user already answered the question in this session.

13. Project Learnings

When the user corrects an agent approach, add or tighten one concrete rule here before ending the session. Keep this section short and prune rules that no longer matter.

• Keep winutil.ps1 generated-only: change source files, compile to verify, and never stage the generated script.
• Keep WinUtil runtime logging in the existing timestamped %LocalAppData%\winutil\logs\winutil_*.log session file; do not create a separate root winutil.log.
• Import Pester 5.8.0 before running tests so Invoke-Pester -Output Detailed -CI does not resolve to Windows' inbox Pester 3.4.0.
• Keep package install/uninstall process launches simple unless explicitly requested; do not add a separate stdout/stderr process logging helper for winget or Chocolatey.
• When the active log file is owned by Start-Transcript, do not call Add-Content against that file; write to host output so the transcript captures the line in the same log file without recording a terminating-error diagnostic.
• Log install/uninstall package names and package-manager IDs before queuing background runspace work; do not rely on runspace host output for the package identity.
• For Win11 Creator, start each new ISO modification in a fresh WinUtil_Win11ISO_* temp directory; existing-work detection is only for resuming/exporting already modified media.
• For Script Analyzer cleanup, fix actionable source warnings first and do not globally suppress accepted convention warnings such as plural names, ShouldProcess on UI helpers, $global:sync, or compile-time cross-file false positives.
• For DNS DHCP reset, keep the cmdlet reset and explicitly set IPv4 and IPv6 DNS source to DHCP.