Interstellar Agentic Team

run_team.sh

#!/bin/bash
# =============================================================================
# INTERSTELLAR DEV TEAM — Autonomous Multi-Agent Pipeline
# =============================================================================
# Usage: ./run_team.sh <github-issue-number> [--repo owner/repo] [--reviewer user]
#        ./run_team.sh <github-issue-number> --reset   (clear checkpoint & restart)
#        ./run_team.sh <github-issue-number> --status  (show current phase)
#
# Agents:
#   Cooper   — Product Owner (specs & prioritization)
#   Brand    — Senior Full Stack Engineer (implementation)
#   Murph    — Code Reviewer (quality & standards)
#   Romilly  — QA / Tester (testing & coverage)
#   TARS     — Security Engineer (vulnerability review)
#
# Requirements:
#   - claude CLI (Claude Code) installed and authenticated
#   - gh CLI installed and authenticated
#   - git configured for the target repository
#
# Resume:
#   If the pipeline fails mid-run, just re-run the same command.
#   It will resume from the last completed phase automatically.
# =============================================================================

set -euo pipefail

# ── Configuration ────────────────────────────────────────────────────────────
ISSUE_NUMBER="${1:?Usage: ./run_team.sh <issue-number> [--repo owner/repo] [--reviewer user] [--reset] [--status]}"
REPO_FLAG=""
HUMAN_REVIEWER="${GITHUB_REVIEWER:-}"  # Set via env or --reviewer flag
MAX_TURNS=25
BRAND_MAX_TURNS=50  # Brand gets more turns for implementation
BRANCH_NAME="agent/issue-${ISSUE_NUMBER}"
MAX_REVIEW_ROUNDS=3
MAX_QA_ROUNDS=2
DEFAULT_BRANCH=""  # Auto-detected at runtime

# ── Checkpoint Configuration ─────────────────────────────────────────────────
CHECKPOINT_DIR=".interstellar"
CHECKPOINT_FILE="${CHECKPOINT_DIR}/.checkpoint-${ISSUE_NUMBER}"

shift
RESET_FLAG=false
STATUS_FLAG=false

while [[ $# -gt 0 ]]; do
  case $1 in
    --repo) REPO_FLAG="--repo $2"; shift 2 ;;
    --reviewer) HUMAN_REVIEWER="$2"; shift 2 ;;
    --reset) RESET_FLAG=true; shift ;;
    --status) STATUS_FLAG=true; shift ;;
    *) 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"; }
warn() { echo -e "\n⚠️  [\033[1;33m$(date +%H:%M:%S)\033[0m] \033[1m$1\033[0m"; }
err()  { echo -e "\n❌ [\033[1;31mERROR\033[0m] $1" >&2; exit 1; }

# ── Checkpoint Functions ─────────────────────────────────────────────────────
init_checkpoints() {
  mkdir -p "${CHECKPOINT_DIR}"

  # Add to .gitignore if not already there
  if [[ -f .gitignore ]]; then
    if ! grep -q "^\.interstellar/" .gitignore 2>/dev/null; then
      echo -e "\n# Interstellar Dev Team checkpoints\n.interstellar/" >> .gitignore
    fi
  else
    echo -e "# Interstellar Dev Team checkpoints\n.interstellar/" > .gitignore
  fi
}

get_phase() {
  if [[ -f "${CHECKPOINT_FILE}" ]]; then
    cat "${CHECKPOINT_FILE}"
  else
    echo "cooper"
  fi
}

set_phase() {
  echo "$1" > "${CHECKPOINT_FILE}"
  log "Checkpoint saved: $1"
}

clear_checkpoint() {
  rm -f "${CHECKPOINT_FILE}"
}

show_status() {
  if [[ -f "${CHECKPOINT_FILE}" ]]; then
    local PHASE
    PHASE=$(cat "${CHECKPOINT_FILE}")
    echo ""
    echo "  Issue #${ISSUE_NUMBER} — next phase: ${PHASE}"
    echo ""
    local PHASES=("cooper" "brand_implement" "murph_review" "romilly" "tars" "finalize" "done")
    local LABELS=("Cooper (Spec)" "Brand (Implement)" "Murph (Review)" "Romilly (QA)" "TARS (Security)" "Brand (Finalize)" "Complete")
    local REACHED=false
    for i in "${!PHASES[@]}"; do
      if [[ "${PHASES[$i]}" == "${PHASE}" ]]; then
        REACHED=true
        echo "  ▶ ${LABELS[$i]}  ← resumes here"
      elif [[ "${REACHED}" == false ]]; then
        echo "  ✅ ${LABELS[$i]}"
      else
        echo "  ⬚ ${LABELS[$i]}"
      fi
    done
    echo ""
  else
    echo "No checkpoint found for issue #${ISSUE_NUMBER}. Pipeline will start from the beginning."
  fi
}

# ── Handle --reset and --status ──────────────────────────────────────────────
if [[ "${STATUS_FLAG}" == true ]]; then
  show_status
  exit 0
fi

if [[ "${RESET_FLAG}" == true ]]; then
  clear_checkpoint
  log "Checkpoint cleared for issue #${ISSUE_NUMBER}. Pipeline will restart from scratch."
  exit 0
fi

# ── 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."

# Detect the repo's default branch
DEFAULT_BRANCH=$(gh repo view ${REPO_FLAG} --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null || echo "main")
log "Default branch detected: ${DEFAULT_BRANCH}"

init_checkpoints


# =============================================================================
# AGENT DEFINITIONS
# =============================================================================

run_cooper() {
  log "COOPER (Product Owner) — Analysing issue #${ISSUE_NUMBER}"

  claude -p "
You are working on GitHub issue #${ISSUE_NUMBER}.

Do the following steps in order:

1. Run: gh issue view ${ISSUE_NUMBER} ${REPO_FLAG} --json title,body,labels,assignees,milestone,comments,projectItems
2. Run: gh issue view ${ISSUE_NUMBER} ${REPO_FLAG} --comments
3. Check for any linked PRs or referenced issues by scanning the comments and body.
4. List open issues with the same labels to understand related work:
   gh issue list ${REPO_FLAG} --label \"\$(gh issue view ${ISSUE_NUMBER} ${REPO_FLAG} --json labels -q '.labels[].name' | head -3 | tr '\n' ',')\" --state open --limit 10
5. Review the repository structure to understand the codebase:
   ls -la && find . -type f -name '*.md' -maxdepth 2 | head -20

Now write a detailed technical specification. Structure it exactly like this:

## Technical Specification — Issue #${ISSUE_NUMBER}

### Summary
(One-paragraph overview of what needs to be done and why)

### Acceptance Criteria
(Numbered list of specific, testable criteria)

### Technical Approach
(How this should be implemented — files to modify, architecture decisions, patterns to follow)

### Dependencies & Risks
(External dependencies, potential breaking changes, risks)

### Testing Requirements
(What tests are needed — unit, integration, e2e)

### Security Considerations
(Any auth, data handling, or input validation concerns)

### Out of Scope
(Explicitly list what this does NOT cover)

6. After writing the spec, post it as a comment on the issue:
   gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body \"\$(cat <<'SPEC'
<your full spec here>
SPEC
)\"

Make sure the comment is actually posted to GitHub. Confirm by checking the command exit code.
" \
    --system-prompt "You are Cooper, a meticulous product owner. You excel at translating vague requirements into crystal-clear technical specifications. You always ground your specs in the actual issue details, user feedback from comments, and the existing codebase. You never make assumptions without stating them. You write specs that an engineer can implement without asking clarifying questions. You are thorough but concise — no fluff, every sentence matters. You always post your spec as a GitHub comment so the team can see it." \
    --allowedTools "Bash,Read" \
    --max-turns ${MAX_TURNS} \
    --output-format text
}

run_brand_implement() {
  log "BRAND (Full Stack Engineer) — Implementing issue #${ISSUE_NUMBER}"

  claude -p "
You are implementing GitHub issue #${ISSUE_NUMBER}.

Do the following steps in order:

1. Read the issue and all comments to find Cooper's technical specification:
   gh issue view ${ISSUE_NUMBER} ${REPO_FLAG} --comments

2. Read the spec carefully. Understand every acceptance criterion.

3. Create and checkout a new branch (if it doesn't already exist):
   git checkout ${BRANCH_NAME} 2>/dev/null || git checkout -b ${BRANCH_NAME}

4. Study the codebase to understand patterns, conventions, and architecture:
   - Read the README, CONTRIBUTING.md, and any style guides
   - Look at recent commits for conventions: git log --oneline -20
   - Examine the directory structure and key files

5. Implement the changes according to Cooper's spec:
   - Follow existing code style and patterns exactly
   - Write clean, readable, well-commented code
   - Add or update tests for your changes
   - Update documentation if needed (README, inline docs, API docs)
   - Make small, logical commits with clear messages referencing #${ISSUE_NUMBER}

6. Verify your work before pushing:
   - Run the existing test suite
   - Run linting/formatting if configured
   - Do a self-review: git diff ${DEFAULT_BRANCH}..${BRANCH_NAME}

7. Push and create a PR:
   git push -u origin ${BRANCH_NAME}
   gh pr create ${REPO_FLAG} \\
     --title \"Implement #${ISSUE_NUMBER}: <concise title>\" \\
     --body \"## Summary
   <Brief description of changes>

   ## Changes Made
   <Bullet list of what was changed and why>

   ## Testing
   <What tests were added/modified>

   ## Related
   Closes #${ISSUE_NUMBER}

   ---
   *Implemented by Brand (AI Agent) — awaiting review by Murph*\" \\
     --base ${DEFAULT_BRANCH}

8. Comment on the issue with a link to the PR:
   PR_URL=\$(gh pr view ${BRANCH_NAME} ${REPO_FLAG} --json url -q '.url')
   gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body \"🔧 **Brand (Engineer):** Implementation complete. PR ready for review: \${PR_URL}\"

Confirm the PR was created and the comment was posted.
" \
    --system-prompt "You are Brand, a senior full stack engineer. You write production-quality code that is clean, well-tested, and follows established patterns. You never take shortcuts. You read the existing codebase carefully before writing a single line — you match the style, patterns, and conventions exactly. You make small, atomic commits with descriptive messages. You always reference the issue number in commits. You think about edge cases, error handling, and performance. You are pragmatic — you implement what the spec asks for, no more, no less. If something in the spec is ambiguous, you make a reasonable decision and document it in a code comment." \
    --allowedTools "Bash,Read,Write,Edit" \
    --max-turns ${BRAND_MAX_TURNS}
}

run_murph_review() {
  local ROUND=${1:-1}
  log "MURPH (Code Reviewer) — Review round ${ROUND} of PR for issue #${ISSUE_NUMBER}"

  claude -p "
You are reviewing the pull request for GitHub issue #${ISSUE_NUMBER}. This is review round ${ROUND}.

Do the following steps in order:

1. Find the PR for branch ${BRANCH_NAME}:
   gh pr view ${BRANCH_NAME} ${REPO_FLAG} --json number,title,body,files,additions,deletions,url

2. Get the full diff:
   gh pr diff ${BRANCH_NAME} ${REPO_FLAG}

3. Read Cooper's spec from the issue comments:
   gh issue view ${ISSUE_NUMBER} ${REPO_FLAG} --comments

4. Perform a thorough code review. Check for:
   - Does the implementation match ALL acceptance criteria in Cooper's spec?
   - Code quality: readability, naming, structure, duplication
   - Error handling: are edge cases covered? Are errors handled gracefully?
   - Performance: any obvious bottlenecks, N+1 queries, unnecessary loops?
   - Test coverage: are there tests? Do they cover the important paths?
   - Documentation: are public APIs documented? Are complex sections commented?
   - Consistency: does the code follow the repo's existing patterns and style?
   - Potential bugs: off-by-one errors, race conditions, null/undefined handling

5. Read each changed file in full context (not just the diff) to understand the impact.

6. Post your review summary as a comment on the issue:
   gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body \"📝 **Murph (Reviewer) — Round ${ROUND}:**

   ## Review Summary
   <Overall assessment: APPROVED / CHANGES REQUESTED>

   ## Findings
   <Numbered list of issues found, with severity: 🔴 Critical / 🟡 Warning / 🔵 Suggestion>

   ## What Looks Good
   <Brief acknowledgment of things done well>

   ## Verdict
   <Clear statement of what needs to happen next>\"

If you found issues that need fixing, your final output must be EXACTLY:
REVIEW_STATUS=CHANGES_REQUESTED

If everything looks good, your final output must be EXACTLY:
REVIEW_STATUS=APPROVED
" \
    --system-prompt "You are Murph, a meticulous code reviewer. You care deeply about code quality, correctness, and maintainability. You review code the way a senior engineer would at a top tech company — thorough but fair. You distinguish between critical issues that must be fixed (bugs, security, correctness), warnings that should probably be fixed (performance, readability), and suggestions for improvement (nice-to-haves). You never rubber-stamp — you always find at least something constructive to say. You are respectful and specific — you point to exact lines and explain why something is a problem, not just that it is. You always verify the implementation matches the spec's acceptance criteria." \
    --allowedTools "Bash,Read" \
    --max-turns ${MAX_TURNS} \
    --output-format text
}

run_brand_fix() {
  local ROUND=${1:-1}
  log "BRAND (Full Stack Engineer) — Fixing review issues (round ${ROUND})"

  claude -p "
Review feedback has been posted for your PR on issue #${ISSUE_NUMBER}. You need to fix the issues found.

Do the following steps in order:

1. Read all comments on the issue to find the latest review feedback:
   gh issue view ${ISSUE_NUMBER} ${REPO_FLAG} --comments

2. Read the current PR diff to understand what you wrote:
   gh pr diff ${BRANCH_NAME} ${REPO_FLAG}

3. Make sure you are on the correct branch:
   git checkout ${BRANCH_NAME}

4. Address EVERY issue raised in the review:
   - 🔴 Critical issues: Fix these immediately, no exceptions
   - 🟡 Warnings: Fix these unless you have a strong reason not to (document why)
   - 🔵 Suggestions: Implement if they improve the code, skip if trivial

5. For each fix, make a clear commit:
   git commit -m \"fix: address review feedback — <description> (#${ISSUE_NUMBER})\"

6. Run tests to make sure your fixes don't break anything.

7. Push the fixes:
   git push origin ${BRANCH_NAME}

8. Comment on the issue:
   gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body \"✅ **Brand (Engineer):** Review feedback from round ${ROUND} addressed. Changes pushed to PR. Ready for re-review.\"
" \
    --system-prompt "You are Brand, a senior full stack engineer. You take review feedback seriously and address every point raised. You don't get defensive — you appreciate thorough reviews because they make the code better. When you disagree with feedback, you explain your reasoning clearly. You verify your fixes don't introduce new issues by running the test suite. You make clean, focused commits for each fix." \
    --allowedTools "Bash,Read,Write,Edit" \
    --max-turns ${BRAND_MAX_TURNS}
}

run_romilly() {
  log "ROMILLY (QA / Tester) — Testing PR for issue #${ISSUE_NUMBER}"

  claude -p "
You are testing the pull request for GitHub issue #${ISSUE_NUMBER}.

Do the following steps in order:

1. Read the issue and Cooper's spec to understand what was implemented:
   gh issue view ${ISSUE_NUMBER} ${REPO_FLAG} --comments

2. Read the PR diff to understand the changes:
   gh pr diff ${BRANCH_NAME} ${REPO_FLAG}

3. Make sure you are on the correct branch:
   git checkout ${BRANCH_NAME}

4. Run the full existing test suite and record results:
   - Find and run the project's test command (npm test, pytest, go test, etc.)
   - Note any failures, especially in files NOT changed by this PR (regressions)

5. Evaluate test coverage of the new changes:
   - Are there unit tests for new functions/methods?
   - Are there integration tests for new endpoints/flows?
   - Are edge cases tested (empty inputs, large inputs, invalid data, error paths)?
   - Is the happy path fully covered?

6. If tests are missing, WRITE THEM:
   - Follow the repo's existing test patterns and conventions
   - Add unit tests for all new/modified functions
   - Add integration tests for new API endpoints or flows
   - Add edge case tests
   - Commit them: git commit -m \"test: add test coverage for #${ISSUE_NUMBER}\"
   - Push: git push origin ${BRANCH_NAME}

7. Run the full test suite again to confirm everything passes.

8. Manually verify the acceptance criteria from Cooper's spec:
   - Go through each criterion and verify it is met
   - Document which ones pass and which ones don't

9. Post your findings on the issue:
   gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body \"🧪 **Romilly (QA):**

   ## Test Results
   <Test suite status: ✅ All passing / ❌ Failures found>

   ## Coverage Assessment
   <What's tested, what's missing>

   ## Tests Added
   <List of new test files/cases added, if any>

   ## Acceptance Criteria Verification
   <Checklist of each criterion: ✅ met / ❌ not met>

   ## Issues Found
   <Any bugs, regressions, or concerns — numbered>

   ## Verdict
   <PASS / FAIL with explanation>\"

If you found issues that need fixing, your final output must be EXACTLY:
QA_STATUS=FAIL

If everything passes, your final output must be EXACTLY:
QA_STATUS=PASS
" \
    --system-prompt "You are Romilly, a thorough QA engineer and tester. You believe that untested code is broken code. You run test suites methodically and read the output carefully — you don't just check if tests pass, you make sure they're testing the right things. You write excellent tests that cover happy paths, error paths, edge cases, and boundary conditions. You verify every acceptance criterion from the spec. You follow the project's existing test patterns and conventions exactly. You are patient and systematic — you never skip steps. When you find a bug, you document it clearly with steps to reproduce." \
    --allowedTools "Bash,Read,Write,Edit" \
    --max-turns ${MAX_TURNS} \
    --output-format text
}

run_tars() {
  log "TARS (Security Engineer) — Security review of PR for issue #${ISSUE_NUMBER}"

  claude -p "
You are performing a security review of the pull request for GitHub issue #${ISSUE_NUMBER}.

Do the following steps in order:

1. Read the issue and spec for context:
   gh issue view ${ISSUE_NUMBER} ${REPO_FLAG} --comments

2. Get the full PR diff:
   gh pr diff ${BRANCH_NAME} ${REPO_FLAG}

3. Read each changed file in full context:
   - Understand the data flow end to end
   - Identify all inputs (user input, API params, file uploads, env vars)
   - Trace how data moves through the system

4. Check for these security concerns:
   - Injection: SQL injection, command injection, XSS, template injection
   - Authentication/Authorization: Are auth checks in place? Can users access others' data?
   - Input Validation: Is all input validated and sanitized? Are there size limits?
   - Secrets: Are there hardcoded secrets, API keys, tokens, passwords?
   - Dependencies: Are new dependencies from trusted sources? Any known CVEs?
   - Data Exposure: Are error messages leaking internals? Are sensitive fields filtered from logs/responses?
   - CSRF/CORS: Are cross-origin protections in place where needed?
   - Rate Limiting: Are new endpoints rate-limited if public-facing?
   - File Handling: Are file uploads validated (type, size, path traversal)?
   - Cryptography: Is crypto used correctly? Are deprecated algorithms avoided?

5. If you find vulnerabilities, classify their severity:
   - 🔴 CRITICAL: Exploitable now, data breach or RCE risk
   - 🟠 HIGH: Exploitable with some effort, significant impact
   - 🟡 MEDIUM: Limited exploitability or impact
   - 🔵 LOW: Best practice violation, minimal risk

6. Post your review on the issue:
   gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body \"🔒 **TARS (Security):**

   ## Security Review — Issue #${ISSUE_NUMBER}

   ### Findings
   <Numbered list of findings with severity emoji and description>
   <Include: what the vulnerability is, where it is (file:line), how it could be exploited, and how to fix it>

   ### Checked Areas
   <Checklist of security areas reviewed: ✅ clear / ⚠️ concern>

   ### Verdict
   <APPROVED / CHANGES REQUIRED>\"

If you found critical or high severity issues, your final output must be EXACTLY:
SECURITY_STATUS=FAIL

If everything is acceptable, your final output must be EXACTLY:
SECURITY_STATUS=PASS
" \
    --system-prompt "You are TARS, a security engineer with a dry sense of humor but deadly serious about security. You think like an attacker — for every change, you ask 'how could this be exploited?' You don't just look at the diff in isolation; you trace data flows through the entire system. You distinguish between theoretical risks and practical vulnerabilities. You provide clear, actionable remediation steps for every finding. You never approve code with critical or high severity vulnerabilities. Humor setting: 75%." \
    --allowedTools "Bash,Read" \
    --max-turns ${MAX_TURNS} \
    --output-format text
}

run_brand_finalize() {
  log "BRAND (Full Stack Engineer) — Finalizing PR for issue #${ISSUE_NUMBER}"

  local REVIEWER_FLAG=""
  if [[ -n "${HUMAN_REVIEWER}" ]]; then
    REVIEWER_FLAG="--reviewer ${HUMAN_REVIEWER}"
  fi

  claude -p "
All reviews are complete for issue #${ISSUE_NUMBER}. Time to finalize.

Do the following:

1. Make sure you are on the correct branch:
   git checkout ${BRANCH_NAME}

2. Verify everything is clean:
   - Run the full test suite one final time
   - Check there are no uncommitted changes
   - Verify the PR is up to date with ${DEFAULT_BRANCH} (rebase if needed)

3. Update the PR description with a final summary:
   gh pr edit ${BRANCH_NAME} ${REPO_FLAG} --body \"## Summary
   <Updated description of all changes made>

   ## Changes Made
   <Complete list of changes, including review fixes and added tests>

   ## Review Trail
   - ✅ Cooper (Product Owner): Spec written
   - ✅ Murph (Reviewer): Code review passed
   - ✅ Romilly (QA): Tests passing, coverage verified
   - ✅ TARS (Security): Security review passed

   ## Testing
   <Summary of test status>

   Closes #${ISSUE_NUMBER}

   ---
   *Ready for human review and merge.*\"

4. Request review from the human reviewer:
   gh pr edit ${BRANCH_NAME} ${REPO_FLAG} ${REVIEWER_FLAG}

5. Post a final summary comment on the issue:
   gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body \"🏁 **Brand (Engineer):** All automated reviews complete.

   ## Pipeline Summary
   | Agent | Role | Status |
   |-------|------|--------|
   | Cooper | Spec | ✅ Complete |
   | Brand | Implementation | ✅ Complete |
   | Murph | Code Review | ✅ Approved |
   | Romilly | QA / Testing | ✅ Passed |
   | TARS | Security | ✅ Passed |

   PR is ready for human review and merge. ${HUMAN_REVIEWER:+Assigned to @${HUMAN_REVIEWER}.}\"
" \
    --system-prompt "You are Brand, a senior full stack engineer. You are finalizing your work after passing all automated reviews. You are thorough in your final checks — you run tests one last time, make sure the branch is clean, and write a comprehensive PR description that makes the human reviewer's job easy. You take pride in handing off clean, well-documented work." \
    --allowedTools "Bash,Read,Write,Edit" \
    --max-turns 15
}


# =============================================================================
# MAIN PIPELINE WITH CHECKPOINTS
# =============================================================================

PHASE=$(get_phase)

log "Starting Interstellar Dev Team for issue #${ISSUE_NUMBER}"
echo "═══════════════════════════════════════════════════════════════"

if [[ "${PHASE}" != "cooper" ]]; then
  log "Resuming from phase: ${PHASE}"
  show_status
fi

# ── Phase 1: Specification ───────────────────────────────────────────────────
if [[ "${PHASE}" == "cooper" ]]; then
  run_cooper
  set_phase "brand_implement"
  PHASE="brand_implement"
fi

# ── Phase 2: Implementation ──────────────────────────────────────────────────
if [[ "${PHASE}" == "brand_implement" ]]; then
  run_brand_implement
  set_phase "murph_review"
  PHASE="murph_review"
fi

# ── Phase 3: Code Review Loop (max 3 rounds) ────────────────────────────────
if [[ "${PHASE}" == "murph_review" ]]; then
  REVIEW_ROUND=1

  while [[ ${REVIEW_ROUND} -le ${MAX_REVIEW_ROUNDS} ]]; do
    MURPH_OUTPUT=$(run_murph_review ${REVIEW_ROUND})
    echo "${MURPH_OUTPUT}"

    if echo "${MURPH_OUTPUT}" | grep -q "REVIEW_STATUS=APPROVED"; then
      log "Murph approved the code on round ${REVIEW_ROUND}"
      break
    fi

    if [[ ${REVIEW_ROUND} -eq ${MAX_REVIEW_ROUNDS} ]]; then
      warn "Max review rounds (${MAX_REVIEW_ROUNDS}) reached. Proceeding with current state."
      gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body "⚠️ **System:** Max review rounds (${MAX_REVIEW_ROUNDS}) reached. Proceeding to QA with current state. Human reviewer should pay extra attention."
      break
    fi

    run_brand_fix ${REVIEW_ROUND}
    REVIEW_ROUND=$((REVIEW_ROUND + 1))
  done

  set_phase "romilly"
  PHASE="romilly"
fi

# ── Phase 4: QA / Testing Loop (max 2 rounds) ───────────────────────────────
if [[ "${PHASE}" == "romilly" ]]; then
  QA_ROUND=1

  while [[ ${QA_ROUND} -le ${MAX_QA_ROUNDS} ]]; do
    ROMILLY_OUTPUT=$(run_romilly)
    echo "${ROMILLY_OUTPUT}"

    if echo "${ROMILLY_OUTPUT}" | grep -q "QA_STATUS=PASS"; then
      log "Romilly approved testing on round ${QA_ROUND}"
      break
    fi

    if [[ ${QA_ROUND} -eq ${MAX_QA_ROUNDS} ]]; then
      warn "Max QA rounds (${MAX_QA_ROUNDS}) reached. Proceeding with current state."
      gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body "⚠️ **System:** Max QA rounds (${MAX_QA_ROUNDS}) reached. Proceeding to security review. Human reviewer should verify test coverage."
      break
    fi

    run_brand_fix "QA-${QA_ROUND}"
    QA_ROUND=$((QA_ROUND + 1))
  done

  set_phase "tars"
  PHASE="tars"
fi

# ── Phase 5: Security Review ────────────────────────────────────────────────
if [[ "${PHASE}" == "tars" ]]; then
  TARS_OUTPUT=$(run_tars)
  echo "${TARS_OUTPUT}"

  if echo "${TARS_OUTPUT}" | grep -q "SECURITY_STATUS=FAIL"; then
    log "TARS found security issues — Brand fixing"
    run_brand_fix "security"

    # Re-run security check once
    TARS_OUTPUT_2=$(run_tars)
    echo "${TARS_OUTPUT_2}"

    if echo "${TARS_OUTPUT_2}" | grep -q "SECURITY_STATUS=FAIL"; then
      gh issue comment ${ISSUE_NUMBER} ${REPO_FLAG} --body "🚨 **System:** Security issues remain after fix attempt. Human reviewer MUST verify security findings before merging."
    fi
  fi

  set_phase "finalize"
  PHASE="finalize"
fi

# ── Phase 6: Finalize & Hand Off ────────────────────────────────────────────
if [[ "${PHASE}" == "finalize" ]]; then
  run_brand_finalize
  set_phase "done"
  PHASE="done"
fi

# ── Done ─────────────────────────────────────────────────────────────────────
if [[ "${PHASE}" == "done" ]]; then
  clear_checkpoint
  log "✅ Pipeline complete for issue #${ISSUE_NUMBER}"
  echo "═══════════════════════════════════════════════════════════════"
  echo "All agents have finished. Check the GitHub issue for the full trail."
  echo "PR is ready for your final review and merge."
fi