From 7de75e9799674311cd9fee8c17cad814d43a0335 Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Mon, 6 Jul 2026 03:31:53 -0500 Subject: [PATCH] docs: add AGENTS.md + CLAUDE.md agent-contributor guidance Canonical entry point for agents opening PRs against the Familiar Contract spec: branch/PR workflow, spec-change discipline (schemas are normative, keep prose + schema in sync, prefer additive changes, ward semantics are load-bearing/security-sensitive), and contributor attribution (GitHub-linked Co-authored-by trailer, never a .local email). CLAUDE.md points at AGENTS.md. --- AGENTS.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 11 +++++++++ 2 files changed, 83 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..0aa0ef8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,72 @@ +# AGENTS.md — familiar-contract + +Guidance for **AI agents** (Codex, Claude Code, and any Coven familiar) opening +pull requests against this repo. This is the agent-specific layer; read +[`README.md`](README.md) for the full specification. + +> **What this repo is:** the **Familiar Contract** — an open specification for +> what an agent is *allowed to be*: not just what it can do, but what it cannot +> change about itself. The normative artifacts are the JSON Schemas under +> [`schemas/`](schemas/) (`identity`, `role`, `soul`, `ward`) and the prose +> spec in the Markdown pages. + +## Branch & PR workflow + +- **Never push to `main`.** Every change lands via a PR. 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/famcontract- 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. + +## This is a specification — change it deliberately + +- **Schemas are normative; prose explains them.** When you change a schema under + `schemas/`, update the corresponding prose page in the **same PR**, and vice + versa. They must not drift. +- **Validate before you submit.** Every JSON Schema must be valid, and every + example/fixture in the repo must validate against its schema: + ```sh + # example — use whatever validator the repo scripts provide + find schemas -name '*.schema.json' -print0 | xargs -0 -n1 + ``` +- **Backward compatibility matters.** The contract is consumed by real agents. + Prefer additive changes; a breaking change to identity/role/soul/ward needs an + explicit rationale and a version note in the PR body. +- **Ward semantics are load-bearing.** The `ward` schema encodes what an agent + may *not* change about itself — treat edits there as security-sensitive and + spell out the reasoning. + +## Attribution — credit contributors correctly + +When you re-land or build on someone else's work (a fork PR, an issue author's +proposal, a co-author), **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 or `.local` email (e.g. `name@Someones-Mac.local`) in a + co-author trailer — it links to no account and gives **zero** credit. +- When a squash-merge folds a contributor's PR into an internal branch, preserve + their `Co-authored-by:` line in the squash commit message. +- Credit **people**, not AI tools. + +## Secrets & safety + +- Never commit secrets, tokens, or private emails. Use `*.noreply.github.com` + for attribution. +- Don't loosen a ward or safety constraint in the spec to make an example pass; + fix the example 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..b92fa75 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,11 @@ +# CLAUDE.md — familiar-contract + +**Read [`AGENTS.md`](AGENTS.md).** It is the canonical guide for AI agents +(including Claude Code) contributing to this repo — the branch/PR workflow, the +spec-change discipline (schemas are normative, keep prose + schema in sync, +prefer additive changes, ward semantics are load-bearing), and contributor +attribution. + +Claude Code auto-loads this file; everything you need lives in `AGENTS.md` plus +[`README.md`](README.md). There is no separate Claude-only workflow — follow +`AGENTS.md`.