agentsys 5.1.0 → 5.2.0

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

@@ -1,313 +0,0 @@
----
-name: enhance-plugins
-description: "Use when analyzing plugin structures, MCP tools, and plugin security patterns."
-version: 5.1.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

@@ -1,340 +0,0 @@
----
-name: enhance-prompts
-description: "Use when improving general prompts for structure, examples, and constraints."
-version: 5.1.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