@humanbased/crosscheck 0.14.0

package/AGENT.md

@@ -0,0 +1,207 @@
+# AGENT.md — crosscheck optimize harness
+
+You are improving crosscheck's AI code review instructions. crosscheck runs `codex` and
+`claude` CLIs to review pull requests automatically. Both reviewers read
+`~/.crosscheck/instructions.md` before every review. Your job is to read the diagnostic
+report below and produce an improved `instructions.md` that increases review quality and
+reduces failures.
+
+> **Note:** `crosscheck optimize` selects which agent runs you based on your local config
+> and log history — whichever reviewer has the highest success rate, or `claude` if there
+> is no data. The instructions you produce are reviewer-agnostic: they are read by both
+> `claude` and `codex`, so write in plain language that both understand.
+
+---
+
+## Input you will receive
+
+1. **Diagnostic JSON** from `crosscheck diagnose --json` — error patterns, review outcomes,
+   repos seen, language signals, and suggestions.
+2. **Current `instructions.md`** — may be empty on first run.
+
+## Output you must produce
+
+Respond with only the new content of `instructions.md`. No explanation, no preamble, no
+markdown fences — just the file content. The file uses plain Markdown.
+
+---
+
+## Required sections (always present)
+
+### `## Constraints`
+What reviewers must NOT do. Each constraint is one bullet:
+```
+- Do not run [specific command].
+```
+
+### `## Focus`
+What reviewers should prioritize. Free-form prose or bullets.
+
+### `## Verdict format` (never modify this section)
+This section must always be preserved exactly as written in the current file. If it is
+missing from the current file, add it verbatim:
+
+```markdown
+## Verdict format
+
+On the very last line of your response, write exactly one of:
+
+VERDICT: APPROVE
+VERDICT: NEEDS WORK
+VERDICT: BLOCK
+
+Use APPROVE for no issues or trivial nits only.
+Use NEEDS WORK for addressable issues that are not blocking.
+Use BLOCK for security risks, data loss, broken API contracts, or correctness bugs.
+```
+
+---
+
+## Rules for the `## Constraints` section
+
+### Add a constraint when
+- `diagnostic.errors` contains a `command_not_found` pattern with `count >= 1` for a
+  specific command.
+- `diagnostic.errors` contains a `timeout` pattern with `count >= 2` for a reviewer that
+  is also producing `command_not_found` entries (likely spinning on a failed tool call).
+
+### Remove a constraint when
+- It was previously added for a specific command but that command no longer appears in
+  `diagnostic.errors` and has not appeared for the full log period analyzed.
+
+### Phrasing rules
+- Use the exact command name, not a category. Write `Do not run tsc.` not `Do not run
+  TypeScript build tools.`
+- One command per bullet. Do not combine: `Do not run tsc or npm.` → split into two.
+- Do not restrict reading. `Do not open package.json` is wrong. Constraints are for
+  execution only.
+- Do not restrict security analysis. Never add a constraint that would prevent a reviewer
+  from flagging a vulnerability.
+
+---
+
+## Language detection → constraint mapping
+
+Use `diagnostic.languages_detected` (list of detected language/tool identifiers) to seed
+the initial constraints. Add the corresponding constraint only if the language is detected
+AND a related `command_not_found` error is present OR this is the first run with no
+existing constraints.
+
+| Detected signal | Constraint to add |
+|---|---|
+| `typescript` / `tsconfig.json` / `package.json` | `Do not run tsc.` |
+| `nodejs` / `package.json` | `Do not run npm, npx, yarn, or pnpm.` |
+| `jest` / `vitest` in devDependencies | `Do not run jest or vitest.` |
+| `python` / `requirements.txt` / `pyproject.toml` | `Do not run pytest, pip, or python scripts.` |
+| `rust` / `Cargo.toml` | `Do not run cargo build or cargo test.` |
+| `go` / `go.mod` | `Do not run go build or go test.` |
+| `java` / `pom.xml` | `Do not run mvn.` |
+| `kotlin` / `gradle` / `build.gradle` | `Do not run gradle.` |
+| `ruby` / `Gemfile` | `Do not run bundle exec or rspec.` |
+
+Do not add constraints for languages not detected. Do not add all of the above blindly.
+
+---
+
+## Rules for the `## Focus` section
+
+### Update focus when
+- `diagnostic.verdict_distribution.APPROVE` percentage > 80% across >= 10 reviews → reviews
+  may be too lenient → add: "Apply strict scrutiny to error handling and edge cases."
+- `diagnostic.verdict_distribution.BLOCK` percentage > 30% across >= 10 reviews → reviews
+  may be too strict → add: "Prefer NEEDS WORK over BLOCK unless the issue causes data loss
+  or a security vulnerability."
+- `diagnostic.repos_seen` consistently includes infrastructure repos (name contains
+  `-infra`, `-deploy`, `-k8s`) → add: "Pay extra attention to secrets, env vars, and IAM
+  permissions in infrastructure changes."
+
+### Default focus (use when no signals override it)
+```markdown
+## Focus
+
+Review for correctness, security, and maintainability. Flag issues that would cause bugs
+in production, expose sensitive data, or make the code significantly harder to maintain.
+Nits and style preferences should be NEEDS WORK, not BLOCK.
+```
+
+---
+
+## Quality principles
+
+1. **Minimal** — fewer instructions produce better reviews. Each line must earn its place.
+2. **Specific** — exact command names, concrete criteria, not vague categories.
+3. **Evidence-based** — add only what the diagnostic shows is needed or what language
+   detection justifies.
+4. **Reversible** — stale constraints (no matching errors in the log period) should be
+   removed, not accumulated.
+5. **Reviewer-agnostic** — these instructions are read by both `codex` and `claude`. Write
+   them in plain language that both understand.
+
+---
+
+## What must never change
+
+- The `## Verdict format` section content and label.
+- Instructions that the user has manually annotated with `<!-- keep -->`.
+- The overall Markdown structure (## headings, bullet lists).
+
+---
+
+## Worked example
+
+### Input diagnostic (excerpt)
+```json
+{
+  "summary": { "total_reviews": 6, "successful": 3, "failed": 3, "failure_rate": 0.5 },
+  "errors": [
+    { "pattern": "command_not_found", "command": "tsc", "count": 2, "reviewer": "codex" },
+    { "pattern": "command_not_found", "command": "jest", "count": 1, "reviewer": "codex" },
+    { "pattern": "base_branch_missing", "branch": "staging", "count": 2 }
+  ],
+  "verdict_distribution": { "APPROVE": 2, "NEEDS_WORK": 1, "BLOCK": 0 },
+  "languages_detected": ["typescript", "nodejs"],
+  "suggestions": [
+    { "type": "add_constraint", "instruction": "Do not run tsc.", "reason": "tsc not found ×2" },
+    { "type": "add_constraint", "instruction": "Do not run jest.", "reason": "jest not found ×1" }
+  ]
+}
+```
+
+### Input current instructions.md
+```markdown
+## Verdict format
+
+On the very last line of your response, write exactly one of:
+...
+```
+
+### Correct output
+```markdown
+## Constraints
+
+- Do not run tsc.
+- Do not run jest.
+- Do not run npm, npx, yarn, or pnpm.
+
+## Focus
+
+Review for correctness, security, and maintainability. Flag issues that would cause bugs
+in production, expose sensitive data, or make the code significantly harder to maintain.
+Nits and style preferences should be NEEDS WORK, not BLOCK.
+
+## Verdict format
+
+On the very last line of your response, write exactly one of:
+
+VERDICT: APPROVE
+VERDICT: NEEDS WORK
+VERDICT: BLOCK
+
+Use APPROVE for no issues or trivial nits only.
+Use NEEDS WORK for addressable issues that are not blocking.
+Use BLOCK for security risks, data loss, broken API contracts, or correctness bugs.
+```
+
+Note: `Do not run npm, npx, yarn, or pnpm.` was added because `nodejs` was detected, even
+though no npm error appeared yet — this is the language-detection pre-emptive path for
+first-run seeding.

package/ISSUE.md

@@ -0,0 +1,234 @@
+# ISSUE.md — crosscheck issue analysis harness
+
+You are analyzing `~/.crosscheck/logs/*.ndjson` to find bugs and improvement opportunities
+in the crosscheck project and draft GitHub issues for `Motivation-Labs/crosscheck`.
+
+Your job is to surface patterns that a simple error-count approach would miss: session
+instability, tunnel failure modes, process crash loops, and reliability regressions.
+
+---
+
+## Log schema
+
+Each line in a `.ndjson` file is one JSON event with at minimum:
+
+```
+{ "ts": "<ISO-8601 UTC>", "level": "info|warn|error", "event": "<name>", ...fields }
+```
+
+### Events that matter most
+
+| Event | Key fields | Meaning |
+|---|---|---|
+| `session_start` | `command` | A new watch/serve process started |
+| `session_end` | — | Process exited cleanly (graceful shutdown) |
+| `tunnel_opened` | `url` | Tunnel is live; url is `lhr.life` or `smee.io` |
+| `tunnel_closed` | `reconnecting: bool` | Tunnel dropped; reconnecting if true |
+| `tunnel_error` | `message` | SSH failure; message contains "did not start within" (timeout) or "exit (code 255)" (hard exit) |
+| `webhook_registered` | `repo` | Webhook confirmed active |
+| `webhook_register_retry` | — | Webhook registration retrying |
+| `webhook_error` | `message` | Webhook registration failed |
+| `pr_received` | `repo`, `pr` | Incoming PR event |
+| `review_started` | `reviewer`, `pr` | Review agent invoked |
+| `review_complete` | `verdict`, `duration_ms` | Review finished |
+| `verdict_parse_failed` | — | Agent output did not contain a parseable VERDICT line |
+| `error` | `message` | Any runtime error |
+
+---
+
+## How to compute sessions
+
+Split all log entries on `session_start` events. Each session is the slice of events
+from one `session_start` up to (but not including) the next `session_start`.
+
+For each session compute:
+
+| Field | How |
+|---|---|
+| `duration_min` | `(last_event.ts - session_start.ts)` in minutes |
+| `clean_exit` | Session contains a `session_end` event |
+| `tunnel_opened` | Any `tunnel_opened` event present |
+| `tunnel_type` | `"lhr.life"` / `"smee.io"` / `"none"` from tunnel url |
+| `tunnel_error_count` | Count of `tunnel_error` events |
+| `ssh_timeout_count` | `tunnel_error` where message contains `"did not start within"` |
+| `ssh_255_count` | `tunnel_error` where message contains `"255"` |
+| `reconnect_count` | `tunnel_closed` events where `reconnecting: true` |
+| `webhook_registered` | Any `webhook_registered` event present |
+| `pr_received` | Any `pr_received` event present |
+| `review_completed` | Any `review_complete` event present |
+| `error_count` | Events where `level == "error"` |
+
+---
+
+## Analysis 1 — Session stability
+
+Compute per-session stats and then aggregate.
+
+**Aggregate metrics to report:**
+- Total sessions, total days covered
+- Average / median session lifespan (minutes)
+- % sessions with clean exit (`session_end` present)
+- % sessions where tunnel never opened
+- % sessions where webhook was never registered
+- Longest and shortest session
+
+**Thresholds that indicate a reportable problem:**
+
+| Condition | Severity | Report type |
+|---|---|---|
+| avg session lifespan < 15 min across any single day | high | bug |
+| > 40% of sessions never reach `tunnel_opened` | high | bug |
+| > 50% of sessions have no `session_end` (abrupt death) | medium | improvement |
+| ≥ 5 sessions in any 90-minute window all under 5 min | high | bug — rapid restart loop |
+| > 30% of sessions have no `webhook_registered` | medium | improvement |
+
+---
+
+## Analysis 2 — Tunnel reliability
+
+**Aggregate metrics:**
+- Count of `tunnel_opened`, `tunnel_closed`, `tunnel_error` across all sessions
+- SSH timeout count vs SSH code-255 count (from `tunnel_error` messages)
+- Reconnect rate: `reconnect_count / tunnel_closed_count`
+- Terminal close rate: `tunnel_closed` where `reconnecting: false`
+- % of sessions that never reached `tunnel_opened`
+
+**Key insight to encode:** Sessions that accumulate many tunnel errors and reconnects
+can still survive long — the reconnect logic is working. The real kill signal is
+`tunnel_opened == false`, not high `tunnel_error_count`.
+
+**Thresholds:**
+
+| Condition | Severity | Report type |
+|---|---|---|
+| SSH timeout rate > 60% of tunnel errors | high | bug — connectivity or lhr.life instability |
+| SSH code-255 rate > 20% of tunnel errors | high | bug — SSH process crash |
+| Terminal close rate > 30% of tunnel closes | high | bug — tunnel not recovering |
+| > 40% sessions never open a tunnel | high | bug |
+
+---
+
+## Analysis 3 — Process health (crash loops)
+
+This is distinct from tunnel failure. A process crash loop has these signatures:
+- Rapid session restarts (≥ 5 sessions in 90 minutes)
+- Sessions dying before `tunnel_opened` with **zero** tunnel errors
+- `error` events containing `gh repo clone`, `Command failed`, or `ENOENT`
+- Sessions with normal `tunnel_error_count` but very short lifespan
+
+**What to look for:**
+- Cluster rapid-restart windows: sessions where `duration_min < 5` AND `tunnel_opened == false`
+  AND `tunnel_error_count == 0`. These are process crashes, not connectivity failures.
+- Extract the `error` event messages from those sessions to identify the root cause.
+- Check if `verdict_parse_failed` or `webhook_error` events appear in the final 60 seconds
+  of abrupt-death sessions — these indicate the review or webhook path is triggering exits.
+
+**Thresholds:**
+
+| Condition | Severity | Report type |
+|---|---|---|
+| ≥ 5 sessions: duration < 5 min AND tunnel_opened=false AND tunnel_errors=0 | critical | bug — startup crash loop |
+| `gh repo clone` in any error message | high | bug — clone failure |
+| `verdict_parse_failed` in final 60s of > 20% abrupt-death sessions | medium | improvement — VERDICT format reliability |
+
+---
+
+## The two failure modes (always distinguish these in your report)
+
+**Mode A — Tunnel failure:** Sessions die because SSH connectivity fails and the tunnel
+never comes up. Signals: `ssh_timeout_count > 0` OR `ssh_255_count > 0` in failed sessions.
+Root cause: network, lhr.life instability, or SSH configuration.
+
+**Mode B — Process crash:** Sessions die fast with zero tunnel errors. The process exits
+before even attempting a tunnel. Signals: `duration_min < 3`, `tunnel_opened = false`,
+`tunnel_error_count = 0`, error messages about `gh`, `clone`, `ENOENT`, or similar.
+Root cause: code bug, missing dependency, bad config, or file system issue.
+
+Never combine these two modes in a single issue. They have different root causes and
+different fixes.
+
+---
+
+## Improvement opportunities (not bugs)
+
+File an improvement issue when the system is working but data shows a reliability gap:
+
+| Pattern | Issue title pattern | Label |
+|---|---|---|
+| avg session lifespan 15–30 min (should be hours) | `watch: improve session longevity — avg Xmin` | `improvement` |
+| smee.io has 0 tunnel errors but lhr.life does not | `watch: add smee.io as automatic tunnel fallback` | `improvement` |
+| Reconnect works but adds latency | `tunnel: reduce reconnect gap when lhr.life drops` | `improvement` |
+| `webhook_registered` strongly predicts session survival | `watch: surface webhook status earlier in startup sequence` | `improvement` |
+| `verdict_parse_failed` events in logs | `review: harden VERDICT line parsing — N parse failures found` | `improvement` |
+
+---
+
+## Output format
+
+For each issue you file, output exactly:
+
+```
+TITLE: <concise title under 80 characters>
+LABELS: <comma-separated: bug, improvement, priority:high, priority:low>
+---
+<GitHub-flavored markdown body>
+```
+
+### Required body sections
+
+**For bugs:**
+```markdown
+## Summary
+One paragraph describing the failure pattern and impact on the user.
+
+## Evidence from logs
+Exact metrics from your analysis (counts, percentages, session table if relevant).
+Use a code block for representative raw log entries — sanitize any PII or tokens.
+
+## Failure mode
+State clearly: Mode A (tunnel failure) or Mode B (process crash), and why.
+
+## Reproduction signals
+What log patterns indicate this bug is active. How to check if it's happening.
+
+## Suggested fix direction
+One sentence on where in the codebase to look. Do not prescribe the implementation.
+
+## Environment
+crosscheck version (from log entries if present), platform, date range analyzed.
+```
+
+**For improvements:**
+```markdown
+## Summary
+One paragraph describing the opportunity and expected benefit.
+
+## Evidence from logs
+The metrics that surfaced this opportunity.
+
+## Current behavior vs desired behavior
+Two-line contrast: what happens now, what should happen instead.
+
+## Suggested approach
+One paragraph, high level. Do not write code.
+```
+
+---
+
+## What NOT to report
+
+- Single-occurrence errors with no clear pattern
+- Events that are expected (e.g., one `tunnel_closed` followed immediately by `tunnel_opened`)
+- Issues already covered by an existing `crosscheck diagnose` error pattern
+  (`command_not_found`, `base_branch_missing`, `timeout`, `auth_failure`)
+- Anything requiring access to source code you were not given — stay in the log data
+
+---
+
+## Prioritization
+
+If you find multiple issues, report them in this order:
+1. Startup crash loops (Mode B, critical) — they prevent any work from happening
+2. Tunnel-never-opens rate > 40% (Mode A, high) — degrades session reliability
+3. Short average session lifespan (< 15 min/day) — signals chronic instability
+4. Improvement opportunities — after bugs are covered

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 Motivation Labs LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+<div align="right">
+  <h5><a href="./README.zh.md">🌏 &nbsp;中文</a></h5>
+</div>
+
+<p align="center">
+  <img src="./assets/logo.png" alt="crosscheck" width="160" />
+</p>
+
+<p align="center"><em>Building crosscheck with crosscheck.</em></p>
+
+# crosscheck
+
+<p align="center">
+  <img src="./assets/screenshot-watch.png" alt="crosscheck watch — live pipeline view" width="860" />
+</p>
+
+**Auto Code Review Pipeline — customizable PR → Review → Fix → Recheck loop, single-vendor or cross-vendor, zero new infrastructure.**
+
+Define the review pipeline in `workflow.yml`: review-only, review + fix, or the full review + fix + recheck cycle. Each step runs through the `claude` or `codex` CLI against your existing subscriptions — no API keys, no per-review cost.
+
+---
+
+## Quick start
+
+```bash
+# 1. Install crosscheck and the agent CLIs
+npm install -g @humanbased/crosscheck
+npm install -g @anthropic-ai/claude-code && claude        # Claude Pro/Max subscription
+npm install -g @openai/codex && codex login --device-auth # ChatGPT Plus/Pro subscription
+brew install gh && gh auth login                          # GitHub CLI
+
+# 2. Guided setup — repos, review mode, workflow pipeline
+crosscheck onboard
+
+# 3. Start watching
+crosscheck watch        # personal laptop
+crosscheck serve        # always-on team server
+```
+
+---
+
+## Commands
+
+### `crosscheck onboard`
+
+Interactive setup wizard. Picks repos/orgs to monitor, selects single-vendor or cross-vendor mode, configures the review pipeline, and writes `~/.crosscheck/config.yml` and `workflow.yml`.
+
+```bash
+crosscheck onboard              # guided setup
+crosscheck onboard --personal   # skip persona prompt, go straight to personal mode
+crosscheck onboard --team       # skip persona prompt, go straight to team mode
+crosscheck onboard -y           # accept all defaults non-interactively
+```
+
+---
+
+### `crosscheck watch`
+
+Personal mode. Starts an SSH tunnel (localhost.run), registers GitHub webhooks, and listens for PR events. Everything self-cleans on Ctrl+C.
+
+```bash
+crosscheck watch
+crosscheck watch --no-backtrace       # skip startup scan for unreviewed open PRs
+crosscheck watch --reconfigure        # re-run deployment setup before starting
+```
+
+---
+
+### `crosscheck serve`
+
+Team mode. Binds to a fixed port — register the webhook once, cover the whole team. Designed for a mac-mini or home server.
+
+```bash
+crosscheck serve
+crosscheck serve --no-backtrace       # skip startup scan
+crosscheck serve --personal           # personal scope this session only
+crosscheck serve --reconfigure        # re-run deployment setup
+```
+
+---
+
+### `crosscheck review <pr-url>`
+
+One-shot review of a single PR. Clones, checks out, reviews, and posts the comment.
+
+```bash
+crosscheck review https://github.com/org/repo/pull/42
+crosscheck review <pr-url> --reviewer claude    # force Claude regardless of detection
+crosscheck review <pr-url> --reviewer codex     # force Codex regardless of detection
+```
+
+---
+
+### `crosscheck run <pr-url>`
+
+Runs the full configured workflow against one PR: review → fix → recheck. Same logic as `watch`/`serve`, but triggered manually.
+
+```bash
+crosscheck run <pr-url>
+crosscheck run <pr-url> --steps review           # only the review step
+crosscheck run <pr-url> --steps fix,recheck      # skip initial review
+crosscheck run <pr-url> --reviewer claude        # override reviewer assignment
+crosscheck run <pr-url> --dry-run                # review without posting or fixing
+```
+
+---
+
+### `crosscheck scan`
+
+Scans every open PR in the configured monitor scope and reports where each one is in the crosscheck workflow. Results are cached for 60 seconds.
+
+States: `PR` (needs review) · `APPROVE` · `NEEDS_WORK` · `BLOCK` · `RECHECK` (fix applied, needs recheck)
+
+```bash
+crosscheck scan                          # all open PRs, grouped stale/not-stale
+crosscheck scan --tidy                   # stale actionable rows only
+crosscheck scan --stale-after 4h         # custom staleness threshold (default 24h)
+crosscheck scan --force                  # bypass cache
+crosscheck scan --json                   # machine-readable output
+```
+
+---
+
+### `crosscheck kickass`
+
+Selects stale PRs from the operator queue and advances them — runs `scan` first, presents a multi-select picker, shows a preflight summary, then executes after confirmation.
+
+```bash
+crosscheck kickass                       # interactive operator queue
+crosscheck kickass --dry-run             # preflight only — no mutations
+crosscheck kickass --stale-after 2h      # tighter staleness threshold
+crosscheck kickass --force               # bypass scan cache before picking
+```
+
+Actions: `PR → CR` · `NEEDS_WORK/BLOCK → Fix` · `FIX/RECHECK → Recheck` · `APPROVE → Merge`
+
+---
+
+## Configuration
+
+### Review depth (`quality.tier`)
+
+```yaml
+# crosscheck.config.yml
+quality:
+  tier: balanced    # fast | balanced | thorough
+```
+
+| Tier | Claude model | Codex model | Latency |
+|---|---|---|---|
+| `fast` | Haiku | default | ~10s |
+| `balanced` | Sonnet (default) | default | ~30s |
+| `thorough` | Opus | default | ~60s |
+
+### Pipeline (`workflow.yml`)
+
+```yaml
+steps:
+  - name: review
+    type: review
+    reviewer: auto          # auto | claude | codex | origin
+
+  - name: fix
+    type: fix
+    reviewer: origin
+    when: review.verdict != 'APPROVE'
+
+  - name: recheck
+    type: recheck
+    reviewer: auto
+    when: fix.applied_count > 0
+```
+
+### Config snapshot
+
+```yaml
+# ~/.crosscheck/config.yml
+orgs:
+  - your-org
+
+routing:
+  allowed_authors:
+    - your-github-login
+
+mode: cross-vendor          # cross-vendor | single-vendor
+
+vendors:
+  claude:
+    enabled: true
+  codex:
+    enabled: true
+
+quality:
+  tier: balanced
+
+clone_protocol: ssh         # ssh (default) | https
+```
+
+Full reference: [get-started.md](./get-started.md)
+
+---
+
+## Requirements
+
+| | Minimum |
+|---|---|
+| Node.js | 18+ |
+| Claude Code CLI | latest — `npm install -g @anthropic-ai/claude-code` |
+| Codex CLI | latest — `npm install -g @openai/codex` |
+| GitHub CLI | 2.65+ — `brew install gh` |
+
+`GITHUB_TOKEN` is derived automatically from `gh auth login`. No manual export needed.
+
+---
+
+## Documentation
+
+| | |
+|---|---|
+| **[get-started.md](./get-started.md)** | Full setup guide — prerequisites, all flags, complete config reference, FAQ |
+| **[crosscheck.config.example.yml](./crosscheck.config.example.yml)** | Annotated config with every option |
+| **[CHANGELOG.md](./CHANGELOG.md)** | Release notes |
+
+---
+
+## Contributing
+
+Issues and PRs welcome at [github.com/humanbased-ai/crosscheck](https://github.com/humanbased-ai/crosscheck).
+
+---
+
+## License
+
+[MIT](./LICENSE) — Copyright (c) 2025–2026 HumanBased AI.