# Development Workflow & Tooling Requirements

**⚠️ CRITICAL: This document is MANDATORY reading for all development work**

## Core Principles

### 1. ALWAYS Use Local Tooling

**Never use system-wide tooling**. Always use project-local executables to ensure version consistency:

#### Python
```bash
# REQUIRED: Use venv python executable
source .venv/bin/activate
.venv/bin/python -m pytest
.venv/bin/python -m flake8
.venv/bin/python main.py

# WRONG - Uses system python (version mismatch risk)
python -m pytest
python main.py
```

#### Node.js / npm
```bash
# REQUIRED: Use local node_modules binaries
node_modules/.bin/eslint
node_modules/.bin/prettier
npx <tool>  # Uses local if available, downloads if not

# WRONG - Uses global install (version mismatch risk)
eslint
prettier
```

#### Ruby / Bundler
```bash
# REQUIRED: Use bundler exec
bundle exec rspec
bundle exec rubocop

# WRONG - Bypasses Gemfile versions
rspec
rubocop
```

#### Go
```bash
# REQUIRED: Use project bin or go install to local path
./bin/tool
go run ./cmd/tool

# Check for local install first
which tool | grep $(pwd)
```

#### General Pattern for Any Tool
1. Check `./<toolchain>/bin/<tool>` (e.g., `.venv/bin`, `node_modules/.bin`, `vendor/bin`)
2. Check `./bin/<tool>` (project-specific builds)
3. Use toolchain-specific runners (`uv run`, `bundle exec`, `npx`)
4. **ONLY** use system-wide as last resort (and document why)

---

### 2. ALWAYS Prevent Interactive Git Editors

**Git operations MUST NEVER open nano/vi/vim/emacs**. These block AI workflows and require human intervention.

#### Mandatory Prefix for ALL Git Commands
```bash
# REQUIRED: Set GIT_EDITOR=true before EVERY git command
export GIT_EDITOR=true && git commit -m "message"
export GIT_EDITOR=true && git rebase --continue
export GIT_EDITOR=true && git merge <branch>
export GIT_EDITOR=true && git cherry-pick <commit>
export GIT_EDITOR=true && git revert <commit>
export GIT_EDITOR=true && git stash push -m "message"

# For longer sessions, set it once:
export GIT_EDITOR=true
git commit -m "message"
git rebase --continue
```

#### Why This Matters
- **Blocking**: Interactive editors halt execution until closed
- **AI Workflows**: Automated tools cannot interact with nano/vi
- **CI/CD**: Pipelines fail when editors open
- **Consistency**: Enforces commit messages via `-m` flag

#### Commands That Require This
- `git commit` (without `-m`, `-F`, or `--amend -m`)
- `git rebase --continue` (after conflict resolution)
- `git merge` (when conflicts require messages)
- `git cherry-pick` (for commit messages)
- `git revert` (for revert messages)
- `git tag -a` (for annotated tags)
- `git stash` (without message)

---

### 3. ALWAYS Test and Lint Before Commit/Push

#### Pre-Commit Checklist
```bash
# 1. Activate environment
source .venv/bin/activate

# 2. Run tests (MUST pass)
.venv/bin/python -m pytest tests/ -v --cov=. --cov-report=term-missing

# 3. Run linting (MUST show 0 errors)
.venv/bin/python -m flake8 . --config=.flake8 --count

# 4. Check git status
export GIT_EDITOR=true && git status

# 5. Stage changes
export GIT_EDITOR=true && git add <files>

# 6. Commit with proper message
export GIT_EDITOR=true && git commit -m "[TAG] Description"

# 7. Push (only after all checks pass)
export GIT_EDITOR=true && git push <remote> <branch>
```

#### Enforced Tags
- `[SAFE/ADD]` - New code (standard review)
- `[SAFE/REFACTOR]` - Internal changes (ensure tests pass)
- `[SAFE/FIX]` - Bug fixes (document root cause)
- `[RISK/BEHAVIOR]` - User-visible changes (extra validation)
- `[RISK/SCHEMA]` - Data shape changes (migration plan)

---

## Toolchain-Specific Setup

### Python

#### Installation
```bash
# Install uv (if not present)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv .venv --python 3.11

# Activate
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt
```

#### Daily Workflow
```bash
# Activate (every terminal session)
source .venv/bin/activate

# Run application
.venv/bin/python main.py

# Run tests
.venv/bin/python -m pytest

# Lint
.venv/bin/python -m flake8 . --config=.flake8 --count
```

### Node.js Projects

#### Installation
```bash
# Install dependencies (creates node_modules/)
npm install

# Verify local install
ls node_modules/.bin/
```

#### Daily Workflow
```bash
# Use local binaries
node_modules/.bin/eslint src/
node_modules/.bin/prettier --write src/

# Or use npx (checks local first)
npx eslint src/
npx prettier --write src/
```

### Ruby Projects

#### Installation
```bash
# Install bundler
gem install bundler

# Install dependencies (creates vendor/bundle)
bundle install --path vendor/bundle
```

#### Daily Workflow
```bash
# Always use bundle exec
bundle exec rspec
bundle exec rubocop
bundle exec rails server
```

---

## Git Workflow

### Branch Naming
```bash
# Pattern: <ticket>-<descriptive-name>
export GIT_EDITOR=true && git checkout -b TICKET-123-add-feature
export GIT_EDITOR=true && git checkout -b JIRA-456-fix-authentication-bug
```

### Commit Messages
```bash
# Format: [TAG] Brief description (50 chars max)
#
# Detailed explanation (wrap at 72 chars)
# - What changed
# - Why it changed
# - Any breaking changes

export GIT_EDITOR=true && git commit -m "[SAFE/ADD] Add authentication module

Implements OAuth 2.0 client for third-party authentication.
Includes retry logic, token refresh, and comprehensive error handling.

Breaking Change: Requires AUTH_CLIENT_ID environment variable."
```

### Rebase Workflow
```bash
# Fetch latest
export GIT_EDITOR=true && git fetch upstream main

# Rebase feature branch
export GIT_EDITOR=true && git rebase upstream/main

# If conflicts occur:
# 1. Resolve conflicts in files
# 2. Stage resolved files
export GIT_EDITOR=true && git add <resolved-files>

# 3. Continue rebase
export GIT_EDITOR=true && git rebase --continue

# 4. Force push (after tests pass)
export GIT_EDITOR=true && git push --force-with-lease origin <branch>
```

---

## Common Pitfalls

### ❌ Using System Python
```bash
# WRONG
python -m pytest
python main.py
```
**Problem**: Uses system Python (could be 3.8, 3.9, 3.10, wrong packages)  
**Fix**: Use `.venv/bin/python`

### ❌ Forgetting GIT_EDITOR
```bash
# WRONG
git commit
# Opens nano/vi - blocks workflow
```
**Problem**: Opens interactive editor, requires human intervention  
**Fix**: `export GIT_EDITOR=true && git commit -m "message"`

### ❌ Not Activating venv
```bash
# WRONG
python -m pytest
ModuleNotFoundError: No module named 'pytest'
```
**Problem**: System Python doesn't have test dependencies  
**Fix**: `source .venv/bin/activate` first

### ❌ Pushing Without Testing
```bash
# WRONG
export GIT_EDITOR=true && git add . && git commit -m "fix" && git push
# Tests fail in CI
```
**Problem**: Broken code reaches remote repository  
**Fix**: Run `pytest` and `flake8` BEFORE commit

### ❌ Using Global npm Packages
```bash
# WRONG
npm install -g eslint
eslint src/
```
**Problem**: Version doesn't match project requirements  
**Fix**: Use `node_modules/.bin/eslint` or `npx eslint`

---

## IDE Configuration

### VS Code

Add to `.vscode/settings.json`:
```json
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "python.testing.pytestEnabled": true,
  "python.testing.pytestPath": "${workspaceFolder}/.venv/bin/pytest",
  "python.linting.flake8Enabled": true,
  "python.linting.flake8Path": "${workspaceFolder}/.venv/bin/flake8",
  "terminal.integrated.env.osx": {
    "GIT_EDITOR": "true"
  },
  "terminal.integrated.env.linux": {
    "GIT_EDITOR": "true"
  }
}
```

### PyCharm

1. **Settings → Project → Python Interpreter**
   - Select `.venv/bin/python`
   
2. **Settings → Version Control → Git**
   - Set "Path to Git executable"
   - Add environment variable: `GIT_EDITOR=true`

3. **Settings → Tools → Python Integrated Tools**
   - Default test runner: `pytest`
   - Package requirements file: `requirements.txt`

---

## Environment Variables

### Required for Git
```bash
export GIT_EDITOR=true  # Prevent interactive editors
```

### Recommended for Shell
```bash
# Add to ~/.zshrc or ~/.bashrc
export GIT_EDITOR=true
export VIRTUAL_ENV_DISABLE_PROMPT=0  # Show venv in prompt
```

---

## Troubleshooting

### "ModuleNotFoundError" when running tests
```bash
# Check if venv is activated
which python  # Should show .venv/bin/python

# If not, activate:
source .venv/bin/activate

# Verify:
.venv/bin/python -c "import pytest; print(pytest.__version__)"
```

### "nano opened during git rebase"
```bash
# Kill nano: Ctrl+X
# Abort rebase:
export GIT_EDITOR=true && git rebase --abort

# Restart with GIT_EDITOR set:
export GIT_EDITOR=true && git rebase upstream/main
```

### "Command not found: <tool>"
```bash
# Check local install first:
ls .venv/bin/
ls node_modules/.bin/
ls vendor/bin/

# Install if missing:
# Python: uv pip install <package>
# Node: npm install <package>
# Ruby: bundle add <gem>
```

---

## Summary

### The Three Commandments

1. **Use Local Tooling**
   - `.venv/bin/python` for Python
   - `node_modules/.bin/` for Node.js
   - `bundle exec` for Ruby
   - Check project directories FIRST

2. **Prevent Interactive Editors**
   - `export GIT_EDITOR=true && git <command>`
   - Add to shell profile for persistence
   - Never let git open nano/vi/vim

3. **Test Before Push**
   - Run `pytest` (must pass)
   - Run linter (0 errors)
   - Use proper commit tags
   - Verify with `git status`

### Quick Reference Card

```bash
# Daily workflow
source .venv/bin/activate
export GIT_EDITOR=true

# Develop
.venv/bin/python main.py

# Test
.venv/bin/python -m pytest

# Lint
.venv/bin/python -m flake8 . --config=.flake8 --count

# Commit
export GIT_EDITOR=true && git add . && git commit -m "[TAG] Message"

# Push (after tests pass)
export GIT_EDITOR=true && git push origin <branch>
```

---

**Version:** 1.0