itsgoin/AGENTS.md

Agent Session Guide — ItsGoin

This file is for AI coding agents (Claude Code, Cursor, Aider, Codex, etc. — any role: Lead or Jr) entering this repo. Read it first on every fresh session before doing any work. It is the cross-agent analog of CONTRIBUTING.md focused on session-start protocol.

---

⚠️ Security banner — read before writing anything to this file

This file is committed to the repo. It ships with every checkout, shows up in every mirror, lives forever in git history.

• Never write credentials, API keys, passwords, tokens, SSH keys, keystore passwords, or any secret of any kind here.
• Never paste the contents of .deploy-creds or any other *-creds* file here.
• Never paste connect strings that contain embedded secrets.
• If you're tempted to leave a "note to self" that contains auth material — stop. Put it in your out-of-tree instance memory (for Claude: ~/.claude/projects/…/memory/) or hand it to Scott.
• .gitignore includes CLAUDE.md, .deploy-creds, *pass*.txt, *.keystore, and related patterns precisely because credentials historically leaked into files with those names. Don't recreate that pattern under a new filename.

If you notice a secret was committed anywhere in history, do not try to rewrite history yourself — surface it to Scott immediately.

---

On session start

1. Orient.

   git fetch origin
   git status
   git branch --show-current
   git log --oneline -10
   

   Know what branch you're on and whether anything is uncommitted from a prior session.

2. Read the workflow policy. CONTRIBUTING.md in the repo root is authoritative on branching, PRs, reviews, hotfixes, and role boundaries. Read it if you haven't, or if it's been updated since you last did.

3. Read recent sessions.md entries. The last few entries tell you what's been shipped, what's in flight, and what other contributors are actively touching. Catching up here prevents conflicts before they happen.

4. Read your own instance memory (if your tooling has one). For Claude Code: ~/.claude/projects/-home-sologretto-Projects-itsgoin/memory/MEMORY.md indexes user preferences, reference docs, known bugs, and role defaults. Start with MEMORY.md and pull specific entries only when relevant.

5. Check for inbound work. If Scott has routed a PR to you for review, or assigned you an issue, address that before starting speculative work. If your role is Lead, also check whether any cargo test / cargo check --workspace has drifted on master since you last built.

---

Role-specific starts

If you are the Lead

• Check the Forgejo PR queue for anything awaiting your review.
• If Scott has said "ship it" on a set of merged PRs, run the pre-deploy integration check: git checkout master && git pull && cargo check --workspace && cargo test -p itsgoin-core, then start builds.
• If Scott has assigned you a senior-category issue (protocol / crypto / concurrency / hotfix), follow the branch-and-PR flow in CONTRIBUTING.md.

If you are a Jr

• Confirm the issue Scott has assigned you. If unsure about approach, ask Scott to route the question to the Lead before writing code.
• Create your branch from current master, not from a stale local master.
• Read the touched-file areas of the codebase before editing. If the file has heavy recent activity (check git log --since="1 week" -- <file>), double-check nobody's mid-flight on it.

---

On session end

1. Commit any WIP with a clear message (imperative mood, reference the issue).
2. Push your branch if it's in a shareable state.
3. Append to sessions.md: what you completed, what's pending, blockers, your exact stopping point.
4. If work is ready, open the PR before signing off.

---

Key reference documents

• CONTRIBUTING.md — branching, PR, review, hotfix policy
• sessions.md — rolling coordination log (read + append)
• ARCHITECTURE.md — project-level architecture overview
• docs/DISCOVERY-PROTOCOL.md — network discovery protocol
• website/design.html — canonical design doc (read via memory/reference_design_index.md for section-specific line ranges)
• Instance-specific memory (for Claude Code: ~/.claude/projects/.../memory/) — user preferences, reference docs, known bugs. Check MEMORY.md for the index.

---

Critical rules (repeat of the ones you absolutely must know before coding)

• Never commit or push directly to master (except the Lead's hotfix carve-out — see CONTRIBUTING.md).
• Read memory/bugs-fixed.md BEFORE modifying networking / connection code. Historical bugs are listed there to prevent reintroduction.
• Session relay is OPT-IN ONLY and DISABLED BY DEFAULT. Do not enable it as a fallback.
• Canonical design is website/design.html. Consult it FIRST for architecture or protocol decisions; use the section index in memory/reference_design_index.md to read only relevant lines.
• No credentials in committed files. See the security banner at the top of this doc.

---

When in doubt

Stop and ask Scott. A paused session is cheap; overwritten work is expensive.