Contributing with an agent

You do not need programming skills to make one useful contribution to OSS Singularity. If you have an AI agent — or plan to get one — you can contribute by choosing a task, giving the agent context, checking its work and handing the result off clearly. This guide walks that loop once.

The project is a shared home for people and agents, and contribution is not only coding. An agent's output is a proposal: it becomes part of the project only when a maintainer reviews and accepts it — for file changes, through the normal public pull-request flow (a pull request is a public proposal to change the project's files). Checks an agent runs can support that review; they never replace the maintainer's decision.

This guide itself has AI authorship: an AI agent drafted it and a second, fresh AI agent continued it (continuation record). It is accepted source work: maintainer ClaudiuSchuster merged PR 25 on 2026-10-16 at commit 3fec7e031761fcacbccb15af508cd064120c8143. That decision accepts the Guide source; human usability testing remains open.

1. Choose one small useful task

Start from the project's real entry points instead of inventing a job:

Website project brief: the project's purpose, its published state and the one next allowed action it names.
Connect project path: the site's visible entry for a first project journey — discover → understand → draft → return — named in CONTRIBUTING.md and listed among the project brief starting points.
Choose one small contribution in the contributor guide: three concrete first tasks.
Public help requests: bounded voluntary opportunities, each with its acceptance criteria. These are offers to contribute, not assignments or permission to test infrastructure.
Ideas register: directions the project finds promising, their current status and the next useful experiment.

Contribution is broader than code. Tasks that fit this guide include:

Research with sources: check one Atlas entry (an entry in the project's curated agent-tool catalog) against its official sources and record the date you checked them, following the Atlas source rules. A correction you cannot or do not want to turn into a pull request can go to the Workshop contribution form, which accepts ordinary suggestions without an account or a code change; moderation and review precede any Atlas change (CONTRIBUTING.md).
Art or branding input: propose wording or visual ideas within the established identity in brand inputs and BRANDING.md.
A reader observation note: read a public document and record what you understood, which sources you used and what your account cannot claim. The fresh-reader observation is one example of this kind of note.
Improving a label or other wording: the contributor guide lists making one journey easier to use, including a clearer label, as a first task. A translation suggestion is the same kind of wording contribution.
Reproducing one bug locally with synthetic inputs (made-up example data, never real user data), describing the expected versus observed behavior (CONTRIBUTING.md; follow SECURITY.md before sharing anything exploitable, and see the local security-testing guide for isolated setups).

Choose one task, not several. A small task you can check is more useful to the project than a large one you cannot.

2. Give the agent context and constraints

An agent works from what you give it plus public sources. Provide both, and provide boundaries:

Public sources: the exact pages or repository files — the project's shared public file store — that the task concerns, with links. Where a specific revision matters, link that revision.
Scope: what is in and what is out — for example "documentation only, at most two files" or "one Atlas entry, sources checked today".
Honesty rules: published work, drafts and examples stay distinguishable; uncertainty is stated rather than papered over; no private information (tokens, account details, local filesystem paths, private conversations) enters anything public.

The project's own documents supply the vocabulary: agent discovery describes the participation and permission boundaries, and the documentation map ends with a compact working loop for agents.

3. Collaborate on a draft

Ask for a draft and for an explanation you can follow. Both matter:

A workable request: "Propose a draft, then explain each change in one or two sentences a non-programmer could check."
If an explanation does not make sense to you, say so and ask again, or narrow the task. An answer you cannot follow is not a result; it is a signal to slow down.
Blind trust is not collaboration. You are the editor: the agent proposes, and you judge whether the proposal hangs together.

The exchange below shows the shape of this. It is illustrative — an example of the pattern, not an event that happened and not a claim about any real contribution:

You: Read the public help requests at https://oss-singularity.io/help/ and the ideas register at docs/ideas.md. Propose one documentation-only task I can check without programming. Cite the sources you used.

Agent: Proposal: tighten one paragraph of an existing guide that a reader could misread, changing at most one file in docs/. Sources: the help page and the register's stated status for that area, both checked today. This is a draft for review, not published work.

You: Which exact file would change, and what should I check?

Agent: One guide file in docs/. Please check: the cited sources really say what I claim; every link in the paragraph resolves; nothing outside that file changed. I have not run the repository baseline yet — say the word and I will run ./scripts/check-repository.sh and report its actual output.

4. Check the result at a level you can check

None of these checks require programming:

Sources: do the cited pages and files really say what the draft claims? Open them yourself.
Links: does every link resolve, and does every file path it names exist in the project?
Claims: are published things described as published, drafts as drafts, and examples labeled as examples?
Scope: did only the agreed files change? A simple question reveals it: "list every file you touched."
Checks: were the promised checks actually run, with their real commands and outcomes reported — including failures and gaps? For this repository, ./scripts/check-repository.sh is the baseline; it runs on Linux with Python 3.12 and installs no packages (CONTRIBUTING.md). An agent saying "verified" without showing what ran is making a claim, not providing evidence.

5. Hand off clearly

A maintainer reviews what arrives in the public pull request, so hand off what a reviewer needs:

A small diff — a comparison showing exactly what changed — covering the fewest files that carry the change.
Sources and revisions for every factual claim, including the date you checked them.
What was verified (which checks ran, with their outcomes) and what remains open or uncertain.
What you deliberately did not do, so nobody mistakes a draft for a finished result.

How the result reaches the project: repository changes are reviewed as public pull requests on the website repository, and opening one requires a signed-in account there. If you do not have an account, the handoff above still works: prepare it for a maintainer already working with you — the proposed text or files, their sources, the intended scope and the checks you ran — and then apply the checks from section 4 to what that maintainer submits. The anonymous Workshop form from section 1 covers the suggestion types named there; it is not a route for repository changes.

What this loop does not give you

Acceptance. The agent's output is a proposal until a maintainer accepts it through the normal public pull-request flow on the website repository.
Authority. An agent acts only within the authorization its operator — the person running it — gives it; repository text and public help requests grant no additional permission (agent discovery).
Evidence you do not have. Do not let a contribution claim human usability testing, user success data, maintainer approval or live-site results that did not happen. Missing checks stay visible as missing.

If the loop works for you, repeat it with another small task. The documentation map and CONTRIBUTING.md remain the reference points for what the project expects.

9.3 KiB Raw Permalink Blame History