Slice 0 Hybrid Platform Skeleton Implementation Plan

Full legacy body rendered for humans

B2BEA.org Slice 0 Hybrid Platform Skeleton Implementation Plan

> For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Establish the hybrid B2BEA.org foundation: Eleventy remains the fast public/static layer while a dedicated app/runtime layer owns authenticated, permissioned, write-heavy, preview, export, and operational workflows.

Architecture: Keep the existing Eleventy public site as the public rendering layer. Add a small app layer and shared contracts/packages for route ownership, auth decisions, metadata validation, data adapters, design tokens, and QA smoke coverage. Slice 0 does not migrate page content or build full admin/member/vendor/company features.

Tech Stack: Eleventy, Node.js, TypeScript, app-layer technology decision gate (Next.js + TypeScript recommended unless Cloudflare Pages Functions-only is explicitly chosen), Cloudflare Pages, Supabase, Sanity, HubSpot, node:test or Vitest, Playwright/screenshot smoke.

---

Source Artifacts

• target-architecture-spec v2
• implementation-roadmap v2
• design-system-spec v4
• route-family-inventory v3
• page-template-spec v1
• seo-geo-social-spec v1
• security-privacy-spec v1
• qa-baseline-spec v1

Scope

Slice 0 creates a working skeleton and testable contracts only.

In scope:

• Confirm and document workspace layout.
• Confirm app-layer technology.
• Confirm same-domain route split versus subdomains.
• Create route registry contract for public/static and app/protected ownership.
• Create access decision and guard contract.
• Create metadata validation contract.
• Create data adapter interfaces for Sanity, Supabase, and HubSpot.
• Create shared design-system token contract usable by Eleventy and app surfaces.
• Create basic app shell route placeholders for admin, member, vendor, company, auth/access states.
• Create automated tests and screenshot smoke harness.

Out of scope:

• Migrating public routes.
• Rebuilding homepage or editorial templates.
• Building real admin modules.
• Implementing real member/vendor/company workflows.
• Implementing payments, survey engine, exports, certification, or notifications.
• Changing canonical public content without a separate Slice 1 plan.

Decisions To Confirm Before Code

• App layer technology: Next.js + TypeScript, Remix, or Cloudflare Pages Functions plus lightweight frontend.
• Workspace layout: monorepo with public/app/packages, or current Eleventy repo plus separate app package.
• Route split: same-domain route prefixes or app/admin subdomains.

Recommended defaults for this plan:

• App layer: Next.js + TypeScript.
• Workspace layout: monorepo-style structure in the B2BEA website repo with current Eleventy public layer preserved.
• Route split: same-domain route prefixes first: /admin, /member, /vendor, /company, /login, /access-denied.

Proposed File Map

Exact paths must be adjusted after inspecting the selected implementation repo, but ownership should remain stable.

| path | responsibility |

| --- | --- |

| package.json | Workspace scripts for public build, app build, tests, and QA smoke. |

| src/_data/route-registry.js or packages/b2bea-routes/src/registry.ts | Canonical route ownership, page family, surface, custom treatment, sitemap/search inclusion. |

| packages/b2bea-auth/src/access-decision.ts | Shared AccessDecision type and guard result helpers. |

| packages/b2bea-auth/src/guards.ts | Server-side guard contract and test doubles. |

| packages/b2bea-metadata/src/metadata.ts | Route metadata type and validation rules. |

| packages/b2bea-data/src/sanity.ts | Sanity adapter interface and no-secret stub implementation. |

| packages/b2bea-data/src/supabase.ts | Supabase adapter interface and no-secret stub implementation. |

| packages/b2bea-data/src/hubspot.ts | HubSpot adapter interface and no-secret stub implementation. |

| packages/b2bea-design-system/src/tokens.ts | Shared B2BEA design tokens used by public and app layers. |

| packages/b2bea-design-system/src/components.ts | Minimal component contract exports for buttons, cards, fields, page headers, states. |

| app routes or functions | Placeholder private shells for admin/member/vendor/company/auth/access states. |

| tests/routes/route-registry.test.* | Route classification and sitemap/search tests. |

| tests/auth/access-decision.test.* | Guard decision tests. |

| tests/metadata/metadata.test.* | Metadata validation tests. |

| tests/design-system/tokens.test.* | Design token and component contract tests. |

| tests/qa/smoke-routes.test.* | Browser/screenshot smoke route list. |

Design System Governance Addendum

The B2BEA design system is still actively improving. Slice 0 must therefore establish styling governance before page migration or app surface buildout.

Implementation rule: no rogue CSS. Public Eleventy templates and app-layer surfaces consume approved design-system tokens, components, and scoped custom exceptions only.

Slice 0 must add a design governance audit that fails on raw colors outside design-system files, inline style attributes outside an allowlist, page-specific primitive CSS, unregistered route CSS files, duplicate button/card/field/nav/table/page-header implementations, and unscoped custom import CSS.

Product/page code should use semantic tokens and component contracts. Designer updates should flow through token/component values rather than route-level rewrites.

Additional Slice 0 Task: CSS Governance Audit

Files:

• Create: design governance audit script/test in the selected implementation repo.
• Modify: package scripts to run the audit with tests.

• Step 1: Write failing governance audit tests

Test fixtures should include:

• a page file with raw #00196C and expect failure
• a page file with style="" and expect failure unless allowlisted
• a route CSS file without custom exception registration and expect failure
• a scoped custom CSS file with a registered custom exception and expect pass
• design-system token files with raw values and expect pass

• Step 2: Implement audit allowlist

Allow raw visual values only inside approved design-system files and registered custom exception files.

• Step 3: Wire audit into verification

Run the audit as part of Slice 0 verification and future public/app build checks.

• Step 4: Commit

git add <governance-audit-files> <package-script-updates>
git commit -m "test: add b2bea css governance audit"

Confirmed Slice 0 Setup Decisions

These defaults were set after inspecting the current B2BEA implementation repo on 2026-05-08.

| decision | value | rationale |

| --- | --- | --- |

| implementation repo | /Users/justinking/Vaults/Projects/B2BEA-org-new | Existing Eleventy public site and Cloudflare Pages Functions already live here. No new repo for Slice 0. |

| preservation branch | feature/content-quality-cleanup at commit b6721fc | Dirty Lovable/page migration work was preserved as WIP before Slice 0 isolation. |

| Slice 0 worktree | .worktrees/b2bea-slice-0-hybrid-skeleton | Clean isolated workspace from origin/main. |

| Slice 0 branch | feature/b2bea-slice-0-hybrid-skeleton | Keeps architecture/contracts separate from page migration work. |

| app/runtime layer | Cloudflare Pages Functions first | Current repo already has functions/api; use the thinnest runtime that proves server-side guards and workflows before introducing a heavier app framework. |

| future app option | Next.js/TypeScript only if Functions prove too thin | Avoid premature second app/repo while keeping an escape hatch. |

| route split | same-domain route prefixes first | Use /admin, /member, /vendor, /company, /login, /access-denied; subdomains only if Cloudflare routing becomes brittle. |

| design governance | mandatory before page/app buildout | No rogue CSS; styling goes through tokens/components or scoped custom exceptions. |

Baseline evidence from setup:

• WIP branch verification before commit: npm test passed 25/25 and npm run build exited 0 with existing content/data warnings.
• Clean Slice 0 worktree baseline: npm test is not available on origin/main because package.json has no test script; npm run build exited 0 with expected missing-env fallbacks.

Implementation agents should start in the Slice 0 worktree, not the original dirty branch.

Task 1: Repo And Workspace Decision Record

Files:

• Create or update implementation-repo decision record for Slice 0.
• No product routes yet.

• Step 1: Inspect current repo shape

Run from the selected B2BEA implementation repo:

git status --short --branch
find . -maxdepth 2 -type f ( -name 'package.json' -o -name 'eleventy.config.*' -o -name '.eleventy.js' -o -name 'wrangler.toml' -o -name 'next.config.*' ) -print

Expected: identify current Eleventy public-site configuration and whether a workspace/app layer already exists.

• Step 2: Write the architecture decision record

Create a short implementation-local decision record that states:

# Slice 0 Architecture Decision

B2BEA.org uses a hybrid architecture.

- Public/static layer: Eleventy.
- App/runtime layer: [chosen app technology].
- Shared contracts: route registry, access decision, metadata validation, design tokens, data adapters.
- Route split: [same-domain prefixes or subdomains].
- Public practitioner company profiles/directories are excluded from V1.

• Step 3: Commit only the decision record if code is not started in the same change

git add <decision-record-path>
git commit -m "docs: record b2bea hybrid architecture decision"

Task 2: Route Registry Contract

Files:

• Create: route registry module.
• Test: route registry tests.

• Step 1: Write failing route registry tests

Test these cases:

• / is public/static and sitemap/search eligible.
• /admin is protected/app and excluded from sitemap/search.
• /member is protected/app and excluded from sitemap/search.
• /vendor is protected/app and excluded from sitemap/search.
• /company is protected/app and excluded from sitemap/search.
• /studio redirects to /admin/studio.
• /vendor-portal redirects to /vendor.
• every route record has surface, page_family, owner_layer, custom_treatment, sitemap, search_index.

• Step 2: Implement minimal route registry

Define route records with these fields:

type RouteRecord = {
  route: string;
  surface: 'public_site' | 'auth_account' | 'b2bea_admin' | 'member_portal' | 'vendor_portal' | 'company_workspace';
  pageFamily: string;
  ownerLayer: 'eleventy_public' | 'app_runtime' | 'redirect' | 'system_generated';
  customTreatment: 'none' | 'home_custom' | 'campaign_custom' | 'signature_editorial' | 'custom_html_import';
  sitemap: boolean;
  searchIndex: boolean;
  redirectTo?: string;
};

• Step 3: Run registry tests

Expected: tests pass and private/app routes are excluded from public discovery.

• Step 4: Commit

git add <route-registry-files> <route-registry-tests>
git commit -m "feat: add b2bea route ownership registry"

Task 3: Access Decision And Guard Contract

Files:

• Create: auth/access decision module.
• Test: guard contract tests.

• Step 1: Write failing access tests

Test these cases:

• anonymous user can access public route.
• anonymous user cannot access /admin.
• member cannot access another member resource by ID.
• vendor user cannot access another vendor account scope.
• company user cannot access another company workspace scope.
• admin can access admin shell when role includes b2bea_admin.
• denied decisions include reason and source.

• Step 2: Implement AccessDecision type and helper

Implement the shared shape:

type AccessDecision = {
  allowed: boolean;
  subjectId: string | null;
  subjectRoles: string[];
  resourceType: string;
  resourceId?: string;
  entitlementKey?: string;
  reason: string;
  source: 'role' | 'entitlement' | 'ownership' | 'public' | 'denied';
};

• Step 3: Implement guard stubs

Add pure functions for route, role, and ownership checks. Do not connect real auth provider yet.

• Step 4: Run access tests

Expected: pass with deterministic test subjects and resource scopes.

• Step 5: Commit

git add <auth-contract-files> <auth-tests>
git commit -m "feat: add b2bea access decision contract"

Task 4: Metadata Validation Contract

Files:

• Create: metadata module.
• Test: metadata tests.

• Step 1: Write failing metadata tests

Test these cases:

• public page requires title, description, canonical path, schema type, OG fields, GEO summary.
• private route must be noindex and excluded from sitemap/search.
• published route cannot change slug without redirect record.
• custom route requires custom treatment marker.

• Step 2: Implement metadata validator

Implement minimal validation result:

type MetadataValidation = {
  valid: boolean;
  errors: string[];
};

• Step 3: Run metadata tests

Expected: all tests pass.

• Step 4: Commit

git add <metadata-files> <metadata-tests>
git commit -m "feat: add b2bea metadata validation contract"

Task 5: Shared Design-System Token Contract

Files:

• Create or update shared design token module.
• Test: design-system token tests.

• Step 1: Write failing token tests

Assert exact V1 values:

• primary #00196C
• accent #EB5444
• background #FFFFFF
• surface #F5F5F5
• radius 0.75rem
• standard page title scale clamp(2.25rem, 4vw, 3.75rem)
• article title scale clamp(2.75rem, 6vw, 5rem)

• Step 2: Implement token exports

Expose tokens for both Eleventy CSS generation and app components.

• Step 3: Add minimal component contract exports

Add contracts for button, card, field, badge, page header, state panel. Do not build full visual library in Slice 0.

• Step 4: Run design-system tests

Expected: exact token tests pass.

• Step 5: Commit

git add <design-system-files> <design-system-tests>
git commit -m "feat: add shared b2bea design token contract"

Task 6: Data Adapter Interfaces

Files:

• Create: Sanity, Supabase, HubSpot adapter interfaces.
• Test: adapter interface tests.

• Step 1: Write failing adapter tests

Test that pages/components can import local adapter interfaces without importing external SDK clients directly.

• Step 2: Implement no-secret adapter stubs

Adapters should expose typed method signatures and return deterministic stub responses in tests. Do not read real credentials in Slice 0 unit tests.

• Step 3: Add lint/static check if practical

Forbid direct SDK imports outside adapter directories.

• Step 4: Run adapter tests

Expected: pass without network or secrets.

• Step 5: Commit

git add <adapter-files> <adapter-tests>
git commit -m "feat: add b2bea data adapter contracts"

Task 7: App Shell Placeholders

Files:

• Create app-layer shell routes according to selected technology.
• Test: route smoke tests.

• Step 1: Write shell route tests

Expected shell routes:

• /admin
• /admin/studio
• /member
• /vendor
• /company
• /login or chosen auth entry
• /access-denied

• Step 2: Implement minimal shells

Each shell should render:

• surface name
• protected/public state marker
• no real data
• no marketing hero on admin/private shells
• shared design tokens applied

• Step 3: Run route smoke tests

Expected: app shell routes render and private shells are marked protected.

• Step 4: Commit

git add <app-shell-files> <route-smoke-tests>
git commit -m "feat: add b2bea app shell placeholders"

Task 8: Public Eleventy Shell Contract

Files:

• Modify minimally: Eleventy public layout only if needed.
• Test: public route/static tests.

• Step 1: Write tests for public static ownership

Assert public pages remain Eleventy-owned and private app prefixes are not emitted in sitemap/search index.

• Step 2: Add registry integration to public build

Use route registry to classify sitemap/search inclusion. Do not migrate public templates yet.

• Step 3: Run Eleventy build/test

Expected: public build still succeeds and no private app route enters public discovery.

• Step 4: Commit

git add <eleventy-registry-integration> <public-tests>
git commit -m "feat: connect public build to route registry"

Task 9: QA Smoke Harness

Files:

• Create or update QA smoke test setup.
• Test: screenshot smoke route list.

• Step 1: Define smoke route matrix

Minimum routes:

• /
• /login
• /access-denied
• /admin
• /admin/studio
• /member
• /vendor
• /company

Viewports:

• 1440x1000
• 834x1112
• 390x844

• Step 2: Implement smoke harness

Use Playwright or the repo-standard browser test tool. Capture screenshots or at least route render assertions if screenshot tooling is not yet available.

• Step 3: Add failure checks

Fail on HTTP errors, blank pages, obvious horizontal overflow, and private route inclusion in public sitemap/search output.

• Step 4: Run smoke harness

Expected: all shell routes render.

• Step 5: Commit

git add <qa-harness-files>
git commit -m "test: add b2bea hybrid shell smoke checks"

Task 10: Slice 0 Verification And Handoff

Files:

• Update implementation-local README or handoff note.
• Update Studio artifact status only after review.

• Step 1: Run full verification

Required commands depend on selected repo, but must include:

• unit tests
• public build
• app build or route smoke
• screenshot/smoke harness
• lint/typecheck where configured

• Step 2: Produce Slice 0 handoff

Record:

• chosen app-layer technology
• chosen route split
• repo/workspace layout
• commands run and results
• known limitations
• next slice recommendation

• Step 3: Commit final handoff

git add <handoff-note>
git commit -m "docs: complete b2bea slice 0 handoff"

• Step 4: Update Studio artifact

After Justin reviews and accepts the implementation result, update the Slice 0 plan/build artifact status according to Studio workflow.

Completion Criteria

Slice 0 is complete when:

• Hybrid architecture decision is implemented as repo structure and contracts.
• Public/static and app/protected route ownership is testable.
• Guard, metadata, data adapter, and design token contracts exist and pass tests.
• Public Eleventy build remains intact.
• App shell placeholders render for private surfaces.
• Private routes are excluded from sitemap/search index.
• Desktop/tablet/mobile smoke checks pass for shell routes.
• The next implementation plan can target Slice 1 Public Static Core or Slice 2 Content And Publishing without re-deciding architecture.