ai-intent-tracker 1.0.0

AI-powered validation tool that ensures code changes match Jira story requirements

AI Intent Tracker with Jira Integration

Automatically validate that code changes match Jira story requirements using AI. Prevent scope creep and ensure developers work on what they committed to.

---

The Problem

• Scope Creep: Developers working on PROJ-123 but changing unrelated code
• Difficult Reviews: Managers can't tell if PR matches the Jira story
• Lost Context: Code changes don't align with ticket requirements
• Compliance: No audit trail linking code to business requirements

The Solution

AI Intent Tracker validates every commit against Jira stories:

1. Git Hook: Automatically validates commits before they're made (optional)
2. Jira Integration: Extracts intent from Jira story descriptions
3. AI Validation: Checks if code changes match the story (0-10 score)
4. PR Reports: Manager sees alignment scores before approving

Key Features

• Jira Story Validation - Automatic intent from Jira tickets
• Pre-commit Hooks - Block misaligned commits before they happen (optional)
• AI-Powered Analysis - GPT-4 validates code vs story requirements
• PR Dashboard - Manager-friendly validation reports
• Scope Creep Detection - Catches unrelated changes automatically
• Zero Friction - Works with existing git workflow
• Security Scanning - AI-powered vulnerability detection

---

Quick Start (5 Minutes)

1. Install (1 min)

git clone https://github.com/yourusername/intent_aware_git.git
cd intent_aware_git
pip install -r requirements.txt
pip install -e .

2. Configure Jira (2 min)

# Copy template
cp .env.example .env

# Edit .env with your credentials:
# JIRA_URL=https://yourcompany.atlassian.net
# JIRA_EMAIL=[e-mail]
# JIRA_API_TOKEN=<your_token>
# OPENAI_API_KEY=<your_key>

Get Jira API token: https://id.atlassian.com/manage-profile/security/api-tokens

3A. Server-Side Only (Zero Setup)

# Add .github/workflows/pr-summary.yml to your repo
# Add secrets to GitHub repo settings
# Done! Validation happens automatically on PRs

3B. Client-Side (Optional - For Instant Feedback)

cd /path/to/your/project
intent install-hooks

4. Use It

# Make changes
git add .

# Commit with Jira ID
git commit -m "PROJ-123: Add OAuth authentication"

# With hook: validates immediately
# Without hook: validates on PR (GitHub Action)

---

How It Works

Two-Tier Architecture

Tier 1: Server-Side (Always Active)

Developer → commit → push → PR → GitHub Action validates → Manager reviews
                                   ↑ Zero setup, can't bypass

What Happens:

1. Developer commits with Jira ID: PROJ-123: Add feature
2. Pushes to GitHub
3. GitHub Action automatically:
   • Extracts PROJ-123
   • Fetches story from Jira
   • Validates with AI
   • Posts report as PR comment
   • Sets status check (pass/fail)
4. Manager reviews before merge

Tier 2: Client-Side (Optional)

Developer → commit → pre-commit hook validates → instant feedback

What Happens:

1. Developer installs hook: intent install-hooks
2. On commit, hook:
   • Extracts Jira ID
   • Fetches story
   • Validates with AI
   • Blocks if score < 3/10
3. Developer gets instant feedback

Validation Flow

graph LR
    A[Commit with PROJ-123] --> B[Extract Jira ID]
    B --> C[Fetch Jira Story]
    C --> D[Get Git Diff]
    D --> E[AI Validation]
    E --> F{Score >= 3?}
    F -->|Yes| G[Pass]
    F -->|No| H[Block]

---

Developer Workflow

Regular Developer (No Setup)

# 1. Work on Jira story
# 2. Make changes
git add .

# 3. Commit normally with Jira ID
git commit -m "PROJ-456: Add OAuth2 login button"

# 4. Push
git push origin feature-branch

# 5. Create PR
# → GitHub Action validates automatically
# → Posts alignment report

Power User (With Hook)

# One-time setup
intent install-hooks

# Then commit as normal
git commit -m "PROJ-456: Add OAuth2 login button"

# → Hook validates immediately (5 seconds)
# → Get instant feedback
# → GitHub Action still validates on PR

---

Manager Workflow

Review PR with Auto-Generated Report

Pull Request #234: "Add OAuth and fix styling"

Status Checks:
[PASS] intent-validation - Passed

Comment from AI Intent Tracker:
---
## Jira Story Validation Report

### PROJ-123: Add OAuth2 authentication
**Alignment Score:** 9/10 (Confidence: 95%)
**Status:** aligned
**Key Functionality Present:** Yes

**What Aligns:**
- OAuth2 flow implementation present
- Token validation logic added
- Proper error handling included

**Suggestions:**
- Consider adding unit tests for token refresh

### Summary
- Average Score: 9.0/10
- Stories Validated: 1
- Critical Issues: 0

Manager Actions:

• Approve (high score)
• Review carefully (medium score)
• Request changes (low score)

---

Example Output

Pre-commit Hook Output

[INFO] Validating commit against Jira story...
[SUCCESS] Found Jira ID: PROJ-123
[INFO] Fetching Jira story PROJ-123...
[SUCCESS] Story: Add OAuth2 authentication
Type: Story | Status: In Progress

[ANALYSIS] Intent Alignment:
   Score: 9/10 | Confidence: 95% | Status: aligned
   [OK] Key functionality present
   [OK] GOOD alignment

   [MATCHES] What aligns:
      • OAuth2 flow implementation present
      • Token validation logic added
      • Proper error handling included

[SUCCESS] Commit validation passed!

Scope Creep Detection

[CRITICAL] MISMATCH - Code does NOT implement stated intent!
   Score: 2/10 [FAIL]

   [WARNING] Discrepancies:
   • Story says "fix styling" but OAuth system was refactored
   • Database schema changes not mentioned in story
   • Auth configuration modified - out of scope

   [SUGGESTIONS]
   • Split into multiple stories
   • Current changes should be PROJ-790, PROJ-791
   • Only style changes belong in PROJ-789

[BLOCKED] Commit blocked due to alignment < 3/10

---

Use Cases

1. Scope Creep Detection

Story: PROJ-789: Fix login button styling
What Developer Changed:

• LoginButton.css (expected)
• AuthSystem.js (unexpected)
• database/schema.sql (unexpected)

Result: Score 2/10 → Blocked → Developer splits into proper stories

2. Multi-Story PR

git commit -m "PROJ-100: Add user profile page"
git commit -m "PROJ-101: Add profile photo upload"
git commit -m "PROJ-102: Add profile edit form"

Result: Each story validated separately, granular feedback per story

3. Emergency Bypass

# Production hotfix
SKIP_INTENT_VALIDATION=1 git commit -m "HOTFIX: Fix crash"

---

Project Structure

ai-intent-tracker/
│
├── cli/                     # Python CLI code
│   ├── commands.py          # CLI commands
│   ├── jira_client.py       # Jira API integration
│   ├── ai_validator.py      # AI validation logic
│   ├── install_hooks.py     # Git hook installer
│   └── utils.py             # Helpers
│
├── hooks/
│   └── pre-commit           # Git pre-commit hook
│
├── .github/
│   └── workflows/
│       └── pr-summary.yml   # PR validation action
│
├── tests/                   # Unit tests
├── README.md
├── requirements.txt
└── setup.py

---

Configuration

Environment Variables

# Required for Jira integration
JIRA_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=[e-mail]
JIRA_API_TOKEN=your_token_here

# Required for AI validation
OPENAI_API_KEY=your_openai_key

# Optional: Control validation behavior
ENABLE_AI_VALIDATION=true
SKIP_INTENT_VALIDATION=false

GitHub Secrets (For PR Validation)

Add these to your repository settings:

• JIRA_URL
• JIRA_EMAIL
• JIRA_API_TOKEN
• OPENAI_API_KEY

Make Validation Required

Repository Settings → Branches → main → 
☑️ Require status checks to pass
☑️ intent-validation

Now PRs can't be merged without passing validation!

---

Benefits by Role

For Developers

• Catch scope creep early
• Learn from AI suggestions
• Clear definition of "on-task"
• Optional instant feedback

For Managers

• See alignment before review
• Block scope creep automatically
• Save review time
• Data-driven decisions

For Teams

• Reduce wasted development time
• Improve estimate accuracy
• Compliance audit trail
• Better sprint execution

---

Troubleshooting

"Jira authentication failed"

• Check JIRA_EMAIL and JIRA_API_TOKEN in .env
• Verify API token is valid: https://id.atlassian.com/manage-profile/security/api-tokens
• Test: curl -u [e-mail]:token https://yourcompany.atlassian.net/rest/api/3/myself

"Jira issue not found"

• Verify issue ID format: PROJECT-123 (uppercase)
• Check issue exists and you have access
• Test in Jira UI first

"OpenAI API error"

• Verify OPENAI_API_KEY is valid
• Check API quota/billing at https://platform.openai.com/usage
• Or disable AI: ENABLE_AI_VALIDATION=false

Hook not running

# Check hook is installed
ls -la .git/hooks/pre-commit

# Check it's executable
chmod +x .git/hooks/pre-commit

# Test manually
.git/hooks/pre-commit

---

Advanced Usage

Commit Message Formats

All these work:

"PROJ-123: Add feature"
"[PROJ-123] Add feature"
"PROJ-123 Add feature"
"Add feature (PROJ-123)"

Skip Validation (Optional - Rarely Needed)

Most commits work normally without any special markers. Only use these for edge cases:

# Normal commit (no skip marker needed)
git commit -m "PROJ-123: Add OAuth feature"
# → Validates automatically

# Skip validation (only when needed)
git commit -m "PROJ-123: Emergency hotfix [skip-validation]"
git commit -m "Update README [no-validation]"

# Alternative: environment variable
SKIP_INTENT_VALIDATION=1 git commit -m "Config tweak"

When to skip (rare cases):

• Emergency production hotfixes
• README/docs updates
• Version bumps, config changes

You DON'T need skip markers for:

• Normal feature work
• Bug fixes
• Code without tests (validation is flexible)
• Any commit that roughly matches your Jira story

Custom Scoring Threshold

Edit .github/workflows/pr-summary.yml:

# Block if score < 5 (default is 3)
if critical_issues or score < 5:
    sys.exit(1)

---

What's Next

Immediate Improvements

• Cache Jira stories (reduce API calls)
• Offline mode (store stories locally)
• Better error messages
• Add unit tests

Short Term

• VS Code extension (one-click install)
• Team dashboard (web UI)
• Historical analytics
• Support GitLab/Bitbucket

Long Term

• Linear/Asana/Azure DevOps support
• Custom validation rules
• On-prem deployment option
• Enterprise licensing

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• OpenAI for GPT-4 API
• Atlassian for Jira API
• The open-source community

---

Support

• Email: [e-mail]
• Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ for better code reviews

**3. Commit with Jira ID**
```bash
# Commit message MUST include Jira ID
git commit -m "PROJ-123: Add OAuth2 authentication"

# The pre-commit hook will:
# → Extract PROJ-123 from message
# → Fetch story details from Jira
# → Analyze code changes vs story intent with AI
# → Block commit if misaligned (score < 3/10)
# → Warn if low alignment (score < 5/10)

4. Push and create PR

git push origin feature-branch

# GitHub Action automatically runs on PR
# → Validates all commits against their Jira stories
# → Posts validation report as PR comment
# → Shows alignment scores for manager review

Manager Workflow

1. Review PR with validation report

• PR comment shows alignment scores for each Jira story
• See what matches vs what doesn't
• Get AI-generated suggestions
• Identify scope creep automatically

2. Approve or request changes

• High alignment (7-10/10) → safe to approve
• Medium (5-7/10) → review carefully
• Low (<5/10) → request changes

Example Output

Pre-commit Hook

[INFO] Validating commit against Jira story...
[SUCCESS] Found Jira ID: PROJ-123
[INFO] Fetching Jira story PROJ-123...
[SUCCESS] Story: Add OAuth2 authentication
Type: Story | Status: In Progress
[INFO] Running AI validation against Jira story...

[ANALYSIS] Intent Alignment:
   Score: 9/10 | Confidence: 95% | Status: aligned
   [OK] Key functionality present
   [OK] GOOD alignment - Changes match intent well

   [MATCHES] What aligns:
      • OAuth2 flow implementation present
      • Token validation logic added
      • Proper error handling included

[SUCCESS] Commit validation passed!

PR Comment

## Jira Story Validation Report

### PROJ-123: Add OAuth2 authentication

**Alignment Score:** 9/10 (Confidence: 95%)
**Status:** aligned
**Key Functionality Present:** Yes

**What Aligns:**
- OAuth2 flow implementation present
- Token validation logic added
- Proper error handling included

**Suggestions:**
- Consider adding unit tests for token refresh
- Document OAuth2 configuration in README

---

### Summary

- **Average Score:** 9.0/10
- **Stories Validated:** 1
- **Critical Issues:** 0
- **Low Alignment:** 0
- **Good Alignment:** 1

Advanced Configuration

Skip Validation (Emergency)

# Skip all validation
SKIP_INTENT_VALIDATION=1 git commit -m "PROJ-123: Hotfix"

# Skip only AI validation
ENABLE_AI_VALIDATION=false git commit -m "PROJ-123: Minor change"

GitHub Secrets

Add these to your repository secrets for PR validation:

• JIRA_URL
• JIRA_EMAIL
• JIRA_API_TOKEN
• OPENAI_API_KEY

Features

• 🎯 Jira Story Validation: Automatic intent from Jira tickets
• 🔒 Pre-commit Hooks: Block misaligned commits before they happen
• 🤖 AI-Powered Analysis: GPT-4 validates code vs story requirements
• 📊 PR Dashboard: Manager-friendly validation reports
• 🚫 Scope Creep Detection: Catches unrelated changes automatically
• ⚡ Zero Friction: Works with existing git workflow
• 🔐 Security Scanning: AI-powered vulnerability detection

How It Works

1. Developer starts work on Jira story PROJ-123
2. Makes code changes and stages them
3. Commits with git commit -m "PROJ-123: description"
4. Pre-commit hook:
   • Extracts PROJ-123 from message
   • Fetches story from Jira API
   • Analyzes code diff vs story with AI
   • Blocks if score < 3/10
5. GitHub Action validates entire PR
6. Manager reviews alignment report before merge

Benefits

For Developers

• Catch scope creep early
• Get AI feedback on alignment
• Learn what "on-task" looks like
• Automatic documentation of intent

For Managers

• See alignment before code review
• Identify scope issues at PR time
• Data-driven approval decisions
• Audit trail for compliance

For Teams

• Reduce wasted review time
• Improve estimate accuracy
• Better sprint planning
• Clear commit-to-story mapping

Troubleshooting

"Jira authentication failed"

• Check JIRA_EMAIL and JIRA_API_TOKEN in .env
• Verify API token is valid: https://id.atlassian.com/manage-profile/security/api-tokens

"Jira issue not found"

• Verify issue ID format: PROJECT-123 (uppercase)
• Check issue exists and you have access

"OpenAI API error"

• Verify OPENAI_API_KEY is valid
• Check API quota/billing
• Or disable AI: ENABLE_AI_VALIDATION=false

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.