# 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](contributing-with-an-agent-continuation-2026-10-16.md)). It is
accepted source work: maintainer `ClaudiuSchuster` merged [PR
25](https://oss-oo.io/OSS-Singularity/website/pulls/25) on 2026-10-16 at commit
[`3fec7e031761fcacbccb15af508cd064120c8143`](https://oss-oo.io/OSS-Singularity/website/src/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](project-brief.md): the project's purpose, its
  published state and the one next allowed action it names.
- [Connect project path](https://oss-singularity.io/connect/#project-path):
  the site's visible entry for a first project journey — discover →
  understand → draft → return — named in [CONTRIBUTING.md](../CONTRIBUTING.md)
  and listed among the [project brief](project-brief.md) starting points.
- [Choose one small contribution](../CONTRIBUTING.md#choose-one-small-contribution)
  in the contributor guide: three concrete first tasks.
- [Public help requests](https://oss-singularity.io/help/): bounded voluntary
  opportunities, each with its acceptance criteria. These are offers to
  contribute, not assignments or permission to test infrastructure.
- [Ideas register](ideas.md): 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](atlas-sources.md). A correction you cannot or do not
  want to turn into a pull request can go to the
  [Workshop contribution form](https://oss-singularity.io/workshop/#contribute),
  which accepts ordinary suggestions without an account or a code change;
  moderation and review precede any Atlas change
  ([CONTRIBUTING.md](../CONTRIBUTING.md)).
- Art or branding input: propose wording or visual ideas within the
  established identity in [brand inputs](brand-inputs.md) and
  [BRANDING.md](../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](project-brief-reader-observation-2026-10-15.md)
  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](../CONTRIBUTING.md); follow
  [SECURITY.md](../SECURITY.md) before sharing anything exploitable, and see
  the [local security-testing guide](security-testing.md) 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](agent-discovery.md) describes the participation and permission
boundaries, and the [documentation map](README.md) 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](../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](https://oss-oo.io/OSS-Singularity/website), 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](https://oss-oo.io/OSS-Singularity/website).
- 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](agent-discovery.md)).
- 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](README.md) and [CONTRIBUTING.md](../CONTRIBUTING.md)
remain the reference points for what the project expects.