From 1752edf2b2c2caaef76679185bdd7dcb96c9b4aa Mon Sep 17 00:00:00 2001
From: Marc Klose <marcklose99@gmail.com>
Date: Tue, 7 Apr 2026 11:41:24 +0300
Subject: [PATCH] feat: initialize agent workflow documentation

---
 .agents/GEMINI-template.md        | 138 ++++++++++
 .agents/rules/frontend.md         |  45 ++++
 .agents/workflows/create-rules.md | 163 ++++++++++++
 .agents/workflows/execute.md      | 113 +++++++++
 .agents/workflows/plan-feature.md | 407 ++++++++++++++++++++++++++++++
 .agents/workflows/prime.md        |  81 ++++++
 GEMINI.md                         | 118 +++++++++
 7 files changed, 1065 insertions(+)
 create mode 100644 .agents/GEMINI-template.md
 create mode 100644 .agents/rules/frontend.md
 create mode 100644 .agents/workflows/create-rules.md
 create mode 100644 .agents/workflows/execute.md
 create mode 100644 .agents/workflows/plan-feature.md
 create mode 100644 .agents/workflows/prime.md
 create mode 100644 GEMINI.md

diff --git a/.agents/GEMINI-template.md b/.agents/GEMINI-template.md
new file mode 100644
index 0000000..f4c520d
--- /dev/null
+++ b/.agents/GEMINI-template.md
@@ -0,0 +1,138 @@
+# GEMINI.md Template
+
+A flexible template for creating global rules. Adapt sections based on your project type.
+
+---
+
+# GEMINI.md
+
+This file provides guidance to Gemini when working with code in this repository.
+
+## Project Overview
+
+<!-- What is this project? One paragraph description -->
+
+{Project description and purpose}
+
+---
+
+## Tech Stack
+
+<!-- List technologies used. Add/remove rows as needed -->
+
+| Technology | Purpose         |
+| ---------- | --------------- |
+| {tech}     | {why it's used} |
+
+---
+
+## Commands
+
+<!-- Common commands for this project. Adjust based on your package manager and setup -->
+
+```bash
+# Development
+{dev-command}
+
+# Build
+{build-command}
+
+# Test
+{test-command}
+
+# Lint
+{lint-command}
+```
+
+---
+
+## Project Structure
+
+<!-- Describe your folder organization. This varies greatly by project type -->
+
+```
+{root}/
+├── {dir}/     # {description}
+├── {dir}/     # {description}
+└── {dir}/     # {description}
+```
+
+---
+
+## Architecture
+
+<!-- Describe how the code is organized. Examples:
+- Layered (routes → services → data)
+- Component-based (features as self-contained modules)
+- MVC pattern
+- Event-driven
+- etc.
+-->
+
+{Describe the architectural approach and data flow}
+
+---
+
+## Code Patterns
+
+<!-- Key patterns and conventions used in this codebase -->
+
+### Naming Conventions
+
+- {convention}
+
+### File Organization
+
+- {pattern}
+
+### Error Handling
+
+- {approach}
+
+---
+
+## Testing
+
+<!-- How to test and what patterns to follow -->
+
+- **Run tests**: `{test-command}`
+- **Test location**: `{test-directory}`
+- **Pattern**: {describe test approach}
+
+---
+
+## Validation
+
+<!-- Commands to run before committing -->
+
+```bash
+{validation-commands}
+```
+
+---
+
+## Key Files
+
+<!-- Important files to know about -->
+
+| File     | Purpose       |
+| -------- | ------------- |
+| `{path}` | {description} |
+
+---
+
+## On-Demand Context
+
+<!-- Optional: Reference docs for deeper context -->
+
+| Topic   | File     |
+| ------- | -------- |
+| {topic} | `{path}` |
+
+---
+
+## Notes
+
+<!-- Any special instructions, constraints, or gotchas -->
+
+- {note}
diff --git a/.agents/rules/frontend.md b/.agents/rules/frontend.md
new file mode 100644
index 0000000..13cd78e
--- /dev/null
+++ b/.agents/rules/frontend.md
@@ -0,0 +1,45 @@
+---
+trigger: model_decision
+description: Applied when creating or modifying frontend components, Next.js pages, Tailwind styling, and UI logic in the app/ or components/ directories to ensure strict TypeScript usage, consistent design patterns, and responsive best practices.
+---
+
+# Frontend Rules
+
+This document outlines the coding standards and best practices for the frontend of the Teklifsat Platform.
+
+## TypeScript & Types
+
+- **Never use `any`**: Always define proper interfaces or types for your data. If a type is truly unknown, use `unknown` and type guards.
+- **Strict Typing**: Enable and follow strict TypeScript rules.
+- **Component Props**: Always define an interface or type for component props, even if empty.
+
+## React & Next.js
+
+- **Functional Components**: Use functional components with arrow functions.
+- **Hooks**: Use standard hooks (`useState`, `useEffect`, `useMemo`, `useCallback`) appropriately.
+- **App Router Design**:
+  - Default to Server Components (`'use server'`) for data fetching.
+  - Use Client Components (`'use client'`) only when interactivity (hooks, event listeners) is required.
+  - Keep Client Components at the leaves of your component tree.
+- **File Naming**: Use `kebab-case` for file and directory names.
+
+## Styling & UI
+
+- **Tailwind CSS**: Use Tailwind for all styling. Avoid inline styles or custom CSS classes unless absolutely necessary.
+- **Dynamic Classes**: Always use the `cn` utility from `lib/utils.ts` for conditional or dynamic class merging.
+- **Radix UI**: Use Radix UI primitives for complex accessible components (Modals, Dropdowns, etc.).
+- **Icons**: Use `Lucide` as the primary icon set.
+- **Responsive Design**: Mobile-first approach is mandatory. Use Tailwind's responsive prefixes (`sm:`, `md:`, `lg:`, etc.).
+- **Theme Consistency**: Use the CSS variables defined in `globals.css` for colors, spacing, and other design tokens.
+
+## State Management
+
+- Use React context or appropriate libraries when state needs to be shared across many components.
+- Prefer local state for component-specific data.
+- Leverage Supabase Realtime for live updates where necessary.
+
+## Performance & SEO
+
+- **Image Optimization**: Use the Next.js `Image` component for all images.
+- **Semantic HTML**: Use proper semantic tags (`<header>`, `<footer>`, `<main>`, `<section>`, etc.) for better accessibility and SEO.
+- **Meta Tags**: Ensure each page has appropriate meta titles and descriptions.
diff --git a/.agents/workflows/create-rules.md b/.agents/workflows/create-rules.md
new file mode 100644
index 0000000..fe4df34
--- /dev/null
+++ b/.agents/workflows/create-rules.md
@@ -0,0 +1,163 @@
+---
+description: Create global rules (GEMINI.md) from codebase analysis
+---
+
+# Create Global Rules
+
+Generate a GEMINI.md file by analyzing the codebase and extracting patterns.
+
+---
+
+## Objective
+
+Create project-specific global rules that give Claude context about:
+
+- What this project is
+- Technologies used
+- How the code is organized
+- Patterns and conventions to follow
+- How to build, test, and validate
+
+---
+
+## Phase 1: DISCOVER
+
+### Identify Project Type
+
+First, determine what kind of project this is:
+
+| Type                 | Indicators                                    |
+| -------------------- | --------------------------------------------- |
+| Web App (Full-stack) | Separate client/server dirs, API routes       |
+| Web App (Frontend)   | React/Vue/Svelte, no server code              |
+| API/Backend          | Express/Fastify/etc, no frontend              |
+| Library/Package      | `main`/`exports` in package.json, publishable |
+| CLI Tool             | `bin` in package.json, command-line interface |
+| Monorepo             | Multiple packages, workspaces config          |
+| Script/Automation    | Standalone scripts, task-focused              |
+
+### Analyze Configuration
+
+Look at root configuration files:
+
+```
+package.json       → dependencies, scripts, type
+tsconfig.json      → TypeScript settings
+vite.config.*      → Build tool
+*.config.js/ts     → Various tool configs
+```
+
+### Map Directory Structure
+
+Explore the codebase to understand organization:
+
+- Where does source code live?
+- Where are tests?
+- Any shared code?
+- Configuration locations?
+
+---
+
+## Phase 2: ANALYZE
+
+### Extract Tech Stack
+
+From package.json and config files, identify:
+
+- Runtime/Language (Node, Bun, Deno, browser)
+- Framework(s)
+- Database (if any)
+- Testing tools
+- Build tools
+- Linting/formatting
+
+### Identify Patterns
+
+Study existing code for:
+
+- **Naming**: How are files, functions, classes named?
+- **Structure**: How is code organized within files?
+- **Errors**: How are errors created and handled?
+- **Types**: How are types/interfaces defined?
+- **Tests**: How are tests structured?
+
+### Find Key Files
+
+Identify files that are important to understand:
+
+- Entry points
+- Configuration
+- Core business logic
+- Shared utilities
+- Type definitions
+
+---
+
+## Phase 3: GENERATE
+
+### Create GEMINI.md
+
+Use the template at `.agents/GEMINI-template.md` as a starting point.
+
+**Output path**: `GEMINI.md` (project root)
+
+**Adapt to the project:**
+
+- Remove sections that don't apply
+- Add sections specific to this project type
+- Keep it concise - focus on what's useful
+
+**Key sections to include:**
+
+1. **Project Overview** - What is this and what does it do?
+2. **Tech Stack** - What technologies are used?
+3. **Commands** - How to dev, build, test, lint?
+4. **Structure** - How is the code organized?
+5. **Patterns** - What conventions should be followed?
+6. **Key Files** - What files are important to know?
+
+**Optional sections (add if relevant):**
+
+- Architecture (for complex apps)
+- API endpoints (for backends)
+- Component patterns (for frontends)
+- Database patterns (if using a DB)
+- On-demand context references
+
+---
+
+## Phase 4: OUTPUT
+
+```markdown
+## Global Rules Created
+
+**File**: `GEMINI.md`
+
+### Project Type
+
+{Detected project type}
+
+### Tech Stack Summary
+
+{Key technologies detected}
+
+### Structure
+
+{Brief structure overview}
+
+### Next Steps
+
+1. Review the generated `GEMINI.md`
+2. Add any project-specific notes
+3. Remove any sections that don't apply
+4. Optionally create reference docs in `.agents/reference/`
+```
+
+---
+
+## Tips
+
+- Keep GEMINI.md focused and scannable
+- Don't duplicate information that's in other docs (link instead)
+- Focus on patterns and conventions, not exhaustive documentation
+- Update it as the project evolves
diff --git a/.agents/workflows/execute.md b/.agents/workflows/execute.md
new file mode 100644
index 0000000..d00b559
--- /dev/null
+++ b/.agents/workflows/execute.md
@@ -0,0 +1,113 @@
+---
+description: Execute an implementation plan
+---
+
+# Execute: Implement from Plan
+
+## Plan to Execute
+
+Read plan file
+
+## Execution Instructions
+
+### 1. Read and Understand
+
+- Read the ENTIRE plan carefully
+- Understand all tasks and their dependencies
+- Note the validation commands to run
+- Review the testing strategy
+
+### 2. Create a New Branch
+
+- Create a descriptive branch name based on the feature or fix being implemented
+- Switch to the new branch before making any changes
+
+### 3. Execute Tasks in Order
+
+For EACH task in "Step by Step Tasks":
+
+#### a. Navigate to the task
+
+- Identify the file and action required
+- Read existing related files if modifying
+
+#### b. Implement the task
+
+- Follow the detailed specifications exactly
+- Maintain consistency with existing code patterns
+- Include proper type hints and documentation
+- Add structured logging where appropriate
+
+#### c. Verify as you go
+
+- After each file change, check syntax
+- Ensure imports are correct
+- Verify types are properly defined
+
+### 4. Implement Testing Strategy
+
+After completing implementation tasks:
+
+- Create all test files specified in the plan
+- Implement all test cases mentioned
+- Follow the testing approach outlined
+- Ensure tests cover edge cases
+
+### 5. Run Validation Commands
+
+Execute ALL validation commands from the plan in order:
+
+```bash
+# Run each command exactly as specified in plan
+```
+
+If any command fails:
+
+- Fix the issue
+- Re-run the command
+- Continue only when it passes
+
+### 6. Final Verification
+
+Before completing:
+
+- ✅ All tasks from plan completed
+- ✅ All tests created and passing
+- ✅ All validation commands pass
+- ✅ Code follows project conventions
+- ✅ Documentation added/updated as needed
+
+## Output Report
+
+Provide summary:
+
+### Completed Tasks
+
+- List of all tasks completed
+- Files created (with paths)
+- Files modified (with paths)
+
+### Tests Added
+
+- Test files created
+- Test cases implemented
+- Test results
+
+### Validation Results
+
+```bash
+# Output from each validation command
+```
+
+### Ready for Commit
+
+- Confirm all changes are complete
+- Confirm all validations pass
+- Ready for `/commit` command
+
+## Notes
+
+- If you encounter issues not addressed in the plan, document them
+- If you need to deviate from the plan, explain why
+- If tests fail, fix implementation until they pass
+- Don't skip validation steps
diff --git a/.agents/workflows/plan-feature.md b/.agents/workflows/plan-feature.md
new file mode 100644
index 0000000..0f4a084
--- /dev/null
+++ b/.agents/workflows/plan-feature.md
@@ -0,0 +1,407 @@
+---
+description: Create comprehensive feature plan with deep codebase analysis and research
+---
+
+# Plan a new task
+
+## Mission
+
+Transform a feature request into a **comprehensive implementation plan** through systematic codebase analysis, external research, and strategic planning.
+
+**Core Principle**: We do NOT write code in this phase. Our goal is to create a context-rich implementation plan that enables one-pass implementation success for ai agents.
+
+**Key Philosophy**: Context is King. The plan must contain ALL information needed for implementation - patterns, mandatory reading, documentation, validation commands - so the execution agent succeeds on the first attempt.
+
+## Planning Process
+
+### Phase 1: Feature Understanding
+
+**Deep Feature Analysis:**
+
+- Extract the core problem being solved
+- Identify user value and business impact
+- Determine feature type: New Capability/Enhancement/Refactor/Bug Fix
+- Assess complexity: Low/Medium/High
+- Map affected systems and components
+
+**Create User Story Format Or Refine If Story Was Provided By The User:**
+
+```
+As a <type of user>
+I want to <action/goal>
+So that <benefit/value>
+```
+
+### Phase 2: Codebase Intelligence Gathering
+
+**Use specialized agents and parallel analysis:**
+
+**1. Project Structure Analysis**
+
+- Detect primary language(s), frameworks, and runtime versions
+- Map directory structure and architectural patterns
+- Identify service/component boundaries and integration points
+- Locate configuration files (pyproject.toml, package.json, etc.)
+- Find environment setup and build processes
+
+**2. Pattern Recognition** (Use specialized subagents when beneficial)
+
+- Search for similar implementations in codebase
+- Identify coding conventions:
+  - Naming patterns (CamelCase, snake_case, kebab-case)
+  - File organization and module structure
+  - Error handling approaches
+  - Logging patterns and standards
+- Extract common patterns for the feature's domain
+- Document anti-patterns to avoid
+- Check CLAUDE.md for project-specific rules and conventions
+
+**3. Dependency Analysis**
+
+- Catalog external libraries relevant to feature
+- Understand how libraries are integrated (check imports, configs)
+- Find relevant documentation in docs/, ai_docs/, .agents/reference or ai-wiki if available
+- Note library versions and compatibility requirements
+- ALWAYS use browser_subagent tool and consult https://developer.unipile.com/docs/ if the task is related to LinkedIn
+
+**4. Testing Patterns**
+
+- Identify test framework and structure (pytest, jest, etc.)
+- Find similar test examples for reference
+- Understand test organization (unit vs integration)
+- Note coverage requirements and testing standards
+
+**5. Integration Points**
+
+- Identify existing files that need updates
+- Determine new files that need creation and their locations
+- Map router/API registration patterns
+- Understand database/model patterns if applicable
+- Identify authentication/authorization patterns if relevant
+
+**Clarify Ambiguities:**
+
+- If requirements are unclear at this point, ask the user to clarify before you continue
+- Get specific implementation preferences (libraries, approaches, patterns)
+- Resolve architectural decisions before proceeding
+
+### Phase 3: External Research & Documentation
+
+**Use specialized subagents when beneficial for external research:**
+
+**Documentation Gathering:**
+
+- Research latest library versions and best practices
+- Find official documentation with specific section anchors
+- Locate implementation examples and tutorials
+- Identify common gotchas and known issues
+- Check for breaking changes and migration guides
+
+**Technology Trends:**
+
+- Research current best practices for the technology stack
+- Find relevant blog posts, guides, or case studies
+- Identify performance optimization patterns
+- Document security considerations
+
+**Compile Research References:**
+
+```markdown
+## Relevant Documentation
+
+- [Library Official Docs](https://example.com/docs#section)
+  - Specific feature implementation guide
+  - Why: Needed for X functionality
+- [Framework Guide](https://example.com/guide#integration)
+  - Integration patterns section
+  - Why: Shows how to connect components
+```
+
+### Phase 4: Deep Strategic Thinking
+
+**Think Harder About:**
+
+- How does this feature fit into the existing architecture?
+- What are the critical dependencies and order of operations?
+- What could go wrong? (Edge cases, race conditions, errors)
+- How will this be tested comprehensively?
+- What performance implications exist?
+- Are there security considerations?
+- How maintainable is this approach?
+
+**Design Decisions:**
+
+- Choose between alternative approaches with clear rationale
+- Design for extensibility and future modifications
+- Plan for backward compatibility if needed
+- Consider scalability implications
+
+### Phase 5: Plan Structure Generation
+
+**Create comprehensive plan with the following structure:**
+
+Whats below here is a template for you to fill for th4e implementation agent:
+
+```markdown
+# Feature: <feature-name>
+
+The following plan should be complete, but its important that you validate documentation and codebase patterns and task sanity before you start implementing.
+
+Pay special attention to naming of existing utils types and models. Import from the right files etc.
+
+## Feature Description
+
+<Detailed description of the feature, its purpose, and value to users>
+
+## User Story
+
+As a <type of user>
+I want to <action/goal>
+So that <benefit/value>
+
+## Problem Statement
+
+<Clearly define the specific problem or opportunity this feature addresses>
+
+## Solution Statement
+
+<Describe the proposed solution approach and how it solves the problem>
+
+## Feature Metadata
+
+**Feature Type**: [New Capability/Enhancement/Refactor/Bug Fix]
+**Estimated Complexity**: [Low/Medium/High]
+**Primary Systems Affected**: [List of main components/services]
+**Dependencies**: [External libraries or services required]
+
+---
+
+## CONTEXT REFERENCES
+
+### Relevant Codebase Files IMPORTANT: YOU MUST READ THESE FILES BEFORE IMPLEMENTING!
+
+<List files with line numbers and relevance>
+
+- `path/to/file.py` (lines 15-45) - Why: Contains pattern for X that we'll mirror
+- `path/to/model.py` (lines 100-120) - Why: Database model structure to follow
+- `path/to/test.py` - Why: Test pattern example
+
+### New Files to Create
+
+- `path/to/new_service.py` - Service implementation for X functionality
+- `path/to/new_model.py` - Data model for Y resource
+- `tests/path/to/test_new_service.py` - Unit tests for new service
+
+### Relevant Documentation YOU SHOULD READ THESE BEFORE IMPLEMENTING!
+
+- [Documentation Link 1](https://example.com/doc1#section)
+  - Specific section: Authentication setup
+  - Why: Required for implementing secure endpoints
+- [Documentation Link 2](https://example.com/doc2#integration)
+  - Specific section: Database integration
+  - Why: Shows proper async database patterns
+
+### Patterns to Follow
+
+<Specific patterns extracted from codebase - include actual code examples from the project>
+
+**Naming Conventions:** (for example)
+
+**Error Handling:** (for example)
+
+**Logging Pattern:** (for example)
+
+**Other Relevant Patterns:** (for example)
+
+---
+
+## IMPLEMENTATION PLAN
+
+### Phase 1: Foundation
+
+<Describe foundational work needed before main implementation>
+
+**Tasks:**
+
+- Set up base structures (schemas, types, interfaces)
+- Configure necessary dependencies
+- Create foundational utilities or helpers
+
+### Phase 2: Core Implementation
+
+<Describe the main implementation work>
+
+**Tasks:**
+
+- Implement core business logic
+- Create service layer components
+- Add API endpoints or interfaces
+- Implement data models
+
+### Phase 3: Integration
+
+<Describe how feature integrates with existing functionality>
+
+**Tasks:**
+
+- Connect to existing routers/handlers
+- Register new components
+- Update configuration files
+- Add middleware or interceptors if needed
+
+### Phase 4: Testing & Validation
+
+<Describe testing approach>
+
+**Tasks:**
+
+- Implement unit tests for each component
+- Create integration tests for feature workflow
+- Add edge case tests
+- Validate against acceptance criteria
+
+---
+
+## STEP-BY-STEP TASKS
+
+IMPORTANT: Execute every task in order, top to bottom. Each task is atomic and independently testable.
+
+### Task Format Guidelines
+
+Use information-dense keywords for clarity:
+
+- **CREATE**: New files or components
+- **UPDATE**: Modify existing files
+- **ADD**: Insert new functionality into existing code
+- **REMOVE**: Delete deprecated code
+- **REFACTOR**: Restructure without changing behavior
+- **MIRROR**: Copy pattern from elsewhere in codebase
+
+### {ACTION} {target_file}
+
+- **IMPLEMENT**: {Specific implementation detail}
+- **PATTERN**: {Reference to existing pattern - file:line}
+- **IMPORTS**: {Required imports and dependencies}
+- **GOTCHA**: {Known issues or constraints to avoid}
+- **VALIDATE**: `{executable validation command}`
+
+<Continue with all tasks in dependency order...>
+
+---
+
+## TESTING STRATEGY
+
+<Define testing approach based on project's test framework and patterns discovered in during research>
+
+### Unit Tests
+
+<Scope and requirements based on project standards>
+
+Design unit tests with fixtures and assertions following existing testing approaches
+
+### Integration Tests
+
+<Scope and requirements based on project standards>
+
+### Edge Cases
+
+<List specific edge cases that must be tested for this feature>
+
+---
+
+## VALIDATION COMMANDS
+
+<Define validation commands based on project's tools discovered in Phase 2>
+
+Execute every command to ensure zero regressions and 100% feature correctness.
+
+### Level 1: Syntax & Style
+
+<Project-specific linting and formatting commands>
+
+### Level 2: Unit Tests
+
+<Project-specific unit test commands>
+
+### Level 3: Integration Tests
+
+<Project-specific integration test commands>
+
+### Level 4: Manual Validation
+
+<Feature-specific manual testing steps - API calls, UI testing, etc.>
+
+### Level 5: Additional Validation (Optional)
+
+<MCP servers or additional CLI tools if available>
+
+---
+
+## ACCEPTANCE CRITERIA
+
+<List specific, measurable criteria that must be met for completion>
+
+- [ ] Feature implements all specified functionality
+- [ ] All validation commands pass with zero errors
+- [ ] Unit test coverage meets requirements (80%+)
+- [ ] Integration tests verify end-to-end workflows
+- [ ] Code follows project conventions and patterns
+- [ ] No regressions in existing functionality
+- [ ] Documentation is updated (if applicable)
+- [ ] Performance meets requirements (if applicable)
+- [ ] Security considerations addressed (if applicable)
+
+---
+
+## COMPLETION CHECKLIST
+
+- [ ] All tasks completed in order
+- [ ] Each task validation passed immediately
+- [ ] All validation commands executed successfully
+- [ ] Full test suite passes (unit + integration)
+- [ ] No linting or type checking errors
+- [ ] Manual testing confirms feature works
+- [ ] Acceptance criteria all met
+- [ ] Code reviewed for quality and maintainability
+
+---
+
+## NOTES
+
+<Additional context, design decisions, trade-offs>
+```
+
+## Output Format
+
+**Filename**: `.agents/plans/{kebab-case-descriptive-name}.md`
+
+- Replace `{kebab-case-descriptive-name}` with short, descriptive feature name
+- Examples: `add-user-authentication.md`, `implement-search-api.md`, `refactor-database-layer.md`
+
+**Directory**: Create `.agents/plans/` if it doesn't exist
+
+## Quality Criteria
+
+### Context Completeness ✓
+
+- [ ] All necessary patterns identified and documented
+- [ ] External library usage documented with links
+- [ ] Integration points clearly mapped
+- [ ] Gotchas and anti-patterns captured
+- [ ] Every task has executable validation command
+
+### Implementation Ready ✓
+
+- [ ] Another developer could execute without additional context
+- [ ] Tasks ordered by dependency (can execute top-to-bottom)
+- [ ] Each task is atomic and independently testable
+- [ ] Pattern references include specific file:line numbers
+
+### Pattern Consistency ✓
+
+- [ ] Tasks follow existing codebase conventions
+- [ ] New patterns justified with clear rationale
+- [ ] No reinvention of existing patterns or utils
+- [ ] Testing approach matches project standards
+
+### Informat
diff --git a/.agents/workflows/prime.md b/.agents/workflows/prime.md
new file mode 100644
index 0000000..1fd012e
--- /dev/null
+++ b/.agents/workflows/prime.md
@@ -0,0 +1,81 @@
+---
+description: Prime agent with codebase understanding
+---
+
+# Prime: Load Project Context
+
+## Objective
+
+Build comprehensive understanding of the codebase by analyzing structure, documentation, and key files.
+
+## Process
+
+### 1. Analyze Project Structure
+
+List all tracked files:
+!`git ls-files`
+
+Show directory structure:
+On Linux, run: `tree -L 3 -I 'node_modules|__pycache__|.git|dist|build'`
+
+### 2. Read Core Documentation
+
+- Read the PRD.md or similar spec file
+- Read CLAUDE.md or similar global rules file
+- Read README files at project root and major directories
+- Read any architecture documentation
+- Read the drizzle config so you understand the database schema
+
+### 3. Identify Key Files
+
+Based on the structure, identify and read:
+
+- Main entry points (main.py, index.ts, app.py, etc.)
+- Core configuration files (pyproject.toml, package.json, tsconfig.json)
+- Key model/schema definitions
+- Important service or controller files
+
+### 4. Understand Current State
+
+Check recent activity:
+!`git log -10 --oneline`
+
+Check current branch and status:
+!`git status`
+
+## Output Report
+
+Provide a concise summary covering:
+
+### Project Overview
+
+- Purpose and type of application
+- Primary technologies and frameworks
+- Current version/state
+
+### Architecture
+
+- Overall structure and organization
+- Key architectural patterns identified
+- Important directories and their purposes
+
+### Tech Stack
+
+- Languages and versions
+- Frameworks and major libraries
+- Build tools and package managers
+- Testing frameworks
+
+### Core Principles
+
+- Code style and conventions observed
+- Documentation standards
+- Testing approach
+
+### Current State
+
+- Active branch
+- Recent changes or development focus
+- Any immediate observations or concerns
+
+**Make this summary easy to scan - use bullet points and clear headers.**
diff --git a/GEMINI.md b/GEMINI.md
new file mode 100644
index 0000000..7d8e31c
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1,118 @@
+# GEMINI.md
+
+This file provides guidance to Gemini when working with code in this repository.
+
+## Project Overview
+
+**Teklifsat Platform**: A multi-tenant AI lead generation platform that automates the prospecting pipeline from LinkedIn search to AI-powered qualification and outreach. It uses Unipile for LinkedIn API integration and Next.js/Supabase as its core stack.
+
+---
+
+## Tech Stack
+
+| Technology     | Purpose                                         |
+| -------------- | ----------------------------------------------- |
+| **Next.js**    | Frontend framework (App Router)                 |
+| **Supabase**   | Database, Auth, Realtime, Edge Functions        |
+| **TypeScript** | Static typing and enhanced developer experience |
+| **Tailwind**   | Styling and responsive design                   |
+| **Radix UI**   | Accessible UI primitives                        |
+| **Lucide**     | Icon set                                        |
+| **Playwright** | End-to-end testing                              |
+| **Unipile**    | LinkedIn Multi-account API integration          |
+
+---
+
+## Commands
+
+```bash
+# Development
+npm run dev
+
+# Build
+npm run build
+
+# Start Production
+npm run start
+
+# Lint
+npm run lint
+
+# Documentation (refer to docs/)
+# Migrations (refer to migrations/)
+```
+
+---
+
+## Project Structure
+
+```
+app/              # Next.js App Router (Routes, API, Layouts)
+├── api/          # Backend API routes
+├── auth/         # Authentication flow
+├── dashboard/    # Dashboard pages and logic
+└── onboarding/   # User onboarding steps
+components/       # UI and feature components
+├── ui/           # Radix-based UI building blocks
+└── ...           # Feature-specific components (auth, linkedin)
+lib/              # Shared logic and libraries
+├── supabase/     # Supabase client and server-side utilities
+└── utils.ts      # UI helper functions (cn)
+migrations/       # Database schema migrations
+e2e/              # Playwright E2E tests
+docs/             # Project documentation
+```
+
+---
+
+## Architecture
+
+The application follows the **Next.js App Router** patterns with server/client component separation.
+
+- **Frontend**: React client components for interactive UI, Server Components for data fetching.
+- **Backend API**: Next.js API routes handling business logic and integration with external APIs (Unipile, AI models).
+- **Data Layer**: Supabase for relational data, authentication, and file storage.
+- **Flow**: Multi-tenant data model where organizations/teams manage campaigns, leads, and outreach.
+
+---
+
+## Code Patterns
+
+### UI & Styling
+
+- Use the `cn` utility from `lib/utils.ts` for dynamic class merging.
+- Prefer Radix UI primitives and Tailwind CSS for custom components.
+- Maintain consistency with the `globals.css` variable-based theme system.
+
+### Database & Auth
+
+- Use `lib/supabase/server.ts` for server-side actions/routes.
+- Use `lib/supabase/client.ts` for interactive client components.
+- Leverage Supabase Auth for user identity and organization-based access control.
+
+---
+
+## Testing
+
+- **E2E Tests**: Located in `e2e/`, using Playwright.
+- **Run tests**: `npx playwright test`
+
+---
+
+## Key Files
+
+| File                     | Purpose                                       |
+| ------------------------ | --------------------------------------------- |
+| `app/layout.tsx`         | Global structure and context providers.       |
+| `lib/supabase/server.ts` | Supabase server-side client factory.          |
+| `lib/supabase/client.ts` | Supabase browser-side client factory.         |
+| `package.json`           | Dependency management and script definitions. |
+| `tailwind.config.ts`     | UI theme and styling configuration.           |
+
+---
+
+## AI Agent Guidelines
+
+- **Database Operations**: GEMINI / Antigravity has access to the `supabase-mcp` server. This tool **must** be used for all database-related operations, including schema exploration, table creation, and performing queries, to ensure accuracy and consistency with the Supabase environment.
+
+---