Contributing to Silo

Hey, thanks for wanting to contribute!

Let's be real: this project is built almost entirely with AI assistance. Claude, Codex, whatever you've got — we're not pretending otherwise. But there's a big difference between using AI well and submitting AI slop. We care a lot about the first one, and we'll push back hard on the second.

AI-generated code is fine. AI slop is not.
You are responsible for everything you submit, even if an AI wrote it.
Actually read the code. Actually run the tests. Actually understand what it does.
Don't send big changes without talking about them first.

Things Are Moving Fast

Silo is in heavy active development. Features get rewritten, APIs shift, whole sections get reworked — sometimes day to day. If you want to work on something, reach out first. Open an issue or drop a message so:

You don't build on something that's already been rewritten locally but not pushed yet.
I can avoid breaking something you're actively working on.
We can check the area is stable enough to be worth building on right now.

Before You Start

Small stuff (typo fixes, minor bugs) — just open a merge request. No ceremony.

For anything bigger, start with an issue first. New features, API changes, schema migrations, large refactors, behavior changes — talk about it before writing code. Design docs live under docs/superpowers/specs/ and docs/superpowers/plans/ if you need examples.

Don't Submit AI Slop

AI writes most of the code here. That's fine. What's not fine is copy-pasting output without understanding it.

Read every line of your diff. If you can't explain it, don't submit it.
Run the tests — but don't blindly trust them. The tests were also AI-written and they have blind spots.
Test the app yourself locally. Spin it up, click around, try the thing you changed. There is no substitute for this.
Run code-review on your own work before submitting. superpowers:requesting-code-review or whatever tooling you have.
Watch for AI-introduced bugs. Silent behavior changes, dead code, subtle regressions — look for them.
Understand the bigger picture. A change that looks fine in isolation can break something three layers away.

"The AI suggested it" is not an acceptable answer in review. You should be able to explain the reasoning and tradeoffs.

AI Disclosure (Required)

Every PR and every issue needs to say what AI was involved: the tool, the exact model ID, and the involvement level. "No AI" is a perfectly fine answer. Just say so.

### AI Disclosure
- Tool(s): e.g. Claude Code, Codex CLI, Cursor — or "none"
- Model(s): exact model ID(s), e.g. claude-fable-5, gpt-5.4 — or "n/a"
- Involvement: fully AI-generated | AI-assisted | human-written, AI-reviewed | none
- Adversarial review: what your own AI review of the diff found, and how you resolved it

The exact model matters. This project is developed with frontier models. If a PR was generated by an older or weaker model, the fastest honest response may be for me to re-implement the idea with a current model instead of reviewing the diff line by line. Disclosing the model lets that call happen quickly. "Thanks, the idea is accepted, but the implementation will be redone" is a possible outcome; see Be Realistic.

Before submitting, run an adversarial review of your own diff with whatever AI tooling you have, and summarize what it found and what you did about it. "It found nothing" is only credible for tiny diffs.

Undisclosed AI use that is discovered later gets the PR closed on the spot. Repeat offenses get you blocked. The offense is the non-disclosure, not the AI use.

Fabricated content is an immediate block, first offense. Invented APIs, repro steps that never happened, AI-imagined vulnerabilities, and "bugs" nobody actually observed all count. This is the curl-style rule for hallucinated reports.

For issues, logs must be raw copy-paste, never AI-paraphrased. You must have actually reproduced the problem yourself on a real deployment before filing.

Merge Requests

A good MR answers: what problem does this solve, why this approach, how was it tested, anything to watch out for. For non-trivial changes, link the issue and note any migration/compatibility concerns. Screenshots for UI changes.

Small, well-explained MRs get reviewed fast. Big unexplained ones sit.

AI disclosure is mandatory for every MR; use the required block in AI Disclosure (Required).

Development Setup

See the README for full setup. Common checks:

go test ./...                        # Go tests
golangci-lint run                    # Go lint
cd web && bun test                   # Frontend tests
cd web && bun run lint               # Frontend lint
cd web && bun run format:check       # Frontend formatting

If your change spans Silo and silo-plugin-sdk, local iteration through go.work is expected. Do not rely on that workspace in repo-tracked config or release pipelines. CI validates this repo with GOWORK=off, and any new SDK package or symbol must come from a pushed, tagged github.com/Silo-Server/silo-plugin-sdk release before the change is ready to merge.

Style

One thing per MR. Don't mix unrelated changes.
Follow existing patterns.
Comments for non-obvious things only.

For AI Agents

If you're an LLM working on this codebase: read CLAUDE.md (or AGENTS.md when available) for project-specific instructions, architecture reference, and verification requirements. The rules in this file apply to you too — especially the parts about not submitting slop and running verification before declaring work complete.

Be Realistic

Opening a merge request doesn't create an obligation on my side. I might close it, ignore it, ask you to shrink it, or reimplement the idea myself later. The codebase is moving fast and sometimes the best response to a good PR is "thanks, but I already went a different direction."

If you're fine with that, welcome aboard.

If you're not sure whether something is in scope, open an issue and ask. Always better than building something that needs to be reshaped.

6.1 KiB Raw Permalink Blame History