agentsys 5.3.0 → 5.3.2

package/.cursor/skills/perf-benchmarker/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: perf-benchmarker
+description: "Use when running performance benchmarks, establishing baselines, or validating regressions with sequential runs. Enforces 60s minimum runs (30s only for binary search) and no parallel benchmarks."
+version: 5.1.0
+argument-hint: "[command] [duration]"
+---
+
+# perf-benchmarker
+
+Run sequential benchmarks with strict duration rules.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Parse Arguments
+
+```javascript
+const args = '$ARGUMENTS'.split(' ').filter(Boolean);
+const command = args.find(a => !a.match(/^\d+$/)) || '';
+const duration = parseInt(args.find(a => a.match(/^\d+$/)) || '60', 10);
+```
+
+## Required Rules
+
+- Benchmarks MUST run sequentially (never parallel).
+- Minimum duration: 60s per run (30s only for binary search).
+- Warmup: 10s minimum before measurement.
+- Re-run anomalies.
+
+## Output Format
+
+```
+command: <benchmark command>
+duration: <seconds>
+warmup: <seconds>
+results: <metrics summary>
+notes: <anomalies or reruns>
+```
+
+## Output Contract
+
+Benchmarks MUST emit a JSON metrics block between markers:
+
+```
+PERF_METRICS_START
+{"scenarios":{"low":{"latency_ms":120},"high":{"latency_ms":450}}}
+PERF_METRICS_END
+```
+
+## Constraints
+
+- No short runs unless binary-search phase.
+- Do not change code while benchmarking.

package/.cursor/skills/perf-code-paths/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: perf-code-paths
+description: "Use when mapping code paths, entrypoints, and likely hot files before profiling."
+version: 5.1.0
+---
+
+# perf-code-paths
+
+Identify likely implementation paths for a performance scenario.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Required Steps
+
+1. Use repo-map if available; otherwise use grep for entrypoints and handlers.
+2. List top candidate files/symbols tied to the scenario.
+3. Include imports/exports or call chains when relevant.
+
+## Output Format
+
+```
+keywords: <comma-separated list>
+paths:
+  - file: <path>
+    symbols: [<symbol1>, <symbol2>]
+    evidence: <short reason>
+```
+
+## Constraints
+
+- Focus only on supported languages (Rust, Java, JS/TS, Go, Python).
+- Keep to the most relevant 10-15 files.

package/.cursor/skills/perf-investigation-logger/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: perf-investigation-logger
+description: "Use when appending structured perf investigation notes and evidence."
+version: 5.1.0
+---
+
+# perf-investigation-logger
+
+Append structured investigation notes to `{state-dir}/perf/investigations/<id>.md`.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Required Content
+
+1. Exact user quotes (verbatim)
+2. Phase summary
+3. Decisions and rationale
+4. Evidence pointers (files, metrics, commands)
+
+## Output Format
+
+```
+## <Phase Name> - <YYYY-MM-DD>
+
+**User Quote:** "<exact quote>"
+
+**Summary**
+- ...
+
+**Evidence**
+- Command: `...`
+- File: `path:line`
+
+**Decision**
+- ...
+```
+
+## Constraints
+
+- Use `AI_STATE_DIR` for state path (default `.claude`).
+- Do not paraphrase user quotes.

package/.cursor/skills/perf-profiler/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: perf-profiler
+description: "Use when profiling CPU/memory hot paths, generating flame graphs, or capturing JFR/perf evidence."
+version: 5.1.0
+argument-hint: "[tool] [command]"
+---
+
+# perf-profiler
+
+Run profiling tools and capture hotspots with evidence.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Parse Arguments
+
+```javascript
+const args = '$ARGUMENTS'.split(' ').filter(Boolean);
+const tool = args[0] || '';
+const command = args.slice(1).join(' ');
+```
+
+## Required Rules
+
+- Verify debug symbols before profiling.
+- Capture file:line for hotspots.
+- Provide flame graph or equivalent output when possible.
+
+## Output Format
+
+```
+tool: <profiler>
+command: <command>
+hotspots:
+  - file:line - reason
+artifacts:
+  - <path to flame graph or profile>
+```
+
+## Constraints
+
+- No profiling without a clear scenario.
+- Keep outputs minimal and evidence-backed.

package/.cursor/skills/perf-theory-gatherer/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: perf-theory-gatherer
+description: "Use when generating performance hypotheses backed by git history and code evidence."
+version: 5.1.0
+---
+
+# perf-theory-gatherer
+
+Generate performance hypotheses for a specific scenario.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Required Steps
+
+1. Review recent git history (scope to relevant paths when possible).
+2. Identify code paths involved in the scenario (repo-map or grep).
+3. Produce up to 5 hypotheses with evidence + confidence.
+
+## Output Format
+
+```
+hypotheses:
+  - id: H1
+    hypothesis: <short description>
+    evidence: <file/path or git change>
+    confidence: low|medium|high
+  - id: H2
+    ...
+```
+
+## Constraints
+
+- MUST check git history before hypothesizing.
+- No optimization suggestions; only hypotheses.
+- Keep to 5 hypotheses maximum.

package/.cursor/skills/perf-theory-tester/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: perf-theory-tester
+description: "Use when running controlled perf experiments to validate hypotheses."
+version: 5.1.0
+---
+
+# perf-theory-tester
+
+Test hypotheses using controlled experiments.
+
+Follow `docs/perf-requirements.md` as the canonical contract.
+
+## Required Steps
+
+1. Confirm baseline is clean.
+2. Apply a single change tied to the hypothesis.
+3. Run 2+ validation passes.
+4. Revert to baseline before the next experiment.
+
+## Output Format
+
+```
+hypothesis: <id>
+change: <summary>
+delta: <metrics>
+verdict: accept|reject|inconclusive
+evidence:
+  - command: <benchmark command>
+  - files: <changed files>
+```
+
+## Constraints
+
+- One change per experiment.
+- No parallel benchmarks.
+- Record evidence for each run.

package/.cursor/skills/repo-mapping/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: repo-mapping
+description: "Use when user asks to \"create repo map\", \"generate repo map\", \"update repo map\", \"repo map status\", or \"map symbols/imports\". Builds and validates an AST-based repo map using ast-grep."
+argument-hint: "[action] [--force]"
+---
+
+# Repo Mapping Skill
+
+Build and maintain a cached AST-based map of repository symbols and imports using ast-grep.
+
+## Parse Arguments
+
+```javascript
+const args = '$ARGUMENTS'.split(' ').filter(Boolean);
+const action = args.find(a => !a.startsWith('--')) || 'status';
+const force = args.includes('--force');
+```
+
+## Primary Responsibilities
+
+1. **Generate map** on demand (`/repo-map init`)
+2. **Update map** incrementally (`/repo-map update`)
+3. **Check status** and staleness (`/repo-map status`)
+4. **Validate output** with the map-validator agent
+
+## Core Data Contract
+
+Repo map is stored in the platform state directory:
+
+- Claude Code: `.claude/repo-map.json`
+- OpenCode: `.opencode/repo-map.json`
+- Codex CLI: `.codex/repo-map.json`
+
+Minimal structure:
+
+```json
+{
+  "version": "1.0.0",
+  "generated": "2026-01-25T12:00:00Z",
+  "updated": "2026-01-25T12:05:00Z",
+  "git": { "commit": "abc123", "branch": "main" },
+  "project": { "languages": ["typescript", "python"] },
+  "stats": { "totalFiles": 142, "totalSymbols": 847 },
+  "files": {
+    "src/auth/login.ts": {
+      "hash": "deadbeef1234abcd",
+      "language": "typescript",
+      "symbols": { "exports": [], "functions": [], "classes": [] },
+      "imports": [ { "source": "./utils", "kind": "named" } ]
+    }
+  }
+}
+```
+
+## Behavior Rules
+
+- **Never** run ast-grep without user approval if it is not installed
+- **Never** install dependencies without explicit user consent
+- **Always** validate map output with `map-validator` after init/update
+- **Prefer** incremental update unless map is stale or history rewritten
+
+## When to Suggest Repo Map
+
+If a user asks for drift detection, documentation alignment, or repo analysis and repo-map is missing:
+
+```
+Repo map not found. For better analysis, run:
+  /repo-map init
+```
+
+## Staleness Signals
+
+- Map commit not found (rebased)
+- Branch changed
+- Git hooks marked stale
+- Commits behind HEAD
+
+## Output Expectations
+
+Keep outputs concise:
+
+- **init/update**: file count, symbol count, commit, warnings
+- **status**: staleness, commits behind, last updated

package/.cursor/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.1.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