mims-harvard/devtu-github

DevTU GitHub Workflow

Safely push ToolUniverse code to GitHub by enforcing pre-push cleanup, pre-commit hooks, and test validation.

Instructions

When the user wants to push code, fix CI, or prepare a commit, follow this workflow:

Phase 1: Pre-Push Cleanup

1. Move temp files out of root - session docs and ad-hoc test scripts must NOT be pushed:

# Move session markdown files to temp_docs_and_tests/
for f in $(ls *.md 2>/dev/null | grep -v README.md | grep -v CHANGELOG.md | grep -v LICENSE.md); do
  mv "$f" temp_docs_and_tests/
done

# Move root-level test scripts to temp_docs_and_tests/
for f in $(ls test_*.py 2>/dev/null); do
  mv "$f" temp_docs_and_tests/
done

2. Verify nothing unwanted is staged:

git status --short

Red flags - these should NEVER be staged:

• *_SUMMARY.md, *_REPORT.md, SESSION_*.md in root
• test_*.py in root (these are ad-hoc scripts, not real tests)
• .env or credential files
• temp_docs_and_tests/ contents

Phase 2: Activate Pre-Commit Hooks

3. Ensure pre-commit is installed and active:

pre-commit install

This enables automatic checks on every git commit:

• ruff check --fix - Python linting with auto-fix
• ruff format - Code formatting
• YAML/TOML validation
• Trailing whitespace removal
• End of file fixes

4. Verify hooks are active:

ls -la .git/hooks/pre-commit

Phase 3: Run Tests

5. Run the full test suite locally:

python -m pytest tests/ -x --tb=short -q

6. If tests fail, diagnose using the error patterns below and fix before proceeding.

Phase 4: Commit and Push

7. Stage only specific files (never use git add . or git add -A):

git add src/tooluniverse/specific_file.py tests/specific_test.py

8. Commit (pre-commit hooks run automatically):

git commit -m "Clear, descriptive message"

9. Rebase onto latest main BEFORE pushing (CRITICAL — prevents PR conflicts):

git fetch origin
git stash            # stash any uncommitted work
git rebase origin/main
git stash pop        # restore uncommitted work

If rebase conflicts arise, resolve them (keep our newer changes), then:

git add <conflicted-file>
git rebase --continue

10. Push (force-with-lease after a rebase):

git push --force-with-lease origin <branch-name>

After pushing, verify the PR is conflict-free:

gh pr view <PR-number> --json mergeable,mergeStateStatus
# Must show: "mergeable":"MERGEABLE"

Files That Must NEVER Be Pushed

Temp Session Documents (Root-Level .md)

These are session notes created during development. Move to temp_docs_and_tests/ before committing:

| Pattern | Example | |---------|---------| | *_SUMMARY.md | API_DISCOVERY_SESSION_SUMMARY.md | | *_REPORT.md | SKILL_TESTING_REPORT.md, TOOLUNIVERSE_BUG_REPORT.md | | SESSION_*.md | SESSION_2026_02_13.md | | IMPLEMENTATION_*.md | IMPLEMENTATION_COMPLETE.md | | BUG_ANALYSIS_*.md | BUG_ANALYSIS_DETAILED.md | | FIX_*.md | FIX_SUMMARY.md, CORRECT_FIX.md | | AGENT_*.md | AGENT_DESIGN_UPDATES.md |

Exception: README.md, CHANGELOG.md, LICENSE.md are real docs and MUST stay.

Root-Level Test Scripts

Ad-hoc test scripts like test_*.py in root are NOT part of the test suite (tests/ directory is). Move them to temp_docs_and_tests/:

| File | Purpose | |------|---------| | test_clear_tools.py | One-off tool cleanup test | | test_finemapping_tools.py | Ad-hoc tool validation | | test_metabolomics_tools.py | Ad-hoc tool validation | | test_original_bug.py | Bug reproduction | | test_pathway_tools.py | Ad-hoc tool validation | | test_protein_interaction_skill.py | Skill test | | test_reload_fix.py | Bug reproduction | | test_round10_tools.py | Ad-hoc tool validation |

Other Excluded Files

• .env - Environment variables with secrets
• temp_docs_and_tests/ - Already in .gitignore
• .claude/ - Claude Code configuration
• __pycache__/, *.pyc - Python bytecode
• .DS_Store - macOS metadata

Common Test Failure Patterns

Pattern 1: KeyError: 'role'

Symptom: KeyError: 'role' when accessing message dicts

Fix: Add return_message=True to tu.run() and use .get():

messages = tu.run(calls, use_cache=True, return_message=True)
if msg.get("role") == "tool":

Pattern 2: Mock Not Subscriptable

Symptom: TypeError: 'Mock' object is not subscriptable

Fix: Use real dicts for all_tool_dict and add _get_tool_instance:

mock_tu.all_tool_dict = {"Tool": mock_tool}
mock_tu._get_tool_instance = lambda name, cache=True: mock_tu.all_tool_dict.get(name)

Pattern 3: Linting Errors (F841, E731)

Fix F841 (unused variable): Use _ prefix or _ = func() Fix E731 (lambda assignment): Replace with def

Pattern 4: Temp Files Tracked by Git

Symptom: git status shows temp files as modified/staged

Fix:

git rm -r --cached temp_docs_and_tests/
git rm --cached API_DISCOVERY_SESSION_SUMMARY.md
git commit -m "Remove temp files from tracking"

Pre-Commit Hook Configuration

The project uses .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    hooks: [end-of-file-fixer, trailing-whitespace, check-yaml, check-toml]
  - repo: https://github.com/astral-sh/ruff-pre-commit
    hooks: [ruff-check --fix, ruff-format]

Scope: Only files matching ^(ToolUniverse/)?src/tooluniverse/

Quick Reference

| Task | Command | |------|---------| | Activate hooks | pre-commit install | | Run all tests | pytest tests/ -x --tb=short -q | | Run specific test | pytest tests/path/test.py::Class::method -xvs | | Check staged files | git status --short | | Unstage a file | git restore --staged <file> | | Remove from tracking | git rm --cached <file> | | Move temp files | See Phase 1 commands | | Run hooks manually | pre-commit run --all-files |

Pre-Push Checklist

Before every push, verify:

• [ ] Temp markdown files moved from root to temp_docs_and_tests/
• [ ] Root-level test_*.py scripts moved to temp_docs_and_tests/
• [ ] Pre-commit hooks installed (pre-commit install)
• [ ] All tests pass locally (pytest tests/ -x)
• [ ] No linting errors
• [ ] Only relevant files staged (no .env, no temp files)
• [ ] Commit message is clear and descriptive
• [ ] Correct branch selected

Git Commit Guidelines

• Never include AI attribution in commits
• Never commit session documentation markdown files
• Use git add <specific-files> instead of git add .
• Write clean, professional commit messages
• One logical change per commit