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/07 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

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

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 8 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.

TODO: Add testing suite

• 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)
themes	10 presets + AI-generated custom themes (oklch)
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.
• 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.
• 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.

project structure

src/
├── app/
│   ├── (auth)/            # auth pages (login, signup, etc)
│   ├── api/               # api routes (agent, push, netsuite, auth)
│   ├── dashboard/         # protected dashboard routes
│   ├── actions/           # server actions (25 files, all mutations)
│   ├── globals.css        # tailwind + theme variables
│   └── layout.tsx         # root layout (ChatProvider lives here)
├── components/
│   ├── ui/               # shadcn/ui primitives
│   ├── agent/            # ai chat (ChatView, ChatProvider, ChatPanelShell)
│   ├── native/           # capacitor mobile components
│   ├── netsuite/         # netsuite connection ui
│   ├── files/            # google drive file browser
│   ├── financials/       # invoice/bill components
│   ├── schedule/         # gantt and scheduling
│   └── people/           # user management
├── 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-google.ts
├── hooks/                 # react hooks (chat, native, audio)
├── lib/
│   ├── agent/            # ai agent harness + plugins/
│   ├── google/           # google drive integration
│   ├── native/           # capacitor platform detection + photo queue
│   ├── netsuite/         # netsuite integration
│   ├── push/             # push notification sender
│   ├── schedule/         # scheduling computation
│   ├── theme/            # theme presets, apply, fonts
│   ├── auth.ts           # workos integration
│   ├── permissions.ts    # rbac checks
│   └── validations/      # zod schemas
└── types/                # global typescript types

docs/                      # full documentation (start with docs/README.md)
drizzle/                   # database migrations (auto-generated)
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.