From 60f6243fe4f3d2e61449a97f259be4bd19c05e2f Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Mon, 6 Jul 2026 02:15:24 -0500 Subject: [PATCH 1/2] docs: add AGENTS.md + CLAUDE.md agent-contributor guidance Canonical entry point for AI agents opening PRs against the GitHub App adapter: the mandatory DCO sign-off (git commit -s), branch/PR workflow, local CI gates (cargo check/clippy -D warnings/test), adapter invariants (no App secrets, GitHub-native progress surfaces), and contributor attribution. Notes that a commit can carry both Signed-off-by and Co-authored-by trailers. CLAUDE.md points at AGENTS.md. Signed-off-by: Val Alexander --- AGENTS.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 11 +++++++ 2 files changed, 108 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3c08b46 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,97 @@ +# AGENTS.md — coven-github + +Guidance for **AI agents** (Codex, Claude Code, Hermes, and any Coven familiar) +opening pull requests against this repo. Humans: your canonical guide is +[`CONTRIBUTING.md`](CONTRIBUTING.md) — this is the agent-specific layer on top. + +> **Read first:** [`README.md`](README.md) for what this repo is, and +> [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full contribution bar — including +> the **DCO sign-off requirement**, which is mandatory here. + +--- + +## What this repo is (one line) + +`coven-github` is the **GitHub App adapter** for OpenCoven (Rust): it routes +GitHub issues, labels, mentions, and review comments into a Coven familiar, then +publishes progress via Check Runs, issue comments, draft PRs, and CovenCave +session links. + +## DCO — every commit must be signed off (mandatory) + +This repo uses the **Developer Certificate of Origin**. Every commit needs a +`Signed-off-by` trailer or CI/merge will block it: + +```sh +git commit -s -m "type: summary" +``` + +This produces `Signed-off-by: Your Name `. Use a real +GitHub-linked identity. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full DCO +text. + +## Branch & PR workflow (all agents) + +- **Never push to `main`.** Every change lands via a PR with green CI. Branch + from current `origin/main`. +- **Fresh branch per task**; use a worktree if multiple sessions may touch this + repo: + ```sh + git fetch origin main + git worktree add -b /tmp/covengh- origin/main + ``` +- Keep the diff **scoped to one concern**; conventional-commit subjects + (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`). +- After merge: delete the remote branch, remove your local worktree/branch. + +## CI gates — run locally before opening the PR + +CI (`.github/workflows/ci.yml`) rejects on any of these. Run them first: + +```sh +cargo check --all-targets +cargo clippy --all-targets -- -D warnings +cargo test --all +``` + +`-D warnings` has **no exceptions**. Fix lints; don't `#[allow(...)]` without a +justifying comment. + +## Repo-specific invariants (don't break these) + +- This is an **adapter**, not a familiar. Keep GitHub-webhook/App plumbing here; + don't reimplement familiar/authority logic that belongs in `coven`. +- **Never commit App private keys, webhook secrets, or installation tokens.** + The placeholder-secret list exists to keep test fixtures inert — keep real + credentials out of the repo entirely. +- Surface progress through the GitHub-native primitives (Check Runs, comments, + draft PRs) rather than inventing new side channels. + +## Attribution — credit contributors correctly + +When you re-land or build on someone else's work, **credit the human +contributor with a working GitHub-linked trailer** so they appear in the +contributors graph and on their profile: + +``` +Co-authored-by: Full Name +``` + +- Use the **numeric-id no-reply form**. Get the id with + `gh api users/ --jq .id`. +- **Never** use a machine/`.local` email in a co-author trailer — it links to no + account and gives **zero** credit. +- A commit can carry **both** `Signed-off-by:` (DCO, required) and + `Co-authored-by:` (attribution) trailers — include both when re-landing a + contributor's work. + +## Secrets & safety + +- Never commit secrets, tokens, or private emails. Use `*.noreply.github.com` + for attribution. +- Don't disable CI gates or branch protection to land a change. If it can't go + through a green PR, surface the blocker instead. + +## Claude Code + +`CLAUDE.md` points here — this file is the source of truth for both. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d4e076a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,11 @@ +# CLAUDE.md — coven-github + +**Read [`AGENTS.md`](AGENTS.md).** It is the canonical guide for AI agents +(including Claude Code) contributing to this repo — the mandatory **DCO +sign-off** (`git commit -s`), branch/PR workflow, local CI gates, the GitHub-App +adapter invariants, and contributor attribution. + +Claude Code auto-loads this file; everything you need lives in `AGENTS.md` plus +[`README.md`](README.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md). There is no +separate Claude-only workflow — follow `AGENTS.md` (and remember `-s` on every +commit). From 3cdc11a2803b09522ba931313de1dad1d363f025 Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Mon, 6 Jul 2026 05:55:08 -0500 Subject: [PATCH 2/2] docs: clarify DCO signoff guidance Signed-off-by: Val Alexander --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3c08b46..68b2f0f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,8 +19,8 @@ session links. ## DCO — every commit must be signed off (mandatory) -This repo uses the **Developer Certificate of Origin**. Every commit needs a -`Signed-off-by` trailer or CI/merge will block it: +This repo uses the **Developer Certificate of Origin**. Every commit must carry +a `Signed-off-by` trailer: ```sh git commit -s -m "type: summary"