agentsys 5.0.0

package/plugins/audit-project/commands/audit-project.md

@@ -0,0 +1,336 @@
+---
+description: Multi-agent code review with iterative improvement
+codex-description: 'Use when user asks to "review my code", "check for issues", "run code review", "analyze PR quality". Multi-agent iterative review that loops until all critical/high issues are resolved.'
+argument-hint: "[scope] [--recent] [--domain AGENT] [--quick] [--create-tech-debt] [--resume]"
+allowed-tools: Bash(git:*), Bash(node:*), Read, Write, Edit, Glob, Grep, Task, AskUserQuestion
+---
+
+# /audit-project - Multi-Agent Code Review
+
+Comprehensive code review using specialized AI agents with iterative improvement.
+
+## Quick Reference
+
+| Phase | Description | Details |
+|-------|-------------|---------|
+| 1 | Context & Agent Selection | This file |
+| 2 | Multi-Agent Review | See `audit-project-agents.md` |
+| 3-4 | Tech Debt & Fixes | This file |
+| 5-6 | Verification & Iteration | This file |
+| 7 | Completion Report | This file |
+| 8 | GitHub Issues | See `audit-project-github.md` |
+
+## Arguments
+
+Parse from $ARGUMENTS:
+- **Scope**: Path to review (default: `.`) or `--recent` (last 5 commits only)
+- **--domain AGENT**: Review with specific agent only (e.g., `--domain security`)
+- **--quick**: Single pass, no iteration (fast feedback)
+- **--create-tech-debt**: Force create/update TECHNICAL_DEBT.md
+- **--resume**: Resume from existing review queue file
+
+### Resume Mode
+
+If `--resume` is provided, reuse the most recent review queue in the platform state dir.
+Otherwise create a new queue file. See `audit-project-agents.md` for queue handling.
+
+## Phase 1: Context Gathering
+
+### Platform Detection
+
+```bash
+# Get plugin root using Node.js helper
+PLUGIN_ROOT=$(node -e "const { getPluginRoot } = require('@agentsys/lib/cross-platform'); const root = getPluginRoot('audit-project'); if (!root) { console.error('Error: Could not locate audit-project plugin root'); process.exit(1); } console.log(root);")
+PLATFORM=$(node "$PLUGIN_ROOT/lib/platform/detect-platform.js")
+TOOLS=$(node "$PLUGIN_ROOT/lib/platform/verify-tools.js")
+
+PROJECT_TYPE=$(echo $PLATFORM | jq -r '.projectType')
+PACKAGE_MGR=$(echo $PLATFORM | jq -r '.packageManager')
+
+# Detect framework
+FRAMEWORK="unknown"
+if [ "$PROJECT_TYPE" = "nodejs" ]; then
+  [ -n "$(jq -e '.dependencies.react' package.json 2>/dev/null)" ] && FRAMEWORK="react"
+  [ -n "$(jq -e '.dependencies.express' package.json 2>/dev/null)" ] && FRAMEWORK="express"
+elif [ "$PROJECT_TYPE" = "python" ]; then
+  grep -q "django" requirements.txt 2>/dev/null && FRAMEWORK="django"
+  grep -q "fastapi" requirements.txt 2>/dev/null && FRAMEWORK="fastapi"
+fi
+
+RESUME_MODE=$([ "${ARGUMENTS}" != "${ARGUMENTS%--resume*}" ] && echo "true" || echo "false")
+```
+
+### Project Analysis
+
+```bash
+FILE_COUNT=$(git ls-files | wc -l)
+TEST_FILES=$(git ls-files | grep -E '(test|spec)\.' | wc -l)
+HAS_TESTS=$( [ "$TEST_FILES" -gt 0 ] && echo "true" || echo "false" )
+HAS_DB=$(grep -rq -E "(Sequelize|Prisma|TypeORM)" . 2>/dev/null && echo "true" || echo "false")
+HAS_API=$(grep -rq -E "(express|fastify|@nestjs)" . 2>/dev/null && echo "true" || echo "false")
+HAS_FRONTEND=$( [ "$(git ls-files | grep -E '\.(tsx|jsx|vue|svelte)$' | wc -l)" -gt 0 ] && echo "true" || echo "false" )
+HAS_BACKEND=$(grep -rq -E "(express|fastify|@nestjs|koa|hapi)" . 2>/dev/null && echo "true" || echo "false")
+if [ -d ".github/workflows" ] || [ -f ".gitlab-ci.yml" ] || [ -f ".circleci/config.yml" ] || \
+  [ -f "Jenkinsfile" ] || [ -f ".travis.yml" ] || [ -f "azure-pipelines.yml" ] || \
+  [ -f "bitbucket-pipelines.yml" ]; then
+  HAS_CICD="true"
+else
+  HAS_CICD="false"
+fi
+```
+
+### Agent Selection
+
+**Always Active:**
+- `code-quality-reviewer`: Code quality, error handling, maintainability
+- `security-expert`: Security vulnerabilities, auth, input validation
+- `performance-engineer`: Performance bottlenecks, algorithms, memory
+- `test-quality-guardian`: Test coverage and quality (reports missing tests)
+
+**Conditional:**
+- `architecture-reviewer`: Design patterns (if `FILE_COUNT > 50`)
+- `database-specialist`: Query optimization (if `HAS_DB=true`)
+- `api-designer`: REST best practices (if `HAS_API=true`)
+- `frontend-specialist`: Component design (if `HAS_FRONTEND=true`)
+- `backend-specialist`: Service and domain logic (if `HAS_BACKEND=true`)
+- `devops-reviewer`: CI/CD config (if `HAS_CICD=true`)
+
+## Phase 2: Multi-Agent Review
+
+See `audit-project-agents.md` for detailed agent coordination.
+
+**Review queue:** Write findings to a temporary queue file in the platform state dir and keep it updated until all issues are resolved. Remove the file when the queue is empty.
+
+### Finding Format (Required)
+
+Every finding MUST include:
+- **File:Line**: Exact location (e.g., `src/auth/session.ts:42`)
+- **Severity**: critical | high | medium | low
+- **Category**: From agent domain
+- **Description**: What's wrong and why
+- **Code Quote**: 1-3 lines showing issue
+- **Suggested Fix**: Specific remediation
+- **Effort**: small | medium | large
+
+### Example Finding
+
+```markdown
+### Finding: Unsafe SQL Query
+**Agent**: security-expert
+**File**: src/api/users.ts:87
+**Severity**: critical
+**Code**:
+```typescript
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+```
+**Fix**: Use parameterized queries.
+**Effort**: small
+```
+
+## Phase 3: Tech Debt Documentation
+
+If TECHNICAL_DEBT.md exists or `--create-tech-debt`:
+
+```markdown
+# Technical Debt
+
+Last updated: $(date -I)
+
+## Summary
+**Total Issues**: X | Critical: Y | High: Z | Medium: A | Low: B
+
+## Critical Issues
+[Grouped by severity with file:line, description, fix, effort]
+
+## Progress Tracking
+- [ ] Issue 1
+- [ ] Issue 2
+```
+
+## Phase 4: Automated Fixes
+
+### Fix Strategy
+
+1. **Auto-fixable** (lint, formatting): Apply directly
+2. **Manual fix** (code logic): Implement suggested fix
+3. **Design decision required**: Flag as blocked and report to user
+4. **False positive**: Mark and remove from review queue
+
+### Fix Order
+
+1. Critical severity first
+2. Then high → medium → low
+3. Then by effort (small → large)
+4. Then batch by file
+
+## Phase 5: Verification
+
+```bash
+# Run tests
+[ -n "$TEST_CMD" ] && $TEST_CMD
+TEST_STATUS=$?
+
+# Run linter
+[ -n "$LINT_CMD" ] && $LINT_CMD
+LINT_STATUS=$?
+
+# Run build
+[ -n "$BUILD_CMD" ] && $BUILD_CMD
+BUILD_STATUS=$?
+
+# Overall status
+VERIFICATION_PASSED=$([ $TEST_STATUS -eq 0 ] && [ $LINT_STATUS -eq 0 ] && [ $BUILD_STATUS -eq 0 ] && echo "true" || echo "false")
+```
+
+### Handle Failures
+
+If verification fails:
+1. Review recent changes (`git diff`)
+2. Identify breaking fix
+3. Rollback: `git restore <file>`
+4. Document as "fix caused regression"
+
+## Phase 6: Iteration
+
+```javascript
+const initialReview = /* results from Phase 2 review */;
+const initialIssues = Array.isArray(initialReview?.issues) ? initialReview.issues : [];
+let iteration = 1;
+let remainingIssues = initialIssues;
+
+while (remainingIssues.length > 0) {
+  const fixResult = applyFixes(remainingIssues);
+
+  const verifyResult = runVerification();
+  if (!verifyResult.passed) {
+    rollbackFailed(fixResult);
+  }
+
+  const reReviewResult = reReview(fixResult.changedFiles);
+  remainingIssues = reReviewResult.issues;
+
+  if (remainingIssues.length === 0) {
+    console.log("[OK] Zero issues remaining!");
+    break;
+  }
+
+  iteration++;
+}
+```
+
+### Quick Mode
+
+If `--quick` flag: Single pass, findings only, no fixes.
+
+## Phase 6.5: Decision Gate (User)
+
+After each iteration (or after re-review if issues remain), report the queue state and ask the user what to do next.
+
+```javascript
+const openCount = remainingIssues.length;
+console.log(`Open issues: ${openCount}`);
+console.log(`Queue file: ${reviewQueuePath}`); // set in Phase 2 (audit-project-agents)
+
+const decision = await AskUserQuestion({
+  questions: [{
+    header: "Audit Decision",
+    question: "Review queue still open. What next?",
+    options: [
+      { label: "Continue review", description: "Run another iteration" },
+      { label: "Create issues", description: "Stop and create issues" },
+      { label: "Update tech debt", description: "Stop and update TECHNICAL_DEBT.md" },
+      { label: "Leave queue", description: "Stop and keep queue for resume" }
+    ],
+    multiSelect: false
+  }]
+});
+
+const choice = decision[0];
+if (choice === 'Continue review') {
+  // continue loop
+} else if (choice === 'Create issues') {
+  // Create issues and remove queue file
+} else if (choice === 'Update tech debt') {
+  // Update TECHNICAL_DEBT.md and remove queue file
+} else if (choice === 'Leave queue') {
+  // Leave queue file for --resume
+  break;
+}
+```
+
+## Phase 7: Completion Report
+
+```markdown
+# Project Review Complete
+
+**Scope**: ${SCOPE} | **Framework**: ${FRAMEWORK}
+**Iterations**: ${iteration} | **Duration**: ${duration}
+
+## Summary
+**Issues Found**: ${initialCount}
+**Issues Fixed**: ${fixedCount}
+**Remaining**: ${remainingCount}
+
+## By Severity
+- Critical: ${criticalFound} → ${criticalRemaining}
+- High: ${highFound} → ${highRemaining}
+- Medium: ${mediumFound} → ${mediumRemaining}
+- Low: ${lowFound} → ${lowRemaining}
+
+## Verification
+- Tests: [OK]/[FAIL]
+- Linter: [OK]/[FAIL]
+- Build: [OK]/[FAIL]
+
+## Files Changed
+${FILE_COUNT} files modified
+
+## Remaining Issues
+[List of issues needing attention]
+```
+
+## Phase 8: GitHub Issue Creation
+
+See `audit-project-github.md` for:
+- Creating GitHub issues for deferred items
+- Security issue handling (no public issues)
+- TECHNICAL_DEBT.md cleanup
+
+## Error Handling
+
+### No Framework Detected
+```
+Framework detection failed, using generic patterns.
+```
+
+### No Tests Available
+```
+No test suite detected. Skipping test-quality-guardian.
+```
+
+### All Agents Failed
+```
+ERROR: All review agents failed.
+Try: --recent or specific path for smaller scope.
+```
+
+## Usage Examples
+
+```bash
+/audit-project                    # Full review
+/audit-project --recent           # Last 5 commits only
+/audit-project src/api            # Specific path
+/audit-project --domain security  # Security audit only
+/audit-project --quick            # Fast feedback, no fixes
+/audit-project --create-tech-debt # Force tech debt file
+```
+
+## Success Criteria
+
+- [OK] All agents completed review
+- [OK] Evidence-based findings (file:line provided)
+- [OK] Critical issues fixed or documented
+- [OK] Verification passes
+- [OK] TECHNICAL_DEBT.md updated (if enabled)
+
+Begin Phase 1 now.

package/plugins/audit-project/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
+};