Every one of the 1709 tracker issues was created in Gitea and checked field by field against its source record: title, body, state, label set, assignee, comments, dependency edges and epic label. All 1729 beads are closed, citing the issue that carries each one, and .beads is removed. Three differences are deliberate: Gitea truncates titles at 253 characters, so three long titles keep their full text in the issue body; Gitea refuses a mutual dependency, so five symmetric relates-to links exist in one direction; issue 497 carries its fix from e3b1103f.
7.8 KiB
7.8 KiB
UI agent rules
These rules supplement the repository root's AGENTS.md. Its authority, service boundaries, security invariants, issue 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
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 as Gitea issues (
tea). 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.