agentsys 5.2.1 → 5.3.1

package/.cursor/commands/drift-detect.md

@@ -0,0 +1,259 @@
+
+# /drift-detect - Reality Check Scanner
+
+Perform deep repository analysis to identify drift between documented plans and actual implementation.
+
+## Architecture
+
+```
+scan.md → collectors.js (pure JS) → plan-synthesizer (Opus) → report
+          ├─ scanGitHubState()      (single call with full context)
+          ├─ analyzeDocumentation()
+          └─ scanCodebase()
+```
+
+Data collection is pure JavaScript (no LLM). Only semantic analysis uses Opus.
+
+## Arguments
+
+Parse from $ARGUMENTS:
+- `--sources`: Comma-separated list of sources to scan (default: github,docs,code)
+- `--depth`: Scan depth - quick or thorough (default: thorough)
+- `--output`: Output mode - file, display, or both (default: both)
+- `--file`: Output file path (default: drift-detect-report.md)
+
+Example: `/drift-detect --sources github,docs --depth quick --output file`
+
+## Phase 1: Parse Arguments and Collect Data
+
+```javascript
+
+const pluginRoot = getPluginRoot('drift-detect');
+if (!pluginRoot) { console.error('Error: Could not locate drift-detect plugin root'); process.exit(1); }
+
+
+
+// Suggest repo-map if missing or stale
+const mapStatus = repoMap.status(process.cwd());
+if (!mapStatus.exists) {
+  console.log('Repo map not found. For faster, more accurate drift detection, run: /repo-map init');
+} else if (mapStatus.status?.staleness?.isStale) {
+  console.log('Repo map is stale (' + mapStatus.status.staleness.reason + '). Consider: /repo-map update');
+}
+
+// Parse arguments
+const args = '$ARGUMENTS'.split(' ').filter(Boolean);
+const options = {
+  sources: ['github', 'docs', 'code'],
+  depth: 'thorough',
+  output: 'both',
+  file: 'drift-detect-report.md',
+  cwd: process.cwd()
+};
+
+// Parse flags
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--sources' && args[i+1]) {
+    options.sources = args[++i].split(',').map(s => s.trim());
+  } else if (args[i] === '--depth' && args[i+1]) {
+    options.depth = args[++i];
+  } else if (args[i] === '--output' && args[i+1]) {
+    options.output = args[++i];
+  } else if (args[i] === '--file' && args[i+1]) {
+    options.file = args[++i];
+  }
+}
+
+// Validate options
+const allowedSources = ['github', 'docs', 'code'];
+const allowedDepths = ['quick', 'thorough'];
+const allowedOutputs = ['file', 'display', 'both'];
+
+const invalidSources = options.sources.filter(s => !allowedSources.includes(s));
+if (invalidSources.length > 0) {
+  console.error(`Invalid --sources value(s): ${invalidSources.join(', ')}. Allowed: ${allowedSources.join(', ')}`);
+  process.exit(1);
+}
+
+if (!allowedDepths.includes(options.depth)) {
+  console.error(`Invalid --depth value: ${options.depth}. Allowed: ${allowedDepths.join(', ')}`);
+  process.exit(1);
+}
+
+if (!allowedOutputs.includes(options.output)) {
+  console.error(`Invalid --output value: ${options.output}. Allowed: ${allowedOutputs.join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`
+## Starting Reality Check Scan
+
+**Sources**: ${options.sources.join(', ')}
+**Depth**: ${options.depth}
+**Output**: ${options.output}
+
+Collecting data...
+`);
+
+// Collect all data using pure JavaScript (no LLM)
+const collectedData = await collectors.collectAllData(options);
+
+// Check if GitHub data collection succeeded
+if (options.sources.includes('github') && collectedData.github && !collectedData.github.available) {
+  console.log(`
+[WARN] GitHub CLI not available or not authenticated.
+Run \`gh auth login\` to enable GitHub issue scanning.
+Continuing with other sources...
+  `);
+}
+
+console.log(`
+### Data Collection Complete
+
+${collectedData.github?.available ? `- **GitHub**: ${collectedData.github.issues.length} issues, ${collectedData.github.prs.length} PRs` : '- **GitHub**: Not available'}
+${collectedData.docs ? `- **Documentation**: ${Object.keys(collectedData.docs.files).length} files analyzed` : '- **Documentation**: Skipped'}
+${collectedData.code?.summary?.totalDirs ? `- **Code**: ${collectedData.code.summary.totalDirs} directories scanned` : '- **Code**: Skipped'}
+
+→ Sending to semantic analyzer...
+`);
+```
+
+## Phase 2: Semantic Analysis (Single Opus Call)
+
+Send all collected data to plan-synthesizer for deep semantic analysis:
+
+```javascript
+const analysisPrompt = `
+You are analyzing a project to identify drift between documented plans and actual implementation.
+
+## Collected Data
+
+### GitHub State
+${'```'}json
+${JSON.stringify(collectedData.github, null, 2)}
+${'```'}
+
+### Documentation Analysis
+${'```'}json
+${JSON.stringify(collectedData.docs, null, 2)}
+${'```'}
+
+### Codebase Analysis
+${'```'}json
+${JSON.stringify(collectedData.code, null, 2)}
+${'```'}
+
+## Your Task
+
+Be BRUTALLY SPECIFIC. The user wants concrete, actionable insights - not generic observations.
+
+### 1. Issue-by-Issue Verification
+
+For EACH open issue, determine:
+- Is this already implemented? → "Close issue #X - implemented in src/auth/login.js"
+- Is this stale/irrelevant? → "Close issue #X - no longer applicable after Y refactor"
+- Is this blocked? → "Issue #X blocked by: missing Z dependency"
+
+### 2. Phase/Checkbox Validation
+
+For EACH phase or checkbox marked "complete" in docs:
+- Verify against actual code: Does the feature exist?
+- Check for missing pieces: "Phase 'Authentication' marked complete but MISSING:
+  - Password reset functionality (no code in auth/)
+  - Session timeout handling (not implemented)
+  - Tests for login flow (0 test files)"
+
+### 3. Release Readiness Assessment
+
+If there are milestones or planned releases, assess:
+- "Your plan to release tomorrow is UNREALISTIC because:
+  - 3 critical tests missing for payment module
+  - No QA coverage on authentication flows
+  - Issue #45 (security) still open
+  - Phase B only 40% complete despite being marked done"
+
+### 4. Specific Recommendations
+
+Output SPECIFIC actions, not generic advice:
+- "Close issues: #12, #34, #56 (already implemented)"
+- "Reopen: Phase C (missing: X, Y, Z)"
+- "Block release until: tests added for auth/, issue #78 fixed"
+- "Update PLAN.md: Phase B is NOT complete - missing items listed above"
+
+## Output Format
+
+```markdown
+# Reality Check Report
+
+## Executive Summary
+[2-3 sentences: Overall project health and biggest concerns]
+
+## Issues to Close (Already Done)
+- #XX: [title] - Implemented in [file/location]
+- #YY: [title] - No longer relevant because [reason]
+
+## Phases Marked Complete But NOT Actually Done
+### [Phase Name]
+**Status in docs**: Complete [OK]
+**Actual status**: INCOMPLETE
+**Missing**:
+- [ ] [Specific missing item 1]
+- [ ] [Specific missing item 2]
+
+## Release Blockers
+If you're planning to ship soon, these MUST be addressed:
+1. [Specific blocker with file/issue reference]
+2. [Specific blocker with file/issue reference]
+
+## Issues That Need Attention
+- #XX: [why it's stale/blocked/misprioritized]
+
+## Quick Wins
+Things you can do right now:
+1. Close issue #XX (already done)
+2. Update Phase Y status (not complete)
+3. Add test for [specific untested code]
+```
+`;
+
+Invoke the plan-synthesizer agent
+```
+
+## Phase 3: Output Report
+
+After the synthesizer completes, the report is available. Handle output per settings:
+
+```javascript
+// The synthesizer outputs the report directly
+// Handle file writing if requested
+
+if (options.output === 'file' || options.output === 'both') {
+  console.log(`\n---\nReport saved to: ${options.file}`);
+}
+
+console.log(`
+## Reality Check Complete
+
+Use the findings above to realign your project with reality.
+Run \`/drift-detect --depth quick\` for faster subsequent scans.
+`);
+```
+
+## Quick Reference
+
+| 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 |
+
+## Success Criteria
+
+- Data collected via pure JavaScript (no LLM overhead)
+- Single Opus call for semantic analysis with full context
+- Drift and gaps clearly identified with examples
+- Prioritized reconstruction plan produced
+- Report output per user settings
+
+Begin scan now.

package/.cursor/commands/enhance.md

@@ -0,0 +1,172 @@
+
+# /enhance - Master Enhancement Orchestrator
+
+Run all enhancement analyzers in parallel and generate a unified report.
+
+## Overview
+
+The master `/enhance` command orchestrates 7 specialized enhancers:
+- **plugin** - Plugin structures, MCP tools, security patterns
+- **agent** - Agent prompts, frontmatter, tool restrictions
+- **claudemd** - CLAUDE.md/AGENTS.md project memory files
+- **docs** - Documentation structure and RAG optimization
+- **prompt** - General prompt quality and clarity
+- **hooks** - Hook definitions and frontmatter quality
+- **skills** - SKILL.md structure and trigger clarity
+
+## Arguments
+
+Parse from $ARGUMENTS:
+- **target-path**: Directory or file to analyze (default: current directory)
+- **--apply**: Apply auto-fixes for HIGH certainty issues after report
+- **--focus=TYPE**: Run only specified enhancer(s): plugin, agent, claudemd/claude-memory, docs, prompt, hooks, skills
+- **--verbose**: Include LOW certainty issues in report
+- **--show-suppressed**: Show what's being filtered by auto-learned suppressions
+- **--no-learn**: Disable auto-learning for this run (analyze but don't save)
+- **--reset-learned**: Clear all auto-learned suppressions for this project
+- **--export-learned**: Export learned suppressions as JSON for team sharing
+
+## Workflow
+
+1. **Discovery** - Detect what content types exist in target path
+2. **Load Suppressions** - Load auto-learned and manual suppressions for project
+3. **Launch** - Start all relevant enhancers in parallel via Task()
+4. **Aggregate** - Collect and deduplicate findings from all enhancers
+5. **Report** - Generate unified report from aggregated findings
+6. **Auto-Learn** - Detect false positives and save for future runs (unless --no-learn)
+7. **Fix** - Apply auto-fixes if --apply flag is present
+
+## Implementation
+
+Execute the `enhance-orchestrator` skill directly. The skill workflow:
+
+1. Parse arguments from $ARGUMENTS
+2. Run discovery to find content types
+3. Spawn enhancer agents in parallel via Task() for each content type
+4. Aggregate results from all enhancers
+5. Generate unified report
+
+See `skills/enhance-orchestrator/SKILL.md` for detailed implementation.
+
+## Output Format
+
+```markdown
+# Enhancement Analysis Report
+
+**Target**: {targetPath}
+**Date**: {timestamp}
+**Enhancers Run**: plugin, agent, docs
+
+## Executive Summary
+
+| Enhancer | HIGH | MEDIUM | LOW | Auto-Fixable |
+|----------|------|--------|-----|--------------|
+| plugin | 2 | 3 | 1 | 1 |
+| agent | 1 | 2 | 0 | 1 |
+| docs | 0 | 4 | 2 | 0 |
+| **Total** | **3** | **9** | **3** | **2** |
+
+## HIGH Certainty Issues (3)
+
+[Grouped by enhancer, sorted by file]
+
+## MEDIUM Certainty Issues (9)
+
+[...]
+
+## Auto-Fix Summary
+
+2 issues can be automatically fixed with `--apply` flag.
+```
+
+## Example Usage
+
+```bash
+# Full analysis of current directory
+/enhance
+
+# Focus on specific enhancer type
+/enhance --focus=agent
+
+# Apply auto-fixes for HIGH certainty issues
+/enhance --apply
+
+# Analyze specific path with verbose output
+/enhance plugins/next-task --verbose
+
+# Combined flags
+/enhance --focus=plugin --apply --verbose
+
+# Auto-Learning Suppression System
+# See what's being filtered by auto-learned suppressions
+/enhance --show-suppressed
+
+# Run without auto-learning (analyze only, don't save new suppressions)
+/enhance --no-learn
+
+# Reset all learned suppressions for this project
+/enhance --reset-learned
+
+# Export learned suppressions for team sharing
+/enhance --export-learned > suppressions-export.json
+```
+
+## Success Criteria
+
+- All relevant enhancers run in parallel
+- Findings deduplicated and sorted by certainty
+- Clear executive summary with counts
+- Auto-fixable issues highlighted
+- Fixes applied only with explicit --apply flag
+- Auto-learning detects false positives with 90%+ confidence
+- Learned suppressions stored in cross-platform location (${STATE_DIR}/enhance/suppressions.json)
+- Zero token waste on previously suppressed findings
+
+---
+
+# /plugin
+
+Spawns `plugin-enhancer` agent which invokes `enhance-plugins` skill.
+See skill for patterns, detection logic, and auto-fix implementations.
+
+---
+
+# /agent
+
+Spawns `agent-enhancer` agent which invokes `enhance-agent-prompts` skill.
+See skill for patterns, detection logic, and auto-fix implementations.
+
+---
+
+# /docs
+
+Spawns `docs-enhancer` agent which invokes `enhance-docs` skill.
+See skill for patterns, detection logic, and auto-fix implementations.
+
+---
+
+# /claudemd
+
+Spawns `claudemd-enhancer` agent which invokes `enhance-claude-memory` skill.
+See skill for patterns, detection logic, and auto-fix implementations.
+
+---
+
+# /prompt
+
+Spawns `prompt-enhancer` agent which invokes `enhance-prompts` skill.
+See skill for patterns, detection logic, and auto-fix implementations.
+
+---
+
+# /hooks
+
+Spawns `hooks-enhancer` agent which invokes `enhance-hooks` skill.
+See skill for patterns, detection logic, and auto-fix implementations.
+
+---
+
+# /skills
+
+Spawns `skills-enhancer` agent which invokes `enhance-skills` skill.
+See skill for patterns, detection logic, and auto-fix implementations.

package/.cursor/commands/learn.md

@@ -0,0 +1,165 @@
+
+# /learn - Learning Guide Generator
+
+Research any topic by gathering online resources and synthesize into a comprehensive learning guide with RAG-optimized indexes.
+
+## Depth Levels
+
+| Level | Sources | Use Case |
+|-------|---------|----------|
+| `brief` | 10 | Quick overview, time-sensitive |
+| `medium` | 20 | **Default** - balanced coverage |
+| `deep` | 40 | Comprehensive, academic depth |
+
+## Arguments
+
+Parse from $ARGUMENTS:
+
+- **topic**: The subject to learn about (required)
+- **--depth**: `brief` (10 sources), `medium` (20, default), or `deep` (40)
+- **--no-enhance**: Skip enhancement pass (default: enhance enabled)
+
+## Execution
+
+### Phase 1: Parse Arguments
+
+```javascript
+const args = '$ARGUMENTS';
+
+// Extract depth flag
+const depthMatch = args.match(/--depth=(brief|medium|deep)/);
+const depth = depthMatch ? depthMatch[1] : 'medium';
+const noEnhance = args.includes('--no-enhance');
+
+// Extract topic (everything except flags)
+const topic = args
+  .replace(/--depth=(brief|medium|deep)/g, '')
+  .replace(/--no-enhance/g, '')
+  .trim();
+
+if (!topic) {
+  return 'Usage: /learn <topic> [--depth=brief|medium|deep]';
+}
+
+// Generate slug for filenames
+const slug = topic
+  .toLowerCase()
+  .replace(/[^a-z0-9\s-]/g, '')
+  .replace(/\s+/g, '-')
+  .replace(/-+/g, '-')
+  .replace(/^-|-$/g, '')
+  .substring(0, 64);
+
+// Source counts by depth
+const sourceCounts = { brief: 10, medium: 20, deep: 40 };
+const minSources = sourceCounts[depth];
+```
+
+### Phase 2: Check Existing Guide
+
+```javascript
+// Check if guide already exists
+const existingGuide = await Glob({ pattern: `agent-knowledge/${slug}.md` });
+
+if (existingGuide.length > 0) {
+  // Ask user: update existing or create fresh?
+  const choice = await AskUserQuestion({
+    questions: [{
+      question: `A guide for "${topic}" already exists. What would you like to do?`,
+      header: 'Existing guide',
+      options: [
+        { label: 'Update existing', description: 'Add new sources and refresh content' },
+        { label: 'Create fresh', description: 'Start over with new research' }
+      ],
+      multiSelect: false
+    }]
+  });
+
+  if (choice === 'Create fresh') {
+    // Will overwrite
+  }
+}
+```
+
+### Phase 3: Spawn Learn Agent
+
+```javascript
+const taskOutput = Invoke the learn-agent agent
+```
+
+### Phase 4: Parse Results
+
+```javascript
+function parseLearnResult(output) {
+  const match = output.match(/=== LEARN_RESULT ===[\s\S]*?({[\s\S]*?})[\s\S]*?=== END_RESULT ===/);
+  return match ? JSON.parse(match[1]) : null;
+}
+
+const result = parseLearnResult(taskOutput);
+```
+
+### Phase 5: Present Results
+
+```markdown
+## Learning Guide Created
+
+**Topic**: {topic}
+**File**: agent-knowledge/{slug}.md
+**Sources**: {sourceCount} resources analyzed
+
+### Quality Assessment
+
+| Metric | Rating |
+|--------|--------|
+| Coverage | {coverage}/10 |
+| Source Diversity | {diversity}/10 |
+| Example Quality | {examples}/10 |
+| Confidence | {confidence}/10 |
+
+### Source Breakdown
+
+| Type | Count |
+|------|-------|
+| Official Docs | {n} |
+| Tutorials | {n} |
+| Q&A/Stack Overflow | {n} |
+| Blog Posts | {n} |
+| GitHub Examples | {n} |
+
+### Next Steps
+
+- [ ] Review the guide at `agent-knowledge/{slug}.md`
+- [ ] Check source quality in `agent-knowledge/resources/{slug}-sources.json`
+- [ ] Run `/learn {related-topic}` to expand your knowledge base
+```
+
+## Output Structure
+
+Each `/learn` run creates/updates:
+
+```
+agent-knowledge/
+  CLAUDE.md           # Master index (updated)
+  AGENTS.md           # Master index for OpenCode/Codex (updated)
+  {slug}.md           # Topic-specific guide (created)
+  resources/
+    {slug}-sources.json  # Source metadata (created)
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No topic provided | Show usage help |
+| WebSearch fails | Retry with alternative queries |
+| Insufficient sources | Warn user, proceed with available |
+| Enhancement fails | Skip enhancement, note in output |
+
+## Example Usage
+
+```bash
+/learn recursion
+/learn react hooks --depth=deep
+/learn "kubernetes networking" --depth=brief
+/learn python async --no-enhance
+```