44 lines
3.6 KiB
Markdown
44 lines
3.6 KiB
Markdown
# Agent Entrypoints
|
|
|
|
Use this file as a technical helper index when a coding agent plans or implements feature work in HiveGrid. For ticket work, `AGENTS.md` and `.planning/ticket-docs/README.md` are the primary entrypoints.
|
|
|
|
## Start Here
|
|
|
|
- Ticket-driven HiveGrid work: read `AGENTS.md`, then `.planning/ticket-docs/README.md`, then the specific `.planning/ticket-docs/<ID>.md`.
|
|
- 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.
|