AGENTS.md

1---
2name: alpha-template
3description: "Development assistant for a web application. TypeScript/React with strict typing, MUI, Redux Toolkit, AG Grid, form validation."
4metadata:
5  version: "1.0"
6  skills:
7    - typescript
8    - javascript
9    - react
10    - webpack
11    - redux-toolkit
12    - mui
13    - ag-grid
14    - form-validation
15    - html
16    - a11y
17    - code-conventions
18    - technical-communication
19    - critical-partner
20    - interface-design
21    - frontend-dev
22---
23 
24# Alpha Template Agent
25 
26## Purpose
27 
28Primary development assistant for a web application. Ensures strict typing, MUI best practices, accessibility, and version compatibility across Redux Toolkit, AG Grid, and form validation integrations.
29 
30## How to Use Skills (MANDATORY WORKFLOW)
31 
32This project has skills installed in your model's skills directory. Follow this protocol for ALL coding tasks:
33 
34### Step 1: Find the Trigger
35 
36Check the "Skills Reference" table below. Match your task to the "Trigger" column.
37 
38### Step 2: Read the Skill
39 
40**Path format:** `.{model}/skills/{skill-name}/SKILL.md`
41 
42Replace `{model}` with your coding agent:
43 
44- **Cursor:** `.cursor/skills/typescript/SKILL.md`
45- **Claude:** `.claude/skills/typescript/SKILL.md`
46- **Copilot:** `.github/skills/typescript/SKILL.md`
47- **Gemini:** `.gemini/skills/typescript/SKILL.md`
48- **Codex:** `.codex/skills/typescript/SKILL.md`
49 
50### Step 3: Read Dependencies
51 
52Every skill lists dependencies in its frontmatter (`metadata.skills`). Read each direct dependency before proceeding.
53 
54**Example:** `react` skill depends on: `a11y`, `typescript`, `javascript`, `architecture-patterns`
55 
56Read these 4 direct dependencies. Dependencies are resolved transitively - when you read `typescript`, you'll see it depends on `javascript`, which depends on `code-conventions`. The dependency chain ensures you have all required context.
57 
58### Step 4: Apply Patterns
59 
60- Follow "Critical Patterns" marked with ✅ REQUIRED
61- Use "Decision Tree" for implementation choices
62- Reference inline code examples
63 
64### Example Workflow
65 
66**Task:** "Create TypeScript interface for User model"
67 
681. **Check table below** → Trigger: "TypeScript types/interfaces" → Skill: `typescript`
692. **Read:** `.{model}/skills/typescript/SKILL.md`
703. **Check frontmatter** → Dependencies: `javascript`
714. **Read dependency:**
72   - `.{model}/skills/javascript/SKILL.md` (which depends on `code-conventions`)
735. **Apply patterns:** Use `interface` (not `type`), PascalCase names, export from `types/` directory
74 
75## Skills Reference
76 
77**Path format:** `.{model}/skills/{skill-name}/SKILL.md` (see Step 2 above)
78 
79| Trigger                       | Skill                   |
80| ----------------------------- | ----------------------- |
81| TypeScript types/interfaces   | typescript              |
82| JavaScript (ES2020+)          | javascript              |
83| React components/hooks        | react                   |
84| Webpack build config          | webpack                 |
85| Redux state / RTK Query       | redux-toolkit           |
86| MUI components/theming        | mui                     |
87| AG Grid tables                | ag-grid                 |
88| Forms, validation schemas     | form-validation         |
89| Commit messages, PRs, docs    | technical-communication |
90| Code review                   | critical-partner        |
91| Semantic HTML                 | html                    |
92| Accessibility                 | a11y                    |
93| Coding standards              | code-conventions             |
94| UI/UX design, flows           | interface-design        |
95| Frontend development workflow | frontend-dev            |
96 
97## Project Structure & Skills Storage
98 
99**IMPORTANT FOR LLMs:** Skills use a 3-layer symlink structure:
100 
101```
102your-project/
103├── .agents/skills/        # Canonical symlinks to framework skills/ (shared across models)
104│   ├── react/            → ../../skills/react/
105│   ├── typescript/       → ../../skills/typescript/
106│   └── ...
107├── .claude/skills/        # Claude-specific symlinks to .agents/skills/
108│   ├── react/            → ../../.agents/skills/react/
109│   └── typescript/       → ../../.agents/skills/typescript/
110├── .cursor/skills/        # Cursor-specific symlinks to .agents/skills/
111├── .github/skills/        # Copilot-specific symlinks to .agents/skills/
112├── .gemini/skills/        # Gemini-specific symlinks to .agents/skills/
113├── .codex/skills/         # Codex-specific symlinks to .agents/skills/
114└── AGENTS.md             # This file
115```
116 
117**How to access skills:**
118 
119- **Preferred:** Read from `.{model}/skills/<skill-name>/SKILL.md` (your model's directory)
120- **If symlinks fail:** Skills are stored in the ai-agents-skills framework installation (referenced via symlinks)
121- **Real files location:** All source skills are in the framework's `skills/` directory
122 
123**Why 3 layers?**
124 
1251. **Layer 1 (framework skills/):** Source of truth maintained by framework
1262. **Layer 2 (.agents/skills/):** Canonical shared location in your project
1273. **Layer 3 (.{model}/skills/):** Model-specific access for your AI assistant
128 
129**Benefits:**
130 
131- **Zero duplication:** Skills installed once, available to all 5 AI models
132- **Always up-to-date:** Changes propagate instantly via symlinks
133- **Token-efficient:** Your AI reads only the skills it needs
134 
135## Supported Stack
136 
137- **Languages:** TypeScript 5.6.2, JavaScript (ES2020+)
138- **Frameworks:** React 18.3.1, Webpack (latest)
139- **State:** Redux 5.0.1, React-Redux 9.2.0, Redux Toolkit 2.5.1, RTK Query
140- **UI:** MUI 5.15.14, MUI X Charts 7.7.1, MUI X Date Pickers Pro 5.0.20
141- **Data:** AG Grid (latest stable)
142- **Forms:** Context-aware (see form-validation skill — checks package.json for installed library)
143- **Build:** Webpack
144- **Code Quality:** Context-aware (see code-quality skill — checks package.json for installed tools)
145 
146## Workflows
147 
148### Feature Development
149 
1501. Gather requirements and clarify acceptance criteria
1512. Design component architecture with TypeScript interfaces
1523. Implement React components using MUI
1534. Configure Redux Toolkit slices / RTK Query endpoints
1545. Implement forms with validation (see form-validation skill)
1556. Ensure accessibility (semantic HTML, ARIA, keyboard nav)
1567. Test with strict TypeScript, document changes, request review
157 
158### Code Review
159 
1601. Verify strict TypeScript (no `any`, explicit return types)
1612. Check MUI usage, theming consistency, accessibility
1623. Review Redux patterns and RTK Query cache config
1634. Confirm version compatibility with supported stack
164 
165## Policies
166 
167**Typing:** strict mode, no `any` (use `unknown`/generics), explicit return types, prefer interfaces
168 
169**Code quality:** Context-aware linting and formatting (see code-quality skill), format before committing
170 
171**Accessibility:** Semantic MUI components, keyboard-accessible elements, proper heading hierarchy, labeled form fields
172 
173**Versions:**
174 
175- Exact: TypeScript 5.6.2, React 18.3.1, RTK 2.5.1, MUI 5.15.14
176- Ranges: TS >=5.4 <6.0, React >=18.0 <19.0, RTK >=1.8 <3.0, MUI >=5.0 <6.0
177