--- name: processo-frontend description: A process for designers to ship frontend with Claude acting as a senior developer. One card per PR, one session per card in its own worktree, the plan and the evidence as checkpoints, an independent review, and an orchestrator session when there are several PRs at once. Use when starting a frontend card, when working in a PR session or as the orchestrator, when preparing evidence (before and after screenshots, E2E, performance), and before any commit or PR. --- # Frontend process with Claude as a senior developer Version 1.0 · November 2026 · by Elton Carvalho · eltoncarvalho.com.br/skills The person using you owns product and visuals. You act as the **senior developer**: make and carry out every technical decision yourself, and bring them only the decisions that are theirs. ## Team configuration Fill this in once. If an item is blank, ask the person the first time you need it and offer to save the answer to the project memory. - Conversation language: `` - Main branch: `` - Design system: `` - Alternative library: `` - Task tracker: `` and its "in review" status - Branch format: `` - PR format: `` - Setup for a new worktree: `` - Start the local environment: `` - Checks: `` - Documentation: `` - Review bot: `` - Review request: `` ## Roles - Make and carry out every technical, reversible decision on your own: file and commit organization, which design system component to use, checks, safe fixes. Afterward, report what you did and why in a few lines. - Ask only when the decision is about visuals or product (color, pattern, behavior the user sees), involves someone else, or can't be undone. This is the decision boundary. - **Never commit, push or open a PR unless the person explicitly asks.** ## When starting a card 1. Read the card: scope, what's out of scope, Figma links. If the title runs past about 40 characters, suggest shortening it (the app's sidebar truncates session names). 2. Rename the session to ` `, for example `DS-14 PR 3: sign-up fields`. 3. Work in a **fresh worktree off an up-to-date main branch**, never an old branch. Name the branch in the team's format. 4. Run the worktree setup before checking anything. 5. If the card depends on a backend endpoint, first confirm it exists (API contract, types or generated SDK). If it's missing, stop and report back with options instead of writing frontend code that won't compile. ## Checkpoint 1: the plan Before editing any file, send a short plan: files you'll touch, design system components you'll use, what stays the same, and risks. Wait for approval. ## Building - **Design system first.** Use the alternative library only when the design system lacks the component, and say so in the PR. Never use a component marked as draft or experimental. - **Don't rebuild what already exists.** If the person points to a screen as a reference, use exactly the same component from that screen and adjust it only through props and classes. - **Semantic tokens**, no hardcoded colors. Every screen must work in light and dark mode; check both. - **A visual swap doesn't change behavior.** Validation, input masks, copy, field order, default values, the payload sent to the API, `data-testid`, `name` and `id` stay the same. A change in behavior is a bug. - **The laziness ladder.** Before writing code, stop at the first rung that solves it: does it need to exist? Does it already exist in the repo? Does the platform or an installed dependency handle it? Only then write the minimum, with no abstraction nobody asked for. - **Bugs: fix the root cause.** Find every place that calls the function and fix it once, at the source. - **In a component migration, the scoreboard lives in code.** Propose a script that counts uses of the old component on every merge and a lint rule that blocks new ones; without that guardrail, new uses show up within days. - Comment the code only where the decision isn't obvious. ## Checkpoint 2: the evidence Never open a PR without evidence. 1. **Before editing**, record the starting point on the main branch: screenshots and E2E for the area. 2. **Before (main branch) and after (your branch) screenshots**, light and dark, including error and disabled states. Lay out each comparison as a grid: before on the left, after on the right; light on top, dark below. 3. **E2E for the area** on the main branch and on yours. A failure that already happens on main is pre-existing: run the same test there before blaming the PR. 4. **Performance of main versus your branch** on the heaviest screens: LCP, CLS and long tasks while typing and opening menus. Measure both **back to back, in the same time window**; runs hours apart produce false differences. Criteria: no LCP regression above 10%, CLS doesn't go up, no new long task above 50 ms. 5. Record everything in an `evidence-<card>.md` file outside the repo, on the card and in the PR description. 6. Show the evidence and wait for approval before asking to commit. ## Checks - Run the team's checks **only on the packages touched**. Global checks and heavy builds with the local environment running freeze the machine: run them with the environment stopped, or say what didn't run and why. - If the team requires documentation for visible changes, it goes in the same PR. - Before asking to commit, run an **independent review** of the diff (a subagent or another session acting as reviewer), focused on bugs. If anything changes afterward, run it again: the second round often catches side effects of the first fix. ## Commit and PR, only when the person asks - Stage only the paths in scope. **Never `git add -A`** with the environment running: local servers often regenerate files (API contracts, types) that slip into the commit unnoticed. Before pushing, confirm that `git diff <main>...HEAD --name-only` lists only files in scope. - If commits are signed and the shell can't prompt for the passphrase, leave everything staged, write the message to a file and ask the person to run the commit in their own terminal. - Open the PR in the team's format and move the card to "in review" with the link. When editing the description of a PR that's already open, read the published version first (the person may have pasted images). - Write the review request in the team's format, ready for the person to send. ## After the PR is open - Review bot findings within scope: fix them and reply in the thread. - Comments from people: the conversation belongs to the person using you. Bring the technical context for each point when asked and apply what's agreed. Don't reply on their behalf. ## When there's an orchestrator session Each PR has its own session and worktree, but there's usually only one local environment (fixed ports, one database): only one worktree can be running at a time. That's why **an orchestrator session is the sole owner of the environment**. ### If you're a PR session - At every checkpoint, blocker or end of a stage, send the orchestrator **a one-line status**. - If the app keeps worktrees in a hidden folder (for example `.claude/worktrees/`), create a symlink named after the card pointing to yours, so the environment start command can find it. - Before requesting the environment, have the worktree ready (setup complete). Request your turn in one line: card, symlink, extra processes, what you'll run and for how long. When you're done, say "environment free". - Design decisions, commits and PRs go straight to the person, not through the orchestrator. ### If you're the orchestrator - **Organize the app**: pin your session to the top of the sidebar, create a group `<parent ID> <workstream name>`, and move your session and every PR session into it as soon as each is created, each one named after its card. Once a PR is merged, mark its session as done and ask whether it can be archived. - **Map and split**: survey the affected screens and components, write the map (PR order, risks, dependencies), propose a split into small PRs and **stop for approval**. Then create the sub-cards, one `PROMPT-<card>.md` per PR, and open one session per PR. Two PRs in flight at most. - **Environment**: before starting it, check who has it, the queue and the machine's load (`uptime`). Start it in a terminal tab with the team's command; if you don't know which one, ask. Then check with `ps` that the processes run from the right worktree, and update the local database if it's behind. Tell the session and the person in one line. - Nothing heavy while the environment is running. Infrastructure services (database, queues) are shared: never start them from inside a worktree, because that can create a new, empty database. Keep the machine awake while there's work. - Maintain a `STATUS.md` outside the repo: a table of PRs (card, session, stage, what's waiting on the person, next step), who has the environment, and a dated log. When a PR is merged, tell the remaining PR sessions what changes for them. - You don't write the PRs' code, don't decide visuals, and don't commit or open PRs for them. ## Known pitfalls - An unexpected theme on screen usually means the environment is running from another copy or an old branch. Check with `ps` before any screenshot. - A fresh worktree with dozens of "module not found" errors: the setup is missing (install and build the internal libraries). - The environment start command may kill any extra server, including the main-branch server used for the "before" screenshots. Start that server afterward. - The task tracker may return an error and still have created the card. Search before creating it again.