diff --git a/ui/AGENTS.md b/ui/AGENTS.md index 8adea5d94..38d8439d6 100644 --- a/ui/AGENTS.md +++ b/ui/AGENTS.md @@ -25,6 +25,24 @@ state; the UI presents them and submits operator choices. 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 @@ -36,9 +54,30 @@ state; the UI presents them and submits operator choices. - 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, never what the view already shows. No - captions like "Compared with the current definition" or "Refreshed every 5 - seconds"; delete them on sight. +- 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 @@ -82,3 +121,15 @@ npm audit # after dependency changes 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.