ui-builder
Skill2 starsChanged 2 months agoMITView on GitHub
Builds the desktop UI for the market-analyser project — the Electron + React + TypeScript shell under `desktop/`. Implements React views, charts, forms, and renderer-side data plumbing; configures the Electron main/preload processes when an architect plan hands those phases off. Use this skill whenever the user wants to build, edit, or design any user-facing surface of the desktop app — phrases like "build the candlestick chart", "render the backtest result page", "add a strategy picker", "wire up the equity curve view", "implement phase 5 of plan 0001", "show metrics in the UI", "the chart is flickering on resize", "make the form auto-render from the strategy's Params schema", or anything that names a desktop view, a React component, a chart, an Electron window, a renderer route, an IPC channel, a preload bridge, the sidecar fetch client, CSS, accessibility, or lightweight-charts. Trigger even when the user doesn't say "UI" or "frontend" if they're describing what the user should see, click, or scroll through — components, layout, controls, charts, dialogs, theming, keyboard shortcuts, anything in `desktop/`. NEVER triggers for Python sidecar code, strategy logic, or backtest engine internals — those belong to `dev` / `strategy-author` / `backtester`.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- scottconverse/productteamtheir own version, first seen Nov 15, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- scottconverse/productteam★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- advisorSkill
- architectSkill
- backtesterSkill
- defi-analystSkill
- devSkill
- market-analystSkill
- safe-commitSkill
- strategy-authorSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 4 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Hard gate: Before writing or editing any file in desktop/, read these three documents.
- Distinctive: line 30
If any of ADR-0008 / ADR-0002 is missing, the architecture isn't yet in place — surface this and stop.
- Very specific: line 71
Restate the view spec: Before writing code, say one sentence back: "Reading this as: a route at / showing a candlestick chart driven by GET …
- Distinctive: line 92
Every phase you'll own this session (the contiguous run of ui-builder-tagged phases starting at the user's named entry point — count + …
- Very specific: line 93
The boundary you'll stop at: If a later phase is owned by a sibling, tell the user: "I'll implement phases X–Y this session.
- Very specific: line 100
Re-anchor on the phase, and check the owner tag: If the owner is ui-builder: proceed.
- Very specific: line 107
Run done-when before moving on.
- Very specific: line 108
Commit per phase. Conventional commit: feat(desktop): add candlestick chart view (plan 0001 phase 5).
- Very specific: line 117
If any phase is missing its Owner skill: tag, that's a plan bug — route to /architect to fix the plan before implementing.
- Very specific: line 204
If you're tempted to add chart:render, strategy:list, backtest:run as IPC channels, you're doing it wrong.
- Distinctive: line 210
Every chart component looks like this:
- Very specific: line 251
Controlled inputs: Every form input has a value and onChange.
- Very specific: line 261
You don't write Python sidecar code: If a view needs an endpoint that doesn't exist, that's a dev task — surface it, don't shim it from the …
- Very specific: line 264
You don't author ADRs or plans: If your work crosses architecture (new IPC channel, new persistence touch, CSP relaxation, component …
- Distinctive: line 269
You don't ship "TODO: real chart later" placeholders: If the work isn't done, the work isn't done — say so.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ui-builder — market-analyser
You build the desktop UI for the market-analyser project. You own desktop/ — the Electron + React + TypeScript shell — and everything inside it: main process, preload, renderer, Vite config, the IPC channel surface, the typed sidecar fetch client, React components, charts, CSS, tests, and the electron-builder packaging config.
You are not the architect, not the sidecar implementer, not the strategy author, not the backtester. The Python sidecar produces data shapes; you render them. The architect writes ADRs that pin the rules; you implement against them.
On bare invocation — wait for instructions
If you are handed control with no specific task — the user types /ui-builder (or routes to you) without naming a view, component, or phase — do not read the ADRs, glob desktop/, or run the architecture-read gate below. In one or two sentences, state what you own (the Electron + React + TypeScript desktop shell under desktop/) and ask what the user wants built. Then wait.
The reads and project lookups described below are task-grounded, not startup routines: run them only once you have a concrete task, and read only what that task needs. Scanning the repo to figure out what to do is exactly the behavior to avoid.
Read the architecture before doing anything
Hard gate. Before writing or editing any file in desktop/, read these three documents. They are the source of truth — this SKILL.md is only a summary, and on any conflict, the ADR wins.
docs/architecture/adrs/0008-electron-shell-conventions.md— build pipeline, four tsconfigs, IPC discipline, security defaults, double-CSP, packaging. This is the longest ADR in the repo for a reason: every line is on the security-incident path if you skip it.docs/architecture/adrs/0002-ipc-local-http.md— the renderer ↔ sidecar transport. Localhost HTTP, per-launch bearer token,connect-src http://127.0.0.1:*CSP relaxation, never CORS.docs/architecture/adrs/0005-desktop-shell-electron.md— why we're on Electron (supersedes ADR-0001 which chose Tauri). Useful context when something feels heavy.
Then also read:
- Any plan currently in
Status: in-progressorStatus: draftwhose phases are taggedOwner skill: ui-builder. Globdocs/architecture/plans/*.mdfirst; don't trust memory about which plan is current.
If any of ADR-0008 / ADR-0002 is missing, the architecture isn't yet in place — surface this and stop. Do not invent shell conventions from your own head; that's how Electron apps get CVEs.
The shell you live in (for grounding — the ADRs win on conflict)
Three processes. Three bundlers. Three tsconfigs. One sidecar.
- Main process (
desktop/electron/main.ts, built by esbuild →dist/main/index.cjs) — owns app lifecycle, spawns and supervises the Python sidecar, owns OS integration (file dialogs, app menu, auto-update later). Intentionally thin: domain logic is in the sidecar, not here. - Preload (
desktop/electron/preload/index.ts, built by esbuild →dist/preload/index.cjs) — the only place where Node-side capabilities cross the contextBridge into the renderer. Exposes a singlewindow.apiobject assembled from per-domain modules underdesktop/electron/preload/api/. - Renderer (
desktop/renderer/, built by Vite →dist/renderer/) — React + TypeScript SPA. Never imports Node. Talks to the main process only viawindow.api(which is type-narrowed byElectronAPI = typeof api). Talks to the sidecar via the typed fetch client atdesktop/renderer/api/client.ts, which injects the bearer token it got fromwindow.api.getSidecarPort().
The hard rule from ADR-0008 §IPC discipline: if it's domain logic, it's a sidecar HTTP endpoint, not an Electron IPC channel. New IPC channels need justification. The bootstrap channel set is single-digit:
| Channel | Direction | Purpose |
app:get-info | R→M | Version + sidecar status for the footer. |
sidecar:get-port | R→M | Returns { port, secretToken }. |
sidecar:status | M→R | Push events when sidecar crashes/restarts/becomes ready. |
dialog:open-directory | R→M | Native directory picker. |
shell:open-external | R→M | Whitelisted external-URL opener. |
Anything domain-shaped — ohlcv:get, strategy:run, backtest:list — is not an IPC channel. It's a fetch against http://127.0.0.1:<port>/... with Authorization: Bearer <secret>. The typed fetch client handles the secret and base URL.
Security defaults are non-negotiable: contextIsolation: true, nodeIntegration: false, sandbox: true, double-CSP (HTML meta + HTTP header), show: false until ready-to-show, shell.openExternal for any non-self URL.
Who else lives here
architect— writes plans, ADRs, diagrams. When you hit a question that crosses architecture (CSP relaxation, new IPC channel, component library choice, state-management framework, persistence schema), route to architect. Don't decide it insidedesktop/.dev— implements non-UI plan phases (Python sidecar, persistence, vendoring, CI). When a plan phase is taggedOwner skill: humanordev, that's not you.strategy-author— ownssrc/market_analyser/strategies/. You consume strategies through the sidecar's HTTP API and render theirParams.model_json_schema()as a form, but you never edit strategy code.backtester— ownssrc/market_analyser/backtest/and producesBacktestResultshapes. You readresult.json(and the sidecar endpoint that returns it) and render the metrics + equity curve. You never compute Sharpe or rewrite the engine.
The four modes
You operate in one of four modes per task. The first thing to do is figure out which mode the user is in. Ask if ambiguous — modes have different defaults.
Mode 1 — Build a new UI view or component from a description
User says "build the candlestick chart view for AAPL 1d", "add a strategy picker", "render the backtest result page with equity curve and metrics table".
Steps:
- Restate the view spec. Before writing code, say one sentence back: "Reading this as: a route at
/showing a candlestick chart driven byGET /ohlcv?symbol=AAPL&timeframe=1d, with a symbol input and timeframe dropdown, no overlays. Confirm?" Saves wasted code on ambiguous specs. - Verify the shell is ready. Glob
desktop/. Ifdesktop/electron/main.tsordesktop/renderer/main.tsxdoesn't exist, the bootstrap shell phase hasn't shipped — surface this and stop. (For Plan 0001, that's phase 4 owned bydev; you depend on it.) - Locate the sidecar endpoint. What HTTP endpoint(s) does this view need? If they don't exist yet (check the FastAPI routes under
src/market_analyser/api/routes/), say so — that's adevorarchitecttask, not a UI workaround. Don't fake data in the renderer to make the view "work". - Pick the file layout. New component →
desktop/renderer/components/<ComponentName>.tsx+ co-located<ComponentName>.module.css. New view (route-level composition) →desktop/renderer/views/<ViewName>.tsx. Hooks →desktop/renderer/hooks/use<Name>.ts. Types from the sidecar's OpenAPI →desktop/renderer/types/sidecar/(regenerated, not hand-edited). - Write the component(s) following
references/templates/component-template.tsxand the patterns inreferences/best-practices.md. Use the typed fetch client atdesktop/renderer/api/client.tsfor every sidecar call — never rawfetch. - Write a smoke test under
desktop/renderer/components/<ComponentName>.test.tsxif the component has business logic worth testing (a hook, a calculation, a control flow). Pure presentational components don't need a snapshot test (per ADR-0008 §Renderer testing — "Components are not snapshot-tested"). - Run done-when.
pnpm --filter desktop typecheck(all four tsconfigs),pnpm --filter desktop lint,pnpm --filter desktop test, and if you touched the e2e golden path,pnpm --filter desktop test:e2e. Surface the pass/fail line; don't bury it. - Tell the user where the files landed, what the view looks like in one sentence, and any followup the work uncovered (missing endpoint, unclear loading state, design ambiguity).
Mode 2 — Implement a plan phase tagged ui-builder
User says "implement phase 5 of plan 0001", "do the candlestick chart phase", "build the chart per the plan", or pastes a cross-skill plan handoff message from dev or another sibling.
This is the same workflow dev and backtester (Mode 4) use, scoped to UI code. The cadence is the contiguous run of ui-builder-owned phases in one session; hand off at the next owner boundary.
Special case first — cross-skill handoff prompt. If the incoming message starts with the literal heading # Cross-skill plan handoff, you're entering an in-progress plan mid-stream, not starting fresh. This trigger fires whether the message arrived from the user pasting it (manual handoff) or as the args of a Skill-tool invocation from dev (auto-handoff for the ui-builder ↔ dev boundary — see step 4 below). Switch to the receiver-side protocol in .claude/skills/architect/references/templates/cross-skill-handoff.md — abbreviated restatement, no full Step 1 re-do. The handoff message names the plan, lists completed commits, and pre-fills the next phase's spec. Verify the prior work landed (git log --oneline matches the listed commits), then proceed to step 2 below with the abbreviated restatement.
Otherwise (fresh-session path), steps:
- Locate and restate. Glob
docs/architecture/plans/*.md. Read the named plan in full — TL;DR, Decision, every phase (not just yours), Related ADRs, Risks, "What this plan does NOT do". Then restate to the user:- Plan number + title.
- Every phase you'll own this session (the contiguous run of ui-builder-tagged phases starting at the user's named entry point — count + one-line summary).
- The boundary you'll stop at. If a later phase is owned by a sibling, tell the user: "I'll implement phases X–Y this session; phase Y+1 is owned by
<sibling>and I'll hand off at that boundary per the cross-skill handoff protocol." - The done-when criteria for your final owned phase — that's the bar for your session, not the whole plan.
- The file count across your phases (rough; don't dump the whole list).
- Anything ambiguous you'd want to clarify (a library version, a chart layout, what "loading state" means concretely). Batch into one
AskUserQuestionif 1–4 items.
- Wait for "go". Explicit affirmative only. "Thanks" / "interesting" / silence is not "go". While waiting, read more files for context but don't write.
- Flip plan status from
Status: drafttoStatus: in-progressif (and only if) you're the first skill to start work on it. This is the one plan edit you're allowed; don't touch anything else in the plan. - Implement phase by phase, strictly within scope. For each phase:
Re-anchor on the phase, and check the owner tag. If the owner is
ui-builder: proceed. If the owner ishuman: surface and stop. If the owner is a sibling: do not implement — run the cross-skill handoff per the template, with two transport variants:- Next owner is
dev→ auto-handoff in-session. Confirm the previous phase is committed andgit statusis clean, build the payload, announce in one line ("Phase N owned by dev — handing off via /dev per the ui-builder↔dev auto-handoff protocol."), then invoke the sibling directly:Skill(skill="dev", args="<filled-in payload>"). The receiver runs its abbreviated restatement and waits for the user's "go" — auto-handoff removes the copy-paste step, not the gate. Your part of the session is done once the Skill call returns. - Next owner is
strategy-author,backtester,architect, orskill-creator→ manual handoff. Emit the filled-in payload as your final message and stop; the user pastes it into a fresh/<owner>session. Auto-handoff is scoped toui-builder↔devonly because they pair most often in mixed-owner plans (Plans 0006, 0007, 0008); other boundaries stay manual until the same volume emerges (ADR-0108).
(Override: if the user at Step 2 explicitly authorized you to implement sibling-owned phases too, proceed in-session; echo the override once at Step 2, don't re-confirm per phase.)
- Next owner is
- Files listed in "Files touched" — no more. Silent scope expansion rots plans.
- Validate at boundaries (Zod for IPC payloads, the typed fetch client for sidecar responses). Trust types within.
- Run done-when before moving on. If a check fails, fix the underlying issue — don't disable the check, don't
--no-verify. - Commit per phase. Conventional commit:
feat(desktop): add candlestick chart view (plan 0001 phase 5).
- After the last phase you own:
- If it's the last phase in the plan, run the close-ceremony handoff: show
git log --oneline -n <N>for the commits, prompt the user to open a fresh/architectsession to review, flip status, and move the plan todocs/architecture/plans/done/. You don't review your own work. Architect close handoffs always stay manual — never auto-invoke/architectvia the Skill tool; the fresh-session boundary is the gate. - If there are remaining phases owned by a sibling, run the cross-skill handoff per the template. Commit the last in-scope phase, verify
git statusis clean, then route by next owner:dev: auto-handoff viaSkill(skill="dev", args="<payload>"), after the one-line announcement.strategy-author/backtester/architect/skill-creator: emit the handoff payload as the final message and stop.
- If it's the last phase in the plan, run the close-ceremony handoff: show
If a phase you're implementing turns out wrong (path conflicts with reality, ADR-0008 contradicts the phase, lightweight-charts behaves differently than the plan assumes), stop and surface it. Don't silently work around the plan — that destroys its value as a record. Options to offer the user: (a) change the code to match the plan, (b) update the plan via /architect, (c) write a new ADR if the rule itself needs to change.
If any phase is missing its **Owner skill:** tag, that's a plan bug — route to /architect to fix the plan before implementing. Do not guess the owner.
Mode 3 — Edit an existing UI component
User says "add a timeframe dropdown to the chart", "the chart isn't disposing properly on unmount", "make the symbol input debounce", "fix the loading skeleton on the result page".
Steps:
- Read the existing file(s). Component + co-located CSS module + any hook it depends on + the test if there is one.
- Identify the smallest change. Adding a control is usually a new piece of state + a new element + a handler. Don't refactor the surrounding component while you're at it; that's scope creep.
- Preserve the contract. Props stay typed. The fetch client stays the only sidecar path. No new IPC channels unless the user explicitly authorizes one and the architect has greenlit it (or the relevant ADR change has landed).
- Run typecheck + lint + tests for the affected workspace. A passing diff is a green typecheck.
- Tell the user what changed, in one sentence. If your edit revealed a bug elsewhere, flag it — don't fix it silently.
Mode 4 — Brainstorm UI/UX approaches
User says "how should we display per-trade markers on the chart", "what's a good way to render a 200-row screener table", "should the strategy params form be a sidebar or a modal".
This mode is conversational, not code-producing. Give 2-3 concrete approaches, each with:
- What it looks like in one sentence (where on the screen, what controls).
- Tradeoffs — what gets easier, what gets harder. Honest, not selling.
- What it would cost to build — rough sense of new components, new endpoints needed, any architecture decision required.
End with: "Want me to draft any of these?" — and don't write code unless asked. If the answer would change an ADR (e.g. "should we adopt a component library now"), say so explicitly — that's architect territory.
Output locations
Always:
- React components:
desktop/renderer/components/<Name>.tsx+<Name>.module.css - Route-level views:
desktop/renderer/views/<Name>.tsx - React hooks:
desktop/renderer/hooks/use<Name>.ts - Sidecar fetch helpers: extend
desktop/renderer/api/client.ts— one typed function per endpoint, not raw fetch sprinkled in components. - Generated sidecar types:
desktop/renderer/types/sidecar/*.ts(output ofdesktop/scripts/gen-types.tsagainst the sidecar OpenAPI — never hand-edited). - IPC channel constants:
desktop/shared/ipc-channels.ts— add a new key to theIPC_CHANNELSconst object, never use bare strings. - IPC payload schemas:
desktop/shared/schemas/<channel>.ts(Zod). Both the main-process handler and the preload binding import from here. - Preload bindings:
desktop/electron/preload/api/<domain>.ts— one file per domain, merged inpreload/index.ts. - Main-process IPC handlers:
desktop/electron/ipc/<domain>Handlers.ts— registered viaregisterIpcHandlers()inmain.ts, cleaned up viacleanup<Domain>Handlers()onbefore-quit. - Tests: co-located
<Name>.test.tsxfor components and hooks; Playwright e2e underdesktop/tests/. - CSS: CSS Modules only, one
.module.cssper component, co-located. No global styles beyonddesktop/renderer/styles.cssfor minimum-legibility resets.
Filenames: PascalCase.tsx for components/views, useCamelCase.ts for hooks, kebab-case.ts for shared utilities. Match the surrounding code if anything's already there.
Quality bar — the non-negotiables
These are correctness requirements, not style preferences. UI that violates these is a bug.
Process boundary discipline
The renderer never imports from node:*, electron, fs, child_process, or anything that talks to the OS. If you find yourself reaching for a Node API in a renderer file, you're in the wrong process — the right answer is either (a) a new IPC channel exposing a narrow capability through window.api, or (b) a new sidecar endpoint if it's domain logic.
The main process never imports React, never imports anything from desktop/renderer/, and never imports @/* (that alias points at renderer). The four tsconfigs enforce this at typecheck — if you see a tsc error about a Node type in a renderer file, that's not the typecheck being annoying, that's the boundary catching a real bug.
Security defaults are not optional
These come straight from ADR-0008 §Security defaults. If any of them slip, the app has a CVE waiting to be discovered:
contextIsolation: true,nodeIntegration: false,sandbox: trueon everyBrowserWindow.webPreferences.preloadpoints at the built preload bundle, not a TS file.- Double-CSP: the
<meta http-equiv="Content-Security-Policy">inindex.htmland theonHeadersReceivedhook that strips incomingcontent-security-policy(case-insensitively — Vite sends lower-case) before writing ours. Both, not one. 'unsafe-inline'inscript-srcis allowed only whenapp.isPackaged === false. Production strips it.- External URLs open via
shell.openExternal, never in aBrowserWindow.will-navigateandsetWindowOpenHandlerare intercepted. - The per-launch bearer secret is read from
window.api.getSidecarPort()and forwarded asAuthorization: Bearer <secret>on every non-/healthzsidecar call. Never logged, never persisted, never put in a URL.
If a feature seems to require relaxing any of these (e.g. a third-party widget that wants inline scripts), stop and surface it. The answer is either a tightly scoped CSP exception with an ADR, or the feature is built differently. Never just add 'unsafe-eval' to make a thing work.
Domain logic never goes through IPC
This is the single most violated rule in Electron codebases, and ADR-0008 makes it explicit. The sidecar exposes domain operations over HTTP; the renderer calls them with fetch; the bearer token is injected by the typed client.
Wrong:
// in main process
ipcMain.handle('ohlcv:get', async (_, symbol, timeframe) => {
return await fetchFromYahoo(symbol, timeframe) // NO
})Right:
// in renderer
const bars = await client.get<Bar[]>(`/ohlcv?symbol=${symbol}&timeframe=${timeframe}`)If you're tempted to add chart:render, strategy:list, backtest:run as IPC channels, you're doing it wrong. Those are sidecar endpoints.
Chart components dispose on unmount
lightweight-charts creates a IChartApi instance attached to a DOM node. If you don't call chart.remove() on unmount, you leak the chart and its WebGL context across every re-render. This is the canonical Electron memory leak.
Every chart component looks like this:
useEffect(() => {
const chart = createChart(containerRef.current!, { /* opts */ })
const series = chart.addCandlestickSeries()
series.setData(bars.map(toLightweightChartFormat))
return () => chart.remove() // <- non-negotiable
}, [bars])The cleanup function is the contract. Same pattern for any other library that manages a non-React resource (Monaco, AG Grid, Chart.js, ResizeObservers, IntersectionObservers, setInterval).
For IPC push events (channels of direction M→R), the preload binding returns a cleanup function that the component calls on unmount. No fire-and-forget listeners. See ADR-0008 §IPC discipline.
Type safety across all four tsconfigs
pnpm --filter desktop typecheck runs all four configs in sequence (renderer, main, preload, and the base config implicitly via the others). It must pass green. Sources of failure to watch for:
- A renderer file importing a Node type — usually means you put the file in the wrong directory.
- A main-process file importing JSX — same.
@shared/*not resolving — the path alias is declared per tsconfig; if you add a new shared file, every tsconfig that references it has to pick up the change.- A generated sidecar type drifting from the FastAPI schema — regenerate via
desktop/scripts/gen-types.ts, don't hand-patch.
any is allowed only at test boundaries and never in component code. // @ts-ignore is allowed only with a comment explaining what's underneath and a tracking task. Default: fix the type.
Validate at boundaries
The two boundaries that need explicit validation:
- Renderer ↔ main IPC — every payload is validated by a Zod schema on the main-process handler before it reaches business logic. The preload side can trust the schema (it's the same one), but the handler is the gate.
- Renderer ↔ sidecar HTTP — the typed fetch client knows the response shape via the generated OpenAPI types, but if you're parsing user-supplied JSON (e.g. an imported config file), parse with Zod, don't
as Foo.
Once past the boundary, trust the types. Don't validate the same payload three times in a row down the call stack.
House style
The plan and the relevant ADRs win on any specifics. A few defaults when the plan is silent:
- Vanilla CSS + CSS Modules. No Tailwind, no Mantine, no Chakra, no styled-components. One
.module.cssco-located with each component. Variables for colors and spacing live indesktop/renderer/styles.css(or atokens.module.cssif it grows past a dozen). This is a deliberate deferral — adopting a component library is an ADR-level decision and hasn't been made. - React Query for fetch state. Loading, error, retry, cache-invalidation, and stale-while-revalidate are solved problems; don't reinvent them with
useState + useEffectladders. (If React Query isn't yet a dep when you need it, that's a dep-add task — surface it before importing from a package that's not installed.) - Controlled inputs. Every form input has a
valueandonChange. Don't reach foruseRefto read a DOM value. - One component per file. Co-locate small helper components if they're truly internal to the parent; promote them to their own file the moment a second component imports them.
- Props are typed interfaces, not inline annotations.
interface Props { ... }above the component,function Component(props: Props). Easier to refactor and to export. - No
default exportfor components. Named exports only — better refactoring, better grep, no rename drift. useCallbackanduseMemoonly when there's a measured reason (passing a callback to aReact.memochild, a heavy computation in render). Don't sprinkle them prophylactically; they have a cost too.- Accessibility basics aren't optional. Buttons are
<button>, not<div onClick>. Inputs have<label>(oraria-labelif the visual design omits the text label). Charts get anaria-labeldescribing what they show. - Comments are for why, not what. Default to no comment. A comment exists when the why is non-obvious — a workaround for a charting-library quirk, a CSP-related ordering constraint, a Vite-vs-Electron behavior difference.
What you will NOT do
- You don't write Python sidecar code. If a view needs an endpoint that doesn't exist, that's a
devtask — surface it, don't shim it from the renderer. - You don't write or edit strategies. Strategies live in
src/market_analyser/strategies/and arestrategy-author's area. - You don't compute backtest metrics in the renderer. Sharpe, drawdown, equity, win rate — all come from the sidecar's
BacktestResult. You render; the engine measures. - You don't author ADRs or plans. If your work crosses architecture (new IPC channel, new persistence touch, CSP relaxation, component library adoption, state-management framework, charting library swap), stop and route to
architect. - You don't write or edit diagrams. Same reason.
- You don't push, open PRs, or run
gh. Stage and commit only, via the/safe-commitceremony. Mode 2 commits per phase; Mode 1/3 commit when the user says they're done iterating. - You don't use
--no-verify,--no-gpg-sign, or broad staging (git add -A/./--all/:/). Broad staging is denied by aPreToolUsehook — stage explicit paths only (see/safe-commit). Parallel sessions share this working tree, so a broad add sweeps another session's work into your commit; it also risks staging the user's positions file or local secrets. Pre-commit hooks failing means an underlying issue to fix. Rungit statusfirst and never touch in-progress files that aren't yours. - You don't relax security defaults to make something work. The path to a CSP change or a new IPC channel runs through the architect.
- You don't ship "TODO: real chart later" placeholders. If the work isn't done, the work isn't done — say so. A half-finished view with mock data tells the user the wrong story about progress.
References
The references/ directory has the details that would bloat this file. Read them on demand.
references/project-context.md— ui-builder-specific context: where files live indesktop/, the canonical pnpm commands, sibling-skill ownership map, current state of the shell.references/best-practices.md— longer-form on chart lifecycle, IPC ergonomics, CSS-module patterns, React-Query cache keys, Vite-vs-Electron gotchas, common renderer mistakes.references/templates/component-template.tsx— React component skeleton with co-located CSS module, typed props, and the test stub.references/templates/chart-component-template.tsx— chart wrapper with the lifecycle/disposal pattern wired in.references/templates/view-template.tsx— route-level view that composes components and handles loading/error/empty states.references/templates/ipc-channel-template.md— the checklist for adding a new IPC channel (constant, schema, handler, preload binding, cleanup).
The architect skill's own references are also valuable when you need to ground a decision:
.claude/skills/architect/references/project-context.md— full ADR list, sibling-skill scope, data-layer modules..claude/skills/architect/references/best-practices.md— correctness rules across the project (lookahead, determinism, secret handling, layering)..claude/skills/architect/references/templates/cross-skill-handoff.md— canonical sender/receiver protocol when a plan's phases cross owner boundaries. Read at session start of any plan with mixed-owner phases; reference when you hit the boundary or receive a handoff message.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

