chore: bootstrap agent files (JUM-870)#2834
Conversation
Add AGENTS.md, ARCHITECTURE.md and a thin CLAUDE.md so agents and contributors picking up work cold have a baseline map of the repo. Update README.md to point at the new entry points and rewrite the getting-started/test sections more tightly. Add per-developer AGENTS.local.md / CLAUDE.local.md to .gitignore.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This comment has been minimized.
This comment has been minimized.
WalkthroughAdds new project documentation ( Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Review rate limit: 0/5 reviews remaining, refill in 55 minutes and 20 seconds. Comment |
|
✅ All snapshot tests passed |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Line 30: The markdown reference to an external style guide in the sentence
"Function names should be self-documenting" uses a broken relative link
(`../../../.claude/CLAUDE.md`); update that link in AGENTS.md so it points to a
valid in-repo document (e.g., replace with the correct path to the repo's style
guide) or remove the hyperlink if the guide is intentionally external, ensuring
the visible text "Function names should be self-documenting" remains unchanged.
- Line 9: Replace the non-portable reference token "@README.md" with a standard
relative Markdown link so it renders on GitHub (locate the "See `@README.md`" line
and change it to a regular link like "See [README.md](README.md)" to ensure
portability and correct rendering).
In `@ARCHITECTURE.md`:
- Around line 118-131: Update the “No barrel files (`index.ts` re-exports)”
invariant in ARCHITECTURE.md to align with repo reality: either scope it to “new
or modified code” and explicitly state that existing barrel files (e.g.,
utils/routes/index.ts, hooks/userTracking/index.ts,
providers/ThemeProvider/index.ts, providers/WalletProvider/index.ts) are legacy,
or add a short migration note and timeline with an owner who will remove/replace
those barrels; change the invariant text and append a brief “Migration plan /
timeline” section that lists the known barrel examples and the expected
remediation steps and deadline.
- Around line 30-62: The markdown fenced code blocks in ARCHITECTURE.md (the
ASCII project tree and other blocks shown around lines 30–62 and 66–91) lack
language identifiers and trigger MD040; update each triple-backtick fence (e.g.,
the block containing "jumper-exchange/" and the other ASCII diagrams) to include
a language token such as text (```text) so markdownlint passes and readability
improves—ensure every opening ``` has a matching closing ``` and apply the same
change to all similar fenced blocks in the file.
In `@CLAUDE.md`:
- Line 1: Replace the inline mention "See `@AGENTS.md`" with a standard relative
Markdown link so it renders reliably (e.g., change the text to "See
[AGENTS.md](AGENTS.md)"); locate the string "See `@AGENTS.md`" in CLAUDE.md and
update it to use the Markdown link syntax, making sure the link target matches
the repository filename exactly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f0381436-63b4-4793-a2c4-d98b2ba63404
📒 Files selected for processing (5)
.gitignoreAGENTS.mdARCHITECTURE.mdCLAUDE.mdREADME.md
|
|
||
| ## Run, build, test | ||
|
|
||
| See @README.md |
There was a problem hiding this comment.
Use a standard Markdown link instead of @README.md.
@README.md is not a portable Markdown link format on GitHub. Use a regular relative link so it renders reliably.
Suggested fix
-See `@README.md`
+See [README.md](./README.md)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| See @README.md | |
| See [README.md](./README.md) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` at line 9, Replace the non-portable reference token "@README.md"
with a standard relative Markdown link so it renders on GitHub (locate the "See
`@README.md`" line and change it to a regular link like "See
[README.md](README.md)" to ensure portability and correct rendering).
| - **No barrel files** (`index.ts` re-exports). Import directly from the source file. | ||
| - **TypeScript path aliases**: `@/foo` and `src/foo` both resolve to `./src/foo` (see `tsconfig.json` and `vitest.config.ts`). Prefer `@/` in new code. | ||
| - **Comments explain *why*, not *what*.** Self-documenting names first; comments only for non-obvious logic or constraints. | ||
| - **Function names should be self-documenting** — see [`~/.claude/CLAUDE.md`](../../../.claude/CLAUDE.md) for the user-level style guide we follow. |
There was a problem hiding this comment.
Fix broken link target for the style guide reference.
../../../.claude/CLAUDE.md points outside the repo and won’t resolve in GitHub. Point to an in-repo doc (or remove the link if intentionally external).
Suggested fix
-- **Function names should be self-documenting** — see [`~/.claude/CLAUDE.md`](../../../.claude/CLAUDE.md) for the user-level style guide we follow.
+- **Function names should be self-documenting** — see [CLAUDE.md](./CLAUDE.md) for the user-level style guide we follow.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Function names should be self-documenting** — see [`~/.claude/CLAUDE.md`](../../../.claude/CLAUDE.md) for the user-level style guide we follow. | |
| - **Function names should be self-documenting** — see [CLAUDE.md](./CLAUDE.md) for the user-level style guide we follow. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` at line 30, The markdown reference to an external style guide in
the sentence "Function names should be self-documenting" uses a broken relative
link (`../../../.claude/CLAUDE.md`); update that link in AGENTS.md so it points
to a valid in-repo document (e.g., replace with the correct path to the repo's
style guide) or remove the hyperlink if the guide is intentionally external,
ensuring the visible text "Function names should be self-documenting" remains
unchanged.
| ``` | ||
| jumper-exchange/ | ||
| ├── src/ | ||
| │ ├── app/ # Next.js App Router | ||
| │ │ ├── [lng]/ # all user-facing pages — locale-prefixed | ||
| │ │ │ ├── (main)/ # route group: landing + main shell | ||
| │ │ │ ├── (infos)/ # route group: legal / informational pages | ||
| │ │ │ ├── bridge/, swap/ # core swap surfaces | ||
| │ │ │ ├── earn/, portfolio/, quests/, missions/, campaign/, zap/, scan/, onboard/ | ||
| │ │ │ ├── error-preview/, meta/ | ||
| │ │ │ ├── error.tsx, layout.tsx | ||
| │ │ ├── api/ # Next.js route handlers (thin proxies to jumper-backend) | ||
| │ │ ├── lib/, ui/ # framework-level helpers | ||
| │ │ ├── layout.tsx, global.css, global-error.tsx, not-found.tsx, robots.ts, sitemap.xml/ | ||
| │ ├── components/ # feature components (one folder per feature) | ||
| │ │ ├── core/, composite/, headless/ # primitives by composition level | ||
| │ │ ├── <FeatureName>/ # e.g. EarnDetails, ConnectButton, Cards, … | ||
| │ ├── providers/ # provider tree: WalletProvider, ThemeProvider, | ||
| │ │ # ReactQueryProvider, TranslationProvider, … | ||
| │ ├── stores/<feature>/ # zustand stores (one folder per feature) | ||
| │ ├── hooks/<feature>/ # react-query hooks + feature hooks | ||
| │ ├── config/ # runtime config (env, wallet connectors, widget) | ||
| │ ├── i18n/translations/<lng>/ # translation JSON; resources.d.ts is generated | ||
| │ ├── theme/ # MUI theme + design tokens | ||
| │ ├── const/, types/, utils/, fonts/, stories/ | ||
| │ ├── Layout.tsx, proxy.ts | ||
| ├── tests/ # Playwright E2E + page objects + test data | ||
| ├── public/ # static assets | ||
| ├── .storybook/ # Storybook config | ||
| ├── instrumentation.ts, instrumentation-client.ts, sentry.*.config.ts | ||
| ├── next.config.mjs, vitest.config.ts, playwright.config.ts, eslint.config.mjs | ||
| ├── gen-api.sh # regenerates the typed API client from jumper-backend's Swagger | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks (MD040).
These fenced blocks should specify a language to satisfy markdownlint and improve readability.
Suggested fix
-```
+```text
jumper-exchange/
...
-```
+```
-```
+```text
┌─────────────────────────────────────────────────────────┐
...
-```
+```Also applies to: 66-91
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@ARCHITECTURE.md` around lines 30 - 62, The markdown fenced code blocks in
ARCHITECTURE.md (the ASCII project tree and other blocks shown around lines
30–62 and 66–91) lack language identifiers and trigger MD040; update each
triple-backtick fence (e.g., the block containing "jumper-exchange/" and the
other ASCII diagrams) to include a language token such as text (```text) so
markdownlint passes and readability improves—ensure every opening ``` has a
matching closing ``` and apply the same change to all similar fenced blocks in
the file.
| - **No barrel `index.ts` files.** Import from source files directly. This keeps the dependency graph honest and tree-shakeable. | ||
|
|
||
| If a change requires reversing one of these directions, **stop**. The right shape is usually to move the shared code down a level (often into `utils/` or `config/`) rather than to invert the arrow. | ||
|
|
||
| ## Invariants | ||
|
|
||
| | # | Invariant | Enforcement | | ||
| | --- | --- | --- | | ||
| | 1 | All user-facing pages live under `src/app/[lng]/` | doc; obvious on review | | ||
| | 2 | API route handlers in `src/app/api/` are thin proxies — no business logic | doc | | ||
| | 3 | Server state goes through react-query; no direct `fetch` in components | doc | | ||
| | 4 | One zustand store per feature folder under `src/stores/` | doc | | ||
| | 5 | No barrel files (`index.ts` re-exports) | doc; ESLint candidate | | ||
| | 6 | Sentry is initialised only in `instrumentation*.ts` / `sentry.*.config.ts` | doc | |
There was a problem hiding this comment.
Align “no barrel files” invariant with current repository reality.
This section defines an absolute invariant, but current code still contains barrel index.ts files (e.g., src/utils/routes/index.ts, src/hooks/userTracking/index.ts, src/providers/ThemeProvider/index.ts, src/providers/WalletProvider/index.ts). Please either scope this to “new code” or add a migration note/timeline so the architecture doc remains accurate.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@ARCHITECTURE.md` around lines 118 - 131, Update the “No barrel files
(`index.ts` re-exports)” invariant in ARCHITECTURE.md to align with repo
reality: either scope it to “new or modified code” and explicitly state that
existing barrel files (e.g., utils/routes/index.ts, hooks/userTracking/index.ts,
providers/ThemeProvider/index.ts, providers/WalletProvider/index.ts) are legacy,
or add a short migration note and timeline with an owner who will remove/replace
those barrels; change the invariant text and append a brief “Migration plan /
timeline” section that lists the known barrel examples and the expected
remediation steps and deadline.
| @@ -0,0 +1 @@ | |||
| See @AGENTS.md | |||
There was a problem hiding this comment.
Switch to a standard Markdown link for reliability.
Use a normal relative link so the pointer renders consistently in GitHub and other Markdown viewers.
Suggested fix
-See `@AGENTS.md`
+See [AGENTS.md](./AGENTS.md)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| See @AGENTS.md | |
| See [AGENTS.md](./AGENTS.md) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` at line 1, Replace the inline mention "See `@AGENTS.md`" with a
standard relative Markdown link so it renders reliably (e.g., change the text to
"See [AGENTS.md](AGENTS.md)"); locate the string "See `@AGENTS.md`" in CLAUDE.md
and update it to use the Markdown link syntax, making sure the link target
matches the repository filename exactly.
There was a problem hiding this comment.
Pull request overview
Bootstraps “agent readiness” documentation for jumper-exchange, adding new repo orientation/docs and updating the README + gitignore so new contributors/agents can quickly find commands, conventions, and architecture notes.
Changes:
- Add new docs:
AGENTS.md(entry point) andARCHITECTURE.md(app shape + dependency rules). - Add
CLAUDE.mdas a pointer file. - Update
README.mdto link the new docs and streamline dev/tools/tests sections; update.gitignorefor per-developer overrides.
Reviewed changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Links new docs; refreshes getting-started, tools, and tests guidance. |
| CLAUDE.md | Adds a pointer to AGENTS documentation. |
| ARCHITECTURE.md | Introduces documented app layout + dependency rules and invariants. |
| AGENTS.md | Adds repo conventions, entry points, and “where things go” guidance. |
| .gitignore | Ignores AGENTS.local.md / CLAUDE.local.md per-developer overrides. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ### Style rules | ||
|
|
||
| - **No barrel files** (`index.ts` re-exports). Import directly from the source file. |
There was a problem hiding this comment.
The doc states “No barrel files (index.ts re-exports)”, but the current codebase already contains many index.ts re-export barrels (e.g. src/components/AccordionFAQ/index.ts, src/stores/*/index.ts). Either adjust this rule to “avoid introducing new barrels” / “prefer direct imports for new code”, or plan/enforce a migration and link to it here.
| - **No barrel files** (`index.ts` re-exports). Import directly from the source file. | |
| - **Avoid introducing new barrel files** (`index.ts` re-exports). Prefer direct imports from the source file in new code, and do not expand existing barrels unless there is a clear reason. |
| - **No barrel files** (`index.ts` re-exports). Import directly from the source file. | ||
| - **TypeScript path aliases**: `@/foo` and `src/foo` both resolve to `./src/foo` (see `tsconfig.json` and `vitest.config.ts`). Prefer `@/` in new code. | ||
| - **Comments explain _why_, not _what_.** Self-documenting names first; comments only for non-obvious logic or constraints. | ||
| - **Function names should be self-documenting** — see [`~/.claude/CLAUDE.md`](../../../.claude/CLAUDE.md) for the user-level style guide we follow. |
There was a problem hiding this comment.
This links to ../../../.claude/CLAUDE.md, but there’s no .claude/ directory in this repository, so the link will be broken on GitHub. If there’s a shared style guide, consider linking to a URL or adding a repo-local copy (or remove the link if it’s only intended for a specific local setup).
| - **Function names should be self-documenting** — see [`~/.claude/CLAUDE.md`](../../../.claude/CLAUDE.md) for the user-level style guide we follow. | |
| - **Function names should be self-documenting** and describe intent clearly at the call site. |
| | Tests | Playwright (E2E), Vitest (unit, snapshot, Storybook) | | ||
| | Package manager | pnpm (`packageManager` field pins the version) | | ||
|
|
||
| `node >=20` is required; `.nvmrc` pins the minor. |
There was a problem hiding this comment.
node >=20 is accurate (package.json engines), but the statement “.nvmrc pins the minor” doesn’t match the current .nvmrc value (22, major only). Update the wording or pin a specific minor/patch if that’s required for tooling compatibility.
| `node >=20` is required; `.nvmrc` pins the minor. | |
| `node >=20` is required; `.nvmrc` pins the major version. |
There was a problem hiding this comment.
🧹 Nitpick comments (1)
AGENTS.md (1)
73-80: Optional: rephrase repeated “Do not …” bullets to satisfy style lint.Lines 75–79 contain multiple successive bullets starting with
**Do not**, which trips English-word-repeat style lint. It’s not functionally harmful, but consider varying the phrasing (e.g., “Avoid …”) to reduce churn in markdownlint/LanguageTool.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` around lines 73 - 80, In the "What NOT to do" section the consecutive bullets all start with the exact phrase "**Do not**", which trips the style lint; edit the bullets that currently begin with "**Do not**" (the lines listing backwards-compatibility shims, barrel index.ts files, business logic in src/app/api route handlers, Sentry.init calls, and direct strapi-cms imports) to vary phrasing while preserving meaning — e.g., change some to "Avoid …", "Do not add …", or "Refrain from …" so the repeated token "**Do not**" is not used on successive bullets.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@AGENTS.md`:
- Around line 73-80: In the "What NOT to do" section the consecutive bullets all
start with the exact phrase "**Do not**", which trips the style lint; edit the
bullets that currently begin with "**Do not**" (the lines listing
backwards-compatibility shims, barrel index.ts files, business logic in
src/app/api route handlers, Sentry.init calls, and direct strapi-cms imports) to
vary phrasing while preserving meaning — e.g., change some to "Avoid …", "Do not
add …", or "Refrain from …" so the repeated token "**Do not**" is not used on
successive bullets.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 38ea8550-a259-4398-9c1b-cbf3c9aa0a57
📒 Files selected for processing (2)
AGENTS.mdARCHITECTURE.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Laurent Senta <Laurent.Senta@gmail.com>
There was a problem hiding this comment.
♻️ Duplicate comments (2)
ARCHITECTURE.md (2)
28-60:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced code blocks.
The ASCII directory tree and data flow diagram lack language identifiers, triggering MD040 markdownlint warnings. This issue has already been flagged in previous reviews.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@ARCHITECTURE.md` around lines 28 - 60, The fenced ASCII directory tree in ARCHITECTURE.md is missing a language identifier and triggers MD040; add a language label to the opening fence (e.g., change ``` to ```text or ```bash) for the directory tree block (the triple-backtick block containing "jumper-exchange/" and its src/ subtree) and do the same for any other fenced blocks (e.g., the data flow diagram) so all triple-backtick blocks include a language identifier.
116-116:⚠️ Potential issue | 🟠 MajorAlign "no barrel files" rule with repository reality.
The absolute "No barrel
index.tsfiles" rule has already been flagged as inconsistent with the current codebase, which still contains barrel files (e.g.,src/utils/routes/index.ts,src/hooks/userTracking/index.ts,src/providers/ThemeProvider/index.ts,src/providers/WalletProvider/index.ts). This issue was previously identified and requires scoping to "new code" or adding a migration timeline.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@ARCHITECTURE.md` at line 116, The "No barrel index.ts files" rule is too absolute given existing barrel modules; update the ARCHITECTURE.md entry to scope the rule to "no new barrel index.ts files" (or add an explicit migration timeline/exemption list) and mention the existing barrel modules (e.g., routes, userTracking, ThemeProvider, WalletProvider) as accepted legacy cases; ensure the rule text explains how to add exemptions and/or the plan for migrating or removing existing barrels and where contributors should look for the policy (e.g., a migration checklist or PR tag).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@ARCHITECTURE.md`:
- Around line 28-60: The fenced ASCII directory tree in ARCHITECTURE.md is
missing a language identifier and triggers MD040; add a language label to the
opening fence (e.g., change ``` to ```text or ```bash) for the directory tree
block (the triple-backtick block containing "jumper-exchange/" and its src/
subtree) and do the same for any other fenced blocks (e.g., the data flow
diagram) so all triple-backtick blocks include a language identifier.
- Line 116: The "No barrel index.ts files" rule is too absolute given existing
barrel modules; update the ARCHITECTURE.md entry to scope the rule to "no new
barrel index.ts files" (or add an explicit migration timeline/exemption list)
and mention the existing barrel modules (e.g., routes, userTracking,
ThemeProvider, WalletProvider) as accepted legacy cases; ensure the rule text
explains how to add exemptions and/or the plan for migrating or removing
existing barrels and where contributors should look for the policy (e.g., a
migration checklist or PR tag).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 25d44f22-e082-4854-92e4-897f9b29a9da
📒 Files selected for processing (2)
ARCHITECTURE.mdREADME.md
✅ Files skipped from review due to trivial changes (1)
- README.md
Playwright test results
Details
Flaky testschromium › mainMenu.spec.ts › Main Menu flows › Should open Resources section inside menu (Qase ID: 13) Skipped testschromium › themeManipulation.spec.ts › Switch between dark and light theme and check the background color › Partner theme should appear in theme menu and apply background color (Qase ID: 49) |
Summary
Bootstraps agent-readiness docs for
jumper-exchangeso an agent (or contributor) picking up work cold has a baseline map of the repo.AGENTS.md— entry point: commands, repo conventions, pointersARCHITECTURE.md— app shape and dependency rulesCLAUDE.md— thin pointer toAGENTS.mdREADME.md— point readers at the new docs; tighten getting-started + tests sections.gitignore— ignore per-developer overrides (AGENTS.local.md,CLAUDE.local.md)Linear: JUM-870 Bootstrap the agent files (parent: JUM-869 Jumper Exchange — AI readiness, project: Jumper Engineering AI 101). Mirrors the same bootstrap that landed for
jumper-backend(JUM-863) andstrapi-cms(JUM-855).Test plan
AGENTS.mdand confirm the listed commands matchpackage.jsonscripts.ARCHITECTURE.mdand confirm the dependency rules match the actualsrc/layout.README.mdlinks toAGENTS.mdandARCHITECTURE.mdrender on GitHub.Summary by CodeRabbit