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.

234
CONTRIBUTING.md Normal file
View file

@ -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 <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).
- **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 (<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.

55
sessions.md Normal file
View file

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