devtu-github

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
# 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**:

```bash
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**:

```bash
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**:

```bash
ls -la .git/hooks/pre-commit
```

### Phase 3: Run Tests

5. **Run the full test suite locally**:

```bash
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`):

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

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

```bash
git commit -m "Clear, descriptive message"
```

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

```bash
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:
```bash
git add <conflicted-file>
git rebase --continue
```

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

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

After pushing, verify the PR is conflict-free:
```bash
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` |

From Zaoqu-Liu/ScienceClaw, MIT.

More from Zaoqu-Liu/ScienceClaw