AI Agents Guide

This guide provides comprehensive instructions for AI agents (Claude, Amazon Q, Cursor, etc.) working on the Global Watch codebase. Following these guidelines ensures consistent, high-quality contributions.

Quick Start

Before starting any work on Global Watch:

Read this guide completely (5 minutes)
Read the RITO Methodology section below
Understand the Absolute Laws - Zero tolerance rules
Check Makerkit documentation for the relevant feature

Starting work without reading documentation will result in rejected contributions.

The 7 Absolute Laws

These rules have zero tolerance - violations result in immediate rejection.

Law #1: Makerkit Standards are Sacred

Always follow Makerkit patterns exactly.

Before coding anything:

Read Makerkit docs: makerkit.dev/docs/next-supabase-turbo
Check the official repo: github.com/makerkit/next-supabase-saas-kit-turbo
Copy patterns exactly as documented
Never "improve" or "simplify" Makerkit patterns

-- ✅ CORRECT - Makerkit pattern
CREATE POLICY "team_access" ON projects
  FOR ALL USING (
    has_role_on_account(account_id)
  );

-- ❌ WRONG - Custom pattern
CREATE POLICY "team_access" ON projects
  FOR ALL USING (
    account_id IN (
      SELECT account_id FROM accounts_memberships
      WHERE user_id = auth.uid()
    )
  );

Law #2: TDD is Mandatory

Tests BEFORE code. Always. No exceptions.

Follow the RED → GREEN → REFACTOR cycle:

# 1. RED: Write failing test
pnpm test  # Must see FAIL

# 2. GREEN: Minimal code to pass
pnpm test  # Must see PASS

# 3. REFACTOR: Clean up
pnpm test  # Must stay PASS

Coverage requirements:

70% minimum overall
90%+ for critical components
Test business logic and edge cases

Law #3: TypeScript Type Safety

NO any types without explicit justification.

// ❌ WRONG
const data: any = getData();

// ✅ CORRECT - Library types
import type { GeoJSONSource } from 'mapbox-gl';
const source = map.getSource('id') as GeoJSONSource;

// ✅ CORRECT - Database types
import type { Database } from '~/lib/database.types';
type ProjectRow = Database['public']['Tables']['projects']['Row'];

// ✅ CORRECT - Unknown + type guard
function process(data: unknown) {
  if (typeof data === 'object' && data !== null) {
    // Type-safe processing
  }
}

Law #4: Environment Variables for URLs

NO hardcoded URLs.

// ❌ WRONG
const url = 'http://localhost:3000/auth/callback';
const origin = window.location.origin;

// ✅ CORRECT
const url = process.env.NEXT_PUBLIC_APP_URL + '/auth/callback';
const origin = process.env.NEXT_PUBLIC_APP_URL;

Law #5: Workspace Boundaries

Stay in your assigned workspace.

Working in apps/web/? → Stay in apps/web/
Working in packages/fw/? → Stay in packages/fw/

Before modifying files outside your workspace:

STOP - Don't proceed
ANALYZE - Why is this needed?
ASK - Wait for approval

Law #6: Centralized Configuration

NO magic numbers or strings.

// ❌ WRONG - Magic numbers
if (slug.length < 3 || slug.length > 32) {
  throw new Error('Invalid slug');
}

// ✅ CORRECT - Config file
import { SLUG_CONFIG } from '~/config';
if (slug.length < SLUG_CONFIG.MIN_LENGTH) {
  throw new Error('Slug too short');
}

Law #7: Security by Default

RLS, Auth, Encryption ALWAYS enabled.

-- ✅ ALWAYS enable RLS
CREATE TABLE my_table (...);
ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;

-- ✅ ALWAYS create policy
CREATE POLICY "access_policy" ON my_table
  FOR ALL USING (has_role_on_account(account_id));

RITO Methodology

RITO (Registro, Investimento, Tarefas, Orçamento) is the development methodology for Global Watch.

RITO v2: Lean Approach

Level	Feature Type	Documentation	Overhead
1	UI Component, Utility, Bug Fix	None (Context Manager captures)	5min
2	API Endpoint, DB Table, Integration	Task file	15min
3	Auth Flow, Billing, PII Handling	Task + ADR	30min

Level 1: Simple Features (90% of cases)

# 1. TDD (RED → GREEN → REFACTOR)
pnpm test  # See fail
# ... code ...
pnpm test  # See pass

# 2. Verify
pnpm typecheck
pnpm lint

# 3. Commit
git commit -m "feat: add export button

✅ Tests: 5/5 passing
⏱️ Time: 30min"

Level 2: Medium Features (9% of cases)

# 1. Quick Plan (5min)
echo "## Task: Create Project API
- RLS: Yes
- Auth: Required
- Tests: Unit + E2E" > TASK-123.md

# 2. TDD + Security
pnpm test  # TDD cycle

# 3. Commit Auditable
git commit -m "feat(api): create project endpoint

✅ Verified:
- Tests: 12/12 passing
- RLS: Verified

⏱️ Time: 1h 20min"

Level 3: Critical Features (1% of cases)

For Auth, Billing, or PII handling:

Create Impact Assessment
TDD + Security + Privacy verification
Create ADR (Architecture Decision Record)
Full compliance commit

Package Conventions

@kit vs @fw Packages

Namespace	Purpose	Modify?
`@kit/*`	Makerkit base packages	❌ Never
`@fw/*`	Global Watch custom packages	✅ Yes

// ✅ CORRECT - Our custom code
import { PasswordInput } from '@fw/ui/password-input';
import { EntitySettings } from '@fw/entity-settings';

// ❌ WRONG - Don't create in @kit
import { MyCustom } from '@kit/ui/my-custom';

When to Create @fw Package

✅ New universal component
✅ Refactoring existing code for reuse
✅ Global Watch-specific feature
✅ Custom utility/helper

Pre-Commit Checklist

Before any commit, verify:

Code Quality

pnpm typecheck      # No TypeScript errors
pnpm lint:fix       # No lint errors
pnpm format:fix     # Code formatted
pnpm --filter [app] build  # Build succeeds

Tests

pnpm --filter [package] test:run  # All tests pass
# Coverage ≥ 70%

Manual Verification

Feature works in browser
No console errors
No regressions

Commit Message Format

type(scope): Brief description

[Detailed description]

✅ Verified:
- Tests: X/X passing
- TypeCheck: No errors
- Lint: No errors

⏱️ Time: Xh XXmin

Types:

feat - New feature
fix - Bug fix
docs - Documentation
refactor - Code refactoring
test - Adding tests
chore - Maintenance

Multi-Agent Collaboration

When multiple AI agents work on the project:

Track System

Each agent works in an isolated track:

# Create track
pnpm track:create amazon-q-ui "Amazon Q" "UI components"

# Switch track
pnpm track:switch amazon-q-ui
pnpm context:restart  # Required after switch

# Check current track
pnpm track:current

Best Practices

One track per agent - Avoid conflicts
Always restart after switching - pnpm context:restart
Descriptive names - Identify agent and work
Save before switching - pnpm context:save

Feature Flags

Check feature flag status before implementing:

Flag	Default	Description
`enableTeamAccounts`	✅ true	Team accounts
`enableNotifications`	✅ true	Notifications
`enableWorkOrders`	✅ true	Work orders
`enableAccountDeletion`	❌ false	Account deletion
`enableBilling`	❌ false	Billing features

Rule: Don't implement features for disabled flags without approval.

Troubleshooting

Common Issues

Port already in use:

lsof -i :3000
kill -9 <PID>

Supabase not starting:

docker ps  # Check Docker
pnpm supabase:web:stop
pnpm supabase:web:start

Type errors after schema changes:

pnpm supabase:web:typegen
# Restart TypeScript server in IDE

Getting Help

When stuck:

Re-read this guide
Check Makerkit documentation
Search existing code for patterns
ASK before proceeding with uncertainty

Never improvise. Always ask when in doubt.

Development Setup - Environment configuration
Coding Conventions - Code standards
Testing Overview - Testing strategies
Architecture - System design

AI Agents Guide

On this page