TenantAtlas/specs/216-homepage-structure/tasks.md

Tasks: Website Homepage Structure & Section Model

Input: Design documents from /specs/216-homepage-structure/
Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/homepage-surface.openapi.yaml

Tests: Browser smoke coverage and the root website build proof are required for this runtime-changing website feature.

Test Governance Checklist

• Lane assignment stays Browser in fast-feedback, which is the narrowest sufficient proof for this homepage-only change.
• New or changed tests stay in the existing website smoke suite instead of widening into a heavier family.
• Shared helpers stay cheap by default; no backend, auth, database, or provider fixtures are introduced.
• Planned validation commands remain the feature-local website build proof and Playwright smoke suite.
• No additional budget, baseline, or escalation path is required beyond document-in-feature for this slice.

Phase 1: Setup (Shared Infrastructure)

Purpose: Establish the homepage-specific content/type surface before story work begins.

• T001 Add homepage-specific section content types for hero visuals, optional trust subclaims, outcome framing, capability clusters, trust signals, and progress teasers in apps/website/src/types/site.ts

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Add the reusable homepage helpers and scaffolds that every story slice depends on.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

• T002 [P] Create reusable homepage section scaffolds in apps/website/src/components/sections/OutcomeSection.astro and apps/website/src/components/sections/ProgressTeaser.astro
• T003 [P] Add a shared recent-changelog helper for homepage progress signals in apps/website/src/lib/changelog.ts
• T004 [P] Extend homepage smoke helpers for ordered section, product-near visual, mobile viewport, and CTA assertions in apps/website/tests/smoke/smoke-helpers.ts

Checkpoint: Homepage foundations are ready. User-story work can proceed.

---

Phase 3: User Story 1 - Understand the Product Fast (Priority: P1) 🎯 MVP

Goal: Make the homepage explain what TenantAtlas is, why it matters, and what the next step is within the first reading pass.

Independent Test: Visit / and confirm the hero, outcome framing, and CTA hierarchy make the product category, buyer relevance, and next step understandable without opening any other route.

Tests for User Story 1

Note

: Write this test first and confirm it fails before implementing the story.

• T005 [P] [US1] Write failing homepage smoke assertions for hero clarity, product-near visual presence, outcome framing, and one dominant CTA hierarchy in apps/website/tests/smoke/home-product.spec.ts

Implementation for User Story 1

• T006 [P] [US1] Add Spec 216 hero content, product-near visual data, optional bounded trust subclaims, and outcome blocks in apps/website/src/content/pages/home.ts
• T007 [US1] Implement the hero-to-outcome homepage flow and hero visual rendering in apps/website/src/pages/index.astro and apps/website/src/components/sections/PageHero.astro

Checkpoint: The homepage delivers the MVP story of product clarity, buyer relevance, and one clear next step.

---

Phase 4: User Story 2 - Evaluate Product Model and Trust Without a Feature Wall (Priority: P2)

Goal: Turn the homepage middle section into a grouped product model with explicit trust and visible progress instead of route-job cards.

Independent Test: Visit / and confirm the homepage shows grouped capability coverage, an explicit trust block, and a dated progress signal before the final CTA.

Tests for User Story 2

Note

: Write this test first and confirm it fails before implementing the story.

• T008 [P] [US2] Write failing homepage smoke assertions for grouped capability clusters, explicit trust visibility, and pre-CTA progress signaling in apps/website/tests/smoke/home-product.spec.ts and apps/website/tests/smoke/changelog-core-ia.spec.ts

Implementation for User Story 2

• T009 [P] [US2] Replace route-job homepage cards with grouped capability and trust/progress content data in apps/website/src/content/pages/home.ts and apps/website/src/content/pages/trust.ts
• T010 [US2] Render the grouped capability model and explicit trust block on the homepage in apps/website/src/pages/index.astro and apps/website/src/components/sections/TrustGrid.astro
• T011 [US2] Use the shared changelog helper to wire a dated homepage progress teaser in apps/website/src/components/sections/ProgressTeaser.astro and apps/website/src/pages/index.astro

Checkpoint: The homepage explains the connected product model, shows explicit trust, and proves visible product movement.

---

Phase 5: User Story 3 - Move Into the Right Next Route (Priority: P3)

Goal: Make Product, Trust, Changelog, Contact, and legal follow-through obvious from the homepage without multiple competing conversion paths.

Independent Test: Start on / and confirm the homepage routes clearly into /product, /trust, /changelog, and /contact, while footer/legal links remain discoverable and optional unpublished routes stay de-emphasized.

Tests for User Story 3

Note

: Write this test first and confirm it fails before implementing the story.

• T012 [P] [US3] Write failing homepage smoke assertions for Product, Trust, Changelog, Contact, footer/legal discoverability, and narrow-screen/mobile visibility in apps/website/tests/smoke/home-product.spec.ts and apps/website/tests/smoke/contact-legal.spec.ts

Implementation for User Story 3

• T013 [P] [US3] Align homepage CTA targets, secondary deep links, and optional-route suppression in apps/website/src/content/pages/home.ts and apps/website/src/lib/site.ts
• T014 [P] [US3] Tighten header and footer route discoverability for the homepage journey on desktop and narrow screens in apps/website/src/components/layout/Navbar.astro and apps/website/src/components/layout/Footer.astro
• T015 [US3] Finalize homepage onward routing to /product, /trust, /changelog, and /contact in apps/website/src/pages/index.astro

Checkpoint: The homepage routes qualified visitors into the right next page without dead ends or competing primary actions.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Validate proof commands, tighten claim wording, and capture close-out notes.

• T016 [P] Review homepage proof and trust wording against bounded-claim rules in apps/website/src/content/pages/home.ts, apps/website/src/content/pages/trust.ts, and apps/website/src/content/pages/changelog.ts
• T017 [P] Run corepack pnpm build:website from package.json and confirm homepage proof expectations in specs/216-homepage-structure/quickstart.md
• T018 [P] Run cd apps/website && corepack pnpm exec playwright test against apps/website/tests/smoke/home-product.spec.ts, apps/website/tests/smoke/changelog-core-ia.spec.ts, and apps/website/tests/smoke/contact-legal.spec.ts
• T019 Record the homepage smoke-coverage close-out and verification notes in specs/216-homepage-structure/plan.md and specs/216-homepage-structure/quickstart.md

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): Starts immediately.
• Foundational (Phase 2): Depends on Setup and blocks all user stories.
• User Stories (Phases 3-5): Depend on Foundational. They remain independently testable, but shared homepage assembly in apps/website/src/pages/index.astro should land sequentially in story order.
• Polish (Phase 6): Depends on all desired user stories being complete.

User Story Dependencies

• User Story 1 (P1): Starts after Foundational and is the MVP slice.
• User Story 2 (P2): Starts after Foundational for content and helper work, and remains independently valuable because it upgrades the homepage product-model and proof layer. Its shared index.astro assembly should follow US1.
• User Story 3 (P3): Starts after Foundational for routing and shell work, and remains independently valuable because it sharpens onward routing and CTA clarity from the homepage. Its shared index.astro assembly should follow US2.

Within Each User Story

• Write the story-specific browser smoke assertions first and confirm they fail.
• Update content modules and supporting helpers before final route composition in apps/website/src/pages/index.astro.
• Treat apps/website/src/pages/index.astro as a shared assembly point: content/helper work may branch, but homepage route composition should land sequentially.
• Finish the homepage route wiring before running the story proof commands.

---

Parallel Opportunities

• T002, T003, and T004 can run in parallel after T001.
• In US1, T005 and T006 can run in parallel before T007.
• In US2, T008 and T009 can run in parallel before T010; T011 follows the shared homepage assembly work.
• In US3, T013 and T014 can run in parallel before T015.
• T016, T017, and T018 can run in parallel during polish before T019.

---

Parallel Example: User Story 1

# After the foundations are complete, split the first slice into test + content work:
Task: "T005 [US1] Write failing homepage smoke assertions for hero clarity, outcome framing, and one dominant CTA hierarchy"
Task: "T006 [US1] Add Spec 216 hero and outcome content blocks"

# Then assemble the homepage route:
Task: "T007 [US1] Implement the hero-to-outcome homepage flow"

Parallel Example: User Story 2

# Safe split inside US2 is limited to assertions plus content prep before homepage assembly:
Task: "T008 [US2] Write failing homepage smoke assertions for grouped capability clusters, explicit trust visibility, and pre-CTA progress signaling"
Task: "T009 [US2] Replace route-job homepage cards with grouped capability and trust/progress content data"

# Then complete the shared homepage assembly sequentially:
Task: "T010 [US2] Render the grouped capability model and explicit trust block on the homepage"
Task: "T011 [US2] Use the shared changelog helper to wire a dated homepage progress teaser"

Parallel Example: User Story 3

# Split route-target and shell-discoverability work once the routing assertions exist:
Task: "T013 [US3] Align homepage CTA targets, secondary deep links, and optional-route suppression"
Task: "T014 [US3] Tighten header and footer route discoverability for the homepage journey"

# Then finish the homepage route wiring:
Task: "T015 [US3] Finalize homepage onward routing to /product, /trust, /changelog, and /contact"

---

Implementation Strategy

MVP First

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Run the homepage build proof and US1 browser smoke coverage.
5. Demo the homepage MVP with clear product explanation and one dominant next step.

Incremental Delivery

1. Foundations create the reusable homepage scaffolds, changelog helper, and smoke assertions.
2. US1 establishes immediate product clarity and CTA discipline.
3. US2 upgrades the homepage middle narrative into grouped product model, trust, and progress proof.
4. US3 sharpens onward routing and discoverability for Product, Trust, Changelog, Contact, and legal follow-through.
5. Polish runs both proof commands, validates wording, and records close-out notes before merge.

Suggested MVP Scope

• Deliver through User Story 1 for the smallest independently valuable slice.
• Add User Story 2 next for stronger product-model and trust proof.
• Finish with User Story 3 for fully deliberate onward routing from the homepage.