agentsys 5.3.0 → 5.3.2

package/.cursor/skills/learn/SKILL.md

@@ -0,0 +1,349 @@
+---
+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.1.0
+argument-hint: "[topic] [--depth=brief|medium|deep]"
+---
+
+# learn
+
+Research any topic by gathering online resources and creating a comprehensive learning guide with RAG-optimized indexes.
+
+## Parse Arguments
+
+```javascript
+const args = '$ARGUMENTS'.split(' ').filter(Boolean);
+const depth = args.find(a => a.startsWith('--depth='))?.split('=')[1] || 'medium';
+const topic = args.filter(a => !a.startsWith('--')).join(' ');
+```
+
+## 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/.cursor/skills/orchestrate-review/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: orchestrate-review
+version: 5.1.0
+description: "Use when user asks to \"deep review the code\", \"thorough code review\", \"multi-pass review\", or when orchestrating the Phase 9 review loop. Provides review pass definitions (code quality, security, performance, test coverage), signal detection patterns, and iteration algorithms."
+metadata:
+  short-description: "Multi-pass code review orchestration"
+---
+
+# 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
+const corePasses = [
+  { id: 'code-quality', role: 'code quality reviewer',
+    focus: ['Style and consistency', 'Best practices', 'Bugs and logic errors', 'Error handling', 'Maintainability', 'Duplication'] },
+  { id: 'security', role: 'security reviewer',
+    focus: ['Auth/authz flaws', 'Input validation', 'Injection risks', 'Secrets exposure', 'Insecure defaults'] },
+  { id: 'performance', role: 'performance reviewer',
+    focus: ['N+1 queries', 'Blocking operations', 'Hot path inefficiencies', 'Memory leaks'] },
+  { id: 'test-coverage', role: 'test coverage reviewer',
+    focus: ['Missing tests', 'Edge case coverage', 'Test quality', 'Integration needs', 'Mock appropriateness'] }
+];
+```
+
+### 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
+const signals = {
+  hasDb: files.some(f => /(db|migrations?|schema|prisma|typeorm|sql)/i.test(f)),
+  hasApi: files.some(f => /(api|routes?|controllers?|handlers?)/i.test(f)),
+  hasFrontend: files.some(f => /\.(tsx|jsx|vue|svelte)$/.test(f)),
+  hasBackend: files.some(f => /(server|backend|services?|domain)/i.test(f)),
+  hasDevops: files.some(f => /(\.github\/workflows|Dockerfile|k8s|terraform)/i.test(f)),
+  needsArchitecture: files.length > 20  // 20+ files typically indicates cross-module changes
+};
+```
+
+## Task Prompt Template
+
+```
+You are a ${pass.role}. Review these changed files:
+${files.join('\n')}
+
+Focus: ${pass.focus.map(f => `- ${f}`).join('\n')}
+
+Return JSON:
+{
+  "pass": "${pass.id}",
+  "findings": [{
+    "file": "path.ts",
+    "line": 42,
+    "severity": "critical|high|medium|low",
+    "description": "Issue",
+    "suggestion": "Fix",
+    "confidence": "high|medium|low",
+    "falsePositive": false
+  }]
+}
+
+Example findings (diverse passes and severities):
+
+// Security - high severity
+{ "file": "src/auth/login.ts", "line": 89, "severity": "high",
+  "description": "Password comparison uses timing-vulnerable string equality",
+  "suggestion": "Use crypto.timingSafeEqual() instead of ===",
+  "confidence": "high", "falsePositive": false }
+
+// Code quality - medium severity
+{ "file": "src/utils/helpers.ts", "line": 45, "severity": "medium",
+  "description": "Duplicated validation logic exists in src/api/validators.ts:23",
+  "suggestion": "Extract to shared lib/validation.ts",
+  "confidence": "high", "falsePositive": false }
+
+// Performance - low severity
+{ "file": "src/config.ts", "line": 12, "severity": "low",
+  "description": "Magic number 3600 should be named constant",
+  "suggestion": "const CACHE_TTL_SECONDS = 3600;",
+  "confidence": "medium", "falsePositive": false }
+
+// False positive example
+{ "file": "src/crypto/hash.ts", "line": 78, "severity": "high",
+  "description": "Non-constant time comparison",
+  "suggestion": "N/A - intentional for non-secret data",
+  "confidence": "low", "falsePositive": true }
+
+Report all issues with confidence >= medium. Empty findings array if clean.
+```
+
+## Aggregation
+
+```javascript
+function aggregateFindings(results) {
+  const items = [];
+  for (const {pass, findings = []} of results) {
+    for (const f of findings) {
+      items.push({
+        id: `${pass}:${f.file}:${f.line}:${f.description}`,
+        pass, ...f,
+        status: f.falsePositive ? 'false-positive' : 'open'
+      });
+    }
+  }
+
+  // Deduplicate by id
+  const deduped = [...new Map(items.map(i => [i.id, i])).values()];
+
+  // Group by severity
+  const bySeverity = {critical: [], high: [], medium: [], low: []};
+  deduped.forEach(i => !i.falsePositive && bySeverity[i.severity || 'low'].push(i));
+
+  const totals = Object.fromEntries(Object.entries(bySeverity).map(([k, v]) => [k, v.length]));
+
+  return {
+    items: deduped,
+    bySeverity,
+    totals,
+    openCount: Object.values(totals).reduce((a, b) => a + b, 0)
+  };
+}
+```
+
+## 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.
+
+```javascript
+// 5 iterations balances thoroughness vs cost; 1 stall (2 consecutive identical-hash iterations) indicates fixes aren't progressing
+const MAX_ITERATIONS = 5, MAX_STALLS = 1;
+let iteration = 1, stallCount = 0, lastHash = null;
+
+while (iteration <= MAX_ITERATIONS) {
+  // 1. Spawn parallel Task agents
+  const results = await Promise.all(passes.map(pass => Task({
+    subagent_type: 'general-purpose',
+    model: 'sonnet',
+    prompt: /* see template above */
+  })));
+
+  // 2. Aggregate findings
+  const findings = aggregateFindings(results);
+
+  // 3. Check if done
+  if (findings.openCount === 0) {
+    workflowState.completePhase({ approved: true, iterations: iteration });
+    break;
+  }
+
+  // 4. Fix issues (severity order: critical → high → medium → low)
+  // Orchestrator reviews each suggestion before applying via Edit tool
+  for (const issue of [...findings.bySeverity.critical, ...findings.bySeverity.high,
+                          ...findings.bySeverity.medium, ...findings.bySeverity.low]) {
+    if (!issue.falsePositive) {
+      // Read file, locate issue.line, validate suggestion, apply via Edit tool
+      // For complex fixes, use simple-fixer agent pattern
+    }
+  }
+
+  // 5. Commit
+  exec(`git add . && git commit -m "fix: review feedback (iteration ${iteration})"`);
+
+  // 6. Post-iteration deslop
+  Task({ subagent_type: 'deslop-agent', model: 'sonnet' });
+
+  // 7. Stall detection
+  const hash = crypto.createHash('sha256')
+    .update(JSON.stringify(findings.items.filter(i => !i.falsePositive)))
+    .digest('hex');
+  stallCount = hash === lastHash ? stallCount + 1 : 0;
+  lastHash = hash;
+
+  // 8. Check limits
+  if (stallCount >= MAX_STALLS || iteration >= MAX_ITERATIONS) {
+    const reason = stallCount >= MAX_STALLS ? 'stall-detected' : 'iteration-limit';
+    console.log(`[BLOCKED] Review loop ended: ${reason}. Remaining: ${JSON.stringify(findings.totals)}`);
+    // Ask the user before advancing - do not silently proceed to delivery-validation
+    const question = `Review loop blocked (${reason}). Open issues remain. How should we proceed?`;
+    const response = AskUserQuestion({
+      questions: [{
+        question,
+        header: 'Review Blocked',
+        multiSelect: false,
+        options: [
+          { label: 'Override and proceed', description: 'Advance to delivery-validation with unresolved issues (risky)' },
+          { label: 'Abort workflow', description: 'Stop here; open issues must be fixed manually' }
+        ]
+      }]
+    });
+    // AskUserQuestion returns { answers: { [questionText]: selectedLabel } }
+    const choice = response.answers?.[question] ?? response[question];
+    if (choice === 'Override and proceed') {
+      workflowState.completePhase({
+        approved: false, blocked: true, overridden: true,
+        reason, remaining: findings.totals
+      });
+    } else {
+      workflowState.failPhase(`Review blocked: ${reason}. ${JSON.stringify(findings.totals)} issues remain.`);
+    }
+    break;
+  }
+
+  iteration++;
+}
+```
+
+## 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/.cursor/skills/perf-analyzer/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: perf-analyzer
+description: "Use when synthesizing perf findings into evidence-backed recommendations and decisions."
+version: 5.1.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/.cursor/skills/perf-baseline-manager/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: perf-baseline-manager
+description: "Use when managing perf baselines, consolidating results, or comparing versions. Ensures one baseline JSON per version."
+version: 5.1.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.