Add AGENTS.md and a skills directory for AI coding agents

.agents/skills/pr-description/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: pr-description
+description: Write a PR description for the current Firefly feature branch and copy it to the clipboard — Jira ticket link, a what/why summary sized to the change, and a Testing section with the branch's dev build URL. Use when the user asks to write, draft, or generate a PR/pull-request description, or invokes /pr-description.
+---
+
+Write a PR description for the current feature branch and copy it to the clipboard.
+
+## Steps
+
+1. **Find the base branch.** Firefly PRs target `dev`, or an `rc-*` branch for release fixes. Run `git fetch origin` and pick whichever of `origin/dev` and the `origin/rc-*` branches has the fewest commits in `git rev-list --count <base>..HEAD`. Use it as `<base>` below.
+
+2. **Understand the changes.** Run these in parallel:
+   - `git log <base>..HEAD --oneline`
+   - `git diff <base>...HEAD --stat`
+
+   Then read the key changed files to understand what the code actually does — not just the commit messages.
+
+3. **Get the ticket** from the branch name (`FIREFLY-1234-short-desc` → `FIREFLY-1234`; also `IRSA-…`). Link it as `https://jira.ipac.caltech.edu/browse/<TICKET>`.
+
+4. **Learn the author's style** from their recent PRs:
+   - `gh pr list --repo Caltech-IPAC/firefly --author @me --state merged --limit 5 --json number,title,body`
+   - Note the tone, tense, header levels, and bullets vs prose — and match them.
+   - If the author has no past PRs, use the structure in step 5 as is.
+   - Saved preferences from the author (memory, CLAUDE.md) take precedence over anything inferred here.
+
+5. **Draft the description in markdown:**
+   - **Ticket line** at the top, linking the Jira ticket (e.g. `Fixes [FIREFLY-1234](https://jira.ipac.caltech.edu/browse/FIREFLY-1234)`).
+   - **What and why**, sized to the change. For a small fix: one tight paragraph covering the problem, the cause, and the fix. For a larger change: add bullets or a short section for non-obvious design decisions and their trade-offs. Skip obvious choices.
+   - Briefly define library-specific terms in plain words.
+   - If the change has a counterpart PR in another repo (e.g. an IFE PR), link it.
+   - **`## Testing`** — first the dev build URL: `https://<branch-name-lowercased>.irsakubedev.ipac.caltech.edu/firefly/` (append the app path if the change is in a specific app). Then concrete steps a reviewer can follow: what to load, what to click, what they should see. Put caveats and known issues to verify here too.
+
+6. **Show the draft** to the user and iterate until they approve. Remind them that the dev build URL only works once the branch's test build has been run.
+
+7. **Copy the final version to the clipboard** with `pbcopy` on macOS (`xclip -selection clipboard` or `wl-copy` on Linux). If none of these is available, print it for the user to copy.

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in the Firefly repo. Human-facing docs live in `README.md`, `CONTRIBUTING.md` and `docs/`.
+
+## Project overview
+
+Firefly is IPAC's astronomy data visualization and archive UI toolkit: a React/Redux client (images, tables, charts) backed by a Java server (Tomcat webapp). It's a large, mature codebase that has been through several generations of code patterns.
+
+## Repo map
+
+- `src/firefly/js/` — client code
+  - `visualize/` images, HiPS and coordinates; `tables/` table model and UI; `charts/` Plotly-based charts
+  - `ui/` components, dialogs and search panels; `core/` Redux store, reducers and sagas; `api/` public JS API; `util/` helpers
+  - `*Cntlr.js` files (e.g. `charts/ChartsCntlr.js`) define a state slice's action types, `dispatch*` functions and reducer
+  - tests live next to the code in `__tests__/` folders, named `<Module>-test.js`
+- `src/firefly/java/edu/caltech/ipac/` — server code (`firefly/`, `table/`, `visualize/`, `util/`, `astro/`)
+- `src/firefly/test/` — Java tests, mirroring the `java/` package layout
+- `buildScript/` — Gradle build logic (`tasks.gincl` defines the tasks below)
+- `docs/` — developer docs, e.g. `development-process.md`, `jstest-notes.md`
+
+## Build, test, lint
+
+```shell
+gradle :firefly:buildAndDeploy        # build the war and deploy to local Tomcat — needed first, and after server (Java) changes
+gradle :firefly:devMode               # watch JS and rebuild straight into the deployed webapp — the usual client dev loop
+```
+
+While iterating, check only what you touched:
+
+```shell
+yarn test-unit js/charts/__tests__/ChartUtil-test.js   # one Jest file, run from src/firefly/
+npx eslint src/firefly/js/charts/ChartUtil.js          # lint changed files, run from repo root
+```
+
+Before calling a change done, run the full suites CI runs: `gradle :firefly:jsTest`, `gradle :firefly:jsLint`, and `gradle :firefly:test` if Java changed.
+
+## Code conventions
+
+- Match the surrounding code's style, reuse existing utilities, and follow established patterns rather than reinventing them. The exception is a pattern that's clearly legacy or bug-prone. Use the modern approach there, and say that you did.
+- Use descriptive names — no single-letter or cryptic abbreviations like `t`, `xs`, `ll`; the name should say what the value holds.
+- For debug output, use `Logger` from `util/Logger.js` rather than `console.log`. Turn it on in the browser console with `window.firefly.debug = 'debug'`; filter it with `window.firefly.debugTags = 'Table'`.
+- Add short comments where the reason isn't obvious (a temporary hardcode, a subtle check); don't narrate what the code does.
+- JSDoc: when a function also has rest params, document destructured props as `@param {object} props` / `@param props.field` to satisfy `jsdoc/check-param-names`.
+- Tests: one helper per function under test, named after that function. Avoid chained generic helpers and hidden defaults — each test should show its inputs.
+- Before upgrading a JS dependency, check `package-json-doc.md` for why some packages are held at older versions.
+
+## How to approach a change
+
+- **Find the nearest cousin first.** Read the full round trip of an existing analog — component *and* the reducer/controller/server handler under it — not just a similar-looking call site. It reveals the ordering, side effects and edge cases you'll need to handle.
+- **Weigh decisions by blast radius, not diff size.** Local, reversible edits: just make them. New data flows, persisted state, endpoints, or edits to shared reducers/utilities: propose a short plan and get confirmation before editing.
+- **Build and debug one layer at a time.** Prove an endpoint with a raw request before wiring UI; prove render before selection; selection before persistence.
+- **Suspect stale state.** Redux state, server caches and long sessions outlive the code that filled them. When a bug contradicts verified code, try a hard reload or cache reset before re-reading the code.
+- **Reactive flows need a live check.** For new subscription/effect chains across files, code review isn't enough — ask for the interaction to be exercised live, more than once.
+- **Set scope early and keep it.** Name what's deferred; raise tempting adjacent fixes instead of folding them in.
+- **Remove superseded code in the same edit** — old functions, unused imports, stale comments — once you've confirmed it's actually dead.
+
+## Git workflow
+
+- Branches: `FIREFLY-<ticket>-short-desc`, created from `dev` (or the current `rc-*` branch for release fixes). Commit messages start with the ticket, e.g. `FIREFLY-1234: ...`.
+- PRs target `dev` (or the `rc-*` branch) and are squashed before merge. Full process: `docs/development-process.md`.
+- Don't commit, push, or rebase unless asked.