# Development Partnership Guide

## Development Partnership Principles

We are partners in creating production-quality code. Every line of code we write together should be:

- Maintainable by the next developer
- Thoroughly tested and documented
- Designed to catch issues early rather than hide them

## 🚨 MANDATORY AI WORKFLOW

**_BEFORE DOING ANYTHING, YOU MUST:_**

**_ALWAYS use zen gemini_** for complex problems and architectural decisions

**_ALWAYS check Context7_** for library documentation and best practices

**_SAY THIS PHRASE_**: "Let me research the codebase using zen gemini and Context7 to create a plan before implementing."

## Critical Workflow

**_Research → Plan → Implement_**

NEVER jump straight to coding. Always follow this sequence:

1. **_Research_**: Use multiple agents to understand the codebase, existing patterns, and requirements
2. **_Plan_**: Create a detailed implementation plan with TodoWrite
3. **_Implement_**: Execute the plan with continuous validation

### Use Multiple Agents for Parallel Problem-Solving

When facing complex problems, launch multiple agents concurrently to:

- Research different aspects of the codebase
- Investigate various implementation approaches
- Validate assumptions and requirements

### Mandatory Automated Checks and Reality Checkpoints

Before any code is considered complete:

- Run all linters and formatters
- Execute all tests
- Validate the feature works end-to-end
- Clean up any old/unused code

## TypeScript/Next.js Specific Rules

### Forbidden Practices

- **_NO any or unknown types_**: Always use specific types
- **_NO console.log in production_**: Use proper logging
- **_NO inline styles_**: Use Tailwind classes or CSS modules
- **_NO direct DOM manipulation_**: Use React patterns
- **_NO drizzle command_**: Skip the drizzle commands

### Implementation Standards

Code is complete when:

- TypeScript compiler passes with strict mode
- ESLint passes with zero warnings
- All tests pass
- Next.js builds successfully
- Feature works end-to-end
- Old code is deleted
- JSDoc comments on all exported functions

## Project Structure Standards

### Next.js App Router Structure

### Component Patterns

## Testing Strategy

### When to Write Tests

- **_Complex business logic_**: Write tests first (TDD)
- **_API routes_**: Write integration tests
- **_Utility functions_**: Write unit tests
- **_Components_**: Write component tests for complex logic

## Communication Protocol

- Provide clear progress updates using TodoWrite
- Suggest improvements transparently
- Prioritize clarity over complexity
- Always explain the "why" behind architectural decisions

## Common Commands

```bash
# Development
npm run dev          # Start development server
npm run build        # Production build
npm run start        # Start production server
npm run lint         # Run ESLint
npm run type-check   # TypeScript checking

# Database (if using Prisma)
npx prisma generate  # Generate Prisma client
npx prisma db push   # Push schema changes
npx prisma studio    # Open Prisma Studio

# Strapi (if backend)
npm run develop      # Start Strapi dev server
npm run build        # Build Strapi admin
npm run start        # Start Strapi production
```

## Performance & Security

### Performance Standards

- Use Next.js Image component for all images
- Implement proper loading states
- Use React.memo for expensive components
- Optimize bundle size with dynamic imports
- Follow Web Vitals guidelines

### Security Standards

- Validate all inputs with Zod
- Use environment variables for secrets
- Implement proper authentication
- Sanitize user-generated content
- Use HTTPS in production

## Quality Gates

### Before Any Commit

1. TypeScript compiler passes ✅
2. ESLint passes with zero warnings ✅
3. All tests pass ✅
4. Build completes successfully ✅
5. Manual testing in development ✅

### Before Deployment

1. Production build works ✅
2. Environment variables configured ✅
3. Database migrations applied ✅
4. API endpoints tested ✅
5. Performance metrics acceptable ✅

## Architecture Principles

- **Single Responsibility**: Each component/function has one job
- **Dependency Injection**: Use context and hooks for dependencies
- **Type Safety**: Leverage TypeScript's type system fully
- **Error Boundaries**: Implement proper error handling
- **Accessibility**: Follow WCAG guidelines
- **Mobile First**: Design for mobile, enhance for desktop

## Common Patterns

### API Route Pattern

### Component Pattern

## Emergency Procedures

### When Hooks Fail

1. STOP immediately
2. Fix ALL reported issues
3. Verify the fix manually
4. Re-run the hook
5. Only continue when ✅ GREEN

### When Build Fails

1. Check TypeScript errors first
2. Verify all imports are correct
3. Check for missing dependencies
4. Validate environment variables
5. Clear .next cache if needed

Remember: This is production code - quality and reliability are paramount!