agentsys 5.0.0

package/adapters/opencode/skills/enhance-plugins/SKILL.md

@@ -0,0 +1,314 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: enhance-plugins
+description: "Use when analyzing plugin structures, MCP tools, and plugin security patterns."
+version: 5.0.0
+argument-hint: "[path] [--fix]"
+---
+
+> **OpenCode Note**: Invoke agents using `@agent-name` syntax.
+> Available agents: task-discoverer, exploration-agent, planning-agent,
+> implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent
+> Example: `@exploration-agent analyze the codebase`
+
+
+# enhance-plugins
+
+Analyze plugin structures, MCP tools, and security patterns against best practices.
+
+## Parse Arguments
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## 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 reference - not executable in OpenCode)*
+
+### 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

package/adapters/opencode/skills/enhance-prompts/SKILL.md

@@ -0,0 +1,341 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: enhance-prompts
+description: "Use when improving general prompts for structure, examples, and constraints."
+version: 5.0.0
+argument-hint: "[path] [--fix]"
+---
+
+> **OpenCode Note**: Invoke agents using `@agent-name` syntax.
+> Available agents: task-discoverer, exploration-agent, planning-agent,
+> implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent
+> Example: `@exploration-agent analyze the codebase`
+
+
+# enhance-prompts
+
+Analyze prompts for clarity, structure, examples, and output reliability.
+
+## Parse Arguments
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Differentiation from enhance-agent-prompts
+
+| Skill | Focus | Use When |
+|-------|-------|----------|
+| `enhance-prompts` | Prompt quality (clarity, structure, examples) | General prompts, system prompts, templates |
+| `enhance-agent-prompts` | Agent config (frontmatter, tools, model) | Agent files with YAML frontmatter |
+
+## Workflow
+
+1. **Run Analyzer** - Execute the JavaScript analyzer to get findings:
+   *(Bash command with Node.js require - adapt for OpenCode)*
+   For a specific path: `a.analyzeAllPrompts('./plugins/enhance')`
+   For a single file: `a.analyzePrompt('./path/to/file.md')`
+
+2. **Parse Results** - The analyzer returns JSON with `summary` and `findings`
+3. **Filter** - Apply certainty filtering based on --verbose flag
+4. **Report** - Format findings as markdown output
+5. **Fix** - If --fix flag, apply auto-fixes from findings
+
+The JavaScript analyzer (`lib/enhance/prompt-analyzer.js`) implements all detection patterns including AST-based code validation. The patterns below are reference documentation.
+
+---
+
+## Prompt Engineering Knowledge Reference
+
+### System Prompt Structure
+
+Effective system prompts include: Role/Identity, Capabilities & Constraints, Instruction Priority, Output Format, Behavioral Directives, Examples, Error Handling.
+
+**Minimal Template:**
+```xml
+<system>
+You are [ROLE]. [PURPOSE].
+Key constraints: [CONSTRAINTS]
+Output format: [FORMAT]
+When uncertain: [HANDLING]
+</system>
+```
+
+### XML Tags (Claude-Specific)
+
+Claude is fine-tuned for XML tags. Use: `<role>`, `<constraints>`, `<output_format>`, `<examples>`, `<instructions>`, `<context>`
+
+```xml
+<constraints>
+- Maximum response length: 500 words
+- Use only Python 3.10+ syntax
+</constraints>
+```
+
+### Few-Shot Examples
+
+- 2-5 examples is optimal (research-backed)
+- Include edge cases and ensure format consistency
+- Start zero-shot, add examples only if needed
+- Show both good AND bad examples when relevant
+
+### Chain-of-Thought (CoT)
+
+| Use CoT | Don't Use CoT |
+|---------|---------------|
+| Complex multi-step reasoning | Simple factual questions |
+| Math and logic problems | Classification tasks |
+| Code debugging | When model has built-in reasoning |
+
+**Key:** Modern models (Claude 4.x, o1/o3) perform CoT internally. "Think step by step" is redundant.
+
+### Role Prompting
+
+**Helps:** Creative tasks, tone/style, roleplay
+**Doesn't help:** Accuracy tasks, factual retrieval, complex reasoning
+
+Better: "Approach systematically, showing work" vs "You are an expert"
+
+### Instruction Hierarchy
+
+Priority: System > Developer > User > Retrieved Content
+
+Include explicit priority in prompts with multiple constraint sources.
+
+### Negative Prompting
+
+Positive alternatives are more effective than negatives:
+
+| Less Effective | More Effective |
+|----------------|----------------|
+| "Don't use markdown" | "Use prose paragraphs" |
+| "Don't be vague" | "Use specific language" |
+
+### Structured Output
+
+- Prompt-based: ~35.9% reliability
+- Schema enforcement: 100% reliability
+- Always provide schema example and validate output
+
+### Context Window Optimization
+
+**Lost-in-the-Middle:** Models weigh beginning and end more heavily.
+
+Place critical constraints at start, examples in middle, error handling at end.
+
+### Extended Thinking
+
+High-level instructions ("Think deeply") outperform step-by-step guidance. "Think step-by-step" is redundant with modern models.
+
+### Anti-Patterns Quick Reference
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| Vague references | "The above code" loses context | Quote specifically |
+| Negative-only | "Don't do X" without alternative | State what TO do |
+| Aggressive emphasis | "CRITICAL: MUST" | Use normal language |
+| Redundant CoT | Wastes tokens | Let model manage |
+| Critical info buried | Lost-in-the-middle | Place at start/end |
+
+---
+
+## Detection Patterns
+
+### 1. Clarity Issues (HIGH Certainty)
+
+**Vague Instructions:** "usually", "sometimes", "try to", "if possible", "might", "could"
+
+**Negative-Only Constraints:** "don't", "never", "avoid" without stating what TO do
+
+**Aggressive Emphasis:** Excessive CAPS (CRITICAL, IMPORTANT), multiple !!
+
+### 2. Structure Issues (HIGH/MEDIUM Certainty)
+
+**Missing XML Structure:** Complex prompts (>800 tokens) without XML tags
+
+**Inconsistent Sections:** Mixed heading styles, skipped levels (H1→H3)
+
+**Critical Info Buried:** Important instructions in middle 40%, constraints after examples
+
+### 3. Example Issues (HIGH/MEDIUM Certainty)
+
+**Missing Examples:** Complex tasks without few-shot, format requests without example
+
+**Suboptimal Count:** Only 1 example (optimal: 2-5), more than 7 (bloat)
+
+**Missing Contrast:** No good/bad labeling, no edge cases
+
+### 4. Context Issues (MEDIUM Certainty)
+
+**Missing WHY:** Rules without explanation
+
+**Missing Priority:** Multiple constraint sections without conflict resolution
+
+### 5. Output Format Issues (HIGH/MEDIUM Certainty)
+
+**Missing Format:** Substantial prompts without format specification
+
+**JSON Without Schema:** Requests JSON but no example structure
+
+### 6. Anti-Patterns (HIGH/MEDIUM/LOW Certainty)
+
+**Redundant CoT (HIGH):** "Think step by step" with modern models
+
+**Overly Prescriptive (MEDIUM):** 10+ numbered steps, micro-managing reasoning
+
+**Prompt Bloat (LOW):** Over 2500 tokens, redundant instructions
+
+**Vague References (HIGH):** "The above code", "as mentioned"
+
+---
+
+## Auto-Fix Implementations
+
+### 1. Aggressive Emphasis
+Replace CRITICAL→critical, !!→!, remove excessive caps
+
+### 2. Negative-Only to Positive
+Suggest positive alternatives for "don't" statements
+
+---
+
+## Output Format
+
+```markdown
+## Prompt Analysis: {prompt-name}
+
+**File**: {path}
+**Type**: {system|agent|skill|template}
+**Token Count**: ~{tokens}
+
+### Summary
+- HIGH: {count} issues
+- MEDIUM: {count} issues
+
+### Clarity Issues ({n})
+| Issue | Location | Fix | Certainty |
+
+### Structure Issues ({n})
+| Issue | Location | Fix | Certainty |
+
+### Example Issues ({n})
+| Issue | Location | Fix | Certainty |
+```
+
+---
+
+## Pattern Statistics
+
+| Category | Patterns | Auto-Fixable |
+|----------|----------|--------------|
+| Clarity | 4 | 1 |
+| Structure | 4 | 0 |
+| Examples | 4 | 0 |
+| Context | 2 | 0 |
+| Output Format | 3 | 0 |
+| Anti-Pattern | 4 | 0 |
+| **Total** | **21** | **1** |
+
+---
+
+<examples>
+### Example: Vague Instructions
+
+<bad_example>
+```markdown
+You should usually follow best practices when possible.
+```
+**Why it's bad**: Vague qualifiers reduce determinism.
+</bad_example>
+
+<good_example>
+```markdown
+Follow these practices:
+1. Validate input before processing
+2. Handle null/undefined explicitly
+```
+**Why it's good**: Specific, actionable instructions.
+</good_example>
+
+### Example: Negative-Only Constraints
+
+<bad_example>
+```markdown
+- Don't use vague language
+- Never skip validation
+```
+**Why it's bad**: Only states what NOT to do.
+</bad_example>
+
+<good_example>
+```markdown
+- Use specific, deterministic language
+- Always validate input; return structured errors
+```
+**Why it's good**: Each constraint includes positive action.
+</good_example>
+
+### Example: Redundant Chain-of-Thought
+
+<bad_example>
+```markdown
+Think through this step by step:
+1. First, analyze the input
+2. Then, identify the key elements
+```
+**Why it's bad**: Modern models do this internally. Wastes tokens.
+</bad_example>
+
+<good_example>
+```markdown
+Analyze the input carefully before responding.
+```
+**Why it's good**: High-level guidance without micro-managing.
+</good_example>
+
+### Example: Missing Output Format
+
+<bad_example>
+```markdown
+Respond with a JSON object containing the analysis results.
+```
+**Why it's bad**: No schema or example.
+</bad_example>
+
+<good_example>
+```markdown
+## Output Format
+{"status": "success|error", "findings": [{"severity": "HIGH"}]}
+```
+**Why it's good**: Concrete schema shows exact structure.
+</good_example>
+
+### Example: Critical Info Buried
+
+<bad_example>
+```markdown
+# Task
+[task]
+## Background
+[500 words...]
+## Important Constraints  <- buried at end
+```
+**Why it's bad**: Lost-in-the-middle effect.
+</bad_example>
+
+<good_example>
+```markdown
+# Task
+## Critical Constraints  <- at start
+[constraints]
+## Background
+```
+**Why it's good**: Critical info at start where attention is highest.
+</good_example>
+</examples>
+
+---
+
+## Constraints
+
+- Only apply auto-fixes for HIGH certainty issues
+- Preserve original structure and formatting
+- Validate against embedded knowledge reference above