docs(agents): generic file placement rules and CLI AGENTS.md

[muddlebee]

Fixes #3631

Describe the changes you have made in this PR -

• Expand root AGENTS.md Code Style with a generic File placement (all packages) section: orchestration vs shared UI vs domain modules, thin dispatch, tier boundaries, and a stop rule for provider-specific branches in multi-provider files
• Add surfaces/cli/AGENTS.md at the CLI package level (not wizard-only): package map for commands/, wizard/, llm_auth/, investigation/, and file-placement examples (azure_openai.py, local_llm/, etc.)
• Link repo map and package-local AGENTS references to the new CLI guide

Follow-up to #4117 — codifies the refactor/placement guidance that should have been applied on the first Azure onboarding pass.

Demo/Screenshot for feature changes and bug fixes -

Docs-only change. No runtime behavior change.

---

Code Understanding and AI Usage

Did you use AI assistance (ChatGPT, Claude, Copilot, etc.) to write any part of this code?

• No, I wrote all the code myself
• Yes, I used AI assistance (continue below)

If you used AI assistance:

• I have reviewed every single line of the AI-generated code
• I can explain the purpose and logic of each function/component I added
• I have tested edge cases and understand how the code handles them
• I have modified the AI output to follow this project's coding standards and conventions

Explain your implementation approach:
Agents were patching provider-specific logic into shared wizard files (_ui.py, validation.py) because root AGENTS.md only stated "one clear purpose per file" without actionable placement rules. This PR adds generic, repo-wide guidance at the root and a CLI-specific map at surfaces/cli/AGENTS.md (matching surfaces/interactive_shell/AGENTS.md placement). Wizard details live under CLI rather than a nested wizard/AGENTS.md so commands/, llm_auth/, and investigation/ are covered too.

---

Checklist before requesting a review

• I have added proper PR title and linked to the issue
• I have performed a self-review of my code
• I can explain the purpose of every function, class, and logic block I added
• I understand why my changes work and have tested them thoroughly
• I have considered potential edge cases and how my code handles them
• If it is a core feature, I have added thorough tests
• My code follows the project's style guidelines and conventions

---

Note: Please check Allow edits from maintainers if you would like us to assist in the PR.

[github-actions]

Greptile code review

This repo uses Greptile for automated review. Before merge, aim for Confidence Score: 5/5 with zero unresolved review threads — see CONTRIBUTING.md.

Run a review — add a PR comment with:

@greptile review

Give it ~5-10 minutes (sometimes longer) for results, then fix feedback and re-trigger until you reach Confidence Score: 5/5.

Optional: automate with the greploop skill.

[greptile-apps]

Greptile Summary

This PR expands the root AGENTS.md with a generic "File placement (all packages)" section (table + 6 rules) and updates the surfaces/cli/ repo map row with inline placement pointers. The PR originally added a dedicated surfaces/cli/AGENTS.md, but that file was removed in a follow-up commit (after review feedback on incorrect test paths and missing wizard/prompts.py), with the essential CLI guidance folded into the root file.

• Adds a structured file-placement table covering orchestration, shared UI/prompts, domain/provider modules, and registry/catalog files, plus a hard stop rule for new if provider.value == ... blocks in multi-provider files.
• Removes the separately-created surfaces/cli/AGENTS.md; the surfaces/cli/ repo map row now carries inline pointers for provider onboarding, new subcommands, and LLM wiring reference.
• Existing linked files (surfaces/interactive_shell/AGENTS.md, core/llm/AGENTS.md, docs/ARCHITECTURE.md, docs/tool-placement-policy.md) are all verified present.

Confidence Score: 5/5

Docs-only change with no runtime behavior; safe to merge.

All linked files verified present; no broken references in the final state. The removed surfaces/cli/AGENTS.md leaves a small gap around wizard/configurators/ placement guidance, but this does not affect any running code.

AGENTS.md — the surfaces/cli/ repo map row could be expanded to name wizard/configurators/ and wizard/integration_validators/.

Important Files Changed

Filename	Overview
AGENTS.md	Adds "File placement (all packages)" section with a 4-row table and 6 rules; updates surfaces/cli/ repo map row inline. The deleted surfaces/cli/AGENTS.md's integration-configurator placement rule (wizard/configurators/ vs wizard/flow.py) is not captured in the root guidance.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Agent adds/changes behavior] --> B{Owning module exists?}
    B -- Yes --> C[Put code in owning module]
    B -- No --> D{Two+ functions for same provider/vendor?}
    D -- Yes --> E[Create dedicated module: wizard/provider.py or wizard/local_llm/]
    D -- No --> F{Shared file already handles it?}
    F -- Yes --> G{Would add provider if-block?}
    G -- Yes --> E
    G -- No --> H[Delegate via thin dispatch]
    F -- No --> I{Integration-specific onboarding?}
    I -- Yes --> J[wizard/configurators/ + wizard/integration_validators/]
    I -- No --> K[wizard/flow.py or root orchestration]
    C --> L[Check package AGENTS.md if present]
    E --> L
    H --> L
    J --> L
    L --> M[Respect tier boundaries: surfaces compose core/ + integrations/]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Agent adds/changes behavior] --> B{Owning module exists?}
    B -- Yes --> C[Put code in owning module]
    B -- No --> D{Two+ functions for same provider/vendor?}
    D -- Yes --> E[Create dedicated module: wizard/provider.py or wizard/local_llm/]
    D -- No --> F{Shared file already handles it?}
    F -- Yes --> G{Would add provider if-block?}
    G -- Yes --> E
    G -- No --> H[Delegate via thin dispatch]
    F -- No --> I{Integration-specific onboarding?}
    I -- Yes --> J[wizard/configurators/ + wizard/integration_validators/]
    I -- No --> K[wizard/flow.py or root orchestration]
    C --> L[Check package AGENTS.md if present]
    E --> L
    H --> L
    J --> L
    L --> M[Respect tier boundaries: surfaces compose core/ + integrations/]

Loading

_{Reviews (2): Last reviewed commit: "docs(agents): drop redundant CLI AGENTS...." | Re-trigger Greptile}

[Davidson3556]

@greptile review

[Davidson3556]

Docs look sound, two things you should work on:

1. The PR body is stale. It says this adds surfaces/cli/AGENTS.md and links the repo map to it, but commit 899dac7 dropped that file — net change is root AGENTS.md only. Worth updating so the description matches the diff.

2. The repo-map row points provider onboarding at wizard/<provider>.py, but that path doesn't exist. Real siblings are wizard/configurators/<name>.py and wizard/local_llm/; runtime clients live in core/llm/providers/<name>.py. Rule Revert "Codebase refactoring and cleanup " #2 tells readers to match an existing sibling, and there isn't one for wizard/<provider>.py. Suggest pointing at the paths that exist.

All the links in the actual diff resolve fine.

[github-actions]

🐉 Legend says enough merged PRs and you ascend. @muddlebee is dangerously close. 🌤️

---

👋 Join us on Discord - OpenSRE : hang out, contribute, or hunt for features and issues. Everyone's welcome.