openpetswithchatandmcp/docs/phases/phase-00-workspace-foundation.md

Phase 00: Workspace foundation and DX

Goal

Create the fresh OpenPets 2.0 workspace foundation with excellent developer experience and Node/npm-compatible runtime behavior.

This phase should establish the project skeleton and basic commands needed for later implementation phases, without building real product features yet.

Non-goals

This phase does not implement:

• Tray/menu app behavior.
• Floating pet windows.
• Pet rendering.
• Pet catalog browsing or installation.
• Local IPC.
• MCP tools.
• Claude detection/configuration/hooks.
• First-run onboarding.
• Packaging/release builds.

This phase should also avoid large migrations from v1. v1 remains reference material only.

User-visible/manual outcome

After this phase, the user/developer should be able to install dependencies and run basic workspace checks from a clean v2 workspace.

Expected manual outcome:

I can install dependencies, inspect the v2 workspace structure, and run basic check/build scripts without using Bun.

Acceptance criteria

• A fresh v2 workspace structure exists outside v1/.
• v1 remains untouched except as reference material.
• Runtime and published package design is Node/npm/npx-compatible.
• Bun is not required for v2 runtime behavior.
• Development tooling is documented clearly.
• Node baseline is documented.
• Workspace boundaries exclude v1 and web app code from v2 workspace commands.
• Initial packages are protected from accidental publishing while they are skeletons.
• Basic workspace scripts exist for checking/building the initial skeleton.
• Package names align with the agreed @open-pets/* organization.
• The initial package/app structure supports later phases without overbuilding empty abstractions.
• The repo clearly distinguishes current v2 code from v1 reference code.

Proposed files/directories

Create or update:

package.json
pnpm-workspace.yaml
pnpm-lock.yaml
tsconfig.base.json
.gitignore
README.md                    # if useful for v2 developer commands

apps/
  desktop/
    package.json
    tsconfig.json
    src/
      main.ts                # placeholder or minimal entry, no real tray behavior yet

packages/
  client/
    package.json
    tsconfig.json
    src/index.ts

  mcp/
    package.json
    tsconfig.json
    src/index.ts

  claude/
    package.json
    tsconfig.json
    src/index.ts

  cli/
    package.json
    tsconfig.json
    src/index.ts

  pet-format/
    package.json
    tsconfig.json
    src/index.ts

Important constraint:

• Do not add large placeholder systems just to fill packages.
• If a package would be purely empty and creates more maintenance than value, keep it minimal with only package metadata and a tiny exported placeholder/type needed for build checks.
• Defer packages/shared until there is a concrete first use. Avoid creating a dumping-ground package in Phase 00.

Technical approach

Use pnpm workspaces for development ergonomics.

Recommended baseline:

Node: 20+
Package manager: pnpm via Corepack
Module style: ESM
Build: plain TypeScript `tsc` for initial packages

Node 20+ is a conservative baseline with broad ecosystem support. A later phase may raise this if Electron or another dependency requires it.

Important distinction:

Developer package manager: pnpm
Runtime/user interface: Node/npm/npx

This means:

• Contributors may run pnpm install and pnpm check during development.
• Contributors should use Corepack or an explicitly documented pnpm version from the root packageManager field.
• Published packages must be usable through normal Node/npm/npx flows.
• @open-pets/mcp should eventually support npx -y @open-pets/mcp.
• @open-pets/cli should eventually support npx -y @open-pets/cli ....
• No v2 package should rely on Bun runtime APIs.

Workspace inclusion rule:

packages:
  - "apps/*"
  - "packages/*"

Do not include:

v1/**
web/**

The existing web/ app and v1/ references must remain outside v2 workspace commands.

Package privacy rules:

• Root package.json is private: true.
• apps/desktop is private: true.
• Skeleton packages should be private: true during Phase 00 unless there is a concrete reason to make one publishable immediately.
• Public package names may still be reserved in package metadata, but avoid accidental publication of empty packages.

Initial scripts should be simple and predictable, for example:

{
  "scripts": {
    "check": "pnpm -r check",
    "typecheck": "pnpm -r typecheck",
    "build": "pnpm -r build"
  }
}

Each initial package should expose minimal check, typecheck, and build scripts where practical.

Linting is deferred in Phase 00 unless it is trivial to add without expanding scope. TypeScript strictness is the initial code-quality gate.

Use TypeScript project configuration that can scale to multiple packages without making Phase 00 too complex.

Initial TypeScript/build convention:

• Use type: "module".
• Use strict TypeScript settings.
• Use moduleResolution appropriate for modern Node ESM.
• Emit to dist/.
• Generate declarations for packages where practical.
• Use source maps where practical.
• Avoid bundlers until a later phase requires them.

Recommended package intent:

• apps/desktop — Electron desktop app, implemented in later phases.
• packages/client — local IPC client, implemented in Phase 05.
• packages/mcp — MCP stdio server, implemented in Phase 06.
• packages/claude — Claude detection/configuration/hooks package, implemented in Phases 07–08.
• packages/cli — explicit user-run CLI commands, implemented after core app/client behavior exists.
• packages/pet-format — shared pet manifest/catalog validation types, used by pet manager/catalog install phases.

Deferred package:

• packages/shared — defer until a concrete shared constant/type exists. Do not create it in Phase 00 by default.

Electron app note:

• apps/desktop/src/main.ts is compile-only placeholder code in Phase 00.
• Do not add real tray behavior, renderer framework, Electron window code, or packaging setup in Phase 00.
• Avoid adding Electron/Vite/React dependencies until Phase 01 unless needed for a minimal compile check.

Risks and tradeoffs

Risk: too much empty scaffolding

Creating every planned package immediately may produce fake progress and maintenance overhead.

Mitigation:

• Keep package contents minimal.
• Add only enough for workspace checks and future package boundaries.
• Do not implement fake APIs before their phase.
• Defer packages/shared until needed.

Risk: pnpm confusion vs npm/npx requirement

The project may use pnpm for development while users need npm/npx compatibility.

Mitigation:

• Document the distinction clearly.
• Avoid pnpm-specific runtime assumptions.
• Keep package bin/publish behavior npm-compatible when those packages become real.

Risk: v1 assumptions leaking into v2

v1 is Bun-oriented and has known broken agent configuration flows.

Mitigation:

• Do not copy v1 structure blindly.
• Treat v1 as reference only.
• Re-check docs and design before implementing each real feature phase.

Risk: Phase 00 becomes abstract tooling work

Phase 00 should enable work, not become a tooling project.

Mitigation:

• Keep tooling minimal.
• Avoid CI/release/publishing complexity until later hardening phases.

Risk: v2 workspace accidentally runs v1 or web commands

The repository contains existing v1/ and web/ folders with their own tooling. Accidentally including them in pnpm workspaces would blur boundaries and may pull Bun-era assumptions into v2.

Mitigation:

• pnpm-workspace.yaml includes only apps/* and packages/*.
• v1/** and web/** remain outside v2 workspace commands.

Risk: accidental publish of skeleton packages

Early package skeletons should not be published before they are real.

Mitigation:

• Mark root, apps, and skeleton packages private: true in Phase 00.
• Revisit publish settings only in the phase where a package is ready for actual npm usage.

Security/privacy notes

This phase should not introduce network behavior, local IPC, config editing, pet zip extraction, or agent hooks.

Security/privacy expectations for this phase:

• No secrets or credentials are added.
• No telemetry is added.
• No install scripts should perform surprising system changes.
• No package should require postinstall behavior for core development.
• Skeleton packages should be private to prevent accidental empty-package publication.

Test/check plan

Automated checks:

pnpm install
pnpm check
pnpm typecheck
pnpm build

Expected result:

• Dependency install succeeds.
• TypeScript/workspace checks pass.
• Typecheck passes under the agreed Node/ESM/strict TypeScript settings.
• Initial package builds pass or intentionally no-op with clear scripts.

If package scripts are intentionally minimal, they should still be explicit and understandable.

Manual verification guide

After implementation, the user should verify:

1. Run dependency install:

   pnpm install
   

2. Run checks:

   pnpm check
   

3. Run typecheck:

   pnpm typecheck
   

4. Run build:

   pnpm build
   

5. Inspect that v2 code lives outside v1/:

   apps/desktop
   packages/client
   packages/mcp
   packages/claude
   packages/cli
   packages/pet-format
   

6. Confirm no Bun command is required for v2 checks/builds.

7. Confirm pnpm-workspace.yaml does not include v1/** or web/**.

Manual acceptance question:

Does Phase 00 pass on your machine: dependencies install, checks/typechecks/builds run, and the v2 workspace structure looks right?

Oracle plan review

Oracle reviewed the Phase 00 plan and approved it with required minor revisions before implementation.

Summary of Oracle feedback:

• Tighten workspace boundary so v2 workspace excludes v1/** and web/**.
• Define Node/tooling baseline.
• Protect skeleton packages from accidental publishing.
• Clarify scripts and build conventions.
• Avoid adding Electron implementation/dependencies too early.
• Defer packages/shared unless immediately needed.

Oracle feedback disposition

• Fixed: Added workspace inclusion/exclusion rule for apps/* and packages/*, excluding v1/** and web/**.
• Fixed: Added Node 20+, Corepack/pnpm, ESM, and plain TypeScript build baseline.
• Fixed: Added privacy rules for root/app/skeleton packages.
• Fixed: Added typecheck script expectation and deferred linting explicitly.
• Fixed: Added TypeScript/build convention notes.
• Fixed: Clarified apps/desktop/src/main.ts is compile-only placeholder and no tray/Electron implementation belongs in Phase 00.
• Fixed: Deferred packages/shared until concrete need exists.

Oracle implementation review

Oracle reviewed the implemented Phase 00 diff after successful validation with:

pnpm install && pnpm check && pnpm typecheck && pnpm build

Oracle found no blocking correctness, security, or spec issues and approved Phase 00 for manual user verification.

Implementation review disposition:

• Fixed: Updated stale docs/workflow.md current-action wording so the workflow document remains reusable across phases.
• Deferred: README Corepack guidance can be expanded later if needed; root packageManager already pins pnpm.
• Deferred: Package script/tsconfig simplifications can be revisited if they become maintenance overhead.