AI and Agent Workflow Artifacts (RPS Digital)

Source Summary

Document Metadata

• 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

Document Metadata

• 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

1. /DOCS/project-master.md - Core project status and overview
2. /DOCS/ROADMAP.md - Development phases and priorities
3. /DOCS/CHANGELOG.md - Change history and version tracking
4. /DOCS/technical-reference.md - Technical setup and architecture
5. /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

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

---

🚀 Development Workflow

Phase-Based Development

1. Check Current Phase: Review /DOCS/ROADMAP.md
2. Understand Requirements: Read phase details and acceptance criteria
3. Plan Implementation: Break down tasks into specific steps
4. Implement Changes: Follow technical guidelines
5. Test Thoroughly: Run all test suites
6. Update Documentation: Maintain changelog and roadmap
7. 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

1. Create feature branch
2. Implement feature following existing patterns
3. Add comprehensive tests
4. Update documentation
5. Submit for review

Fixing Bugs

1. Identify root cause
2. Implement fix with tests
3. Update changelog with bug details
4. Verify fix doesn't break existing functionality

Updating Dependencies

1. Check for breaking changes
2. Update package.json
3. Test thoroughly
4. Update documentation if needed
5. 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

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

Escalation Path

1. Review existing documentation thoroughly
2. Check recent changelog entries for patterns
3. Consult technical reference for architecture
4. 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

1. Read /DOCS/project-master.md for current status and overview
2. Check /DOCS/ROADMAP.md for immediate priorities and development phases
3. Follow this guide for specific agent instructions
4. Log changes in /DOCS/CHANGELOG.md with proper format
5. 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