Create AI/LLM guidance skill file (AGENTS.md)

[joshschmelzle]

Add AGENTS.md agent guidance file to the developers repo

WLAN Pi development increasingly involves AI assistants and LLM-powered tooling (Claude Code, Codex, Copilot, Cursor, and similar). These tools do not currently have a single, authoritative file describing how to work within the WLAN Pi ecosystem. As a result, they copy patterns from whichever repo they land in, including archived and legacy repos that contain cruft and anti-patterns. This can lead to production of inconsistent or even incorrect output.

This issue is to track creation of an agent guidance file in the developers repo that AI agents and LLMs might consume to understand how to interact with WLAN Pi development generically. The term "agent guidance file" is used throughout; "skill" is avoided because it has a competing, tool-specific meaning in current agent ecosystems.

Goal

Add AGENTS.md at the repo root of the developers repo, following the convention agent tools read automatically. The guidance is org-wide: it applies to AI agents working across all WLAN Pi repos, not just developers.

The file should be guidance, not a rigid standard. It points to the existing docs in the developers repo rather than duplicating them.

Distribution model

The AGENTS.md convention is per-repo: agent tools read the file at the root of the repo they are currently working in. A file that lives only in developers is invisible to an agent working in wlanpi-profiler or wlanpi-core, which is exactly the scenario this issue exists to fix.

• This issue delivers the file in developers.
• A follow-up issue will roll out a thin stub AGENTS.md to each active repo. The stub states the platform rule and links to the file. Stubs contain no independent guidance so there is only one source to maintain.
• All links in the file and the stubs must be absolute GitHub URLs, not relative paths, so they resolve regardless of which repo the file is read from or copied into.

Tool coverage of AGENTS.md varies. Some tools key on other filenames (for example CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI). This issue targets AGENTS.md only. Symlinks or pointer files for other conventions are out of scope here and can be handled in the rollout issue if needed.

Authority model

The developers repo should be the source of truth for WLAN Pi development guidance.

Repo-specific READMEs and top-level docs are useful evidence of patterns, but they may contain historical cruft, legacy decisions, or release-specific guidance.

Archived repos, legacy repos, and older Debian-suite branches must not override the current guidance in developers.

Target platform

• Current development targets Debian 13 ("Trixie").
• Python targets 3.13, because that is the system python3 package in Trixie. WLAN Pi is tied to the system Python package.
• Do not target Python 3.14 or 3.15. There are no plans to do so at this time. This means do not describe the policy as Python 3.13+.
• Do not select alternate production Python runtimes with pyenv, conda, uv-managed interpreters, or similar tools. The interpreter version is determined by Debian Trixie's system python3 package. Production apps are distributed as .deb packages and may use dh_virtualenv under /opt/wlanpi-{app}.
• Exception: Python 3.11 on Bookworm and Python 3.9 on Bullseye remain valid when explicitly working on the relevant older Debian suite branch or an existing-package bug fix. The guidance file must state this exception so agents do not refuse legitimate maintenance work.
• If an active repo still carries py39 or py311 in tox.ini or pyproject.toml, update it to include py313 when the repo is next actively worked on. See style/PYTHON.md.

Maintenance note: the platform rule is intentionally duplicated in AGENTS.md and style/PYTHON.md. When the target suite or Python version changes, both files must be updated in the same change. AGENTS.md should carry a comment or line noting this coupling.

Conventions to capture

Framed as recommendations, each linking to the authoritative doc via absolute URL:

• Be concise. Avoid filler and unnecessary preamble.
• Do not use em dashes in prose. Do not use double hyphens as punctuation. CLI flags and URLs may contain -- where required.
• Do not make assumptions. Ask for clarity when a task is ambiguous.
• Do not invent files, abstractions, dependencies, or features that were not requested. Build only what is needed.
• Prefer boring, well-understood technology. Reach for something novel only where innovation is genuinely required, and call it out when you do.
• Match the surrounding style of the file you are editing. Keep changes minimal and reviewable.
• Python: follow style/PYTHON.md. Use pyproject.toml for new packages, not setup.py. Support running as python -m app. Use argparse, not a hand-rolled parser. Test with pytest. Use tox for test, lint, and format workflows.
• Packaging: follow architecture/PACKAGING.md and architecture/FHS.md. WLAN Pi uses Debian .deb packaging exclusively. Package names use the mandatory wlanpi- prefix. Python apps use dh_virtualenv where applicable. App files go under /opt/wlanpi-{app}, config under /etc/wlanpi-{app}, logs under /var/log/wlanpi-{app}, variable data under /var/lib/wlanpi-{app}, systemd units under /lib/systemd/system. Use debhelper-compat (= 13).
• Documentation: follow style/README_STANDARDS.md. Markdown only (no .rst). Start with a short What/Why section. Use Title Case headings. Use language hints on code fences. Keep tone neutral and professional. Link back to the developers repo.
• Git: follow CONTRIBUTING.md, GIT_WORKFLOW.md, RELEASE_PROCESS.md, and style/DCH.md. Target dev when it exists, else main. Never commit directly to dev or main. Branch naming: u/<user>/<desc>, feature/<desc>, bugfix/<desc>, hotfix/<desc>. Squash merges for temporary branches only; regular merge commit for dev into main. Manage debian/changelog with dch.
• Licensing: prefer BSD-3-Clause for new projects, following licensing/licensing.md.

Recognizing cruft

The guidance file should warn LLMs not to copy outdated patterns from old repos. In AGENTS.md itself, describe cruft at the pattern level rather than naming specific repos, since repo names go stale and add length. Patterns found during the org review:

• System-level sudo python3 -m pip install ... (seen in fpms-legacy, profiler-legacy, etc).
• Hardcoded python3.9 or python3.11 interpreter paths (seen in wlanpi-core/WORKFLOW.md).
• Bookworm, Bullseye, or Buster defaults presented as if current (seen in wlanpi-profiler, wlanpi-desktop, wlanpi-kernel, build, sbuild-debian-package, raspap-webgui).
• setup.py based packaging for new projects.
• Any pattern from archived, abandoned, or legacy repos.

The repo names above are evidence for this issue, not content for the guidance file.

When in doubt, defer to the developers repo, not the repo being edited.

Size and validation

• Keep the file short. Target under roughly 150 lines. Oversized agent files consume context and get ignored or truncated by tooling.
• Before closing, validate the file: run at least one agent tool against a sample task in a WLAN Pi repo with the file present, and confirm it avoids at least one known anti-pattern from the cruft list (for example, it does not reach for sudo pip install or setup.py).

Non-goals

• Not a canonical, exhaustive standards document. The developers repo style and architecture docs remain the source of truth.
• Not a replacement for human review. Humans should always review the output.
• Not an attempt to mandate every detail ("you must do X, Y, and Z").
• Not the per-repo stub rollout. That is a follow-up issue blocked on this one.

Acceptance criteria

• AGENTS.md added at the repo root of developers, concise and scoped (target under ~150 lines).
• States the authority model clearly: developers repo is the source of truth.
• States the hard platform rule: Debian 13 Trixie, Python 3.13 exactly, no Python 3.14, no Python 3.15, no 3.13+, Python version is tied to the OS Python package.
• States the maintenance exception: Python 3.11/3.9 are valid only on the corresponding older Debian suite branches or existing-package bug fixes.
• Captures the conventions above as recommendations linking to existing docs via absolute GitHub URLs.
• Includes a "Recognizing Cruft" section written at the pattern level, without naming specific legacy repos. Maybe?
• Notes the coupling between the platform rule in AGENTS.md and style/PYTHON.md so both are updated together at the next suite transition.
• Prose contains no em dashes and no double hyphens used as punctuation.
• README indexes the new file under the appropriate section.
• GETTING_STARTED.md changed from Python 3.13+ to Python 3.13.
• style/PYTHON.md updated to make the policy explicit: WLAN Pi follows Debian Trixie's system python3 package (3.13), does not target Python 3.14 or 3.15, and does not describe the policy as 3.13+.
• Validated against at least one agent tool on a sample task, confirming it steers away from a known anti-pattern.
• Follow-up issue filed for the per-repo stub rollout.

Resolved decisions

• Filename and location: AGENTS.md at the repo root of developers. Other filename conventions (CLAUDE.md, GEMINI.md) are out of scope for this issue.
• Scope: org-wide guidance, reusable across all WLAN Pi repos, distributed via thin per-repo stubs in a follow-up issue.
• The no-3.14 / no-3.15 rule lives in both the guidance file and style/PYTHON.md, with an explicit note that the two must be updated together.
• Cruft examples in the guidance file are pattern-level only; repo names stay in this issue.
• Terminology: "agent guidance file" throughout, not "skill file".

[joshschmelzle]

I'm sure there are some things we need to change about what was generated above. That's why I assigned y'all.

[joshschmelzle]

Thanks @jsnyder81

wlanpi-compliance-audit.skill.md
wlanpi-dev-conventions.skill.md

[joshschmelzle]

Need to have guidance for commit and PR sizes so that we don't have 10k LOC review requests.

[jsnyder81]

We should also add packaging guidelines as well for Debian packages.

[joshschmelzle]

Worth considering recommending a specific "agentic" pattern whether thats a "reflection pattern"/"generator-critic" or "orchestrator-workers" so that the agent or LLM is forced to review it's own output before throwing the first thing over the fence.