Hanaol/agent integration

[hanaol]

Summary

Everything in this plan flows from two ideas:

1. The goal is to use AI assistants work correctly with quacc, both for contributors writing recipes/calculators and for users who try to compose and run calculations.
2. AI assistants guess confidently when information is missing or ambiguous. So the aim is to remove ambiguity (quacc-only conventions, non-obvious rules, etc).

Issue #3154 asked for a CLAUDE.md, however, this PR proposes a broader, provider-neutral plan for agent integration instead.

Opening as a draft to get early feedback on scope and direction before implementing.

What's proposed

• Phase 1: AGENTS.md at the repo root — a short file explaining how quacc recipes are supposed to be written and rules an agent would otherwise get wrong by default. The benefit: these conventions get applied automatically when an agent writes code, instead of being caught later in human review.

• Phase 2: contributor skills (new-recipe, new-calculator, recipe-tests, docs-sync) as portable skills/ (agentskills.io format)

• Phase 3, two built-in GitHub platform capabilities:

  • On-demand PR review: request Copilot as a reviewer on a pull request, same as requesting a human. Its comments are advisory and never count as an approval, so it can neither satisfy nor block a merge requirement. It reads AGENTS.md automatically, no separate instructions file needed. The setting that would auto-request it on every PR stays off — no automatic AI reviewer, humans remain the only required reviewers.

  • Hosted coding agent: a maintainer assigns an issue to Copilot; it works on GitHub's machines and opens an ordinary PR for human review. It needs a small environment-setup workflow (.github/workflows/copilot-setup-steps.yml, installs Python + pip install -e . + test deps) plus branch-skip lines in the existing CI so it doesn't burn minutes on in-progress branches.

• Phase 4: a new skill, quacc-workflow, aimed at scientists using quacc ather than people editing its code (unlike the Phase 2 skills). An AI assistant that has the quacc repo open can already answer a lot of questions on its own by searching the source code directly. This skill targets the specific cases where that isn't enough:

  • Questions with no obvious keyword to search for: The skill points the assistant at quacc's existing, always-current documentation pages instead of making it guess.

  • Picking the right function when several share a name: Quacc has 14 different functions all called relax_job (one per supported simulation code) and 17 called static_job.The skill states the correct one explicitly.

  • Choosing which workflow engine to use: Quacc supports 6 different systems for running large batches of jobs (e.g. on a shared computing cluster vs. a single computer), and picking the right one depends on the user's setup. The skill encodes that decision instead of leaving it to a guess.

  • Customizing a pre-built workflow: Quacc has its own way of letting users tweak one step of a multi-step workflow (via job_params/ job_decorators), which doesn't resemble any convention from outside quacc, so an assistant is likely to invent something plausible-looking but wrong. The skill documents the real syntax.

• Phase 5: per-skill CI verification + an eval set, so nothing ships without
  a way to catch it going stale

Progress

• Phase 0 — guardrails and sign-off
• Phase 1 — AGENTS.md
• Phase 2 — contributor skills
• Phase 3 — on-demand PR review + hosted coding agent
• Phase 4 — user-facing skill
• Phase 5 — eval suite + CI verification

[buildbot-princeton]

Can one of the admins verify this patch?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (e5bb4d2) to head (688460e).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #3443   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          100       100           
  Lines         4281      4281           
=========================================
  Hits          4281      4281           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Andrew-S-Rosen]

I am open to these --- in particular Phase 1-3. Although I admit that Phase 3 isn't super critical because I can launch PR reviews from the LLM desktop client. Phase 4 and 5 seem nice to have but not critical.