# Contributing-with-an-agent guide: fresh continuation pass, 2026-10-16 This is the project's account of one completed continuation exercise on the [contributing-with-an-agent guide](contributing-with-an-agent.md) and [brief revision 3](project-brief.md). It records what a fresh agent received and did; it is not a verbatim quotation, a usability test, or a maintainer review. Both the guide's authoring pass and this continuation pass were performed by AI agents — no human authored the guide, and human usability testing has not happened — so everything described below remains a proposal until maintainer review in the normal public pull-request flow decides it. ## Method and checked sources One fresh agent received only the pinned artifacts — the guide (`docs/contributing-with-an-agent.md`) and brief revision 3 (`docs/project-brief.md`) at commit `8cec1999131d297d330d6a3f7f2fbb5453acc98f` (based on `forge/main` at `0818e78d9740e833fc23e3a22bddde5bc6a07811`), plus the guide's single index link in the [documentation map](README.md) — a concrete list of improvement candidates, and public sources. It did not have the authoring conversation, and no other context. It read the two documents end to end as the guide's intended reader (a person without programming skills), then checked the sources for each candidate change: - [CONTRIBUTING.md](../CONTRIBUTING.md) in the same checkout: the first-project-journey paragraph, the three first tasks, and the [documentation map](README.md). - Live public pages fetched over HTTPS on 2026-10-16: `https://oss-singularity.io/connect/` (HTTP 200; the served HTML contains `id="project-path"`, and its four steps are discover a purpose, understand public sources, prepare a contribution draft, make it possible to return), `https://oss-singularity.io/workshop/` (HTTP 200; contains `id="contribute"`; submissions enter a review queue before publication), `https://oss-singularity.io/help/` (HTTP 200; individual help requests each carry an `Acceptance:` line), and `https://oss-oo.io/OSS-Singularity/website` (HTTP 200). - Repository documents the guide cites: [atlas-sources.md](atlas-sources.md) (describes the Atlas as a curated catalog of the agent ecosystem), [ideas.md](ideas.md), [agent-discovery.md](agent-discovery.md), [workshop-ui.md](workshop-ui.md) (ordinary, non-review contributions can be anonymous), [brand-inputs.md](brand-inputs.md), [security-testing.md](security-testing.md), and the [fresh-reader observation](project-brief-reader-observation-2026-10-15.md) used as the shape for this record. At the time of the exercise the pinned commit existed only in the session's checkout, so it is identified above by path and commit hash rather than by an immutable remote link. ## Findings and decisions The agent made three accepted improvements to the guide and rejected the rest; every change keeps the guide's existing voice (proposal until merged; agent checks support, never replace, maintainer review; illustrative examples labeled). 1. **Added the Connect project path as an entry point** (accepted). The guide's "Choose one small useful task" list omitted the project's own visible first-journey surface, which CONTRIBUTING.md names ("The visible entry is Connect's project path") and the brief lists among its starting points. A newcomer bullet now links `https://oss-singularity.io/connect/#project-path` with the brief's discover → understand → draft → return summary, sourced to both documents. The live anchor and the four steps were verified as above. 2. **Added the Workshop contribution form to the Atlas-research bullet** (accepted, scoped). CONTRIBUTING.md attaches the form to exactly this task: it "accepts ordinary suggestions without an account or a code change; moderation and editorial review precede any Atlas change". The guide's reader may be unable or unwilling to work through a pull request, so it now names the form as the path for a correction that will not become a pull request, keeping the review-before-change boundary explicit. It was not added as a general second track: the guide is about working with an agent on a repository change, and the form is the documented destination for one of its listed task types. 3. **Glossed terms a non-programmer may not know** (accepted). Brief parentheticals now explain pull request, repository, Atlas entry and "synthetic inputs" at first use, "operator" in the closing section, and one jargon phrase in the checklist ("repository path" became "file path … in the project"). The intro sentence about acceptance was tightened to scope the pull-request flow to file changes, so the form's moderation path does not contradict it. The project's own terms remain alongside every gloss. 4. **No other changes** (rejected after checking). Every existing link and anchor in the guide resolved on 2026-10-16, the guide's descriptions of the help page, ideas register and agent-discovery document match those sources, and the structure held up when read end to end. Submission mechanics (how an agent could push branches or open pull requests) were deliberately not added: the brief lists authenticated agent contributions as separate roadmap work, and such a passage would outrun its sources. After an owner review of this continuation, the same session made four further small edits on owner direction (2026-10-16): the brief's scope and next action now name the four contribution artifacts; the guide gained an explicit ending on how work reaches the project — pull requests need a signed-in account (checked anonymously on the live forge: the compare view offers sign-in, not a pull-request form), and without one the handoff goes to a maintainer already working with you, while the Workshop form stays limited to the suggestion types the guide's section 1 names; "diff" is explained in plain language at first use; and the guide and this record now state their AI authorship, with maintainer review and human usability testing open. Checks run on 2026-10-16 from the session worktree, documentation-only scope: `./scripts/check-repository.sh` passed ("repository baseline checks passed"); the site-boundary checker reported no hits; every repository path the guide names exists in the tree. The full product/runtime suites were not run; they are unaffected by a documentation-only change and belong to the pull-request review. ## Limits This was one fresh agent and one pass, not a human usability test or a representative sample. It evaluates the guide as a document — coverage of entry points, accuracy against public sources, and readability — and does not establish that real newcomers succeed with it, that maintainers accept any of it, or that the live pages will remain as fetched. The pinned revision was read in a private session checkout; the live-page checks are point-in-time HTTP fetches, not a monitoring claim. Nothing here constitutes maintainer review, plugin or catalog acceptance, authenticated agent writes, or a change to the contribution's scope beyond the files this pass and its owner-directed follow-up touched: the guide, this record, and the brief updates described above.