⚡ EXECUTION INSTRUCTIONS FOR CLAUDE
When this command is invoked, YOU (Claude) must execute these steps immediately:
This is NOT documentation - these are COMMANDS to execute right now.
Use TodoWrite to track progress through multi-phase workflows.
🚨 EXECUTION WORKFLOW
Phase 1: Execute Documented Workflow
Action Steps:
- Review the reference documentation below and execute the detailed steps sequentially.
📋 REFERENCE DOCUMENTATION
Push Lite Command - Enhanced Reliability with LLM Intelligence
Purpose: Enhanced reliable push to GitHub with LLM-powered PR intelligence, selective staging, error handling, and debugging capabilities
Action: Push current branch to origin with comprehensive reliability improvements and optional smart PR creation
Basic Usage:
/pushlite or /pushl - Push current branch to origin
/pushlite pr or /pushl pr - Push and create PR with LLM-generated content
/pushlite force or /pushl force - Force push to origin
/pushlite smart or /pushl smart - Use LLM-first approach for intelligent PR creation
Enhanced Options:
/pushlite --verbose - Enable detailed debugging output
/pushlite --dry-run - Preview operations without executing
/pushlite --include "*.py" - Include only files matching pattern
/pushlite --exclude "test_*" - Exclude files matching pattern
/pushlite -m "message" - Custom commit message
/pushlite --smart - Enable LLM analysis for PR content generation
/pushlite --update-description - Refresh existing PR description vs origin/main
/pushlite --labels-only - Update PR labels without changing description
/pushlite --detect-outdated - Check if PR description matches current changes
Examples:
/pushl - Pushes current branch to origin/branch-name
/pushl pr - Pushes and creates PR to main
/pushl force - Force pushes current branch (use with caution)
Implementation:
Execute: ./claude_command_scripts/commands/pushlite.sh [arguments]
Key Features:
- Smart Untracked File Handling: Interactive options for untracked files
- Lightweight Operation: No test automation or server management
- Safety Checks: Confirms actions before execution
- PR Integration: Optional PR creation with auto-generated content
- Post-Push Linting: Non-blocking code quality checks after successful push
- Commit Hash URL Output: Automatically displays GitHub commit URL after successful push
- Intelligent Change Detection: Automatically detects and stages uncommitted changes
- Post-Push Verification: Checks for uncommitted changes after push completion
- Conditional Lint Fixes: Auto-applies lint fixes to Python files being committed
Untracked Files Options:
- Add all - Stages all untracked files with smart commit messages
- Select files - Choose specific files interactively
- Continue - Push without adding untracked files
- Cancel - Abort the push operation
Smart Commit Messages:
- Detects file types (tests, docs, scripts, CI tools)
- Suggests appropriate commit messages
- Allows custom messages
Comparison with /push:
/push: Quality gate workflow (linting BEFORE push, blocks on failures, full automation)
/pushl: Fast iteration workflow (push FIRST, linting after, non-blocking)
Safety Features:
- Force push confirmation required
LLM-First Smart PR Creation
Workflow: When using smart mode or --smart flag:
- Analyze Current Changes: Claude analyzes git diff vs origin/main to understand what changed
- Generate Smart Content: Creates intelligent PR title, description, and labels based on:
- Git history and commit messages
- File types and patterns changed
- Scope and impact of changes
- Conventional commit standards
- Execute Streamlined Push: Calls pushlite with pre-generated content
Benefits of LLM-First Approach:
- Intelligence: Claude analyzes context, git history, and patterns for better PR content
- Adaptability: Content generation adapts to different types of changes
- Consistency: Ensures consistent PR quality and formatting
- Maintainability: Keeps shell script focused on operations, not intelligence
Smart Mode Examples:
/pushl smart - Push with LLM-generated PR content
/pushl pr --smart - Create PR with intelligent analysis
/pushl --smart --verbose - See LLM analysis process
Architecture:
User Request → Claude Analysis → Smart Content → Pushlite Script → GitHub PR
Migration Note: The smart functionality from /pushlite_smart has been integrated directly into /pushlite for a unified experience
🤖 Auto-Generated PR Features
Smart Labels (based on git diff vs origin/main):
- Type: bug, feature, improvement, infrastructure, documentation, testing
- Size: small (<100), medium (100-500), large (500-1000), epic (>1000 lines)
- Scope: frontend, backend, fullstack (based on file types)
- Priority: critical, high, normal, low (based on keywords and file patterns)
Smart Descriptions:
- Analyzes complete diff vs origin/main (not just recent commits)
- Lists all changed files with line count statistics
- Auto-detects outdated descriptions (>20% file deviation)
- Generates comprehensive change summaries
Outdated Description Detection:
- Compares PR body file list vs current
git diff --name-only origin/main...HEAD
- Flags PRs where line counts don't match actual
git diff --stat
- Warns when PR description describes old changes
🚨 MANDATORY: FILE JUSTIFICATION PROTOCOL ENFORCEMENT
CRITICAL: Before any push operation, ALL file changes must comply with FILE JUSTIFICATION PROTOCOL
Required Checks:
- Goal Justification: Every modified file must have clear purpose documentation
- Integration Verification: Proof that integration into existing files was attempted first
- Necessity Validation: Evidence that each file change is essential vs alternatives
- Protocol Compliance: All changes must follow NEW FILE CREATION PROTOCOL hierarchy
File Categories:
- ✅ ESSENTIAL: Core functionality, bug fixes, security, production requirements
- ⚠️ ENHANCEMENT: Clear business value with integration evidence
- ❌ UNNECESSARY: Documentation that could be integrated, temporary files, redundant implementations
Enforcement: This command will validate each file change against justification criteria before pushing
Use Cases:
- Quick documentation updates (with integration justification)
- Small fixes that don't need full test environment (with necessity proof)
- When you want manual control over automation (with protocol compliance)
- Fast iteration during development (with file justification documentation)
- Adding CI tools, browser dependencies, or supporting files (with integration evidence)