feat(workspace): scaffold monorepo per workspace plan

[themightychris]

Implements plans/workspace.md — the foundational plan everything else in the DAG depends on. The PR grew well past its original scope: review-driven fixes, a CLAUDE.md relocation, a root README, and the first cut of a plan-closeout convention all landed here.

Original workspace scaffold

• npm workspaces at root (apps/*, packages/*), type: module, scripts for dev, build, type-check, lint. Node pinned to 22.22.3 via .tool-versions; engines.node belt + suspenders.
• apps/api — Fastify 5.8 boots on ${PORT:-3001} with a single /api/health route returning {"status":"ok"}. Pino-pretty in dev, JSON logs in prod. Under 20 lines per the plan.
• apps/web — Vite 8 + React 19 placeholder rendering "Hello, Code for Philly". Dev server proxies /api/* to :3001. resolve.dedupe: ['react', 'react-dom'] is the workaround for Vite 8 + npm-workspace-hoisted React (react/jsx-dev-runtime won't resolve without it).
• packages/shared — typed-module stub; Zod schemas land here when storage-foundation begins.
• Toolchain — tsconfig.base.json (strict + noUncheckedIndexedAccess), ESLint flat config (@eslint/js + typescript-eslint + react-hooks), .gitignore, .editorconfig.
• CI — .github/workflows/ci.yml runs actions/checkout@v6 → asdf-vm/actions/install@v4 (picks up .tool-versions) → npm ci → type-check → lint → build. Test step deferred to test-harness.

Review-driven fixes (PR #9 first review)

• .gitignore stopped ignoring fixtures/private-storage-seeded/ — that directory ships in the code repo per specs/behaviors/private-storage.md. Only the runtime ./private-storage/ is ignored.
• exactOptionalPropertyTypes: false removed from tsconfig.base.json — it's not part of strict, so the explicit false was a no-op that implied intent without explanation.

Documentation and structural housekeeping

• CLAUDE.md moved to .claude/CLAUDE.md. Both locations are valid Claude Code project-scoped configs; collocating with .claude/agents/ and .claude/commands/ keeps Claude-specific config in one directory. Internal relative paths rewritten; three cross-file references (plans/README.md, plans/workspace.md, specs/architecture.md) updated.
• Root README.md added — short, pointer-focused landing page (recommended in the review).

Plan-closeout convention established

This PR is the first to ship using the new convention, and the convention itself was hammered out during the PR:

• The last commit before merge updates the plan being implemented: frontmatter to status: done + pr: <n>, validation checkboxes ticked for verified criteria, Notes populated with non-actionable carry-forwards (learnings, decisions, gotchas), Follow-ups populated with actionable items not shipped.
• Follow-ups entry shapes: Issue [#N](link) for actionable + un-owned work, Deferred to <plan> for actionable + already-owned-by-a-downstream-plan, Tracked as: <pointer> for free-form, or None. explicitly.
• Deferrals must be absorbed: a Deferred to <plan> entry is only valid when the downstream plan is still planned, AND the same closeout commit must edit that downstream plan to actually pick up the work (typically a new Approach bullet + Validation criterion). If the downstream plan is in-progress or done, file an issue instead. Demonstrated by the .env.example deferral from this plan being absorbed into plans/api-skeleton.md.
• plans/README.md slimmed down: the status table and ASCII DAG were both deleted as redundant with per-plan frontmatter (status: and depends:) and rot-prone. The README now points readers at the per-plan files and provides grep recipes.

Validation against plans/workspace.md

All eight criteria re-verified against the final branch HEAD just before the closeout commit (ffbffe2):

• git clone … && npm install && npm run dev works on a fresh machine with only asdf preinstalled — verified locally and via three successful CI runs
• curl localhost:3001/api/health returns {"status":"ok"}
• The web dev server serves the placeholder page at http://localhost:5173/ — verified via chrome-devtools-axi; rendered DOM shows <main><h1>Hello, Code for Philly</h1>…</main>
• npm run type-check exits 0
• npm run build produces apps/api/dist/ and apps/web/dist/
• .github/workflows/ci.yml passes on a clean push (three successful runs across the three pushes)
• package-lock.json is committed at root
• No .js files in apps/api/src/ or apps/web/src/

Commit map

23 atomic commits, roughly grouped:

• 648a280…6b5fdfd — scaffold (Node, root, api, web, shared, eslint, CI)
• 1c39c04 293f799 — first-review fixes (.gitignore, tsconfig)
• 0d3ac74 73c4f09 — CLAUDE.md relocation + root README
• d2d32b0 ffbffe2 — plan-closeout convention v1 + workspace done-flip
• 221805b 94e57ff 23d496d — convention refinement (drop status table + DAG, add Follow-ups, require absorption of deferrals)

Test plan

• CI green on all three pushes
• Fresh npm ci && npm run dev boots both servers on a clean clone
• curl localhost:3001/api/health returns expected JSON
• Browser at http://localhost:5173/ renders the placeholder

🤖 Generated with Claude Code

[themightychris]

Review

CI green; the scaffold matches plans/workspace.md cleanly. One fix worth taking before (or just after) merge, plus a couple of optional nits.

What's solid

• Layout matches the plan exactly. apps/api, apps/web, packages/shared. ESM-only across the board. Root tsconfig.base.json carries strict: true plus the smart-strict extras (noUncheckedIndexedAccess, noImplicitOverride, noFallthroughCasesInSwitch, verbatimModuleSyntax). Per-workspace tsconfigs scope module resolution correctly — NodeNext for apps/api, Bundler for apps/web.
• The API is ≤20 lines as the plan asked, and the listen-error path is handled correctly (app.log.error(err); process.exit(1)).
• vite.config.ts dedupe: ['react', 'react-dom'] is the right workaround for workspace-hoisted React; the PR body documents why.
• CI uses current actions — actions/checkout@v6, asdf-vm/actions/install@v4 — and the concurrency group with cancel-in-progress is a nice touch.
• engines.node belt + .tool-versions suspenders is a good combo.
• All 8 plan validation criteria are checked off, plus the extra DOM-render verification via chrome-devtools-axi.

One thing worth fixing

.gitignore ignores fixtures/private-storage-seeded/, but per specs/behaviors/private-storage.md that directory is meant to ship in the code repo — it's the seeded fake-data fixture devs can load against the filesystem backend:

the API uses STORAGE_BACKEND=filesystem against a local ./private-storage/ directory. Contributors either start empty (sign up via GitHub OAuth during dev) or load a fixture-seeded directory shipped at fixtures/private-storage-seeded/

The runtime ./private-storage/ dir should be ignored. The fixture should NOT be. Two-line fix:

 # Dev private storage (filesystem backend; see specs/behaviors/private-storage.md)
 private-storage/
-fixtures/private-storage-seeded/

Not strictly blocking — the seeded fixtures don't exist yet (they'll land with storage-foundation), so nothing's currently being mis-ignored. But better to catch now than discover when the storage plan lands and git add fixtures/private-storage-seeded/ silently does nothing.

Nits (optional)

• No .env.example matching the !.env.example carve-out in .gitignore. Fine for now since no env vars are defined yet — natural follow-up when api-skeleton introduces EnvSchema.
• No root README.md. The plan didn't require it, but a 10-line "this is the CFP rewrite, see CLAUDE.md + specs/" would help a stranger arriving cold. Optional.
• exactOptionalPropertyTypes: false is explicit in tsconfig.base.json. It's the default under strict, so the explicit line documents a choice — worth a brief comment if the intent is to keep it off deliberately. Very minor.

Verdict

LGTM with the .gitignore change. Doesn't need to block merge if you'd rather fold it into the storage-foundation plan when that work lands — your call.

[themightychris]

Thanks for the review! Addressed both fixes; skipping the README/.env.example nits per the reviewer's "optional" framing.

Applied

• .gitignore — seeded fixture un-ignored (1c39c04). Dropped the fixtures/private-storage-seeded/ line and expanded the comment to make explicit which directory ships and which is runtime-only.
• tsconfig.base.json — redundant flag removed (293f799). exactOptionalPropertyTypes is opt-in, not part of strict, so the explicit false was a no-op that implied intent without explaining it. Removed rather than commented; if we later decide to enable EOP, that's its own intentional change with its own justification.

Deliberately skipped

• No .env.example file yet — agreed, no env vars are defined until api-skeleton introduces EnvSchema. The !.env.example carve-out in .gitignore is harmless and will be matched then.
• No root README.md — the plan didn't ask for one, and the global authoring rule is to not create READMEs unless explicitly requested. If we want a contributor-facing landing, happy to add it as a separate PR with intentional scope.

Type-check still clean; pushing now should re-trigger CI.