Sologretto/itsgoin
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

Adopt multi-contributor git workflow (CONTRIBUTING.md + AGENTS.md + sessions.md)

Browse source 
First-pass adoption of the branch-and-PR workflow so Scott can onboard
Jr Claude contributors without blocking on the Lead. This PR is also
the inaugural test case of the workflow — branch + PR + review rather
than direct-to-master.

Three new files at the repo root:

- **CONTRIBUTING.md** — authoritative workflow policy. Based on the
  doc Opus outlined, with ItsGoin-specific amendments:
    1. Hotfix carve-out: Lead retains direct-to-master authority for
       true production-down scenarios, with mandatory retrospective PR
       within 24h.
    2. Build trigger is explicit — Scott says "ship it," no rolling
       auto-deploy.
    3. Review SLA is "natural stopping point," no hard time budget.
       Exception: Jr blocked + Scott flags urgent → Lead preempts.
    4. Re-evaluation triggers for the Lead role (5+ agents, >1d review
       latency, rewriting PRs in review, Scott's routing load).
    5. Secrets policy explicit (`.deploy-creds` is .gitignored; never
       commit credentials).
  A Phase 0 checklist at the bottom tracks which prereqs (CI, branch
  protection, Jr Forgejo account) are still pending.

- **AGENTS.md** — cross-agent session-start guide. Originally drafted
  as CLAUDE.md, but that filename is `.gitignore`d at the repo root
  because it has historically been a credential-leak vector. Switched
  to AGENTS.md (emerging cross-tool convention) with an explicit
  security banner at the top forbidding credential writes. Covers
  session start, role-specific starts (Lead vs Jr), session end,
  critical rules.

- **sessions.md** — rolling contributor coordination log. Seeded with
  an entry for this PR and the current post-v0.6.2-ship state (anchor
  PID 3475521, shipped artifacts, last merged commit 2ce668a).

No code touched. Workflow-only.

Phase 0 prereqs still open after this PR:
- Forgejo CI (`cargo check` + `cargo test` on push + PR)
- Branch protection on master (require PR + 1 review + green CI)
- Second Forgejo account + SSH key for Jr Claude(s)
This commit is contained in:
Scott Reimers 2026-04-23 17:01:34 -04:00
parent 2ce668aa58
commit 518fa43f4f
3 changed files with 380 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

91
AGENTS.md Normal file
View file

@ -0,0 +1,91 @@
# 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" -- <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.