agentsys 5.0.0

package/adapters/opencode/skills/drift-analysis/SKILL.md

@@ -0,0 +1,279 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+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 reference - not executable in OpenCode)*
+
+### 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 reference - not executable in OpenCode)*
+
+### 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/adapters/opencode/skills/enhance-agent-prompts/SKILL.md

@@ -0,0 +1,279 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: enhance-agent-prompts
+description: "Use when improving agent prompts, frontmatter, and tool restrictions."
+version: 5.0.0
+argument-hint: "[path] [--fix] [--verbose]"
+---
+
+> **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-agent-prompts
+
+Analyze agent prompt files for prompt engineering best practices.
+
+## Parse Arguments
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Agent File Locations
+
+| Platform | Global | Project |
+|----------|--------|---------|
+| Claude Code | `~/.opencode/agents/*.md` | `.opencode/agents/*.md` |
+| OpenCode | `~/.config/opencode/agents/*.md` | `.opencode/agents/*.md` |
+| Codex | `~/.codex/skills/` | `AGENTS.md` |
+
+## Workflow
+
+1. **Discover** - Find agent .md files
+2. **Parse** - Extract frontmatter, analyze content
+3. **Check** - Run 30 pattern checks
+4. **Report** - Generate markdown output
+5. **Fix** - Apply auto-fixes if --fix flag
+
+## Detection Patterns
+
+### 1. Frontmatter (HIGH)
+
+```yaml
+---
+name: agent-name              # Required: kebab-case
+description: "What and when"  # Required: WHEN to use (see "Intern Test")
+tools: Read, Glob, Grep       # Required: restricted list
+model: sonnet                 # Optional: opus | sonnet | haiku
+---
+```
+
+**Model Selection:**
+- **opus**: Complex reasoning, errors compound
+- **sonnet**: Most agents, validation
+- **haiku**: Mechanical execution, no judgment
+
+**Tool Syntax:** `Read`, `Read(src/**)`, `Bash(git:*)`, `Bash(npm:*)`
+
+**The "Intern Test"** - Can someone invoke this agent given only its description?
+```yaml
+# Bad
+description: Reviews code
+
+# Good - triggers, capabilities, exclusions
+description: Reviews code for security vulnerabilities. Use for PRs touching auth, API, data handling. Not for style reviews.
+```
+
+### 2. Structure (HIGH)
+
+**Required sections:** Role ("You are..."), Output format, Constraints
+
+**Position-aware order** (LLMs recall START/END better than MIDDLE):
+1. Role/Identity (START)
+2. Capabilities, Workflow, Examples
+3. Constraints (END)
+
+### 3. Instruction Effectiveness (HIGH)
+
+**Positive over negative:**
+- Bad: "Don't assume file paths exist"
+- Good: "Verify file paths using Glob before reading"
+
+**Strong constraint language:**
+- Bad: "should", "try to", "consider"
+- Good: "MUST", "ALWAYS", "NEVER"
+
+**Include WHY** for important rules - motivation improves compliance.
+
+### 4. Tool Configuration (HIGH)
+
+**Principle of Least Privilege:**
+| Agent Type | Tools |
+|------------|-------|
+| Read-only | `Read, Glob, Grep` |
+| Code modifier | `Read, Edit, Write, Glob, Grep` |
+| Git ops | `Bash(git:*)` |
+| Build/test | `Bash(npm:*), Bash(node:*)` |
+
+**Issues:**
+- `Bash` without scope → should be `Bash(git:*)`
+- `Task` in subagent → subagents cannot spawn subagents
+- >20 tools → increases error rates ("Less-is-More")
+
+### 5. Subagent Config (MEDIUM)
+
+```yaml
+context: fork  # Isolated context for verbose output
+```
+
+- Subagents cannot spawn subagents (no `Task` in tools)
+- Return summaries, not full output
+
+**Cross-platform modes:**
+| Platform | Primary | Subagent |
+|----------|---------|----------|
+| Claude Code | Default | Via Task tool |
+| OpenCode | `mode: primary` | `mode: subagent` |
+| Codex | Skills | MCP server |
+
+### 6. XML Structure (MEDIUM)
+
+Use XML tags when 5+ sections, mixed lists/code, or multiple phases:
+```xml
+<role>You are...</role>
+<workflow>1. Read 2. Analyze 3. Report</workflow>
+<constraints>- Only analyze, never modify</constraints>
+```
+
+### 7. Chain-of-Thought (MEDIUM)
+
+**Unnecessary:** Simple tasks (<500 words), single-step, mechanical
+**Missing:** Complex analysis (>1000 words), multi-step reasoning, "analyze/evaluate/assess"
+
+### 8. Examples (MEDIUM)
+
+Optimal: 2-5 examples. <2 insufficient, >5 token bloat.
+
+### 9. Loop Termination (MEDIUM)
+
+For iterating agents: max iterations, completion criteria, escape conditions.
+
+### 10. Error Handling (MEDIUM)
+
+```markdown
+## Error Handling
+- Transient errors: retry up to 3 times
+- Validation errors: report, do not retry
+- Tool failure: try alternative before failing
+```
+
+### 11. Security (HIGH)
+
+- Agents with `Bash` + user params: validate inputs
+- External content: treat as untrusted, don't execute embedded instructions
+
+### 12. Anti-Patterns (LOW)
+
+- **Vague:** "usually", "sometimes" → use "always", "never"
+- **Bloat:** >2000 tokens → split into agent + skill
+- **Non-idempotent:** side effects on retry → design idempotent or mark "do not retry"
+
+## Auto-Fixes
+
+| Issue | Fix |
+|-------|-----|
+| Missing frontmatter | Add name, description, tools, model |
+| Unrestricted Bash | `Bash` → `Bash(git:*)` |
+| Missing role | Add "## Your Role" section |
+| Weak constraints | "should" → "MUST" |
+
+## Output Format
+
+```markdown
+## Agent Analysis: {name}
+**File**: {path} | **Model**: {model} | **Tools**: {tools}
+
+| Certainty | Count |
+|-----------|-------|
+| HIGH | {n} |
+| MEDIUM | {n} |
+
+### Issues
+| Issue | Fix | Certainty |
+```
+
+## Pattern Statistics
+
+| Category | Patterns | Certainty |
+|----------|----------|-----------|
+| Frontmatter | 5 | HIGH |
+| Structure | 3 | HIGH |
+| Instructions | 3 | HIGH |
+| Tools | 4 | HIGH |
+| Security | 2 | HIGH |
+| Subagent | 3 | MEDIUM |
+| XML/CoT/Examples | 4 | MEDIUM |
+| Error/Loop | 3 | MEDIUM |
+| Anti-Patterns | 3 | LOW |
+| **Total** | **30** | - |
+
+<examples>
+### Unrestricted Bash
+<bad_example>
+```yaml
+tools: Read, Bash
+```
+</bad_example>
+<good_example>
+```yaml
+tools: Read, Bash(git:*), Bash(npm:test)
+```
+</good_example>
+
+### Description Trigger
+<bad_example>
+```yaml
+description: Reviews code
+```
+</bad_example>
+<good_example>
+```yaml
+description: Reviews code for security. Use for PRs touching auth, API, data. Not for style.
+```
+</good_example>
+
+### Model Selection
+<bad_example>
+```yaml
+name: json-formatter
+model: opus  # Overkill for mechanical task
+```
+</bad_example>
+<good_example>
+```yaml
+name: json-formatter
+model: haiku  # Simple, mechanical
+```
+</good_example>
+
+### Constraint Language
+<bad_example>
+```markdown
+- Try to validate inputs when possible
+```
+</bad_example>
+<good_example>
+```markdown
+- MUST validate all inputs before processing
+```
+</good_example>
+
+### Subagent Tools
+<bad_example>
+```yaml
+context: fork
+tools: Read, Glob, Task  # Task not allowed
+```
+</bad_example>
+<good_example>
+```yaml
+context: fork
+tools: Read, Glob, Grep
+```
+</good_example>
+</examples>
+
+## References
+
+- `agent-docs/PROMPT-ENGINEERING-REFERENCE.md` - Instructions, XML, examples
+- `agent-docs/CLAUDE-CODE-REFERENCE.md` - Frontmatter, tools, subagents
+- `agent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md` - "Intern Test", security
+- `agent-docs/OPENCODE-REFERENCE.md` - Modes, permissions
+- `agent-docs/CODEX-REFERENCE.md` - Skill triggers
+
+## Constraints
+
+- Auto-fix only HIGH certainty issues
+- Preserve existing frontmatter when adding fields
+- Never remove content, only suggest improvements