[jaladh-singhal]

Added shared instructions for AI coding agents (Claude Code, Codex, Cursor, etc.) working in this repo:

• AGENTS.md (repo root): project instructions that agents load at the start of every session. It covers the repo map, the dev and test loop, code conventions, and how to approach a change in this codebase.
  • Kept deliberately short (about 60 lines), since it uses context in every session. It points to docs/ rather than repeating them.
  • No CLAUDE.md: Claude Code reads AGENTS.md natively from v2.1.277, as long as no CLAUDE.md exists (claude --version to check).
• .agents/skills/: task-specific instructions that load only when a request matches a skill's description, or when it's run as a command (e.g. /skill-name), so they cost nothing until they're used.
  • Starts with pr-description as an example. It drafts a PR description in the team's usual format (Jira link, what/why, Testing with the dev build URL).
  • .agents/skills/ is the cross-tool location recommended by the Agent Skills spec. Claude Code only reads .claude/skills/, so that is a symlink to .agents/skills/ and one copy works for all tools.

Testing

• From the repo root, start a new Claude Code session and ask it something answered in AGENTS.md (e.g. "how do I run a single JS test?"). It should answer without searching the repo.
• On any feature branch, run /pr-description or just ask "write a PR description for this branch". Either should load the skill and produce a draft with the Jira link and the dev build URL.
• Please read through AGENTS.md and flag anything that doesn't match how you work, especially the Code conventions and "How to approach a change" sections.

[aventura121]

This is great, thanks for proposing it. One thing that may be helpful to explain in AGENTS.md, if you agree, is a note about the firefly_test_data dependency for the tests. Maybe something like, "Some Java and jest tests read data from a separate firefly_test_data repo, checked out next to this one (../firefly_test_data; internal, not on GitHub). If it's missing or out of date, those tests fail with file-not-found errors. That's a data gap, not a regression. FIREFLY_SKIP_TESTDATA=true skips the jest ones (src/firefly/jest.config.js)."

[kpuriIpac]

Looks good to me. I tested with some questions (after checking out this repo) to claude and made sure it used agents.md (I even asked it explicitly about where it got the info from in agents.md). I am excited to have this be merged and try out building PRs from the new PR skill!

[robyww]

Looks fine.

It is not clear to me how much detail should be added.

I left details about how Controller refactor direction.

[robyww]

Look at the ImagePlotCntlr.js and DrawLayerCntrl.js refactor to help eliminate circular dependencies.

• ImagePlotDispatch.js - dispatch functions
• DrawLayerDispatch.js - dispatch functions
• VisConst.js - holds all the action constants for both
• VisStoreRoots.js - holds the roots functions
• This is our refactor redirection

If we refactor MultViewCntlr.js we will make a MultiViewDispatch.js and add the constants to VisConst.js and root function to VisStoreRoots.js

[jaladh-singhal]

@robyww This is a good point that we should capture! I added a sub-bullet under the *Cntlr.js line that walks one action (image zoom) through the split: ZOOM_IMAGE in VisConst.js, dispatchZoom() in ImagePlotDispatch.js, reducer in ImagePlotCntlr.js, visRoot() in VisStoreRoots.js. It also says to use this pattern for new controllers and when refactoring old ones, so agents won't keep adding to the all-in-one shape.

Re how much detail should be added, this is where AI helps. I showed Claude your PR comment and it came up with the wording, since it knows the format and the goal of keeping AGENTS.md short. It did take a few iterations over its first draft though.