agentsys 5.0.0

package/plugins/sync-docs/skills/sync-docs/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: sync-docs
+description: "Sync documentation with code. Use when user asks to update docs, check docs, fix stale documentation, update changelog, or after code changes."
+version: 5.0.0
+argument-hint: "[report|apply] [--scope=all|recent|before-pr] [--include-undocumented]"
+allowed-tools: Bash(git:*), Read, Grep, Glob
+---
+
+# sync-docs
+
+Unified skill for syncing documentation with code state. Combines discovery, analysis, and CHANGELOG update into a single workflow.
+
+## Parse Arguments
+
+```javascript
+const args = '$ARGUMENTS'.split(' ').filter(Boolean);
+const mode = args.find(a => ['report', 'apply'].includes(a)) || 'report';
+const scope = args.find(a => a.startsWith('--scope='))?.split('=')[1] || 'recent';
+const includeUndocumented = args.includes('--include-undocumented');
+```
+
+## Quick Start - Agent Instructions
+
+**Step 1**: Get changed files (use Bash):
+```bash
+# Recent changes (default scope)
+git diff --name-only origin/main..HEAD 2>/dev/null || git diff --name-only HEAD~5..HEAD
+
+# Or for all files
+git ls-files '*.md'
+```
+
+**Step 2**: Find docs that reference changed files (use Grep):
+- Search for filenames, function names, class names in `*.md` files
+- Check README.md, CHANGELOG.md, docs/*.md
+
+**Step 3**: Analyze each doc for issues:
+- Version mismatches (compare doc versions to package.json)
+- Removed exports (symbols in docs but not in code)
+- Outdated code examples
+- Import path changes
+
+**Step 4**: Check CHANGELOG:
+- Look for `## [Unreleased]` section
+- Compare recent commit messages to CHANGELOG entries
+
+**Step 5**: If repo-map exists (`{stateDir}/repo-map.json` - platform state directory):
+- Load it to get accurate export list
+- Find exports not mentioned in any documentation
+- Report as `undocumented-export` issues
+
+## Input
+
+Arguments: `[report|apply] [--scope=all|recent|before-pr] [--include-undocumented]`
+
+- **Mode**: `report` (default) or `apply`
+- **Scope**:
+  - `recent` (default): Files changed since last commit to main
+  - `all`: Scan all docs against all code
+  - `before-pr`: Files in current branch, optimized for /next-task Phase 11
+- **--include-undocumented**: Find exports not mentioned in any docs (uses repo-map)
+
+## Architecture
+
+This skill orchestrates all documentation sync operations:
+
+```
+sync-docs skill
+    |-- Phase 1: Detect project context
+    |-- Phase 2: Find related docs (lib/collectors/docs-patterns)
+    |-- Phase 3: Analyze issues
+    |-- Phase 3.5: Find undocumented exports (repo-map integration)
+    |-- Phase 4: Check CHANGELOG
+    |-- Phase 5: Return structured results
+```
+
+The skill MUST NOT apply fixes directly. It returns structured data for the orchestrator to decide what to do.
+
+---
+
+## Implementation Details (Reference)
+
+The sections below describe the internal JavaScript implementation for reference only. Agents should follow the Quick Start instructions above using Bash, Read, and Grep tools.
+
+### Phase 1: Detect Project Context
+
+Detect project type and find documentation files.
+
+### Phase 1.5: Ensure Repo-Map
+
+Before analyzing issues, ensure repo-map is available for accurate symbol detection:
+
+```javascript
+const { ensureRepoMap } = require('../../lib/collectors/docs-patterns');
+
+// Try to get repo-map (will auto-init if ast-grep available)
+const repoMapStatus = await ensureRepoMap({
+  cwd: process.cwd(),
+  askUser: async (opts) => {
+    // Use AskUserQuestion tool
+    const answer = await AskUserQuestion({
+      question: opts.question,
+      header: opts.header,
+      options: opts.options
+    });
+    return answer;
+  }
+});
+
+if (repoMapStatus.installInstructions) {
+  // User wants to install ast-grep, show instructions
+  console.log(repoMapStatus.installInstructions);
+  // Wait for user to confirm installation, then retry
+}
+
+// repoMapStatus.available indicates if repo-map can be used
+// repoMapStatus.fallbackReason explains why if not available
+```
+
+**User Interaction (only if ast-grep not installed):**
+
+Use AskUserQuestion:
+- Header: "ast-grep Required"
+- Question: "ast-grep not found. Install for better doc sync accuracy?"
+- Options:
+  - "Yes, show instructions" - Display platform-specific install instructions
+  - "No, use regex fallback" - Continue with less accurate regex-based detection
+
+If user declines or repo-map unavailable, the system falls back to regex-based export detection automatically.
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+
+// Detect documentation files
+const docFiles = [];
+const commonDocs = ['README.md', 'CHANGELOG.md', 'CONTRIBUTING.md', 'docs/**/*.md'];
+
+for (const pattern of commonDocs) {
+  // Use glob to find matching files
+  const matches = glob.sync(pattern, { cwd: process.cwd() });
+  docFiles.push(...matches);
+}
+
+// Detect project type from package.json, Cargo.toml, go.mod, etc.
+let projectType = 'unknown';
+if (fs.existsSync('package.json')) projectType = 'javascript';
+else if (fs.existsSync('Cargo.toml')) projectType = 'rust';
+else if (fs.existsSync('go.mod')) projectType = 'go';
+else if (fs.existsSync('pyproject.toml') || fs.existsSync('setup.py')) projectType = 'python';
+
+const context = { docFiles, projectType };
+```
+
+This phase gathers context about the project without requiring external scripts.
+
+## Phase 2: Find Related Documentation
+
+Use lib/collectors/docs-patterns to find docs related to changed files:
+
+```javascript
+// Use relative path from skill directory to plugin lib
+// Path: skills/sync-docs/ -> ../../lib
+const { collectors } = require('../../lib');
+const docsPatterns = collectors.docsPatterns;
+
+// Get changed files based on scope
+let changedFiles;
+if (scope === 'all') {
+  changedFiles = await exec("git ls-files '*.js' '*.ts' '*.py' '*.go' '*.rs' '*.java'");
+} else if (scope === 'before-pr') {
+  changedFiles = await exec("git diff --name-only origin/main..HEAD");
+} else {
+  // recent (default): get the default branch name
+  let base = 'main';
+  try {
+    const { stdout: refOutput } = await exec("git symbolic-ref refs/remotes/origin/HEAD");
+    // Parse "refs/remotes/origin/branch-name" to extract "branch-name"
+    const rawBase = refOutput.trim().split('/').pop();
+    // Sanitize branch name to prevent shell injection (only allow alphanumeric, dash, underscore, dot)
+    if (/^[a-zA-Z0-9._-]+$/.test(rawBase)) {
+      base = rawBase;
+    }
+  } catch (e) {
+    base = 'main'; // fallback to main if symbolic-ref fails
+  }
+  changedFiles = await exec(`git diff --name-only origin/${base}..HEAD 2>/dev/null || git diff --name-only HEAD~5..HEAD`);
+}
+
+// Find related docs
+const relatedDocs = docsPatterns.findRelatedDocs(changedFiles.split('\n').filter(Boolean), {
+  cwd: process.cwd()
+});
+```
+
+## Phase 3: Analyze Documentation Issues
+
+For each related doc, check for issues:
+
+```javascript
+const allIssues = [];
+
+for (const { doc, referencedFile } of relatedDocs) {
+  const issues = docsPatterns.analyzeDocIssues(doc, referencedFile, {
+    cwd: process.cwd()
+  });
+
+  issues.forEach(issue => {
+    allIssues.push({
+      ...issue,
+      doc,
+      referencedFile
+    });
+  });
+}
+```
+
+Issue types detected:
+- `outdated-version`: Version string doesn't match current
+- `removed-export`: References removed symbol
+- `code-example`: Code example may be outdated
+- `import-path`: Import path changed
+- `undocumented-export`: Export exists in code but not mentioned in any docs (requires repo-map)
+
+## Phase 4: Check CHANGELOG
+
+```javascript
+const changelogResult = docsPatterns.checkChangelog(changedFiles.split('\n').filter(Boolean), {
+  cwd: process.cwd()
+});
+
+// changelogResult contains:
+// - exists: boolean
+// - hasUnreleased: boolean
+// - documented: string[]
+// - undocumented: string[]
+// - suggestion: string | null
+```
+
+## Phase 5: Return Structured Results
+
+Combine all results into a single output:
+
+```json
+{
+  "mode": "report|apply",
+  "scope": "recent|all|before-pr|path",
+  "context": {
+    "projectType": "javascript|python|rust|go|unknown",
+    "docFiles": ["README.md", "CHANGELOG.md"]
+  },
+  "repoMap": {
+    "available": true,
+    "fallbackReason": null,
+    "stats": { "files": 142, "symbols": 847 }
+  },
+  "discovery": {
+    "changedFilesCount": 5,
+    "relatedDocsCount": 3,
+    "relatedDocs": [
+      { "doc": "README.md", "referencedFile": "src/api.js", "referenceTypes": ["filename", "import"] }
+    ]
+  },
+  "issues": [
+    {
+      "type": "outdated-version",
+      "severity": "low",
+      "doc": "README.md",
+      "line": 15,
+      "current": "1.0.0",
+      "expected": "1.1.0",
+      "autoFix": true,
+      "suggestion": "Update version from 1.0.0 to 1.1.0"
+    }
+  ],
+  "undocumentedExports": [
+    {
+      "type": "undocumented-export",
+      "severity": "low",
+      "file": "src/utils.js",
+      "name": "formatDate",
+      "line": 25,
+      "certainty": "MEDIUM",
+      "suggestion": "Export 'formatDate' in src/utils.js is not mentioned in any documentation"
+    }
+  ],
+  "fixes": [
+    {
+      "file": "README.md",
+      "type": "update-version",
+      "line": 15,
+      "search": "1.0.0",
+      "replace": "1.1.0"
+    }
+  ],
+  "changelog": {
+    "exists": true,
+    "hasUnreleased": true,
+    "undocumented": ["feat: add new feature"],
+    "status": "needs-update|ok"
+  },
+  "summary": {
+    "issueCount": 3,
+    "fixableCount": 2,
+    "bySeverity": { "high": 0, "medium": 1, "low": 2 }
+  }
+}
+```
+
+## Output Format
+
+Output the result as JSON between markers:
+
+```
+=== SYNC_DOCS_RESULT ===
+{JSON output}
+=== END_RESULT ===
+```
+
+## Usage by Agents
+
+### sync-docs-agent (standalone /sync-docs)
+
+```
+Skill: sync-docs
+Args: report --scope=recent
+```
+
+### /next-task Phase 11
+
+```
+Skill: sync-docs
+Args: apply --scope=before-pr
+```
+
+The orchestrator receives the structured result and spawns `simple-fixer` if fixes are needed.
+
+## Constraints
+
+1. **Report mode by default** - Never modify files unless explicitly in apply mode
+2. **Structured output** - Always return JSON between markers
+3. **No direct fixes** - Return fix instructions, let orchestrator decide
+4. **Preserve formatting** - Fix suggestions should preserve existing style
+5. **Safe changes only** - Only auto-fixable issues get fix entries
+
+## Error Handling
+
+- **No git**: Exit with error "Git required for change detection"
+- **No docs found**: Report empty docFiles, suggest creating README.md
+- **No changed files**: Report scope as "empty", suggest using --scope=all

package/scripts/bump-version.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Version Bump Tool
+ *
+ * Usage:
+ *   node scripts/bump-version.js <version>
+ *   node scripts/bump-version.js 3.7.3
+ *   node scripts/bump-version.js 3.7.3-rc.1
+ *
+ * Delegates to `npm version` which:
+ * 1. Updates package.json + package-lock.json (npm handles natively)
+ * 2. Triggers the `version` lifecycle script (stamp-version.js)
+ *    which stamps all plugin.json, marketplace.json, and site/content.json
+ *
+ * Uses --no-git-tag-version so existing release workflow controls commits/tags.
+ */
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+const discovery = require(path.join(__dirname, '..', 'lib', 'discovery'));
+
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/;
+
+// Discover plugins from filesystem (for help text)
+const PLUGIN_NAMES = discovery.discoverPlugins(path.join(__dirname, '..'));
+
+function main(args) {
+  if (!args) args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log(`
+Version Bump Tool
+
+Usage:
+  node scripts/bump-version.js <version>
+
+Examples:
+  node scripts/bump-version.js 3.7.3        # Stable release
+  node scripts/bump-version.js 3.7.3-rc.1   # Release candidate
+  node scripts/bump-version.js 3.8.0-beta.1 # Beta release
+
+Files updated (via npm version + stamp-version.js):
+  - package.json + package-lock.json (npm native)
+  - .claude-plugin/plugin.json
+  - .claude-plugin/marketplace.json (all occurrences)
+  - plugins/*/.claude-plugin/plugin.json (${PLUGIN_NAMES.length} plugins)
+  - site/content.json (meta.version)
+`);
+    return 0;
+  }
+
+  const newVersion = args[0];
+
+  if (!VERSION_PATTERN.test(newVersion)) {
+    console.error(`[ERROR] Invalid version format: ${newVersion}`);
+    console.error('Expected: X.Y.Z or X.Y.Z-prerelease (e.g., 3.7.3, 3.7.3-rc.1)');
+    return 1;
+  }
+
+  console.log(`\nBumping version to: ${newVersion}\n`);
+
+  try {
+    // npm version updates package.json + package-lock.json, then triggers
+    // the "version" lifecycle script which runs stamp-version.js.
+    // Version is validated by VERSION_PATTERN above (safe for shell use).
+    execFileSync('npm', ['version', newVersion, '--no-git-tag-version'], {
+      cwd: path.join(__dirname, '..'),
+      stdio: 'inherit'
+    });
+  } catch (err) {
+    console.error(`[ERROR] npm version failed: ${err.message}`);
+    return 1;
+  }
+
+  console.log(`
+[OK] Version bump complete!
+
+Next steps:
+  1. Update CHANGELOG.md with release notes
+  2. git add -A && git commit -m "chore: release v${newVersion}"
+  3. git tag v${newVersion}
+  4. git push origin main v${newVersion}
+`);
+  return 0;
+}
+
+if (require.main === module) {
+  const code = main();
+  if (typeof code === 'number') process.exit(code);
+}
+
+module.exports = { main };

package/scripts/check-hardcoded-paths.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * Check for Hardcoded Platform Paths
+ * Scans plugins for hardcoded .claude/, .opencode/, .codex/ paths
+ *
+ * CRITICAL: Per CLAUDE.md cross-platform requirement - all 3 platforms must work
+ *
+ * Usage: node scripts/check-hardcoded-paths.js
+ * Exit code: 0 if clean, 1 if issues found
+ *
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+// Patterns to detect hardcoded platform paths
+const HARDCODED_PATTERNS = [
+  {
+    pattern: /\.claude\/(?!.*\(example\)|.*for example|.*Platform|.*State directory)/,
+    platform: '.claude/',
+    severity: 'ERROR'
+  },
+  {
+    pattern: /\.opencode\/(?!.*\(example\)|.*for example|.*Platform|.*State directory)/,
+    platform: '.opencode/',
+    severity: 'ERROR'
+  },
+  {
+    pattern: /\.codex\/(?!.*\(example\)|.*for example|.*Platform|.*State directory)/,
+    platform: '.codex/',
+    severity: 'ERROR'
+  }
+];
+
+// Files to exclude from checks (docs, examples, research)
+const EXCLUDE_PATTERNS = [
+  /RESEARCH\.md$/,
+  /CLAUDE\.md$/,
+  /AGENTS\.md$/,
+  /README\.md$/,
+  /INSTALLATION\.md$/,
+  /CROSS_PLATFORM\.md$/,
+  /ARCHITECTURE\.md$/,
+  /examples?\//,
+  /\.git\//,
+  /node_modules\//,
+  /__tests__\//,
+  /\.json$/,
+  // Enhance skills document platform differences - OK to have hardcoded paths in docs
+  /plugins\/enhance\/skills\/.*\/SKILL\.md$/
+];
+
+// Lines that are OK to have hardcoded paths (documentation examples)
+const SAFE_CONTEXTS = [
+  'State stored in',
+  'State directory:',
+  'example',
+  'Example',
+  'Platform',
+  '| State Dir |',
+  'State Dir |',
+  'detected by',
+  'Detected by',
+  'Override with',
+  'Personal:',
+  'Project:',
+  'User settings',
+  'Project settings',
+  'Local settings',
+  '| Claude Code |',
+  '| OpenCode |',
+  '| Codex |',
+  'Claude Code:',
+  'OpenCode:',
+  'Codex CLI:',
+  'Codex:',
+  "Don't hardcode",
+  'Support ',
+  '~/.claude/',
+  '~/.config/opencode/',
+  '~/.opencode/', // legacy (pre-XDG) path; keep as safe context for historical docs
+  '~/.codex/',
+  'MCP in',
+  'or `~/',
+  '$CLAUDE_PROJECT_DIR'
+];
+
+function shouldExcludeFile(filePath) {
+  // Normalize path separators for cross-platform regex matching
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  return EXCLUDE_PATTERNS.some(pattern => pattern.test(normalizedPath));
+}
+
+function isSafeContext(line) {
+  return SAFE_CONTEXTS.some(ctx => line.includes(ctx));
+}
+
+function scanFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+  const issues = [];
+
+  lines.forEach((line, index) => {
+    // Skip if line is in safe context
+    if (isSafeContext(line)) {
+      return;
+    }
+
+    HARDCODED_PATTERNS.forEach(({ pattern, platform, severity }) => {
+      if (pattern.test(line)) {
+        issues.push({
+          file: path.relative(REPO_ROOT, filePath),
+          line: index + 1,
+          platform,
+          severity,
+          content: line.trim()
+        });
+      }
+    });
+  });
+
+  return issues;
+}
+
+function scanDirectory(dir, issues = []) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (shouldExcludeFile(fullPath)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      scanDirectory(fullPath, issues);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const fileIssues = scanFile(fullPath);
+      issues.push(...fileIssues);
+    }
+  }
+
+  return issues;
+}
+
+function formatIssue(issue) {
+  return `${issue.severity}: ${issue.file}:${issue.line}
+  Hardcoded path: ${issue.platform}
+  Line: ${issue.content}
+  Fix: Use platform-aware state directory variable (${issue.platform === '.claude/' ? 'STATE_DIR or stateDir' : 'stateDir'})
+`;
+}
+
+// Main execution
+if (require.main === module) {
+  console.log('[OK] Scanning for hardcoded platform paths...\n');
+
+  const pluginsDir = path.join(REPO_ROOT, 'plugins');
+  const issues = scanDirectory(pluginsDir);
+
+  if (issues.length === 0) {
+    console.log('[OK] No hardcoded platform paths found\n');
+    console.log('All files use platform-aware state directory variables.');
+    process.exit(0);
+  }
+
+  console.error(`[ERROR] Found ${issues.length} hardcoded platform path(s):\n`);
+
+  issues.forEach(issue => {
+    console.error(formatIssue(issue));
+  });
+
+  console.error(`
+CLAUDE.md Critical Rule:
+> 3 platforms: Claude Code + OpenCode + Codex - ALL must work
+
+Fix guide:
+1. Replace hardcoded paths with platform-aware variables:
+   - In agents/commands: Use workflowState.getStateDir()
+   - In prompts: Use \${stateDir} or \${STATE_DIR} template variables
+
+2. Examples:
+   BAD:  await Task({ prompt: "State file: .claude/flow.json" });
+   GOOD: await Task({ prompt: \`State file: \${stateDir}/flow.json\` });
+
+   BAD:  State files in .claude/tasks.json
+   GOOD: State files in {stateDir}/tasks.json
+
+See: checklists/cross-platform-compatibility.md
+`);
+
+  process.exit(1);
+}
+
+module.exports = { scanDirectory, scanFile, HARDCODED_PATTERNS };