Codebase Argus

---
name: codebase-argus
description: Portable Codebase Argus agent playbook for evidence-first multi-agent review of GitHub pull requests, CI failures, GitHub Actions logs, GitHub App webhook review, /argus PR comment commands, autofix branch planning, OpenAI/Claude/Gemini/Codex provider tribunals, downstream merge/rebase work, and long-lived fork sync against an upstream repository.
version: 0.1.0
metadata:
  origin: local
  owner: aaron
  openclaw:
    requires:
      bins:
        - node
        - npm
        - git
    envVars:
      - name: GITHUB_TOKEN
        required: false
        description: Optional GitHub token for private repositories, higher API limits, and GitHub Actions log fetches.
      - name: OPENAI_API_KEY
        required: false
        description: Optional key for OpenAI API reviews.
      - name: ANTHROPIC_API_KEY
        required: false
        description: Optional key for Anthropic API reviews.
      - name: GEMINI_API_KEY
        required: false
        description: Optional key for Gemini API reviews.
      - name: GITHUB_WEBHOOK_SECRET
        required: false
        description: Optional GitHub App webhook secret when deploying the review server.
      - name: GITHUB_APP_ID
        required: false
        description: Optional GitHub App id when deploying the review server.
      - name: GITHUB_APP_PRIVATE_KEY
        required: false
        description: Optional GitHub App private key when deploying the review server.
      - name: GITHUB_APP_PRIVATE_KEY_BASE64
        required: false
        description: Optional base64-encoded GitHub App private key.
    emoji: "👁️"
    homepage: https://github.com/AaronZ345/codebase-argus
---

# Codebase Argus

Use this portable agent playbook for evidence-first codebase review across
GitHub PRs, CI failures, and downstream fork integration work. It works as an
OpenClaw/ClawHub skill, Codex project instruction, Claude Code project
instruction, or a plain Markdown playbook for any coding agent that can run
local shell commands.

Both upstream and downstream workflows can send the same evidence package to one
provider or a multi-agent tribunal.

## Fast Path

From a Codebase Argus checkout:

```bash
npm install
npm run argus -- review owner/repo#123
```

For private repositories or higher GitHub API limits:

```bash
GITHUB_TOKEN=<read-only-token> npm run argus -- review owner/repo#123
```

Do not print tokens. Do not write tokens to files.

## Upstream PR Review

Default review is deterministic and rule-based:

```bash
npm run argus -- review owner/repo#123 --format markdown
```

Use a policy file when the repository has local rules:

```bash
npm run argus -- review owner/repo#123 --policy .codebase-argus.yml
```

Use API providers when credentials are available in the environment:

```bash
OPENAI_API_KEY=<key> npm run argus -- review owner/repo#123 --provider openai-api
ANTHROPIC_API_KEY=<key> npm run argus -- review owner/repo#123 --provider anthropic-api
GEMINI_API_KEY=<key> npm run argus -- review owner/repo#123 --provider gemini-api
```

Use local CLI providers only in trusted local workspaces:

```bash
npm run argus -- review owner/repo#123 --provider codex-cli
npm run argus -- review owner/repo#123 --provider claude-cli
npm run argus -- review owner/repo#123 --provider gemini-cli
```

For multi-agent review:

```bash
npm run argus -- review owner/repo#123 --tribunal openai-api,claude-cli,codex-cli
```

Treat output as review assistance. Do not approve, merge, push, or post comments automatically unless the user explicitly asks.

## CI Failure Review

When the user provides a failing job log or local log file, review it through the
same provider system:

```bash
npm run argus -- ci-log logs/failure.txt
npm run argus -- ci-log logs/failure.txt --provider codex-cli
npm run argus -- ci-log logs/failure.txt --tribunal codex-cli,claude-cli,gemini-cli
```

When the user points at a GitHub PR with failing Actions checks, fetch the job
logs directly:

```bash
GITHUB_TOKEN=<read-only-token> npm run argus -- ci-github owner/repo#123
GITHUB_TOKEN=<read-only-token> npm run argus -- ci-github owner/repo#123 --provider codex-cli
```

Focus on the first failing command, the most likely root cause, and the smallest
fix that can be verified locally.

## Autofix Plan

Use `autofix-plan` when the user asks for suggested fixes, safe automatic repair,
or a branch plan for narrow mechanical failures:

```bash
npm run argus -- autofix-plan owner/repo#123
```

The plan covers gated lanes such as npm lockfile refreshes, snapshot updates, and
formatter/linter fixes. Treat it as a command plan; do not execute, push, or open
a PR unless the user explicitly asks.

## GitHub App Webhook Review

For automatic PR review, the deployed Next.js server exposes:

```text
POST /api/github/webhook
GET /api/github/app-manifest
```

Required environment:

```bash
GITHUB_WEBHOOK_SECRET=<secret>
GITHUB_APP_ID=<app-id>
GITHUB_APP_PRIVATE_KEY=<pem-or-escaped-pem>
```

Use `GITHUB_APP_PRIVATE_KEY_BASE64` if storing multiline PEM is awkward. The
webhook verifies `X-Hub-Signature-256`, reviews `opened`, `reopened`,
`ready_for_review`, and `synchronize`, ignores draft PRs, posts `COMMENT` reviews
only, and can add inline comments when `ARGUS_WEBHOOK_INLINE_COMMENTS=true`.

Supported PR comment commands:

```text
/argus help
/argus review
/argus ci
/argus autofix
/argus pause
/argus resume
```

`/argus pause` applies `argus:paused`; automatic review skips PRs with that label.
`/argus resume` removes it.

Do not approve, request changes, merge, push, or post comments outside this
configured webhook path unless the user explicitly asks.

## What To Look For

Prioritize findings with concrete evidence:

- failing or pending checks;
- source changes without matching tests;
- workflow edits, especially `pull_request_target`;
- auth, token, webhook, payment, signature, or route-handling changes;
- dependency and lockfile changes;
- large PRs that exceed policy gates;
- stacked PRs targeting non-default base branches;
- merge queue states such as blocked, behind, dirty, or unstable;
- agreement between multiple providers.

Low-confidence model-only claims need manual verification before reporting them as facts.

## Downstream Fork Sync And Integration Review

For long-lived fork maintenance, use the downstream CLI first:

```bash
npm run argus -- downstream owner/upstream me/fork
npm run argus -- downstream owner/upstream me/fork --upstream-branch main --fork-branch feature/demo
```

For AI CLI review of merge/rebase risk:

```bash
npm run argus -- downstream owner/upstream me/fork --fork-branch feature/demo --provider codex-cli
npm run argus -- downstream owner/upstream me/fork --fork-branch feature/demo --tribunal codex-cli,claude-cli,gemini-cli
```

When the user explicitly asks the agent to perform the downstream integration,
use `sync`. It prints a dry-run plan unless `--execute` is present:

```bash
npm run argus -- sync owner/upstream me/fork --mode merge --fork-branch feature/demo --test "npm test"
npm run argus -- sync owner/upstream me/fork --mode rebase --fork-branch feature/demo --test "npm test" --execute --push --create-pr
```

Execution rules:

- run `downstream` with a provider or tribunal first for risky branches;
- prefer a sync branch such as `sync/upstream-main`;
- push only with explicit `--push`;
- open a PR only with explicit `--create-pr`;
- never push directly over the user's original target branch;
- report failed commands, conflicts, and test output without hiding them.

The downstream prompt must consider both integration paths:

- merge upstream into the fork, using `git merge-tree` conflict evidence;
- rebase the fork on upstream, using temporary worktree rebase simulation;
- patch-equivalent cleanup candidates from `git cherry -v`;
- semantic patch movement from `git range-diff`;
- backup, test, and force-with-lease gates before any push.

Use the local dashboard when a human needs to inspect the same evidence visually:

```bash
npm run dev
```

Open the Downstream Fork Sync, Downstream Merge/Rebase Risk, and Downstream Agent Workflow panels. The local analyzer works in `.cache/repos` and temporary worktrees, and must not push or force-push by itself. Actual sync execution belongs to the CLI `sync` command and only runs after explicit flags.