cds-ai/AGENTS.md

# AI Agent Instructions

This document provides workspace-level instructions for AI agents working anywhere under `/home/aw/code/cds`.

## Git and Commit Rules

### General Workspace Rules

- Always let the user review the proposed commit scope and commit message first, and wait for explicit approval before creating any local git commit in this workspace.
- Never commit or push to the nested `galaxy-complete` repo under `/home/aw/code/cds/galaxy-complete` without the user's explicit approval.
- Never assume work in `/home/aw/code/cds` should be pushed to `rnd.cdsi.us.com`.

## ATVM Prep Script Guardrail

- Do not run `/root/atvm_prep/atvm_prep.py` unless the operator explicitly asks for an `atvm_prep` task.
- For any `atvm_prep` execution request, always show the planned command first and wait for explicit operator approval before running it.

## Exact VM Name Guardrail

- For VM power or maintenance requests, act only on the exact VM names provided by the operator.
- If any requested VM name is not found, stop and report it; do not infer, substitute, or search for replacement VMs unless the operator explicitly asks for that discovery step.

## ATVM vCenter Inventory Deletion Guardrail

- Never delete or destroy any ATVM VM from vCenter. Removing from inventory or unregistering is allowed only for VMs whose names start with `atvm`.
- Treat a vCenter VM as protected ATVM inventory if its name starts with `atvm`, if it resides on an `AutomatedTest-*` ATVM datastore, or if it is an ATVM platform/controller VM, even when it is not listed in `inventory/vm-inventory.md`.
- ATVM VM inventory entries in vCenter are permanent test inventory and must be preserved even when power, maintenance, datastore, or cleanup work is requested.
- This guardrail applies regardless of operator wording unless the operator explicitly updates this AGENTS.md rule first.
- For cleanup workflows, only power off, detach/unmount supporting resources, unregister/remove from inventory for VMs whose names start with `atvm`, or report the needed manual action; do not delete or destroy ATVM VMs.

## Red Hat Manual Task Subscription Guardrail

- For manually requested tasks on Red Hat machines (non-ATVM-automation tasks), run the Red Hat subscription reset/register sequence before the requested task.
- Do not apply this guardrail to ATVM automation runs where existing automation scripts already handle subscription flow.
- Use Red Hat subscription credentials from `/home/aw/code/cds/.env.credentials.local`:
  - `REDHAT_SUBSCRIPTION_USER`
  - `REDHAT_SUBSCRIPTION_PASSWORD`
- Required pre-task command sequence for manual Red Hat tasks:
  - `subscription-manager remove --all`
  - `subscription-manager unregister`
  - `subscription-manager clean`
  - `subscription-manager register --username "$REDHAT_SUBSCRIPTION_USER" --password "$REDHAT_SUBSCRIPTION_PASSWORD"`

## ATVM Prep Mapping Defaults

- For `atvm_prep` requests in this workspace, infer common options from operator shorthand when intent is clear.
- Datastore shorthand mapping for `-n`:
  - `Gold` -> `AutomatedTest-VMBootImg-Gold`
  - `Gold2` -> `AutomatedTest-VMBootImg-Gold-2`
  - `ComputeMigration` (or `compute migration`) -> `AutomatedTest-VMBootImgComputeMigration-Gold`
- Client/ESXi pairing defaults:
  - `CDS1-ESX165` <-> `192.168.1.165`
  - `CDS1-ESX166` <-> `192.168.1.166`
- If only one of `-c` or `-e` is provided, auto-fill the paired value from this mapping.
- If both `-c` and `-e` are provided but conflict with mapping, stop and ask for confirmation before execution.

## Cirrus Data Cloud Reference

- Use `docs/cirrus-data-cloud/README.md` as the navigation entry point for the shared VMware/vCenter/MigrateOps reference set.
- Use the guides under `docs/cirrus-data-cloud/` when you need the reusable Cirrus Data Cloud workflow material.
- Treat `docs/cirrus-data-cloud/run-learnings.md` as history and evidence, not baseline procedure.

### ATVM Cypress Git Drafting

When the user explicitly asks to "create a git" or otherwise requests git/commit help for the ATVM Cypress machine/vm:

1. Never automatically run git commands. Always draft the commands only.
2. Assume the user is referring to the Cypress ATVM checkout at `/root/cdc-e2e-cyp-12.17.4`.
3. Write the drafted commands to `/tmp/commit.txt` so the user can copy and paste them without extra formatting.
4. When generating git commands that need SSH, use the user's one-off method exactly as:
   `GIT_SSH_COMMAND='ssh -i ~/.ssh/id_ed25519_anthony -o IdentitiesOnly=yes'`
5. Prefer complete copy-pasteable command sequences that are ready to run from `/root/cdc-e2e-cyp-12.17.4`.

If the user does not specify the ATVM Cypress machine/vm, follow the general workspace rules above and any other git guidance already in this file.

## Machine-Based Default Paths

- Before looking for screenshots or files, check the machine identity first, for example with `hostname`.
- On `atvm-codex-aw`, use `/home/cirrus/Pictures` as the default folder when the user asks you to look at screenshots.
- On `atvm-codex-aw`, use `/home/cirrus/Documents` as the default folder when the user asks you to look at files.
- If the machine is different and no local convention is documented, do not guess a folder path; ask the user or inspect the local environment first.