agentsys 5.3.0 → 5.3.2

package/.kiro/skills/discover-tasks/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: discover-tasks
+description: "Use when user asks to \"discover tasks\", \"find next task\", \"prioritize issues\", \"what should I work on\", or \"list open issues\". Discovers and ranks tasks from GitHub, GitLab, local files, and custom sources."
+version: 5.1.1
+allowed-tools: "Bash(gh:*), Bash(glab:*), Bash(git:*), Bash(grep:*), Grep, Read, AskUserQuestion"
+---
+
+# discover-tasks
+
+Discover tasks from configured sources, validate them, and present for user selection.
+
+## When to Use
+
+Invoked during Phase 2 of `/next-task` workflow, after policy selection. Also usable standalone when the user wants to discover and select tasks from configured sources.
+
+## Workflow
+
+### Phase 1: Load Policy and Claimed Tasks
+
+```javascript
+// Use relative path from skill directory to plugin lib
+// Path: skills/discover-tasks/ -> ../../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
+- `gh-projects`: GitHub Projects (v2 boards)
+- `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
+```
+
+**GitHub Projects (v2):**
+```javascript
+// Extract gh-projects parameters from policy
+const projectNumber = policy.taskSource.projectNumber;
+const owner = policy.taskSource.owner;
+if (!projectNumber || !owner) {
+  throw new Error('gh-projects source missing projectNumber or owner in policy.taskSource');
+}
+```
+
+```bash
+# Requires 'project' token scope. If permission error: gh auth refresh -s project
+gh project item-list "$PROJECT_NUMBER" --owner "$OWNER" --format json --limit 100 > /tmp/gh-project-items.json
+```
+
+```javascript
+const fs = require('fs');
+const raw = JSON.parse(fs.readFileSync('/tmp/gh-project-items.json', 'utf8'));
+const items = (raw.items || []);
+
+// Filter to ISSUE type only (exclude PULL_REQUEST, DRAFT_ISSUE)
+const issues = items
+  .filter(item => item.content && item.content.type === 'ISSUE')
+  .map(item => ({
+    number: item.content.number,
+    title: item.content.title,
+    body: item.content.body || '',
+    labels: (item.content.labels || []).map(l => typeof l === 'object' ? l.name || '' : l).filter(Boolean),
+    url: item.content.url,
+    createdAt: item.content.createdAt
+  }));
+```
+
+[WARN] If `gh project item-list` returns a permission error, tell the user:
+`Run: gh auth refresh -s project`
+
+**Custom Source:**
+```javascript
+const { sources } = require('../../lib');
+const capabilities = sources.getToolCapabilities(toolName);
+// Execute capabilities.commands.list_issues
+```
+
+### Phase 2.5: Collect PR-Linked Issues (GitHub only)
+
+```javascript
+// Default for non-GitHub sources - always defined so Phase 3 filter is safe
+let prLinkedIssues = new Set();
+```
+
+For GitHub sources (`policy.taskSource?.source === 'github'`, `'gh-issues'`, or `'gh-projects'`), fetch all open PRs and build a Set of issue numbers that already have an associated PR. Skip to Phase 3 for all other sources.
+
+```bash
+# Only run when policy.taskSource?.source is 'github', 'gh-issues', or 'gh-projects'
+# Note: covers up to 100 open PRs. If repo has more, some linked issues may not be excluded.
+gh pr list --state open --json number,title,body,headRefName --limit 100 > /tmp/gh-prs.json
+```
+
+```javascript
+const fs = require('fs');
+try {
+  const prs = JSON.parse(fs.readFileSync('/tmp/gh-prs.json', 'utf8') || '[]');
+
+  for (const pr of prs) {
+    // 1. Branch name suffix: fix/some-thing-123 extracts 123
+    // Note: heuristic - branches like "release-2026" will false-positive on issue #2026.
+    // Patterns 2 and 3 are more precise; this is a best-effort supplement.
+    const branchMatch = (pr.headRefName || '').match(/-(\d+)$/);
+    if (branchMatch) prLinkedIssues.add(branchMatch[1]);
+
+    // 2. PR body closing keywords (GitHub's full keyword set, with word boundary)
+    if (pr.body) {
+      const bodyMatches = pr.body.matchAll(/\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi);
+      for (const m of bodyMatches) prLinkedIssues.add(m[1]);
+    }
+
+    // 3. PR title (#N) convention - capture all occurrences
+    const titleMatches = (pr.title || '').matchAll(/\(#(\d+)\)/g);
+    for (const m of titleMatches) prLinkedIssues.add(m[1]);
+  }
+} catch (e) {
+  console.log('[WARN] Could not parse open PRs, skipping PR-link filter:', e.message);
+  prLinkedIssues = new Set();
+}
+```
+
+### Phase 3: Filter and Score
+
+**Exclude claimed tasks:**
+```javascript
+const available = tasks.filter(t => !claimedIds.has(String(t.number || t.id)));
+```
+
+**Exclude issues with open PRs (GitHub only):**
+```javascript
+const filtered = available.filter(t => {
+  const id = String(t.number || t.id);
+  if (prLinkedIssues.has(id)) {
+    console.log(`[INFO] Skipping #${id} - already has an open PR`);
+    return false;
+  }
+  return true;
+});
+```
+
+**Apply priority filter** (pass `filtered` through scoring pipeline):
+```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)));
+  });
+}
+
+const prioritized = filterByPriority(filtered, policy.priorityFilter);
+// Assign score to each task so it is available for display in the UI
+const topTasks = prioritized.map(t => ({ ...t, score: scoreTask(t) })).sort((a, b) => b.score - a.score);
+```
+
+**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?.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)
+
+**Skip this phase entirely for non-GitHub sources (GitLab, local, custom).** Run for `github`, `gh-issues`, and `gh-projects` sources.
+
+```bash
+# Only run for GitHub sources (github, gh-issues, gh-projects). Use policy.taskSource?.source from Phase 1 to check.
+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
+- Exclude issues that already have an open PR (GitHub and GitHub Projects sources)
+- PR-link detection covers up to 100 open PRs (--limit 100 is the fetch cap)
+- Top 5 tasks only

package/.kiro/skills/drift-analysis/SKILL.md

@@ -0,0 +1,324 @@
+---
+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.1.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
+function calculatePriority(item, weights) {
+  let score = 0;
+
+  // Severity base score
+  const severityScores = {
+    critical: 15,
+    high: 10,
+    medium: 5,
+    low: 2
+  };
+  score += severityScores[item.severity] || 5;
+
+  // Category multiplier
+  const categoryWeights = {
+    security: 2.0,    // Security issues get 2x
+    bugs: 1.5,        // Bugs get 1.5x
+    infrastructure: 1.3,
+    features: 1.0,
+    documentation: 0.8
+  };
+  score *= categoryWeights[item.category] || 1.0;
+
+  // Recency boost
+  if (item.createdRecently) score *= 1.2;
+
+  // Stale penalty (old items slightly deprioritized)
+  if (item.daysStale > 180) score *= 0.9;
+
+  return Math.round(score);
+}
+```
+
+### 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
+// Fuzzy matching for feature names
+function featureMatch(docFeature, codeFeature) {
+  const normalize = s => s
+    .toLowerCase()
+    .replace(/[-_\s]+/g, '')
+    .replace(/s$/, ''); // Remove trailing 's'
+
+  const docNorm = normalize(docFeature);
+  const codeNorm = normalize(codeFeature);
+
+  return docNorm.includes(codeNorm) ||
+         codeNorm.includes(docNorm) ||
+         levenshteinDistance(docNorm, codeNorm) < 3;
+}
+```
+
+### 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...
+```