diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md new file mode 100644 index 000000000..2385a42e2 --- /dev/null +++ b/.cursor/automations/enum-shared-type-migration.md @@ -0,0 +1,202 @@ +# enum-shared-type-migration + +Daily Jira pickup for epic **DSYS-468** (_Component ADR Migration_ / ADR-0003 & ADR-0004). + +## Purpose (version control for Cursor Automations) + +[Cursor Automations](https://cursor.com/docs/cloud-agent/automations) prompts in the Cursor product are **not** stored in this git repo. This file **is** the **canonical, reviewable spec**: change it here (PRs, `main`, tags) and treat the UI as a **deployment target**. + +- **Stable link** — Use a GitHub URL to this path on `main` (or pin a **commit SHA** when you need a frozen prompt). Prefer having the automation run against a branch that **includes** this file, and tell the agent to read `.cursor/automations/enum-shared-type-migration.md` in the workspace; the URL is for humans, pinning, or tooling that fetches raw markdown. +- **Copy-paste** — Paste sections (e.g. the cloud prompt block below) into **Private** or **Team Visible** automations. When the spec changes, merge the PR here, then update the pasted prompt or the link you use. + +**Invoke (IDE):** `@.cursor/automations/enum-shared-type-migration.md`. + +**Strategy:** Matches [docs/ai-agents.md](../../docs/ai-agents.md): _reference over duplication_, _checklists over narratives_, _context efficiency_. This file only defines **orchestration** (Jira, triggers, PR identity). **Implementation guardrails and golden paths** live in `@.cursor/rules/` — agents must read those files, not improvise from this doc alone. + +## Scope (edit if your epic or identity changes) + +| Setting | Value | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| Epic | **DSYS-468** — _Component ADR Migration: Align with ADR-0003 and ADR-0004_ | +| Board (reference) | [DSYS board — epic filter](https://consensyssoftware.atlassian.net/jira/software/c/projects/DSYS/boards/1888?issueParent=343549) | + +## 1. Find candidates + +Run JQL (company-managed / parent epic): + +```jql +parent = DSYS-468 AND statusCategory != "Done" ORDER BY Rank ASC +``` + +If you only want work already on your plate: + +```jql +parent = DSYS-468 AND statusCategory != "Done" AND assignee = currentUser() ORDER BY Rank ASC +``` + +Next **unclaimed** item: + +```jql +parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC +``` + +## 2. Choose one issue + +### Interactive (IDE / manual run) + +- Prefer **In Progress** already assigned to you (continue that thread). +- Else prefer **To Do** assigned to you. +- Else take the **first** issue from the unassigned `To Do` query (top of backlog order). + +### Scheduled Cursor Cloud Automation (“always take backlog”) + +Use **only** unclaimed work so each run picks a new ticket: + +```jql +parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC +``` + +Take the **first** result. If the list is empty, stop (no PR); optionally comment in the run log or Slack. + +**Jira + cloud agent:** Enable your **Atlassian/Jira MCP** (or equivalent) on the automation so the agent can search JQL, assign, and transition. Without Jira tools, the automation cannot claim tickets by itself. + +## 3. Pick up in Jira + +- If unassigned, set **assignee** to you (`editJiraIssue`, or equivalent). +- If still in **To Do**, use `getTransitionsForJiraIssue` then `transitionJiraIssue` to move to **In Progress** (or the project’s equivalent “active” state). + +## 4. Reply in chat + +- Issue key, summary, status, link (`https://consensyssoftware.atlassian.net/browse/`). +- One-line suggestion for what to do first in this repo (e.g. component name from the summary). +- If no issues match, say so and suggest checking epic **DSYS-468** or relaxing JQL. + +## 5. Open the PR as your GitHub user + +### Cursor Cloud Automations ([docs](https://cursor.com/docs/cloud-agent/automations)) + +Create and manage automations at [cursor.com/automations](https://cursor.com/automations). Flow: pick a **trigger** (schedule, GitHub event, Slack, webhook, Linear, PagerDuty, etc.), write the **prompt**, enable **tools** (e.g. Open pull request, MCP). + +**Who opens the PR** (per Cursor docs — _Identity_): + +| Automation permission | Pull requests opened as | +| ------------------------------- | ------------------------------------------------ | +| **Private** or **Team Visible** | **Your** GitHub account | +| **Team Owned** | The **`cursor`** service account (not your user) | + +GitHub **comments**, **review approvals**, and **reviewer requests** run as **`cursor`** regardless. **Slack** sends as the Cursor bot. + +**Billing**: Automations use cloud agents; cost follows the automation’s permission scope (team pool for Team Owned, creator for Private / Team Visible). Enable **Open pull request** when the automation should commit and open a PR. + +For **scheduled** (or Slack, etc.) triggers you choose **repository and branch** explicitly — Cursor does not infer them from a PR. + +### Local agent / `gh` on your machine + +When **you** run the agent in the IDE and it uses **`gh pr create`**, the PR author is whoever is logged into the GitHub CLI: + +```bash +gh auth status +``` + +- **Fork workflow**: push to your fork’s `origin`, then `gh pr create` toward upstream — you remain the opener. +- **PR body**: Follow `.github/pull_request_template.md` and `@pr` / `.cursor/rules/pr.mdc`. + +## 6. Implement the migration (ADR-0003 / ADR-0004) + +DSYS-468 tasks are **internal refactors** of components already in the monorepo (e.g. “Migrate **BadgeStatus** …”). They are **not** extension/mobile imports. + +### Guardrails (agent must not skip) + +- ❌ Do **not** use `@.cursor/rules/component-migration.md` for this epic (extension/mobile → monorepo only). +- ✅ Do use `@CLAUDE.md` for **monorepo commands** (always run from repo root: `yarn workspace …` patterns as documented). +- ✅ Do follow each rule’s **Verification** / checklist sections literally — rules are Layer 2 in [docs/ai-agents.md](../../docs/ai-agents.md). + +### Layer 2 rules — read in order (do not duplicate their content here) + +| Order | Rule | Role | +| ----- | -------------------------------------------------- | --------------------------------------------------------------------- | +| 1 | `@.cursor/rules/component-enum-union-migration.md` | Primary workflow, ❌/✅ examples, **Golden Path** file paths, PR #912 | +| 2 | `@.cursor/rules/component-architecture.md` | ADR-0003/0004 layering, shared vs platform | +| 3 | `@.cursor/rules/testing.md` | Jest, a11y, assertions | +| 4 | `@.cursor/rules/component-documentation.md` | Storybook/README when stories or docs change | + +**Golden path:** Defined inside `component-enum-union-migration.md` (e.g. **BadgeStatus** paths). + +### Verification (after edits) + +From repository root (per `CLAUDE.md`): + +```bash +yarn build && yarn test && yarn lint +``` + +### PR + +`@.cursor/rules/pr.mdc` + `.github/pull_request_template.md`; include Jira key (e.g. `DSYS-476`). + +## Cloud automation — example prompt (paste into cursor.com/automations) + +Keep the prompt **short**; implementation detail lives in `@.cursor/rules/` per [docs/ai-agents.md](../../docs/ai-agents.md). Use **Private** if the PR must be under your GitHub user. + +```text +Repository/branch: @ . + +You are in the MetaMask design-system monorepo. Follow docs/ai-agents.md: reference rules with @ — do not invent ADR patterns from memory. + +1) Jira (Consensys): JQL parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC → first issue, or exit with a one-line message if empty. Assign/transition to In Progress per workflow. + +2) Read and follow in order (full checklists inside each file): + @CLAUDE.md + @.cursor/rules/component-enum-union-migration.md + @.cursor/rules/component-architecture.md + @.cursor/rules/testing.md + @.cursor/rules/component-documentation.md (if stories/docs change) + Do NOT use @.cursor/rules/component-migration.md for this epic. + +3) Verify from repo root: yarn build && yarn test && yarn lint (per CLAUDE.md). + +4) Open PR per @.cursor/rules/pr.mdc and .github/pull_request_template.md; put Jira key in title/body. +``` + +Optional: `@`-mention `@.cursor/automations/enum-shared-type-migration.md` in the automation prompt so the agent loads JQL + PR-identity notes from this file. + +## 7. Post-merge automation: close Jira ticket + +Use a second automation for completion/closure. + +### Trigger + +- **GitHub trigger:** **Pull request merged** +- This runs only when a PR is merged. + +### Required tools + +- **MCP server** enabled in the automation. +- **GitHub MCP** connected (to inspect the triggering PR). +- **Atlassian/Jira MCP** connected (to transition the linked Jira issue). + +### Decision rules + +1. Read the triggering PR metadata (title/body/branch/labels). +2. Continue only if it is an enum-to-union/shared-type migration PR for this stream. +3. Extract Jira key (e.g. `DSYS-476`) from title/body. +4. Fetch transitions and move the issue to the workflow’s done state (`Done` / equivalent). +5. Add a Jira comment with the merged PR link and merge commit SHA. +6. If no Jira key or no matching transition is available, leave a comment and exit without changing status. + +### Cloud automation — example prompt (PR merged -> Jira Done) + +```text +Triggered by a GitHub "Pull request merged" event. + +Use MCP tools only: +- GitHub MCP to read the triggering PR +- Atlassian/Jira MCP to update Jira + +Workflow: +1) Inspect triggering PR title/body/labels/branch. Only continue if this is an enum-union/shared-type migration PR in this repo flow. +2) Extract Jira key from PR title/body (format DSYS-). If none, stop and log why. +3) In Jira, get available transitions for that issue and transition to Done (or closest done-category status in this workflow). +4) Add Jira comment: include PR URL, PR number, merge commit SHA, and date. +5) Output one concise summary line with issue key + final status. +``` diff --git a/docs/ai-agents.md b/docs/ai-agents.md index 22879a2a8..5cdbe4f2f 100644 --- a/docs/ai-agents.md +++ b/docs/ai-agents.md @@ -110,6 +110,17 @@ The three-layer model provides static guidance (rules, conventions, and process) ## How AI Agents Use This +### Cursor Cloud Automations + +[Cursor Automations](https://cursor.com/docs/cloud-agent/automations) should follow the **same principles** as interactive agents in this repo (see [Key Principles](#key-principles) below): + +- **Reference over duplication** — Automation prompts should `@`-mention `@CLAUDE.md` and specific `@.cursor/rules/*.md` files instead of pasting long paraphrased workflows. Rules stay the single source of truth. +- **Checklists over narratives** — Implementation steps live in the rules (Do/Don’t, verification); the prompt only sequences _which_ rules apply and _when_ (e.g. after Jira pickup). +- **Context efficiency** — Keep the scheduled prompt short; agents pull detail from rules and golden-path file paths inside those rules. +- **Verification** — Always run commands from repo root as in `CLAUDE.md` (e.g. `yarn build`, `yarn test`, `yarn lint`). + +Repo-specific automation specs (Jira epic, JQL, PR identity notes) live under `.cursor/automations/`. Keep specs **in git** on purpose: the Cursor Automations UI has **no native version control**—the repo is where you review, diff, and roll forward or back; the UI prompt is a **mirror** (link or copy-paste) of that spec. + ### Cursor **Automatic loading:**