Source Summary

--- description: RPS Digital - AI Agent Instructions & Guidelines alwaysApply: true lastUpdated: 2025-01-27 16:00 UTC audience: AI Agents --- # AI Agent Instructions for RPS Digital Comprehensive instructions and guidelines for AI agents working on the RPS Digital e-commerce platform ## 🤖 Agent Instructions Overview This guide provides specific inst

Imported Context

description: RPS Digital - AI Agent Instructions & Guidelines alwaysApply: true lastUpdated: 2025-01-27 16:00 UTC audience: AI Agents

AI Agent Instructions for RPS Digital

Comprehensive instructions and guidelines for AI agents working on the RPS Digital e-commerce platform

🤖 Agent Instructions Overview

This guide provides specific instructions for AI agents working on the RPS Digital project. Follow these guidelines to ensure consistent, high-quality contributions and proper documentation maintenance.

📚 Documentation Hierarchy

Primary Reference Order

/DOCS/project-master.md - Core project status and overview
/DOCS/ROADMAP.md - Development phases and priorities
/DOCS/CHANGELOG.md - Change history and version tracking
/DOCS/technical-reference.md - Technical setup and architecture
/DOCS/testing-and-ci.md - Testing requirements and processes

Quick Reference Files

/AGENTS.md - Root-level agent instructions (this file)
/README.md - Project overview and getting started

🎯 Core Agent Rules

1. Always Start Here

Before beginning any work:

1. Read /DOCS/project-master.md for current status
2. Check /DOCS/ROADMAP.md for immediate priorities
3. Review /DOCS/CHANGELOG.md for recent changes
4. Understand the current phase and next steps

2. Documentation Maintenance

When making changes:

1. Update /DOCS/CHANGELOG.md with detailed entry
2. Update /DOCS/ROADMAP.md if affecting phases/priorities
3. Update /DOCS/project-master.md if changing core status
4. Follow changelog format: date, time, detailed bullet points

3. Testing Requirements

Before committing changes:

1. Run: npm test (unit tests)
2. Run: npm run test:e2e (end-to-end tests)
3. Run: npm run prettier (code formatting)
4. Run: npm run build (build verification)
5. Follow testing guidelines in /DOCS/testing-and-ci.md

🔧 Technical Guidelines

Code Standards

TypeScript: Use strict typing, no any types
React: Functional components with hooks
Styling: TailwindCSS classes only
State: Redux Toolkit for global state
API: RESTful endpoints with proper error handling
SEO: Use next-seo components and JSON-LD structured data
Digital Products: Optimize for digital product specific SEO requirements

File Organization

src/
├── app/                    # Next.js App Router
│   ├── (site)/            # Main site routes
│   ├── studio/            # Sanity Studio
│   └── api/               # API routes
│       └── feeds/         # Product feeds (Google Merchant Center)
├── components/            # React components
│   └── SEO/              # SEO components (ProductSEO, etc.)
├── redux/                 # Redux store & slices
├── sanity/               # Sanity configuration
├── types/                # TypeScript definitions
├── lib/                  # Utility libraries
│   └── seo.ts           # SEO utilities and JSON-LD generation
└── utils/                # Utility functions

Database Operations

Use Prisma ORM for all database operations
Follow existing schema patterns
Implement proper error handling
Add transaction support for complex operations

SEO Guidelines

Structured Data: Always include JSON-LD for products using generateProductJsonLd()
Meta Tags: Use ProductSEO component for consistent SEO implementation
Digital Products: Emphasize file format, license type, and instant download in descriptions
Google Merchant Center: Ensure all products have proper merchant center fields
Sitemaps: Run npm run sitemap:build after adding new products
Social Media: Include Open Graph images and Twitter card optimization

📝 Changelog Format

⚠️ CRITICAL: Use Date Utilities - Never Manual Dates

ALWAYS use the changelog utilities to prevent date errors:

# Get current timestamp
npm run changelog:timestamp

# Generate header with current timestamp
npm run changelog:header "Your Title Here"

# Add complete changelog entry interactively
npm run changelog:interactive

# Add changelog entry with command line arguments
npm run changelog:add "Title" "Entry 1" "Entry 2"

Required Format

### **YYYY-MM-DD HH:MM UTC - Brief Description**

- ✅ **Category**: Detailed description
  - Specific technical details
  - File changes and modifications
  - Impact and benefits
- ✅ **Another Category**: Additional changes
  - More specific details
  - Related modifications

Changelog Rules

NEVER manually type dates - Use npm run changelog:timestamp or utilities
Reverse Chronological: Most recent entries first
Grouped Context: Related changes under single heading
Detailed Descriptions: Include specific technical details
File References: Mention specific files changed
Impact Assessment: Explain benefits and effects
Use Utilities: Always use the changelog scripts to prevent date errors

🚀 Development Workflow

Phase-Based Development

Check Current Phase: Review /DOCS/ROADMAP.md
Understand Requirements: Read phase details and acceptance criteria
Plan Implementation: Break down tasks into specific steps
Implement Changes: Follow technical guidelines
Test Thoroughly: Run all test suites
Update Documentation: Maintain changelog and roadmap
Verify Build: Ensure no compilation errors

Priority Handling

Priority 1 (Critical): Production readiness items
Priority 2 (High): Security and performance
Priority 3 (Medium): Operations automation
Planned: Future phases and features

🔍 Common Tasks

Adding New Features

Create feature branch
Implement feature following existing patterns
Add comprehensive tests
Update documentation
Submit for review

Fixing Bugs

Identify root cause
Implement fix with tests
Update changelog with bug details
Verify fix doesn't break existing functionality

Updating Dependencies

Check for breaking changes
Update package.json
Test thoroughly
Update documentation if needed
Log changes in changelog

📊 Status Tracking

Current Status Indicators

✅ Completed: Fully implemented and tested
🚧 In Progress: Currently being worked on
📋 Planned: Scheduled for future implementation
❌ Blocked: Cannot proceed due to dependencies

Phase Status

Phases 0-8, 10-12: ✅ Complete (Core platform operational)
Phase 9: 📋 Planned (Enhanced Features)
Priority 1: 🚧 In Progress (Production readiness)
Priority 2: 📋 Planned (Security & performance)
Priority 3: 📋 Planned (Operations automation)

🛠️ Environment Setup

Required Environment Variables

# Sanity
NEXT_PUBLIC_SANITY_PROJECT_ID=ietazqpm
NEXT_PUBLIC_SANITY_DATASET=production
SANITY_API_TOKEN=your_token_here

# Stripe
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Database
DATABASE_URL=postgresql://...

# Email (for production)
RESEND_API_KEY=re_...
EMAIL_FROM=RPS Digital <noreply@orders.rps-digital.com>

Development Commands

npm run dev          # Start development server
npm run build        # Build for production
npm test             # Run unit tests
npm run test:e2e     # Run end-to-end tests
npm run prettier     # Format code
npm run lint         # Lint code
npm run sitemap      # Generate sitemaps
npm run sitemap:build # Build and generate sitemaps

🚨 Important Notes

Critical Files

Never modify: /DOCS/project-master.md without updating changelog
Always update: /DOCS/CHANGELOG.md when making changes
Check first: /DOCS/ROADMAP.md for current priorities
Test always: Run full test suite before committing

External Dependencies

digital-product-pipeline repo: Contains Google Cloud Storage implementation
- ⚠️ REMINDER: When implementing Priority 1 file storage, request access to this repo
- Contains existing GCP infrastructure that can be integrated
- Implemented last week - ready for integration

Common Pitfalls

Don't skip testing requirements
Don't forget to update documentation
Don't modify core architecture without discussion
Don't ignore TypeScript errors
Don't commit without running build

📞 Getting Help

When Stuck

Check /DOCS/technical-reference.md for setup issues
Review /DOCS/CHANGELOG.md for similar past changes
Consult /DOCS/testing-and-ci.md for testing problems
Reference /DOCS/ROADMAP.md for context and priorities

Escalation Path

Review existing documentation thoroughly
Check recent changelog entries for patterns
Consult technical reference for architecture
If still stuck, document the issue clearly for human review

📋 Project Overview

RPS Digital is a digital-only e-commerce store built with:

NextMerce (Next.js 15.2.3 e-commerce template)
Sanity CMS for content management
Stripe for payment processing (operational)
TypeScript 5.2.2 with React 19.0.0
SEO Optimization with next-seo and Google Merchant Center integration

Focus: Selling digital products with instant download capabilities and comprehensive SEO optimization

🚀 Getting Started

Read /DOCS/project-master.md for current status and overview
Check /DOCS/ROADMAP.md for immediate priorities and development phases
Follow this guide for specific agent instructions
Log changes in /DOCS/CHANGELOG.md with proper format
For comprehensive documentation navigation, see /DOCS/README.md

Last Updated: 2025-01-27 16:00 UTC Version: 1.0.0 Maintained By: AI Development Team

Provenance

Source file: rps-digital/Agents.md
Source URL: https://github.com/maggielerman/rps-digital/blob/main/Agents.md