commit

plans/task-expand-agents.md

@@ -0,0 +1,299 @@
+# 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