From 518fa43f4f0a9dda95059cfd2c98df23a8d3677c Mon Sep 17 00:00:00 2001 From: Scott Reimers Date: Thu, 23 Apr 2026 17:01:34 -0400 Subject: [PATCH] Adopt multi-contributor git workflow (CONTRIBUTING.md + AGENTS.md + sessions.md) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- AGENTS.md | 91 +++++++++++++++++++ CONTRIBUTING.md | 234 ++++++++++++++++++++++++++++++++++++++++++++++++ sessions.md | 55 ++++++++++++ 3 files changed, 380 insertions(+) create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md create mode 100644 sessions.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b4624bb --- /dev/null +++ b/AGENTS.md @@ -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" -- `), 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f13e1f9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,234 @@ +# Contributing to ItsGoin + +This document defines how all contributors — human and Claude Code instances — work on this repository. It is authoritative policy; follow it regardless of whether you are the primary context-holder or a newly-joined contributor. + +--- + +## Status + +**Adopted: 2026-04-23.** The workflow below is policy, but some of its prerequisites are still being stood up. Until the Phase 0 checklist at the bottom of this file is complete, certain rules that reference infrastructure (e.g. "wait for CI to pass") are aspirational. The **branching, PR, and review rules are in effect immediately**. See the Phase 0 section for current state. + +--- + +## Core rules (all contributors) + +### Branching + +- **Never commit or push directly to `master`.** Master is only updated through merged PRs. +- Before starting work, create a branch tied to a Forgejo issue: + ``` + git checkout -b /- + ``` + - Types: `feat`, `fix`, `refactor`, `chore`, `docs` + - Example: `feat/142-pq-key-exchange`, `fix/89-anchor-handshake-timeout` +- One branch per issue. If there's no issue yet, create one first. +- Keep branches short-lived — hours to a couple of days. Long branches accumulate conflicts. + +### Commits + +- Commit early, commit often. WIP commits are fine; squash before PR if you want a cleaner history. +- Use imperative mood: "Add retry logic" not "Added retry logic". +- Reference the issue in the message: `Fix anchor handshake timeout (#89)`. + +### Staying current with master + +Before pushing, always: +``` +git fetch origin +git rebase origin/master +``` + +Resolve conflicts locally, then push. If a rebase goes sideways, `git rebase --abort` safely returns you to where you started. + +### Pushing and opening PRs + +- Push to your own branch: `git push origin `. +- Open a PR in Forgejo targeting `master`. Fill in the description: what, why, how tested. +- Link the Forgejo issue. +- Wait for CI to pass (once CI exists — see Phase 0). +- **Jr PRs**: wait for Lead review before merging. The Lead is the review. +- **Lead PRs**: self-merge permitted after self-review. The Lead carries the most project context and the buck stops there; failure mode is "take steps back and retry," which Scott accepts as the cost of removing PR-review bottlenecks from the critical path. + +### Force-pushing + +- **Never** use `git push --force`. +- `git push --force-with-lease` is acceptable *only* on your own feature branch and *only* when you are its sole contributor. +- Never force-push to `master` or any shared branch. + +### Absolutely forbidden + +- `git push --force` (without `--with-lease`) +- `git reset --hard` on a branch containing uncommitted work you didn't author +- Rebasing a branch another contributor is committing to +- **Jr contributors**: merging your own PR (Lead review is required) +- Committing secrets, credentials, API keys, or large binaries +- Bypassing `.deploy-creds` into git history (it's .gitignored; keep it that way) + +### Before any destructive operation + +Always check: +``` +git status +git branch --show-current +git log -5 --oneline +``` + +Know what branch you're on and what you'd lose before you lose it. + +--- + +## Session protocol + +### Starting a session + +1. `git fetch origin` +2. Read the latest `sessions.md` entries to understand recent state. +3. Pick or confirm your assigned Forgejo issue. Verify no other contributor is actively working it. +4. Create your branch from current `master`. +5. Append to `sessions.md`: timestamp, your instance identifier, issue number, branch name. + +### Ending a session + +1. Commit any WIP with a clear message. +2. Push your branch if it's in a shareable state. +3. Update `sessions.md` with what you completed, what's pending, blockers, and your exact stopping point. +4. If work is ready, open the PR before signing off. + +--- + +## Reviewing PRs + +- **Jr PRs are reviewed by the Lead.** This is the critical check — a Lead who knows the codebase deeply is best positioned to catch the issues that a merge of foreign code could introduce (compile breaks across files, invariant violations, mis-scoped changes). +- **Lead PRs are self-reviewed by the Lead.** Scott is not in the PR review path; see Amendment 6 below. +- Focus on intent and design — CI handles formatting, tests, and lints. +- Approvals should include a brief "why." Change requests should be specific. +- Scott is the tiebreaker for genuine disagreements with the Lead's call, not the default reviewer. + +--- + +## Role-specific notes + +### Primary contributor (highest project context — "Lead") + +- The Lead carries the most project context. Self-merge authority is explicit: review carefully, merge, move on. Buck stops here. +- You're often the best source for "why is this code this way?" — write that reasoning into PR reviews of Jr work so the knowledge spreads. +- Accept that some decisions will need reversion later. Scott's posture: *"the risk of failure is generally taking steps back and trying again"* — preferable to blocking on a review step that has no effective reviewer in the current single-senior era. + +**Lead role responsibilities (current Lead = Scott's Claude):** + +- Check the PR queue on session start and at natural stopping points. Pick up any Jr PR there. Pull the branch, run `cargo check --workspace` + `cargo test -p itsgoin-core`, read for semantic issues that clean-merged textually but may break compile / violate invariants / change behavior subtly. +- Take dev work on **senior-category** issues only: protocol, crypto, concurrency / locking, `receive_post` gate changes, identity/network split, architectural refactors, production hotfixes. +- Own the full build + deploy pipeline: CLI + AppImage + APK on Linux; signing; uploads; anchor swap; release-announcement publish. +- Maintain `reference_build_deploy.md`, `AGENTS.md`, and your own `sessions.md` entries for any active branch. + +**Lead does NOT:** + +- Track who is working on what (Scott coordinates / watches alignment). +- Authorize anyone for anything (Scott authorizes Jr assignments). +- Answer Jr questions unprompted (Scott pings you with specific ones when needed). +- Decide Jr- vs senior-category scoping (Scott triages). +- Windows installer builds, iOS/Mac builds (handed off to environment-bound builders). +- Wait for Scott's approval to merge own PRs (self-merge authority is explicit). + +### Secondary / newly-joined contributors ("Jr") + +- Before writing code, read `AGENTS.md`, `CONTRIBUTING.md` (this file), and the last several `sessions.md` entries. +- If unsure whether an approach fits the project's existing patterns, ask Scott to route the question to the Lead *before* investing in the implementation. +- Defer to established architectural decisions unless you have a specific, articulable reason to revisit them. If you want to revisit, open a discussion issue first — not a PR. + +--- + +## Amendments to the base workflow (2026-04-23) + +These adjust the generic contributor doc to ItsGoin's specific operational realities. They are policy, not suggestions. + +### 1. Hotfix carve-out + +For **true production-down scenarios** the Lead retains direct-to-master authority, bypassing branch + PR + review. Scope is narrow and specific: + +- Anchor won't start / crash loop +- TLS handshake broken for all clients +- Storage corruption / migration failure +- Active security incident (e.g. key compromise, auth bypass) + +Requirements when the carve-out is exercised: + +1. Commit message must begin with `hotfix:` and clearly describe the production symptom. +2. A retrospective PR must be opened within 24 hours for review-after-the-fact. Purpose is audit trail + sanity check, not gating. +3. Logged in `sessions.md` with timestamp + what was broken + what was changed. + +This does **not** apply to: routine bugs, feature requests flagged urgent, UX polish, or any case where the network is operational. + +### 2. Build trigger: partnered go/no-go + +Builds and deploys are a partnership between Lead and Scott. Lead proposes ship / hold based on what's ready; Scott confirms or redirects. There is no rolling auto-deploy on merge and no N-PRs-threshold. Either party can initiate the conversation ("ready to ship X" / "let's hold until Y lands"), and the other can agree, counter, or surface a concern. + +### 3. Review SLA: Lead pulls from queue at stopping points + +The Lead checks the Jr PR queue at session start and at natural stopping points between their own tasks. No hard time budget. Scott doesn't route PRs to the Lead — they appear in Forgejo and the Lead picks them up. The only exception: if a Jr is blocked AND Scott flags it urgent, the Lead preempts current work. + +### 4. Re-evaluation triggers for the Lead role + +The current Lead role is "senior-category dev + reviewer + build/deploy owner." Shift to pure-reviewer/integrator (drop the dev hat) if any of these hold: + +- 5+ concurrent Jr agents active +- Lead review queue regularly runs past 1-day latency +- Lead finds themselves rewriting Jr PRs in review rather than commenting +- Scott's coordination / routing load hits his limit + +These are triggers for reassessment, not automatic policy flips. + +### 5. Secrets and credentials + +- `.deploy-creds` is `.gitignore`d. Never commit it. +- Each contributor instance gets its own Forgejo account + SSH key (see Identity section below). Never share credentials. + +### 6. Scott's role + Lead self-merge authority + +Scott's role in the day-to-day workflow is: + +- **Contributor alignment watcher.** Scott maintains awareness of what each contributor is working on and catches drift, scope creep, or cross-purposes early — at the contributor level, not the PR level. When he sees alignment issues, he redirects the contributor directly. +- **Ship partner.** On build + deploy decisions, Scott is the Lead's partner (see Amendment 2). Not an authorizer standing between the Lead and production. +- **Tiebreaker on disagreements.** Where the Lead and a Jr (or a future second senior) disagree on architectural direction, Scott is the final call. + +Scott is **not** in the PR review critical path. He does not route PRs, does not approve merges, does not sign off on individual changes. He trusts the Lead's code-review judgment and the Jr contributor's aligned intent. + +**Lead self-merge is authorized by default.** The Lead reviews their own PR, merges, moves on. The explicit tradeoff Scott has named: *"the risk of failure is generally taking steps back and trying again."* That's preferred over a gating step that has no effective reviewer in the current single-senior era. The Lead carries the context and the accountability. + +--- + +## Identity + +Each instance has its own Forgejo account and SSH key. Set local Git config per repo: +``` +git config user.name "Claude ()" +git config user.email "@" +``` + +- Never use another instance's credentials. +- Never share your own. +- Commit authorship is how we audit and debug multi-agent work. Keep it clean. + +--- + +## When in doubt + +Stop and ask. A paused session is cheap; overwritten work is expensive. If something about the repo state looks unexpected (unfamiliar commits, a branch in a weird position, a conflict you don't understand), do not "fix" it autonomously — note it in `sessions.md` and surface it to Scott. + +--- + +## Phase 0 checklist — prerequisites still pending + +These must be true before the full workflow above is operational. Until each is checked, the corresponding rule is aspirational and contributors should route around it by asking Scott. + +- [ ] Forgejo CI stood up (minimum: `cargo check --workspace` + `cargo test -p itsgoin-core` on push to any branch and on PR). +- [ ] Branch protection enabled on `master`: require PR, require 1 passing review, require CI green. +- [x] `sessions.md` exists in the repo root (this PR creates it). +- [ ] Second Forgejo account created for Jr Claude(s) with its own SSH key configured. +- [x] `AGENTS.md` exists in the repo root (this PR creates it; cross-agent session guide — see security banner at top of that file). + +Note on `CLAUDE.md` specifically: it is `.gitignore`d at the repo root because historically AI agents (including Claude) have dropped credentials into a `CLAUDE.md`-style file and those leaks are catastrophic in git history. `AGENTS.md` replaces it as the committed contributor-facing guide, with an explicit security banner forbidding credential writes. If a Claude instance needs a local scratch file, it can still use `CLAUDE.md` in the working copy — just knowing it will never reach the repo. + +Current state as of 2026-04-23: **this PR** (`chore/workflow-adoption`) creates `CONTRIBUTING.md`, `AGENTS.md`, and `sessions.md`. The remaining items (CI + branch protection + Jr account) are follow-up work Scott will coordinate. + +Until CI exists, the Lead's `cargo check --workspace` + `cargo test -p itsgoin-core` during PR review serves as the CI gate. diff --git a/sessions.md b/sessions.md new file mode 100644 index 0000000..e12327a --- /dev/null +++ b/sessions.md @@ -0,0 +1,55 @@ +# Contributor Sessions Log + +Rolling log of active sessions on the ItsGoin repository. Every contributor — Lead or Jr — appends an entry on session start and updates it on session end. Newest entries at the top. + +See `CONTRIBUTING.md` for the protocol. See `AGENTS.md` for the Claude-specific session-start checklist. + +--- + +## 2026-04-23 — primary Claude (Lead) — `chore/workflow-adoption` + +**Started**: late April 23 UTC +**Instance**: Scott's primary Claude (Lead role per `feedback_senior_role.md`) +**Issue**: none yet (inaugural PR; this is the chicken-and-egg case noted in CONTRIBUTING.md) +**Branch**: `chore/workflow-adoption` +**Scope**: Introduce the multi-contributor workflow to the repo. Creates `CONTRIBUTING.md`, `AGENTS.md`, and this file (`sessions.md`) with a seed entry. + +**Pre-existing state at session start**: +- v0.6.2 shipped end-to-end earlier today: APK, AppImage, CLI, anchor (PID 3475521, up since ~17:39 UTC). +- Last merged-to-master commit before this branch: `2ce668a` — People-tab rewrite (recency sort, profile-post Discover, bio modal, ignore primitive, per-author feed filter). +- Active artifacts on `itsgoin.com/public_html/`: `itsgoin-0.6.2.apk` (183.7 MB), `itsgoin_0.6.2_amd64.AppImage` (177.7 MB), `itsgoin-cli-0.6.2-linux-amd64` (40.8 MB). +- No other contributors active. + +**Completed in this session (before this commit)**: +- Designed the Lead role + amendments to the base workflow (hotfix carve-out, partnered build/deploy go-no-go, Lead-pulls-queue review pattern, re-evaluation triggers, Scott's contributor-alignment role, Lead self-merge authority). +- Saved `feedback_senior_role.md` to instance memory. +- Wrote `CONTRIBUTING.md`, `AGENTS.md`, `sessions.md` (this file). Originally drafted the agent guide 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` with an explicit security banner. +- Iterated on Scott's role: initial draft put him in the PR-routing / build-authorizer position; revised to watch contributor alignment + partner on ship, Lead self-merges. + +**Pending after this PR merges**: +- Phase 0 prereqs from `CONTRIBUTING.md`: Forgejo CI (`cargo check --workspace` + `cargo test -p itsgoin-core` on push + PR), branch protection on master (require PR + 1 review + green CI), second Forgejo account + SSH key for Jr Claude(s). Scott coordinates. + +**Stopping point**: session ending — Lead self-merged this PR to master (inaugural exercise of the self-merge authority the PR itself establishes, per Amendment 6). Branch `chore/workflow-adoption` deleted locally + remote. + +--- + +