--- kind: rule project: HiveGrid Screen Project area: Agent Workflow status: active validated: true --- # Screen Agent Workflow Use this file for all HiveGrid screen, flow, Canvas, tracker and Subframe planning work. Outcome: The agent guides David through UX screen/flow planning, validates every decision with David, documents only validated outcomes, and keeps Obsidian, Tracker, Canvas and Subframe references synchronized. This file is the operative checklist. `Screen Agent Workflow - Brainstorming.md` is only the archive and must not override this file. --- ## MUST - MUST read the relevant Planning, tickets, existing flow package, screen files, tracker and Canvas before proposing changes. - MUST check for similar existing flows, screens, reusable patterns and naming conflicts before creating a new flow or screen. - MUST use internal Planning as the default source of truth. - MUST use external research only as decision support, and validate relevant research-derived ideas with David before they enter planning. - MUST use `04 Standards/Subframe UI Standards/` as reference for already validated Subframe, component and layout standards when relevant. - MUST give an assumption and recommendation before asking David a decision question. - MUST have David validate every product, UX, screen, state, backlog, scope and research-derived decision. - MUST keep one small flow or screen package in focus at a time. - MUST maintain Error-State candidates for every flow and validate them with David. - MUST document UX behavior: visible data, actions, states, permissions, dependencies and flow logic. - MUST avoid backend implementation decisions; Development decides technical implementation. - MUST sync structural changes immediately across package MD, screen files, tracker, Canvas and Subframe links. - MUST keep Canvas readable: grouped, labeled, non-confusing and JSON-valid. - MUST ask before committing, unless David explicitly said to commit/push or clearly asked to "mach und push". - MUST create or update a `Tickets/` handoff file when a ticket is finished or ready for handoff. --- ## NEVER - NEVER finalize unvalidated decisions. - NEVER silently create, delete, rename or split screens. - NEVER build or edit Subframe without explicit OK for the concrete screen or flow. - NEVER edit `04 Standards/Subframe UI Standards/` during normal screen work unless David explicitly asks for standards work or validates a systemwide rule that belongs there. - NEVER overwrite or revert David's manual changes in Obsidian or Subframe. - NEVER let external examples override internal Planning without making the conflict visible and asking David. - NEVER create Canvas nodes for normal Toasts, Banners, Inline States, field validation or pure documentation states. - NEVER invent unavailable components; mark them as open component questions. - NEVER commit unrelated local changes such as `.obsidian/workspace.json` or unrelated Canvas edits. --- ## DEFAULTS - DEFAULT view is Admin unless the flow clearly requires a non-admin variant. - DEFAULT for roles/permissions: think about them briefly, document only if visibly relevant or risky. - DEFAULT for Error States: document them, do not build individual screens for every field error. - DEFAULT for Backlog: collect candidates, but only mark final Backlog after David validates. - DEFAULT for working names: keep sensible names, but validate if the name affects files, Canvas, Tracker, Subframe or flow structure. - DEFAULT for final MDs: compact, decision-oriented and readable. - DEFAULT for Brainstorming/Draft files: more detailed is allowed. --- ## Workflow ### 1. Brief Before proposing screens: - Identify ticket/module, user goal, flow start and flow end. - Read relevant Planning, tickets, existing package MDs, screen files, tracker and Canvas. - Check whether this is a new flow, existing flow change, screen, modal, state or documentation-only item. - Check similar flows/screens and possible reuse. - Mark assumptions and unknowns. ### 2. Map Build the working map before final decisions: - Happy path. - Branches and blockers. - Screen candidates. - Modal candidates. - Toast/Banner/Inline/documentation states. - Error-State candidates. - Dependency candidates. - Scope candidates. - Backlog candidates. - Component/pattern questions. Do not finalize this map without David. ### 3. Align Present decisions in small validated chunks. Use this pattern when there are alternatives: | Option | Beschreibung | Vorteil | Nachteil | Empfehlung | |---|---|---|---|---| | A | - | - | - | - | | B | - | - | - | - | Then get David's decision: | Entscheidung | Status | Notiz | |---|---|---| | - | genommen / spaeter / raus / unklar / Backlog | - | For every screen/state candidate, clarify: - Is it a Screen, Modal, Version, Inline State, Toast, Banner or documentation-only? - Does it need Canvas? - Does it need a screen file? - Does it need Subframe? - Does David validate it? ### 4. Document Only document validated outcomes as final planning. Document: - Goal and user task. - Visible data. - Actions and button outcomes. - UX flow logic. - States and validated Error States. - Dependencies. - Component/pattern notes. - Scope decisions. - Validated Backlog. - Open questions. Do not write backend architecture or implementation details. ### 5. Sync For every structural change, update all relevant artifacts in the same work block: - Package MD. - Screen file. - `02 Wireframes/Screen Paket Tracker.md`. - Canvas. - Subframe link/flow reference, if applicable. Then check: - Search for old names/paths/links with `rg`. - Validate changed Canvas JSON. - Check Canvas readability. - Run `git status --short`. - Stage only intended files. ### 5b. Ticket Handoff When a ticket is finished, ready for external ticket-system handoff, or David asks for a ticket summary: - Create or update one Markdown file in `Tickets/Fertige Tickets/`. - Use the same structure as `Tickets/Fertige Tickets/D-P2 Auth Wireframes.md`. - Name it clearly after the ticket and area, for example `Tickets/Fertige Tickets/D-P2 Auth Wireframes.md`. - Include ticket id, area, status, repo link, central tracker link and working area. - Summarize what was done, what David validated and what remains Backlog/Open. - Link every relevant flow package MD, Canvas and Subframe flow. - Link relevant screen files. - Keep detail truth in the package MDs and tracker; the ticket file is the handoff index. - Before finalizing, verify local links point to existing files. - If the ticket changes after the handoff file exists, update the same ticket file instead of creating a duplicate. ### 6. After-Change Impact Check When David says he changed something in Obsidian: - Read the affected files. - Check wording, structure and affected screen files. - Check whether related screens need edits. - Ask before editing further screens. When David says he changed something in Subframe: - Read the named screen(s) via MCP when MCP is available. - Summarize only the fachlich relevant change. - Do not create a changelog. - Update Obsidian only for relevant planning changes. Always ask: - Does this create or remove an Error State? - Does this create or remove a dependency? - Does this change a button outcome? - Does this create a new Modal, Toast, Banner, Screen or Flow? - Does this affect Canvas, Tracker or Subframe links? If a new screen or flow might be needed, do not create it directly. Start a Mini-Brainstorm first. --- ## Error States The agent is responsible for finding Error-State candidates. David validates them. Default: Error States are documented, not built as separate screens. Own Error Screens only when the state is: - blockierend - fachlich extrem wichtig - security-critical - legally/copy critical - a new mental step for the user Use this table: | Ereignis | Ort/Screen | UI-Form/Komponente | Bauen? | Empfehlung | David-Entscheidung | |---|---|---|---|---|---| | - | - | Inline / Banner / Toast / Modal / Screen / Dokumentation / offene Komponentenfrage | ja / nein | - | offen / validiert / raus / spaeter | Rules: - One field can have multiple Error States. - Do not create several screens for normal input validation. - Assign existing components/patterns when known. - If the component is unknown, mark `offene Komponentenfrage`. --- ## Dependency Check For every flow, quickly check: - Does this flow start another flow? - Is this flow started by another flow? - Does it touch central Auth, Account, Admin or Settings flows? - Does it change roles, permissions or visibility? - Does it create or change Error States in another flow? - Can an existing screen, modal or state be reused? - Should Canvas or Tracker link to another flow? - Are there name, route, screen or Subframe conflicts? If a dependency could create a new screen/flow, start a Mini-Brainstorm and ask David. --- ## Canvas Rules Canvas shows: - real Screens - real Modals - real Versions/Variants when they are own work moments Canvas does not show as own nodes: - Toasts - Banners - normal Inline States - field validation - documentation-only states Still validate and document relevant non-Canvas states with David. --- ## Subframe Rules Subframe is used only after David explicitly approves a concrete screen or flow. Before Subframe work: - Validated screen list exists. - Screen purpose is clear. - Existing Subframe screens are checked if needed. - Existing David changes are respected. After Subframe work: - Update screen file frontmatter/link. - Update package MD. - Update tracker. - Update Canvas if structure changed. - Verify Dialog/Modal screens use real Dialog/Page Layout patterns, not simulated cards. - For every Modal/Dialog screen, explicitly instruct Subframe to use `DialogLayout` -> `Dialog` -> `Dialog.Content`; never accept a fake modal built from `Card`, an absolute overlay, blur background or a full page wrapper. - Before handoff, read the page with `get_page_info` and confirm the JSX imports `Dialog` and contains `Dialog.Content`. --- ## Done Criteria The agent is done only when: - David validated the relevant decisions. - Validated decisions are documented. - Error-State candidates were considered and validated or left open. - Dependencies were checked. - Structural changes are synced across files. - Canvas is valid and readable if changed. - Subframe links are updated if Subframe was used. - Ticket handoff in `Tickets/` is created/updated when the ticket is finished or handed off. - Git status was checked. - Commit/push handling follows David's instruction.