README.md

<p align="center">
  <img src="docs/assets/logo.svg" width="128" alt="Repo Scout logo">
</p>

<h1 align="center">Repo Scout</h1>

<p align="center">
  <b>Find real engineering work in any repository. Evidence first. Zero findings is a valid answer.</b><br>
  <sub>An agent skill for <b>Claude Code</b>, <b>Codex CLI</b> and <b>Grok Build</b> · 中文名「裝忙 Skills」 · <a href="https://iml1s.github.io/repo-scout/">Website</a> · <a href="README.zh-TW.md">繁體中文說明</a></sub>
</p>

<p align="center">
  <a href="https://github.com/ImL1s/repo-scout/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ImL1s/repo-scout/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/ImL1s/repo-scout/releases"><img alt="Release" src="https://img.shields.io/github/v/release/ImL1s/repo-scout?display_name=tag&color=7C3AED"></a>
  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white">
  <img alt="Dependencies: none" src="https://img.shields.io/badge/dependencies-none-success">
  <a href="LICENSE"><img alt="GPL-3.0-or-later" src="https://img.shields.io/badge/license-GPL--3.0--or--later-blue"></a>
</p>

<p align="center">
  <img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-loader%20tested-D97757?logo=anthropic&logoColor=white">
  <img alt="Codex CLI" src="https://img.shields.io/badge/Codex%20CLI-loader%20tested-000000?logo=openai&logoColor=white">
  <img alt="Grok Build" src="https://img.shields.io/badge/Grok%20Build-loader%20tested-1D9BF0?logo=x&logoColor=white">
  <img alt="Grok Bot" src="https://img.shields.io/badge/Grok%20Bot-manual%20port-lightgrey">
</p>

---

Most "review my code" prompts look at a diff. **Repo Scout looks at the whole repository** — architecture, frontend, backend, mobile, systems, security, tests, CI, docs and AI-agent code — and turns it into a **prioritized, evidence-backed backlog** the way a careful senior engineer would on their first week.

It is deliberately allergic to busywork:

| A typical AI review | Repo Scout |
| --- | --- |
| Scans the latest diff | Maps modules, data flow and trust boundaries across the repo |
| Lists everything that *looks* off | Separates **reproduced bugs** from **source-proven issues** from **unverified risks** from **optional ideas** |
| Produces N items every time | **Zero findings is a legitimate result.** Limits are ceilings, never quotas |
| "Consider migrating to microservices" | A monolith, a long file or an old dependency is a *lead*, not a defect |
| Claims "tests pass" | Records exact command, cwd, commit, exit code — or says **NOT RUN** |
| Says "no duplicates" | Says *"dedup incomplete"* when it had no issue-tracker access |

## How it works

```text
inventory the project  →  pick applicable review lanes  →  hunt for candidates
      →  actively look for counter-evidence  →  verify proportionately
      →  dedupe against issues/PRs  →  rank  →  auditable report
```

Every retained finding carries a source location, trigger, impact, **evidence level (E0–E3)**, the alternative explanations that were checked, a minimal fix direction, acceptance criteria and its verification status. The report ends with a **coverage matrix** that says what was inspected, partially inspected, blocked or skipped — so you can trust the silence as much as the findings.

### Review lanes

| Lane | Looks for |
| --- | --- |
| **Architecture** | Module boundaries, state ownership, cancellation/failure propagation, frontend↔backend contract drift |
| **Web / frontend** | Loading · empty · error · retry states, double submits, navigation, a11y, locales, viewports |
| **Backend / data** | AuthZ, transactions, idempotent retries, pagination, migrations, backups, background jobs |
| **Mobile** | Android, iOS, Flutter, RN, KMP — lifecycle, process death, offline, permissions, platform parity |
| **Systems** | Desktop/CLI exit codes & paths, libraries/FFI, embedded protocols, wallets/contracts, games |
| **Security / privacy** | Trust boundaries, tenant isolation, secrets in logs, supply chain, prompt-injection surfaces |
| **Delivery / quality** | Tests that actually run, missing regression cases, CI wiring, README vs reality, releases |
| **AI agents / MCP / skills** | Tool permissions, duplicate side effects, sub-agent handoffs, retries, budgets, injection |

Lanes are loaded on demand from `skills/repo-scout/references/`, so an unrelated checklist never inflates a run.

### Evidence levels

| Level | Meaning |
| --- | --- |
| **E0** | Lead from names/patterns — never presented as confirmed |
| **E1** | Code-supported concern with concrete reachability; residual assumptions labelled |
| **E2** | Source-level proof of a violated invariant, explicitly *without* runtime reproduction |
| **E3** | Reproduced in a recorded environment with command and actual output |

Severity and certainty are tracked separately: a high-impact E1 can still be a P0 to investigate.

## Get it from a directory

| Host | Where | Status |
| --- | --- | --- |
| Codex / ChatGPT | [OpenAI Plugins Directory](https://chatgpt.com/plugins/plugins_6aa0595d1d1881918d6321ebc0d66b91) | published (0.1.0) |
| Claude Code | `anthropics/claude-plugins-community` | submitted, pending review |
| Grok Build | [xai-org/plugin-marketplace PR #622](https://github.com/xai-org/plugin-marketplace/pull/622) | PR open |

Until a directory lists it, the install routes below work from this repository directly.

## Install

Requires **Python 3.10+** and nothing else. The installer is **dry-run by default** and **never overwrites** an existing skill: since 0.1.2 it stages the copy next to the destination, writes a `.repo-scout-install.json` marker with per-file SHA-256, and publishes with a no-replace rename (it fails rather than falling back to a replacing move). The primitive is `renameat2(RENAME_NOREPLACE)` on Linux, `renamex_np(RENAME_EXCL)` on macOS and `MoveFileEx` without replace on Windows; some network, FUSE or overlay filesystems and very old kernels or C libraries reject it, and the installer then stops with an explicit error and leaves the destination untouched.

```bash
git clone https://github.com/ImL1s/repo-scout.git
cd repo-scout
python3 install.py --agent claude --apply   # → ~/.claude/skills/repo-scout
python3 install.py --agent codex  --apply   # → ~/.agents/skills/repo-scout
```

<details>
<summary><b>Upgrade an existing copy (the installer never overwrites)</b></summary>

1. Move the old copy **outside every skill discovery directory**, for example `mv ~/.claude/skills/repo-scout ~/repo-scout-backup-$(date +%F)`, so no host can still load it.
2. Install the new version: `python3 install.py --agent claude --apply`.
3. Start a **new** host session and confirm `/repo-scout` loads; `python3 install.py doctor` should show the copy as `managed`, `intact`, with the new version.
4. Handle the backup by hand once you are satisfied. There is no `uninstall` yet: deleting a directory just because it carries a marker could remove files you added or edited.
</details>

<details>
<summary><b>Which copies are installed? <code>install.py doctor</code></b></summary>

```bash
python3 install.py doctor                          # user scope: ~/.claude, ~/.agents, ~/.grok
python3 install.py doctor --project /path/to/repo  # also scan that project's .claude/.agents/.grok
```

Read-only. For every documented root it reports whether a copy exists, whether it is `managed` (carries the `.repo-scout-install.json` marker written by 0.1.2+), the version as `version_observed` (the copy's `VERSION` file) and `version_recorded` (the marker) with a `version_mismatch` flag (`version` is the observed value when both exist, else the recorded one, else `unknown`), SKILL.md and whole-payload SHA-256, integrity against the marker (`intact`; `modified`, listing missing, modified, extra and irregular entries; or `incomplete` when part of the copy could not be read, in which case the payload digest and the source comparison are `null`), whether it matches the source you ran it from, and leftover staging directories. Symlinks and Windows junctions are never followed: as a `.claude`, `skills` or `repo-scout` component they are reported as `symlink-not-followed`, inside a copy as irregular entries that keep it from being `intact`. It scans **known roots only** and cannot tell which copy a host actually loads (`active_copy: unknown`); check the host's own skill list in a new session for that.
</details>

<details>
<summary><b>Claude Code — as a plugin via <code>/plugin</code></b></summary>

```text
/plugin marketplace add ImL1s/repo-scout
/plugin install repo-scout@repo-scout
```

The plugin form is invoked as `/repo-scout:repo-scout`; the standalone skill is `/repo-scout`. Pick one, not both.
</details>

<details>
<summary><b>Codex CLI — as a plugin from this repo's marketplace</b></summary>

```bash
codex plugin marketplace add https://github.com/ImL1s/repo-scout.git
codex plugin add repo-scout@repo-scout
```

Invoke with `$repo-scout`. Pick either the plugin or the standalone skill, not both.
</details>

<details>
<summary><b>Grok Build</b></summary>

As a plugin:

```bash
grok plugin marketplace add ImL1s/repo-scout
grok plugin install repo-scout --trust
```

Grok Build also reads Claude Code skills automatically. If you installed with `--agent claude`, **you are done** — `/repo-scout` already shows up (verified on Grok Build 1.0.13; a second copy under `~/.grok/skills` may show up twice in the menu).

Without a Claude Code install:

```bash
python3 install.py --agent grok --apply     # → ~/.grok/skills/repo-scout
# or (documented by Grok, not tested here): grok plugin install ImL1s/repo-scout
```
</details>

<details>
<summary><b>Codex CLI — project scope</b></summary>

```bash
python3 install.py --agent codex --scope project --project /path/to/repo --apply
# → /path/to/repo/.agents/skills/repo-scout  (commit it to share with the team)
```
</details>

<details>
<summary><b>Grok Bot</b></summary>

Grok Bot manages skills through its own private-skill flow, not a local directory. Give the Bot the `skills/repo-scout` folder and use the prompt in [`examples/grok-bot-setup.zh-TW.md`](examples/grok-bot-setup.zh-TW.md) to have it save the workflow as a reusable private skill. This path is documented but **not yet verified end-to-end**.
</details>

## Use

Claude Code / Grok Build:

```text
/repo-scout mode=scan scope=all
Inventory every first-party module and target platform, then do a risk-driven review
covering architecture, frontend, backend/data, mobile, security, tests/CI and docs.
Do not modify code, run project scripts, open issues or trigger CI.
For each finding: location, impact, evidence level, counter-checks, acceptance criteria,
and what was NOT verified. Keep at most 10 items — count is not the goal.
```

Codex:

```text
$repo-scout mode=scan scope=all
Draft a backlog for this repo. Separate suspected from proven issues. Zero is fine.
```

`mode=scan | verify | plan | publish | fix` and `scope=all | changed | <path>` are **natural-language conventions** the skill interprets — not CLI flags. `scan` is the default and never writes, runs project commands, publishes or spends money. Everything else has to be explicitly authorized, and the skill still relies on your host's permission system as the real boundary.

More scenarios (focused mobile scan, planning from a report, authorized local verification): [`examples/usage.zh-TW.md`](examples/usage.zh-TW.md).

## What it will *not* do

- Pretend a filename inventory is a review. `scripts/inventory.py` reads **file names only** — no source, no manifests, no git, no network — and says so in its own output.
- Claim "all languages supported". The workflow is language-agnostic; parsers and runtime checks are whatever *your* repo already ships. Unknown stacks get a generic review and an explicit gap.
- Report iOS/UI/hardware verification from source reading. No Xcode → *blocked*, not *passed*.
- Turn itself into a scheduler, issue publisher or fix bot. Those need a host runner with scoped credentials, a state ledger and publication gates (see [`docs/roadmap.md`](docs/roadmap.md)).

## Verified so far

| Host | Version | Loading & reference resolution | Behavioral accuracy |
| --- | --- | --- | --- |
| Claude Code | 2.1.263 | ✅ `claude -p "/repo-scout …"` | ⏳ not yet measured |
| Codex CLI | 0.153.0 | ✅ `codex exec '$repo-scout …'` | ⏳ not yet measured |
| Grok Build | 1.0.13 | ✅ via the Claude Code skill directory | ⏳ not yet measured |
| Grok Bot | — | 📝 manual port documented | ⏳ |

Package tests: **103 unit tests**, run by CI on Linux, macOS and Windows for Python 3.10–3.14, covering traversal limits, exclusions, symlinks and Windows junctions, sensitive filenames, installer staging, no-replace publish and abrupt termination, `doctor` diagnostics, and the release acceptance script against deliberately damaged asset sets. Details and the smoke-test transcript summary: [`TEST-RESULTS.txt`](TEST-RESULTS.txt). The evaluation plan with a *no-skill control group* is in [`docs/evaluation.md`](docs/evaluation.md).

## Repository layout

```text
skills/repo-scout/
├── SKILL.md                     # the shared workflow (what every host loads)
├── references/                  # one file per review lane + evidence contract + tool profiles
├── assets/finding.template.json # machine-readable finding shape (example, not enforced)
├── scripts/inventory.py         # read-only, filename-only, bounded inventory helper
├── VERSION                      # version data that travels with every installed copy
└── agents/openai.yaml           # Codex display metadata, implicit invocation disabled
install.py                       # install (no-replace publish + marker) or `doctor` (read-only inventory)
scripts/                         # build_plugin_zip.py and release_acceptance.py (bundles + their acceptance run)
tests/                           # unit tests for the helper, installer and package integrity
.claude-plugin/ .codex-plugin/ .grok-plugin/ .agents/   # plugin + marketplace manifests per host
assets/                          # logo and composer icon used by directory listings
site/                            # website (GitHub Pages): landing, privacy, terms, support
submission/                      # directory-submission drafts, reviewer test cases and fixtures
docs/                            # compatibility notes, evaluation plan, roadmap, external reviews
examples/                        # prompts for common scenarios and the Grok Bot port
```

## Development

```bash
python3 -m unittest discover -s tests -v          # or: python3 -m pytest -q tests
python3 skills/repo-scout/scripts/inventory.py .  # exit 0 = complete, 2 = partial traversal
python3 skills/repo-scout/scripts/inventory.py . --include build/gen --exclude docs   # scope flags (see below)
python3 install.py --agent claude                 # dry-run: prints the plan, writes nothing
python3 install.py doctor                         # read-only: every copy under the known host roots
python3 scripts/release_acceptance.py             # build, unpack, install and exercise the bundles
claude plugin validate .                          # manifest check (needs Claude Code CLI)
```

Inventory scope flags are repeatable, repo-relative and `/`-separated (no absolute paths, no `..`; `foo` never matches `foobar`). Precedence, highest first: the root boundary, symlinks and Windows junctions (never followed), non-regular entries and hard sensitive names (`.ssh`, `.aws`, `.secrets`, `.gnupg`, `.env*`, key files) > `--exclude` > `--include` > convenience exclusions such as `node_modules`, `build`, `dist`, `vendor`. `--include` is **additive**: it re-admits a file or subtree under a convenience-excluded directory by passing through only the necessary ancestors. `--include DIR` re-admits the whole subtree; `--include DIR/file` re-admits just that file, and the other entries of the convenience-excluded ancestors it passes through are reported as `outside-include-scope`. Ordinary ancestors are unaffected (`--include src/gen.py` does not hide `src/other.py`). Flags that matched nothing are listed under `scope.include_unmatched` and `scope.exclude_unmatched`. Backslashes count as separators only on Windows. Components are literal: one with leading or trailing whitespace is rejected rather than trimmed, so `--exclude " private "` is an error and never a silent match of `private` (a trailing `/` is fine). An include under an exclude, or into a sensitive directory or file, is rejected up front. `.gitignore` is never read and the output says so (`gitignore_respected: false`).

CI runs the suite on Linux, macOS and Windows for Python 3.10–3.14, validates the plugin manifests and runs the release acceptance script from the unpacked bundles. Tagging `vX.Y.Z` (matching `.claude-plugin/plugin.json` and `skills/repo-scout/VERSION`) waits for a green CI run on that commit, builds the source archive (with an embedded `MANIFEST.sha256`) and the bundles, runs the acceptance script against exactly that asset set, re-resolves the remote tag and refuses to publish unless it still points at the commit that passed CI, then publishes the release (`gh release create --verify-tag`) with `SHA256SUMS`.

The acceptance script verifies the assets the release job has just built against the tagged commit (source archive equal to the commit's tree, plugin bundle a hash-equal subset of it, the skill byte-identical in all three archives, no bytecode, no directory entries, no extra fields, each local header naming the same member). It is not a general ZIP sanitizer: it trusts the central directory as `zipfile` does and compares only the name and extra-field length of each local header, so an archive crafted with inconsistent local records (method, CRC or size mismatch, orphan or concatenated records, mode bits) can be extracted differently, or as garbage, by other extractors. For assets you download, verify `repo-scout-vX.Y.Z.zip.sha256` and `SHA256SUMS`; that is the integrity binding.

## Roadmap

- **v0.1.2** (shipped) — no-replace installer with an install marker, `install.py doctor`, additive `--include`/`--exclude` scope flags (no `.gitignore` parsing by design), release acceptance from the unpacked bundles. `uninstall` stays deferred.
- **v0.2** — behavioral evals with a no-skill control group on seeded-defect fixtures; snapshot/content-hash binding for evidence; a real-project case study.
- **v0.3** — optional continuous mode: run ledger, incremental scope, overlap locks, cost caps, publication reconciliation.

Full reasoning in [`docs/roadmap.md`](docs/roadmap.md).

## Contributing

Issues and PRs are welcome. Keep the spirit: **no manufactured findings, no unverified success claims.** If you add a lane or a check, add the counter-evidence question that keeps it honest.

## License

[GPL-3.0-or-later](LICENSE) © 2026 ImL1s

Repo Scout is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Versions up to and including v0.1.0 (the tagged release, its zip assets and the 0.1.0 bundle in the OpenAI directory) were released under the MIT License and remain available under it; this and every later commit is GPL-3.0-or-later.