community-events: Instructions file for Codex

AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. CLAUDE.md is a symlink to it.

README.md is for the person using the toolkit, who is not technical and runs it from Goose or Claude Desktop. Keep it in plain words: what to ask for, what is safe, how to set up once. Engine detail, gws setup and the standalone-zip list belong in MAINTAINING.md. CONTRIBUTING.md covers skill authoring; DESIGN.md covers how anything this repo renders for a human is styled. This file is what those don't say.

An installed plugin is not a checkout. Goose installs a git clone of this repo; Claude Desktop installs a copy without .git, one folder per version. Both run each script from wherever the session is, with no shell environment. So a SKILL.md command names its script by <skill-root>, never skills/<name>/... (check_skill_portability.py enforces this; eleven skills once broke it while working fine from the repo root). And a secret an engine needs is read from the environment, the repo-root .env, then the macOS keychain, because the keychain is the one route that reaches an installed plugin. aaif-check-setup is the operator's diagnosis for all of it. Nothing an engine writes defaults to the cwd, which from those apps is the operator's own, often synced, folder: it goes through aaif_events.datadir (with copies in the lib-free sync.py and backup.py), and a scratch file such as changes.json goes in mktemp -d. Every deliberate copy of a lib decision — those two, and check_setup.py's secret lookup — is pinned to the library by tests/test_pinned_copies.py; a new copy goes on that list in the same commit.

This repo is public — never commit PII

The skills operate on real organizer and attendee data (Slack directory, intake sheet, chapter CRMs). None of it belongs in git:

• Write audit output, backups, and exports only to paths .gitignore already covers (.slack-audit-cache/, **/backups/*, slack-*-audit.*, and the downloaded-into-cwd shapes *.docx/*.xlsx/*.pptx/*.png, changes.json, luma.md, new.md; only lib/aaif_events/tests/fixtures/ and assets/ are re-included). Extend .gitignore before a script starts emitting a new kind of output. Ignored is not the same as safe — delete these files when the run is done.
• Tests and fixtures use synthetic data only — [email protected], Ada, Boston. Never paste a real row, email, name, Slack ID, handle, phone number or LinkedIn URL into a test, docstring, comment, or commit message.
• Never paste a value you just observed in a live run. This is the rule that actually gets broken, because it does not feel like committing PII — it feels like showing your work. A real organizer's Gmail address went into a lib/ docstring as evidence for a lookup bug, under the words "Verified live", and two real Slack ids went into a test fixture as "known-good" inputs. Both were written by someone who had read the rule above. Record the shape and the date, never the value: "verified live 2026-09-14: the dotted spelling of a real organizer's address missed where the dotless spelling hit" proves the same thing and names nobody. If a reader would need the real value to trust the claim, the claim belongs in the PR description, not in the repo.
• A commit is not undoable here. Rewriting history and force-pushing cleans the branch and nothing else: GitHub keeps serving the old commit at its SHA — verified, not assumed — and only a GitHub Support request garbage-collects it. Treat every identifier that reaches a commit as published permanently, and act accordingly (tell the person, rather than assuming a rewrite covered it).
• scripts/check_no_real_pii.py enforces the decidable half of this on every commit and in CI: a Slack-id shape must be on its allowlist, and an address must be at a synthetic domain (or carry a stand-in local part at one of the domains this estate really uses). It cannot tell a real name from an invented one, so it is a floor, not a guarantee — and adding to its allowlist to make a check pass is the bug, not the fix, unless the value is genuinely invented.
• Stage explicitly. A single git add -A publishes irreversibly.
• Never paste a token into a command the agent runs; put it in .env (gitignored) or the keychain, and never export TOKEN=... interactively — shell history and the transcript both keep it.
• Secrets are NEVER accepted as command-line parameters (argv is visible in ps and gets echoed in logs/console) — scripts read tokens and API keys from environment variables (or .env / keychain) only.