agentsys 5.0.0

package/plugins/next-task/skills/discover-tasks/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: discover-tasks
+description: "Use when discovering and prioritizing tasks from configured sources. Handles GitHub, GitLab, local files, and custom sources."
+version: 5.0.0
+---
+
+# discover-tasks
+
+Discover tasks from configured sources, validate them, and present for user selection.
+
+## Workflow
+
+### Phase 1: Load Policy and Claimed Tasks
+
+```javascript
+// Use relative path from skill directory to plugin lib
+// Path: skills/task-discovery/ -> ../../lib/state/workflow-state.js
+const workflowState = require('../../lib/state/workflow-state.js');
+
+const state = workflowState.readState();
+const policy = state.policy;
+
+// Load claimed tasks from registry
+const claimedTasks = workflowState.readTasks().tasks || [];
+const claimedIds = new Set(claimedTasks.map(t => t.id));
+```
+
+### Phase 2: Fetch Tasks by Source
+
+**Source types:**
+- `github` / `gh-issues`: GitHub CLI
+- `gitlab`: GitLab CLI
+- `local` / `tasks-md`: Local markdown files
+- `custom`: CLI/MCP/Skill tool
+- `other`: Agent interprets description
+
+**GitHub Issues:**
+```bash
+# Fetch with pagination awareness
+gh issue list --state open \
+  --json number,title,body,labels,assignees,createdAt,url \
+  --limit 100 > /tmp/gh-issues.json
+```
+
+**GitLab Issues:**
+```bash
+glab issue list --state opened --output json --per-page 100 > /tmp/glab-issues.json
+```
+
+**Local tasks.md:**
+```bash
+for f in PLAN.md tasks.md TODO.md; do
+  [ -f "$f" ] && grep -n '^\s*- \[ \]' "$f"
+done
+```
+
+**Custom Source:**
+```javascript
+const { sources } = require('../../lib');
+const capabilities = sources.getToolCapabilities(toolName);
+// Execute capabilities.commands.list_issues
+```
+
+### Phase 3: Filter and Score
+
+**Exclude claimed tasks:**
+```javascript
+const available = tasks.filter(t => !claimedIds.has(String(t.number || t.id)));
+```
+
+**Apply priority filter:**
+```javascript
+const LABEL_MAPS = {
+  bugs: ['bug', 'fix', 'error', 'defect'],
+  security: ['security', 'vulnerability', 'cve'],
+  features: ['enhancement', 'feature', 'improvement']
+};
+
+function filterByPriority(tasks, filter) {
+  if (filter === 'continue' || filter === 'all') return tasks;
+  const targetLabels = LABEL_MAPS[filter] || [];
+  return tasks.filter(t => {
+    const labels = (t.labels || []).map(l => (l.name || l).toLowerCase());
+    return targetLabels.some(target => labels.some(l => l.includes(target)));
+  });
+}
+```
+
+**Score tasks:**
+```javascript
+function scoreTask(task) {
+  let score = 0;
+  const labels = (task.labels || []).map(l => (l.name || l).toLowerCase());
+
+  // Priority labels
+  if (labels.some(l => l.includes('critical') || l.includes('p0'))) score += 100;
+  if (labels.some(l => l.includes('high') || l.includes('p1'))) score += 50;
+  if (labels.some(l => l.includes('security'))) score += 40;
+
+  // Quick wins
+  if (labels.some(l => l.includes('small') || l.includes('quick'))) score += 20;
+
+  // Age (older bugs get priority)
+  if (task.createdAt) {
+    const ageInDays = (Date.now() - new Date(task.createdAt)) / 86400000;
+    if (labels.includes('bug') && ageInDays > 30) score += 10;
+  }
+
+  return score;
+}
+```
+
+### Phase 4: Present to User via AskUserQuestion
+
+**CRITICAL**: Labels MUST be max 30 characters (OpenCode limit).
+
+```javascript
+function truncateLabel(num, title) {
+  const prefix = `#${num}: `;
+  const maxLen = 30 - prefix.length;
+  return title.length > maxLen
+    ? prefix + title.substring(0, maxLen - 1) + '...'
+    : prefix + title;
+}
+
+const options = topTasks.slice(0, 5).map(task => ({
+  label: truncateLabel(task.number, task.title),
+  description: `Score: ${task.score} | ${(task.labels || []).slice(0, 2).join(', ')}`
+}));
+
+AskUserQuestion({
+  questions: [{
+    header: "Select Task",
+    question: "Which task should I work on?",
+    options,
+    multiSelect: false
+  }]
+});
+```
+
+### Phase 5: Update State
+
+```javascript
+workflowState.updateState({
+  task: {
+    id: String(selectedTask.number),
+    source: policy.taskSource,
+    title: selectedTask.title,
+    description: selectedTask.body || '',
+    labels: selectedTask.labels?.map(l => l.name || l) || [],
+    url: selectedTask.url
+  }
+});
+
+workflowState.completePhase({
+  tasksAnalyzed: tasks.length,
+  selectedTask: selectedTask.number
+});
+```
+
+### Phase 6: Post Comment (GitHub only)
+
+```bash
+gh issue comment "$TASK_ID" --body "[BOT] Workflow started for this issue."
+```
+
+## Output Format
+
+```markdown
+## Task Selected
+
+**Task**: #{id} - {title}
+**Source**: {source}
+**URL**: {url}
+
+Proceeding to worktree setup...
+```
+
+## Error Handling
+
+If no tasks found:
+1. Suggest creating issues
+2. Suggest running /audit-project
+3. Suggest using 'all' priority filter
+
+## Constraints
+
+- MUST use AskUserQuestion for task selection (not plain text)
+- Labels MUST be max 30 characters
+- Exclude tasks already claimed by other workflows
+- Top 5 tasks only

package/plugins/next-task/skills/orchestrate-review/SKILL.md

@@ -0,0 +1,239 @@
+---
+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"
+---
+
+# 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; 2 stalls indicates fixes aren't progressing
+const MAX_ITERATIONS = 5, MAX_STALLS = 2;
+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.updateFlow({ reviewResult: { 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: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) {
+    workflowState.updateFlow({
+      reviewResult: { approved: false, blocked: true,
+                     reason: stallCount >= MAX_STALLS ? 'stall-detected' : 'iteration-limit',
+                     remaining: findings.totals }
+    });
+    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/plugins/next-task/skills/validate-delivery/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: validate-delivery
+description: "Use when validating task completion before shipping. Runs tests, build, and requirement checks. Returns pass/fail with fix instructions."
+version: 5.0.0
+---
+
+# validate-delivery
+
+Autonomously validate that a task is complete and ready to ship.
+
+## Validation Checks
+
+### Check 1: Review Status
+
+```javascript
+function checkReviewStatus(reviewResults) {
+  if (!reviewResults) return { passed: false, reason: 'No review results' };
+  if (reviewResults.approved) return { passed: true };
+  if (reviewResults.override) return { passed: true, override: true };
+  return { passed: false, reason: 'Review not approved' };
+}
+```
+
+### Check 2: Tests Pass
+
+```bash
+# Detect test runner and run
+if grep -q '"test"' package.json; then
+  npm test; TEST_EXIT_CODE=$?
+elif [ -f "pytest.ini" ]; then
+  pytest; TEST_EXIT_CODE=$?
+elif [ -f "Cargo.toml" ]; then
+  cargo test; TEST_EXIT_CODE=$?
+elif [ -f "go.mod" ]; then
+  go test ./...; TEST_EXIT_CODE=$?
+else
+  TEST_EXIT_CODE=0  # No tests
+fi
+```
+
+### Check 3: Build Passes
+
+```bash
+if grep -q '"build"' package.json; then
+  npm run build; BUILD_EXIT_CODE=$?
+elif [ -f "Cargo.toml" ]; then
+  cargo build --release; BUILD_EXIT_CODE=$?
+elif [ -f "go.mod" ]; then
+  go build ./...; BUILD_EXIT_CODE=$?
+else
+  BUILD_EXIT_CODE=0  # No build step
+fi
+```
+
+### Check 4: Requirements Met
+
+```javascript
+async function checkRequirementsMet(task, changedFiles) {
+  const requirements = extractRequirements(task.description);
+  const results = [];
+
+  for (const req of requirements) {
+    const implemented = await verifyRequirement(req, changedFiles);
+    results.push({ requirement: req, implemented });
+  }
+
+  return {
+    passed: results.every(r => r.implemented),
+    requirements: results
+  };
+}
+
+function extractRequirements(description) {
+  const reqs = [];
+  // Extract bullet points: - Item
+  const bullets = description.match(/^[-*]\s+(.+)$/gm);
+  if (bullets) reqs.push(...bullets.map(m => m.replace(/^[-*]\s+/, '')));
+  // Extract numbered items: 1. Item
+  const numbered = description.match(/^\d+\.\s+(.+)$/gm);
+  if (numbered) reqs.push(...numbered.map(m => m.replace(/^\d+\.\s+/, '')));
+  return [...new Set(reqs)].slice(0, 10);
+}
+```
+
+### Check 5: No Regressions
+
+```bash
+# Compare test counts before/after changes
+git stash
+BEFORE=$(npm test 2>&1 | grep -oE '[0-9]+ passing' | grep -oE '[0-9]+')
+git stash pop
+AFTER=$(npm test 2>&1 | grep -oE '[0-9]+ passing' | grep -oE '[0-9]+')
+[ "$AFTER" -lt "$BEFORE" ] && REGRESSION=true || REGRESSION=false
+```
+
+## Aggregate Results
+
+```javascript
+const checks = {
+  reviewClean: checkReviewStatus(reviewResults),
+  testsPassing: { passed: TEST_EXIT_CODE === 0 },
+  buildPassing: { passed: BUILD_EXIT_CODE === 0 },
+  requirementsMet: await checkRequirementsMet(task, changedFiles),
+  noRegressions: { passed: !REGRESSION }
+};
+
+const allPassed = Object.values(checks).every(c => c.passed);
+const failedChecks = Object.entries(checks)
+  .filter(([_, v]) => !v.passed)
+  .map(([k]) => k);
+```
+
+## Decision and Output
+
+### If All Pass
+
+```javascript
+workflowState.completePhase({
+  approved: true,
+  checks,
+  summary: 'All validation checks passed'
+});
+
+return { approved: true, checks };
+```
+
+### If Any Fail
+
+```javascript
+const fixInstructions = generateFixInstructions(checks, failedChecks);
+
+workflowState.failPhase('Validation failed', {
+  approved: false,
+  failedChecks,
+  fixInstructions
+});
+
+return { approved: false, failedChecks, fixInstructions };
+```
+
+## Fix Instructions Generator
+
+```javascript
+function generateFixInstructions(checks, failedChecks) {
+  const instructions = [];
+
+  if (failedChecks.includes('testsPassing')) {
+    instructions.push({ action: 'Fix failing tests', command: 'npm test' });
+  }
+  if (failedChecks.includes('buildPassing')) {
+    instructions.push({ action: 'Fix build errors', command: 'npm run build' });
+  }
+  if (failedChecks.includes('requirementsMet')) {
+    const unmet = checks.requirementsMet.requirements
+      .filter(r => !r.implemented)
+      .map(r => r.requirement);
+    instructions.push({ action: 'Implement missing', details: unmet.join(', ') });
+  }
+
+  return instructions;
+}
+```
+
+## Output Format
+
+```json
+{
+  "approved": true|false,
+  "checks": {
+    "reviewClean": { "passed": true },
+    "testsPassing": { "passed": true },
+    "buildPassing": { "passed": true },
+    "requirementsMet": { "passed": true },
+    "noRegressions": { "passed": true }
+  },
+  "failedChecks": [],
+  "fixInstructions": []
+}
+```
+
+## Constraints
+
+- NO human intervention - fully autonomous
+- Returns structured JSON for orchestrator
+- Generates specific fix instructions on failure
+- Workflow retries automatically after fixes

package/plugins/perf/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "perf",
+  "version": "5.0.0",
+  "description": "Rigorous performance investigation workflow with baselines, profiling, and evidence-backed decisions",
+  "author": {
+    "name": "Avi Fenesh",
+    "email": "[email protected]",
+    "url": "https://github.com/avifenesh"
+  },
+  "homepage": "https://github.com/avifenesh/agentsys#perf",
+  "repository": "https://github.com/avifenesh/agentsys",
+  "license": "MIT",
+  "keywords": [
+    "performance",
+    "benchmarks",
+    "profiling",
+    "optimization",
+    "baseline"
+  ]
+}

package/plugins/perf/agents/perf-analyzer.md

@@ -0,0 +1,43 @@
+---
+name: perf-analyzer
+description: Synthesize perf findings into evidence-backed recommendations and decisions.
+tools:
+  - Skill
+  - Read
+  - Write
+model: opus
+---
+
+# Perf Analyzer
+
+You MUST follow `docs/perf-requirements.md` as the canonical contract.
+
+Synthesize investigation outputs into clear, evidence-backed recommendations.
+
+You MUST execute the perf-analyzer skill to produce the output. Do not bypass the skill.
+
+## 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/plugins/perf/agents/perf-code-paths.md

@@ -0,0 +1,16 @@
+---
+name: perf-code-paths
+description: Map likely code paths for perf scenarios before profiling.
+tools:
+  - Skill
+  - Read
+  - Grep
+  - Glob
+model: sonnet
+---
+
+# Perf Code Paths
+
+Identify code paths and entrypoints tied to a performance scenario.
+
+You MUST execute the perf-code-paths skill to produce the output. Do not bypass the skill.