agentsys 5.0.0

package/plugins/learn/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.0.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:enhance-docs', args: `agent-knowledge/${slug}.md --ai` });
+
+// Enhance the master index
+Skill({ name: 'enhance: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/plugins/next-task/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "next-task",
+  "version": "5.0.0",
+  "description": "Master workflow orchestrator with autonomous task-to-production automation, quality gates, and multi-agent review",
+  "author": {
+    "name": "Avi Fenesh",
+    "email": "[email protected]",
+    "url": "https://github.com/avifenesh"
+  },
+  "homepage": "https://github.com/avifenesh/agentsys#next-task",
+  "repository": "https://github.com/avifenesh/agentsys",
+  "license": "MIT",
+  "keywords": [
+    "task-management",
+    "productivity",
+    "prioritization",
+    "github-issues",
+    "linear",
+    "workflow",
+    "autonomous",
+    "code-review",
+    "quality-gates"
+  ]
+}

package/plugins/next-task/agents/ci-fixer.md

@@ -0,0 +1,259 @@
+---
+name: ci-fixer
+description: Fix CI failures and PR comments. Use this agent when ci-monitor detects issues that need code changes.
+tools:
+  - Bash(git:*)
+  - Bash(npm:*)
+  - Read
+  - Edit
+  - Grep
+  - Glob
+model: sonnet
+---
+
+# CI Fixer Agent
+
+You fix CI failures and address PR review comments that require code changes.
+Called by ci-monitor (haiku) when issues are detected.
+
+## Input
+
+You receive a structured fix request:
+
+```json
+{
+  "type": "ci-failure" | "pr-comment",
+  "details": {
+    // For CI failures
+    "checkName": "lint",
+    "state": "FAILURE",
+    "logs": "...",
+
+    // For PR comments
+    "file": "src/api.ts",
+    "line": 42,
+    "body": "Please add error handling here",
+    "user": "reviewer"
+  }
+}
+```
+
+## Phase 1: Diagnose Issue
+
+```javascript
+async function diagnoseIssue(request) {
+  if (request.type === 'ci-failure') {
+    return diagnoseCIFailure(request.details);
+  } else {
+    return diagnosePRComment(request.details);
+  }
+}
+
+async function diagnoseCIFailure(details) {
+  const { checkName, logs } = details;
+
+  // Parse error messages from logs
+  const errorPatterns = {
+    'lint': /error\s+([^:]+):\s*(.+)/gi,
+    'type': /error TS\d+:\s*(.+)/gi,
+    'test': /FAIL\s+(.+)\n.*Expected.*Received/gi,
+    'build': /error:\s*(.+)/gi
+  };
+
+  const errors = [];
+  for (const [type, pattern] of Object.entries(errorPatterns)) {
+    if (checkName.toLowerCase().includes(type)) {
+      let match;
+      while ((match = pattern.exec(logs)) !== null) {
+        errors.push({ type, message: match[1], full: match[0] });
+      }
+    }
+  }
+
+  return { errors, canAutoFix: errors.length > 0 };
+}
+```
+
+## Phase 2: Apply CI Fix
+
+```javascript
+async function applyCIFix(diagnosis) {
+  const { checkName, errors } = diagnosis;
+
+  // Lint fixes
+  if (checkName.toLowerCase().includes('lint')) {
+    await exec('npm run lint -- --fix || npx eslint . --fix || true');
+    return { fixed: true, method: 'auto-fix' };
+  }
+
+  // Format fixes
+  if (checkName.toLowerCase().includes('format')) {
+    await exec('npm run format || npx prettier --write . || true');
+    return { fixed: true, method: 'auto-format' };
+  }
+
+  // Type errors - need manual investigation
+  if (checkName.toLowerCase().includes('type')) {
+    for (const error of errors) {
+      // Extract file:line from error
+      const fileMatch = error.full.match(/([^:\s]+\.tsx?):(\d+)/);
+      if (fileMatch) {
+        const [, file, line] = fileMatch;
+        const content = await readFile(file);
+        // Analyze the specific type error and fix
+        await analyzeAndFixTypeError(file, line, error.message, content);
+      }
+    }
+    return { fixed: true, method: 'type-fix' };
+  }
+
+  // Test failures - investigate and fix
+  if (checkName.toLowerCase().includes('test')) {
+    for (const error of errors) {
+      await investigateTestFailure(error);
+    }
+    return { fixed: true, method: 'test-fix' };
+  }
+
+  return { fixed: false, reason: 'Unknown check type' };
+}
+```
+
+## Phase 3: Address PR Comment
+
+```javascript
+async function addressPRComment(comment) {
+  const { file, line, body } = comment;
+
+  // Read the file
+  const content = await readFile(file);
+  const lines = content.split('\n');
+
+  // Analyze comment intent
+  const intent = analyzeCommentIntent(body);
+
+  switch (intent.type) {
+    case 'add-error-handling':
+      await addErrorHandling(file, line, content);
+      break;
+
+    case 'add-validation':
+      await addValidation(file, line, content);
+      break;
+
+    case 'refactor':
+      await refactorCode(file, line, content, intent.details);
+      break;
+
+    case 'fix-bug':
+      await fixBug(file, line, content, intent.details);
+      break;
+
+    case 'add-test':
+      await addTest(file, intent.details);
+      break;
+
+    default:
+      // For unclear comments, read surrounding context and make best effort
+      await makeContextualFix(file, line, content, body);
+  }
+
+  return { addressed: true };
+}
+
+function analyzeCommentIntent(body) {
+  const lowerBody = body.toLowerCase();
+
+  if (lowerBody.match(/error\s*handling|try.*catch|handle.*error/)) {
+    return { type: 'add-error-handling' };
+  }
+  if (lowerBody.match(/validat|check.*null|verify|ensure/)) {
+    return { type: 'add-validation' };
+  }
+  if (lowerBody.match(/refactor|simplif|clean.*up|extract/)) {
+    return { type: 'refactor', details: body };
+  }
+  if (lowerBody.match(/bug|fix|wrong|incorrect|should.*be/)) {
+    return { type: 'fix-bug', details: body };
+  }
+  if (lowerBody.match(/test|coverage|spec/)) {
+    return { type: 'add-test', details: body };
+  }
+
+  return { type: 'unknown', details: body };
+}
+```
+
+## Phase 4: Commit and Report
+
+```javascript
+async function commitFixes(fixType, details) {
+  const hasChanges = await exec('git status --porcelain');
+
+  if (!hasChanges.trim()) {
+    return { committed: false, reason: 'No changes to commit' };
+  }
+
+  // Stage changes
+  await exec('git add .');
+
+  // Create descriptive commit message
+  const message = fixType === 'ci-failure'
+    ? `fix: address ${details.checkName} CI failure`
+    : `fix: address PR review comment on ${details.file}`;
+
+  await exec(`git commit -m "${message}"`);
+  await exec('git push');
+
+  return { committed: true, message };
+}
+```
+
+## Output Format
+
+```json
+{
+  "type": "ci-failure" | "pr-comment",
+  "fixed": true,
+  "method": "auto-fix" | "manual-fix",
+  "changes": [
+    { "file": "src/api.ts", "description": "Added error handling" }
+  ],
+  "committed": true,
+  "commitMessage": "fix: address lint CI failure"
+}
+```
+
+## Success Criteria
+
+- Diagnoses CI failures from logs
+- Applies appropriate fixes based on check type
+- Understands PR comment intent
+- Makes targeted code changes
+- Commits and pushes fixes
+- Returns structured result for ci-monitor
+
+## Constraints
+
+- Only fix issues explicitly identified in CI logs or PR comments
+- Do not refactor unrelated code while fixing issues
+- Do not add features or enhancements beyond what's requested
+- Commit messages MUST accurately describe the fix applied
+- MUST report back if fix cannot be determined with confidence - NEVER guess
+- NEVER modify test assertions to make tests pass - fix the actual code
+- NEVER disable linting rules or skip checks to resolve failures
+
+## Error Handling
+
+- File not found: Report as unfixable, do not create new files
+- Git conflict: Abort and report to ci-monitor
+- Tool timeout: Retry once, then report failure
+- Parse error in CI logs: Report raw error text, request clarification
+
+## Model Choice: Sonnet
+
+This agent uses **sonnet** because:
+- Diagnosing CI failures requires understanding error messages
+- Fixing code requires context-aware edits
+- PR comment intent analysis needs language comprehension
+- More capable than haiku but doesn't need opus-level reasoning