HiveGrid-Wireframes/hivegrid-cloud/docs/agent-playbooks/feature-integration.md

Feature Integration Playbook

Use this playbook when adding a feature to the boilerplate or adapting a proprietary feature from another product.

Goal

Make the feature understandable before implementation. A human operator and a coding agent should be able to answer where the feature lives, who owns its configuration, which flows it exposes, and how to verify it.

Required Steps

1. Read docs/agent-entrypoints.md.
2. Find or create a manifest in docs/feature-manifests/.
3. Classify ownership:
   • tenant-owned: tenant configures and uses it.
   • admin-managed: admin/platform configures it; tenant only uses approved surfaces.
   • hybrid: admin defines policy/defaults; tenant can configure local behavior.
   • system-only: internal platform feature with no tenant-owned controls.
4. Map surfaces:
   • Admin route source files and canonical admin-host runtime paths.
   • Tenant route source files and canonical tenant-host runtime paths.
   • Public route source files and root/web-host runtime paths.
   • API route source files and canonical API-host /v1/... runtime paths.
   • Link/form/action helpers: adminPath, appPath, apiPath, cross-host helpers, or UrlUtils.getModulePath(...) for tenant modules.
5. Map persistence:
   • Prisma models.
   • Existing tables reused.
   • Migrations required.
   • Tenant scoping fields.
6. Map configuration:
   • Admin settings.
   • Tenant settings.
   • Environment variables.
   • Secrets and their owner.
7. Map runtime:
   • Request/response only.
   • Queue-backed.
   • Worker-backed.
   • Browser-backed.
8. Map controls:
   • Permissions.
   • Audit events.
   • Billing or usage limits.
9. Define UAT:
   • Operator-visible checks.
   • Negative checks for forbidden access.
   • Secret exposure checks if providers are involved.

Implementation Rules

• Do not expose provider secrets through tenant loaders, API responses, client bundles or logs.
• Do not add sidebar/nav entries without stable UI IDs.
• Do not add new root UI primitives without updating docs/ui-inventory/components.json.
• Do not add worker behavior without declaring queues and jobs in the manifest.
• Do not add admin-managed tenant behavior without admin permissions and audit events.
• Keep proprietary feature logic behind explicit module boundaries.
• Do not hard-code legacy runtime paths such as /admin/..., /app/..., or /api/v1/... outside tests that explicitly cover legacy redirects.
• Do not ship visible UI text without locale keys and pnpm run verify:i18n.

Done Criteria

• Manifest updated and valid.
• Routes and surfaces match the manifest.
• Permissions are enforced on admin/API/tenant surfaces.
• Tenant-scope negative tests cover forbidden reads and mutations.
• Route helpers and runtime host ownership are tested for new navigation.
• i18n and deploy/static verifiers relevant to the change have run.
• Required worker queues/jobs exist or are explicitly deferred.
• UAT checks pass or are marked as deferred with a reason.