Imported from ncsa/taloscluster (AGENTS.md). Install upstream with npx skills add ncsa/taloscluster. Copyright stays with the author.

AGENTS.md

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

5. Application Specific Rules

Following rules are here to help the AI avoid the same mistakes again:

• Dependencies are managed with uv, code is run with uv
• Imports at top of file only
• Variables are in both cluster.yaml and secrets.yaml, combine these when reading them.
• Track changes in the CHANGELOG.md, if no unreleased section exists, then add it, make sure to not add a new subsection.
• Keep CHANGELOG entries short: one terse bullet per logical change, present tense, user-facing language. Do not write long narrative paragraphs explaining the "why" at length. Where a change has an obvious PR, link it (e.g. (#123)).
• When bumping the version in pyproject.toml, also run uv lock to update uv.lock.
• Talos commands (talosctl) always target a server's real address, never the kube-api VIP or floating IP. The VIP belongs to whichever control plane currently owns it and may be pointed at an address no node owns yet; the endpoint is controlplane-01's tailscale name or real address, and the node is its own private address.
• When cutting a release, first pull the latest dependencies (uv lock --upgrade) and then run the full test suite (uv run pytest) before tagging — upgraded dependencies can introduce breaking changes, so the release must not go out unless the tests pass.
• Documentation lives in docs/ and is published with MkDocs (uv run mkdocs build --strict must pass; the docs workflow deploys it). Update it in the same change as the code, not afterwards:
  • Any new, removed or changed key in cluster.yaml or secrets.yaml (core or plugin) is reflected in the matching page under docs/configuration/ (key heading, the Required · type · default line, the example) and, for a new top-level key, in the tables in docs/configuration.md.
  • A change in how a module works — a new provider feature, a different converge phase, new firewall or upgrade behaviour, a new plugin or plugin hook — is reflected in the relevant page under docs/concepts/ (machines.md for provider and access behaviour, lifecycle.md for check/plan/converge/upgrade behaviour, plugins.md for plugins, talos.md for security claims).
  • Examples in docs/ use placeholder values only: RFC 5737 addresses (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24), RFC 1918 private ranges, and example.edu/example.com hostnames. Never real NCSA addresses, hostnames or credentials.
  • Do not hard-wrap prose in markdown files; one paragraph per line.

GitNexus — Code Intelligence

This project is indexed by GitNexus as taloscluster (1564 symbols, 3635 relationships, 134 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

Index stale? Run node .gitnexus/run.cjs analyze from the project root — it auto-selects an available runner. No .gitnexus/run.cjs yet? npx gitnexus analyze (npm 11 crash → npm i -g gitnexus; #1939).

Always Do

• MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
• MUST run detect_changes() before committing to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: detect_changes({scope: "compare", base_ref: "main"}).
• MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
• When exploring unfamiliar code, use query({query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
• When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use context({name: "symbolName"}).

Never Do

• NEVER edit a function, class, or method without first running impact on it.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
• NEVER rename symbols with find-and-replace — use rename which understands the call graph.
• NEVER commit changes without running detect_changes() to check affected scope.

Resources

CLI