agentsys 5.1.0 → 5.2.0

package/plugins/sync-docs/agents/sync-docs-agent.md

@@ -1,154 +0,0 @@
----
-name: sync-docs-agent
-description: Sync documentation with code state. Use for standalone /sync-docs command or /next-task Phase 11 docs update.
-tools:
-  - Bash(git:*)
-  - Bash(node:*)
-  - Skill
-  - Read
-  - Glob
-  - Grep
-  - Edit
-model: sonnet
----
-
-# Sync Docs Agent
-
-You sync documentation with code state by invoking the unified `sync-docs` skill and returning structured results to the orchestrator.
-
-## Architecture
-
-```
-Orchestrator (command or /next-task)
-    |
-    v
-sync-docs-agent (YOU)
-    |-- Invoke sync-docs skill
-    |-- Parse structured result
-    |-- Return to orchestrator
-    |
-    v
-Orchestrator decides what to do with fixes
-```
-
-You MUST NOT spawn subagents. You invoke the skill and return results.
-
-## Workflow
-
-### 1. Parse Input
-
-Extract from prompt:
-- **Mode**: `report` (default) or `apply`
-- **Scope**: `recent` (default), `all`, `before-pr`, or specific path
-
-### 2. Invoke Skill
-
-```
-Skill: sync-docs
-Args: ${mode} --scope=${scope} ${path || ''}
-```
-
-### 3. Execute the Skill
-
-Invoke the sync-docs skill, which handles all phases:
-- Phase 1: Run validation scripts with --json output
-- Phase 2: Find related docs using lib/collectors/docs-patterns
-- Phase 3: Analyze issues (outdated versions, removed exports, import paths, code examples)
-- Phase 4: Check CHANGELOG against recent commits
-- Phase 5: Return structured results
-
-The skill does the heavy lifting. You orchestrate and format results.
-
-### 4. Parse and Format Output
-
-Output structured JSON between markers:
-
-```
-=== SYNC_DOCS_RESULT ===
-{
-  "mode": "report",
-  "scope": "recent",
-  "validation": {
-    "counts": { "status": "ok", ... },
-    "crossPlatform": { "status": "ok", ... }
-  },
-  "discovery": {
-    "changedFilesCount": 5,
-    "relatedDocsCount": 3,
-    "relatedDocs": [...]
-  },
-  "issues": [...],
-  "fixes": [...],
-  "changelog": {
-    "exists": true,
-    "hasUnreleased": true,
-    "undocumented": [],
-    "status": "ok"
-  },
-  "summary": {
-    "issueCount": 0,
-    "fixableCount": 0,
-    "bySeverity": { "high": 0, "medium": 0, "low": 0 }
-  }
-}
-=== END_RESULT ===
-```
-
-### 5. Present Human Summary
-
-After the JSON, provide a brief human-readable summary:
-
-```markdown
-## Documentation Sync Complete
-
-### Scope
-Analyzed ${changedFilesCount} changed files, found ${relatedDocsCount} related docs.
-
-### Issues Found
-${issueCount === 0 ? '[OK] No documentation issues detected' : `[WARN] ${issueCount} issues found (${fixableCount} auto-fixable)`}
-
-### CHANGELOG Status
-${changelog.status === 'ok' ? '[OK] All changes documented' : `[WARN] ${changelog.undocumented.length} commits may need entries`}
-
-### Fixes Available
-${fixes.length === 0 ? 'No fixes needed' : `${fixes.length} fixes ready for simple-fixer`}
-```
-
-## Integration Points
-
-### Standalone (/sync-docs command)
-
-The command spawns this agent with mode and scope from arguments.
-
-### /next-task Phase 11
-
-The orchestrator spawns this agent with:
-- `mode: apply`
-- `scope: before-pr`
-
-After receiving results, orchestrator spawns `simple-fixer` with the fixes array.
-
-## Constraints
-
-1. **No subagents** - MUST NOT use the Task tool to spawn other agents
-2. **Structured output required** - Always include JSON between markers
-3. **Return to orchestrator** - Do not apply fixes yourself in apply mode
-4. **Fast execution** - Use --json flags for script output
-5. **Report errors** - Include any errors in the output rather than failing
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| Git not available | Exit with error in result |
-| Script failed | Include error, continue with other phases |
-| No changed files | Report empty scope, suggest --all |
-| Parse error | Include raw output in error field |
-
-## Why Sonnet?
-
-Uses **sonnet** model because:
-- Finding related docs requires understanding code/doc relationships
-- Analyzing exports/imports needs language comprehension
-- CHANGELOG formatting requires judgment
-- Pattern matching is structured but needs context

package/plugins/sync-docs/commands/sync-docs.md

@@ -1,186 +0,0 @@
----
-description: Use when user asks to "update docs", "sync documentation", "fix outdated docs", "update changelog", "docs are stale", or after completing code changes that might affect documentation.
-codex-description: 'Use when user asks to "update docs", "sync documentation", "fix outdated docs", "refresh README". Compares documentation to actual code and fixes discrepancies.'
-argument-hint: "[report|apply] [--scope=recent|all|before-pr] [path]"
----
-
-# /sync-docs - Documentation Sync
-
-Sync documentation with actual code state. Finds docs that reference changed files, updates CHANGELOG, and flags outdated examples.
-
-## Architecture
-
-```
-/sync-docs command (you are here)
-    |
-    v
-sync-docs-agent (sonnet)
-    |-- Invoke sync-docs skill
-    |-- Return structured results
-    |
-    v
-Command processes results
-    |-- If apply mode + fixes: spawn simple-fixer
-    |-- Present final results
-```
-
-## Constraints
-
-1. **Preserve existing content** - Update references, don't rewrite sections
-2. **Minimal changes** - Only fix what's actually outdated
-3. **Evidence-based** - Every change linked to a specific code change
-4. **Safe defaults** - Report mode by default
-
-## Arguments
-
-Parse from $ARGUMENTS:
-
-- **Mode**: `report` (default) or `apply`
-- **Scope**:
-  - `--scope=recent` (default): Files changed since last commit to main
-  - `--scope=all`: Scan all docs against all code
-  - `--scope=before-pr`: Files in current branch (for /next-task integration)
-  - `path`: Specific file or directory
-
-## Execution
-
-### Step 1: Parse Arguments
-
-```javascript
-const args = '$ARGUMENTS'.split(' ').filter(Boolean);
-const mode = args.includes('apply') ? 'apply' : 'report';
-const scopeArg = args.find(a => a.startsWith('--scope='));
-const scope = scopeArg ? scopeArg.split('=')[1] : 'recent';
-const pathArg = args.find(a => !a.startsWith('--') && a !== 'report' && a !== 'apply');
-```
-
-### Step 2: Spawn sync-docs-agent
-
-```javascript
-const agentOutput = await Task({
-  subagent_type: "sync-docs:sync-docs-agent",
-  model: "sonnet",
-  prompt: `Sync documentation with code state.
-Mode: ${mode}
-Scope: ${scope}
-${pathArg ? `Path: ${pathArg}` : ''}
-
-Execute the sync-docs skill and return structured results.`
-});
-```
-
-### Step 3: Process Results
-
-Parse the structured JSON from between `=== SYNC_DOCS_RESULT ===` markers:
-
-```javascript
-// Helper to extract JSON result from agent output
-function parseSyncDocsResult(output) {
-  const match = output.match(/=== SYNC_DOCS_RESULT ===[\s\S]*?({[\s\S]*?})[\s\S]*?=== END_RESULT ===/);
-  if (!match) {
-    throw new Error('No SYNC_DOCS_RESULT found in agent output');
-  }
-  return JSON.parse(match[1]);
-}
-
-const result = parseSyncDocsResult(agentOutput);
-// result now contains: { mode, scope, validation, discovery, issues, fixes, changelog, summary }
-```
-
-### Step 4: Apply Fixes (if apply mode)
-
-If mode is `apply` and fixes array is non-empty:
-
-```javascript
-if (mode === 'apply' && result.fixes.length > 0) {
-  await Task({
-    subagent_type: "next-task:simple-fixer",
-    model: "haiku",
-    prompt: `Apply these documentation fixes:
-${JSON.stringify(result.fixes, null, 2)}
-
-Use the Edit tool to apply each fix. Commit message: "docs: sync documentation with code changes"`
-  });
-}
-```
-
-### Step 5: Present Results
-
-```markdown
-## Documentation Sync ${mode === 'apply' ? 'Applied' : 'Report'}
-
-### Scope
-- Mode: ${mode}
-- Scope: ${scope}
-- Changed files analyzed: ${result.discovery.changedFilesCount}
-- Related docs found: ${result.discovery.relatedDocsCount}
-
-### Validation Results
-
-**Count/Version Validation**
-${result.validation.counts.status === 'ok' ? '[OK] Counts and versions aligned' : `[WARN] ${result.validation.counts.summary.issueCount} issues found`}
-
-**Cross-Platform Validation**
-${result.validation.crossPlatform.status === 'ok' ? '[OK] Cross-platform docs valid' : `[WARN] ${result.validation.crossPlatform.summary.issueCount} issues found`}
-
-### Documentation Issues
-
-${result.issues.length === 0 ? '[OK] No documentation issues detected' :
-  result.issues.map(i => `- **${i.doc}:${i.line || '?'}** (${i.severity}): ${i.suggestion || i.type}`).join('\n')}
-
-### CHANGELOG Status
-
-${result.changelog.status === 'ok' ? '[OK] All changes documented' :
-  `[WARN] ${result.changelog.undocumented.length} commits may need entries:\n${result.changelog.undocumented.map(c => `  - ${c}`).join('\n')}`}
-
-${mode === 'apply' && result.fixes.length > 0 ? `
-### Fixes Applied
-
-${result.fixes.map(f => `- **${f.file}**: ${f.type}`).join('\n')}
-` : ''}
-
-${mode === 'report' && result.fixes.length > 0 ? `
-## Do Next
-
-- [ ] Run \`/sync-docs apply\` to fix ${result.fixes.length} auto-fixable issues
-- [ ] Review flagged items manually
-` : ''}
-```
-
-## Examples
-
-```bash
-# Check what docs might need updates (safe, no changes)
-/sync-docs
-
-# Check docs related to specific path
-/sync-docs report src/auth/
-
-# Apply safe fixes
-/sync-docs apply
-
-# Full codebase scan
-/sync-docs report --scope=all
-
-# For PR preparation
-/sync-docs apply --scope=before-pr
-```
-
-## Integration
-
-This command is also used by `/next-task` Phase 11:
-
-```javascript
-// Phase 11 invocation
-await Task({
-  subagent_type: "sync-docs:sync-docs-agent",
-  prompt: "Sync docs for PR. Mode: apply, Scope: before-pr"
-});
-```
-
-## Error Handling
-
-- **No git**: Exit with "Git required for change detection"
-- **No changed files**: "No changes detected. Use --scope=all to scan entire codebase"
-- **No docs found**: "No documentation files found"
-- **Agent failure**: Report error, suggest manual review

package/plugins/sync-docs/lib/adapter-transforms.js

@@ -1,298 +0,0 @@
-/**
- * Adapter Transform Functions
- *
- * Shared transforms for converting Claude Code plugin content into
- * OpenCode and Codex adapter formats. Used by:
- *   - bin/cli.js (npm installer)
- *   - scripts/dev-install.js (development installer)
- *   - scripts/gen-adapters.js (static adapter generation)
- *
- * @module adapter-transforms
- * @author Avi Fenesh
- * @license MIT
- */
-
-const discovery = require('./discovery');
-
-function transformBodyForOpenCode(content, repoRoot) {
-  content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, '${PLUGIN_ROOT}');
-  content = content.replace(/\$CLAUDE_PLUGIN_ROOT/g, '$PLUGIN_ROOT');
-
-  // Replace .claude/ paths with .opencode/ but preserve platform documentation lists
-  // that enumerate all three platforms (Claude Code: .claude/, OpenCode: .opencode/, Codex: .codex/)
-  // Also preserve {AI_STATE_DIR} references which are platform-agnostic
-  content = content.replace(/\.claude\//g, (match, offset) => {
-    const context = content.substring(Math.max(0, offset - 60), offset + match.length + 10);
-    // Skip if inside a platform enumeration (e.g., "Claude Code: `.claude/`")
-    if (/Claude Code:/.test(context)) return match;
-    return '.opencode/';
-  });
-  content = content.replace(/\.claude'/g, (match, offset) => {
-    const context = content.substring(Math.max(0, offset - 60), offset + match.length + 10);
-    if (/Claude Code:/.test(context)) return match;
-    return ".opencode'";
-  });
-  content = content.replace(/\.claude"/g, (match, offset) => {
-    const context = content.substring(Math.max(0, offset - 60), offset + match.length + 10);
-    if (/Claude Code:/.test(context)) return match;
-    return '.opencode"';
-  });
-  content = content.replace(/\.claude`/g, (match, offset) => {
-    const context = content.substring(Math.max(0, offset - 60), offset + match.length + 10);
-    if (/Claude Code:/.test(context)) return match;
-    return '.opencode`';
-  });
-
-  const plugins = discovery.discoverPlugins(repoRoot);
-  if (plugins.length > 0) {
-    const pluginNames = plugins.join('|');
-    content = content.replace(new RegExp('`(' + pluginNames + '):([a-z-]+)`', 'g'), '`$2`');
-    content = content.replace(new RegExp('(' + pluginNames + '):([a-z-]+)', 'g'), '$2');
-  }
-
-  content = content.replace(
-    /```(\w*)\n([\s\S]*?)```/g,
-    (match, lang, code) => {
-      const langLower = (lang || '').toLowerCase();
-
-      if (langLower === 'bash' || langLower === 'shell' || langLower === 'sh') {
-        if (code.includes('node -e') && code.includes('require(')) {
-          return '*(Bash command with Node.js require - adapt for OpenCode)*';
-        }
-        return match;
-      }
-
-      if (!lang && (code.trim().startsWith('gh ') || code.trim().startsWith('glab ') ||
-          code.trim().startsWith('git ') || code.trim().startsWith('#!'))) {
-        return match;
-      }
-
-      if (code.includes('require(') || code.includes('Task(') ||
-          code.includes('const ') || code.includes('let ') ||
-          code.includes('function ') || code.includes('=>') ||
-          code.includes('async ') || code.includes('await ')) {
-
-        let instructions = '';
-
-        const taskMatches = [...code.matchAll(/(?:await\s+)?Task\s*\(\s*\{[^}]*subagent_type:\s*["'](?:[^"':]+:)?([^"']+)["'][^}]*\}\s*\)/gs)];
-        for (const taskMatch of taskMatches) {
-          const agent = taskMatch[1];
-          instructions += `- Invoke \`@${agent}\` agent\n`;
-        }
-
-        const phaseMatches = code.match(/startPhase\s*\(\s*['"]([^'"]+)['"]\s*\)/g);
-        if (phaseMatches) {
-          for (const pm of phaseMatches) {
-            const phase = pm.match(/['"]([^'"]+)['"]/)[1];
-            instructions += `- Phase: ${phase}\n`;
-          }
-        }
-
-        if (code.includes('AskUserQuestion')) {
-          instructions += '- Use AskUserQuestion tool for user input\n';
-        }
-
-        if (code.includes('EnterPlanMode')) {
-          instructions += '- Use EnterPlanMode for user approval\n';
-        }
-
-        if (instructions) {
-          return instructions;
-        }
-
-        return '*(JavaScript reference - not executable in OpenCode)*';
-      }
-
-      return match;
-    }
-  );
-
-  content = content.replace(/\*\(Reference - adapt for OpenCode\)\*/g, '');
-
-  content = content.replace(/await\s+Task\s*\(\s*\{[\s\S]*?\}\s*\);?/g, (match) => {
-    const agentMatch = match.match(/subagent_type:\s*["'](?:[^"':]+:)?([^"']+)["']/);
-    if (agentMatch) {
-      return `Invoke \`@${agentMatch[1]}\` agent`;
-    }
-    return '*(Task call - use @agent-name syntax)*';
-  });
-
-  content = content.replace(/(?:const|let|var)\s+\{?[^}=\n]+\}?\s*=\s*require\s*\([^)]+\);?/g, '');
-  content = content.replace(/require\s*\(['"][^'"]+['"]\)/g, '');
-
-  if (content.includes('agent')) {
-    const note = `
-> **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\`
-
-`;
-    content = content.replace(/^(---\n[\s\S]*?---\n)/, `$1${note}`);
-  }
-
-  if (content.includes('Master Workflow Orchestrator') && content.includes('No Shortcuts Policy')) {
-    const policySection = `
-## Phase 1: Policy Selection (Built-in Options)
-
-Ask the user these questions using AskUserQuestion:
-
-**Question 1 - Source**: "Where should I look for tasks?"
-- GitHub Issues - Use \`gh issue list\` to find issues
-- GitLab Issues - Use \`glab issue list\` to find issues
-- Local tasks.md - Read from PLAN.md, tasks.md, or TODO.md in the repo
-- Custom - User specifies their own source
-- Other - User describes source, you figure it out
-
-**Question 2 - Priority**: "What type of tasks to prioritize?"
-- All - Consider all tasks, pick by score
-- Bugs - Focus on bug fixes
-- Security - Security issues first
-- Features - New feature development
-
-**Question 3 - Stop Point**: "How far should I take this task?"
-- Merged - Until PR is merged to main
-- PR Created - Stop after creating PR
-- Implemented - Stop after local implementation
-- Deployed - Deploy to staging
-- Production - Full production deployment
-
-After user answers, proceed to Phase 2 with the selected policy.
-
-`;
-    if (content.includes('OpenCode Note')) {
-      content = content.replace(/(Example:.*analyze the codebase\`\n\n)/, `$1${policySection}`);
-    }
-  }
-
-  return content;
-}
-
-function transformCommandFrontmatterForOpenCode(content) {
-  return content.replace(
-    /^---\n([\s\S]*?)^---/m,
-    (match, frontmatter) => {
-      // Parse existing frontmatter
-      const lines = frontmatter.trim().split('\n');
-      const parsed = {};
-      for (const line of lines) {
-        const colonIdx = line.indexOf(':');
-        if (colonIdx > 0) {
-          const key = line.substring(0, colonIdx).trim();
-          const value = line.substring(colonIdx + 1).trim();
-          parsed[key] = value;
-        }
-      }
-
-      // Build OpenCode command frontmatter
-      let opencodeFrontmatter = '---\n';
-      if (parsed.description) opencodeFrontmatter += `description: ${parsed.description}\n`;
-      opencodeFrontmatter += 'agent: general\n';
-      // Don't include argument-hint or allowed-tools (not supported)
-      opencodeFrontmatter += '---';
-      return opencodeFrontmatter;
-    }
-  );
-}
-
-function transformAgentFrontmatterForOpenCode(content, options) {
-  const { stripModels = true } = options || {};
-
-  return content.replace(
-    /^---\n([\s\S]*?)^---/m,
-    (match, frontmatter) => {
-      // Parse existing frontmatter
-      const lines = frontmatter.trim().split('\n');
-      const parsed = {};
-      for (const line of lines) {
-        const colonIdx = line.indexOf(':');
-        if (colonIdx > 0) {
-          const key = line.substring(0, colonIdx).trim();
-          const value = line.substring(colonIdx + 1).trim();
-          parsed[key] = value;
-        }
-      }
-
-      // Build OpenCode frontmatter
-      let opencodeFrontmatter = '---\n';
-      if (parsed.name) opencodeFrontmatter += `name: ${parsed.name}\n`;
-      if (parsed.description) opencodeFrontmatter += `description: ${parsed.description}\n`;
-      opencodeFrontmatter += 'mode: subagent\n';
-
-      // Map model names - only include if NOT stripping
-      if (parsed.model && !stripModels) {
-        const modelMap = {
-          'sonnet': 'anthropic/claude-sonnet-4',
-          'opus': 'anthropic/claude-opus-4',
-          'haiku': 'anthropic/claude-haiku-3-5'
-        };
-        opencodeFrontmatter += `model: ${modelMap[parsed.model] || parsed.model}\n`;
-      }
-
-      // Convert tools to permissions
-      if (parsed.tools) {
-        opencodeFrontmatter += 'permission:\n';
-        const tools = parsed.tools.toLowerCase();
-        opencodeFrontmatter += `  read: ${tools.includes('read') ? 'allow' : 'deny'}\n`;
-        opencodeFrontmatter += `  edit: ${tools.includes('edit') || tools.includes('write') ? 'allow' : 'deny'}\n`;
-        opencodeFrontmatter += `  bash: ${tools.includes('bash') ? 'allow' : 'ask'}\n`;
-        opencodeFrontmatter += `  glob: ${tools.includes('glob') ? 'allow' : 'deny'}\n`;
-        opencodeFrontmatter += `  grep: ${tools.includes('grep') ? 'allow' : 'deny'}\n`;
-      }
-
-      opencodeFrontmatter += '---';
-      return opencodeFrontmatter;
-    }
-  );
-}
-
-function transformSkillBodyForOpenCode(content, repoRoot) {
-  return transformBodyForOpenCode(content, repoRoot);
-}
-
-function transformForCodex(content, options) {
-  const { skillName, description, pluginInstallPath } = options;
-
-  // Escape description for YAML: wrap in double quotes, escape backslashes and internal quotes
-  const escapedDescription = description.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-  const yamlDescription = `"${escapedDescription}"`;
-
-  if (content.startsWith('---')) {
-    // Replace existing frontmatter with Codex-compatible format
-    content = content.replace(
-      /^---\n[\s\S]*?\n---\n/,
-      `---\nname: ${skillName}\ndescription: ${yamlDescription}\n---\n`
-    );
-  } else {
-    // Add new frontmatter
-    content = `---\nname: ${skillName}\ndescription: ${yamlDescription}\n---\n\n${content}`;
-  }
-
-  // Transform PLUGIN_ROOT to actual installed path (or placeholder) for Codex
-  content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginInstallPath);
-  content = content.replace(/\$CLAUDE_PLUGIN_ROOT/g, pluginInstallPath);
-  content = content.replace(/\$\{PLUGIN_ROOT\}/g, pluginInstallPath);
-  content = content.replace(/\$PLUGIN_ROOT/g, pluginInstallPath);
-
-  // Transform AskUserQuestion → request_user_input for Codex native tool
-  content = content.replace(/AskUserQuestion/g, 'request_user_input');
-
-  // Remove multiSelect lines (not supported in Codex)
-  content = content.replace(/^[ \t]*multiSelect:.*\n?/gm, '');
-
-  // Inject Codex note about required id field after request_user_input blocks
-  content = content.replace(
-    /^([ \t]*request_user_input:\s*)$/gm,
-    '$1\n> **Codex**: Each question MUST include a unique `id` field (e.g., `id: "q1"`).'
-  );
-
-  return content;
-}
-
-module.exports = {
-  transformBodyForOpenCode,
-  transformCommandFrontmatterForOpenCode,
-  transformAgentFrontmatterForOpenCode,
-  transformSkillBodyForOpenCode,
-  transformForCodex
-};