HiveGrid-Wireframes/hivegrid-cloud/docs/agent-entrypoints.md

Agent Entrypoints

Use this file as the first stop when a coding agent plans or implements feature work in this boilerplate.

Start Here

• Interpreting old improvement-plan status, handoffs, or verification notes: read docs/improvement-plan/CURRENT-STATUS.md first, then follow the canonical docs it links.
• New or migrated feature: read docs/agent-playbooks/feature-integration.md and update the matching manifest before implementation.
• Existing MVP import: read docs/agent-playbooks/mvp-intake.md before proposing code changes.
• Admin-managed tenant feature: read docs/agent-playbooks/admin-managed-features.md.
• Foundation, billing usage, notifications, flags, permissions, audit, or idempotency changes: read docs/agent-playbooks/foundation-boundaries.md.
• Worker-backed or browser-backed feature: read docs/agent-playbooks/worker-backed-features.md, docs/ops/worker-queues.md, and packages/queue/src/payloads.ts.
• Plugin, WASM, lifecycle, or hook work: read docs/features/plugins.md, docs/operations/plugin-lifecycle.md, and docs/security/plugin-runtime-signoff.md.
• UI surface or component changes: start with docs/ui-inventory/surface-map.md, then read docs/agent-playbooks/ui-changes.md, docs/ui-inventory/, and apps/web/app/application/ui/uiRegistry.ts.
• Navigation, sidebar, or route-helper changes: read docs/navigation-architecture.md.
• UI adapter or hotswap work: read docs/agent-playbooks/ui-adapter-migration.md and packages/ui/README.md.
• Feature ownership, dependencies, configuration, provider, worker and UAT contracts: read docs/feature-manifests/.
• New manifest scaffold: run pnpm run manifest:new -- --id my-feature --title "My Feature" --classification plugin-candidate --ownership hybrid, then replace placeholders before coding.
• Architecture Closure closure/status contract: start from the aligned sources docs/archive/architecture-handoff-summary.md, docs/architecture-migration-status.md, docs/feature-inventory.md, and docs/feature-manifests/*.json; read them together before planning implementation, extraction, or removal work.

Agent Rule

Do not jump from a user request directly into implementation when the request imports an existing product, adds a proprietary feature, adds provider credentials, changes admin-managed behavior, or introduces workers.

For those requests, produce or update a feature manifest first. The manifest is the contract the implementation must satisfy.

Expected Planning Output

For a substantial feature, the planning output should identify:

• Existing user flows and target boilerplate flows.
• Feature ownership: tenant-owned, admin-managed, hybrid, or system-only.
• Admin, tenant, public and API surfaces.
• Runtime route ownership and helper choice: admin host paths use adminPath, tenant app paths use appPath or UrlUtils.getModulePath(...), and API host paths use apiPath//v1.
• Tenant-scope and negative access checks for every loader/action/API mutation that touches tenant data.
• i18n surfaces, including new locale keys and pnpm run verify:i18n when UI text changes.
• Deploy/static gates affected by the change, especially pnpm run verify:deploy-workflow, Docker baseline/static checks, and production seed artifact checks for deploy work. Run live Docker smokes only when the task explicitly requires them.
• Database models and migrations.
• Provider credentials and secret ownership.
• Worker queues and jobs.
• Permissions and audit events.
• Billing or usage-metering impact.
• UAT checks the operator can run.