|
| 1 | +# Agent & Assistant Guidelines (PayPal Messaging Components) |
| 2 | + |
| 3 | +## Persona & style |
| 4 | + |
| 5 | +- Address the user as Developer. |
| 6 | +- Open: "Hi Developer — <motivation>." then act. |
| 7 | +- Telegraph; noun phrases OK; minimal tokens; expand only for clarity. |
| 8 | +- Ask clarifying questions whenever requirements are underspecified or constraints are missing. |
| 9 | +- For PR comment review tasks: validate each PR comment to ensure it makes sense, avoid false positives, and state why it is valid or not. |
| 10 | +- During plan/research: actively look for codebase improvements and friction/misalignment with existing patterns; call them out with concrete suggestions (and tradeoffs when relevant). |
| 11 | +- Optimize for correctness + leverage; be direct/critical when needed. |
| 12 | +- Never claim checks ran unless they actually ran; cite commands executed. |
| 13 | +- Every time you plan a feature, make it comprehensive and detailed, and include robust acceptance criteria to validate the changes. Do not stop until acceptance criteria is met. |
| 14 | + |
| 15 | +## Subagents |
| 16 | + |
| 17 | +- Always wait for all subagents to complete before yielding. |
| 18 | +- Spawn subagents automatically when: |
| 19 | + - Parallelizable work (e.g., `npm run lint` + `npm test`, snapshot review + content scan). |
| 20 | + - Long-running or blocked tasks where a worker can run independently (e.g., functional suites, build validation). |
| 21 | + - Isolation for risky changes or checks (e.g., content/i18n, modal rendering, build/release scripts). |
| 22 | +- Give each subagent crisp context, the exact files it needs, and clear instructions with expected output format. |
| 23 | +- When a subagent completes, log the finish here, mark the task done, then immediately check for newly unblocked tasks. |
| 24 | +- Repeat the cycle until the entire plan is complete. |
| 25 | +- Use subagents liberally to keep the main context window clean for long-running work. |
| 26 | +- Offload research, exploration, and parallel analysis to subagents whenever tasks are independent. |
| 27 | +- Keep one task per subagent for focused execution and easier validation handoff. |
| 28 | + |
| 29 | + |
| 30 | +## Docs-first (read before coding) |
| 31 | + |
| 32 | +- `README.md` (scripts, dev server targets, stage env override) |
| 33 | +- `CONTRIBUTING.md` (contribution expectations) |
| 34 | +- `docs/message-demo-pages.md` (demo + snapshot pages) |
| 35 | +- `docs/message-types.md` (message/modal type naming by locale) |
| 36 | +- `docs/message-stage-bundle.md` (internal stage-tag bundle workflow) |
| 37 | +- `tests/playwright/README.md` (Playwright usage notes) |
| 38 | +- `src/components/modal/v2/parts/views/README.md` (how to add modal "views" correctly) |
| 39 | + |
| 40 | +## Context7 MCP (3rd-party docs) |
| 41 | + |
| 42 | +- Use Context7 for library/API documentation, setup steps, and configuration guidance. |
| 43 | +- Always call `resolve-library-id` first, then `query-docs` with that ID. |
| 44 | +- Be specific in queries; max 3 calls per question. |
| 45 | + |
| 46 | +## Project snapshot |
| 47 | + |
| 48 | +- **Runtime**: Node `20` (see `.nvmrc`) |
| 49 | +- **Build**: Webpack 4 + `@krakenjs/webpack-config-grumbler` (`webpack.config.js`, `webpack.config.dev.js`) |
| 50 | +- **UI**: Preact + JSX (`preact`, `@krakenjs/jsx-pragmatic`) + SCSS (modal v2) |
| 51 | +- **Cross-domain components**: Zoid + Post-Robot (`@krakenjs/zoid`, `@krakenjs/post-robot`) |
| 52 | +- **Primary outputs**: |
| 53 | + - `dist/` bundles (built via release/asset script; do not hand-edit) |
| 54 | + - `demo/` pages for local verification |
| 55 | +- **Content**: locale-specific JSON under `content/` (messages/modals/offers) |
| 56 | + |
| 57 | +## Key directories (where things live) |
| 58 | + |
| 59 | +- `src/library/`: library entrypoints (`messaging.js`, `modal.js`) |
| 60 | +- `src/components/`: Zoid components |
| 61 | + - `src/components/message/` |
| 62 | + - `src/components/modal/v2/` (modern modal) |
| 63 | +- `src/server/`: server-side rendering / endpoints used by demos and tests |
| 64 | +- `content/`: localized copy and configuration payloads |
| 65 | + - `content/messages/<LOCALE>/*.json` |
| 66 | + - `content/modals/<LOCALE>/*.json` |
| 67 | + - `content/offers/<LOCALE>/*.json` |
| 68 | +- `demo/`: local demo + snapshot pages (`demo/standalone.html`, `demo/snapshot/*.html`) |
| 69 | +- `tests/`: unit + functional snapshot suites + Playwright |
| 70 | +- `utils/devServerProxy/`: local dev-server proxy hooks |
| 71 | + |
| 72 | +## Coding & formatting standards |
| 73 | + |
| 74 | +- **Prettier**: `.prettierrc.js` (4 spaces, `printWidth: 120`, single quotes, semicolons) |
| 75 | +- **ESLint**: `.eslintrc` (Airbnb + Prettier; `prettier/prettier` enforced as error) |
| 76 | +- **Lint-staged**: `.lintstagedrc.js` (formats/lints staged JS/JSX + formats json/md/html/css) |
| 77 | + |
| 78 | +## Local gate (run before PR / handoff) |
| 79 | + |
| 80 | +- `nvm use` (Node 20) |
| 81 | +- `npm install` |
| 82 | +- `npm run lint` |
| 83 | +- `npm test` (unit tests; Jest) |
| 84 | + |
| 85 | +Run additional suites when you touched related areas: |
| 86 | + |
| 87 | +- **Functional (puppeteer) tests**: |
| 88 | + - Start server: `npm run dev:ci` |
| 89 | + - Then run: |
| 90 | + - `npm run test:func` (all functional) |
| 91 | + - `npm run test:func:nosnaps` (functional without snapshots) |
| 92 | + - `npm run test:func:snapshots` (v2 snapshot suite) |
| 93 | +- **Build sanity**: |
| 94 | + - `npm run build:production` (or `npm run build:stage` / `npm run build:sandbox` as appropriate) |
| 95 | + |
| 96 | +## Verify & iterate (behavior-first) |
| 97 | + |
| 98 | +- If you change rendering/UX, verify with local demo pages: |
| 99 | + - `npm start` then open `demo/standalone.html` |
| 100 | + - For multi-banner comparisons: `demo/text.html`, `demo/flex.html` (see `docs/message-demo-pages.md`) |
| 101 | +- If you change snapshot-relevant rendering, use snapshot pages (`demo/snapshot/*.html`) and run the snapshot suite. |
| 102 | +- If tests fail: reproduce → fix root cause → re-run the same suite(s) until green. |
| 103 | +- When fixing bugs: reproduce first → fix → verify the fix via the most relevant demo/tests. |
| 104 | +- Never mark work complete without proving behavior with relevant tests, logs, or runtime checks. |
| 105 | +- When relevant, compare behavior between base/main and your changes to confirm intended deltas. |
| 106 | +- Apply a staff-level quality bar: ask whether the result is robust, observable, and review-ready. |
| 107 | + |
| 108 | + |
| 109 | +## Tests (what to run and when) |
| 110 | + |
| 111 | +- **Unit**: `npm test` (Jest, jsdom; HTML report at `tests/__reports__/unit.html`) |
| 112 | +- **Functional / snapshots**: Jest + Puppeteer |
| 113 | + - Snapshot update flows: |
| 114 | + - `npm run test:func:ciupdate` (updates snapshots for functional suite) |
| 115 | + - `npm run test:func:snapshots:ciupdate` (updates v2 snapshot suite) |
| 116 | + - Targeted snapshots use `CONFIG_PATH` (from `README.md`): |
| 117 | + - `CONFIG_PATH={locale}/{account} npm run test:func:snapshots -- --testPathPattern {integrationType}` |
| 118 | +- **Playwright**: `npx playwright test` |
| 119 | + - Note: `playwright.config.js` references `./.github/scripts/runServerV2.sh` as `webServer.command`. |
| 120 | + - If that script is missing in your checkout, Playwright will not be able to auto-start the server; start a dev server yourself (e.g. `npm run dev:ci`) and adjust the config/command as needed in your change. |
| 121 | + |
| 122 | +## Playwright interactive debugging |
| 123 | + |
| 124 | +Use Playwright’s interactive modes when tests fail or when implementing a complex user flow. |
| 125 | + |
| 126 | +- **When to use**: |
| 127 | + - Browser tests failing; need to see what’s happening. |
| 128 | + - New/complex modal or banner flows; verify end-to-end behavior. |
| 129 | + - Timing/race issues and flaky selectors. |
| 130 | +- **How to use (CLI)** (see `tests/playwright/README.md`): |
| 131 | + - `npx playwright test --ui` |
| 132 | + - `npx playwright test --debug` |
| 133 | + - `npx playwright test --headed` |
| 134 | + - `npx playwright test --project=chromium` |
| 135 | + - Tip: cap concurrency locally with `--workers <n>` if needed. |
| 136 | +- **Principles**: |
| 137 | + - Test what a real user experiences, not what code "should" do. |
| 138 | + - Prefer screenshots/trace on failures; update selectors only after confirming the DOM/state. |
| 139 | + |
| 140 | +## Content & i18n safety (JSON under `content/`) |
| 141 | + |
| 142 | +- Treat `content/` as product-facing copy/config; changes are high-impact. |
| 143 | +- Keep locale files consistent with existing naming conventions (see `docs/message-types.md`). |
| 144 | +- Prefer minimal diffs; avoid unnecessary reformatting across many JSON files. |
| 145 | +- If you update content that affects rendering, run the relevant snapshot suite(s) to catch regressions. |
| 146 | + |
| 147 | +## Modal v2 "views" (when adding/changing views) |
| 148 | + |
| 149 | +- Follow `src/components/modal/v2/parts/views/README.md`: |
| 150 | + - New view folder with `Content.jsx` |
| 151 | + - Export from the `views/index.js` |
| 152 | + - Preserve shared structural classNames (`content__container`, `content__body`, etc.) to reuse shared styles |
| 153 | + - For per-view overrides, add a local `.scss` and inject via `<style>{fileName._getCss()}</style>` pattern |
| 154 | + |
| 155 | +## Dev servers & environments |
| 156 | + |
| 157 | +- Primary dev entrypoints: |
| 158 | + - `npm run dev` (TARGET=sdk) |
| 159 | + - `npm run dev:standalone`, `npm run dev:modal`, `npm run dev:lander` |
| 160 | + - `npm run dev:stage`, `npm run dev:sandbox`, `npm run dev:production` |
| 161 | +- Environment override for demos (dev only): set `window.__TEST_ENV__` in the demo page (see `README.md`). |
| 162 | + |
| 163 | +## Release & dist hygiene |
| 164 | + |
| 165 | +- Releases are driven by `semantic-release` (`release.config.js`) and build assets via `./scripts/semantic-release/assets.sh`. |
| 166 | +- Avoid committing changes to `dist/` unless you are intentionally running the release/asset workflow; `dist/` is large and should reflect an intentional build. |
| 167 | + |
| 168 | +## Git hooks (Husky) & staged-file hygiene |
| 169 | + |
| 170 | +- Pre-commit runs `lint-staged` + `npm test` (see `scripts/husky/pre-commit.sh`). |
| 171 | +- Expect staged JS/JSX to be formatted by Prettier and checked by ESLint before commit (see `.lintstagedrc.js`). |
| 172 | + |
| 173 | +## Cross-platform scripts |
| 174 | + |
| 175 | +- Prefer `npm run <script>` over ad-hoc command invocations so workflows stay consistent. |
| 176 | +- Avoid adding Unix-only shell one-liners directly into `package.json` scripts; prefer Node scripts or existing repo patterns (e.g. webpack `--env ...` flags). |
| 177 | +- Do not add new dependencies (like `cross-env`) without approval. |
| 178 | + |
| 179 | +## Production safety |
| 180 | + |
| 181 | +- Assume production impact unless stated otherwise; this repo ships merchant-facing messaging UX. |
| 182 | +- Prefer small, reversible changes; call out risk when touching content, rendering, tests, or build/release scripts. |
| 183 | + |
| 184 | +## Critical thinking |
| 185 | + |
| 186 | +- Fix root cause; avoid band-aids. |
| 187 | +- Unsure: read more code/docs; if still ambiguous, ask with short options. |
| 188 | +- Conflicts between docs and code: call out; pick the safer/more consistent path. |
| 189 | +- Unrecognized large diffs: assume other agent or context missing; proceed cautiously. |
| 190 | + |
| 191 | +## SCM & safety |
| 192 | + |
| 193 | +- No destructive git commands (`reset --hard`, `clean`) without explicit permission. |
| 194 | +- No new deps/services without approval. |
| 195 | +- Keep secrets out of code/logs. Use env/global overrides as documented. |
| 196 | +- Prefer small, reversible changes; call out risk when touching content rendering, tests, or build/release scripts. |
| 197 | + |
| 198 | +## Acceptance criteria (for changes you make) |
| 199 | + |
| 200 | +- Include a clear plan with acceptance criteria before implementing non-trivial changes. |
| 201 | +- Keep changes aligned with repo patterns (webpack targets, demo verification, test suites). |
| 202 | +- Run the most relevant local gates for the impacted area(s) and cite the commands you executed. |
| 203 | + |
| 204 | +## Plan Mode Default |
| 205 | + |
| 206 | +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). |
| 207 | +- If execution goes sideways, stop and re-plan immediately before continuing. |
| 208 | +- Include verification steps in the plan, not only implementation steps. |
| 209 | +- Write detailed specs up front to reduce ambiguity and rework. |
| 210 | + |
| 211 | +## Demand Elegance (Balanced) |
| 212 | + |
| 213 | +- For non-trivial changes, pause and ask whether there is a more elegant path before implementation. |
| 214 | +- If a fix feels hacky, prefer the cleaner approach you would choose with full context. |
| 215 | +- Skip elegance over-optimization for obvious small fixes; do not over-engineer. |
| 216 | + |
| 217 | +## Autonomous Bug Fixing |
| 218 | + |
| 219 | +- When given a bug report, own the full path: reproduce, identify root cause, fix, and verify. |
| 220 | +- Start from logs, errors, and failing tests; resolve issues with minimal user context switching. |
| 221 | +- If CI checks fail in scope, investigate and fix them without waiting for step-by-step instructions. |
| 222 | + |
| 223 | +## Task Management (Portable) |
| 224 | + |
| 225 | +- For non-trivial work, maintain a checkable plan in tasks/todo.md. |
| 226 | +- Track progress as items are completed and include brief review notes for key decisions. |
| 227 | +- Capture recurring corrections and preventions in tasks/lessons.md. |
| 228 | +- If tasks/todo.md or tasks/lessons.md does not exist, create it on demand for active work. |
| 229 | + |
| 230 | +## Core Principles |
| 231 | + |
| 232 | +- Simplicity first: keep each change as small as possible while solving the right problem. |
| 233 | +- No laziness: find and fix root causes, not temporary patches. |
| 234 | +- Minimal impact: touch only what is necessary and avoid introducing regressions. |
| 235 | + |
| 236 | +## Self-improvement |
| 237 | + |
| 238 | +- After any user correction, update portable task notes (tasks/lessons.md) with mistake-prevention rules. |
| 239 | +- Review relevant lessons at the start of related tasks and apply them proactively. |
| 240 | +- Iterate on these lessons until repeat mistakes materially drop. |
| 241 | + |
| 242 | + |
| 243 | +- If we hit the same correction twice, codify it in `AGENTS.md` so future work stays aligned. |
| 244 | + |
| 245 | + |
| 246 | + |
| 247 | + |
| 248 | +## Service Dependencies |
| 249 | + |
| 250 | +- Keep dependency references high-level in this public repository. |
| 251 | +- If a change requires deep internal service details, escalate to maintainers and use internal docs for implementation specifics. |
0 commit comments