agentsys 5.0.0

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

@@ -0,0 +1,154 @@
+---
+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

@@ -0,0 +1,186 @@
+---
+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

@@ -0,0 +1,278 @@
+/**
+ * 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');
+
+  content = content.replace(/\.claude\//g, '.opencode/');
+  content = content.replace(/\.claude'/g, ".opencode'");
+  content = content.replace(/\.claude"/g, '.opencode"');
+  content = content.replace(/\.claude`/g, '.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
+};