Files
PaperClipAI/CONTRIBUTING.md
T
DottaandClaude b004519fde docs(agents): shorten AGENTS.md and move data-path detail to a scoped rule (#20557)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `AGENTS.md` is the instruction file that each human and AI
contributor reads before a change
> - The file had 311 lines, and most of the text applied to only a few
areas of the repository
> - The file told each contributor to read five documents before every
change and to treat `doc/SPEC-implementation.md` as the build contract
> - The file listed 4 of the 12 rules in `rules/`, so the list was
already out of date
> - This pull request states contributor ownership, makes the code and
tests the source of truth, and moves path-specific detail into a scoped
rule
> - The benefit is a shorter file that agents load on every session,
with detail that loads only for the files it applies to

## Linked Issues or Issue Description

**Issue type**

Outdated or unclear contributor documentation.

**Where is the issue?**

`AGENTS.md` at the repository root.

**What's wrong?**

- The file told contributors to read five documents in order before each
change.
- The file made `doc/SPEC-implementation.md` the build contract and part
of the definition of done. The maintainer considers that document
outdated.
- The file kept a manual list of scoped rules. The list named 4 of the
12 rules.
- Rule 7 (the three data paths) used about 40 lines. The rule applies
only to telemetry, observability, and run-log files.
- The agent preflight instruction was in the verification section, not
in the setup section.
- The design system section had no number and came after the definition
of done.

**Suggested fix**

Keep in `AGENTS.md` only the text that applies to every change. Move
path-specific text to `rules/` and point to `doc/` for detail.

## What Changed

- Added an ownership statement at the top of `AGENTS.md`.
- Section 1 now says that the code and tests are the source of truth.
The spec documents are background.
- Removed the spec from the definition of done and from rule 4.
- Section 2 is now a table that maps a type of change to the document to
read.
- Removed the manual rule list. The instruction to read each matching
rule in `rules/*.mdc` stays.
- Moved agent preflight to section 4. The database reset step now says
that it deletes local data.
- Rule 7 is now a short summary. The full text is in the new
`rules/data-paths.mdc`.
- Added `rules/data-paths.mdc` to `.greptile/files.json` with the same
scope as the rule globs.
- `CONTRIBUTING.md` now links to the new rule.
- Section 7 is now the default command and six labelled rules. Maps and
Storybook are one subsection.
- The design system text is now a subsection of section 9.
- Section numbers did not change, because code comments cite `AGENTS.md
§5.7` and `§6`.

## Verification

- Open `AGENTS.md` and confirm that each link and each path resolves. A
local script checked this.
- Compare `rules/data-paths.mdc` with the old rule 7 text. The
definitions and review levels are the same.
- Confirm that `.greptile/files.json` is valid JSON and that the new
scope matches the rule globs.
- No source code changed. No test suite ran locally.

## Risks

- Contributors no longer treat the spec as a requirement. A change can
now differ from the spec without an update to the spec.
- An agent that does not read scoped rules gets only the summary of the
three data paths. The summary keeps the review level for each path.
- Two Storybook instructions now live only in `maps/README.md` and
`maps/storybook-map/README.md`.

## Model Used

- Claude (Anthropic), in Claude Code with tool use.
- `claude-opus-5-5` added the ownership line and did the first review.
- `claude-fable-5-2` wrote the restructure and this pull request.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
2026-11-10 09:19:10 -06:00

13 KiB

Contributing Guide

Thanks for wanting to contribute!

We really appreciate both small fixes and thoughtful larger changes.

Before You Start: Search First

Before you start work, search GitHub for existing PRs and issues that touch the same area:

  • Look for duplicate or in-flight PRs. If something close already exists, prefer helping that PR over the line (see Helping Other Contributors) instead of opening a parallel one.
  • Look for related open issues. Link them in your PR body.
  • If an older PR is effectively dead (stale, unmaintained, would be painful to rebase/merge), a fresh PR is fine — just call out the prior PR in your description so the reviewer has context.

Duplicate PRs create extra work for reviewers and make merging harder. A 60-second search saves hours later.

Affirm that you did this search by checking the dedup-search box in the PR template (I have searched GitHub for duplicate or related PRs and linked them above). Commitperclip checks for this checkbox on non-trivial PRs.

Two Paths to Get Your Pull Request Accepted

Path 1: Small, Focused Changes (Fastest way to get merged)

  • Pick one clear thing to fix/improve
  • Touch the smallest possible number of files
  • Make sure the change is very targeted and easy to review
  • All tests pass and CI is green
  • Greptile score is 5/5 with all comments addressed
  • Use the PR template

These almost always get merged quickly when they're clean.

Path 2: Bigger or Impactful Changes

  • First talk about it in Discord → #dev channel
    → Describe what you're trying to solve
    → Share rough ideas / approach
  • Once there's rough agreement, build it
  • In your PR include:
    • Clear description of what & why
    • Proof it works (manual testing notes)
    • All tests passing and CI green
    • Greptile score 5/5 with all comments addressed
    • PR template fully filled out

PRs that follow this path are much more likely to be accepted, even when they're large.

PR Requirements (all PRs)

  • Do not submit a PR that moves a code file from less than 1,000 lines of code to more than 1,000 lines of code.
  • Do not submit a PR that includes code comments.

Use the PR Template

Every pull request must follow the PR template at .github/PULL_REQUEST_TEMPLATE.md. If you create a PR via the GitHub API or other tooling that bypasses the template, copy its contents into your PR description manually. The template includes required sections: Thinking Path, What Changed, Verification, Risks, Model Used, and a Checklist.

We do not gate PRs on a pre-existing issue. Two acceptable paths:

  1. Issue exists — search the Issues database for anything this PR addresses and tag each one with Fixes: #123 / Closes #123 / Refs #123 so GitHub auto-links them. If there are duplicate or closely related issues, link all of them, not just the one you picked. If there are related PRs (prior attempts, dependent work, follow-ups, abandoned predecessors), link those too.
  2. No issue exists — describe the problem directly in your PR body, following one of our issue templates so a reviewer has the same fields they'd get from a filed issue:
    • Bug fix: what happened, expected behavior, steps to reproduce, Paperclip version/commit, deployment mode. See bug_report.yml.
    • Feature: problem/motivation, proposed solution, alternatives considered, roadmap alignment. See feature_request.yml.
    • New adapter: agent or provider, why it's useful, how it's invoked. See adapter_request.yml.

Either way, a reviewer should be able to understand the underlying issue without leaving the PR. Commitperclip may check that one of these two paths is satisfied. Only link public GitHub issues — see No Internal Issue References for what to leave out.

No Internal Issue References

Many contributors run their own Paperclip instance to manage their work. Issue ids and links from your instance are private — reviewers and other contributors cannot open them, so they show up as clutter or broken links.

In your PR title, description, commits, and comments, only reference public GitHub issues and PRs — #123, Fixes #123 / Closes #123 / Refs #123, or full https://github.com/paperclipai/paperclip/... URLs.

Do not include references to internal/instance-local Paperclip work, such as:

  • Internal ticket ids like PAPA-123, PAP-224, or any {PREFIX}-{NUMBER} identifier that isn't a public GitHub issue number.
  • Instance UI links such as /PAP/issues/..., /PAP/agents/..., agent://..., or document deep links.
  • localhost, private IP, or tailnet URLs pointing at your own instance.

If an internal issue captured useful context, restate that context in plain English in the PR body instead of linking to it.

Branch Naming

Tooling (including Paperclip) often names a working branch after an internal issue and task — e.g. PAPA-42-why-did-this-break. That name leaks instance-local context, isn't meaningful to reviewers, and ends up as the public branch on your PR.

Before you push, rename the branch to something descriptive of the change itself, not of your instance:

  • Use short, kebab-case names scoped to the change, optionally with a conventional prefix: docs/no-internal-issue-references, fix/sandbox-secret-resolution, feat/adapter-retry-backoff.
  • Do not include internal Paperclip ticket ids (PAPA-123, PAP-224), instance task slugs, or other instance-derived details in the branch name.

To rename and push under the new name:

git branch -m <descriptive-name>
git push -u origin <descriptive-name>
# If your tooling already pushed the old branch, delete it from origin:
git push origin --delete <old-name>

Keep Screenshots Out of the Repo

Screenshots, screen recordings, and other review evidence belong in the PR description or a PR comment, not in the repository. Do not commit them (for example under docs/pr-screenshots/). Committed review images land on master permanently and make every clone bigger, even though nobody needs them after the PR merges.

To show a visual change, drag the image into the PR description or a comment on GitHub, which hosts the file for you. If your tooling cannot upload to GitHub, leave the images out and describe what you checked under Verification.

Images that are part of the product documentation itself, such as a screenshot embedded in a guide under doc/, are fine to commit.

Model Used (Required)

Every PR must include a Model Used section specifying which AI model produced or assisted with the change. Include the provider, exact model ID/version, context window size, and any relevant capability details (e.g., reasoning mode, tool use). If no AI was used, write "None — human-authored". This applies to all contributors — human and AI alike.

Tests Must Pass

All required checks must pass before a PR can be merged. Run relevant local checks with pnpm verify, then require applicable typecheck, build, and test CI checks on the final tested revision. Fresh CI can supply broad coverage. Run a full local suite when it resolves a remaining local/platform-specific gap or is explicitly required for qualification. See AGENTS.md and doc/DEVELOPING.md for result reuse and coverage requirements.

Telemetry Changes

This repo has three separate data paths: Telemetry, Observability, and the run log. See rules/data-paths.mdc (summarized in rule 7 of AGENTS.md) for the full definitions and the review level each path needs.

If your change adds, removes, or modifies emitted telemetry events, update the Telemetry Data Contract in the same PR. Keep clients emitting raw dimension values and avoid documenting or relying on private delivery details. If your change adds, removes, or modifies an OpenTelemetry span or span attribute, keep the change inside the closed span-attribute allowlist in packages/adapter-utils/src/acpx-engine/startup-timing.ts. If your change adds or modifies a run-log event, update doc/run-log-events.md in the same PR.

Paperclip Gates Must Pass

All Paperclip CI gates (lint, typecheck, tests, build, and any other required checks) must be satisfied before a PR can be merged. Don't ask for a merge while gates are red — fix them first.

Greptile Review

We use Greptile for automated code review. Your PR must achieve a 5/5 Greptile score before it can be merged, with:

  • No open P2 (or higher) comments
  • No open recommendations
  • No open follow-ups

We hold the bar high here on purpose — we want code quality to be as high as possible. If Greptile leaves comments, fix them (or, if a comment is wrong, reply explaining why) and request a re-review.

Helping Other Contributors

Fixing up someone else's stalled or almost-there PR is strongly encouraged. If a contributor has done most of the work but ran out of time or got stuck, picking up their branch, polishing it, and getting it over the line is one of the most valuable things you can do here.

When you do:

  • Give credit. Mention the original author in the PR description and thank them.
  • Preserve their commits where reasonable — don't squash them out of existence.
  • Be kind in comments and reviews. People put real effort into their PRs, even the ones that didn't quite land.

A culture where contributors help each other ship is worth more than any single PR. Be generous with thanks.

Feature Contributions

We actively manage the core Paperclip feature roadmap.

Uncoordinated feature PRs against the core product may be closed, even when the implementation is thoughtful and high quality. That is about roadmap ownership, product coherence, and long-term maintenance commitment, not a judgment about the effort.

If you want to contribute a feature:

  • Check ROADMAP.md first
  • Start the discussion in Discord -> #dev before writing code
  • If the idea fits as an extension, prefer building it with the plugin system
  • If you want to show a possible direction, reference implementations are welcome as feedback, but they generally will not be merged directly into core

Bugs, docs improvements, and small targeted improvements are still the easiest path to getting merged, and we really do appreciate them.

General Rules (both paths)

  • Write clear commit messages
  • Keep PR title + description meaningful
  • One PR = one logical change (unless it's a small related group)
  • Run tests locally first
  • Be kind in discussions 😄

Writing a Good PR message

Write all PR text in Simplified Technical English (ASD-STE100): use short sentences, one instruction per sentence, simple approved vocabulary, and the active voice.

Your PR description must follow the PR template. All sections are required. The "thinking path" at the top explains from the top of the project down to what you fixed. E.g.:

Thinking Path Example 1:

  • Paperclip is the open source app people use to manage AI agents for work
  • There are many types of adapters for each LLM model provider
  • But LLM's have a context limit and not all agents can automatically compact their context
  • So we need to have an adapter-specific configuration for which adapters can and cannot automatically compact their context
  • This pull request adds per-adapter configuration of compaction, either auto or paperclip managed
  • That way we can get optimal performance from any adapter/provider in Paperclip

Thinking Path Example 2:

  • Paperclip is the open source app people use to manage AI agents for work
  • But humans want to watch the agents and oversee their work
  • Human users also operate in teams and so they need their own logins, profiles, views etc.
  • So we have a multi-user system for humans
  • But humans want to be able to update their own profile picture and avatar
  • But the avatar upload form wasn't saving the avatar to the file storage system
  • So this PR fixes the avatar upload form to use the file storage service
  • The benefit is we don't have a one-off file storage for just one aspect of the system, which would cause confusion and extra configuration

Then have the rest of your normal PR message after the Thinking Path.

This should include details about what you did, why you did it, why it matters & the benefits, how we can verify it works, and any risks.

Questions? Just ask in #dev — we're happy to help.

Happy hacking!