Jessica

🚀 Development Tools

This directory contains various development and productivity tools used in the project. These tools are designed to assist developers and product managers in completing common tasks and maintaining consistency in the codebase.

🚀 Quick Start

Directory Structure

.dev-tools/
├── prompts/           # AI prompt templates for various tasks
│   ├── prompt_pr.md   # Template for generating PR descriptions
│   ├── prompt_commit.md # Template for creating meaningful commit messages
│   └── prompt_user_story.md # Template for creating well-structured user stories as GitHub issues
│
└── scripts/          # Development utility scripts
    ├── generate_git_diffs.py  # Python script for generating git diffs
    ├── check_env_files.py  # Validate environment files for all services
    ├── pyproject.toml       # Poetry project configuration
    ├── .env.example        # Example environment variables
    └── .env               # Your local environment variables (ignored by git)

✨ Features

Prompts

The prompts/ directory contains templates for AI-assisted tasks:

• prompt_pr.md: Template for generating detailed PR descriptions.
• prompt_commit.md: Template for creating meaningful commit messages.
• prompt_user_story.md: Template for creating well-structured user stories as GitHub issues.

Scripts

The scripts/ directory contains utility scripts:

• generate_git_diffs.py: Used to generate git diffs between branches and collect commit information.
• check_env_files.py: Validate environment files for all services.
  • Check for missing .env files compared to the .env.example template.
  • Ensure all required variables are set.
  • Detect example/placeholder values that need to be replaced.
  • Validate against the .gitignore pattern.
  • Provide clear progress indicators and summary reports.

📦 Installation

Environment Variables

1. Create your local environment file:

   cd .dev-tools/scripts
   cp .env.example .env
   

2. Adjust the variables in .env as needed:

   • GIT_DIFF_BRANCH: The branch to compare (default is origin/dev for PRs).
   • Note: Most PRs should target the dev branch. Use origin/main only for hotfixes or release PRs.

Python Dependencies

1. Install Poetry if not already installed:

   curl -sSL https://install.python-poetry.org | python3 -
   

2. Install dependencies:

   cd .dev-tools/scripts
   poetry install
   

3. Activate the virtual environment:

   poetry shell
   

💻 Usage Examples

Workflow: Creating User Stories with AI

1. In Cursor's Composer:

   • Refer to or drag and drop prompt_user_story.md.
   • Describe the goal you want to achieve.
   • The AI will analyze your input and the codebase to generate a comprehensive user story.
   • Review and confirm the generated story.
   • The AI will help create a GitHub issue with appropriate project assignments.

2. The generated user stories include:

   • Business requirements from the product manager's perspective.
   • Technical requirements from the developer's perspective.
   • Clear problem descriptions and goals.

Workflow: Generating Git Diffs

1. Run the script to generate diffs:

   cd .dev-tools/scripts
   poetry run python generate_git_diffs.py
   

2. The script will:

   • Select two branches or commits to compare.
   • Display detailed file-level diffs.
   • Provide copy-pasteable git commands.

Workflow: Checking Environment Files

1. Run the environment checker:

   cd .dev-tools/scripts
   poetry run python check_env_files.py
   

2. The script will:

   • Scan the project for service directories.
   • Load and respect the .gitignore pattern.
   • Check the environment configuration for each service.
   • Provide a detailed report showing:
     • ✅ Correctly configured environment files.
     • ❌ Missing environment files.
     • ⚠️ Variables using example values.
     • ⚠️ Extra variables not in the example file.

3. Fix the issues indicated in the report:

   • Create missing .env files based on the .env.example template.
   • Populate the required variables.
   • Replace example/placeholder values with actual values.
   • Review extra variables to ensure they are necessary.

📚 Documentation

Contribution Guidelines

When adding new tools:

1. Create an appropriate subdirectory based on the tool type.
2. Provide clear documentation.
3. Update the tool descriptions in this README.
4. For Python scripts:
   • Add dependencies to pyproject.toml using Poetry.
   • Follow the code style defined in pyproject.toml.
   • Update the setup instructions if necessary.