CD

Developer Tools & CI/CD

AI Agent Rules & IDE Syncing

Relevant source files

The following files were used as context for generating this wiki page:

• .agents/AGENTS.md (Content referenced as source of truth in CLAUDE.md)
• scripts/sync-agents.js
• CLAUDE.md
• .windsurfrules
• README.md
• .github/workflows/agents-sync-check.yml (Reference to CI workflow in sync script comments)

AI Agent Rules & IDE Syncing

Introduction

The Colabs project implements a sophisticated "Single Source of Truth" (SSOT) architecture for managing AI agent instructions and IDE configurations. As modern development increasingly relies on AI assistants (Claude Code, GitHub Copilot, Cursor, Windsurf), maintaining consistent coding standards, security rules, and project mental models across different tools becomes critical. This system ensures that all AI assistants operating within the repository adhere to the same technical constraints and architectural patterns.

The core of this system is located in .agents/AGENTS.md, which serves as the master document. A dedicated Node.js synchronization script (scripts/sync-agents.js) parses this master file and propagates relevant sections into various IDE-specific "adapter" files. This automation prevents documentation drift and ensures that security-critical rules—such as Row Level Security (RLS) enforcement and secret management—are consistently presented to every AI agent.

Sources: CLAUDE.md:6-12, scripts/sync-agents.js:4-15

System Architecture

Synchronization Workflow

The synchronization process is a one-way flow from the master Markdown file to multiple target adapters. The sync-agents.js script identifies specific H2 sections within the source file and maps them to target files based on the requirements of the specific IDE.

flowchart TD
    Master[.agents/AGENTS.md] -- "npm run sync-agents" --> Script[scripts/sync-agents.js]
    Script --> C1[CLAUDE.md]
    Script --> C2[.github/copilot-instructions.md]
    Script --> C3[.windsurfrules]
    Script --> C4[.cursor/rules/*.mdc]
    Script --> C5[.agents/rules/context.md]
    
    subgraph "IDE Adapters"
    C1
    C2
    C3
    C4
    end
    
    subgraph "Internal Documentation"
    C5
    end

Loading

The diagram above shows the distribution of rules from the master file to various IDE-specific adapter files and internal context hubs. Sources: scripts/sync-agents.js:77-180

Key Components

Component	Path	Description
Master Source	.agents/AGENTS.md	The authoritative source for all project identities, mental models, and code rules.
Sync Engine	scripts/sync-agents.js	Node.js script using fs and crypto to parse sections and write updates if content hashes differ.
Claude Adapter	CLAUDE.md	Root-level adapter for Claude Code; typically includes the full document content.
Cursor Rules	.cursor/rules/*.mdc	Scoped rules (e.g., hooks.mdc, components.mdc) using YAML frontmatter and glob patterns.
Copilot Rules	.github/copilot-instructions.md	Plain Markdown instructions located in the .github directory for GitHub Copilot Workspace.
Windsurf Rules	.windsurfrules	Plain text adapter located at the repository root for the Windsurf IDE.

Sources: scripts/sync-agents.js:19-75, CLAUDE.md:325-348

Implementation Details

The Sync Logic

The sync-agents.js script utilizes a section parser that extracts Markdown content between H2 headers. It employs a hashing mechanism (sha256) to compare the generated content against existing files on disk, preventing unnecessary "noise" in Git diffs by only overwriting files when content actually changes.

sequenceDiagram
    participant Dev as Developer
    participant Script as sync-agents.js
    participant FS as File System
    
    Dev->>FS: Edit .agents/AGENTS.md
    Dev->>Script: Run npm run sync-agents
    Script->>FS: Read Master Source
    loop For each Adapter Definition
        Script->>Script: Extract required H2 sections
        Script->>Script: Generate SHA256 hash
        Script->>FS: Read existing adapter file
        alt Hash Mismatch
            Script->>FS: Write updated content
            Note right of Script: Mark as changed
        else Hash Match
            Note right of Script: Mark as unchanged
        end
    end
    Script-->>Dev: Summary (X files updated)

Loading

The sequence diagram illustrates the internal logic used by the synchronization script to maintain adapter files while minimizing unnecessary writes. Sources: scripts/sync-agents.js:40-75, scripts/sync-agents.js:185-220

Specialized Scoping

Unlike general adapters that receive most of the master content, Cursor rules are specifically scoped to directory patterns (globs) to provide relevant context without overwhelming the agent's context window.

• Global Rules: Applied to ["**/*"] (Project identity, layout, security).
• Hook Rules: Applied to ["src/hooks/**/*.ts", "src/hooks/**/*.tsx"] (Data fetching, security).
• Component Rules: Applied to ["src/components/**/*.tsx", "src/pages/**/*.tsx"] (Code rules, styling).
• Database Rules: Applied to ["supabase/migrations/**/*.sql", "supabase/functions/**/*.ts"] (Migrations, Edge Functions).

Sources: scripts/sync-agents.js:125-165, CLAUDE.md:330-340

Core Rules & Constraints

The AI agents are strictly instructed on several non-negotiable project pillars:

1. Security Enforcement (RLS)

Every AI agent must enforce Row Level Security (RLS) as the primary security layer.

• Empty Arrays: Queries returning empty arrays should be treated as "no access" rather than errors.
• No Inline Subqueries: RLS policies must use security definer functions (e.g., is_team_member()) to avoid recursive evaluation.
• Service Role: The SUPABASE_SERVICE_ROLE_KEY is restricted to Edge Functions and must never be exposed to the client.

Sources: CLAUDE.md:144-160, CLAUDE.md:237-248

2. Technical Stack Standards

AI assistants are required to use specific libraries and patterns:

• Data Fetching: Use TanStack React Query; useEffect for fetching is explicitly prohibited.
• State Management: Components receive data via props; they do not fetch it themselves.
• Styling: Use semantic Tailwind tokens (e.g., bg-background) instead of raw hex codes to maintain dark mode compatibility.

Sources: CLAUDE.md:167-175, CLAUDE.md:188-200

Maintenance & CI/CD

To ensure that developers do not bypass the sync process, a CI workflow (agents-sync-check.yml) is referenced. This workflow runs the sync script and fails the build if any generated adapter is out of sync with .agents/AGENTS.md.

Manual Sync Command:

npm run sync-agents

Git Workflow: When rules change, developers must commit the master file and all generated adapters together:

git add .agents/AGENTS.md CLAUDE.md .cursor/ .github/copilot-instructions.md .windsurfrules
git commit -m 'docs(agents): update AI agent instructions'

Sources: scripts/sync-agents.js:10-15, scripts/sync-agents.js:225-230, CLAUDE.md:350-355

Conclusion

The AI Agent Rules & IDE Syncing system provides a robust framework for maintaining architectural integrity in a multi-AI environment. By centralizing knowledge in .agents/AGENTS.md and automating the distribution of these rules, the Colabs project ensures that every AI assistant—regardless of the IDE it lives in—operates as a high-context specialist aware of the project's unique security and structural requirements.

Testing Strategy (Vitest & RTL)

Relevant source files

The following files were used as context for generating this wiki page:

• .agents/testing.md
• CLAUDE.md
• README.md
• src/components/CreateGigDialog.tsx
• src/pages/SubmitProposal.tsx
• src/components/CreateProjectDialog.tsx

Testing Strategy (Vitest & RTL)

Colabs employs a robust testing strategy focused on ensuring the reliability of its React-based frontend and Supabase-backed backend logic. The strategy primarily utilizes Vitest as the test runner and React Testing Library (RTL) for component and integration testing. This approach emphasizes testing user behavior rather than implementation details, ensuring that the platform remains stable as features like gig marketplaces and project management evolve.

The testing suite is integrated into the CI/CD pipeline, with specific commands for linting, type-checking, and building that must pass before any Pull Request is merged. This ensures high code quality and security standards across the repository. Sources: CLAUDE.md:68-74, CLAUDE.md:121-125

Testing Architecture and Tooling

The testing environment is built upon a modern JavaScript stack. While the core application runs on React 18 and Vite 5, the testing infrastructure leverages Vitest for its speed and compatibility with Vite-based projects.

Core Testing Stack

Tool	Purpose	Description
Vitest	Test Runner	A Vite-native unit test framework.
React Testing Library	Component Testing	For testing React components by querying the DOM in a way similar to how users find elements.
Mock Service Worker (MSW)	API Mocking	Used to intercept network requests and return mock Supabase/API responses.
Zod	Validation Testing	Used to validate data structures and form inputs (e.g., Gig and Project forms).

Sources: CLAUDE.md:68-74, src/components/CreateGigDialog.tsx:21-49, src/components/CreateProjectDialog.tsx:93-113

Testing Flow Diagram

The following diagram illustrates the flow of data and validation during a typical testing scenario for a form-based component (like CreateGigDialog or SubmitProposal).

flowchart TD
    A[User Input/Test Trigger] --> B{Zod Validation}
    B -- Invalid --> C[Display Error Toast/Inline Error]
    B -- Valid --> D[MSW Intercepts Request]
    D --> E[Mock Supabase Response]
    E --> F[Update UI/Success Toast]
    F --> G[Invalidate Query Cache]

Loading

Sources: src/components/CreateGigDialog.tsx:142-168, src/pages/SubmitProposal.tsx:132-150, CLAUDE.md:286-298

Component Testing Patterns

Testing in Colabs focuses on the interaction between user inputs and system responses. Components like CreateGigDialog use Zod schemas to validate inputs before attempting database operations, which provides a clear surface for unit testing validation logic.

Form Validation Testing

Components are tested to ensure they handle both valid and invalid states. For example, the gigSchema in CreateGigDialog.tsx enforces constraints on titles, company names, and budgets. Sources: src/components/CreateGigDialog.tsx:21-49

// Example of validation logic targeted by tests
const result = gigSchema.safeParse({
  title,
  company,
  // ...other fields
});

if (!result.success) {
  // Logic to handle field errors
}

Sources: src/components/CreateGigDialog.tsx:142-156

Integration Testing with Supabase

Since Colabs is a "Backend-as-a-Service" application, integration tests must account for Supabase client interactions. Testing involves:

1. Auth State: Verifying components behave correctly for authenticated vs. unauthenticated users using AuthGuard or useAuth.
2. Database Operations: Using MSW to mock supabase.from().insert() or update() calls.
3. UI Feedback: Asserting that toast() notifications appear with the correct messages upon success or failure.

Sources: src/pages/SubmitProposal.tsx:132-150, src/components/CreateGigDialog.tsx:181-205, CLAUDE.md:286-298

Security and Rule Enforcement

Testing is also used to enforce the project's strict security rules, specifically regarding Row Level Security (RLS) and environment variables.

Security Testing Considerations

• Secrets: CI workflows and tests ensure that no variables prefixed with VITE_ contain sensitive secrets.

• RLS Policies: While difficult to test purely in the frontend, integration tests verify that unauthorized attempts to fetch data (resulting in empty arrays from Supabase) are handled by EmptyState components.

• File Uploads: Testing for SubmitProposal.tsx includes verifying that file size (max 10MB) and MIME type (PDF/Word) validations are enforced before storage writes.

Sources: CLAUDE.md:195-200, CLAUDE.md:342-348, src/pages/SubmitProposal.tsx:135-155

Deployment and CI Integration

Testing is a mandatory gate in the Colabs development lifecycle. The CLAUDE.md guide specifies a strict sequence of commands that must be executed to maintain code health.

CI/CD Command Summary

npm run lint         # Zero errors required
npm run type-check   # Zero errors required
npm run build        # Must pass before any PR

Sources: CLAUDE.md:123-125

The project also uses a specialized script, scripts/sync-agents.js, to ensure that AI agent instructions (which include testing rules) are synchronized across various IDE adapters like Claude, Cursor, and Copilot. This ensures that even AI-generated code follows the established testing strategy. Sources: scripts/sync-agents.js:1-20

Conclusion

The testing strategy for Colabs combines modern unit testing with Vitest, behavioral component testing with RTL, and strict schema validation with Zod. By integrating these tools into a mandatory CI pipeline and utilizing MSW for API mocking, the project ensures that its complex interactions—ranging from GitHub integration to milestone-based payments—remain reliable and secure for all contributors and users. Sources: CLAUDE.md:68-74, README.md:110-120

Deployment & Vercel Config

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• CLAUDE.md
• README.md
• scripts/sync-agents.js
• index.html
• src/integrations/supabase/types.ts

Deployment & Vercel Config

Colabs is a modern Single Page Application (SPA) built with React 18, TypeScript, and Vite 5, designed for deployment on platforms like Vercel. The project follows a serverless architecture where the frontend is a static build and all backend logic is delegated to Supabase Edge Functions and PostgreSQL.

The deployment process is tightly integrated with the repository's CI/CD workflows and automated documentation synchronization scripts. While the frontend is hosted on Vercel, the backend infrastructure—including authentication, database migrations, and storage—is managed through the Supabase CLI.

Sources: README.md:144-160, CLAUDE.md:12-16

Build and Environment Configuration

The application uses Vite as its build tool, requiring a specific pipeline of checks before a production build is finalized. The package.json defines a strict sequence where formatting, linting, and type-checking must pass before the vite build command executes.

Build Pipeline Flow

The following diagram illustrates the pre-deployment check sequence required for a successful build.

flowchart TD
    Start[npm run build] --> Format[Prettier Check]
    Format --> Lint[ESLint zero warnings]
    Lint --> TypeCheck[TSC NoEmit]
    TypeCheck --> ViteBuild[Vite Build]
    ViteBuild --> Success[Production Assets]

Loading

The build process ensures code quality by enforcing zero linting errors and zero TypeScript type errors.

Sources: package.json:7-22, CLAUDE.md:83-88

Build Command Summary

Command	Action	Requirement
npm run dev	Starts Vite dev server	Localhost:5173
npm run check	Runs format, lint, and type-check	Must pass all
npm run build	Executes production build	Runs check first
npm run preview	Previews production build	Local preview of /dist

Sources: package.json:7-22, CLAUDE.md:83-88

Backend Infrastructure Deployment

Backend deployment is separate from the frontend Vercel deployment. It utilizes the Supabase CLI to manage Edge Functions and Database Migrations.

Supabase Edge Functions

All server-side logic runs in Supabase Edge Functions on the Deno runtime. These functions are deployed independently of the frontend assets. Webhook endpoints (such as those for Stripe or GitHub) require specific configurations in supabase/config.toml, such as setting verify_jwt = false.

Sources: CLAUDE.md:14-16, CLAUDE.md:214-230

Database Migrations

Migrations follow an append-only strategy. Developers must never edit existing migration files. After every migration, TypeScript types must be regenerated to keep the frontend synchronized with the database schema.

flowchart TD
    NewMig[Create New Migration] --> ApplyDB[npx supabase db push]
    ApplyDB --> GenTypes[npx supabase gen types]
    GenTypes --> Commit[Commit types.ts + SQL]

Loading

Sources: CLAUDE.md:139-145, CLAUDE.md:232-234

Vercel and CI/CD Integration

The project is configured for deployment on Vercel (referenced at sytcolabs.vercel.app). The deployment is supported by GitHub Actions workflows that handle security, stale issues, and agent instruction synchronization.

Agent Synchronization Script

A critical part of the deployment and maintenance cycle is the sync-agents.js script. This script ensures that AI assistant instructions (Claude, Cursor, Copilot) are kept in sync with the core documentation. The CI pipeline (pr.yml) runs this script and fails the build if the adapters are out of sync.

File Path	Target Agent	Purpose
CLAUDE.md	Claude Code	General instructions
.cursor/rules/	Cursor IDE	Scoped file rules
.github/copilot-instructions.md	GitHub Copilot	Workspace context

Sources: scripts/sync-agents.js:1-15, README.md:27, package.json:20

Security and Environment Variables

Deployment security is enforced through strict naming conventions for environment variables and Database Row Level Security (RLS).

Variable Masking

• VITE_ Prefixed: These variables are bundled into the client and are visible in the browser.
• Non-prefixed: Secrets like STRIPE_SECRET_KEY or GITHUB_CLIENT_SECRET must never use the VITE_ prefix and are managed via Supabase secrets (npx supabase secrets set).
• Service Role: The SUPABASE_SERVICE_ROLE_KEY is only available in Edge Functions and must never be exposed to the client.

Sources: CLAUDE.md:267-279, CLAUDE.md:292-295

Row Level Security (RLS)

Security is enforced at the database layer. Every table must have RLS enabled and at least one policy. The deployment of a new table without an RLS policy effectively results in a table that returns zero rows to all users.

Sources: CLAUDE.md:164-175, src/integrations/supabase/types.ts:16-30

Summary

The deployment of Colabs involves a dual-stack approach: Vercel hosts the React frontend, while the Supabase CLI manages the Deno-based backend and PostgreSQL schema. Successful deployment is gated by a rigorous CI pipeline that validates code style, type safety, and the synchronization of AI agent configurations across the repository.