From c24de9e9f47f3a138d10a33fd6bd11d31ab27adc Mon Sep 17 00:00:00 2001 From: alexander-sei Date: Tue, 4 Aug 2026 00:16:46 +0200 Subject: [PATCH 1/2] Integrate UCI: AI review, AI assistant, and stale check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This repo had no CI at all, so these are its first workflows. They adopt the same UCI reusable workflows sei-chain calls, wired to the subset that applies to a docs/skill repo — go-lint, go-test, and goreleaser have no Go to act on, release-check/release-publish key off a version.json this repo doesn't have, and backport needs release/** branches that don't exist here. All three callers pin UCI v0.0.15, the latest release. The AI workflows pin the release commit rather than the tag, and pass the same SHA as uci-ref: v0.0.14 moved the shared prompts from .github/seidroid to .github/seidroid/auto-review, so a uses:/uci-ref mismatch would silently fail to load them. Two deliberate differences from sei-chain's callers: - enable-cursor: false, because Cursor's built-in Bugbot already reviews PRs on this repo and the scout would duplicate it. Same reason sei-chain disables it. - The pull_request trigger adds labeled/unlabeled so the `ai: skip-review` label takes effect immediately instead of on the next push. UCI's preflight gate only runs on those two actions when the changed label is the skip label, so unrelated label edits don't queue extra reviews. REVIEW.md carries the repo-specific review standards that ai-review loads from the PR's base branch. Since the product here is prose other agents consume as ground truth, it puts factual accuracy first — the categories that have actually regressed before are gas values, hardware and toolchain requirements, and explorer references. It also documents two silent failure modes in install.sh: a reference file not linked from a SKILL*.md is dropped from every flattened agent install because the file list is grepped out of the entry point, and the awk frontmatter strip mis-slices rather than erroring on malformed frontmatter. Before the AI workflows can run, the seidroid GitHub App needs installing on this repo with read access to sei-protocol/uci, and the PLATFORM_CODE_AGENT secrets and org variables need to be in scope for sei-skill. The `ai: skip-review` label does not exist here yet. Co-authored-by: Cursor --- .github/workflows/ai-assist.yml | 22 +++++ .github/workflows/ai-review.yml | 20 +++++ .github/workflows/uci-stale-check.yml | 24 ++++++ REVIEW.md | 112 ++++++++++++++++++++++++++ 4 files changed, 178 insertions(+) create mode 100644 .github/workflows/ai-assist.yml create mode 100644 .github/workflows/ai-review.yml create mode 100644 .github/workflows/uci-stale-check.yml create mode 100644 REVIEW.md diff --git a/.github/workflows/ai-assist.yml b/.github/workflows/ai-assist.yml new file mode 100644 index 0000000..b21cd3f --- /dev/null +++ b/.github/workflows/ai-assist.yml @@ -0,0 +1,22 @@ +name: AI Assistant +on: + issue_comment: + types: [ created ] + pull_request_review_comment: + types: [ created ] + pull_request_review: + types: [ submitted ] +jobs: + assistant: + # See: https://github.com/sei-protocol/uci/releases/tag/v0.0.15 + uses: sei-protocol/uci/.github/workflows/ai-assistant.yml@65901242783550521f25a19199a6b10e54550b97 + permissions: + contents: read + pull-requests: write + issues: write + id-token: write + secrets: inherit + with: + # See: https://github.com/sei-protocol/uci/releases/tag/v0.0.15 + uci-ref: 65901242783550521f25a19199a6b10e54550b97 + allowed-team: 'sei-protocol/sei-core' diff --git a/.github/workflows/ai-review.yml b/.github/workflows/ai-review.yml new file mode 100644 index 0000000..7413f69 --- /dev/null +++ b/.github/workflows/ai-review.yml @@ -0,0 +1,20 @@ +name: AI Review +on: + pull_request: + # `labeled`/`unlabeled` let the `ai: skip-review` label take effect immediately rather + # than on the next push. UCI ignores those two events for every other label. + types: [ opened, ready_for_review, synchronize, reopened, labeled, unlabeled ] +jobs: + ai-review: + # See: https://github.com/sei-protocol/uci/releases/tag/v0.0.15 + uses: sei-protocol/uci/.github/workflows/ai-review.yml@65901242783550521f25a19199a6b10e54550b97 + permissions: + contents: read + pull-requests: write + checks: write + id-token: write + secrets: inherit + with: + # See: https://github.com/sei-protocol/uci/releases/tag/v0.0.15 + uci-ref: 65901242783550521f25a19199a6b10e54550b97 + enable-cursor: false # Disabled for now since there is a dedicated Bugbot flow built into Cursor currently enabled on repo. diff --git a/.github/workflows/uci-stale-check.yml b/.github/workflows/uci-stale-check.yml new file mode 100644 index 0000000..1421fec --- /dev/null +++ b/.github/workflows/uci-stale-check.yml @@ -0,0 +1,24 @@ +name: UCI +run-name: UCI / Stale Check + +on: + workflow_dispatch: + schedule: + - cron: '0 12 * * *' + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.sha }} + cancel-in-progress: true + +jobs: + stale: + name: Stale + permissions: + issues: write + pull-requests: write + uses: sei-protocol/uci/.github/workflows/stale-check.yml@v0.0.15 + with: + days-before-pr-stale: 28 diff --git a/REVIEW.md b/REVIEW.md new file mode 100644 index 0000000..66385a3 --- /dev/null +++ b/REVIEW.md @@ -0,0 +1,112 @@ +# Review guidelines for AI agents + +Repo-specific conventions for automated PR review (Codex, Cursor, Claude, and +any other AI reviewer). This repo ships **prose that other AI agents consume as +ground truth**, not a running service: the `skill/` tree is the product, and +`install.sh` is the only executable of consequence. Calibrate accordingly — a +wrong number in a markdown table is a higher-severity defect here than it would +be in a normal codebase, and style nits on reference prose are near-worthless. + +## 1. Factual accuracy about Sei is the primary correctness axis + +Every concrete claim in `skill/**` gets replayed to users by an agent that +cannot check it. The highest-value finding in this repo is a Sei fact that is +wrong or stale. Scrutinise added or changed: + +- chain IDs, network names, and `evm_chain_id` values, +- contract, precompile, and pointer addresses, +- gas costs and fee/denom values, +- RPC, explorer, faucet, and docs URLs, +- hardware, Node/Go, and toolchain version requirements, +- CLI flags and subcommands for `seid`, Foundry, and Hardhat. + +Real regressions have shipped in each of those categories, so treat them as +load-bearing rather than incidental. + +You usually cannot settle a network fact from the diff alone. When a value +looks suspect, **ask for the authoritative source rather than asserting the +value is wrong** — link to what you checked (`docs.sei.io`, `sei-chain`, +Seiscan) and say what disagrees. An unsourced numeric or version change to an +existing documented value is worth raising on its own. + +Prefer official Sei sources over third-party aggregators. This repo migrated +off Seitrace in favour of Seiscan (Sourcify) for verification flows; flag new +Seitrace references as regressions. + +## 2. A new reference file must be linked from `skill/SKILL.md` + +`install.sh` does not carry a file manifest. In flatten mode it discovers +reference files by grepping the selected variant entry point for +`references/**.md` paths: + +```bash +grep -Eo 'references/[^)"[:space:]]+\.md' "$SOURCE_DIR/$VARIANT_FILE" | sort -u +``` + +So a file added under `skill/references/` but not linked from a `SKILL*.md` +entry point is **silently omitted** from every flattened agent install +(`--agent cursor`, `--agent codex`, `--flatten`, …) while still appearing in the +Claude Code directory install, which copies the whole tree. That asymmetry is +invisible in CI and in the diff. + +The invariant to check: every file under `skill/references/` is linked from +`skill/SKILL.md` (the full variant), **and** from each domain variant +(`SKILL-CONTRACTS.md`, `SKILL-FRONTEND.md`, `SKILL-ECOSYSTEM.md`) it belongs +to. Flag an added reference file that no entry point links, and flag a renamed +or moved reference whose links were not updated — a stale link degrades to a +missing file rather than an error, since the append loop skips paths that do not +exist. + +## 3. YAML frontmatter on `SKILL*.md` is load-bearing + +Two consumers parse it: + +- `install.sh` strips frontmatter with awk by discarding everything up to the + **second** `---` line. There is no check that those two lines actually + delimit a frontmatter block, so an entry point whose frontmatter is malformed + or missing silently mis-slices — output starting at some later horizontal + rule, or an empty file if fewer than two `---` lines remain. It never fails + loudly. Any edit to the opening `---`/`name`/`description` block deserves a + close look. +- `tests/run.ts` reads `name` and `description` out of the frontmatter and + scores whether an agent selects the skill for a given prompt. + +The `description` field is the skill's trigger surface: it is a long list of +paraphrased user requests, and trimming it changes activation behaviour even +though nothing about it looks like code. Treat a shortened or reworded +`description` as a behavioural change and say which prompts it may stop +matching. + +## 4. `install.sh` portability constraints + +The README commits to macOS, Linux, Git Bash on Windows, and WSL. That means: + +- **bash 3.2 compatible** — macOS ships bash 3.2. No `mapfile`/`readarray`, no + associative arrays (`declare -A`), no `${var,,}` case conversion. The script + is currently clean of all of these; keep it that way. +- **no GNU-only flags** — coreutils on macOS and Git Bash are BSD/MinGW. +- The script runs under `set -e` only. If you flag a missing `set -u` or + `pipefail`, note that adding them is a behavioural change to every path, not a + free hardening win. + +Also check that a new `--agent` target sets `AGENT_DEFAULT_OUTPUT`, is listed in +both `--help` and the `Supported agents` error string, and is documented in the +README table — the four are updated by hand and drift silently. + +## 5. Known non-issues — do not flag these + +- **Content duplicated across `SKILL.md` and the `SKILL-*.md` variants.** Each + variant is a standalone entry point for a separate install, so overlap is + intentional. The same reference file is deliberately linked from several + variants. Do not propose deduplicating them into shared includes. +- **`tests/` not running in CI.** It is a model-scored benchmark: it calls the + Anthropic API (`new Anthropic()`, so it needs `ANTHROPIC_API_KEY`) and grades + skill selection. It is not a deterministic unit-test suite. Do not ask for it + to gate the PR, and do not ask for exact-match assertions in place of model + scoring. +- **Long files and long lines under `skill/references/`.** Reference documents + are meant to be exhaustive and there is no line-length or file-size lint. + Size alone is not a finding. +- **Prose that repeats itself between `README.md` and `skill/`.** The README + describes the skill to humans; `skill/` addresses agents. Parallel wording is + expected — only flag it when the two actually contradict each other. From 60af3ddd7fa90f1faae1adc2ffb9515fb2675324 Mon Sep 17 00:00:00 2001 From: alexander-sei Date: Tue, 4 Aug 2026 00:37:55 +0200 Subject: [PATCH 2/2] Pin stale check to the UCI release commit; point README at REVIEW.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses review feedback on #13. The stale check used the mutable v0.0.15 tag while the two AI callers pinned the release commit. Tags can be re-pointed after the fact, so pin all three to the same SHA — the set is now uniform, and one grep confirms every UCI reference moves together on the next bump. Also link REVIEW.md from the README contributing steps, so human contributors know it is what automated review grades against. Issue staling keeps UCI's defaults (stale at 8 days, closed after 2), matching sei-chain, rather than being disabled or lengthened. Co-authored-by: Cursor --- .github/workflows/uci-stale-check.yml | 3 ++- README.md | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/uci-stale-check.yml b/.github/workflows/uci-stale-check.yml index 1421fec..23057f3 100644 --- a/.github/workflows/uci-stale-check.yml +++ b/.github/workflows/uci-stale-check.yml @@ -19,6 +19,7 @@ jobs: permissions: issues: write pull-requests: write - uses: sei-protocol/uci/.github/workflows/stale-check.yml@v0.0.15 + # See: https://github.com/sei-protocol/uci/releases/tag/v0.0.15 + uses: sei-protocol/uci/.github/workflows/stale-check.yml@65901242783550521f25a19199a6b10e54550b97 with: days-before-pr-stale: 28 diff --git a/README.md b/README.md index 65a77ce..9fe81ef 100644 --- a/README.md +++ b/README.md @@ -346,6 +346,8 @@ Built from: ``` 6. Open a pull request +Pull requests are reviewed automatically against [REVIEW.md](REVIEW.md), which records this repo's review standards — worth a read before a larger change. + ## License MIT — see [LICENSE](LICENSE)