From d879d1d3eade3bd411e85bfab90cb8c38a02bd49 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 | 90 ++++++++++++++++++++ CONTRIBUTING.md | 219 ++++++++++++++++++++++++++++++++++++++++++++++++ sessions.md | 54 ++++++++++++ 3 files changed, 363 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..a642fb8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,90 @@ +# 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" -- `), 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..6f8ec21 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,219 @@ +# 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) and at least one peer review before merging. + +### 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 +- Merging your own PR without review (unless explicitly authorized by Scott) +- 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 + +- Any contributor can review any PR. Cross-review (reviewer ≠ author) is strongly preferred. +- 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, not the default reviewer. + +--- + +## Role-specific notes + +### Primary contributor (highest project context — "Lead") + +- You have no special merge authority for normal PRs. Branch protection is the master manager, not you. +- Expect to be tagged for review on architecturally significant PRs. Prioritize these. +- You're often the best source for "why is this code this way?" — write that reasoning into PR reviews so the knowledge spreads to other contributors. +- Do not approve your own PRs. Having more context is not a substitute for peer review. + +**Lead role responsibilities (current Lead = Scott's Claude):** + +- Review PRs that Scott routes to you. 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). +- Authorize anyone for anything (Scott authorizes). +- 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). + +### 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: explicit + +Builds and deploys happen only when Scott says "ship it" (or equivalent explicit authorization). There is no rolling auto-deploy on merge, no N-PRs-threshold that triggers a build automatically. This reduces surprise deploys and keeps release cadence under human control. + +### 3. Review SLA: natural stopping point + +When Scott routes a PR to the Lead for review, the Lead finishes the current task before picking it up. No hard time budget. The only exception: if a Jr is blocked on the review AND Scott flags it urgent, the Lead preempts. + +### 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. + +--- + +## 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..be49325 --- /dev/null +++ b/sessions.md @@ -0,0 +1,54 @@ +# 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, explicit build trigger, natural-stopping-point review SLA, re-evaluation triggers). +- 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. + +**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**: branch pushed, PR open for Scott's review. Awaiting review. + +--- + +