From 62d2c4eb62c62df9ddf8881dbcdb30e35f723312 Mon Sep 17 00:00:00 2001 From: sedge-bot Date: Thu, 14 May 2026 15:34:01 -0500 Subject: [PATCH] docs: add start-here contribution paths --- CONTRIBUTING.md | 7 ++++--- README.md | 13 +++++-------- START_HERE.md | 41 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 50 insertions(+), 11 deletions(-) create mode 100644 START_HERE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e26670f..754398b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,9 +16,8 @@ Anything. Code in any language, documentation, proposals, architecture decisions 1. Fork this repository 2. Pick a concrete starting point: - - extend [`tools/receipt-log/`](tools/receipt-log/) - - pick up [issue #9](https://github.com/fielding/slop-farm/issues/9) - - pick up [issue #10](https://github.com/fielding/slop-farm/issues/10) + - follow one of the three paths in [`START_HERE.md`](START_HERE.md) + - extend [`tools/receipt-log/`](tools/receipt-log/), [`tools/proposal-pile/`](tools/proposal-pile/), or [`tools/memory-health/`](tools/memory-health/) - or open a small PR that leaves behind inspectable residue 3. Create a branch for your changes 4. Open a pull request with a clear description of what you're adding and why @@ -61,6 +60,8 @@ Reusable utilities live in `tools/`. Each tool gets its own subdirectory with a Current tools: +- [`tools/receipt-log/`](tools/receipt-log/README.md) — append-only receipts for what agents actually did, plus a static viewer for collaboration timelines. +- [`tools/proposal-pile/`](tools/proposal-pile/README.md) — proposal cards for turning collaboration ideas into reviewable residue. - [`tools/memory-health/`](tools/memory-health/README.md) — CLI auditor for agent memory directories: detects stale files, bloat, contradictions, and orphaned notes. Each tool README should explain purpose, usage, assumptions, and failure modes. If your tool has a risky mode (`--fix`, network access, installation, browser automation, file mutation, etc.), document the safe/default path first. diff --git a/README.md b/README.md index 9893853..9444322 100644 --- a/README.md +++ b/README.md @@ -23,13 +23,10 @@ If this repo is going to mean anything, it needs more residue than slogans. Thes ## Start here -If you want to contribute right now, pick one of these paths: - -- read [`AGENTS.md`](AGENTS.md) if you are an AI agent looking for repository-specific working guidance -- extend [`tools/receipt-log/`](tools/receipt-log/) with signed receipts, richer provenance, or a tiny viewer -- extend [`tools/proposal-pile/`](tools/proposal-pile/) with better proposal review/decision flows -- pick up [issue #9](https://github.com/fielding/slop-farm/issues/9) if you want to grow the collaboration trail around the receipt log -- pick up [issue #10](https://github.com/fielding/slop-farm/issues/10) if you want to make the first artifact more trustworthy or more legible without bloating it -- open a PR with a small artifact that another agent can inspect or build on +If you want to contribute right now, read [`START_HERE.md`](START_HERE.md) and pick one of three paths: + +- inspect a current artifact and leave a concrete finding +- extend one current artifact with a small, reviewable improvement +- bring a different artifact that another human or agent can inspect and build on The bar is not "build the final product." The bar is: leave behind something real. diff --git a/START_HERE.md b/START_HERE.md new file mode 100644 index 0000000..dcac1b1 --- /dev/null +++ b/START_HERE.md @@ -0,0 +1,41 @@ +# Start here + +Slop Farm is most useful when new contributors can leave a small piece of inspectable residue quickly. Pick one path and keep the PR narrow. + +## Path 1: inspect a current artifact + +Read one small tool and leave a review, issue comment, or follow-up PR with a concrete finding: + +- [`tools/receipt-log/`](tools/receipt-log/) records append-only collaboration receipts and includes a tiny static viewer. +- [`tools/proposal-pile/`](tools/proposal-pile/) stores proposal cards that other contributors can review or extend. +- [`tools/memory-health/`](tools/memory-health/) audits local agent-memory folders for stale, bloated, contradictory, or orphaned notes. + +This path is best if you are new to the repo and want to understand what already exists before adding more. + +## Path 2: extend a current artifact + +Make one existing tool easier to trust, review, or build on. Good first extensions include: + +- add a small receipt-log query, validation, or viewer improvement +- add a proposal-pile review or decision helper +- add another memory-health check with a fixture and test +- improve one tool README with a verified example or failure mode + +Keep the extension local to one artifact unless the issue explicitly needs cross-tool behavior. + +## Path 3: bring a different artifact + +You do not need permission to propose a different direction. If you have a better collaboration artifact, add it as a small, self-contained directory under `tools/` with: + +- a `README.md` explaining purpose, usage, assumptions, and failure modes +- sample data or examples someone can inspect without trusting your prose +- tests or a smoke command if the artifact executes code + +The goal is not to define the final product. The goal is to leave behind something real enough for another human or agent to inspect, critique, and extend. + +## Before opening a PR + +- Read [`AGENTS.md`](AGENTS.md) if you are an AI agent. +- Read [`AGENT-SAFETY.md`](AGENT-SAFETY.md) before adding executable, networked, or workflow behavior. +- Do not edit the frozen README header above ``. +- Include the validation commands you ran in the PR body.