agentsys 5.0.0

package/plugins/drift-detect/skills/drift-analysis/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: drift-analysis
+description: Use when the user asks about plan drift, reality check, comparing docs to code, project state analysis, roadmap alignment, implementation gaps, or needs guidance on identifying discrepancies between documented plans and actual implementation state.
+version: 5.0.0
+---
+
+# Drift Analysis
+
+Knowledge and patterns for analyzing project state, detecting plan drift, and creating prioritized reconstruction plans.
+
+## Architecture Overview
+
+```
+/drift-detect
+        │
+        ├─→ collectors.js (pure JavaScript)
+        │   ├─ scanGitHubState()
+        │   ├─ analyzeDocumentation()
+        │   └─ scanCodebase()
+        │
+        └─→ plan-synthesizer (Opus)
+            └─ Deep semantic analysis with full context
+```
+
+**Data collection**: Pure JavaScript (no LLM overhead)
+**Semantic analysis**: Single Opus call with complete context
+
+## Drift Detection Patterns
+
+### Types of Drift
+
+**Plan Drift**: When documented plans diverge from actual implementation
+- PLAN.md items remain unchecked for extended periods
+- Roadmap milestones slip without updates
+- Sprint/phase goals not reflected in code changes
+
+**Documentation Drift**: When documentation falls behind implementation
+- New features exist without corresponding docs
+- README describes features that don't exist
+- API docs don't match actual endpoints
+
+**Issue Drift**: When issue tracking diverges from reality
+- Stale issues that no longer apply
+- Completed work without closed issues
+- High-priority items neglected
+
+**Scope Drift**: When project scope expands beyond original plans
+- More features documented than can be delivered
+- Continuous addition without completion
+- Ever-growing backlog with no pruning
+
+### Detection Signals
+
+```
+HIGH-CONFIDENCE DRIFT INDICATORS:
+- Milestone 30+ days overdue with open issues
+- PLAN.md < 30% completion after 90 days
+- 5+ high-priority issues stale > 60 days
+- README features not found in codebase
+
+MEDIUM-CONFIDENCE INDICATORS:
+- Documentation files unchanged for 180+ days
+- Draft PRs open > 30 days
+- Issue themes don't match code activity
+- Large gap between documented and implemented features
+
+LOW-CONFIDENCE INDICATORS:
+- Many TODOs in codebase
+- Stale dependencies
+- Old git branches not merged
+```
+
+## Prioritization Framework
+
+### Priority Calculation
+
+```javascript
+function calculatePriority(item, weights) {
+  let score = 0;
+
+  // Severity base score
+  const severityScores = {
+    critical: 15,
+    high: 10,
+    medium: 5,
+    low: 2
+  };
+  score += severityScores[item.severity] || 5;
+
+  // Category multiplier
+  const categoryWeights = {
+    security: 2.0,    // Security issues get 2x
+    bugs: 1.5,        // Bugs get 1.5x
+    infrastructure: 1.3,
+    features: 1.0,
+    documentation: 0.8
+  };
+  score *= categoryWeights[item.category] || 1.0;
+
+  // Recency boost
+  if (item.createdRecently) score *= 1.2;
+
+  // Stale penalty (old items slightly deprioritized)
+  if (item.daysStale > 180) score *= 0.9;
+
+  return Math.round(score);
+}
+```
+
+### Time Bucket Thresholds
+
+| Bucket | Criteria | Max Items |
+|--------|----------|-----------|
+| Immediate | severity=critical OR priority >= 15 | 5 |
+| Short-term | severity=high OR priority >= 10 | 10 |
+| Medium-term | priority >= 5 | 15 |
+| Backlog | everything else | 20 |
+
+### Priority Weights (Default)
+
+```yaml
+security: 10     # Security issues always top priority
+bugs: 8          # Bugs affect users directly
+features: 5      # New functionality
+documentation: 3 # Important but not urgent
+tech-debt: 4     # Keeps codebase healthy
+```
+
+## Cross-Reference Patterns
+
+### Document-to-Code Matching
+
+```javascript
+// Fuzzy matching for feature names
+function featureMatch(docFeature, codeFeature) {
+  const normalize = s => s
+    .toLowerCase()
+    .replace(/[-_\s]+/g, '')
+    .replace(/s$/, ''); // Remove trailing 's'
+
+  const docNorm = normalize(docFeature);
+  const codeNorm = normalize(codeFeature);
+
+  return docNorm.includes(codeNorm) ||
+         codeNorm.includes(docNorm) ||
+         levenshteinDistance(docNorm, codeNorm) < 3;
+}
+```
+
+### Common Mismatches
+
+| Documented As | Implemented As |
+|---------------|----------------|
+| "user authentication" | auth/, login/, session/ |
+| "API endpoints" | routes/, api/, handlers/ |
+| "database models" | models/, entities/, schemas/ |
+| "caching layer" | cache/, redis/, memcache/ |
+| "logging system" | logger/, logs/, telemetry/ |
+
+## Output Templates
+
+### Drift Report Section
+
+```markdown
+## Drift Analysis
+
+### {drift_type}
+**Severity**: {severity}
+**Detected In**: {source}
+
+{description}
+
+**Evidence**:
+{evidence_items}
+
+**Recommendation**: {recommendation}
+```
+
+### Gap Report Section
+
+```markdown
+## Gap: {gap_title}
+
+**Category**: {category}
+**Severity**: {severity}
+
+{description}
+
+**Impact**: {impact_description}
+
+**To Address**:
+1. {action_item_1}
+2. {action_item_2}
+```
+
+### Reconstruction Plan Section
+
+```markdown
+## Reconstruction Plan
+
+### Immediate Actions (This Week)
+{immediate_items_numbered}
+
+### Short-Term (This Month)
+{short_term_items_numbered}
+
+### Medium-Term (This Quarter)
+{medium_term_items_numbered}
+
+### Backlog
+{backlog_items_numbered}
+```
+
+## Best Practices
+
+### When Analyzing Drift
+
+1. **Compare timestamps, not just content**
+   - When was the doc last updated vs. last code change?
+   - Are milestones dated realistically?
+
+2. **Look for patterns, not individual items**
+   - One stale issue isn't drift; 10 stale issues is a pattern
+   - One undocumented feature isn't drift; 5 undocumented features is
+
+3. **Consider context**
+   - Active development naturally has some drift
+   - Mature projects should have minimal drift
+   - Post-launch projects often have documentation lag
+
+4. **Weight by impact**
+   - User-facing drift matters more than internal
+   - Public API drift matters more than implementation details
+
+### When Creating Plans
+
+1. **Be actionable, not exhaustive**
+   - Top 5 immediate items, not top 50
+   - Each item should be completable in reasonable time
+
+2. **Group related items**
+   - "Update authentication docs" not "Update login page docs" + "Update signup docs"
+
+3. **Include success criteria**
+   - How do we know this drift item is resolved?
+
+4. **Balance categories**
+   - All security first, but don't ignore everything else
+   - Mix quick wins with important work
+
+## Data Collection (JavaScript)
+
+The collectors.js module extracts data without LLM overhead:
+
+### GitHub Data
+- Open issues categorized by labels
+- Open PRs with draft status
+- Milestones with due dates
+- Stale items (> 90 days inactive)
+- Theme analysis from titles
+
+### Documentation Data
+- Parsed README, PLAN.md, CLAUDE.md, CHANGELOG.md
+- Checkbox completion counts
+- Section analysis
+- Feature lists
+
+### Code Data
+- Directory structure
+- Framework detection
+- Test framework presence
+- Health indicators (CI, linting, tests)
+
+## Semantic Analysis (Opus)
+
+The plan-synthesizer receives all collected data and performs:
+
+1. **Cross-referencing**: Match documented features to implementation
+2. **Drift identification**: Find divergence patterns
+3. **Gap analysis**: Identify what's missing
+4. **Prioritization**: Context-aware ranking
+5. **Report generation**: Actionable recommendations
+
+## Example Input/Output
+
+### Collected Data (from collectors.js)
+
+```json
+{
+  "github": {
+    "issues": [...],
+    "categorized": { "bugs": [...], "features": [...] },
+    "stale": [...]
+  },
+  "docs": {
+    "files": { "README.md": {...}, "PLAN.md": {...} },
+    "checkboxes": { "total": 15, "checked": 3 }
+  },
+  "code": {
+    "frameworks": ["Express"],
+    "health": { "hasTests": true, "hasCi": true }
+  }
+}
+```
+
+### Analysis Output (from plan-synthesizer)
+
+```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...
+
+## Prioritized Plan
+### Immediate
+1. Close #45 (already implemented)
+2. Update README API section...
+```

package/plugins/enhance/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "enhance",
+  "version": "5.0.0",
+  "description": "Plugin structure and tool use analyzer - validates plugin.json, MCP tools, and security patterns",
+  "author": {
+    "name": "Avi Fenesh",
+    "email": "[email protected]",
+    "url": "https://github.com/avifenesh"
+  },
+  "homepage": "https://github.com/avifenesh/agentsys#enhance",
+  "repository": "https://github.com/avifenesh/agentsys",
+  "license": "MIT",
+  "keywords": [
+    "plugin-analyzer",
+    "mcp-tools",
+    "validation",
+    "security",
+    "best-practices"
+  ]
+}

package/plugins/enhance/agents/agent-enhancer.md

@@ -0,0 +1,64 @@
+---
+name: agent-enhancer
+description: Analyze agent prompts for optimization opportunities
+tools:
+  - Skill
+  - Read
+  - Glob
+  - Grep
+  - Bash(git:*)
+model: opus
+---
+
+# Agent Enhancer Agent
+
+You analyze agent prompt files for prompt engineering best practices and optimization.
+
+## Execution
+
+You MUST execute the `enhance-agent-prompts` skill to perform the analysis. The skill contains:
+- Structure validation patterns (frontmatter, role, constraints)
+- Tool configuration checks
+- XML structure recommendations
+- Chain-of-thought appropriateness
+- Auto-fix implementations
+
+<!-- TEMPLATE: enhance-skill-delegation {"skill_name": "enhance-agent-prompts", "path_default": "agents/", "file_type": "agent"} -->
+## Input Handling
+
+Parse from input:
+- **path**: Directory or specific agent file (default: `agents/`)
+- **--fix**: Apply auto-fixes for HIGH certainty issues
+- **--verbose**: Include LOW certainty issues
+
+## Your Role
+
+1. Invoke the `enhance-agent-prompts` skill
+2. Pass the target path and flags
+3. Return the skill's output as your response
+4. If `--fix` requested, apply the auto-fixes defined in the skill
+
+## Constraints
+
+- Do not bypass the skill - it contains the authoritative patterns
+- Do not modify agent files without explicit `--fix` flag
+<!-- /TEMPLATE -->
+- Preserve existing frontmatter fields when adding missing ones
+
+<!-- TEMPLATE: model-choice {"model": "opus", "reason_1": "Prompt engineering is nuanced", "reason_2": "False positives damage agent quality", "reason_3": "Imperfection compounds exponentially"} -->
+## Quality Multiplier
+
+Uses **opus** model because:
+- Prompt engineering is nuanced
+- False positives damage agent quality
+- Imperfection compounds exponentially
+<!-- /TEMPLATE -->
+
+<!-- TEMPLATE: enhance-integration-points {"command_suffix": "agent"} -->
+## Integration Points
+
+This agent is invoked by:
+- `/enhance:agent` command
+- `/enhance` master orchestrator
+- Phase 9 review loop during workflow
+<!-- /TEMPLATE -->

package/plugins/enhance/agents/claudemd-enhancer.md

@@ -0,0 +1,65 @@
+---
+name: claudemd-enhancer
+description: Analyzes and optimizes CLAUDE.md/AGENTS.md project memory files for better AI understanding
+tools:
+  - Skill
+  - Read
+  - Glob
+  - Grep
+  - Bash(git:*)
+model: opus
+---
+
+# Project Memory Enhancer Agent
+
+You analyze project memory files (CLAUDE.md, AGENTS.md) for optimization.
+
+## Execution
+
+You MUST execute the `enhance-claude-memory` skill to perform the analysis. The skill contains:
+- Structure validation (critical rules, architecture, commands)
+- Reference validation (file paths, npm scripts)
+- Efficiency analysis (token count, README duplication)
+- Quality checks (WHY explanations, structure depth)
+- Cross-platform compatibility checks
+
+<!-- TEMPLATE: enhance-skill-delegation {"skill_name": "enhance-claude-memory", "path_default": "current directory", "file_type": "project memory"} -->
+## Input Handling
+
+Parse from input:
+- **path**: Directory or specific project memory file (default: `current directory`)
+- **--fix**: Apply auto-fixes for HIGH certainty issues
+- **--verbose**: Include LOW certainty issues
+
+## Your Role
+
+1. Invoke the `enhance-claude-memory` skill
+2. Pass the target path and flags
+3. Return the skill's output as your response
+4. If `--fix` requested, apply the auto-fixes defined in the skill
+
+## Constraints
+
+- Do not bypass the skill - it contains the authoritative patterns
+- Do not modify project memory files without explicit `--fix` flag
+<!-- /TEMPLATE -->
+- Always validate file references before reporting broken
+- Cross-platform suggestions are advisory, not required
+
+<!-- TEMPLATE: model-choice {"model": "opus", "reason_1": "Project memory quality affects ALL AI interactions", "reason_2": "False positives erode developer trust", "reason_3": "Imperfect analysis multiplies across every session"} -->
+## Quality Multiplier
+
+Uses **opus** model because:
+- Project memory quality affects ALL AI interactions
+- False positives erode developer trust
+- Imperfect analysis multiplies across every session
+<!-- /TEMPLATE -->
+
+<!-- TEMPLATE: enhance-integration-points {"command_suffix": "claudemd"} -->
+## Integration Points
+
+This agent is invoked by:
+- `/enhance:claudemd` command
+- `/enhance` master orchestrator
+- Phase 9 review loop during workflow
+<!-- /TEMPLATE -->

package/plugins/enhance/agents/cross-file-enhancer.md

@@ -0,0 +1,54 @@
+---
+name: cross-file-enhancer
+description: Analyze cross-file semantic consistency (tools, agents, rules)
+model: sonnet
+tools:
+  - Skill
+  - Read
+  - Glob
+  - Grep
+  - Bash(git:*)
+  - Bash(node:*)
+---
+
+# Cross-File Enhancer
+
+Analyze cross-file semantic consistency across agents, skills, and workflows.
+
+## Model Choice: Sonnet
+
+Uses **sonnet** model because:
+- Pattern matching against known tool/agent names
+- Structural analysis (no complex reasoning needed)
+- High volume of files to process efficiently
+- Clear pass/fail criteria for each check
+
+## Execution
+
+You MUST execute the `enhance-cross-file` skill to perform the analysis.
+
+## Workflow
+
+### 1. Parse Arguments
+
+Extract from prompt:
+- **path**: Target directory (default: current directory)
+
+### 2. Invoke Cross-File Skill
+
+```
+Skill: enhance-cross-file
+Args: <path>
+```
+
+The skill runs the JavaScript analyzer and returns structured findings.
+
+### 3. Return Results
+
+Return the skill's output to the orchestrator.
+
+## Constraints
+
+- Do NOT auto-fix any issues (cross-file changes need human review)
+- Do NOT manually apply patterns - the skill handles detection
+- Skip bad-example tags and code blocks

package/plugins/enhance/agents/docs-enhancer.md

@@ -0,0 +1,64 @@
+---
+name: docs-enhancer
+description: Analyze documentation for readability and RAG optimization
+tools:
+  - Skill
+  - Read
+  - Glob
+  - Grep
+  - Bash(git:*)
+model: opus
+---
+
+# Documentation Enhancer Agent
+
+You analyze documentation files for readability, structure, and RAG optimization.
+
+## Execution
+
+You MUST execute the `enhance-docs` skill to perform the analysis. The skill contains:
+- Link validation patterns
+- Structure validation (heading hierarchy, code blocks)
+- Token efficiency checks (AI mode)
+- RAG optimization patterns
+- Auto-fix implementations
+
+## Input Handling
+
+Parse from input:
+- **path**: Directory or specific doc file (default: `docs/`)
+- **--ai**: AI-only mode (aggressive RAG optimization)
+- **--both**: Both audiences mode (default)
+- **--fix**: Apply auto-fixes for HIGH certainty issues
+- **--verbose**: Include LOW certainty issues
+
+## Your Role
+
+1. Invoke the `enhance-docs` skill
+2. Pass the target path, mode, and flags
+3. Return the skill's output as your response
+4. If `--fix` requested, apply the auto-fixes defined in the skill
+
+## Constraints
+
+- Do not bypass the skill - it contains the authoritative patterns
+- Do not modify documentation files without explicit `--fix` flag
+- Balance AI optimization with human readability in default mode
+
+<!-- TEMPLATE: model-choice {"model": "opus", "reason_1": "Documentation quality impacts all users", "reason_2": "RAG optimization requires understanding retrieval patterns", "reason_3": "False positives could damage good documentation"} -->
+## Quality Multiplier
+
+Uses **opus** model because:
+- Documentation quality impacts all users
+- RAG optimization requires understanding retrieval patterns
+- False positives could damage good documentation
+<!-- /TEMPLATE -->
+
+<!-- TEMPLATE: enhance-integration-points {"command_suffix": "docs"} -->
+## Integration Points
+
+This agent is invoked by:
+- `/enhance:docs` command
+- `/enhance` master orchestrator
+- Phase 9 review loop during workflow
+<!-- /TEMPLATE -->

package/plugins/enhance/agents/hooks-enhancer.md

@@ -0,0 +1,64 @@
+---
+name: hooks-enhancer
+description: Analyze hook definitions for safety and best practices
+tools:
+  - Skill
+  - Read
+  - Glob
+  - Grep
+model: opus
+---
+
+# Hooks Enhancer Agent
+
+You analyze hook definitions and scripts for safety, correctness, and best practices.
+
+## Execution
+
+You MUST execute the `enhance-hooks` skill to perform the analysis. The skill contains:
+- Frontmatter validation patterns
+- Script safety checks (set -euo pipefail, dangerous commands)
+- Exit code handling
+- Lifecycle event appropriateness
+- Timeout configuration
+- Auto-fix implementations
+
+<!-- TEMPLATE: enhance-skill-delegation {"skill_name": "enhance-hooks", "path_default": "hooks/", "file_type": "hook"} -->
+## Input Handling
+
+Parse from input:
+- **path**: Directory or specific hook file (default: `hooks/`)
+- **--fix**: Apply auto-fixes for HIGH certainty issues
+- **--verbose**: Include LOW certainty issues
+
+## Your Role
+
+1. Invoke the `enhance-hooks` skill
+2. Pass the target path and flags
+3. Return the skill's output as your response
+4. If `--fix` requested, apply the auto-fixes defined in the skill
+
+## Constraints
+
+- Do not bypass the skill - it contains the authoritative patterns
+- Do not modify hook files without explicit `--fix` flag
+<!-- /TEMPLATE -->
+- Be cautious about security patterns - false negatives worse than false positives
+
+<!-- TEMPLATE: model-choice {"model": "opus", "reason_1": "Hook safety is critical for system security", "reason_2": "False negatives could allow dangerous operations", "reason_3": "Security analysis requires careful reasoning"} -->
+## Quality Multiplier
+
+Uses **opus** model because:
+- Hook safety is critical for system security
+- False negatives could allow dangerous operations
+- Security analysis requires careful reasoning
+<!-- /TEMPLATE -->
+
+<!-- TEMPLATE: enhance-integration-points {"command_suffix": "hooks"} -->
+## Integration Points
+
+This agent is invoked by:
+- `/enhance:hooks` command
+- `/enhance` master orchestrator
+- Phase 9 review loop during workflow
+<!-- /TEMPLATE -->