Agent Instructions for Link Shortener Project

This file serves as the entry point for AI coding assistants (LLMs) working on this project.

🤖 Multi-Agent Architecture

This project uses a three-agent workflow to ensure code quality and instruction compliance:

Agent Roles

📋 Code Manager Agent (.github/agents/code-manager.agent.md)
- Role: Orchestrator
- Responsibility: Coordinates workflow between agents
- Tasks: Requirement analysis, agent delegation, quality assurance
🔨 Component Implementation Agent (.github/agents/component-implementer.agent.md)
- Role: Code Generator
- Responsibility: Creates React components and server logic
- Tasks: TypeScript/React code generation following instruction files
🔍 Code Review Agent (.github/agents/code-reviewer.agent.md)
- Role: Quality Gatekeeper
- Responsibility: Validates code against standards
- Tasks: Pattern validation, React best practices, security review

Workflow Process

User Request
     ↓
[Manager Agent]
     ├─→ Identifies relevant instruction files
     ├─→ Reads documentation
     └─→ Creates implementation plan
          ↓
[Implementation Agent]
     ├─→ Reads instruction files
     ├─→ Generates code following patterns
     └─→ Submits implementation
          ↓
[Code Review Agent]
     ├─→ Validates against instruction files
     ├─→ Checks React best practices
     └─→ Provides verdict (APPROVE/REQUEST CHANGES/REJECT)
          ↓
     [If changes needed]
          ↓
     [Implementation Agent fixes]
          ↓
     [Review Agent re-validates]
          ↓
[Manager Agent]
     └─→ Delivers final validated code to user

🎯 Quick Start for AI Assistants

⚠️ MANDATORY: Documentation-First Workflow

🚨 NON-NEGOTIABLE REQUIREMENT 🚨

BEFORE writing a SINGLE LINE of code, you MUST:

✅ READ THE ENTIRE relevant documentation file(s) - No exceptions, no shortcuts
✅ FOLLOW ALL rules and patterns specified in those files - These are requirements, not suggestions
✅ ONLY THEN generate code that strictly adheres to the documented standards

❌ FAILURE TO READ DOCUMENTATION = INVALID CODE

If you generate code without first reading the relevant instruction files, your implementation will be rejected. This is not a "nice to have" - it is a hard requirement.

Priority Guidelines

Always use TypeScript with strict mode - never use any
Prefer Server Components - only use 'use client' when necessary
Use Server Actions for mutations - avoid API routes for internal operations
Write self-documenting code - clear names, proper types, minimal comments

API Management & Error Boundary Standards

Technical Context & Dependencies

The primary data layer for this project is RTK Query. Before generating any API slices, hooks, or data-handling logic, you MUST refer to data-fetching.instructions.md. You are required to strictly follow the RTK Query patterns and the "HTTP 200 Only" validation logic defined therein. Do not suggest alternative fetching implementations (e.g., standard fetch, axios) unless explicitly requested.

Strict HTTP 200 Policy

The system enforces a strict contract where only an HTTP 200 status code is treated as a successful state update. In all baseQuery or transformResponse logic, you must intercept any non-200 status (including 201, 204, or 4xx/5xx). If the status is not 200, the error must be formatted and returned to the RTK Query error state to prevent invalid data from entering the cache.

Error Boundary Strategy

The application utilizes a dual-layer error strategy:

Global Boundary: High-level failures (Network Errors, 500s) should bubble up to the global Error Boundary or be intercepted by middleware for global notifications (Toasts/Modals).
Feature Boundary: For feature-specific components, generate code that monitors the error property from RTK Query hooks.
Triggering Boundaries: If an API error is critical to a component's lifecycle, use the following pattern to throw the error to the nearest Error Boundary:
```
if (error) throw error; // Triggers the nearest React Error Boundary
```

Tech Stack Quick Reference

// Framework
Next.js 16 (App Router) + React 19 + TypeScript 5

// Styling
Tailwind CSS 4 + shadcn/ui (new-york style)

// Database
Neon PostgreSQL + Drizzle ORM

// Authentication
Clerk

// Icons
Lucide React

File Organization

app/                  # Next.js App Router
├── actions/         # Server Actions (mutations)
├── api/            # API routes (webhooks, public APIs)
├── [shortCode]/    # Dynamic redirect route
└── dashboard/      # Protected dashboard pages

db/                  # Database
├── schema.ts       # Drizzle schema definitions
├── index.ts        # DB instance
└── queries/        # Query functions

components/          # React components
├── ui/             # shadcn/ui components
└── [feature]/      # Feature-specific components

lib/                # Utilities
└── utils.ts        # Helper functions

.github/
├── agents/         # Agent instruction files
└── instructions/   # Development instruction files

Common Patterns

Server Component with Data Fetching

import db from "@/db";

export default async function Page() {
  const data = await db.query.users.findMany();
  return <div>{/* render */}</div>;
}

Server Action for Mutation

"use server";
import { auth } from "@clerk/nextjs/server";
import { revalidatePath } from "next/cache";

export async function createItem(data: FormData) {
  const { userId } = await auth();
  if (!userId) return { success: false, error: "Unauthorized" };
  
  // Mutation logic
  revalidatePath("/dashboard");
  return { success: true };
}

Client Component with Interaction

'use client';
import { useState } from 'react';

export function InteractiveComponent() {
  const [state, setState] = useState();
  return <button onClick={() => setState(...)}>Click</button>;
}

🔑 Core Principles

Type Safety - Leverage TypeScript's type system fully
Server-First - Default to server components and server actions
User Experience - Responsive design, loading states, error handling
Security - Validate all inputs, check authentication, sanitize data
Performance - Optimize database queries, use proper indexing, lazy load when needed
Consistency - Follow established patterns throughout the codebase

🚀 Getting Started

🛑 PRE-IMPLEMENTATION CHECKPOINT

Before you proceed with ANY task, answer these questions:

✅ Have I identified which instruction files are relevant to this task?
✅ Have I read those instruction files in their ENTIRETY?
✅ Do I understand the patterns and rules I need to follow?
✅ Am I ready to implement code that strictly follows those patterns?

If you answered "NO" to ANY question, STOP and read the documentation first.

📚 MANDATORY Reading by Feature

🔴 STOP - READ FIRST - CODE SECOND 🔴

**You MUST read the relevant instruction files B.github/instructions/feature-organization.instructions.md

Authentication & User Management → .github/instructions/authentication-rules.instructions.md
Data Fetching & RTK Query → .github/instructions/data-fetching.instructions.md
Server Actions & Mutations → .github/instructions/server-actions.instructions.md
UI Components → .github/instructions/ui-components.instructions.md
React Best Practices → .github/instructions/react-double-check-instructions.md
UI Components → ui-components.instructions.md
React Best Practices → react-double-check-instructions.md

🚫 Common Mistakes to Avoid

❌ CRITICAL ERROR #1: Writing code without reading the relevant `instructions` files first

This is the #1 mistake and will result in code rejection. ALWAYS read documentation FIRST.

Other Violations:

❌ Using custom UI components instead of shadcn/ui (violates ui-components.instructions.md)
❌ Implementing custom auth instead of Clerk (violates authentication-rules.instructions.md)
❌ Using direct Drizzle queries in server actions (violates server-actions.instructions.md)
❌ Skipping Zod validation in server actions (violates server-actions.instructions.md)
❌ Creating API routes for mutations instead of server actions (violates server-actions.instructions.md)
❌ Ignoring established patterns in the documentation

✅ Task Completion Protocol

AFTER completing ANY code generation task, you MUST provide:

Summary Format:

## 📝 Task Summary

### ✅ Documentation Compliance Checklist (REQUIRED)
**I CONFIRM that I have:**
- [x] Read the COMPLETE instruction file(s) BEFORE writing code
- [x] Followed ALL patterns and rules from the documentation
- [x] Not generated any code without consulting the relevant docs

### Agent Workflow Completed
- [x] Manager Agent: Analyzed requirements and identified instruction files
- [x] Implementation Agent: Generated code following documented patterns
- [x] Review Agent: Validated code against instruction files - **APPROVED**

### What Was Implemented
- Brief description of the feature/fix

### Files Mod.github/instructions/data-fetching.instructions.md`
- [x] Read: `.github/instructions/server-actions.instructions.md`

### Patterns Applied
- ✅ Used RTK Query for data fetching
- ✅ Implemented Zod validation
- ✅ Added proper error handling
- ✅ HTTP 200 only policy enforced

### Code Review Results
- ✅ TypeScript strict mode compliant
- ✅ Server components by default
- ✅ Authentication checked
- ✅ Error boundaries configuredtructions.md`

### Patterns Applied
- ✅ Used RTK Query for data fetching
- ✅ Implemented Zod validation
- ✅ Added proper error handling

### Testing Recommendations
- [ ] Test the new feature in development
- [ ] Verify authentication flow
- [ ] Check error boundaries

### Next Steps (if applicable)
## 🎯 Agent Activation

When working on this project:

1. **Manager Agent** identifies the task scope and relevant instruction files
2. **Implementation Agent** generates code following documented patterns
3. **Review Agent** validates the implementation
4. **Manager Agent** delivers final approved code

This ensures **every line of code** is validated against project standards before delivery.

---

- Consider adding unit tests for X
- May need to update Y when Z is implemented

Enforcement Rules

No code delivery without summary - The task is not complete until the summary is provided
Be specific - Reference actual file paths and line numbers
Link to docs - Mention which instruction files guided your implementation
Flag deviations - If you deviated from documented patterns, explain why

Note: This project follows modern Next.js 15+ conventions with App Router, Server Components, and Server Actions as the primary patterns.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Agent Instructions for Link Shortener Project

🤖 Multi-Agent Architecture

Agent Roles

Workflow Process

🎯 Quick Start for AI Assistants

⚠️ MANDATORY: Documentation-First Workflow

Priority Guidelines

API Management & Error Boundary Standards

Technical Context & Dependencies

Strict HTTP 200 Policy

Error Boundary Strategy

Tech Stack Quick Reference

File Organization

Common Patterns

Server Component with Data Fetching

Server Action for Mutation

Client Component with Interaction

🔑 Core Principles

🚀 Getting Started

🛑 PRE-IMPLEMENTATION CHECKPOINT

📚 MANDATORY Reading by Feature

🚫 Common Mistakes to Avoid

❌ CRITICAL ERROR #1: Writing code without reading the relevant `instructions` files first

Other Violations:

✅ Task Completion Protocol

Summary Format:

Enforcement Rules

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

Agent Instructions for Link Shortener Project

🤖 Multi-Agent Architecture

Agent Roles

Workflow Process

🎯 Quick Start for AI Assistants

⚠️ MANDATORY: Documentation-First Workflow

Priority Guidelines

API Management & Error Boundary Standards

Technical Context & Dependencies

Strict HTTP 200 Policy

Error Boundary Strategy

Tech Stack Quick Reference

File Organization

Common Patterns

Server Component with Data Fetching

Server Action for Mutation

Client Component with Interaction

🔑 Core Principles

🚀 Getting Started

🛑 PRE-IMPLEMENTATION CHECKPOINT

📚 MANDATORY Reading by Feature

🚫 Common Mistakes to Avoid

❌ CRITICAL ERROR #1: Writing code without reading the relevant instructions files first

Other Violations:

✅ Task Completion Protocol

Summary Format:

Enforcement Rules

❌ CRITICAL ERROR #1: Writing code without reading the relevant `instructions` files first