# Cursor Rules for gemini4s
# Meta Rules
- This file must be updated whenever workflow or process changes
- All workflow changes must be reflected in both .cursorrules and README.md
- Changes to rules require PR review
- Rules should be kept in sync with project board structure
# Project Structure Guidelines
- Source code should be organized in the src/main/scala/gemini4s directory
- Test code should be in the src/test/scala/gemini4s directory
- Follow the tagless final pattern for all core abstractions
- Use ZIO for effects and resource management
# Project Layers
- Foundation Layer: error types and core models
- Core API Layer: algebra definitions and HTTP client
- Implementation Layer: ZIO interpreter
- Documentation Layer: examples and guides
# Development Workflow
- Start with foundation layer tasks first
- Core API layer tasks can be worked on in parallel once foundation is ready
- Implementation layer depends on both foundation and core API layers
- Documentation should be updated incrementally but finalized last
- Each layer must maintain 90% test coverage
- Run `sbt lint` after making code changes
- Run `sbt lintFix` to automatically fix linting issues
- Verify code passes linting before committing
# Code Quality Requirements
- All code must pass ScalaFix linting rules
- Run linting checks after every code change
- Fix any linting issues before committing
- Maintain consistent import organization
- Remove unused imports and variables
- Follow Scala best practices enforced by ScalaFix
- Use `sbt lintFix` to automatically fix common issues
- Manual review required for any disabled lint rules
# CI/CD Requirements
- All PRs must pass GitHub Actions checks
- Build must succeed on all supported Scala versions
- Tests must pass with minimum 90% coverage
- Scoverage report must be generated
- Branch protection rules must be enforced
- No direct commits to main branch
- PR reviews required before merge
- All lint checks must pass before merge
# CI/CD Workflow for Agents
- After pushing changes to a PR, always check GitHub Actions status
- Wait for CI checks to complete before proceeding
- If checks fail, examine logs and fix issues
- Verify both build and test jobs pass
- Ensure coverage meets 90% threshold
- Verify lint job passes successfully
- Do not proceed with additional changes until CI is green
- Include CI status in progress updates to user
# Coding Standards
- Use meaningful type parameters (e.g., F[_] for effect type)
- All public APIs must be documented with ScalaDoc
- Error handling should use custom ADTs in the error channel
- Prefer immutable data structures
- Use ZIO's built-in testing framework for all tests
# File Organization
- One primary trait/type class per file
- Implementation modules should be in separate files
- Keep files focused and small (< 300 lines)
- Group related functionality in packages
# Git Flow Guidelines
- Main branch is protected and requires PR review
- Feature branches should be named: feature/[issue-number]-short-description
- Bug fix branches should be named: fix/[issue-number]-short-description
- Release branches should be named: release/v[version]
- All commits should reference issue numbers: "#123: Add feature X"
- All PRs must be merged using squash merge
- PR title will be used as the squash commit title
- PR description will be used as the squash commit message
- Branches are automatically deleted after merge
- Delete branches after successful merge
# PR Description Guidelines
- PR title should include issue number and concise description
- PR description should be structured in sections:
- Overview: Brief summary of changes
- Major Components: Categorized list of main changes (e.g., "CI/CD Setup", "Code Quality Tools")
- Process Updates: Any workflow or process changes
- Documentation: Documentation updates and changes
- Each section should use bullet points for clarity
- Include "Resolves #X" to link to relevant issue
- Update description when making significant changes to PR
# PR Description Command Example
```bash
# Create a temporary description file and update PR
printf "Title of PR\n\n# Overview\nBrief summary of changes.\n\n# Major Components\n- Component 1\n - Subitem 1\n - Subitem 2\n- Component 2\n - Subitem 1\n - Subitem 2\n\n# Process Updates\n- Process change 1\n- Process change 2\n\n# Documentation\n- Doc update 1\n- Doc update 2\n\nResolves #X" > pr_description.md && \
gh pr edit PR_NUMBER --body-file pr_description.md && \
rm pr_description.md
```
# Project Board Usage
- All development work must be tracked in the project board
- New features/bugs start in "To Do"
- Move cards to "In Progress" when work begins
- Use "Review" column for PR review phase
- Only move to "Done" after tests pass and PR is merged
- Link commits and PRs to relevant project cards
- Update card status when transitioning between columns
- Check task dependencies before starting new work
# Task Management Guidelines
- Prefer updating existing tasks over creating new ones
- Keep task history in comments for traceability
- Update task labels to reflect current scope
- Ensure task titles remain concise but descriptive
- Regularly review and clean up duplicate tasks:
- Identify overlapping functionality
- Update primary task with any unique requirements
- Close duplicate tasks with explanatory comments
- Link closed tasks to their primary counterparts
# Dependencies Management
- Check issue dependencies before starting work
- Don't start tasks if dependencies aren't complete
- Mark blocked tasks in project board
- Update dependent tasks when completing work
# Testing Requirements
- All public APIs must have test coverage
- Use property-based testing where appropriate
- Mock external services in tests
- Include both unit and integration tests
- Maintain minimum 90% code coverage with scoverage
- Run full test suite before submitting PR
- All tests must pass in CI before merge
# Error Handling
- Define specific error types for each failure case
- Use ZIO error channel for error propagation
- Provide meaningful error messages
- Handle rate limiting and API quotas gracefully
# Performance Considerations
- Use streaming for large responses
- Implement proper resource cleanup
- Consider backpressure in streaming operations
- Cache responses where appropriate
# Documentation
- Keep README.md up to date
- Document all type class instances
- Include examples in ScalaDoc
- Maintain CHANGELOG.md
- Document dependencies between components
- Update build status badges in READMEgolang
less
scala
