302 lines
10 KiB
Markdown
302 lines
10 KiB
Markdown
---
|
|
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.
|