TenantAtlas/specs/183-website-workspace-foundation/tasks.md

Tasks: Website / Workspace Foundation

Input: Design documents from /specs/183-website-workspace-foundation/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Tests are REQUIRED for this feature. Use focused Pest coverage under apps/platform/tests/Feature/WorkspaceFoundation/ plus contract-backed smoke validation from specs/183-website-workspace-foundation/contracts/workspace-command-model.md, specs/183-website-workspace-foundation/contracts/coexistence-smoke.openapi.yaml, and specs/183-website-workspace-foundation/quickstart.md. Operations: This feature does not introduce a new OperationRun type or change existing operations UX semantics. Coexistence, root-command, and build-isolation smoke validation is still required because the repo gains a second app runtime. RBAC: No authorization model changes are allowed. Validation must preserve existing /admin, /admin/t/{tenant}/..., and /system behavior exactly as-is. Operator Surfaces: No operator-surface redesign is part of this slice. Existing public, admin, tenant, and system surfaces must continue to render with the same routing and authorization semantics. Filament UI Action Surfaces: No new Filament action surfaces are introduced. Existing resources and pages must continue to work unchanged once the workspace foundation lands. Filament UI UX-001: No layout or information-architecture redesign is part of this feature. Filament panels, themes, and existing surface contracts must remain intact. Badges: No badge semantics change is planned. Existing badge rendering must continue to work after the workspace changes.

Organization: Tasks are grouped by user story so each story can be implemented and validated as an independent increment once the blocking workspace groundwork is complete.

Phase 1: Setup (Shared Workspace Scaffolding)

Purpose: Prepare the repo root, the website app scaffold, and the focused test namespace before the blocking workspace conversion begins.

• T001 Create the root workspace manifest scaffold in package.json and pnpm-workspace.yaml
• T002 [P] Create the website application scaffold directories in apps/website/src/ and apps/website/public/
• T003 [P] Create the focused workspace foundation test namespace in apps/platform/tests/Feature/WorkspaceFoundation/

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Complete the shared package-manager and repo-boundary work that all user stories depend on.

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

• T004 Replace single-app npm assumptions with the shared pnpm workspace baseline by creating pnpm-lock.yaml, updating apps/platform/package.json, and removing tracked apps/platform/package-lock.json
• T005 [P] Align platform Composer Node scripts with pnpm in apps/platform/composer.json
• T006 [P] Align repo ignore and formatting rules for website and workspace artifacts in .gitignore and .prettierignore
• T007 [P] Add baseline platform boot smoke coverage for workspace changes in apps/platform/tests/Feature/WorkspaceFoundation/PlatformBootSmokeTest.php

Checkpoint: The repo now has one JavaScript workspace standard, one shared lockfile model, and baseline platform smoke coverage for the multi-app transition.

---

Phase 3: User Story 1 - Start the Repo From One Clear Entry Model (Priority: P1) 🎯 MVP

Goal: Make the repo root the obvious and documented entry point for platform-only, website-only, and parallel local development.

Independent Test: From the repo root, a contributor can follow the updated docs and use the official commands to start the platform, the website, or both without undocumented steps.

Implementation for User Story 1

• T008 [US1] Implement the official root workspace scripts and package-manager declaration in package.json, aligned to specs/183-website-workspace-foundation/contracts/workspace-command-model.md
• T009 [P] [US1] Update the multi-app repo entry documentation and architecture overview in README.md and docs/PROJECT_SUMMARY.md
• T010 [P] [US1] Align human and assistant guidance with the multi-app command model in Agents.md, GEMINI.md, .github/copilot-instructions.md, and .github/agents/copilot-instructions.md
• T011 [US1] Add official root entry tasks and platform-only MCP scoping in .vscode/tasks.json, .vscode/mcp.json, and opencode.json, aligned to specs/183-website-workspace-foundation/contracts/workspace-command-model.md
• T012 [US1] Validate the platform-only, website-only, and parallel root entry flows, including the supported port-override path, against specs/183-website-workspace-foundation/contracts/workspace-command-model.md and specs/183-website-workspace-foundation/quickstart.md

Checkpoint: The repo root is now the documented primary entry path for the multi-app workspace.

---

Phase 4: User Story 2 - Work on the Website Independently (Priority: P2)

Goal: Introduce a real standalone public website app that can run and build without the platform runtime.

Independent Test: apps/website can start and build on its own, and its public pages render without the platform app running.

Implementation for User Story 2

• T013 [US2] Implement the standalone Astro website manifest and app configuration in apps/website/package.json and apps/website/astro.config.mjs
• T014 [P] [US2] Build the initial public website structure in apps/website/src/layouts/BaseLayout.astro, apps/website/src/pages/index.astro, and apps/website/src/styles/global.css
• T015 [P] [US2] Add website public assets and metadata files in apps/website/public/favicon.svg and apps/website/public/robots.txt
• T016 [US2] Validate standalone website boot, website-only build behavior, and the supported website port-override path against specs/183-website-workspace-foundation/contracts/coexistence-smoke.openapi.yaml and specs/183-website-workspace-foundation/quickstart.md

Checkpoint: The public website now exists as a real app and can be developed independently from the platform.

---

Phase 5: User Story 3 - Preserve Platform Stability During the Multi-App Transition (Priority: P3)

Goal: Keep apps/platform stable and prove the platform still boots, builds, and coexists cleanly with the website under the new workspace model.

Independent Test: Focused platform regression tests still pass, the platform dev/build workflow remains valid under pnpm, and platform plus website can run together without build or runtime collisions.

Tests for User Story 3

• T017 [P] [US3] Add platform workspace compatibility smoke coverage in apps/platform/tests/Feature/WorkspaceFoundation/PlatformWorkspaceCompatibilityTest.php

Implementation for User Story 3

• T018 [US3] Finalize pnpm-based platform frontend scripts in apps/platform/package.json and apps/platform/composer.json
• T019 [P] [US3] Preserve platform compatibility-helper and deployment asset guidance in scripts/platform-sail and README.md
• T020 [P] [US3] Document multi-app platform isolation and rollout notes in docs/HANDOVER.md and docs/PROJECT_SUMMARY.md
• T021 [US3] Validate focused platform regression, parallel local development, build separation, and the supported platform or website port-override path against specs/183-website-workspace-foundation/contracts/workspace-command-model.md, specs/183-website-workspace-foundation/contracts/coexistence-smoke.openapi.yaml, and specs/183-website-workspace-foundation/quickstart.md

Checkpoint: The platform remains stable under the new workspace model, and coexistence with the website is proven.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Remove stale single-app assumptions, normalize manifests, and finish the final validation pass.

• T022 [P] Remove stale npm-only and single-app references across README.md, Agents.md, GEMINI.md, .github/copilot-instructions.md, .github/agents/copilot-instructions.md, .vscode/tasks.json, .vscode/mcp.json, and opencode.json
• T023 [P] Normalize the final workspace manifests and app package files in package.json, pnpm-workspace.yaml, apps/platform/package.json, and apps/website/package.json
• T024 [P] Run the focused workspace foundation Pest suite in apps/platform/tests/Feature/WorkspaceFoundation/
• T025 Run the full contract-backed smoke validation, including the supported port-override path, and capture final coexistence evidence from specs/183-website-workspace-foundation/contracts/workspace-command-model.md, specs/183-website-workspace-foundation/contracts/coexistence-smoke.openapi.yaml, and specs/183-website-workspace-foundation/quickstart.md
• T026 [P] Audit the final repo topology and slice scope against specs/183-website-workspace-foundation/spec.md, package.json, pnpm-workspace.yaml, apps/, and README.md to confirm no packages/* shared package layer, no shared design-token, UI, or content packages, no apps/docs, no customer or auditor surface, no public API or developer portal work, no CMS, blog, or content-engine expansion, no TenantPilot domain feature changes, no large CI or CD re-architecture beyond this slice, and no additional app surfaces were introduced

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): Starts immediately and prepares the repo and test scaffolding.
• Foundational (Phase 2): Depends on Setup and blocks all user stories until the workspace standard, lockfile model, and baseline smoke coverage are in place.
• User Story 1 (Phase 3): Starts after Foundational and establishes the official root entry model.
• User Story 2 (Phase 4): Starts after Foundational and can proceed in parallel with User Story 1, but its final validation should use the root entry model created in User Story 1.
• User Story 3 (Phase 5): Starts after Foundational and should finish after User Stories 1 and 2 because it validates the final combined platform-plus-website setup.
• Polish (Phase 6): Starts after all desired user stories are complete.

User Story Dependencies

• US1: Depends only on Setup and Foundational work.
• US2: Depends on Setup and Foundational work; final root-command validation reuses US1.
• US3: Depends on Foundational work and validates the final integrated outcome of US1 and US2.

Within Each User Story

• Shared workspace manifests and package-manager conversion must land before docs or tasks that declare them as canonical.
• Website app config should land before website pages and assets.
• Platform stability validation should run after root scripts, website app setup, and pnpm-based platform scripts are complete.

Parallel Opportunities

• T002 and T003 can run in parallel during Setup.
• T005, T006, and T007 can run in parallel once T004 establishes the shared workspace baseline.
• T009 and T010 can run in parallel for US1.
• T014 and T015 can run in parallel for US2 once T013 establishes the website config.
• T017, T019, and T020 can run in parallel for US3.
• T022, T023, T024, and T026 can run in parallel during Polish.

---

Parallel Example: User Story 1

# Story 1 documentation and tooling work in parallel:
Task: T009 README.md and docs/PROJECT_SUMMARY.md
Task: T010 Agents.md, GEMINI.md, .github/copilot-instructions.md, and .github/agents/copilot-instructions.md

Parallel Example: User Story 2

# Story 2 website app work in parallel:
Task: T014 apps/website/src/layouts/BaseLayout.astro, apps/website/src/pages/index.astro, and apps/website/src/styles/global.css
Task: T015 apps/website/public/favicon.svg and apps/website/public/robots.txt

Parallel Example: User Story 3

# Story 3 stability work in parallel:
Task: T017 apps/platform/tests/Feature/WorkspaceFoundation/PlatformWorkspaceCompatibilityTest.php
Task: T019 scripts/platform-sail and README.md
Task: T020 docs/HANDOVER.md and docs/PROJECT_SUMMARY.md

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. STOP and VALIDATE: Confirm the repo root now exposes one clear command model for platform, website, and parallel local development.

Incremental Delivery

1. Finish Setup and Foundational to establish the shared workspace baseline.
2. Deliver US1 to make the repo root the canonical entry path.
3. Deliver US2 to make the website a real standalone public app.
4. Deliver US3 to prove platform stability and multi-app coexistence.
5. Finish Polish to remove stale assumptions and run the full smoke pack.

Parallel Team Strategy

With multiple developers:

1. Complete Setup and Foundational together.
2. After Foundational:
   • Developer A: US1 root scripts, docs, and tasks
   • Developer B: US2 website app structure and assets
3. After US1 and US2 are stable:
   • Developer C: US3 platform stability validation and rollout notes

---

Notes

• Suggested MVP scope for this feature is User Story 1 after Setup and Foundational are complete.
• [P] tasks touch different files or can be validated independently.
• Story labels map each implementation task back to the originating user story for traceability.
• The website must remain outside Sail in this slice; the platform must remain Sail-first.
• No shared package layer, shared design-token, UI, or content package, docs app, customer or auditor surface, public API or developer portal surface, CMS, blog, or content-engine expansion, TenantPilot domain feature change, or large CI/CD re-architecture should appear while executing these tasks.