agentsys 5.0.3 → 5.2.0

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

@@ -1,458 +0,0 @@
----
-description: "Use when coordinating multi-agent review passes in /audit-project. Details agent specialization, file filtering, and review queue handling."
-codex-description: "Use when coordinating multi-agent review passes in /audit-project. Details agent specialization, file filtering, and review queue handling."
----
-
-# Phase 2: Multi-Agent Review - Reference
-
-This file contains detailed agent coordination for `/audit-project`.
-
-**Parent document**: `audit-project.md`
-
-**Review Pass Definitions**: See `orchestrate-review` skill for canonical pass definitions (core + conditional). This command uses the same review passes but detects signals from project structure (not just changed files).
-
-## Agent Specialization
-
-### File Filtering by Agent
-
-Each agent reviews only relevant files:
-
-| Agent | File Patterns |
-|-------|--------------|
-| code-quality-reviewer | All source files (includes error handling) |
-| security-expert | Auth, validation, API endpoints, config |
-| performance-engineer | Hot paths, algorithms, loops, queries |
-| test-quality-guardian | Test files + missing-test signals |
-| architecture-reviewer | Cross-module boundaries, core packages |
-| database-specialist | Models, queries, migrations |
-| api-designer | API routes, controllers, handlers |
-| frontend-specialist | Components, state management |
-| backend-specialist | Services, domain logic, queues |
-| devops-reviewer | CI/CD configs, Dockerfiles |
-
-## Review Queue File
-
-Create a temporary review queue file in the platform state dir. Review passes append JSONL or return JSON for the parent to write.
-
-```javascript
-const path = require('path');
-const fs = require('fs');
-const { getPluginRoot } = require('@agentsys/lib/cross-platform');
-const pluginRoot = getPluginRoot('audit-project');
-if (!pluginRoot) { console.error('Error: Could not locate audit-project plugin root'); process.exit(1); }
-const { getStateDirPath } = require(`${pluginRoot}/lib/platform/state-dir.js`);
-
-const stateDirPath = getStateDirPath(process.cwd());
-if (!fs.existsSync(stateDirPath)) {
-  fs.mkdirSync(stateDirPath, { recursive: true });
-}
-
-function findLatestQueue(dirPath) {
-  const files = fs.readdirSync(dirPath)
-    .filter(name => name.startsWith('review-queue-') && name.endsWith('.json'))
-    .map(name => ({
-      name,
-      fullPath: path.join(dirPath, name),
-      mtime: fs.statSync(path.join(dirPath, name)).mtimeMs
-    }))
-    .sort((a, b) => b.mtime - a.mtime);
-  return files[0]?.fullPath || null;
-}
-
-function safeReadJson(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (error) {
-    console.warn(`Review queue unreadable: ${filePath}. Starting fresh.`);
-    return null;
-  }
-}
-
-const resumeRequested = typeof RESUME_MODE !== 'undefined' && RESUME_MODE === 'true';
-let reviewQueuePath = resumeRequested ? findLatestQueue(stateDirPath) : null;
-
-if (!reviewQueuePath) {
-  reviewQueuePath = path.join(stateDirPath, `review-queue-${Date.now()}.json`);
-}
-
-if (!fs.existsSync(reviewQueuePath)) {
-  const reviewQueue = {
-    status: 'open',
-    scope: { type: 'audit', value: SCOPE },
-    passes: [],
-    items: [],
-    iteration: 0,
-    updatedAt: new Date().toISOString()
-  };
-  fs.writeFileSync(reviewQueuePath, JSON.stringify(reviewQueue, null, 2), 'utf8');
-} else if (resumeRequested) {
-  const reviewQueue = safeReadJson(reviewQueuePath) || {
-    status: 'open',
-    scope: { type: 'audit', value: SCOPE },
-    passes: [],
-    items: [],
-    iteration: 0,
-    updatedAt: new Date().toISOString()
-  };
-  reviewQueue.status = 'open';
-  reviewQueue.resumedAt = new Date().toISOString();
-  reviewQueue.updatedAt = new Date().toISOString();
-  fs.writeFileSync(reviewQueuePath, JSON.stringify(reviewQueue, null, 2), 'utf8');
-}
-```
-
-## Agent Coordination
-
-Use Task tool to launch agents in parallel:
-
-```javascript
-const agents = [];
-
-const baseReviewPrompt = (passId, role, focus) => `Role: ${role}.
-
-Scope: ${SCOPE}
-Framework: ${FRAMEWORK}
-
-Focus on:
-${focus.map(item => `- ${item}`).join('\n')}
-
-Write findings to ${reviewQueuePath} (append JSONL if possible). If you cannot write files, return JSON only.
-
-Return JSON ONLY in this format:
-{
-  "pass": "${passId}",
-  "findings": [
-    {
-      "file": "path/to/file.ts",
-      "line": 42,
-      "severity": "critical|high|medium|low",
-      "category": "${passId}",
-      "description": "Issue description",
-      "suggestion": "How to fix",
-      "confidence": "high|medium|low",
-      "falsePositive": false
-    }
-  ]
-}`;
-
-// Always active agents
-agents.push(Task({
-  subagent_type: "review",
-  prompt: baseReviewPrompt('code-quality', 'code quality reviewer', [
-    'Code style and consistency',
-    'Best practices violations',
-    'Potential bugs and logic errors',
-    'Error handling and failure paths',
-    'Maintainability issues',
-    'Code duplication'
-  ])
-}));
-
-agents.push(Task({
-  subagent_type: "review",
-  prompt: baseReviewPrompt('security', 'security reviewer', [
-    'Auth/authz flaws',
-    'Input validation and output encoding',
-    'Injection risks (SQL/command/template)',
-    'Secrets exposure and unsafe configs',
-    'Insecure defaults'
-  ])
-}));
-
-agents.push(Task({
-  subagent_type: "review",
-  prompt: baseReviewPrompt('performance', 'performance reviewer', [
-    'N+1 queries and inefficient loops',
-    'Blocking operations in async paths',
-    'Hot path inefficiencies',
-    'Memory leaks or unnecessary allocations'
-  ])
-}));
-
-agents.push(Task({
-  subagent_type: "review",
-  prompt: baseReviewPrompt('test-coverage', 'test coverage reviewer', [
-    'New code without corresponding tests',
-    'Missing edge case coverage',
-    'Test quality (meaningful assertions)',
-    'Integration test needs',
-    'Mock/stub appropriateness',
-    HAS_TESTS ? 'Existing tests: verify coverage depth' : 'No tests detected: report missing tests'
-  ])
-}));
-
-// Conditional agents
-if (FILE_COUNT > 50) {
-  agents.push(Task({
-    subagent_type: "review",
-    prompt: baseReviewPrompt('architecture', 'architecture reviewer', [
-      'Module boundaries and ownership',
-      'Dependency direction and layering',
-      'Cross-layer coupling',
-      'Consistency of patterns'
-    ])
-  }));
-}
-
-if (HAS_DB) {
-  agents.push(Task({
-    subagent_type: "review",
-    prompt: baseReviewPrompt('database', 'database specialist', [
-      'Query optimization and N+1 queries',
-      'Missing indexes',
-      'Transaction handling',
-      'Migration safety'
-    ])
-  }));
-}
-
-if (HAS_API) {
-  agents.push(Task({
-    subagent_type: "review",
-    prompt: baseReviewPrompt('api', 'api designer', [
-      'REST best practices',
-      'Error handling and status codes',
-      'Rate limiting and pagination',
-      'API versioning'
-    ])
-  }));
-}
-
-if (HAS_FRONTEND) {
-  agents.push(Task({
-    subagent_type: "review",
-    prompt: baseReviewPrompt('frontend', 'frontend specialist', [
-      'Component boundaries',
-      'State management patterns',
-      'Accessibility',
-      'Render performance'
-    ])
-  }));
-}
-
-if (HAS_BACKEND) {
-  agents.push(Task({
-    subagent_type: "review",
-    prompt: baseReviewPrompt('backend', 'backend specialist', [
-      'Service boundaries',
-      'Domain logic correctness',
-      'Concurrency and idempotency',
-      'Background job safety'
-    ])
-  }));
-}
-
-if (HAS_CICD) {
-  agents.push(Task({
-    subagent_type: "review",
-    prompt: baseReviewPrompt('devops', 'devops reviewer', [
-      'CI/CD safety',
-      'Secrets handling',
-      'Build/test pipelines',
-      'Deploy config correctness'
-    ])
-  }));
-}
-```
-
-## Finding Consolidation
-
-After all agents complete:
-
-```javascript
-function consolidateFindings(agentResults) {
-  const allFindings = [];
-
-  for (const result of agentResults) {
-    const pass = result.pass || 'unknown';
-    const findings = Array.isArray(result.findings) ? result.findings : [];
-    for (const finding of findings) {
-      allFindings.push({
-        id: `${pass}:${finding.file}:${finding.line}:${finding.description}`,
-        pass,
-        ...finding,
-        status: finding.falsePositive ? 'false-positive' : 'open'
-      });
-    }
-  }
-
-  // Deduplicate by pass:file:line:description
-  const seen = new Set();
-  const deduped = allFindings.filter(f => {
-    const key = `${f.pass}:${f.file}:${f.line}:${f.description}`;
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-
-  // Sort by severity
-  const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
-  deduped.sort((a, b) => {
-    const aRank = severityOrder[a.severity] ?? 99;
-    const bRank = severityOrder[b.severity] ?? 99;
-    return aRank - bRank;
-  });
-
-  // Update queue file
-  const queueState = safeReadJson(reviewQueuePath) || {
-    status: 'open',
-    scope: { type: 'audit', value: SCOPE },
-    passes: [],
-    items: [],
-    iteration: 0,
-    updatedAt: new Date().toISOString()
-  };
-  queueState.items = deduped;
-  queueState.passes = Array.from(new Set(deduped.map(item => item.pass)));
-  queueState.updatedAt = new Date().toISOString();
-  fs.writeFileSync(reviewQueuePath, JSON.stringify(queueState, null, 2), 'utf8');
-
-  // Group by file
-  const byFile = {};
-  for (const f of deduped) {
-    if (!byFile[f.file]) byFile[f.file] = [];
-    byFile[f.file].push(f);
-  }
-
-  return {
-    all: deduped,
-    byFile,
-    counts: {
-      critical: deduped.filter(f => f.severity === 'critical' && !f.falsePositive).length,
-      high: deduped.filter(f => f.severity === 'high' && !f.falsePositive).length,
-      medium: deduped.filter(f => f.severity === 'medium' && !f.falsePositive).length,
-      low: deduped.filter(f => f.severity === 'low' && !f.falsePositive).length
-    }
-  };
-}
-```
-
-## Queue Cleanup
-
-After fixes and re-review, remove the queue file if no open issues remain:
-
-```javascript
-const queueState = safeReadJson(reviewQueuePath);
-if (!queueState) {
-  return;
-}
-const openCount = queueState.items.filter(item => !item.falsePositive).length;
-if (openCount === 0) {
-  if (fs.existsSync(reviewQueuePath)) {
-    try {
-      fs.unlinkSync(reviewQueuePath);
-    } catch (error) {
-      if (error.code !== 'ENOENT') {
-        throw error;
-      }
-    }
-  }
-}
-```
-
-## Framework-Specific Patterns
-
-### React Patterns
-
-```javascript
-const reactPatterns = {
-  hooks_rules: {
-    description: "React hooks must be called at top level",
-    pattern: /use[A-Z]\w+\(/,
-    context: "inside conditionals or loops"
-  },
-  state_management: {
-    description: "Avoid prop drilling, use context or state management",
-    pattern: /props\.\w+\.\w+\.\w+/
-  },
-  performance: {
-    description: "Use memo/useMemo for expensive computations",
-    pattern: /\.map\(.*=>.*\.map\(/
-  }
-};
-```
-
-### Express Patterns
-
-```javascript
-const expressPatterns = {
-  error_handling: {
-    description: "Express routes must have error handling",
-    pattern: /app\.(get|post|put|delete)\(/,
-    check: "next(err) in catch block"
-  },
-  async_handlers: {
-    description: "Async handlers need try-catch or wrapper",
-    pattern: /async\s*\(req,\s*res/
-  }
-};
-```
-
-### Django Patterns
-
-```javascript
-const djangoPatterns = {
-  n_plus_one: {
-    description: "Use select_related/prefetch_related",
-    pattern: /\.objects\.(all|filter)\(\)/
-  },
-  raw_queries: {
-    description: "Avoid raw SQL, use ORM",
-    pattern: /\.raw\(|connection\.cursor\(\)/
-  }
-};
-```
-
-## Pattern Application
-
-```javascript
-function applyPatterns(findings, frameworkPatterns) {
-  if (!frameworkPatterns) return findings;
-
-  for (const pattern of Object.values(frameworkPatterns)) {
-    // Check each finding against framework patterns
-    for (const finding of findings) {
-      if (pattern.pattern.test(finding.codeQuote)) {
-        finding.frameworkContext = pattern.description;
-      }
-    }
-  }
-
-  return findings;
-}
-```
-
-## Review Output Format
-
-```markdown
-## Agent Reports
-
-### security-expert
-**Files Reviewed**: X
-**Issues Found**: Y (Z critical, A high)
-
-Findings:
-1. [Finding details with file:line]
-2. [Finding details with file:line]
-
-### performance-engineer
-**Files Reviewed**: X
-**Issues Found**: Y
-
-Findings:
-1. [Finding details with file:line]
-
-[... per agent]
-
-## Consolidated Summary
-
-**Total Issues**: X
-- Critical: Y (must fix)
-- High: Z (should fix)
-- Medium: A (consider)
-- Low: B (nice to have)
-
-**Top Files by Issue Count**:
-1. src/api/users.ts: 5 issues
-2. src/auth/session.ts: 3 issues
-```

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

@@ -1,144 +0,0 @@
----
-codex-description: "Create GitHub issues for non-security deferred findings identified by /audit-project."
----
-
-# Phase 8: GitHub Issue Creation - Reference
-
-This file contains GitHub integration for `/audit-project`.
-
-**Parent document**: `audit-project.md`
-
-## Pre-Conditions
-
-```bash
-# Check if git and gh are available
-GIT_AVAILABLE=$(command -v git >/dev/null 2>&1 && echo "true" || echo "false")
-GH_AVAILABLE=$(command -v gh >/dev/null 2>&1 && echo "true" || echo "false")
-
-# Check if this is a GitHub repository
-IS_GITHUB_REPO="false"
-if [ "$GIT_AVAILABLE" = "true" ]; then
-  REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
-  if echo "$REMOTE_URL" | grep -q "github.com"; then
-    IS_GITHUB_REPO="true"
-  fi
-fi
-```
-
-## Creating GitHub Issues
-
-If `git` and `gh` are available, create issues for **non-security** deferred items:
-
-```bash
-if [ "$GH_AVAILABLE" = "true" ] && [ "$IS_GITHUB_REPO" = "true" ]; then
-  echo "Creating GitHub issues for deferred items..."
-
-  # DO NOT create public issues for security-sensitive findings
-  for issue in "${DEFERRED_NON_SECURITY_ISSUES[@]}"; do
-    gh issue create \
-      --title "${issue.title}" \
-      --body "${issue.body}"
-  done
-
-  echo "Created ${#DEFERRED_NON_SECURITY_ISSUES[@]} GitHub issues"
-fi
-```
-
-## Issue Format
-
-Each created issue includes:
-
-```markdown
-## Issue from /audit-project
-
-**Severity**: [Critical|High|Medium|Low]
-**Category**: [Performance|Architecture|Code Quality|Enhancement]
-**Effort**: [Small|Medium|Large] (~X hours)
-
-### Description
-[Description of the issue]
-
-### Current Behavior
-\`\`\`[language]
-[Code showing the problem]
-\`\`\`
-
-### Proposed Fix
-[Specific remediation approach]
-
-### Impact
-[Why this matters]
-
-### Files
-- [List of affected files]
-```
-
-## Security Issue Handling
-
-```
-
-  [WARN] SECURITY ISSUES MUST NOT BE PUBLIC
-
-  The following must NOT be created as GitHub issues:
-  - Token/credential exposure
-  - Authentication vulnerabilities
-  - Authorization bypasses
-  - Injection vulnerabilities
-  - Any exploitable security finding
-
-  For security issues:
-  1. Fix immediately if possible
-  2. Keep documented internally only
-  3. Note in completion report (no details)
-
-```
-
-## TECHNICAL_DEBT.md Cleanup
-
-After all issues are handled, remove TECHNICAL_DEBT.md:
-
-```bash
-if [ "$GH_AVAILABLE" = "true" ] && [ "$IS_GITHUB_REPO" = "true" ]; then
-  if [ -f "TECHNICAL_DEBT.md" ]; then
-    rm TECHNICAL_DEBT.md
-    git add TECHNICAL_DEBT.md
-    git commit -m "chore: remove TECHNICAL_DEBT.md - issues tracked in GitHub
-
-Created GitHub issues for all deferred non-security items.
-Security-sensitive issues kept internal."
-    echo "Removed TECHNICAL_DEBT.md - issues now in GitHub"
-  fi
-else
-  echo "TECHNICAL_DEBT.md retained - no GitHub integration"
-fi
-```
-
-## Cleanup Conditions
-
-**Remove TECHNICAL_DEBT.md when ALL true:**
-1. `git` is available
-2. `gh` CLI is available and authenticated
-3. Repository has GitHub remote
-4. All non-security issues created as GitHub issues
-
-**Keep TECHNICAL_DEBT.md when ANY true:**
-1. No GitHub integration available
-2. `gh` CLI not authenticated
-3. User requested `--create-tech-debt` flag
-4. Security issues exist
-
-## Final Commit
-
-If issues were created:
-
-```bash
-git add -A
-git commit -m "chore: audit-project complete - issues tracked in GitHub
-
-Created X GitHub issues for deferred items:
-- #N: [issue title]
-- #N: [issue title]
-
-Security-sensitive issues (Y total) kept internal.
-Fixed Z issues in this review session."
-```