Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,169 @@
---
name: plan-ticket
description: Create a complete implementation plan for a HiveGrid ticket from AGENTS.md,
its ticket doc, linked planning sources, live Plane context, and current git
state. Use when a user provides a HiveGrid ticket ID or asks to analyze,
scope, sequence, or plan a ticket without implementing it yet.
---
# Plan Ticket
Plan only. Do not edit code, ticket docs, Plane, or external systems. Stop after
the plan and ask for approval before implementation.
## 1. Resolve the ticket
Require a ticket ID such as `AK-P3`. Then:
1. Read `AGENTS.md` completely enough to apply the current rules relevant to the
ticket.
2. Read `.planning/ticket-docs/README.md` and
`.planning/ticket-docs/<TICKET-ID>.md` completely. Stop if the ticket doc is
missing.
3. Follow only the granular sources linked by the ticket doc. Give
`.planning/ENTITY-MODEL.md` priority where `AGENTS.md` requires it.
4. Read the current branch, recent commits, and diff against `origin/main` to
establish what is already implemented.
5. Pull the live Plane ticket, comments, `blocked-by`, and `blocks` using
`.planning/plane-sync/fetch_ticket.py` or the available Plane integration. If
Plane is unavailable, continue from Git and the ticket doc but state that
evidence gap.
6. Never infer completion from a status badge alone.
## 2. Audit dependencies with three sources
Check both dependency directions. For every blocker or consumer, compare:
1. Plane state and all relevant comments.
2. Git/code reality, including merged commits and implementation notes.
3. The blocker and dependent ticket docs.
Decide whether the exact contract needed by this ticket exists. When sources
conflict, apply the precedence rules in `AGENTS.md`; otherwise expose the
conflict instead of inventing a resolution. For cross-cutting contracts,
schemas, shared services, or `blocks` consumers, include the dependent
verification work in the plan.
## 3. Decide the delivery strategy
Classify every open item as:
- `selbst machbar`
- `extern/blockiert`
- `bewusst v2/out-of-scope`
Recommend `jetzt bauen`, `teilweise bauen`, or `zurückstellen`, with a reason.
Do not pull work forward from later tickets.
For UI-heavy work, read `.planning/INTERIM-UI-PLAYBOOK.md` and
`.planning/INTERIM-UI-DESIGN-STANDARDS.md`. Missing final design does not
automatically block the ticket: plan the AD-28 interim screen when the ticket
permits it, and track final visual work as `design-nachzug`. Use finished
Automation/Forms screens and existing Settings Subscription/Billing interim
screens as style references.
If the ticket specifically integrates new or changed Subframe pages, also use
`$subframe-einbinden` and incorporate its inventory and integration
requirements.
## 4. Produce the plan in this order
1. Plain-language introduction
2. Current state and DoD percentage
3. Dependencies and delivery strategy
4. DoD-to-slices mapping
5. Ordered build plan by slice
6. Verification gates before commit
7. Open questions and risks
8. Reminder for post-build ticket-doc + Plane updates
## 5. Map every DoD item
For every DoD item, state:
- **Status:** done, open, or blocked.
- **Fertigkeitskriterium:** what must be true for full completion.
- **Proof:** the code path, test, screen, external artifact, or Plane evidence
that proves it.
- **Zählt NICHT als fertig:** which partial implementation would be
insufficient.
- **Slice:** where the work and verification happen.
Cross-check each DoD item against `Was wir bauen`, `Benötigte Screens`,
technical building blocks, Plane comments, and design notes. Count only fully
satisfied points. Report `% = completed DoD points / total DoD points`,
separating blocked work from work the developer can still do.
## 6. Make each slice executable
For each slice, name concrete files and include all applicable constraints:
- Loader/action builds the view model; UI receives VMs and callbacks.
- No `@prisma/client` or `~/db` in `packages/ui-app/**`.
- No direct `packages/ui-subframe` import from routes.
- No `useLoaderData` inside `packages/ui-app/**`.
- Reuse audit, activity, notifications, search, permissions, tenant scope, and
other cross-cutting services from `AGENTS.md`.
- Use i18n keys and the existing clear-text error/state patterns.
- For UI, include interim/final visual state, smoke, hot-swap, and
visual-baseline work as required.
- For schema work, use a module schema, develop with `prisma db push`, and plan
the current pre-merge migration/parity gates from `docs/AGENT-CHECKLIST.md`
without guessing around AD-21 timing.
Call out central registries whenever a slice adds or changes their inputs:
- Tenant-scoped Prisma model: tenant model registry plus ordering/tests.
- Workspace package subpath export: explicit Vitest alias plus consumer suites.
- Feature key: entitlements feature, blueprint, plan, and key-list tests.
- Permission key: permission seed, defaults, scope display, and de/en strings.
- Sidebar/navigation ID: UI registry, sidebar tests, and UI inventory mapping.
- UI text: de/en translations and i18n gates.
- Prisma schema: migration parity and the RLS live migration-chain gate.
## 7. Define verification before commit and push
Derive exact commands from `docs/AGENT-CHECKLIST.md`, the affected workspaces,
and `.gitea/workflows/ci.yml`. Include:
- typecheck, lint, and targeted tests for every affected package
- existing consumer suites for shared files, not only new tests
- applicable `verify:*` registry, i18n, RLS, migration, bundle, or Docker gates
- seed idempotency and browser/staging proof when the ticket requires them
- the no-US-provider and architectural anti-pattern checks when relevant
Do not schedule external writes, pushes, Plane changes, or Done transitions
without explicit authorization.
## 8. Include the post-build audit reminder
Before any completion report or Done-state recommendation, perform a
**Ticket-Abschluss-Audit**:
1. Re-read the ticket doc and current Plane comments.
2. Compare code state against every DoD item, required screen, and technical
building block.
3. Separate remaining work into `selbst machbar`, `extern/blockiert`, and
`bewusst v2`.
4. Count percentage only from fully satisfied DoD points. Partial backend-only
or UI-only work does not count as a full DoD point.
5. If a design ticket such as `D-*` is referenced, state whether its delta is
integrated, replaced by a valid interim baseline, or still blocking.
6. Update the ticket doc with date, proof, DoD checkboxes, and percentage before
any Plane completion action.
7. Mirror the result to Plane only with the required identity check and explicit
authorization; set Done only at 100% DoD.
8. If an interim screen was created, offer the optional David handover described
in `.planning/INTERIM-HANDOVER-GUIDE.md` instead of creating it silently.
End the response after the plan and ask whether it should be approved or
adjusted.
## Mandatory constraints
- Follow `AGENTS.md` strictly.
- Stay in ticket scope.
- Keep generated Subframe app chrome out of app screen components.
- Mark out-of-scope ideas explicitly as
`💡 Vorschlag (außerhalb Ticket-Scope): ...`.
- If a source is ambiguous, stop and ask instead of inventing.
@@ -0,0 +1,4 @@
interface:
display_name: "Ticket planen"
short_description: "HiveGrid-Tickets vollständig und belastbar planen"
default_prompt: "Use $plan-ticket to create a complete implementation plan for a HiveGrid ticket."
@@ -0,0 +1,179 @@
---
name: subframe-einbinden
description: Integrate new or changed Subframe pages and David design deltas into HiveGrid
through a screen inventory, Soll/Ist comparison, loader/view-model boundaries,
demo data, documentation, tests, and staging verification. Use when a user
asks to pull, compare, implement, update, or finish Subframe screens, pages,
flows, or a tracked design-nachzug.
---
# Subframe einbinden
Integrate Subframe design artifacts into the existing HiveGrid application.
Treat exported pages as design input, not drop-in application code.
## 1. Read the current contracts
Read before planning or changing code:
1. `AGENTS.md` and the relevant ticket doc.
2. `.planning/SUBFRAME-FLOW-INVENTAR.md` for the current flow/page integration
state.
3. `.planning/INTERIM-UI-PLAYBOOK.md` for app-shell, scrolling, local-kit,
layer, and tracking rules.
4. `.planning/INTERIM-UI-DESIGN-STANDARDS.md` for spacing, controls, dialogs,
states, and copy.
5. `.planning/INTERIM-HANDOVER-GUIDE.md` only when an interim-to-David handover
is in scope or must be offered.
If a Subframe MCP or product-specific design skill is available, load its
required instructions before calling it. Keep this HiveGrid workflow
authoritative for repository integration.
## 2. Establish an isolated branch
Start from current `origin/main` with the repository session/worktree helper.
Keep one flow, or one deliberately bounded flow subset, per branch and PR.
Preserve unrelated dirty worktrees.
Do not push, write Plane, or mutate Subframe without the user's authorization.
## 3. Inventory the Subframe target
Remember that `.subframe/sync.json` and component sync cover components,
layouts, and theme under `apps/web/app/ui`; they do not import complete pages or
application wiring.
Use the available Subframe integration in this order:
1. Call `list_flows`.
2. Call `get_flow_info` for the selected flow and page inventory.
3. Call `get_page_info` for each relevant page individually.
4. Exclude pages explicitly marked `_backlog_` unless the user includes them.
5. Record each screen's visible fields, filters, actions, states, dialogs,
navigation, and responsive variants.
Use project `f023064a5ca0` only when it remains the configured project in
`.subframe/sync.json`; otherwise use the current configured project. Avoid
loading huge page exports wholesale during inventory when a structural/text
extraction is sufficient.
## 4. Build the Soll/Ist delta
Inspect existing routes, loaders/actions, screens, view models, services,
permissions, Prisma models, tests, demo data, and current ticket ownership.
For each design page, classify:
- already integrated and current
- visual delta only
- needs loader/view-model/route-operation support
- lacks backend capability and must remain an explicit rest delta
- backlog or out of scope
Never invent backend behavior to make a design control appear functional. Wire
every visible action to an authorized capability, remove it, or render it
disabled with a documented reason. Respect ticket ownership and dependency
boundaries.
Before implementation, present the per-screen Soll/Ist delta, affected
files/layers, test plan, and remaining unsupported design delta. Ask for
approval when the user has requested planning or the implementation scope is not
already explicit.
## 5. Integrate behind the application boundary
Place app-chrome-free screens under `apps/web/app/components/screens/<domain>/`,
with dialogs in a local `dialogs/` folder when useful. Follow these rules:
- Routes own `useLoaderData`, `useSubmit`, fetchers, CSRF handling, redirects,
and loader/action wiring.
- Screens receive view models and action callbacks as props.
- Never nest `~/ui/layouts/DefaultPageLayout` or another generated
sidebar/header inside the HiveGrid app shell.
- Never import `packages/ui-subframe` directly from routes.
- Never import Prisma or `~/db` into `packages/ui-app/**`.
- Preserve host-aware paths for admin, app, and portal surfaces.
- Format dates and times through HiveGrid locale helpers with the configured
application timezone.
- Put every user-facing string in de/en i18n files; edit translation JSON
surgically.
- Keep rendering deterministic: no render-time `Math.random()`, `Date.now()`, or
unscoped locale formatting.
Use existing Automation and Forms screens plus Settings Subscription/Billing
interim screens as implementation references. Verify actual local component APIs
under `apps/web/app/ui/**`; cloud exports may use different props.
## 6. Apply the known Subframe footguns
1. **Document flow:** Remove page-export roots that combine
`h-full`/`overflow-hidden` with `basis-0`/inner `overflow-y-auto` where they
collapse inside the app shell. Register new screens in
`subframe-layout-boundary.test.ts`.
2. **Single app shell:** Keep sidebar, header, and breadcrumbs owned by HiveGrid
routes/layouts.
3. **Local kit first:** Read local `SearchInput`, table, badge, dropdown, and
dialog APIs instead of trusting cloud-export props.
4. **Title contract:** Return `data.title` and the route `meta` needed by
breadcrumbs and the browser tab.
5. **Timezone:** Use `useLocaleFormatters()` or the canonical server formatter.
6. **i18n:** Add de and en keys without JSON round-tripping or `defaultValue`
workarounds.
7. **Host-aware navigation:** Derive redirects/links from the current surface or
use the canonical path helper.
8. **No dead controls:** Wire, remove, or explicitly disable every exported
placeholder handler.
9. **Schema changes:** Keep changes additive and module-scoped; follow the
current AD-21 and pre-merge migration gates in `docs/AGENT-CHECKLIST.md`.
Treat `.planning/INTERIM-UI-PLAYBOOK.md` as the maintained source for newer
footguns.
## 7. Provide representative demo data
When the integrated screens depend on demo states, update
`scripts/seed-hivegrid-demo.ts` with deterministic IDs, `isDemoData: true`, and
idempotent upserts. Cover relevant populated, empty, warning, and error states.
Run the seed twice against the approved disposable local database and prove the
second run is stable.
Do not expand seed or schema scope merely to imitate unsupported design
behavior.
## 8. Update tracking and documentation
In the same implementation change:
- Update `.planning/SUBFRAME-FLOW-INVENTAR.md` with page count, status, date,
integrated delta, and explicit rest delta.
- Update the owning ticket doc with date, proof, DoD progress, and design
follow-up state.
- Add dependency-aware cross-reference notes to affected owner tickets when
required by `AGENTS.md`.
- Record reusable new footguns in `.planning/INTERIM-UI-PLAYBOOK.md`.
- Keep `/planning` authoritative for `design-nachzug`; Plane mirrors it only
after identity verification and authorization.
- Offer, but do not silently create, the David handover artifacts described in
`.planning/INTERIM-HANDOVER-GUIDE.md` when an interim screen was added.
## 9. Verify end to end
Run the applicable gates from `docs/AGENT-CHECKLIST.md`, including:
- affected workspace typechecks and lint
- targeted screen, route, loader/action, and view-model tests
- `subframe-layout-boundary.test.ts`
- i18n and hardcoded-string gates
- smoke, hot-swap, accessibility, and visual-baseline checks required by the
ticket
- seed idempotency when demo data changed
- migration/RLS gates when schema changed
After an authorized merge and deployment, verify the affected staging screens in
a real browser: content must be visibly rendered, breadcrumbs and titles must be
correct, actions must work, responsive states must hold, and the console must be
free of hydration errors.
Report what was integrated and list every remaining design/backend delta
explicitly.
@@ -0,0 +1,4 @@
interface:
display_name: "Subframe einbinden"
short_description: "Subframe-Screens sicher in HiveGrid integrieren"
default_prompt: "Use $subframe-einbinden to integrate the latest Subframe pages for a HiveGrid flow."