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.

- [X] T001 Create the root workspace manifest scaffold in `package.json` and `pnpm-workspace.yaml`
- [X] T002 [P] Create the website application scaffold directories in `apps/website/src/` and `apps/website/public/`
- [X] 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.

- [X] 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`
- [X] T005 [P] Align platform Composer Node scripts with pnpm in `apps/platform/composer.json`
- [X] T006 [P] Align repo ignore and formatting rules for website and workspace artifacts in `.gitignore` and `.prettierignore`
- [X] 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

- [X] 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`
- [X] T009 [P] [US1] Update the multi-app repo entry documentation and architecture overview in `README.md` and `docs/PROJECT_SUMMARY.md`
- [X] 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`
- [X] 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`
- [X] 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

- [X] T013 [US2] Implement the standalone Astro website manifest and app configuration in `apps/website/package.json` and `apps/website/astro.config.mjs`
- [X] 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`
- [X] T015 [P] [US2] Add website public assets and metadata files in `apps/website/public/favicon.svg` and `apps/website/public/robots.txt`
- [X] 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

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

### Implementation for User Story 3

- [X] T018 [US3] Finalize pnpm-based platform frontend scripts in `apps/platform/package.json` and `apps/platform/composer.json`
- [X] T019 [P] [US3] Preserve platform compatibility-helper and deployment asset guidance in `scripts/platform-sail` and `README.md`
- [X] T020 [P] [US3] Document multi-app platform isolation and rollout notes in `docs/HANDOVER.md` and `docs/PROJECT_SUMMARY.md`
- [X] 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.

- [X] 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`
- [X] 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`
- [X] T024 [P] Run the focused workspace foundation Pest suite in `apps/platform/tests/Feature/WorkspaceFoundation/`
- [X] 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`
- [X] 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

```bash
# 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

```bash
# 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

```bash
# 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.