agentsys 5.1.0 → 5.2.0

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."
-```

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

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