diff --git a/.cursor/automations/README.md b/.cursor/automations/README.md new file mode 100644 index 000000000..03f803152 --- /dev/null +++ b/.cursor/automations/README.md @@ -0,0 +1,46 @@ +# Cursor Automations (Version-Controlled Specs) + +This directory is a version-controlled source of truth for Cursor Cloud Automations: + +- Product UI target: https://cursor.com/automations +- Docs: https://cursor.com/docs/cloud-agent/automations + +## Why this exists + +Cursor automation prompts/config are edited in the Cursor UI, but UI state is not reviewed like code. These markdown specs provide: + +- reviewable change history in git, +- explicit workflow contracts (triggers, identifiers, safety rules), +- reusable templates for personal and team automations. + +Treat the Cursor UI as a deployment target. Treat files in this directory as canonical specs. + +## Operating model + +1. Edit or add automation specs in this directory. +2. Open PR and review prompt/rule changes like code. +3. After merge, sync the corresponding automation in Cursor UI. +4. Keep UI and spec aligned; update this directory first for future changes. + +## Current DSYS-616 suite + +- Index / suite map: + - `@.cursor/automations/dsys-616-migration-docs-cross-repo.md` +- MMDS docs automation: + - `@.cursor/automations/dsys-616-mmds-create-update-migration-docs.md` +- Mobile single-instance replacement automation: + - `@.cursor/automations/dsys-616-mobile-replace-single-instance.md` +- Extension single-instance replacement automation: + - `@.cursor/automations/dsys-616-extension-replace-single-instance.md` + +## Conventions + +- Keep one markdown spec per automation when possible. +- Include explicit trigger and PR-title/body contracts. +- Use deterministic identifiers (`DSYS_EPIC: DSYS-616`, `MIGRATION_DOCS_VERSION`, `Processed MIGRATION_DOCS_VERSION`). +- Prefer file-based comparisons over memory-based reasoning in prompts. +- Add safety constraints for search scope and write scope. + +## Notes + +This folder is also an experimentation area for evolving automation workflows before stabilizing them for wider team use. Keep experiments clear, scoped, and documented so they can be adopted or retired intentionally. diff --git a/.cursor/automations/dsys-616-extension-replace-single-instance.md b/.cursor/automations/dsys-616-extension-replace-single-instance.md new file mode 100644 index 000000000..f20cf83c0 --- /dev/null +++ b/.cursor/automations/dsys-616-extension-replace-single-instance.md @@ -0,0 +1,110 @@ +# DSYS-616: Extension - Replace Single {ComponentName} Instance + @deprecated JSDoc + +Repository: `MetaMask/metamask-extension` + +## Purpose + +For a DSYS-616 component, replace exactly one production usage and update legacy `@deprecated` JSDoc links to MMDS migration docs. + +## Repository Context + +Legacy component definitions (for JSDoc updates): + +- `https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library` + +Replacement search scopes (for usage replacement): + +- `https://github.com/MetaMask/metamask-extension/tree/main/ui/components` (excluding `component-library`) +- `https://github.com/MetaMask/metamask-extension/tree/main/ui/pages` + +Do not perform usage replacement inside `ui/components/component-library`. + +## PR Contract + +- Title: `chore: [DSYS-616] replace single {ComponentName} instance and update @deprecated JSDoc` +- PR body must include: `DSYS_EPIC: DSYS-616` +- PR body should include: `Fixes: DSYS-` +- PR body must include: `Processed MIGRATION_DOCS_VERSION: ` + +## Jira Workflow Contract + +- On first qualifying PR open for the DSYS story, transition Jira to `In Progress` if not already in progress/done. +- Never auto-close Jira issues from this automation. +- Jira closure is manual after all required PRs are merged. + +## Required Tools + +- GitHub built-in tools: + - Open pull request +- Atlassian/Jira MCP +- MCP server connector configured for Atlassian + +## GitHub Author + +- Open PR as GitHub user `{githubusername}`. +- If `{githubusername}` is not explicitly set in automation context, infer it from the signed-in Cursor account and use that value consistently for PR authoring. + +## Trigger/Input + +Use scheduled cron trigger in `MetaMask/metamask-extension`. + +On each run, discover candidate MMDS docs PRs in `MetaMask/metamask-design-system` and verify: + +- title starts with `chore: [DSYS-616] create/update` +- body includes `DSYS_EPIC: DSYS-616` +- body includes `MIGRATION_DOCS_VERSION: ` + +Only run when docs version is newer than the last processed version. + +## Rerun Determinism + +Use client PR body marker as the source of truth: + +- Marker format: `Processed MIGRATION_DOCS_VERSION: ` +- Before making changes, search existing extension PRs for same DSYS story + component. +- If a PR already contains the same processed version marker, exit silently. +- Only proceed when incoming docs version is newer than previously processed version for that story/component in extension. + +## Execution Rules + +1. Read latest MMDS migration docs for `{ComponentName}`. +2. Update `@deprecated` JSDoc on legacy extension component entry points with migration link. +3. Replace exactly one production usage (not tests/stories) of legacy component with MMDS component under allowed replacement scopes. +4. Record any doc discrepancy in PR body under section: + - `Migration doc discrepancies found` +5. Open or update draft PR with required title/body contract. + +## Safety Rules + +- Change exactly one usage site per run. +- Exclude `ui/components/component-library` from replacement target search. +- If zero safe candidates, stop and report. +- If migration docs are ambiguous, report discrepancy instead of guessing. +- If no valid MMDS docs PR candidate is found, exit silently (no PR comments). + +## Cloud Automation Prompt + +```text +Goal: In extension, replace one legacy {ComponentName} usage and update @deprecated JSDoc using latest MMDS migration docs. + +0) Open PR as GitHub user {githubusername}. If not explicitly set, infer from signed-in Cursor account. +0.1) Discover upstream MMDS docs PR candidates in MetaMask/metamask-design-system: + - title starts with chore: [DSYS-616] create/update + - body includes DSYS_EPIC: DSYS-616 + - body includes MIGRATION_DOCS_VERSION: + Pick newest unprocessed version for this repo. If none, exit silently with no PR comments. + +1) Resolve DSYS story + component from selected MMDS docs PR. +2) Fetch latest MMDS migration docs and MIGRATION_DOCS_VERSION. +3) If docs version is not newer than last processed for this story, exit. +4) Update @deprecated JSDoc links for legacy extension entry points. +5) Replace exactly one production usage (exclude tests/stories). +6) If docs are unclear or incorrect, add details to "Migration doc discrepancies found" in PR body. +7) Open/update draft PR with: + - title: chore: [DSYS-616] replace single {ComponentName} instance and update @deprecated JSDoc + - body includes: DSYS_EPIC: DSYS-616 + - body should include: Fixes: DSYS- + - include Processed MIGRATION_DOCS_VERSION: . +8) On first qualifying PR open, transition Jira ticket to In Progress (if not already in progress/done). Do not auto-close Jira. +9) Output summary: changed files, replaced callsite, jira transition status, discrepancies. +``` diff --git a/.cursor/automations/dsys-616-migration-docs-cross-repo.md b/.cursor/automations/dsys-616-migration-docs-cross-repo.md new file mode 100644 index 000000000..2cb3dcbda --- /dev/null +++ b/.cursor/automations/dsys-616-migration-docs-cross-repo.md @@ -0,0 +1,29 @@ +# dsys-616-migration-docs-cross-repo + +This file is now an index for the DSYS-616 automation suite split into three automation specs: + +1. `MMDS docs authoring`: + - `@.cursor/automations/dsys-616-mmds-create-update-migration-docs.md` +2. `Mobile single-instance migration`: + - `@.cursor/automations/dsys-616-mobile-replace-single-instance.md` +3. `Extension single-instance migration`: + - `@.cursor/automations/dsys-616-extension-replace-single-instance.md` + +All three specs share these contracts: + +- PR title format: + - `chore: [DSYS-616] create/update {ComponentName} migration docs` + - `chore: [DSYS-616] replace single {ComponentName} instance and update @deprecated JSDoc` +- Epic marker in PR body: + - `DSYS_EPIC: DSYS-616` +- Jira issue linking in PR body (recommended, not primary matcher): + - `Fixes: DSYS-` +- Jira workflow: + - transition to `In Progress` on first qualifying PR open + - no auto-close (manual close after all required PRs are merged) +- MMDS docs version marker: + - `MIGRATION_DOCS_VERSION: ` in MMDS docs PR body +- Client rerun determinism marker: + - `Processed MIGRATION_DOCS_VERSION: ` in mobile/extension PR bodies +- Client trigger model: + - scheduled cron in mobile/extension repos with MMDS PR discovery by title + body markers diff --git a/.cursor/automations/dsys-616-mmds-create-update-migration-docs.md b/.cursor/automations/dsys-616-mmds-create-update-migration-docs.md new file mode 100644 index 000000000..7674e9e33 --- /dev/null +++ b/.cursor/automations/dsys-616-mmds-create-update-migration-docs.md @@ -0,0 +1,152 @@ +# DSYS-616: MMDS - Create/Update {ComponentName} Migration Docs + +Repository: `MetaMask/metamask-design-system` + +## Purpose + +Create or improve migration docs for one component, then absorb feedback from client PRs (mobile/extension) and iterate docs until discrepancies are resolved. + +## Repository Context + +Primary legacy source roots to audit: + +- Extension: + - `https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library` +- Mobile: + - `https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library/components` + +MMDS target source roots to compare against: + +- React: + - `https://github.com/MetaMask/metamask-design-system/tree/main/packages/design-system-react/src/components` +- React Native: + - `https://github.com/MetaMask/metamask-design-system/tree/main/packages/design-system-react-native/src/components` + +Folder structures may vary by component, but searches should start in these roots before broadening. + +## PR Contract + +- Title: `chore: [DSYS-616] create/update {ComponentName} migration docs` +- PR body must include: `DSYS_EPIC: DSYS-616` +- PR body should include: `Fixes: DSYS-` +- PR body must include: `MIGRATION_DOCS_VERSION: ` + +## Jira Workflow Contract + +- On first qualifying PR open for the DSYS story, transition Jira to `In Progress` if not already in progress/done. +- Never auto-close Jira issues from this automation. +- Jira closure is manual after all required PRs are merged. + +## Required Tools + +- GitHub built-in tools: + - Open pull request + - Comment on pull request +- Atlassian/Jira MCP +- MCP server connector configured for Atlassian + +## GitHub Author + +- Open PR as GitHub user `{githubusername}`. +- If `{githubusername}` is not explicitly set in automation context, infer it from the signed-in Cursor account and use that value consistently for PR authoring. + +## Golden Paths + +- Text + Box: https://github.com/MetaMask/metamask-design-system/pull/953 +- Icon: https://github.com/MetaMask/metamask-design-system/pull/962 + +## Breaking-Change Quality Gate + +For every run, compare legacy vs MMDS APIs before editing docs: + +1. Legacy API in extension and mobile codebases (when in scope): props, enums/unions, required/default values, callback signatures. +2. MMDS API in `design-system-react` and `design-system-react-native`. +3. Produce a structured mapping in docs: removed, renamed, type/value changes, default changes, behavior notes. +4. Include before/after examples for extension and mobile. +5. If source comparison is incomplete, stop and report missing files. + +## Required Deliverables (Docs Story) + +For component docs stories (for example DSYS-632 style work), completion requires all of: + +1. React migration section in `packages/design-system-react/MIGRATION.md`. +2. React Native migration section in `packages/design-system-react-native/MIGRATION.md`. +3. React component README migration link in `packages/design-system-react/src/components/{ComponentName}/README.mdx`. +4. React Native component README migration link in `packages/design-system-react-native/src/components/{ComponentName}/README.md`. + +Do not treat MIGRATION-only edits as complete when README files exist for the component. + +## Validation Gate + +Before opening or updating the PR, run lint autofix and validation: + +1. `yarn lint:fix` +2. `yarn lint` + +If lint still fails, do not open/update the PR. Report the failing files/errors in the run summary. + +## Audit Procedure (File-Based, Not Memory-Based) + +1. Locate component paths under extension/mobile legacy source roots. +2. Locate MMDS component paths under React and React Native roots. +3. Compare from source files: + - props/types/interfaces, + - enum/union values, + - default values, + - callback signatures. +4. Generate migration docs from this explicit diff. +5. If either side is unresolved, report exact missing paths and stop. + +## Feedback Loop Rules + +Scan client PRs for DSYS-616 component work and feed findings back into docs: + +1. Find mobile/extension PRs with title containing `[DSYS-616]` and body containing `DSYS_EPIC: DSYS-616`. +2. Read `Migration doc discrepancies found` section in those PRs. +3. If discrepancies exist, update MMDS migration docs and push/update MMDS PR. +4. Add a comment linking the MMDS docs fix back to each client PR. + +## Loop Trigger Identifier + +Use `MIGRATION_DOCS_VERSION` in PR body/comments (for example commit SHA of docs section update). + +- Any docs version change should trigger another client replacement run. +- Do not rerun clients if version is unchanged. + +## Downstream Discovery Contract + +Client automations (mobile/extension) discover MMDS docs PRs on cron. + +- Discovery signals: + - title starts with `chore: [DSYS-616] create/update` + - body contains `DSYS_EPIC: DSYS-616` + - body contains `MIGRATION_DOCS_VERSION: ` + +## Cloud Automation Prompt + +```text +Goal: Create/update migration docs for one component and keep them accurate using client feedback. + +0) Open PR as GitHub user {githubusername}. If not explicitly set, infer from signed-in Cursor account. + +1) Pick DSYS-616 story + component from Jira. +2) Enforce breaking-change quality gate by comparing extension/mobile legacy APIs with MMDS React/RN APIs. +3) Update migration docs and examples in both React and React Native MIGRATION.md. +4) Update component README migration links in both packages when README files exist: + - React: packages/design-system-react/src/components/{ComponentName}/README.mdx + - React Native: packages/design-system-react-native/src/components/{ComponentName}/README.md +5) If README files exist but are not updated, stop and report incomplete deliverables. +6) Run validation gate: + - yarn lint:fix + - yarn lint + If lint fails, stop and report failures without opening/updating PR. +7) Open or update PR with: + - title: chore: [DSYS-616] create/update {ComponentName} migration docs + - body includes: DSYS_EPIC: DSYS-616 + - body should include: Fixes: DSYS- + - body includes: MIGRATION_DOCS_VERSION: +8) On first qualifying PR open, transition Jira ticket to In Progress (if not already in progress/done). Do not auto-close Jira. +9) Scan DSYS-616 client PRs in extension/mobile for "Migration doc discrepancies found". +10) If discrepancies are present, patch docs, update the same PR, and comment back with the docs-fix link. +11) Output summary: story key, component, docs version, files updated (including README links), lint status, jira transition status, discrepancy actions taken. +``` diff --git a/.cursor/automations/dsys-616-mobile-replace-single-instance.md b/.cursor/automations/dsys-616-mobile-replace-single-instance.md new file mode 100644 index 000000000..134b5a095 --- /dev/null +++ b/.cursor/automations/dsys-616-mobile-replace-single-instance.md @@ -0,0 +1,114 @@ +# DSYS-616: Mobile - Replace Single {ComponentName} Instance + @deprecated JSDoc + +Repository: `MetaMask/metamask-mobile` + +## Purpose + +For a DSYS-616 component, replace exactly one production usage and update legacy `@deprecated` JSDoc links to MMDS migration docs. + +## Repository Context + +Legacy component definitions (for JSDoc updates): + +- `https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library/components` + +Replacement search scope (for usage replacement): + +- `https://github.com/MetaMask/metamask-mobile/tree/main/app/components` + +Do not perform usage replacement inside the legacy component-library root. + +## PR Contract + +- Title: `chore: [DSYS-616] replace single {ComponentName} instance and update @deprecated JSDoc` +- PR body must include: `DSYS_EPIC: DSYS-616` +- PR body should include: `Fixes: DSYS-` +- PR body must include: `Processed MIGRATION_DOCS_VERSION: ` + +## Jira Workflow Contract + +- On first qualifying PR open for the DSYS story, transition Jira to `In Progress` if not already in progress/done. +- Never auto-close Jira issues from this automation. +- Jira closure is manual after all required PRs are merged. + +## Required Tools + +- GitHub built-in tools: + - Open pull request +- Atlassian/Jira MCP +- MCP server connector configured for Atlassian + +## GitHub Author + +- Open PR as GitHub user `{githubusername}`. +- If `{githubusername}` is not explicitly set in automation context, infer it from the signed-in Cursor account and use that value consistently for PR authoring. + +## Trigger/Input + +Use scheduled cron trigger in `MetaMask/metamask-mobile`. + +On each run, discover candidate MMDS docs PRs in `MetaMask/metamask-design-system` and verify: + +- title starts with `chore: [DSYS-616] create/update` +- body includes `DSYS_EPIC: DSYS-616` +- body includes `MIGRATION_DOCS_VERSION: ` + +Only run when docs version is newer than the last processed version. + +## Rerun Determinism + +Use client PR body marker as the source of truth: + +- Marker format: `Processed MIGRATION_DOCS_VERSION: ` +- Before making changes, search existing mobile PRs for same DSYS story + component. +- If a PR already contains the same processed version marker, exit silently. +- Only proceed when incoming docs version is newer than previously processed version for that story/component in mobile. + +## Execution Rules + +1. Read latest MMDS migration docs for `{ComponentName}`. +2. Update `@deprecated` JSDoc on legacy mobile component entry points using exactly two `@see` links: + - MMDS RN README: `https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/{ComponentName}/README.md` + - MMDS RN migration guide anchor: `https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#{component-anchor}` +3. Replace exactly one production usage (not tests/stories) of legacy component with MMDS component under `app/components`. +4. Record any doc discrepancy in PR body under section: + - `Migration doc discrepancies found` +5. Open or update draft PR with required title/body contract. + +## Safety Rules + +- Change exactly one usage site per run. +- Exclude `app/component-library/components` from replacement target search. +- If zero safe candidates, stop and report. +- If migration docs are ambiguous, report discrepancy instead of guessing. +- If no valid MMDS docs PR candidate is found, exit silently (no PR comments). +- If deprecated JSDoc does not contain exactly the two required `@see` links, stop and report. + +## Cloud Automation Prompt + +```text +Goal: In mobile, replace one legacy {ComponentName} usage and update @deprecated JSDoc using latest MMDS migration docs. + +0) Open PR as GitHub user {githubusername}. If not explicitly set, infer from signed-in Cursor account. +0.1) Discover upstream MMDS docs PR candidates in MetaMask/metamask-design-system: + - title starts with chore: [DSYS-616] create/update + - body includes DSYS_EPIC: DSYS-616 + - body includes MIGRATION_DOCS_VERSION: + Pick newest unprocessed version for this repo. If none, exit silently with no PR comments. + +1) Resolve DSYS story + component from selected MMDS docs PR. +2) Fetch latest MMDS migration docs and MIGRATION_DOCS_VERSION. +3) If docs version is not newer than last processed for this story, exit. +4) Update @deprecated JSDoc links for legacy mobile entry points with exactly: + - @see {link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/{ComponentName}/README.md | MMDS README} + - @see {link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#{component-anchor} | Migration Guide} +5) Replace exactly one production usage (exclude tests/stories). +6) If docs are unclear or incorrect, add details to "Migration doc discrepancies found" in PR body. +7) Open/update draft PR with: + - title: chore: [DSYS-616] replace single {ComponentName} instance and update @deprecated JSDoc + - body includes: DSYS_EPIC: DSYS-616 + - body should include: Fixes: DSYS- + - include Processed MIGRATION_DOCS_VERSION: . +8) On first qualifying PR open, transition Jira ticket to In Progress (if not already in progress/done). Do not auto-close Jira. +9) Output summary: changed files, replaced callsite, jira transition status, discrepancies. +``` diff --git a/docs/ai-agents.md b/docs/ai-agents.md index 22879a2a8..47cfb42d1 100644 --- a/docs/ai-agents.md +++ b/docs/ai-agents.md @@ -20,6 +20,9 @@ Engineers can reference `.cursor/rules/` directly when needed, but the primary i ├── CLAUDE.md # Layer 1: Entry point (40-120 lines) ├── .cursor/rules/ # Layer 2: Focused rules (200-400 lines each) │ └── *.md # Individual rule files +├── .cursor/automations/ # Layer 2.5: Version-controlled automation specs +│ ├── README.md # Automation operating model +│ └── *.md # One spec per automation └── docs/ # Layer 3: High-level guides └── ai-agents.md # This file - strategy explanation ``` @@ -82,6 +85,26 @@ Engineers can reference `.cursor/rules/` directly when needed, but the primary i - **Reference-based:** Rules point to canonical code examples in the codebase rather than duplicating them - **Maintainable:** Checklists easier to update than narratives +## Layer 2.5: .cursor/automations/ (Automation Specs) + +**Purpose:** Keep Cursor Cloud Automation logic reviewable in git. + +**Why:** Automations are configured in Cursor UI, but UI state is not code-reviewed by default. Specs in `.cursor/automations/` provide auditable history and explicit trigger/PR contracts. + +**Operating Model:** + +1. Edit automation markdown specs in `.cursor/automations/`. +2. Review and merge spec changes via PR. +3. Sync merged spec changes into Cursor UI automation settings. +4. Treat UI as deployment target, repo markdown as canonical source. + +**Conventions:** + +- One markdown file per automation where possible. +- Include explicit trigger definitions and PR title/body contracts. +- Use deterministic identifiers (`Fixes: DSYS-`, version markers). +- Prefer file-path-based comparison/audit instructions over vague prompts. + ## Layer 3: docs/ (High-Level Guides) **Purpose:** High-level contributor guides and infrequent processes.