Cursor rule

1---
2description: Creating agents.md files with plain markdown format (NO frontmatter) - use when creating agents.md packages for PRPM or generating project context files
3globs: []
4alwaysApply: false
5---
6 
7# Creating agents.md Files
8 
9Quick reference for creating agents.md files - plain markdown project context for AI coding assistants.
10 
11**Schema**: https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/agents-md.schema.json
12 
13## Format Rules
14 
15| Requirement | Value |
16|------------|-------|
17| Format | Plain markdown only |
18| Frontmatter | **None** (forbidden) |
19| Structure | Free-form |
20| File | `agents.md` in project root |
21 
22## Critical Requirements
23 
241. **No frontmatter**: Pure markdown only (no YAML)
252. **Single file**: Typically `agents.md` in project root
263. **Plain markdown**: Standard markdown syntax
274. **Free-form content**: No required structure
28 
29## What to Include
30 
31**High Priority:**
32- Project overview and purpose
33- Architecture decisions and patterns
34- Tech stack and dependencies
35- File structure and organization
36- Coding conventions
37- Development workflow
38- Testing approach
39- Domain knowledge and business logic
40 
41**Skip:**
42- General programming best practices
43- Language syntax explanations
44- Framework basics
45- Obvious code quality rules
46 
47## Example: Full Stack App
48 
49```markdown
50# TaskMaster Development Guide
51 
52## Project Overview
53 
54TaskMaster is a task management application for remote teams with real-time collaboration and offline-first architecture.
55 
56## Architecture
57 
58### Frontend
59- React 18 with TypeScript
60- Vite for build tooling
61- Zustand for state management
62- Tailwind CSS for styling
63 
64### Backend
65- Node.js with Express
66- PostgreSQL with Prisma ORM
67- WebSocket for real-time features
68- Redis for caching and pub/sub
69 
70## Coding Conventions
71 
72- Use TypeScript strict mode
73- Functional components with hooks (no class components)
74- Colocate tests with source files (*.test.tsx)
75- Use Zod for runtime validation
76 
77## File Structure
78 
79\`\`\`
80src/
81  components/     # Reusable UI components
82  features/       # Feature-based modules
83  hooks/          # Custom React hooks
84  lib/            # Utility functions
85  pages/          # Route pages
86\`\`\`
87
88## Development Workflow
89
901. Create feature branch from `main`
912. Write tests first (TDD)
923. Implement feature
934. Run `pnpm test` and `pnpm lint`
945. Create PR with description
95 
96## Testing
97 
98- Vitest for unit tests
99- Playwright for E2E tests
100- 80% coverage target
101- Mock external dependencies
102```
103 
104## Example: API Project
105 
106```markdown
107# Payment Gateway API
108 
109RESTful API for payment processing with multiple payment providers.
110 
111## Tech Stack
112 
113- Node.js 20.x
114- Express
115- PostgreSQL 15
116- Stripe and PayPal integrations
117 
118## API Design
119 
120All endpoints follow REST:
121- `GET /api/payments` - List payments
122- `POST /api/payments` - Create payment
123- `PUT /api/payments/:id` - Update payment
124 
125## Error Format
126 
127\`\`\`json
128{
129  "error": {
130    "code": "PAYMENT_FAILED",
131    "message": "Payment could not be processed"
132  }
133}
134\`\`\`
135
136## Security
137
138- JWT authentication required
139- Rate limiting: 100 req/min per IP
140- Input validation with Zod
141- PCI DSS compliance
142
143## Database Conventions
144
145- snake_case for table/column names
146- UUIDs for primary keys
147- Foreign keys: `{table}_id` pattern
148```
149 
150## Writing Style
151 
152**Good - Concise:**
153```markdown
154## Testing
155- Vitest for unit tests
156- Playwright for E2E
157- 80% coverage target
158- Mock external dependencies
159```
160 
161**Bad - Verbose:**
162```markdown
163## Testing
164When you are writing tests, it's important to understand that we use Vitest
165for our unit tests because it's fast and modern. For end-to-end testing...
166```
167 
168## Common Mistakes
169 
170| Mistake | Fix |
171|---------|-----|
172| Adding YAML frontmatter | No frontmatter - plain markdown only |
173| Generic best practices | Focus on project-specific patterns |
174| Verbose explanations | Be concise - AI knows general concepts |
175| Language tutorials | Skip basics, focus on conventions |
176 
177## File Placement
178 
179Single project:
180```
181project-root/
182  agents.md
183  src/
184  package.json
185```
186 
187Monorepo (multiple files possible):
188```
189monorepo/
190  packages/
191    frontend/agents.md
192    backend/agents.md
193```
194 
195## Best Practices
196 
1971. **Be concise**: Focus on project-specific info (AI knows general practices)
1982. **Keep updated**: Review as project evolves
1993. **Real examples**: Show actual code patterns
2004. **Plain markdown**: No YAML frontmatter
2015. **Human-readable**: For both AI and humans
2026. **Project-specific**: Avoid generic advice
203 
204## Migration from Other Formats
205 
2061. **Strip frontmatter** - Remove all YAML headers
2072. **Focus content** - Keep only markdown
2083. **Combine files** - Merge multiple rules into one
2094. **Simplify** - Remove format-specific features
2105. **Plain markdown** - Standard syntax only
211 
212## References
213 
214- **Official Spec**: https://github.com/openai/agents.md
215- **Schema**: `/Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/agents-md.schema.json`
216- **Docs**: `/Users/khaliqgant/Projects/prpm/app/packages/converters/docs/agents-md.md`
217