agentsys 5.0.0

package/adapters/opencode/skills/learn/SKILL.md

@@ -0,0 +1,352 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: learn
+description: "Research any topic online and create learning guides. Use when user asks to 'learn about', 'research topic', 'create learning guide', 'build knowledge base', or 'study subject'."
+version: 5.0.0
+argument-hint: "[topic] [--depth=brief|medium|deep]"
+---
+
+> **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`
+
+
+# learn
+
+Research any topic by gathering online resources and creating a comprehensive learning guide with RAG-optimized indexes.
+
+## Parse Arguments
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Input
+
+Arguments: `<topic> [--depth=brief|medium|deep]`
+
+- **topic**: Subject to research (required)
+- **--depth**: Source gathering depth
+  - `brief`: 10 sources (quick overview)
+  - `medium`: 20 sources (default, balanced)
+  - `deep`: 40 sources (comprehensive)
+
+## Research Methodology
+
+Based on best practices from:
+- Anthropic's Context Engineering
+- DeepLearning.AI Tool Use Patterns
+- Anara's AI Literature Reviews
+
+### 1. Progressive Query Architecture
+
+Use funnel approach to avoid noise from long query lists:
+
+**Broad Phase** (landscape mapping):
+```
+"{topic} overview introduction"
+"{topic} documentation official"
+```
+
+**Focused Phase** (core content):
+```
+"{topic} best practices"
+"{topic} examples tutorial"
+"{topic} site:stackoverflow.com"
+```
+
+**Deep Phase** (advanced, if depth=deep):
+```
+"{topic} advanced techniques"
+"{topic} pitfalls mistakes avoid"
+"{topic} 2025 2026 latest"
+```
+
+### 2. Source Quality Scoring
+
+Multi-dimensional evaluation (max score: 100):
+
+| Factor | Weight | Max | Criteria |
+|--------|--------|-----|----------|
+| Authority | 3x | 30 | Official docs (10), recognized expert (8), established site (6), blog (4), random (2) |
+| Recency | 2x | 20 | <6mo (10), <1yr (8), <2yr (6), <3yr (4), older (2) |
+| Depth | 2x | 20 | Comprehensive (10), detailed (8), overview (6), superficial (4), fragment (2) |
+| Examples | 2x | 20 | Multiple code examples (10), one example (6), no examples (2) |
+| Uniqueness | 1x | 10 | Unique perspective (10), some overlap (6), duplicate content (2) |
+
+**Selection threshold**: Top N sources by score (N = depth target)
+
+### 3. Just-In-Time Retrieval
+
+Don't pre-load all content (causes context rot):
+
+1. **Collect URLs first** via WebSearch
+2. **Score based on metadata** (title, description, URL)
+3. **Fetch only selected sources** via WebFetch
+4. **Extract summaries** (not full content)
+
+### 4. Content Extraction Guidelines
+
+For each source, extract:
+
+```json
+{
+  "url": "https://...",
+  "title": "Article Title",
+  "qualityScore": 85,
+  "scores": {
+    "authority": 9,
+    "recency": 8,
+    "depth": 7,
+    "examples": 9,
+    "uniqueness": 6
+  },
+  "keyInsights": [
+    "Concise insight 1",
+    "Concise insight 2"
+  ],
+  "codeExamples": [
+    {
+      "language": "javascript",
+      "description": "Basic usage pattern"
+    }
+  ],
+  "extractedAt": "2026-02-05T12:00:00Z"
+}
+```
+
+**Copyright compliance**: Summaries and insights only, never verbatim paragraphs.
+
+## Output Structure
+
+### Topic Guide Template
+
+Create `agent-knowledge/{slug}.md`:
+
+```markdown
+# Learning Guide: {Topic}
+
+**Generated**: {date}
+**Sources**: {count} resources analyzed
+**Depth**: {brief|medium|deep}
+
+## Prerequisites
+
+What you should know before diving in:
+- Prerequisite 1
+- Prerequisite 2
+
+## TL;DR
+
+Essential points in 3-5 bullets:
+- Key point 1
+- Key point 2
+- Key point 3
+
+## Core Concepts
+
+### {Concept 1}
+
+{Synthesized explanation from multiple sources}
+
+**Key insight**: {Most important takeaway}
+
+### {Concept 2}
+
+{Synthesized explanation}
+
+## Code Examples
+
+### Basic Example
+
+```{language}
+// Description of what this demonstrates
+{code}
+```
+
+### Advanced Pattern
+
+```{language}
+{code}
+```
+
+## Common Pitfalls
+
+| Pitfall | Why It Happens | How to Avoid |
+|---------|---------------|--------------|
+| Issue 1 | Root cause | Prevention strategy |
+
+## Best Practices
+
+Synthesized from {n} sources:
+
+1. **Practice 1**: Explanation
+2. **Practice 2**: Explanation
+
+## Further Reading
+
+| Resource | Type | Why Recommended |
+|----------|------|-----------------|
+| [Title]({url}) | Official Docs | Authoritative reference |
+| [Title]({url}) | Tutorial | Step-by-step guide |
+
+---
+
+*Generated by /learn from {count} sources.*
+*See `resources/{slug}-sources.json` for full source metadata.*
+```
+
+### Master Index Template
+
+Create/update `agent-knowledge/CLAUDE.md`:
+
+```markdown
+# Agent Knowledge Base
+
+> Learning guides created by /learn. Reference these when answering questions about listed topics.
+
+## Available Topics
+
+| Topic | File | Sources | Depth | Created |
+|-------|------|---------|-------|---------|
+| {Topic 1} | {slug1}.md | {n} | medium | 2026-02-05 |
+| {Topic 2} | {slug2}.md | {n} | deep | 2026-02-04 |
+
+## Trigger Phrases
+
+Use this knowledge when user asks about:
+- "How does {topic1} work?" → {slug1}.md
+- "Explain {topic1}" → {slug1}.md
+- "{Topic2} best practices" → {slug2}.md
+
+## Quick Lookup
+
+| Keyword | Guide |
+|---------|-------|
+| recursion | recursion.md |
+| hooks, react | react-hooks.md |
+
+## How to Use
+
+1. Check if user question matches a topic
+2. Read the relevant guide file
+3. Answer based on synthesized knowledge
+4. Cite the guide if user asks for sources
+```
+
+Copy to `agent-knowledge/AGENTS.md` for OpenCode/Codex.
+
+### Sources Metadata
+
+Create `agent-knowledge/resources/{slug}-sources.json`:
+
+```json
+{
+  "topic": "{original topic}",
+  "slug": "{slug}",
+  "generated": "2026-02-05T12:00:00Z",
+  "depth": "medium",
+  "totalSources": 20,
+  "sources": [
+    {
+      "url": "https://...",
+      "title": "...",
+      "qualityScore": 85,
+      "scores": {
+        "authority": 9,
+        "recency": 8,
+        "depth": 7,
+        "examples": 9,
+        "uniqueness": 6
+      },
+      "keyInsights": ["..."]
+    }
+  ]
+}
+```
+
+## Self-Evaluation Checklist
+
+Before finalizing, rate output (1-10):
+
+| Metric | Question | Target |
+|--------|----------|--------|
+| Coverage | Does guide cover main aspects? | ≥7 |
+| Diversity | Are sources from diverse types? | ≥6 |
+| Examples | Are code examples practical? | ≥7 |
+| Accuracy | Confidence in content accuracy? | ≥8 |
+
+**Flag gaps**: Note any important subtopics not covered.
+
+## Enhancement Integration
+
+If enhance=true, invoke after guide creation:
+
+```javascript
+// Enhance the topic guide for RAG
+Skill({ name: 'enhance-docs', args: `agent-knowledge/${slug}.md --ai` });
+
+// Enhance the master index
+Skill({ name: 'enhance-prompts', args: 'agent-knowledge/CLAUDE.md' });
+```
+
+## Output Format
+
+Return structured JSON between markers:
+
+```
+=== LEARN_RESULT ===
+{
+  "topic": "recursion",
+  "slug": "recursion",
+  "depth": "medium",
+  "guideFile": "agent-knowledge/recursion.md",
+  "sourcesFile": "agent-knowledge/resources/recursion-sources.json",
+  "sourceCount": 20,
+  "sourceBreakdown": {
+    "officialDocs": 4,
+    "tutorials": 5,
+    "stackOverflow": 3,
+    "blogPosts": 5,
+    "github": 3
+  },
+  "selfEvaluation": {
+    "coverage": 8,
+    "diversity": 7,
+    "examples": 9,
+    "accuracy": 8,
+    "gaps": ["tail recursion optimization not covered"]
+  },
+  "enhanced": true,
+  "indexUpdated": true
+}
+=== END_RESULT ===
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| WebSearch fails | Retry with simpler query |
+| WebFetch timeout | Skip source, note in metadata |
+| <minSources found | Warn user, proceed with available |
+| Enhancement fails | Skip, note in output |
+| Index doesn't exist | Create new index |
+
+## Token Budget
+
+Estimated token usage by phase:
+
+| Phase | Tokens | Notes |
+|-------|--------|-------|
+| WebSearch queries | ~2,000 | 5-8 queries |
+| Source scoring | ~1,000 | Metadata only |
+| WebFetch extraction | ~40,000 | 20 sources × 2,000 avg |
+| Synthesis | ~10,000 | Guide generation |
+| Enhancement | ~5,000 | Two skill calls |
+| **Total** | ~60,000 | Within opus budget |
+
+## Integration
+
+This skill is invoked by:
+- `learn-agent` for `/learn` command
+- Potentially other research-oriented agents

package/adapters/opencode/skills/orchestrate-review/SKILL.md

@@ -0,0 +1,95 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: orchestrate-review
+description: "Use when user asks to \"deep review the code\", \"thorough code review\", \"multi-pass review\", or when orchestrating Phase 9 review loop. Provides review pass definitions (code quality, security, performance, test coverage, specialists), signal detection patterns, and iteration algorithms."
+metadata:
+  short-description: "Multi-pass code review orchestration"
+---
+
+> **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`
+
+
+# Orchestrate Review
+
+Multi-pass code review with parallel Task agents, finding aggregation, and iteration until clean.
+
+## Scope-Based Specialist Selection
+
+Select conditional specialists based on the review scope:
+- **User request**: Detect signals from content user refers to (files, directory, module)
+- **Workflow (Phase 9)**: Detect signals from changed files only
+- **Project audit**: Detect signals from project structure as a whole
+
+## Review Passes
+
+Spawn parallel `general-purpose` Task agents (model: `sonnet`), one per pass:
+
+### Core (Always)
+*(JavaScript reference - not executable in OpenCode)*
+
+### Conditional (Signal-Based)
+```javascript
+if (signals.hasDb) passes.push({ id: 'database', role: 'database specialist',
+  focus: ['Query performance', 'Indexes/transactions', 'Migration safety', 'Data integrity'] });
+if (signals.needsArchitecture) passes.push({ id: 'architecture', role: 'architecture reviewer',
+  focus: ['Module boundaries', 'Dependency direction', 'Cross-layer coupling', 'Pattern consistency'] });
+if (signals.hasApi) passes.push({ id: 'api', role: 'api designer',
+  focus: ['REST conventions', 'Error/status consistency', 'Pagination/filters', 'Versioning'] });
+if (signals.hasFrontend) passes.push({ id: 'frontend', role: 'frontend specialist',
+  focus: ['Component boundaries', 'State management', 'Accessibility', 'Render performance'] });
+if (signals.hasBackend) passes.push({ id: 'backend', role: 'backend specialist',
+  focus: ['Service boundaries', 'Domain logic', 'Concurrency/idempotency', 'Background job safety'] });
+if (signals.hasDevops) passes.push({ id: 'devops', role: 'devops reviewer',
+  focus: ['CI/CD safety', 'Secrets handling', 'Build/test pipelines', 'Deploy config'] });
+```
+
+## Signal Detection
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Task Prompt Template
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Aggregation
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Iteration Loop
+
+**Security Note**: Fixes are applied by the orchestrator using standard Edit tool permissions. Critical/high severity findings should be reviewed before applying - do not blindly apply LLM-suggested fixes to security-sensitive code. The orchestrator validates each fix against the original issue.
+
+- Invoke `@general-purpose` agent
+- Invoke `@deslop-agent` agent
+
+
+## Review Queue
+
+Store state at `{stateDir}/review-queue-{timestamp}.json`:
+```json
+{
+  "status": "open|resolved|blocked",
+  "scope": { "type": "diff", "files": ["..."] },
+  "passes": ["code-quality", "security"],
+  "items": [],
+  "iteration": 0,
+  "stallCount": 0
+}
+```
+
+Delete when approved. Keep when blocked for orchestrator inspection.
+
+## Cross-Platform Compatibility
+
+This skill uses `Task({ subagent_type: ... })` which is Claude Code syntax. For other platforms:
+
+| Platform | Equivalent Syntax |
+|----------|-------------------|
+| Claude Code | `Task({ subagent_type: 'general-purpose', model: 'sonnet', prompt: ... })` |
+| OpenCode | `spawn_agent({ type: 'general-purpose', model: 'sonnet', prompt: ... })` |
+| Codex CLI | `$agent general-purpose --model sonnet --prompt "..."` |
+
+The aggregation and iteration logic remains the same across platforms - only the agent spawning syntax differs.

package/adapters/opencode/skills/perf-analyzer/SKILL.md

@@ -0,0 +1,38 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: perf-analyzer
+description: "Use when synthesizing perf findings into evidence-backed recommendations and decisions."
+version: 5.0.0
+---
+
+# perf-analyzer
+
+Synthesize performance investigation results into clear recommendations.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Inputs
+
+- Baseline data
+- Experiment results
+- Profiling evidence
+- Hypotheses tested
+- Breaking point results
+
+## Output Format
+
+```
+summary: <2-3 sentences>
+recommendations:
+  - <actionable recommendation 1>
+  - <actionable recommendation 2>
+abandoned:
+  - <hypothesis or experiment that failed>
+next_steps:
+  - <if user should continue or stop>
+```
+
+## Constraints
+
+- Only cite evidence that exists in logs or code.
+- If data is insufficient, say so and request a re-run.

package/adapters/opencode/skills/perf-baseline-manager/SKILL.md

@@ -0,0 +1,31 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: perf-baseline-manager
+description: "Use when managing perf baselines, consolidating results, or comparing versions. Ensures one baseline JSON per version."
+version: 5.0.0
+---
+
+# perf-baseline-manager
+
+Manage baseline storage and comparison.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Required Rules
+
+- One baseline JSON per version.
+- Store under `{state-dir}/perf/baselines/<version>.json`.
+- Record metrics + environment metadata.
+
+## Output Format
+
+```
+baseline_version: <version>
+metrics: <summary>
+file: <path>
+```
+
+## Constraints
+
+- Overwrite older baseline for the same version.
+- Do not create multiple files for one version.

package/adapters/opencode/skills/perf-benchmarker/SKILL.md

@@ -0,0 +1,49 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: perf-benchmarker
+description: "Use when running performance benchmarks, establishing baselines, or validating regressions with sequential runs. Enforces 60s minimum runs (30s only for binary search) and no parallel benchmarks."
+version: 5.0.0
+argument-hint: "[command] [duration]"
+---
+
+# perf-benchmarker
+
+Run sequential benchmarks with strict duration rules.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Parse Arguments
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Required Rules
+
+- Benchmarks MUST run sequentially (never parallel).
+- Minimum duration: 60s per run (30s only for binary search).
+- Warmup: 10s minimum before measurement.
+- Re-run anomalies.
+
+## Output Format
+
+```
+command: <benchmark command>
+duration: <seconds>
+warmup: <seconds>
+results: <metrics summary>
+notes: <anomalies or reruns>
+```
+
+## Output Contract
+
+Benchmarks MUST emit a JSON metrics block between markers:
+
+```
+PERF_METRICS_START
+{"scenarios":{"low":{"latency_ms":120},"high":{"latency_ms":450}}}
+PERF_METRICS_END
+```
+
+## Constraints
+
+- No short runs unless binary-search phase.
+- Do not change code while benchmarking.

package/adapters/opencode/skills/perf-code-paths/SKILL.md

@@ -0,0 +1,33 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: perf-code-paths
+description: "Use when mapping code paths, entrypoints, and likely hot files before profiling."
+version: 5.0.0
+---
+
+# perf-code-paths
+
+Identify likely implementation paths for a performance scenario.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Required Steps
+
+1. Use repo-map if available; otherwise use grep for entrypoints and handlers.
+2. List top candidate files/symbols tied to the scenario.
+3. Include imports/exports or call chains when relevant.
+
+## Output Format
+
+```
+keywords: <comma-separated list>
+paths:
+  - file: <path>
+    symbols: [<symbol1>, <symbol2>]
+    evidence: <short reason>
+```
+
+## Constraints
+
+- Focus only on supported languages (Rust, Java, JS/TS, Go, Python).
+- Keep to the most relevant 10-15 files.

package/adapters/opencode/skills/perf-investigation-logger/SKILL.md

@@ -0,0 +1,42 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: perf-investigation-logger
+description: "Use when appending structured perf investigation notes and evidence."
+version: 5.0.0
+---
+
+# perf-investigation-logger
+
+Append structured investigation notes to `{state-dir}/perf/investigations/<id>.md`.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Required Content
+
+1. Exact user quotes (verbatim)
+2. Phase summary
+3. Decisions and rationale
+4. Evidence pointers (files, metrics, commands)
+
+## Output Format
+
+```
+## <Phase Name> - <YYYY-MM-DD>
+
+**User Quote:** "<exact quote>"
+
+**Summary**
+- ...
+
+**Evidence**
+- Command: `...`
+- File: `path:line`
+
+**Decision**
+- ...
+```
+
+## Constraints
+
+- Use `AI_STATE_DIR` for state path (default `.opencode`).
+- Do not paraphrase user quotes.

package/adapters/opencode/skills/perf-profiler/SKILL.md

@@ -0,0 +1,39 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: perf-profiler
+description: "Use when profiling CPU/memory hot paths, generating flame graphs, or capturing JFR/perf evidence."
+version: 5.0.0
+argument-hint: "[tool] [command]"
+---
+
+# perf-profiler
+
+Run profiling tools and capture hotspots with evidence.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Parse Arguments
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Required Rules
+
+- Verify debug symbols before profiling.
+- Capture file:line for hotspots.
+- Provide flame graph or equivalent output when possible.
+
+## Output Format
+
+```
+tool: <profiler>
+command: <command>
+hotspots:
+  - file:line - reason
+artifacts:
+  - <path to flame graph or profile>
+```
+
+## Constraints
+
+- No profiling without a clear scenario.
+- Keep outputs minimal and evidence-backed.