Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

chore(claude): add a PR steward skill and label review severities (#245)

Rufusf41800e2bc43
diff --git a/.claude/skills/steward/SKILL.md b/.claude/skills/steward/SKILL.md
new file mode 100644
index 00000000..384a14f9
--- /dev/null
+++ b/.claude/skills/steward/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: steward
+description: Repo rules for driving an Open Executive pull request to green - CI failures, the pr-checks job, and findings from the automated Claude review. Use when watching, fixing or babysitting a PR in this repo.
+---
+
+# Steward: driving an Open Executive PR
+
+Only what is specific to this repo. `CLAUDE.md` covers the code rules.
+
+## Before every push
+- Run `make check`. It runs what CI runs (lint, unit and integration tests,
+ the UI build if `packages/ui` changed, `scripts/pr_checks.py`) with the
+ `BACKEND_SHARED_SECRET` / `OE_PUBLIC_DEPLOYMENT` traps handled.
+- If a test fails only in the full run, rerun it serially (no `-n`). The
+ usual cause is a ContextVar or audit-log leak from another module (see
+ `CLAUDE.md` -> Testing), not a flake.
+- Batch every fix for a round into one push. Each push re-runs the paid
+ Claude review.
+
+## `PR rules` job red
+- `arch-doc-drift`: re-author the named
+ `architecture/prebuilt/<section>.json` and the matching
+ `architecture-facts.yaml` notes. Waive with `Arch-Docs: n/a - <reason>`
+ only when the change doesn't alter what the section describes. Never
+ waive just to get green.
+- `eval-scenarios`: add the `evals/_scenarios/*.yaml` files the
+ new-agent checklist in `CLAUDE.md` asks for.
+- `no-stubs`: finish the code; don't reword the marker.
+
+## Claude review findings
+The `Claude Code Review` workflow starts each inline comment with a marker:
+- 🔴 must fix before merge (bug, security, `CLAUDE.md` invariant). Fix it,
+ or reply with evidence that it doesn't reproduce.
+- 🟡 optional. Reply in one line; fold it into the next push only if it is
+ plainly right. It never starts a push on its own.
+- 🟣 pre-existing, not introduced by this PR. Reply in one line and leave it.
+
+## Branch and title
+- PRs are squash-merged with the title as the commit subject, which
+ release-please reads. Keep it `type(scope): what changed`.
+- Resolve conflicts by merging `main` into the branch, not by force-pushing.
+- Regenerate lockfiles with `uv lock` / `npm install`, never by hand. The
+ `uv lock --check` step fails on a stale `uv.lock`.
diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml
index ca9bc35a..6487c2fe 100644
--- a/.github/workflows/claude-code-review.yml
+++ b/.github/workflows/claude-code-review.yml
@@ -87,8 +87,13 @@ jobs:
stub markers, eval scenarios).
Put each finding as an inline comment on the line it concerns,
- with a concrete failing input or scenario. Finish with one
- short PR comment summarizing the findings, or saying none were
- found. Do not approve or request changes.
+ with a concrete failing input or scenario. Start every inline
+ comment with exactly one marker:
+ 🔴 must fix before merge: a bug, security issue, CLAUDE.md
+ invariant break, or missing test for new behavior
+ 🟡 optional: a real but minor improvement
+ 🟣 pre-existing: a problem this PR didn't introduce
+ Finish with one short PR comment giving the count per marker,
+ or saying none were found. Do not approve or request changes.
claude_args: |
--allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Read,Grep,Glob"
diff --git a/CLAUDE.md b/CLAUDE.md
index 113f6ad9..3a1dd5b9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -265,4 +265,5 @@ Before calling a code change done or opening a PR:
- New behavior has tests; a new agent or prompt change has eval scenarios.
- A change to what a documented topic describes updates its `prebuilt/<section>.json` (see Architecture Docs), or carries an `Arch-Docs: n/a - <reason>` waiver.
- A change touching `api/`, `integrations/`, `mcp_server/`, auth, `orchestrator/outbound_guard.py`, the cached prompt blocks or `.gitignore` gets a pass from the `security-reviewer` agent (or `/security-review`) before the PR opens.
-- Every non-draft PR also gets an automated Claude review (`.github/workflows/claude-code-review.yml`) as inline comments. Fix or answer each finding.
+- Every non-draft PR also gets an automated Claude review (`.github/workflows/claude-code-review.yml`) as inline comments marked 🔴 must-fix / 🟡 optional / 🟣 pre-existing. Fix or answer each finding.
+- When driving a PR to green, the `steward` skill (`.claude/skills/steward/SKILL.md`) covers CI failures and review findings.