From 9796ece7e3e3e5c37e49e2bab6db13f8772c1d92 Mon Sep 17 00:00:00 2001 From: mg2015agg Date: Thu, 2 Apr 2026 16:09:13 -0500 Subject: [PATCH] =?UTF-8?q?feat:=20add=20git-history=20skill=20=E2=80=94?= =?UTF-8?q?=20git=20history=20intelligence=20for=20AI=20agents?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Indexes entire git history into SQLite+FTS5, computes analytics (churn hotspots, coupling, decision points, quality metrics), and writes health summaries to Claude's memory system. Key features: - Hybrid search (BM25 + vector with RRF fusion) - Smart churn alerts (thrashing, revert chains, fix-on-fix) - verify command ("was this tried before?") - Dev workflow commands (/plan, /implement, /review, /finalize, /trace) - Historical context debugging skill (3 fault types) - Claude memory integration (auto-loaded at session start) - LLM enrichment (commit intent/reasoning analysis) - Nightly cron with team fetch + auto-embed npm: @m2015agg/git-skill GitHub: https://github.com/m2015agg/git-skill --- skills/git-history/LICENSE.txt | 21 +++ skills/git-history/SKILL.md | 202 ++++++++++++++++++++++ skills/git-history/scripts/check-setup.sh | 19 ++ 3 files changed, 242 insertions(+) create mode 100644 skills/git-history/LICENSE.txt create mode 100644 skills/git-history/SKILL.md create mode 100755 skills/git-history/scripts/check-setup.sh diff --git a/skills/git-history/LICENSE.txt b/skills/git-history/LICENSE.txt new file mode 100644 index 000000000..e6998c067 --- /dev/null +++ b/skills/git-history/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 m2015agg + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/git-history/SKILL.md b/skills/git-history/SKILL.md new file mode 100644 index 000000000..b791a0ceb --- /dev/null +++ b/skills/git-history/SKILL.md @@ -0,0 +1,202 @@ +--- +name: git-history +description: "Git history intelligence for coding tasks. Indexes entire git history into SQLite+FTS5, computes analytics (churn hotspots, coupling, decision points, quality metrics), and writes health summaries to Claude memory. TRIGGER when: user asks about codebase evolution, prior attempts, file history, who wrote code, why something was changed, or before modifying high-churn files. Requires: npm package @m2015agg/git-skill, Node.js 18+." +license: Complete terms in LICENSE.txt +--- + +# Git History Intelligence for AI Agents + +Give AI agents institutional memory over a codebase's evolution, decisions, and health trends. Indexes git history into SQLite with FTS5 search, computes derived analytics, and writes a health summary directly into Claude's memory system. + +## Why This Exists + +AI coding agents start every session blind. They don't know which files are churning, what was reverted last week, or that someone already tried the approach they're about to suggest. git-skill fixes this by making git history queryable, analyzable, and automatically loaded into context. + +## What It Enables + +- **"We tried that already"** — `verify` checks staged changes against enriched history before committing +- **"Why does this keep breaking?"** — Churn hotspots and fix-on-fix metrics surface unstable files +- **"Who knows this code?"** — Author expertise mapping per file/directory +- **"The agent has no memory"** — Health summary written to Claude's memory system every commit + +## Setup (One-Time) + +If `git-skill` is not installed, guide the user through setup: + +```bash +npm install -g @m2015agg/git-skill +git-skill config # Interactive: configure embeddings + API key +git-skill init # Per-project: hook, snapshot, workflow commands, 30-day context +``` + +`init` automatically: +1. Installs post-commit hook (captures commits + refreshes memory) +2. Indexes full git history into SQLite +3. Computes analytics (hotspots, coupling, decisions, expertise, metrics) +4. Writes 30-day health summary to Claude's memory +5. Installs workflow commands (`/plan`, `/implement`, `/review`, `/finalize`, `/trace`) +6. Pre-approves read-only commands + +## How to Search History + +### Full-text search (BM25 + vector hybrid when embeddings exist) +```bash +git-skill search "auth refactor" +git-skill search "rate limiting" --bm25 # force keyword-only +``` + +### File/directory evolution +```bash +git-skill timeline src/auth/ +git-skill timeline src/api/routes.ts --since 2026-01-01 +``` + +### Who has context on a file +```bash +git-skill experts src/services/ +``` + +### What changes together +```bash +git-skill coupling src/auth/index.ts +``` + +## How to Check Codebase Health + +### Churn hotspots (which files are most volatile) +```bash +git-skill hotspots --limit 10 +``` + +### Major decision points (reverts, refactors, architecture changes) +```bash +git-skill decisions +git-skill decisions --type revert +``` + +### Quality metrics over time +```bash +git-skill trends +git-skill regression # detect change-point shifts +``` + +### Full health check +```bash +git-skill doctor +``` + +## Before Committing: Verify Against History + +Check if staged changes repeat a known mistake: + +```bash +git add . +git-skill verify +``` + +Returns per-file: +- **PASS** — no concerning history +- **WARN** — file has been churning or relates to a reverted change +- **BLOCK** — change re-introduces something that was explicitly reverted + +Works without LLM (local analysis: edit counts, revert history). With LLM configured, provides deep reasoning about why previous attempts failed. + +## Understanding a Commit + +### View enrichment (intent, reasoning, impact) +```bash +git-skill why +git-skill why HEAD +``` + +### Range summary +```bash +git-skill diff-summary v1.0..v1.1 +``` + +### Enhanced blame +```bash +git-skill blame src/auth/index.ts +``` + +## Dev Workflow Commands + +`init` installs gated slash commands: + +``` +/plan → /implement → /review → /finalize +``` + +- `/plan` checks git history for prior attempts before designing features +- `/implement` follows TDD with WIP commits for backup +- `/review` soft-resets last WIP commit, runs `verify` on staged changes, re-commits clean +- `/finalize` final verify, PR ready for merge +- `/trace` debug unexpected behavior by tracing broken assumptions across git history + +Each phase stops and waits for approval before proceeding. + +## Debugging with Git History + +When code looks correct but behaves wrong, use `/trace` or the `historical-context-debugging` skill: + +```bash +git-skill search "feature keyword" # find related commits +git-skill why # understand original assumptions +git-skill timeline # see all changes chronologically +git-skill verify # validate fix against history +``` + +Three fault types to look for: +1. **Missing Guard** — a flag exists for case X but not similar case Y +2. **Parallel Evolution** — two systems built independently that should share logic +3. **Stale Side Effect** — code updated but cache/config/state wasn't + +## Optional: LLM Enrichment + +Analyze each commit with an LLM (Anthropic or OpenAI) to extract intent, reasoning, and impact: + +```bash +git-skill config # set up API key +git-skill enrich # analyze all unenriched commits +``` + +Enrichments power deeper `verify` analysis and semantic search. + +## Optional: Embeddings + +For semantic search ("auth changes" finds "login", "session", "JWT"): + +```bash +git-skill config # set up embedding provider (Ollama is free) +git-skill embed # generate embeddings for commits + enrichments +``` + +## Automation + +**Every commit** (post-commit hook): +- Captures new commit to SQLite + FTS +- Refreshes Claude memory with latest alerts (5-min cache) + +**Nightly** (`git-skill cron`): +- Fetches team members' commits +- Full re-index + analytics + metrics + auto-embed + memory update + +## Memory System Integration + +`context-update` writes a health summary to `~/.claude/projects//memory/git_context.md`: +- Codebase state (commits, branches, tags) +- Hotspots (last 30 days + all-time) +- Recent decisions (reverts, refactors) +- Health metrics (revert rate, fix-on-fix rate) +- Active alerts (thrashing, revert chains, fix-on-fix patterns) +- Recent activity digest + +Claude's `findRelevantMemories` loads this at session start when doing code work. + +## Troubleshooting + +```bash +git-skill doctor # full health check +git-skill snapshot --force # rebuild from scratch +git-skill context-update --days 30 # regenerate memory context +``` diff --git a/skills/git-history/scripts/check-setup.sh b/skills/git-history/scripts/check-setup.sh new file mode 100755 index 000000000..bff784692 --- /dev/null +++ b/skills/git-history/scripts/check-setup.sh @@ -0,0 +1,19 @@ +#!/bin/bash +# Check if git-skill is installed and configured +# Returns 0 if ready, 1 if setup needed + +if ! command -v git-skill &>/dev/null; then + echo "NOT_INSTALLED" + echo "Run: npm install -g @m2015agg/git-skill && git-skill config" + exit 1 +fi + +if [ ! -d ".git-history" ]; then + echo "NOT_INITIALIZED" + echo "Run: git-skill init" + exit 1 +fi + +# Check freshness +git-skill doctor 2>&1 +exit 0