drift-detect
Deep repository analysis to realign project plans with actual code reality. `/drift-detect` discovers drift between documented plans (CHANGE
Open source Open in the app JSON README (API)
About
Deep repository analysis to realign project plans with actual code reality. `/drift-detect` discovers drift between documented plans (CHANGELOG, ARCHITECTURE.md, design docs, README claims) and what the code actually does, then produces a prioritized reconstruction plan. Pure JavaScript collectors gather data fast (no LLM overhead) and a single Opus call performs the deep semantic analysis - 77% fewer tokens than multi-agent approaches. Tested on 1,000+ repositories. Outputs a ranked list of drift items with severity, evidence, and suggested resolution.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- agent-sh
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 4
- Forks
- 1
- Last push
- 2026-07-22T13:27:58Z
- Repository state
- ativo
- Language
- JavaScript
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
agent-sh/drift-detect/drift-detect
README
# drift-detect
Deep repository analysis to realign project plans with actual code reality.
## Overview
The drift-detect plugin performs comprehensive analysis of your codebase to identify drift between documented plans and actual implementation. It uses pure JavaScript for data collection (no LLM overhead) and a single Sonnet call for deep semantic analysis.
## Architecture
```
/drift-detect
│
├─→ collectors.js (pure JavaScript)
│ ├─ scanGitHubState() → issues, PRs, milestones
│ ├─ analyzeDocumentation() → docs, plans, checkboxes
│ ├─ scanCodebase() → structure, frameworks, health
│ └─ getRepoIntelSignals() → doc-drift, area health (optional)
│
└─→ plan-synthesizer (Sonnet)
└─ Deep semantic analysis with full context
```
**Data collection**: No LLM calls - pure JavaScript
**Semantic analysis**: Single Sonnet call with complete context
**Token efficiency**: ~77% reduction vs. previous multi-agent architecture
## Features
- **Efficient data collection**: JavaScript collectors for deterministic extraction
- **Deep semantic analysis**: Single Sonnet call for cross-referencing and insights
- **Drift detection**: Identifies where plans have diverged from reality
- **Gap analysis**: Finds missing tests, documentation, and implementation
- **Priority ranking**: Context-aware prioritization
- **Command-line flags**: No persistent settings files needed
## Commands
### `/drift-detect`
Run a comprehensive reality check scan.
```
/drift-detect # Full scan (default)
/drift-detect --sources github,docs # Specific sources
/drift-detect --depth quick # Quick scan
/drift-detect --output file --file report.md # Custom output
```
| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--sources` | github,docs,code | all three | Which sources to scan |
| `--depth` | quick, thorough | thorough | How deep to analyze |
| `--output` | file, display, both | both | Where to output results |
| `--file` | path | drift-detect-report.md | Output file path |
## Agent
| Agent | Purpose | Model |
|-------|---------|-------|
| `plan-synthesizer` | Deep semantic analysis, drift detection, prioritization | sonnet |
## Workflow
```
/drift-detect
│
├─→ Parse command flags
│
├─→ JavaScript Data Collection (parallel, no LLM)
│ ├─ scanGitHubState()
│ ├─ analyzeDocumentation()
│ └─ scanCodebase()
│
└─→ Single Sonnet Analysis Call
├─ Cross-reference docs vs code
├─ Identify drift patterns
├─ Find gaps
└─ Generate prioritized plan
│
▼
Reality Check Report
```
## Data Sources
### GitHub (`--sources github`)
- Open issues categorized by labels (bug, feature, security)
- Open pull requests with draft status
- Milestones with due dates and completion
- Stale items (> 90 days inactive)
- Themes extracted from issue titles
**Requires**: `gh` CLI installed and authenticated
### Documentation (`--sources docs`)
- README.md, CONTRIBUTING.md, CHANGELOG.md
- PLAN.md, CLAUDE.md
- docs/*.md
- Checkbox completion rates
- Feature lists and planned work
### Code (`--sources code`)
- Directory structure analysis
- Framework detection (React, Express, Vue, etc.)
- Test framework detection (Jest, Mocha, Vitest)
- Health indicators (CI, linting, tests)
- Implemented features
### Repo-Intel (optional, auto-detected)
- Doc files with low code coupling - likely stale documentation
- Directory-level health: owners, hotspot score, bug-fix rate
- At-risk and needs-attention areas for focused drift analysis
**Requires**: `agent-analyzer` binary and a cached `repo-intel.json` map. If no map exists, the scan prompts to generate one (~5 seconds).
## Output
The scan produces:
1. **Executive Summary**: Overview of project state
2. **Drift Analysis**: Where plans diverge from reality (with evidence)
3. **Gap Analysis**: Missing tests, docs, implementation (with severity)
4. **Cross-Reference**: Documented vs. implemented features
5. **Reconstruction Plan**: Prioritized action items by timeframe
### Example Output
```markdown
# Reality Check Report
## Executive Summary
Project has moderate drift: 8 stale priority issues and 20% plan completion.
Strong code health (tests + CI) but documentation lags implementation.
## Drift Analysis
### Priority Neglect
**Severity**: high
8 high-priority issues inactive for 60+ days.
**Recommendation**: Triage stale issues - close, reassign, or deprioritize.
## Gap Analysis
### No Automated Tests
**Severity**: critical
**Impact**: High risk of regressions, difficult to refactor safely.
**Recommendation**: Add test framework and critical path coverage.
## Prioritized Plan
### Immediate (This Week)
1. **Close issue #45** - already implemented
2. **Address security vulnerability** in auth module
### Short-Term (This Month)
1. Add test coverage for API endpoints
2. Update README to reflect current features
```
## Skills
### drift-analysis
Provides knowledge for:
- Drift detection patterns and signals
- Prioritization framework
- Cross-reference matching logic
- Output templates
## Requirements
- GitHub CLI (`gh`) for GitHub scanning
- Git repository
- Node.js
## Breaking Changes from v1
- `.claude/drift-detect.local.md` settings file no longer used
- Use command flags instead: `--sources`, `--depth`, `--output`, `--file`
- Three scanner agents replaced with JavaScript collectors
## License
MIT