Add project agent instructions

This commit is contained in:
Dandaedre 2026-10-16 13:41:00 +02:00
commit c51d7916a5
1 changed files with 105 additions and 0 deletions

105
AGENTS.md Normal file
View File

@ -0,0 +1,105 @@
# Project instructions
## Purpose
Config Central manages software installation and repository-backed configuration
across several Windows desktops. Each machine pulls from this repository and
applies its selected profiles. Keep the process simple, inspectable, and usable
from a terminal without a management server.
## Architecture
- Use PowerShell 7 for the CLI and implementation modules. Keep `bootstrap.ps1`
compatible with built-in Windows PowerShell 5.1 so a fresh machine can start.
- Use WinGet for software and Git for repository distribution.
- Use JSON manifests for profiles and machine definitions, with no YAML dependency.
- Expose `cc` through a thin launcher for `cc.ps1`. Implement CLI commands before
considering a TUI; any menu must reuse the same command implementation.
- Keep dependencies minimal. Do not introduce a compiled CLI, service, DSC layer,
or remote orchestration framework without a concrete need.
Planned layout:
```text
bootstrap.ps1
cc.ps1
src/
Packages.psm1
Configs.psm1
Repository.psm1
Elevation.psm1
State.psm1
profiles/
machines/
configs/
tests/
TASKS.md
```
## Desired behavior
- Machine manifests select ordered profiles and provide explicit overrides.
Merge packages by package ID and source, and configs by stable config name.
Reject ambiguous definitions and unknown fields. Support `enabled: false` for
disabling inherited entries. Document precedence before implementing it.
- Commands: `plan`, `sync`, `apply`, `status`, and `doctor`. `sync` fetches then
applies; `apply` uses the current local revision. Support config-only sync.
- Resolve a repository revision before applying and execute from an immutable
snapshot. Never replace running scripts midway through a sync or discard local
repository edits automatically.
- Install missing packages and upgrade only declared packages according to their
update policy. Use explicit WinGet IDs and sources. Handle installer scope as a
package constraint rather than assuming every package supports both scopes.
- Run installations sequentially. Preserve diagnostics, interpret exit codes,
report reboot requirements, and never reboot automatically.
- Copy configuration files by default. Back up existing destinations before
replacement, track deployed hashes, and skip unchanged content.
- Report locally modified config files as conflicts. An explicit force option
may replace them only after backing them up. Do not implement generic merging
across arbitrary file formats.
- Removing a manifest entry stops managing it. Uninstalling applications or
deleting destination files requires an explicit operation.
- Record per-item results and the applied commit. Reruns inspect actual state and
recover from partial failure. Do not claim package operations are transactional.
## Windows execution and storage
- Run the controller as the desktop user. Elevate only the worker operations
that require administrator rights, preferably in a batch.
- Resolve user config paths using the original user's context, including when
elevation uses different credentials. Never accidentally target the admin
account's profile.
- Keep user checkout, state, backups, and logs under
`%LOCALAPPDATA%\ConfigCentral`. Protect machine-level state under
`%ProgramData%\ConfigCentral` with appropriate permissions.
- Validate manifest paths and elevated operations. Do not evaluate manifest
strings as PowerShell code or pass arbitrary commands to the elevated worker.
- Do not disable Defender, UAC, or installer integrity checks as setup steps.
Diagnose individual failures instead of adding broad security workarounds.
- Keep credentials and machine secrets out of manifests, logs, and Git.
## Implementation and verification
- Make every task step and each distinct modification a small, focused Git
commit. Do not combine unrelated work. A commit should contain one reviewable
behavior, fix, test, documentation change, or task-state update and should
leave the repository in a coherent state.
- Commit the corresponding `TASKS.md` checkbox update with the implementation
that completes it. If a task requires several independent changes, use several
small commits and mark the task complete only in the final commit.
- Use concise imperative commit messages that describe the completed change.
Review the staged diff before committing and never include unrelated user
changes.
- Keep package, config, repository, elevation, and state logic in separate modules.
Keep the CLI entry point small and make errors actionable.
- `plan` must not install packages or deploy configs. Provide stable exit codes
for automation and readable summaries for interactive use.
- Validate manifests and prerequisites before making changes. Prevent concurrent
applies and write state atomically.
- Test behavior with meaningful failure cases: profile precedence, path handling,
local edits, partial failure, reruns, and privilege boundaries. Mock installers
in unit tests; use a disposable Windows environment for installation checks.
- Run checks appropriate to the change. Clearly distinguish checks executed on
Windows from static checks or mocks executed elsewhere.
- Update `TASKS.md` as implementation progresses. Mark tasks complete only when
the behavior is implemented and relevant validation is done.