AGENTS.md

Org Agent Context Template

About

Public edition of Magaran Software's projects/ root design. AnagramSoft = anagram of Magaran (not a real entity — public rendition stripped of internal product list). Fork as starting point. Replace {org}, <owner-email>, <owner-key-fingerprint>, <hotfix-bypass-team>, <pr-bypass-team> with own values.

Hierarchical CLAUDE.md/AGENTS.md cascade for AI-assisted dev across many repos. Auto-loaded by Claude Code under any nested project.

Writing Style

Agent-written files (AGENTS.md, memories, CLAUDE.md) use caveman ultra grammar: .ai/grammar/caveman.md. Chat with humans stays normal prose.

Repo Layout

~/projects/{org}/
├── CLAUDE.md -> AGENTS.md
├── {app_architecture}/
│   ├── CLAUDE.md -> AGENTS.md
│   └── {project_name}/

Projects

Group by arch category. See examples/ for one example arch.

Context Hierarchy

Project → Architecture → Org (bottom-up). Place info at highest applicable level.

GitHub

All repos: https://github.com/{org}/{project_name}.

Procedures

• Adding projects/arch categories — .ai/memories/adding-projects.md
• PR comments, review modes, thread resolution — .ai/memories/pr-workflow.md
• Safe ops, supply chain, dep analysis — .ai/memories/safe-operations.md
• Sudo/interactive cmds — .ai/memories/admin-steps.md
• Issue branches ("branch out") — .ai/memories/issue-branches.md
• cd into project dir on single-project work start — .ai/memories/working-directory.md
• GPG signing, secret-manager hooks — .ai/memories/git-signing.md

Owner Verification

Before push: confirm signed commit = owner. Applies org-wide.

git log -1 --pretty=format:'%G? %GS %ae %GK'

Owner if %G? ∈ {G, U} (good sig) AND %GS (signer name+email) or %ae (author email) contains <owner-email>, OR %GK (signing key) = <owner-key-fingerprint>. Match → push. No match → commit only, owner pushes later. Signing auto via pre-commit hook (see .ai/memories/git-signing.md).

Replace <owner-email> and <owner-key-fingerprint> with own values.

Auth

No SSH keys for git. Use scoped, short-lived tokens via GitHub App device flow.

Why

SSH keys = long-lived, unscoped creds. Stolen → full read/write across every repo user can access, until manual revoke. No expiry, no scope, no per-action audit.

GitHub App tokens = short-lived (~8h typical), scoped (specific perms), auditable, revocable. Stolen → narrow blast radius, expires soon.

Industry should move off SSH keys for git. Scoped App tokens = same UX (clone/push) at fraction of threat surface.

Pattern

Device-flow auth → OS secret manager → tmpfs cache → git credential helper. Refresh on expiry. Never persist long-lived tokens on disk. Never deploy SSH keys to dev hosts, sandboxes, remote-control hosts.

Bypass Teams Pattern

Branch-protected org → bypass actors must be default-empty teams, never permanent admins. Add self → op → remove self, same session. Never persist membership.

Recommended Setup

Two bypass teams in every branch ruleset. No other bypass actors (no OrgAdmin, no RepositoryRole, nothing else).

• <hotfix-bypass-team> — mode always. Bypasses everything: direct push, force push, PR merge --admin. Use only when PR path infeasible (broken main, prod hotfix at 3am).
• <pr-bypass-team> — mode pull_request. Bypasses PR-merge gates only (stale review, missing check, etc.). Direct/force push still rejected. Default pick when PR has approval but won't merge.

Pick smallest privilege for job. Both teams hold push on all repos so members can push after bypassing. Org default repo permission = none; members get write only via team grant.

Usage

gh api -X PUT    orgs/{org}/teams/<bypass-team-slug>/memberships/<user>
# op: gh pr merge --admin --squash, git push, etc.
gh api -X DELETE orgs/{org}/teams/<bypass-team-slug>/memberships/<user>

Threat Model

Org owner identity alone ≠ bypass. Rulesets enforce on owners too. Bypass = team membership only.

• Routine creds (device-flow token) lack admin:org scope → cannot manage team membership → cannot self-elevate.
• Stolen routine creds → at most open a PR. No path to land code without human review.
• Full creds (admin:org PAT) live only on trusted host (secret manager). Never in sandbox, dev shell, remote-control flake.

Footgun

POST /orgs/.../teams auto-adds creator. After API team create, immediately DELETE self from team unless membership intended. Verify via UI: github.com/{org}/teams/<slug> → Members.

Conventions

Baseline Before Work

Verify project compiles + all tests pass before starting implementation.