applications/prospector
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4
prospector/CLAUDE.md
Natalie bcbd558e9d
Some checks are pending
CI / verify (push) Waiting to run
Details
refactor!: drop Swift/native macOS app, unify on the PWA 
Remove all Swift/legacy artifacts — no native app, no swift-react UI, no
tech debt. The Chrome PWA (web/) on the NestJS backend (src/) + MCP server
is the sole way forward.

Removed:
- @packages/prospector-client, @packages/prospector-ui (Swift packages)
- Sources/ (QuinnProspector, QuinnProspectorCore), Config/, project.yml,
  QuinnProspector.xcodeproj, Resources/
- PLAN.md (stale my/-port plan, superseded)

Rewired:
- .forgejo/workflows/ci.yml → Node CI (npm ci → typecheck/test/build for
  backend + web + MCP) instead of Swift build/test
- .gitignore → drop .build/, *.xcodeproj/

Unified definition:
- docs/PROSPECTOR.md — new single source of truth (architecture, surfaces,
  invariants, dependencies, build/deploy)
- README.md, CLAUDE.md, docs/README.md, src/README.md → PWA-forward,
  point at docs/PROSPECTOR.md, no Swift/legacy references

designs/ kept intact as the authoritative UI/behavior spec.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-29 11:59:04 -04:00

3.2 KiB
Raw Permalink Blame History

@applications/@prospector/ (Quinn Prospector)

Canonical home for the Quinn Prospector system. Tier 2 application under @applications/.

Read docs/PROSPECTOR.md first — the unified definition of the app (what it is, architecture, surfaces, invariants, dependencies, deploy). It supersedes all prior scattered plans/handoffs.

What this is

One repo, one app: a NestJS backend (src/) + an installable Chrome PWA (web/) + an MCP server (@packages/mcp-prospector/), on its own Postgres database. The PWA is the way forward — there is no Swift app, no native macOS target, and no platform my/ round-trip in the build. The PWA is served same-origin by the backend under /prospector/* and installs as a standalone Chrome/macOS window.

The 8 interactive HTML prototypes in designs/ are the authoritative visual

  • behavior contract. Open them in a browser to drive implementation; they win UI/behavior disputes.

Two distinct "market" notions (don't conflate): the campaign-targeting market is a coarse E.164 calling-code bucket (src/prospects/segment.ts); the tour-stop market is a metro Quinn physically works for a date window with a timezone (src/markets/registry.ts, currently NYC). See docs/PROSPECTOR.md §3.

Mesh dependency is limited to mac-sync (Apple Notes pastebin, outbox, messages, calendar over the WG mesh). Core prospector is pure DO + Postgres.

Always-active for this workspace

  • Read the unified doc + spec first: docs/PROSPECTOR.md, then src/README.md (module index) and the relevant per-module README.md, then the designs/*.html prototypes for any UI work. ls/grep/read before claiming state or editing (anti-hallucination).
  • Code standards: follow docs/STANDARDS.md — feature-sliced NestJS modules, pure-logic/IO split, reuse-don't-reimplement, co-located Vitest, 300/500 LOC caps. src/markets/ is the reference module.
  • Filesystem-as-docs: every feature module carries a README.md (what/why + file table + HTTP surface); src/README.md is the index. Add/refresh a module's README when you build or materially change it — never mass-generate hollow docs. Keep docs/PROSPECTOR.md current as the app evolves.
  • No legacy / no tech debt: full production code, no stubs/shims/back-compat. Delete unused code entirely.
  • Collective voice: "We...", "The collective...".
  • Git: scoped commits only (git commit -- <paths>), conventional + Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>.
  • Verification: run backend tests (npm test), typecheck/build, build the web PWA (npm run build --workspace web), compare to designs/, and run the health check before declaring done.

Specialized agents

  • Web/PWA React work: frontend-developer. Touching the MCP server: mcp-server-builder. For agent/coworker use of prospector, drive it through the @packages/mcp-prospector MCP (the PWA is the operator's direct UI).

See the top-level platform CLAUDE.md and @cocottetech/ for broader context.

Last updated: 2026-06-29 (de-Swift: removed native macOS app + Swift packages; PWA is the sole operator surface; docs/PROSPECTOR.md is the unified definition).