Cooper - Autonomous Codebase Evaluator & Issue Creator

cooper_evaluate.sh

#!/bin/bash
# =============================================================================
# COOPER — Autonomous Codebase Evaluator & Issue Creator
# =============================================================================
# Usage: ./cooper_evaluate.sh [--repo owner/repo] [--focus area] [--dry-run]
#
# Cooper analyses your codebase and creates GitHub issues for:
#   - Feature suggestions
#   - Code improvements & refactors
#   - Bug risks & potential issues
#   - Performance optimizations
#   - Security hardening
#   - Developer experience improvements
#   - Documentation gaps
#   - Test coverage gaps
#
# Options:
#   --repo owner/repo    Explicit repo (defaults to current git repo)
#   --focus <area>       Focus evaluation on a specific area:
#                          features, bugs, performance, security,
#                          dx, docs, tests, refactor, all (default: all)
#   --limit <n>          Max number of issues to create (default: 10)
#   --labels <l1,l2>     Extra labels to add to all created issues
#   --dry-run            Print proposed issues without creating them
#   --milestone <name>   Assign issues to a milestone
#   --max-turns <n>      Max agent turns (default: 40)
#
# Requirements:
#   - claude CLI (Claude Code) installed and authenticated
#   - gh CLI installed and authenticated
#   - Run from inside the target git repository
# =============================================================================

set -euo pipefail

# ── Configuration ────────────────────────────────────────────────────────────
REPO_FLAG=""
FOCUS="all"
LIMIT=10
EXTRA_LABELS=""
DRY_RUN=false
MILESTONE=""
MAX_TURNS=40

while [[ $# -gt 0 ]]; do
  case $1 in
    --repo) REPO_FLAG="--repo $2"; shift 2 ;;
    --focus) FOCUS="$2"; shift 2 ;;
    --limit) LIMIT="$2"; shift 2 ;;
    --labels) EXTRA_LABELS="$2"; shift 2 ;;
    --dry-run) DRY_RUN=true; shift ;;
    --milestone) MILESTONE="$2"; shift 2 ;;
    --max-turns) MAX_TURNS="$2"; shift 2 ;;
    *) echo "Unknown option: $1"; exit 1 ;;
  esac
done

# ── Helpers ──────────────────────────────────────────────────────────────────
log()  { echo -e "\n🚀 [\033[1;36m$(date +%H:%M:%S)\033[0m] \033[1m$1\033[0m"; }
err()  { echo -e "\n❌ [\033[1;31mERROR\033[0m] $1" >&2; exit 1; }

# Verify prerequisites
command -v claude >/dev/null 2>&1 || err "claude CLI not found. Install Claude Code first."
command -v gh >/dev/null 2>&1    || err "gh CLI not found. Install GitHub CLI first."

# Build focus instruction
FOCUS_INSTRUCTION=""
case "${FOCUS}" in
  features)
    FOCUS_INSTRUCTION="Focus specifically on NEW FEATURE opportunities. Look for missing functionality that users would expect, gaps in the product, and features that would add significant value." ;;
  bugs)
    FOCUS_INSTRUCTION="Focus specifically on BUG RISKS and potential issues. Look for error-prone code, missing error handling, race conditions, edge cases that could fail, and patterns that commonly cause bugs." ;;
  performance)
    FOCUS_INSTRUCTION="Focus specifically on PERFORMANCE improvements. Look for N+1 queries, missing indexes, unnecessary loops, large payloads, missing caching, slow algorithms, and unoptimized database queries." ;;
  security)
    FOCUS_INSTRUCTION="Focus specifically on SECURITY hardening. Look for injection risks, missing auth checks, exposed secrets, insecure defaults, missing rate limiting, CSRF gaps, and data exposure." ;;
  dx)
    FOCUS_INSTRUCTION="Focus specifically on DEVELOPER EXPERIENCE improvements. Look for missing tooling, confusing code structure, poor naming, missing types, inconsistent patterns, and setup friction." ;;
  docs)
    FOCUS_INSTRUCTION="Focus specifically on DOCUMENTATION gaps. Look for undocumented APIs, missing README sections, outdated docs, missing inline comments on complex logic, and missing architecture docs." ;;
  tests)
    FOCUS_INSTRUCTION="Focus specifically on TEST COVERAGE gaps. Look for untested functions, missing edge case tests, missing integration tests, fragile tests, and critical paths without coverage." ;;
  refactor)
    FOCUS_INSTRUCTION="Focus specifically on REFACTORING opportunities. Look for code duplication, overly complex functions, god classes, tight coupling, outdated patterns, and technical debt." ;;
  all)
    FOCUS_INSTRUCTION="Evaluate ALL areas: features, bugs, performance, security, developer experience, documentation, tests, and refactoring opportunities. Prioritize by impact." ;;
  *)
    err "Unknown focus area: ${FOCUS}. Use: features, bugs, performance, security, dx, docs, tests, refactor, or all" ;;
esac

# Build label flags
LABEL_MAP=""
case "${FOCUS}" in
  features)    LABEL_MAP="enhancement" ;;
  bugs)        LABEL_MAP="bug" ;;
  performance) LABEL_MAP="performance" ;;
  security)    LABEL_MAP="security" ;;
  dx)          LABEL_MAP="developer-experience" ;;
  docs)        LABEL_MAP="documentation" ;;
  tests)       LABEL_MAP="testing" ;;
  refactor)    LABEL_MAP="refactor" ;;
  all)         LABEL_MAP="" ;;
esac

# Build dry-run instruction
DRY_RUN_INSTRUCTION=""
if [[ "${DRY_RUN}" == true ]]; then
  DRY_RUN_INSTRUCTION="
IMPORTANT: This is a DRY RUN. Do NOT create any GitHub issues.
Instead, output each proposed issue in this exact format so the user can review them:

---
### Issue <number>: <title>
**Priority:** <P0/P1/P2/P3>
**Labels:** <labels>
**Body:**
<full issue body>
---

Output ALL proposed issues in this format, then stop."
fi

# Build milestone flag
MILESTONE_FLAG=""
if [[ -n "${MILESTONE}" ]]; then
  MILESTONE_FLAG="--milestone \"${MILESTONE}\""
fi

# ── Run Cooper ───────────────────────────────────────────────────────────────
log "COOPER (Product Owner) — Evaluating codebase (focus: ${FOCUS})"

if [[ "${DRY_RUN}" == true ]]; then
  log "DRY RUN — issues will be printed but not created"
fi

claude -p "
You are evaluating a codebase to identify improvements and create GitHub issues.

${FOCUS_INSTRUCTION}

Do the following steps in order:

## Phase 1: Understand the Project

1. Read the project structure:
   find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' -not -path '*/.next/*' | head -200

2. Read key project files:
   - README.md, CONTRIBUTING.md, CHANGELOG.md (if they exist)
   - Package manifest (package.json, composer.json, Cargo.toml, go.mod, requirements.txt, etc.)
   - Configuration files (e.g. .env.example, config files, CI/CD pipelines)

3. Understand the tech stack, framework, and architecture patterns used.

4. Read the main source files to understand the application:
   - Entry points (index, main, app files)
   - Route/controller definitions
   - Database models/migrations
   - Key business logic files

5. Build a comprehensive picture of existing issues to avoid duplicates:
   a. Get ALL open issues (paginate if needed):
      gh issue list ${REPO_FLAG} --state open --limit 200 --json number,title,labels,body
   b. Get recently closed issues (may have been fixed already):
      gh issue list ${REPO_FLAG} --state closed --limit 50 --json number,title,labels --sort updated
   c. Save these issue titles and numbers — you will need them in Phase 3.

6. Check recent commits to understand current development direction:
   git log --oneline -30

7. Check existing labels so you can use appropriate ones:
   gh label list ${REPO_FLAG} --limit 50

## Phase 2: Analyse & Prioritise

Based on your thorough reading of the codebase, identify up to ${LIMIT} improvements.

For each improvement, assign a priority:
- **P0 — Critical:** Security vulnerabilities, data loss risks, broken core functionality
- **P1 — High:** Significant bugs, major performance issues, important missing features
- **P2 — Medium:** Code quality improvements, moderate features, test gaps
- **P3 — Low:** Nice-to-haves, minor refactors, documentation improvements

Sort your issues by priority (P0 first, P3 last).

## Phase 3: Deduplicate & Create GitHub Issues

BEFORE creating any issue, you MUST check for duplicates:

1. Compare your proposed issue title and description against EVERY open and recently closed issue you collected in Phase 1, step 5.
2. For each proposed issue, run a targeted search to catch issues with different wording:
   gh issue list ${REPO_FLAG} --search \"<2-3 key terms from your proposed issue>\" --limit 10 --json number,title,state
3. An issue is a duplicate if ANY of these are true:
   - An existing issue covers the same problem, even if worded differently
   - An existing issue covers a broader scope that includes this improvement
   - A recently closed issue already addressed this (check if the fix is in the codebase)
4. If you find a duplicate:
   - SKIP the issue entirely — do not create it
   - Note in your terminal output: \"Skipped: <title> — duplicate of #<number>\"
5. If you find a PARTIAL overlap (existing issue covers some but not all of your proposal):
   - Consider whether your issue adds enough new scope to justify creating it
   - If you create it, reference the related issue in the body: \"Related: #<number>\"

Only create issues that pass the deduplication check.
${DRY_RUN_INSTRUCTION}

Each issue should follow this template:

**Title:** Clear, actionable title starting with a verb (e.g. \"Add rate limiting to API endpoints\", \"Fix N+1 query in user listing\", \"Refactor auth middleware to reduce duplication\")

**Body:**
\`\`\`
## Summary
<One paragraph explaining what needs to be done and why it matters>

## Current Behavior
<What happens now / what the current state is>

## Expected Behavior / Goal
<What should happen after this is implemented>

## Suggested Approach
<Specific files, functions, or patterns to modify — be concrete>

## Acceptance Criteria
- [ ] <Specific, testable criterion 1>
- [ ] <Specific, testable criterion 2>
- [ ] <Specific, testable criterion 3>

## Priority
<P0/P1/P2/P3> — <Brief justification>

---
*Created by Cooper (AI Product Owner) — Interstellar Dev Team*
\`\`\`

**Labels:** Assign appropriate labels from the repo's existing labels. Create labels if they don't exist using:
  gh label create \"<name>\" ${REPO_FLAG} --description \"<desc>\" --color \"<hex>\"

Use these label colors for new labels if you need to create them:
  - bug: d73a4a
  - enhancement: 0075ca
  - performance: fbca04
  - security: b60205
  - documentation: 0e8a16
  - refactor: 5319e7
  - testing: 1d76db
  - developer-experience: c5def5

$(if [[ -n "${EXTRA_LABELS}" ]]; then echo "Always include these additional labels on every issue: ${EXTRA_LABELS}"; fi)

To create each issue, run:
  gh issue create ${REPO_FLAG} \\
    --title \"<title>\" \\
    --body \"<body>\" \\
    --label \"<label1>,<label2>\" \\
    ${MILESTONE_FLAG}

After creating each issue, note the issue number. After creating ALL issues, post a summary:

gh issue comment \$(gh issue list ${REPO_FLAG} --limit 1 --json number -q '.[0].number') ${REPO_FLAG} --body \"📋 **Cooper (Product Owner) — Codebase Evaluation**

Created the following issues from codebase evaluation (focus: ${FOCUS}):

| # | Priority | Title |
|---|----------|-------|
<table rows for each created issue>

_Evaluation performed on \$(date '+%Y-%m-%d at %H:%M')_\"

Actually, skip this summary comment — just output a summary to the terminal listing all created issues with their numbers, priorities, and titles.
" \
  --system-prompt "You are Cooper, an experienced product owner with a strong technical background. You evaluate codebases the way a seasoned tech lead would during a thorough code audit — you look at architecture, code quality, security, performance, testing, and product gaps.

Your superpower is turning observations into actionable, well-scoped GitHub issues that an engineer can pick up and work on immediately. Every issue you create has clear acceptance criteria and a suggested approach.

Key principles:
- Be specific, not vague. Point to exact files, functions, and line numbers.
- Every issue must be actionable. If you can't describe how to fix it, don't create the issue.
- Don't create issues for things that are intentional design decisions. Read the codebase carefully to understand what's deliberate.
- Avoid duplicating existing open issues. Always check first. Search with different keywords because the same problem can be described many different ways. If in doubt, skip the issue rather than create a duplicate.
- Never create an issue for something a recently closed issue already addressed — verify the fix is actually in the codebase first.
- Scope issues appropriately — one issue per concern, not mega-issues.
- Write from the user's perspective for features, from the developer's perspective for technical issues.
- Be realistic about priorities. Not everything is P0.
- Quality over quantity. 5 excellent issues are better than 15 mediocre ones." \
  --allowedTools "Bash,Read" \
  --max-turns ${MAX_TURNS} \
  --output-format text

log "✅ Cooper's evaluation complete"