AI Agents

Plainform includes context files for AI coding agents (Cursor, GitHub Copilot, Windsurf, etc.) to understand the project structure and best practices. These files are included in the repository and automatically detected by most AI agents.

Agent Workflow Files

The .agent/workflows/ folder contains markdown files that provide context to AI agents. These files are committed to the repository so all team members benefit from consistent AI assistance:

File Descriptions

How AI Agents Use These Files

Cursor

Cursor automatically reads .agent/workflows/*.md files and uses them as context when:

• You ask questions about the project
• You request code generation
• You use Cmd+K for inline edits

No configuration needed - Cursor detects these files automatically.

GitHub Copilot

GitHub Copilot can reference these files when you:

• Use @workspace in Copilot Chat
• Ask questions about project structure
• Request code that follows project patterns

Tip: Mention "follow project conventions" in your prompts.

Windsurf

Windsurf (Codeium) automatically indexes .agent/ files and uses them for:

• Code completion
• Chat responses
• Refactoring suggestions

No configuration needed - Windsurf detects these files automatically.

Other Agents

For agents that don't auto-detect these files:

1. Copy relevant sections from .agent/workflows/ files
2. Paste into your prompt or agent configuration
3. Reference them when asking for code generation

Customizing for Your Product

Update Product Context

The .agent/workflows/product.md file contains generic starter kit information. You should customize it to describe your specific product so AI agents understand your application's purpose and features.

Example prompt to update product.md:

Update .agent/workflows/product.md to describe my product:

Product Name: TaskFlow
Description: A project management SaaS for remote teams
Key Features:
- Real-time collaboration with team workspaces
- Kanban boards and sprint planning
- Time tracking and reporting
- Slack and GitHub integrations
- Custom workflows and automation

Target Audience: Remote software development teams (5-50 people)
Pricing Model: Tiered subscription ($10/user/month for Pro, $20/user/month for Enterprise)

Keep the same structure as the current file but replace the generic content with TaskFlow-specific information.

After updating, AI agents will have accurate context about your product when generating code, documentation, or making architectural suggestions.

Updating Agent Context

When you make significant changes to the project, update these files:

Update best-practices.md when:

• Adding new coding patterns
• Changing authentication flow
• Updating security practices
• Adopting new libraries

Update product.md when:

• Adding major features
• Changing target audience
• Modifying core functionality

Update project-structure.md when:

• Reorganizing folders
• Changing naming conventions
• Adding new component patterns

Update tech-stack.md when:

• Upgrading major dependencies
• Adding new libraries
• Changing build configuration
• Updating commands

Example: Using Agent Context

Prompt without context:

Create a new pricing card component

Prompt with context awareness:

Create a new pricing card component following our project conventions:
- Use PascalCase naming (PricingCard.tsx)
- Place in components/pricing/
- Use Radix UI primitives
- Export with class-variance-authority variants
- Follow our Tailwind class ordering

The AI agent will reference .agent/workflows/project-structure.md and .agent/workflows/best-practices.md to generate code that matches your project style.

Best Practices for AI-Assisted Development

1. Reference context files in prompts: "Follow our authentication patterns from best-practices.md"
2. Be specific about conventions: "Use our naming conventions for interfaces (I prefix)"
3. Mention file locations: "Create in components/ui/ following our structure"
4. Ask for pattern matching: "Match the style of existing components"
5. Request validation: "Ensure this follows our security best practices"

Troubleshooting

Agent not following conventions:

• Check if .agent/workflows/ files are up to date
• Explicitly reference the files in your prompt
• Restart your AI agent/IDE

Agent suggesting outdated patterns:

• Update the relevant .agent/workflows/ file
• Clear agent cache (if applicable)
• Mention "use latest Next.js 16 patterns"

Agent not aware of project structure:

• Verify .agent/workflows/project-structure.md exists
• Check file permissions (should be readable)
• Try referencing the file explicitly in your prompt

Next Steps

• MCP Servers - Extend AI agents with specialized capabilities
• Environment Variables - Configure your environment
• Git Workflow - Commit conventions
• Best Practices - Coding standards