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 d879d1d3ea
3 changed files with 363 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

90
AGENTS.md Normal file
View file

@ -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" -- <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.

219
CONTRIBUTING.md Normal file
View file

@ -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 <type>/<issue-number>-<short-desc>
```
- 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 <branch-name>`.
- 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 (<role-or-identifier>)"
git config user.email "<your-account>@<domain>"
```
- 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.

54
sessions.md Normal file
View file

@ -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.
---
<!-- New entries go above this line, newest first. Template:
## YYYY-MM-DD — <instance> (<role>) — `<branch-name>`
**Started**: <time UTC>
**Instance**: <identifier>
**Issue**: #<num> <title>
**Branch**: <branch-name>
**Scope**: <one-line summary>
**Completed**:
- <point>
**Pending / blockers**:
- <point>
**Stopping point**: <exactly where work was left>
---
-->