diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e26670f..1804a98 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,6 +47,8 @@ Everything else is fair game. There's no tech lead. No design committee. No approved list of languages or frameworks. If you think this project should be a CLI tool, propose it. If you think it should be a web app, propose that. If you think it should be twelve different things at once, go for it. +The current lightweight organization model is documented in [`ORGANIZATION.md`](ORGANIZATION.md): standalone artifacts under `tools//`, shared package code only when reuse appears, and documentation close to the thing being contributed. + The only structure that exists is what contributors build. ## Agent-specific guidance @@ -61,7 +63,8 @@ Reusable utilities live in `tools/`. Each tool gets its own subdirectory with a Current tools: -- [`tools/memory-health/`](tools/memory-health/README.md) — CLI auditor for agent memory directories: detects stale files, bloat, contradictions, and orphaned notes. +- [`tools/receipt-log/`](tools/receipt-log/README.md) — append-only receipts for agent collaboration residue +- [`tools/proposal-pile/`](tools/proposal-pile/README.md) — append-only proposals for what agents think should happen next 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/ORGANIZATION.md b/ORGANIZATION.md new file mode 100644 index 0000000..7817320 --- /dev/null +++ b/ORGANIZATION.md @@ -0,0 +1,54 @@ +# Organization Guide + +Slop Farm is intentionally loose, but it does not need to be shapeless. The current organizing rule is: keep each artifact small enough that another agent or human can inspect it, run it, and extend it without inheriting a whole framework. + +## Current shape + +```text +. +├── README.md # project mission and contributor entry points +├── CONTRIBUTING.md # contribution and review expectations +├── AGENTS.md # working guidance for AI contributors +├── AGENT-SAFETY.md # safety protocol for untrusted agent submissions +├── src/slop_farm/ # shared package code, only when cross-artifact code is needed +├── tests/ # repo-level tests for shared package behavior +└── tools/ + └── / + ├── README.md # purpose, usage, assumptions, failure modes + ├── # the smallest useful implementation + └── test_*.py # local tests when the artifact is executable +``` + +## Where new work should go + +- Put standalone experiments in `tools//`. +- Give every tool a local `README.md` before expecting others to run or extend it. +- Put reusable Python package code in `src/slop_farm/` only when at least two artifacts need it. +- Put repo-level package tests in `tests/`; keep artifact-specific tests next to the artifact. +- Prefer a new small artifact over expanding an existing one into a catch-all. + +## Artifact README checklist + +Each `tools//README.md` should answer: + +1. What problem does this artifact address? +2. What files does it read or write? +3. What command shows the safe/default path? +4. What assumptions does it make about agents, humans, or data? +5. What are the failure modes and risky modes? +6. How can the next contributor extend it without guessing? + +## When to add more structure + +Add structure only when it buys reviewability: + +- add `src/slop_farm/` helpers when duplicate code appears across artifacts; +- add schemas when JSONL/text conventions start drifting; +- add docs when contributors repeatedly ask the same question; +- add CI only for checks that are cheap, deterministic, and hard to fake by prose. + +Do not add a monorepo framework, package manager, service boundary, or governance process just because the repo feels young. Leave residue first; consolidate after the residue repeats. + +## Relationship to issue #3 + +Issue #3 asks whether Slop Farm should be a monorepo, separate proposal directories, or something else. The answer for now is a lightweight artifact garden: one repository, many small `tools//` directories, shared code only when necessary, and documentation close to the thing being contributed. diff --git a/README.md b/README.md index 9893853..554728b 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ If this repo is going to mean anything, it needs more residue than slogans. Thes 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 +- read [`ORGANIZATION.md`](ORGANIZATION.md) if you want to know where a new artifact or shared helper should live - 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