agentsys 5.3.0 → 5.3.1

package/.cursor/skills/enhance-orchestrator/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: enhance-orchestrator
+description: "Use when coordinating multiple enhancers for /enhance command. Runs analyzers in parallel and produces unified report."
+version: 5.1.0
+argument-hint: "[path] [--apply] [--focus=TYPE]"
+---
+
+# enhance-orchestrator
+
+Coordinate all enhancement analyzers in parallel and produce a unified report.
+
+## Critical Rules
+
+1. **MUST run enhancers in parallel** - Use Promise.all for efficiency
+2. **MUST only run enhancers for existing content** - Skip if no files found
+3. **MUST report HIGH certainty first** - Priority order: HIGH → MEDIUM → LOW
+4. **NEVER auto-fix without --apply flag** - Explicit consent required
+5. **NEVER auto-fix MEDIUM or LOW issues** - Only HIGH certainty
+
+## Workflow
+
+### Phase 1: Parse Arguments
+
+```javascript
+const args = '$ARGUMENTS'.split(' ').filter(Boolean);
+const targetPath = args.find(a => !a.startsWith('--')) || '.';
+
+const flags = {
+  apply: args.includes('--apply'),
+  focus: args.find(a => a.startsWith('--focus='))?.split('=')[1],
+  verbose: args.includes('--verbose'),
+  showSuppressed: args.includes('--show-suppressed'),
+  resetLearned: args.includes('--reset-learned'),
+  noLearn: args.includes('--no-learn'),
+  exportLearned: args.includes('--export-learned')
+};
+
+// Validate focus type
+const VALID_FOCUS = ['plugin', 'agent', 'claudemd', 'claude-memory', 'docs', 'prompt', 'hooks', 'skills', 'cross-file'];
+if (flags.focus && !VALID_FOCUS.includes(flags.focus)) {
+  console.error(`Invalid --focus: "${flags.focus}". Valid: ${VALID_FOCUS.join(', ')}`);
+  return;
+}
+```
+
+### Phase 2: Discovery
+
+Detect what exists in target path:
+
+```javascript
+const discovery = {
+  plugins: await Glob({ pattern: 'plugins/*/.claude-plugin/plugin.json', path: targetPath }),
+  agents: await Glob({ pattern: '**/agents/*.md', path: targetPath }),
+  claudemd: await Glob({ pattern: '**/CLAUDE.md', path: targetPath }) ||
+            await Glob({ pattern: '**/AGENTS.md', path: targetPath }),
+  docs: await Glob({ pattern: 'docs/**/*.md', path: targetPath }),
+  prompts: await Glob({ pattern: '**/prompts/**/*.md', path: targetPath }) ||
+           await Glob({ pattern: '**/commands/**/*.md', path: targetPath }),
+  hooks: await Glob({ pattern: '**/hooks/**/*.md', path: targetPath }),
+  skills: await Glob({ pattern: '**/skills/**/SKILL.md', path: targetPath }),
+  // Cross-file runs if agents OR skills exist (analyzes relationships)
+  'cross-file': discovery.agents?.length || discovery.skills?.length ? ['enabled'] : []
+};
+```
+
+### Phase 3: Load Suppressions
+
+```javascript
+// Use relative path from skill directory to plugin lib
+// Path: skills/enhance-orchestrator/ -> ../../lib/
+const { getSuppressionPath } = require('../../lib/cross-platform');
+const { loadAutoSuppressions, getProjectId, clearAutoSuppressions } = require('../../lib/enhance/auto-suppression');
+
+const suppressionPath = getSuppressionPath();
+const projectId = getProjectId(targetPath);
+
+if (flags.resetLearned) {
+  clearAutoSuppressions(suppressionPath, projectId);
+  console.log(`Cleared suppressions for project: ${projectId}`);
+}
+
+const autoLearned = loadAutoSuppressions(suppressionPath, projectId);
+```
+
+### Phase 4: Launch Enhancers in Parallel
+
+**CRITICAL**: MUST spawn these EXACT agents using Task(). Do NOT use Explore or other agents.
+
+| Focus Type | Agent to Spawn | Model | JS Analyzer |
+|------------|----------------|-------|-------------|
+| `plugin` | `plugin-enhancer` | sonnet | `lib/enhance/plugin-analyzer.js` |
+| `agent` | `agent-enhancer` | opus | `lib/enhance/agent-analyzer.js` |
+| `claudemd` | `claudemd-enhancer` | opus | `lib/enhance/projectmemory-analyzer.js` |
+| `docs` | `docs-enhancer` | opus | `lib/enhance/docs-analyzer.js` |
+| `prompt` | `prompt-enhancer` | opus | `lib/enhance/prompt-analyzer.js` |
+| `hooks` | `hooks-enhancer` | opus | `lib/enhance/hook-analyzer.js` |
+| `skills` | `skills-enhancer` | opus | `lib/enhance/skill-analyzer.js` |
+| `cross-file` | `cross-file-enhancer` | sonnet | `lib/enhance/cross-file-analyzer.js` |
+
+Each agent has `Bash(node:*)` to run its JS analyzer. Do NOT substitute with Explore agents.
+
+```javascript
+// EXACT agent mapping - do not change
+const ENHANCER_AGENTS = {
+  plugin: 'plugin-enhancer',
+  agent: 'agent-enhancer',
+  claudemd: 'claudemd-enhancer',
+  docs: 'docs-enhancer',
+  prompt: 'prompt-enhancer',
+  hooks: 'hooks-enhancer',
+  skills: 'skills-enhancer',
+  'cross-file': 'cross-file-enhancer'
+};
+
+const promises = [];
+
+for (const [type, agentType] of Object.entries(ENHANCER_AGENTS)) {
+  if (focus && focus !== type) continue;
+  if (!discovery[type]?.length) continue;
+
+  // MUST use exact subagent_type - these agents have Bash(node:*) to run JS analyzers
+  promises.push(Task({
+    subagent_type: agentType,
+    prompt: `Analyze ${type} in ${targetPath}.
+MUST use Skill tool to invoke your enhance-* skill.
+The skill runs the JavaScript analyzer and returns structured findings.
+verbose: ${flags.verbose}
+Return JSON: { "enhancerType": "${type}", "findings": [...], "summary": { high, medium, low } }`
+  }));
+}
+
+// MUST use Promise.all for parallel execution
+const results = await Promise.all(promises);
+```
+
+### Phase 5: Aggregate Results
+
+```javascript
+function aggregateResults(enhancerResults) {
+  const findings = [];
+  const byEnhancer = {};
+
+  for (const result of enhancerResults) {
+    if (!result?.findings) continue;
+    for (const finding of result.findings) {
+      findings.push({ ...finding, source: result.enhancerType });
+    }
+    byEnhancer[result.enhancerType] = result.summary;
+  }
+
+  return {
+    findings,
+    byEnhancer,
+    totals: {
+      high: findings.filter(f => f.certainty === 'HIGH').length,
+      medium: findings.filter(f => f.certainty === 'MEDIUM').length,
+      low: findings.filter(f => f.certainty === 'LOW').length
+    }
+  };
+}
+```
+
+### Phase 6: Generate Report
+
+Generate report directly from aggregated findings:
+
+```javascript
+const { generateReport } = require('../../lib/enhance/reporter');
+
+const report = generateReport(aggregated, {
+  verbose: flags.verbose,
+  showAutoFixable: flags.apply
+});
+
+console.log(report);
+```
+
+### Phase 7: Auto-Learning
+
+```javascript
+if (!flags.noLearn) {
+  const { analyzeForAutoSuppression, saveAutoSuppressions } = require('../../lib/enhance/auto-suppression');
+
+  const newSuppressions = analyzeForAutoSuppression(aggregated.findings, fileContents, { projectRoot: targetPath });
+
+  if (newSuppressions.length > 0) {
+    saveAutoSuppressions(suppressionPath, projectId, newSuppressions);
+    console.log(`\nLearned ${newSuppressions.length} new suppressions.`);
+  }
+}
+```
+
+### Phase 8: Apply Fixes
+
+```javascript
+if (flags.apply) {
+  const autoFixable = aggregated.findings.filter(f => f.certainty === 'HIGH' && f.autoFixable);
+
+  if (autoFixable.length > 0) {
+    console.log(`\n## Applying ${autoFixable.length} Auto-Fixes\n`);
+
+    const byEnhancer = {};
+    for (const fix of autoFixable) {
+      const type = fix.source;
+      if (!byEnhancer[type]) byEnhancer[type] = [];
+      byEnhancer[type].push(fix);
+    }
+
+    for (const [type, fixes] of Object.entries(byEnhancer)) {
+      await Task({
+        subagent_type: enhancerAgents[type],
+        prompt: `Apply HIGH certainty fixes: ${JSON.stringify(fixes, null, 2)}`
+      });
+    }
+
+    console.log(`Applied ${autoFixable.length} fixes.`);
+  }
+}
+```
+
+## Output Format
+
+```markdown
+# Enhancement Analysis Report
+
+**Target**: {targetPath}
+**Date**: {timestamp}
+**Enhancers Run**: {list}
+
+## Executive Summary
+
+| Enhancer | HIGH | MEDIUM | LOW | Auto-Fixable |
+|----------|------|--------|-----|--------------|
+| plugin   | 2    | 3      | 1   | 1            |
+| agent    | 1    | 2      | 0   | 1            |
+| **Total**| **3**| **5**  | **1**| **2**       |
+
+## HIGH Certainty Issues
+[Grouped by enhancer, then file]
+
+## MEDIUM Certainty Issues
+[...]
+
+## Auto-Fix Summary
+{n} issues can be fixed with `--apply` flag.
+```
+
+## Constraints
+
+- MUST run enhancers in parallel (Promise.all)
+- MUST skip enhancers for missing content types
+- MUST report HIGH certainty issues first
+- MUST deduplicate findings across enhancers
+- NEVER auto-fix without explicit --apply flag
+- NEVER auto-fix MEDIUM or LOW certainty issues

package/.cursor/skills/enhance-plugins/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: enhance-plugins
+description: "Use when analyzing plugin structures, MCP tools, and plugin security patterns."
+version: 5.1.0
+argument-hint: "[path] [--fix]"
+---
+
+# enhance-plugins
+
+Analyze plugin structures, MCP tools, and security patterns against best practices.
+
+## Parse Arguments
+
+```javascript
+const args = '$ARGUMENTS'.split(' ').filter(Boolean);
+const targetPath = args.find(a => !a.startsWith('--')) || '.';
+const fix = args.includes('--fix');
+```
+
+## Plugin Locations
+
+| Platform | Location |
+|----------|----------|
+| Claude Code | `plugins/*/`, `.claude-plugin/plugin.json` |
+| OpenCode | `.opencode/plugins/`, MCP in `opencode.json` |
+| Codex | MCP in `~/.codex/config.toml` |
+
+## Workflow
+
+1. **Discover** - Find plugins in `plugins/` directory
+2. **Load** - Read `plugin.json`, agents, commands, skills
+3. **Analyze** - Run pattern checks by certainty level
+4. **Report** - Generate markdown output
+5. **Fix** - Apply auto-fixes if `--fix` (HIGH certainty only)
+
+## Detection Patterns
+
+### 1. Tool Schema Design (HIGH)
+
+Based on function calling best practices:
+
+**Required elements:**
+```json
+{
+  "name": "verb_noun",
+  "description": "What it does. When to use. What it returns.",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "param": {
+        "type": "string",
+        "description": "Format and example"
+      }
+    },
+    "required": ["param"],
+    "additionalProperties": false
+  }
+}
+```
+
+**The "Intern Test"** - Can someone use this tool given only the description?
+
+| Issue | Certainty | Auto-Fix |
+|-------|-----------|----------|
+| Missing `additionalProperties: false` | HIGH | Yes |
+| Missing `required` array | HIGH | Yes |
+| Missing tool description | HIGH | No |
+| Missing param descriptions | MEDIUM | No |
+| Vague names (`search`, `process`) | MEDIUM | No |
+
+### 2. Description Quality (HIGH)
+
+**Tool descriptions must include:**
+- What the function does
+- When to use it (trigger context)
+- What it returns
+
+```json
+// Bad - vague
+"description": "Search for things"
+
+// Good - complete
+"description": "Search product catalog by keyword. Use for inventory queries or price checks. Returns matching products with prices."
+```
+
+**Parameter descriptions must include:**
+- Format expectations
+- Example values
+- Relationships to other params
+
+```json
+// Bad
+"query": { "type": "string" }
+
+// Good
+"query": {
+  "type": "string",
+  "description": "Search keywords. Supports AND/OR. Example: 'laptop AND gaming'"
+}
+```
+
+### 3. Schema Structure (MEDIUM)
+
+| Issue | Why It Matters |
+|-------|----------------|
+| Deep nesting (>2 levels) | Reduces generation quality |
+| Missing enums for constrained values | Allows invalid states |
+| No min/max on numbers | Unbounded inputs |
+| >20 tools per plugin | Increases error rates |
+
+**Prefer flat structures:**
+```json
+// Bad - nested
+{ "config": { "settings": { "timeout": 30 } } }
+
+// Good - flat
+{ "timeout_seconds": 30 }
+```
+
+### 4. Plugin Structure (HIGH)
+
+**Required files:**
+```
+plugin-name/
+├── .claude-plugin/
+│   └── plugin.json      # name, version, description
+├── commands/            # User-invokable commands
+├── agents/              # Subagent definitions
+├── skills/              # Reusable skill implementations
+└── package.json         # Optional, for npm plugins
+```
+
+**plugin.json validation:**
+- `name`: lowercase, kebab-case
+- `version`: semver format (`^\d+\.\d+\.\d+$`)
+- `description`: explains what plugin provides
+
+**Version sync:** plugin.json version must match package.json if present.
+
+### 5. MCP Server Patterns (MEDIUM)
+
+For plugins exposing MCP tools:
+
+**Transport types:**
+- `stdio` - Standard I/O (most common)
+- `http` - HTTP/SSE transport
+
+**Configuration:**
+```json
+{
+  "mcp": {
+    "server-name": {
+      "type": "local",
+      "command": ["node", "path/to/server.js"],
+      "environment": { "KEY": "value" },
+      "enabled": true
+    }
+  }
+}
+```
+
+**Security principles:**
+- User consent for data access
+- No transmission without approval
+- Tool descriptions are untrusted input
+
+### 6. Security Patterns (HIGH)
+
+**HIGH Certainty issues:**
+| Pattern | Risk | Detection |
+|---------|------|-----------|
+| Unrestricted `Bash` | Command execution | `tools:.*Bash[^(]` |
+| Command injection | Shell escape | `\${.*}` in commands |
+| Path traversal | File access | `\.\.\/` in paths |
+| Hardcoded secrets | Credential leak | API keys, passwords |
+
+**MEDIUM Certainty issues:**
+| Pattern | Risk |
+|---------|------|
+| Broad file access | Data exfiltration |
+| Missing input validation | Injection attacks |
+| No timeout on tools | Resource exhaustion |
+
+**Input validation required:**
+```javascript
+// Validate before execution
+function validateToolInput(params, schema) {
+  // Type validation
+  // Range validation (min/max)
+  // Enum validation
+  // Format validation (regex patterns)
+}
+```
+
+### 7. Error Handling (MEDIUM)
+
+Tools should return structured errors:
+```json
+{
+  "type": "tool_result",
+  "tool_use_id": "id",
+  "content": "Error: [TYPE]. [WHAT]. [SUGGESTION].",
+  "is_error": true
+}
+```
+
+**Retry guidance:**
+- Transient (429, 503): exponential backoff
+- Validation (400): no retry, return error
+- Timeout: configurable, default 30s
+
+### 8. Tool Count (LOW)
+
+**"Less-is-More" approach:**
+- Research shows reducing tools improves accuracy by up to 89%
+- Limit to 3-5 relevant tools per task context
+- Consider dynamic tool loading for large toolsets
+
+## Auto-Fixes
+
+| Issue | Fix |
+|-------|-----|
+| Missing `additionalProperties` | Add `"additionalProperties": false` |
+| Missing `required` | Add all properties to required array |
+| Version mismatch | Sync plugin.json with package.json |
+
+## Output Format
+
+```markdown
+## Plugin Analysis: {name}
+
+**Files scanned**: {count}
+
+| Certainty | Count |
+|-----------|-------|
+| HIGH | {n} |
+| MEDIUM | {n} |
+
+### Tool Schema Issues
+| Tool | Issue | Fix | Certainty |
+
+### Structure Issues
+| File | Issue | Certainty |
+
+### Security Issues
+| File | Line | Issue | Certainty |
+```
+
+## Pattern Statistics
+
+| Category | Patterns | Certainty |
+|----------|----------|-----------|
+| Tool Schema | 5 | HIGH |
+| Descriptions | 2 | HIGH |
+| Schema Structure | 4 | MEDIUM |
+| Plugin Structure | 3 | HIGH |
+| MCP Patterns | 2 | MEDIUM |
+| Security | 6 | HIGH/MEDIUM |
+| Error Handling | 2 | MEDIUM |
+| Tool Count | 1 | LOW |
+| **Total** | **25** | - |
+
+<examples>
+### Schema Strictness
+<bad_example>
+```json
+{
+  "properties": { "path": { "type": "string" } }
+}
+```
+</bad_example>
+<good_example>
+```json
+{
+  "properties": { "path": { "type": "string", "description": "File path" } },
+  "required": ["path"],
+  "additionalProperties": false
+}
+```
+</good_example>
+
+### Tool Description
+<bad_example>
+```json
+"description": "Search for things"
+```
+</bad_example>
+<good_example>
+```json
+"description": "Search product catalog by keyword. Use for inventory or price queries. Returns products with prices."
+```
+</good_example>
+
+### Security
+<bad_example>
+```yaml
+tools: Read, Bash  # Unrestricted
+```
+</bad_example>
+<good_example>
+```yaml
+tools: Read, Bash(git:*)  # Scoped
+```
+</good_example>
+</examples>
+
+## References
+
+- `agent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md` - Tool schema, descriptions, security
+- `agent-docs/CLAUDE-CODE-REFERENCE.md` - Plugin structure, MCP config
+- `agent-docs/OPENCODE-REFERENCE.md` - OpenCode MCP integration
+- `agent-docs/CODEX-REFERENCE.md` - Codex MCP config
+
+## Constraints
+
+- Auto-fix only HIGH certainty issues
+- Security warnings are advisory - do not auto-fix
+- Preserve existing plugin.json fields
+- Never modify tool behavior, only schema definitions