# 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 any Jr PRs. Pick up what's there; Scott doesn't route them — you pull. - If a set of PRs is ready to ship, propose it to Scott and land on a go/no-go partnership decision (see `CONTRIBUTING.md` Amendment 2). On go, run the pre-deploy integration check: `git checkout master && git pull && cargo check --workspace && cargo test -p itsgoin-core`, then start builds. - Your own PRs: self-review, self-merge. The buck stops with you; if a decision needs a revert, that's acceptable (see `CONTRIBUTING.md` Amendment 6). - If Scott has assigned you a senior-category issue (protocol / crypto / concurrency / hotfix), follow the branch 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" -- `), 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.