Files
worldwideview/AGENTS.md
Silvertakana 9a5adb832e docs(rules): seeder authoring contract + close-context-gaps meta-directive (#240)
* docs(rules): add seeder authoring contract to data-engine-architecture rule

Adds section 8 documenting how to write a seeder: the auto-discovery model,
the three module shapes (interval+fetch, cron+fn, init), the { redis }-only
ctx, and publishing via @worldwideview/seeder-sdk. Includes good/bad examples
contrasting the ctx.setLiveSnapshot trap (which caused a silent CI failure)
against the two correct shapes. This rule auto-loads on local-seeders/** edits.

* docs(rules): add close-context-gaps AI meta-directive to AGENTS.md

When missing/wrong/undocumented context causes an error, a long struggle, or
slow understanding, agents must fix the doc/context (or add a guardrail) at its
source, or ask the user to; in autonomous mode, log the gap to revisit. Codifies
the lesson from the seeder ctx.setLiveSnapshot incident for all contributors.
2026-06-05 00:25:44 +12:00

9.4 KiB

WorldWideView — Agent Rules

1. Project Identity

WorldWideView is a real-time geospatial intelligence engine visualizing live global data on an interactive 3D globe. Built with Next.js 16, CesiumJS, React 19, and Zustand. Design/feature target: www.worldmonitor.app (reference repo).


2. Tech Stack

Layer Technology
Framework Next.js 16 (App Router, output: "standalone")
Language TypeScript 5, strict mode
3D Engine CesiumJS + Resium (Google Photorealistic 3D Tiles)
State Zustand (9 slices: globe, layers, timeline, ui, filter, data, config, favorites, geojson)
Event Bus Custom typed DataBus (pub/sub singleton)
Styling Vanilla CSS — no Tailwind
Database PostgreSQL via Prisma 7
Auth NextAuth v5 beta (Credentials provider, JWT sessions)
Package Manager pnpm (monorepo with pnpm-workspace.yaml)
Testing Vitest + jsdom + React Testing Library
Deployment Docker multi-stage build → Coolify

3. Critical Invariants

Agents MUST respect these at all times:

  • Plugin source of truth: @worldwideview/wwv-plugin-sdk — never define plugin types locally.
  • All-Bundle Model: every plugin is dynamically imported via loadPluginFromManifest using import(/* webpackIgnore: true */ entry). Legacy StaticDataPlugin / DeclarativePlugin runtimes are deprecated.
  • Agnostic frontend: each plugin MUST declare its own streamUrl; do not assume one shared pipe.
  • Nine Zustand slices under src/core/state/: access via useStore in React, useStore.getState() elsewhere.
  • Primitive-based rendering: Point/Billboard/Label/Polyline collections only. Never mix size/outlineWidth/outlineColor onto billboard entities — GPU silently clips.
  • Three editions via NEXT_PUBLIC_WWV_EDITION (local / cloud / demo); feature flags in src/core/edition.ts.
  • Nested git clones: local-plugins/ (community plugins) and local-seeders/community/ + local-seeders/private/ (seeders) are independent git repos cloned inside this repo, gitignored from it. Each has its own remote. Run git pull inside each before editing; commits/pushes there go to their own upstream — not to worldwideview. See .agents/context/ecosystem-repositories.md.

4. Conventions

  • File size: ~300 lines max. Extract helpers, split components, use hooks.
  • Import aliases: @/* → ./src/*; @worldwideview/wwv-plugin-sdk → ./packages/wwv-plugin-sdk/src
  • CSS: Vanilla CSS only. Global: src/app/globals.css. Scoped: CSS Modules. HUD: src/styles/hud-animations.css.
  • Rendering entities: Points use type: "point" + size/outlineColor/outlineWidth. Billboards use type: "billboard" + iconUrl/iconScale. NEVER mix.
  • Plugin registration: Built-ins via AppShell.tsx → PluginRegistry → PluginManager. Marketplace plugins via InstalledPluginsLoader.
  • Workspace: Use "workspace:*" (not "*") for internal deps. New packages/ plugins need transpilePackages in next.config.ts.
  • Temp files: Save debugging scripts/outputs exclusively in /local-scripts/ — never in root.
  • Cleanliness: Remove dead code, unused imports, debug console.log before finalising. Never use any or @ts-ignore. Never create .mdc files.

5. AI Meta-Directives

Warning

  • Always use .md extensions. Never .mdc. Never reference Cursor IDE rules.
  • MUST bump semver in package.json before every commit via /commit workflow (feat: → Minor, fix/refactor/perf: → Patch).
  • MUST explain complex concepts simply — include an everyday-life analogy.
  • MUST require explicit user authorization before any state-changing action that isn't simple/safe.
  • MUST ask clarifying questions rather than assume when requirements are unclear.
  • MUST update .agents/rules/ files immediately whenever an architectural shift invalidates them.
  • MUST close context gaps: when missing/wrong/undocumented context made you err, struggle, or go slow, fix the relevant doc/context (or add a type/guardrail) at its source — or ask the user to update it when it depends on their knowledge. In autonomous mode, log the gap to revisit later. Never fix only the symptom and leave the trap armed for the next contributor.

6. Environment & Configuration

See .agents/context/environment-config.md for required environment variables and secrets.


7. Development & Deployment

pnpm dev          # Frontend only (auto-runs prisma db push + copy-cesium)
pnpm dev:all      # Frontend + data engine via Docker Compose
pnpm build        # Production build
pnpm test         # Vitest
pnpm db:reset     # Wipe + re-migrate DB (destructive)

See .agents/context/ → [deployment and testing details in .agents/rules/deployment-and-testing.md] for Docker architecture, Coolify rules, and CSP headers.


8. On-Demand Rules (path-scoped, auto-load on file access)

These load automatically when you read/edit files matching their paths:

Rule Triggers on
.agents/rules/cesium-rendering.md src/core/globe/**, src/plugins/**, packages/wwv-plugin-*/src/**
.agents/rules/state-management.md src/core/state/**, src/components/**
.agents/rules/plugin-architecture.md src/core/plugins/**, packages/wwv-plugin-*/src/**, local-plugins/**
.agents/rules/marketplace-architecture.md src/lib/marketplace/**, src/app/api/marketplace/**
.agents/rules/cloud-auth-architecture.md src/lib/auth*, src/app/api/auth/**, src/core/auth.ts
.agents/rules/database-migrations.md prisma/**
.agents/rules/monorepo-workflow.md packages/**, pnpm-workspace.yaml, local-plugins/**
.agents/rules/data-engine-architecture.md packages/**, local-seeders/**, docker-compose.yml
.agents/rules/deployment-and-testing.md Dockerfile, docker-compose.yml, .github/**, next.config.ts
.agents/rules/e2e-testing.md tests/**, public/e2e-fixtures/**, playwright.config.ts

9. On-Demand Context (read explicitly when needed)

See .agents/context/INDEX.md for the full navigation table. Key files:

When to read File
Product vision, business model, Edition system .agents/context/platform-architecture.md
Finding files, repo layout .agents/context/directory-structure.md
Routing fix to correct repository .agents/context/ecosystem-repositories.md
Next.js, data pipeline, Redis, DB schema .agents/context/application-architecture.md
Debugging plugin data, namespace collisions .agents/context/troubleshooting-and-debugging.md
SSH, Coolify MCP .agents/context/server-management.md
Coding principles, Definition of Done .agents/context/coding-principles.md
.env variables and secrets .agents/context/environment-config.md

10. Slash Commands

Command Description File
/commit Required before every commit — bump semver + conventional commit .agents/skills/commit/SKILL.md
/remember Save a lesson or fact into permanent memory .agents/skills/remember/SKILL.md
/pr-review 6-role comprehensive pull request review .agents/skills/pr-review/SKILL.md
/local-dev Check, start, troubleshoot local dev environment .agents/workflows/local-dev.md
/data-engine-cli Use the wwv-data-engine CLI wrapper .agents/workflows/data-engine-cli.md
/debugging-coolify Troubleshoot deployed apps on Coolify via MCP/SSH .agents/workflows/debugging-coolify.md
/five Five Whys root cause analysis .agents/workflows/five.md
/stitch-to-nextjs Generate UI with Stitch MCP, port into Next.js .agents/workflows/stitch-to-nextjs.md
/branch-cleanup Post-merge teardown — commit leftovers, delete plan file, remove worktree via worktree-manager .agents/skills/branch-cleanup/SKILL.md
/triage-issue Triage a single issue (plugin/feature/bug/question) per TRIAGE.md; confirm before any state change .agents/workflows/triage-issue.md

11. Agent Skills Reference

Skill When to Use
worldwideview-plugin-creation Use when creating any plugin — strict architectural checklist
plugin-creation-master-guide.md Decision matrix for choosing plugin architecture
osm-static-plugin-creation.md Creating static GeoJSON plugins from OpenStreetMap
database-operations.md Prisma schema changes, migrations, database queries
database-incident-recovery-procedures.md Safely restoring a broken production database

52 global skills available. See .agents/global-skills-index.md.


12. Pull Request & Commit Guidelines

  • Commit format: Conventional Commits (feat:, fix:, refactor:, perf:). Use /commit workflow.
  • Required checks: pnpm test and pnpm build must pass before merge.
  • Review: Use /pr-review for comprehensive multi-role review.
  • Worktrees: Use git-wt switch --create <branch> and git-wt remove (never rm -rf a worktree — orphans the PostgreSQL Docker volume). After a PR merges, use /branch-cleanup to commit leftovers, delete the plan file, and remove the worktree in one flow.

Hard Rule

Always interface-based, extensible, composable, modular. Never band-aids on band-aids.

Read .agents/context/coding-principles.md before any non-trivial code change.