142 lines
7.8 KiB
Markdown
142 lines
7.8 KiB
Markdown
# UI agent rules
|
|
|
|
These rules supplement the repository root's AGENTS.md. Its authority, service
|
|
boundaries, security invariants, Beads workflow and commit gate still apply.
|
|
CLAUDE.md points here so both agents use one policy.
|
|
|
|
## Scope
|
|
|
|
The dashboard is Vue 3, TypeScript, Pinia and Vue Router, with Tailwind and
|
|
vendored shadcn-vue components backed by Reka UI. It talks to the control plane
|
|
through src/lib/api.ts. The server owns contracts, authorization and durable
|
|
state; the UI presents them and submits operator choices.
|
|
|
|
- Fix broken behavior with the smallest complete change. Finish existing
|
|
features before adding new ones. Do not add an abstraction or dependency for
|
|
a few lines of code.
|
|
- Read the affected callers and existing components before editing. Keep
|
|
feature state and behavior in its feature folder; shared code must have real
|
|
consumers. Do not extract production helpers solely to make them testable.
|
|
- Preserve server vocabulary and typed wire values. Do not invent local status,
|
|
action or model catalogs when the server supplies them.
|
|
- Keep requests in src/lib/api.ts and shared live updates in the existing store.
|
|
Preserve its authentication, CSRF, timeout and error handling.
|
|
- Keep unavailable, loading, empty and failed states distinct. Show failures
|
|
where they occur; an unreadable list must not look like an empty one.
|
|
- Async views must discard stale responses after their task, attempt or route
|
|
changes. A setting must save through the API and show its applied state.
|
|
- Build in safety. Edits go to a draft and reach the running workflow only when
|
|
you publish.
|
|
- Never lose work silently. If two things can write the same state (e.g., Archie
|
|
and the operator), lock one out or merge them; never let one silently overwrite
|
|
the other.
|
|
- Phone width is a real target. No global CSS rule may deform controls. Desktop
|
|
layouts must collapse cleanly: dropdowns instead of side lists, stacked panes,
|
|
and nothing overlapping the canvas.
|
|
|
|
## Product scope
|
|
|
|
- Respect the existing feature set. New features honour instructions, policies,
|
|
grants and the access model (ReBAC/ABAC with Cedar). An agent tool never reaches
|
|
further than its caller could through the dashboard.
|
|
- Agentic automation, not a coding agent. A repository is one optional input to
|
|
a workflow, not the frame for anything.
|
|
- Smallest change first. Reuse what exists, such as the change-review list, drafts
|
|
and the existing MCP bridge, before adding new mechanism.
|
|
|
|
## Components and interaction
|
|
|
|
- Build pages only from components/ui, the design system modelled on Astryx
|
|
(astryx.atmeta.com/components). Use Section for a titled card, SettingRow
|
|
for a setting, MetadataList for label/value pairs, DataTable for a table
|
|
with optional columns, Badge and StatusDot for state, Timestamp for times,
|
|
MoreMenu for overflow actions, Empty for empty states, and the type scale
|
|
(text-caption, text-label, text-title) instead of pixel sizes. Never
|
|
hand-roll a card, heading, caption, status dot or date format; if a pattern
|
|
is missing, add it to components/ui with a real consumer first.
|
|
- Reuse components/ui and surrounding composition patterns before writing new
|
|
markup. Keep vendored components local; use pnpm dlx shadcn-vue@latest for CLI work
|
|
instead of adding the generator and its dependency tree to the application.
|
|
- Use semantic theme tokens, existing variants and cn() for conditional classes.
|
|
Support both themes, compact density and reduced motion.
|
|
- Keep controls compact and contextual. Use on-demand panels and inline
|
|
hover/focus icon actions rather than permanent chrome. Do not repeat labels
|
|
in explanatory text or add controls without working behavior.
|
|
- Text states a problem or an action, nothing else. Delete lines that only
|
|
describe what the screen already shows (e.g., "Compared with the current
|
|
definition", "Same as the current definition", "Refreshed every 5 seconds",
|
|
"Showing recent matches…", "Live only").
|
|
- Do not label a control that explains itself. A switch needs no "Enabled"
|
|
beside it, and `+` needs no "New workflow" next to it. Put the name in the
|
|
accessible name or tooltip.
|
|
- Option labels do not repeat their category. Under "Checks", list "Repository",
|
|
"Diff size" and "Diff rules", not "Repository gate".
|
|
- Name things after what you are working with. The page sets context, so use
|
|
"Restore default" not "Restore shipped workflows".
|
|
- No filler or guidance text. Delete empty-state essays, hints that repeat the
|
|
label, and sentences explaining how the UI works.
|
|
- Product names are our own. The editor helper is "Build with Archie" or
|
|
"Iterate with Archie", never generic terms like "Ask bar".
|
|
- Actions live where their scope lives. Bulk or instance-wide actions (e.g.,
|
|
restoring defaults) belong on the settings page for that area, not in a
|
|
working view's header menu.
|
|
- No side panels for editing workflows. Settings, trigger and steps expand
|
|
in place on the canvas, one at a time, with the main field first and the rest
|
|
tucked away.
|
|
- Editor and live view are one surface. Runs show on the same cards you edit.
|
|
- Use Select components wherever the options are known. Avoid native selects
|
|
and free text. Use the same button and badge styles as the settings pages.
|
|
- Preserve keyboard operation, visible focus, accessible names, dialog titles
|
|
and table semantics. A hover action must also be reachable by keyboard.
|
|
- Keep filtering and pagination consistent with the server. State limitations
|
|
such as sorting only loaded rows when they affect the operator's decision.
|
|
|
|
## Tests
|
|
|
|
The default is no new test. Add one for a reproduced bug or a change to a
|
|
security boundary or workflow contract, following the root policy. A regression
|
|
must fail on the relevant assertion before the fix.
|
|
|
|
- Test observable behavior with realistic inputs. Do not test source text,
|
|
imports, wiring, constants, defaults, type shapes, CSS classes, copied labels,
|
|
fakes or call order. A fake may support a behavior test; it is not the subject.
|
|
- Use one table-driven test per behavior. Extend its cases rather than adding
|
|
tests for each branch. Retain meaningful edge cases; reducing the count alone
|
|
is not a cleanup.
|
|
- Keep tests fast and cheap to maintain. Test helpers and fixtures belong in
|
|
test/, never in production code solely for tests.
|
|
- For mirrored control-plane validators, extend the shared fixture at
|
|
internal/infrastructure/controlplanestore/testdata/dashboard-validators.json rather than
|
|
duplicating accept/reject cases in UI-only tests.
|
|
- Use browser checks for rendered behavior. Matching a Vue file with a regex
|
|
does not verify what the user sees. Mocked API checks verify UI behavior, not
|
|
live service integration; report that distinction.
|
|
|
|
## Verification and delivery
|
|
|
|
```bash
|
|
pnpm test # behavior tests
|
|
pnpm run typecheck # TypeScript and Vue checks
|
|
pnpm run build # rebuild the embedded dashboard
|
|
pnpm audit # after dependency changes
|
|
```
|
|
|
|
- Run task check from the repository root before committing; stage only the
|
|
task's own paths. Follow the root's commit and push rules.
|
|
- ui/dist is embedded and committed. Regenerate it for source changes; never
|
|
edit it by hand. Test-only edits do not need new dashboard assets.
|
|
- Reuse a running dev server for browser checks. Verify changed interactions,
|
|
not just a screenshot or successful HTTP response.
|
|
- Track work and follow-ups in Beads. Keep rules here only when they change a
|
|
decision; do not add task history or Markdown TODO lists.
|
|
|
|
## Working with you
|
|
|
|
- A clear direction is the go-ahead. Act in the same turn; do not restate the
|
|
plan, offer options, or ask "shall I proceed?".
|
|
- Say each correction once. When you correct something, fix every instance and
|
|
record the rule here so you do not repeat it.
|
|
- Delegate to pi workers when asked, and verify their output. Check for overlap
|
|
before merging, rerun their checks on the combined result, and fix what they
|
|
find.
|