# Task: Expand AGENTS.md for Enterprise AI Development Standards

Your role is Principal Software Architect, Staff Engineer, Enterprise UI/UX Architect, and AI Workflow Designer.

## Objective

Review the existing `AGENTS.md` and evolve it into a more complete AI engineering guide.

This is an expansion task, NOT a rewrite.

The existing document already contains valuable project rules. Preserve them and extend them where appropriate.

---

## Primary Goal

Improve AI collaboration quality without changing the project's architecture or development philosophy.

The updated AGENTS.md should better support AI coding agents such as Codex, Claude Code, Gemini CLI, Cursor, Windsurf, and future coding assistants.

---

## Requirements

### 1. Preserve Existing Rules

Do NOT remove existing sections unless they are clearly obsolete.

Keep existing:

* Architecture rules
* Foundation reuse
* Governance
* Historical review
* Authentication
* React Query
* CRUD rules
* Date formatting
* Route Handler patterns
* Project structure
* Coding conventions

Improve wording only if necessary.

---

### 2. Add Missing Enterprise Sections

Expand AGENTS.md with new sections where appropriate.

Possible additions include:

### AI Workflow

Define the expected workflow before implementation.

Example:

* Requirement Analysis
* Historical Review
* Architecture Review
* Existing Pattern Discovery
* Implementation Plan
* Implementation
* Self Review
* Validation
* Delivery

---

### Existing Pattern Discovery

Before creating any new:

* Component
* Hook
* Utility
* Dialog
* Service
* API
* Layout
* Table
* Form
* Provider

AI MUST search the project for an existing implementation.

Reuse before creating.

---

### AI Skill Composition

Define responsibilities for external AI skills.

Example:

Project Standards
↓
Architecture
↓
Existing Code Pattern
↓
External Skill
↓
UI Polish

Separate responsibilities such as:

* Code architecture
* Code pattern
* UI/UX
* Accessibility
* Performance
* Documentation

Project rules always have highest priority.

---

### UI/UX Quality Standards

Add enterprise UI expectations.

Examples:

* visual hierarchy
* spacing consistency
* typography hierarchy
* responsive layouts
* dark mode
* loading state
* empty state
* error state
* skeleton loading
* accessibility
* keyboard navigation
* consistent action placement

---

### Design Review Checklist

Require AI to verify:

* readability
* consistency
* spacing
* responsiveness
* accessibility
* component reuse
* visual balance
* unnecessary complexity
* enterprise appearance

before considering a task complete.

---

### Refactoring Policy

Encourage:

* improve existing code
* extend existing modules
* minimize breaking changes

Avoid:

* unnecessary rewrites
* duplicate implementations
* introducing new patterns without justification

---

### Component Reuse Policy

Before creating:

* Card
* Table
* Dialog
* Form
* Toolbar
* Action Bar
* Preview Panel
* Status Badge

AI must search for reusable components first.

---

### Enterprise Dashboard Standards

When implementing dashboard pages:

Prefer:

* clear information hierarchy
* balanced layouts
* action grouping
* summary cards
* sticky action panels when appropriate
* proper whitespace
* predictable navigation

Avoid visual clutter.

---

### Self Review Section

Before considering implementation complete, AI must verify:

✓ Architecture follows project standards

✓ Existing foundations reused

✓ Existing APIs reused

✓ Existing components reused

✓ No duplicated business logic

✓ UI consistency maintained

✓ Accessibility considered

✓ Responsive layout verified

✓ Loading/Error/Empty states implemented

✓ Code remains maintainable

---

### Future Compatibility

The AGENTS.md should remain AI-agnostic.

Do not reference only one AI tool.

The guidance should work equally well with:

* Codex
* Claude Code
* Cursor
* Gemini CLI
* Windsurf
* Cline
* future coding agents

---

## Constraints

* Do NOT change business rules.
* Do NOT change architecture.
* Do NOT replace existing standards.
* Expand rather than rewrite.
* Preserve backward compatibility.

---

## Expected Deliverables

1. Review summary

Explain:

* what already exists
* what is missing
* why each new section is valuable

2. Updated AGENTS.md

Integrate new sections into appropriate locations.

Avoid duplication.

Maintain a consistent writing style.

3. Change Summary

Categorize changes into:

* Added
* Expanded
* Clarified
* Deprecated (if any)

4. Quality Review

Verify the final AGENTS.md is:

* internally consistent
* free of conflicting rules
* suitable for long-term maintenance
* optimized for AI-assisted enterprise software development