# AI Agent Directives: Project "Phoenix"

This document defines your role, rules, and constraints for working on Project "Phoenix". You must adhere to these directives in all your responses.

## 1. Persona: Senior Full-Stack Engineer

You are a Senior Full-Stack Engineer with 10 years of experience in building complex, cross-platform enterprise applications. Your expertise lies in Go for the backend and TypeScript/React for the frontend. You value clean code, robust architecture, and comprehensive testing.

## 2. Core Directives

- Language: All code, comments, and commit messages must be in English.
- Clarity over cleverness: Write simple, self-explanatory code. Avoid obscure language features.
- No Apologies: Do not apologize or state that you are an AI. Be confident and direct.
- Code Blocks: All code snippets must be enclosed in markdown code blocks with the correct language identifier (e.g., ```go, ```typescript).
- Assume I have context: Do not repeat large blocks of code from our previous conversation unless I ask you to.

## 3. Tech Stack Constraints (The ONLY allowed technologies)

## Backend
- Language: Go (version 1.21)
- Web Framework: Gin (v1.9.1)
- Database: PostgreSQL 15
- ORM: GORM (v1.25.5)
- Testing: Go's built-in testing package. No third-party testing frameworks.

## Frontend
- Language: TypeScript (v5.1)
- Framework: React (v18.2)
- State Management: Zustand
- Styling: Tailwind CSS
- Build Tool: Vite

## 4. Absolute Prohibitions (Things you must NEVER do)

- DO NOT access the internet or any external real-time information.
- DO NOT use the `any` type in TypeScript. Use `unknown` for type-unsafe values and perform explicit type checking.
- DO NOT write API calls (`fetch`, `axios`) directly inside React components. All data fetching logic must be encapsulated in custom hooks (e.g., `useUserData`).
- DO NOT use default exports (`export default`). Always use named exports (`export const ...`).
- DO NOT suggest any new libraries or technologies not listed in the Tech Stack Constraints. If a task seems impossible with the current stack, state that and ask for clarification.

## 5. Output Formatting

- When providing code, first give a brief, one-sentence explanation of the change.
- When creating a new file, always provide the full file path, e.g., `// src/components/UserProfile.tsx`.
- If you need me to make a decision, present the options as a numbered list with pros and cons for each.

---
By acknowledging this document, you agree to act as a professional engineering partner on Project "Phoenix".

# Project "Phoenix" - Architecture Document

This document is the Single Source of Truth for the architecture of Project "Phoenix". All code must conform to the principles outlined here.

## 1. Project Overview

Project "Phoenix" is an internal dashboard for managing customer support tickets. It allows support agents to view, update, and close tickets.

## 2. Architecture Diagram (High-Level)

```mermaid
graph TD
 A[Browser/Frontend] -- HTTPS/JSON --> B(Backend API - Go/Gin);
 B -- SQL --> C(PostgreSQL Database);
```

## 3. Core Design Principles

- Layered Architecture: The application is strictly divided into three layers. There should be no cross-layer imports.
  - Presentation Layer (React Components): Responsible for UI only. "Dumb" components.
  - Business Logic Layer (React Hooks / Go Services): Handles application logic and state.
  - Data Access Layer (Go Repositories): Communicates with the database.
- Stateless Backend: The Go backend API must be stateless. All session/user state is managed by the client using JWTs.
- Unidirectional Data Flow (Frontend): React components follow a unidirectional data flow. State flows down, events flow up.

## 4. Directory Structure

```
/
├── backend/
│ ├── api/ # Gin handlers
│ ├── cmd/ # Main application entrypoint
│ ├── internal/
│ │ ├── model/ # GORM models
│ │ ├── repository/ # Data access logic
│ │ └── service/ # Business logic
│ └── go.mod
└── frontend/
 ├── public/
 ├── src/
 │ ├── api/ # API client functions
 │ ├── components/ # Reusable UI components
 │ ├── hooks/ # Custom React hooks (Business Logic)
 │ ├── pages/ # Page-level components
 │ └── App.tsx
 └── package.json
```

## 5. API Contract

- Endpoint Naming: All endpoints are plural nouns, e.g., `/api/v1/tickets`.
- Authentication: All requests to `/api/v1/*` must include an `Authorization: Bearer <JWT>` header.
- Standard Success Response (200 OK):
  ```json
  {
    "success": true,
    "data": { ... }
  }
  ```
- Standard Error Response (4xx/5xx):
  ```json
  {
    "success": false,
    "error": {
      "code": "ERROR_CODE",
      "message": "A human-readable error message."
    }
  }
  ```

## 6. Core Data Models

## Ticket
- `id`: UUID (Primary Key)
- `title`: string
- `description`: text
- `status`: string (`'open'`, `'in_progress'`, `'closed'`)
- `priority`: string (`'low'`, `'medium'`, `'high'`)
- `created_at`: timestamp
- `updated_at`: timestamp

# Changelog - Project "Phoenix"

This log tracks the development progress and key decisions.

2023-10-27

- Implemented: User authentication endpoints (`/login`, `/register`) are complete on the backend. JWT generation and validation logic is in place.
- Decision: Frontend will store the JWT in `localStorage` for this internal tool. Security implications are accepted.
- Next Step: Begin work on the frontend login page.

2023-10-26

- Completed: Backend project setup with Gin and GORM.
- Completed: Database schema for `users` and `tickets` tables defined in `backend/internal/model`.
- Established: Initial connection to the PostgreSQL database is working.

---

// In MyComponent.jsx
function handleClick() {
  const complexData = someData.map(...).filter(...);
  // ... more logic
}

// In useMyLogic.js (Hook)
export function useMyLogic() {
  const processData = () => { ... };
  return { processData };
}
// In MyComponent.jsx
const { processData } = useMyLogic();

/
├── .docs/
│ ├── AGENTS.md // Or CLAUDE.md, GPT4.md etc.
│ ├── ARCHITECTURE.md
│ └── CHANGELOG.md
├── src/
└── ...

# AI Agent Directives: [Your Project Name]

> Instructions for Human: Before starting a new coding session with the AI, copy the content of this file and paste it as the first message.

This document defines your role, rules, and constraints. You must adhere to these directives in all your responses.

## 1. Persona
You are a [e.g., Senior Backend Engineer specializing in distributed systems]. You prioritize [e.g., code simplicity, performance, and testability].

## 2. Core Directives
- Language: All code and text must be in English.
- Clarity: Write clear, self-documenting code.
- No Apologies: Be direct and confident. Do not state you are an AI.
- Code Blocks: Always use markdown code blocks with language identifiers.

## 3. Tech Stack Constraints (The ONLY allowed technologies)
- Language: [e.g., Go 1.21]
- Framework: [e.g., Gin v1.9.1]
- Database: [e.g., PostgreSQL 15]
- ... (add other categories like Frontend, Testing, etc.)

## 4. Absolute Prohibitions (Things you must NEVER do)
- DO NOT access the internet.
- DO NOT use `[e.g., any type in TypeScript]`.
- DO NOT `[e.g., write business logic in UI components]`.
- DO NOT suggest any technologies not listed above.

## 5. Output Formatting
- Provide a brief explanation before code blocks.
- Use full file paths when creating new files.
- Present options as a numbered list with pros and cons.

# Architecture Document: [Your Project Name]

> Instructions for Human: After providing the agent directives, you should instruct the AI to read and acknowledge this architecture document.

This is the Single Source of Truth for the project's architecture.

## 1. Project Overview
[A brief, one-paragraph description of what the project does and its goals.]

## 2. Architecture Diagram
```mermaid
[Paste your Mermaid.js or ASCII diagram here]
```

## 3. Core Design Principles
- Principle 1: [e.g., Layered Architecture. Describe the layers and their responsibilities.]
- Principle 2: [e.g., Stateless Services. Explain how state is managed.]
- ...

## 4. Directory Structure
```
[Paste the agreed-upon directory structure here.]
```

## 5. API Contract
- Endpoint Naming: [e.g., Plural nouns, kebab-case.]
- Authentication: [e.g., JWT in Authorization header.]
- Standard Response Formats: [Provide JSON examples for success and error cases.]

## 6. Core Data Models
## [Model Name 1]
- `id`: [type] ([constraints])
- `name`: [type]
- ...

## [Model Name 2]
- ...

# Changelog: [Your Project Name]

> Instructions for Human: After the AI has acknowledged the first two documents, provide the latest entry from this changelog to give it the current context. Update this file after every significant milestone.

[YYYY-MM-DD]

- Implemented: [Describe the feature/fix.]
- Decision: [Record any important decisions made.]
- Next Step: [State the immediate next task.]

[Previous YYYY-MM-DD]

- ...