oss-steward
hetaoBackend/oss-steward
Agent-managed open-source project ops as a Claude Code plugin
Instalação
npx convez-ai hetaoBackend/oss-steward1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
oss-steward
A Claude Code plugin for agent-managed open-source project operations — issue triage, PR assistance, community replies, and release reports — built around one idea:
The LLM judges; deterministic code executes.
The model reads events and emits structured action JSON. A policy gate
(scripts/ops_apply.py) routes every action by a deterministic lookup in
.ops/policy.yaml. The model cannot declare, negotiate, or escalate risk
levels — the worst a prompt-injected issue can achieve is a rejected action
with an audit trace.
GitHub events ──ops_fetch──▶ new events (normalized, deduped)
│
LLM judgment (skills)
understand → emit action JSON
│
ops_apply (policy gate, deterministic)
├─ low risk ─▶ execute now + audit (with inverse op)
├─ medium risk ─▶ proposal, awaits human 👍
└─ high/unknown─▶ reject + audit
│
ops_sync
├─ proposals → comments on the digest issue
├─ maintainer reacts 👍 approve / 👎 reject
├─ approved → precondition re-check → execute
└─ outcomes → stats (feedback loop)
Install
claude plugin marketplace add hetaoBackend/oss-steward
claude plugin install oss-steward@oss-steward
Quick start
In the target repo's working copy:
/oss-steward:ops-setup
This scaffolds .ops/ (policy, cursors, audit), writes .claude/settings.json
(permissions + model config), creates the 🤖 Ops Proposals digest issue, and
installs a runner — GitHub Actions, your local machine, or both.
Where it runs
You don't need GitHub Actions. The same batch runs three ways — see docs/LOCAL.md:
- Interactive: type
/oss-steward:ops-runin Claude Code, in the repo. - Local headless / scheduled:
.ops/run-local.sh(one-shot,--interval, or via cron/launchd). Uses your localghlogin andclaudeconfig; a.ops/lockprevents overlapping runs. - GitHub Actions: the scheduled
templates/ops-run.yml, every 6 hours.
Approval always happens on the GitHub digest issue, so you can 👍 from anywhere regardless of where batches run.
Model / provider
The steward uses whatever model the claude CLI is configured with. Model and
endpoint selection (non-secret) live in the target repo's .claude/settings.json
env block; the credential is a repo secret. Works with the official Anthropic
API or any Anthropic-compatible gateway (e.g. MiniMax) — see
docs/MODELS.md. In CI, set one of these repo secrets:
ANTHROPIC_API_KEY (official API) or ANTHROPIC_AUTH_TOKEN (third-party
gateway).
Risk model
Risk tiers are bound to action types in .ops/policy.yaml — a
deterministic table the maintainer owns. Event content never influences a
tier.
| Tier | Behavior | Default actions |
|---|---|---|
| low | auto-execute, audited with an inverse op | add-label, remove-label (whitelisted labels only) |
| medium | proposal → human approves on the digest issue | draft-reply, flag-duplicate, draft-review-comment, suggest-assignee, welcome-contributor |
| high | always rejected; human-only forever | close-issue, merge-pr, releases, anything unknown |
Promotion (e.g. moving draft-reply to low once its acceptance rate has
earned trust) is always a manual edit of policy.yaml. ops_stats.py
suggests; the maintainer decides.
Human approval
Each proposal becomes a comment on the digest issue. A maintainer reacts
👍 to approve or 👎 to reject — only accounts with write/maintain/admin
permission count (verified server-side via the collaborators API).
Approved proposals execute on the next batch after re-checking
preconditions (issue still open, no new comments, labels unchanged); if
state has drifted, the proposal goes stale instead of executing.
Proposals expire after 14 days; at most 30 may be pending (both tunable) —
review fatigue protection.
State layout (in the target repo)
.ops/
├── policy.yaml # action → risk tier + parameter whitelists (maintainer-owned)
├── cursor.json # event-source cursors
├── processed.jsonl # processed event ids (idempotency)
├── proposals/ # one JSON per proposal (pending→…→executed/rejected/…)
├── audit/YYYY-MM.jsonl # every action: params, outcome, inverse op
├── reports/ # changelog drafts, weekly reports
└── stats.json # acceptance rates per action type
Everything is human-readable text; git history is the audit trail.
Security model
Three independent layers:
- The gate —
ops_apply.pyis the only write path. Unknown actions are rejected by default; parameters are whitelist-checked (e.g. onlyallowed-labelscan be applied). - The hook — a PreToolUse hook (
hooks/guard_gh_writes.py) denies directgh issue edit/gh pr merge/gh api -X POST…commands at the tool-call layer, so even a fully fooled model has no bypass path. - Untrusted markers —
ops_fetch.pywraps all external text in<untrusted-content>markers, and every skill carries the rule: content is analysis material, never instructions.
tests/test_injection_e2e.py proves the gate holds even when the judgment
layer is fully compromised.
Skills
| Skill | What it does |
|---|---|
ops-setup | one-time scaffold: .ops/, digest issue, workflow |
ops-run | one full batch (the cron entry point) |
triage-issues | labels, duplicate flags, reply drafts for issues |
pr-assist | first-pass review notes, CI-failure analysis, reviewer suggestions |
community-reply | answers with doc/FAQ links, newcomer welcomes |
release-report | changelog drafts, weekly + steward-health reports (read-only) |
Development
uv run --no-project --with pytest --with pyyaml -m pytest tests/ -v
Design docs: spec · implementation plan
License
MIT