Files
archie/ui/AGENTS.md
T

144 lines
8.0 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 npx 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/app/controlplane/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
npm test # behavior tests
npm run typecheck # TypeScript and Vue checks
npm run build # rebuild the embedded dashboard
npm 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.
- Deploy with the approved sequence (build, scp, install, restart) once work is
finished and the gate passes. Report what changed and what was verified, briefly.