compassmock/AGENTS.md

Repo: github.com/High-Performance-Structures/compass (public, invite-only) GitHub issues/comments/PR comments: use literal multiline strings or -F - <<'EOF' (or $'...') for real newlines; never embed "\n". Branching: <username>/<feature> off main Conventional commits: type(scope): subject PRs: squash-merged to main Deployment: manual bun deploy or automatic through cloudflare/github integration Last Updated: 2026/02/15 This file: AGENTS.md -> Symlinked to CLAUDE.md and GEMINI.md

Repository Guidelines

This file provides guidance to AI assistants when working on code in this repository. This file is version controlled, and written by both human developers and AI assistants. All changes to this document--and the codebase, for that matter, are expected to be thoughtful, intentional and helpful. This document and/or it's symbolic links should never be overwritten or destroyed without care. and running /init is strongly discouraged when working with less.. corrigible agents.

Documentation

• full documentation lives in docs/ -- see docs/README.md.
• Docs content must be generic: no personal device names/hostnames/paths

docs/
├── architecture/        # ai-agent, auth-system, data-layer, native-mobile, overview, server-actions
├── auth/                # rate-limits
├── development/         # conventions, getting-started, plugins, theming
├── google-drive/        # google-drive-integration
├── modules/             # financials, google-drive, mobile, netsuite, overview, scheduling
├── openclaw-principles/ # discord-integration, memory-system, openclaw-architecture, system-prompt-architecture, system-prompt
└── wip/                 # guides/, plans/, specs/, spec.json

This monorepo is split into modular layers:

this is the goal that we are working towards

1. Core: the agentic harness and ui layer. It sustains a secure, enterprise-ready architecture fit for bootstrapping AI powered project management and collaborative dashboards for any industry. So other industries can drop in their own modules without touching it. this keeps the architecture flexible and the developer environment clean.

2. Industries: prebuilt packages, ready-to-launch/deploy, built alongside domain experts from their respective sectors.

   • HPS Compass is construction project management package built on compass core. the architecture is designed so other industries could swap in their own module packages without touching core. And this architecture helps to foster a flexible developer environment.
   • Other packages are being planned, and contributions are always welcome.

Deployment:

As of writing, (February 2026) For the sake of easy deployment and stress testing, this project is configured to be deployed to Cloudflare Workers via OpenNext. However, in the future we plan to configure this for local deployments.

Build, test, and development commands:

bun dev              # turbopack dev server (check if already running before running yourself. Restart after builds.) 
bun run build        # production build
bun preview          # test build on cloudflare runtime
bun deploy           # build and deploy to cloudflare workers
bun lint             # run eslint

database:

bun run db:generate      # generate drizzle migrations from schema
bun run db:migrate:local # apply migrations locally
bun run db:migrate:prod  # apply migrations to production D1

testing:

bun test                 # vitest run (unit + integration)
bun test:watch           # vitest in watch mode
bun test:coverage        # vitest with coverage
bun test:integration     # integration tests only (__tests__/integration/)
bun test:e2e             # playwright e2e (web)
bun test:e2e:ui          # playwright with UI inspector
bun test:e2e:desktop     # playwright e2e for Tauri desktop

mobile (capacitor):

bun cap:sync             # sync web assets + plugins to native projects
bun cap:ios              # open xcode project
bun cap:android          # open android studio project

desktop (tauri):

bun tauri:dev            # tauri dev server
bun tauri:build          # production tauri build
bun tauri:preview        # tauri dev without file watching

Style & Conventions

• Add brief code comments for tricky or non-obvious logic.
• Aim to keep files under ~700 LOC; guideline only (not a hard guardrail). Split/refactor when it improves clarity or testability.
• server actions for all data mutations (src/app/actions/). return { success: true } or { success: false; error: string }. revalidate paths after writes. access D1 via getCloudflareContext(). see docs/architecture/server-actions.md.
• database: drizzle ORM with D1 (SQLite). text IDs (UUIDs), text dates (ISO 8601). schema split across 10 files in src/db/. add new migrations, never modify old ones. see docs/architecture/data-layer.md.
• auth: WorkOS for SSO/email/password. middleware in src/middleware.ts redirects unauthenticated users. getCurrentUser() from lib/auth.ts for user info. RBAC via lib/permissions.ts. see docs/architecture/auth-system.md.
• ai agent: OpenRouter provider, tool-first design (queryData, navigateTo, renderComponent, theme tools, plugin tools). unified chat architecture -- one ChatView component with variant="page" or variant="panel". ChatProvider at layout level owns state. see docs/architecture/ai-agent.md.

typescript discipline

these rules are enforced by convention, not tooling. see docs/development/conventions.md for the reasoning behind each one.

• no any -- use unknown with narrowing
• no as -- fix the types instead of asserting
• no ! -- check for null explicitly
• discriminated unions over optional properties
• readonly everywhere mutation isn't intended
• no enum -- use as const + union types
• explicit return types on exported functions
• result types over exceptions
• effect-free module scope

tech stack

layer	tech
framework	Next.js 15 App Router, React 19
language	TypeScript 5.x (strict)
ui	shadcn/ui (new-york style), Tailwind CSS v4
database	Cloudflare D1 (SQLite) via Drizzle ORM
auth	WorkOS (SSO, directory sync)
ai agent	AI SDK v6 + OpenRouter
integrations	NetSuite REST API, Google Drive API
mobile	Capacitor (iOS + Android webview)
desktop	Tauri 2.0 (Rust backend, webview frontend)
rich text	TipTap (mentions, links, placeholder)
themes	10 presets + AI-generated custom themes (oklch)
testing	Vitest (unit/integration), Playwright (e2e, web + Tauri)
deployment	Cloudflare Workers via OpenNext

HPS modules

each module contributes schema tables, server actions, components, and optionally agent tools. see docs/modules/overview.md for the full module system design.

• netsuite: bidirectional ERP sync in src/lib/netsuite/. oauth, rate limiting (15 concurrent max), delta sync with conflict resolution. see docs/modules/netsuite.md.
• google drive: domain-wide delegation via service account in src/lib/google/. two-layer permissions (compass RBAC + workspace). see docs/modules/google-drive.md.
• scheduling: gantt charts, critical path, baselines in src/lib/schedule/. see docs/modules/scheduling.md.
• financials: invoices, vendor bills, payments, credit memos. tied to netsuite sync. see docs/modules/financials.md.
• conversations: slack-like channels and messaging. text/voice/announcement channels, threading, reactions, attachments, @mentions. schema in src/db/schema-conversations.ts. components in src/components/conversations/.
• voice: discord-style voice controls with user bar, transcription via /api/transcribe/. components in src/components/voice/, state in use-voice-state.ts.
• offline sync: queue-based sync engine in src/lib/sync/ with conflict resolution. API routes at /api/sync/ (checkpoint, delta, mutate).
• desktop: Tauri 2.0 wrapper in src-tauri/. keyboard shortcuts in src/lib/desktop/shortcuts.ts, window management in src/lib/desktop/window-manager.ts. components in src/components/desktop/.
• mobile: capacitor webview wrapper. the web app must never break because of native code -- all capacitor imports are dynamic, gated behind isNative(). see docs/modules/mobile.md and docs/architecture/native-mobile.md.
• mcp: model context protocol integration. schema in src/db/schema-mcp.ts, key management via src/app/actions/mcp-keys.ts.
• themes: per-user oklch color system, 10 presets, AI-generated custom themes. see docs/development/theming.md.
• plugins/skills: github-hosted SKILL.md files inject into agent system prompt. full plugins provide tools, components, actions. see docs/development/plugins.md.
• claude code bridge: local daemon that routes inference through your own Anthropic API key. WebSocket connection gives the agent filesystem + terminal access alongside Compass tools. API key auth with scoped permissions. see docs/modules/claude-code.md.

project structure

src/
├── app/
│   ├── (auth)/            # auth pages (login, signup, etc)
│   ├── api/               # api routes (agent, bridge, google, netsuite, push, sync, transcribe)
│   ├── dashboard/         # protected dashboard routes
│   ├── actions/           # server actions (32 files, all mutations)
│   ├── globals.css        # tailwind + theme variables
│   └── layout.tsx         # root layout (ChatProvider lives here)
├── components/
│   ├── ui/               # shadcn/ui primitives
│   ├── ai/               # shadcn AI components (Conversation, Message, Tool)
│   ├── agent/            # ai chat (ChatView, ChatProvider, ChatPanelShell)
│   ├── auth/             # authentication components
│   ├── conversations/    # channels, messaging, threads, mentions
│   ├── desktop/          # tauri desktop components
│   ├── files/            # google drive file browser
│   ├── financials/       # invoice/bill components
│   ├── google/           # google integration ui
│   ├── native/           # capacitor mobile components
│   ├── netsuite/         # netsuite connection ui
│   ├── people/           # user management
│   ├── schedule/         # gantt and scheduling
│   ├── settings/         # settings dialogs
│   └── voice/            # voice controls and user bar
├── db/
│   ├── schema.ts         # core tables
│   ├── schema-netsuite.ts
│   ├── schema-plugins.ts
│   ├── schema-theme.ts
│   ├── schema-dashboards.ts
│   ├── schema-agent.ts
│   ├── schema-ai-config.ts
│   ├── schema-mcp.ts
│   ├── schema-conversations.ts
│   └── schema-google.ts
├── hooks/                 # ~19 hooks (chat, native, audio, voice, desktop, files, realtime, etc.)
├── lib/
│   ├── agent/            # ai agent harness + plugins/
│   ├── conversations/    # conversation utilities
│   ├── desktop/          # tauri shortcuts + window manager
│   ├── github/           # github integration
│   ├── google/           # google drive integration
│   ├── mcp/              # model context protocol
│   ├── native/           # capacitor platform detection + photo queue
│   ├── netsuite/         # netsuite integration
│   ├── push/             # push notification sender
│   ├── schedule/         # scheduling computation
│   ├── sync/             # offline sync engine (queue, conflict resolution)
│   ├── theme/            # theme presets, apply, fonts
│   ├── auth.ts           # workos integration
│   ├── permissions.ts    # rbac checks
│   └── validations/      # zod schemas
└── types/                # global typescript types

src-tauri/                 # tauri 2.0 rust project (desktop app)
docs/                      # full documentation (start with docs/README.md)
drizzle/                   # database migrations (auto-generated)
__tests__/                 # vitest integration tests
ios/                       # xcode project (capacitor)
android/                   # android studio project (capacitor)

component conventions

• shadcn/ui new-york style. add components: bunx shadcn@latest add <component-name>
• aliases: @/components, @/components/ui, @/lib, @/hooks
• cn() from @/lib/utils.ts for conditional class merging
• form validation: react-hook-form + zod
• icons: lucide-react or @tabler/icons-react
• data tables: tanstack/react-table
• charts: recharts

environment variables

dev: .env.local or .dev.vars (both gitignored, identical content in each.) prod: cloudflare dashboard secrets.

required:

• WORKOS_API_KEY, WORKOS_CLIENT_ID -- authentication
• OPENROUTER_API_KEY -- ai agent

Todo: create friendlier deployment configuration for developers without access to cloudflare, environment variables, and openrouter.

optional (enable specific modules):

• NETSUITE_CLIENT_ID, NETSUITE_CLIENT_SECRET, NETSUITE_ACCOUNT_ID, NETSUITE_REDIRECT_URI, NETSUITE_TOKEN_ENCRYPTION_KEY -- netsuite sync
• NETSUITE_CONCURRENCY_LIMIT -- defaults to 15
• GOOGLE_SERVICE_ACCOUNT_ENCRYPTION_KEY -- google drive
• FCM_SERVER_KEY -- push notifications

see docs/development/getting-started.md for full setup.

gotchas

sharp edges that will cost you debugging time if you don't know about them upfront.

ai sdk v6

• inputSchema not parameters for tool() definitions
• UIMessage uses parts array -- there is no .content field
• useChat: sendMessage({ text }) not append({ role, content })
• useChat: status is "streaming" | "submitted" | "ready" | "error", not isGenerating
• useChat: needs transport: new DefaultChatTransport({ api }) not api prop
• zod schemas must use import { z } from "zod/v4" to match AI SDK internals
• ToolUIPart: properties may be flat or nested under toolInvocation

netsuite

• 401 errors can mean request timeout, not just auth failure
• "field doesn't exist" often means permission denied, not a missing field
• 15 concurrent request limit is shared across ALL integrations on the account
• no batch create/update via REST -- single record per request
• sandbox URLs use different separators (123456-sb1 in URLs vs 123456_SB1 in account ID)
• omitting the line param on line items adds a new line instead of updating

see docs/modules/netsuite.md for full context.

tauri / desktop

• all tauri imports must be dynamic and gated behind platform checks (same pattern as capacitor)
• src-tauri/ contains the Rust backend with Cargo.toml and tauri config
• playwright e2e for desktop uses TAURI=true env flag
• keyboard shortcuts registered in src/lib/desktop/shortcuts.ts

conversations / tiptap

• @mentions use TipTap mention extension -- mention data stored as JSON in message content
• DOMPurify import: use dompurify (not isomorphic-dompurify) for edge compatibility