Files
PaperClipAI/AGENTS.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

AGENTS.md

Guidance for human and AI contributors working in this repository.

This codebase is yours: what it's for and how it's built are your call, and you'll keep building on it. The invariants and rules below record what has been decided so far. If you think one of them is wrong, say so and propose the change; do not work around it.

1. Purpose

Paperclip is a control plane for AI-agent companies. The code and its tests are the source of truth for current behavior. doc/SPEC-implementation.md and doc/SPEC.md are background. They can be out of date, so do not treat them as requirements when they disagree with the code or with the task.

2. Read This First

Read the doc that matches your change before you start:

Your change touches Read
Product behavior or scope doc/GOAL.md, doc/PRODUCT.md
Setup, commands, testing, worktrees doc/DEVELOPING.md
Schema, migrations, DB clients doc/DATABASE.md
An Apps catalog connection doc/connections/CONNECTOR-PLAYBOOK.md (the canonical connection authoring runbook)
Anything under ui/ DESIGN.md

Scoped repository rules

Before editing or reviewing files, read the matching rules in rules/*.mdc. Each rule has Markdown content and YAML frontmatter: globs contains comma-separated, repository-relative file patterns, and alwaysApply: true means the rule applies throughout the repository. Read all rules whose scope matches the affected files. These rules supplement this file and any applicable nested AGENTS.md instructions.

The frontmatter is the source of truth for scope, so this file does not list the rules. See rules/README.md for rule authoring and Greptile setup.

3. Repo Map

  • server/: Express REST API and orchestration services
  • ui/: React + Vite board UI
  • packages/db/: Drizzle schema, migrations, DB clients
  • packages/shared/: shared types, constants, validators, API path constants
  • packages/adapters/: agent adapter implementations (Claude, Codex, Cursor, etc.)
  • packages/adapter-utils/: shared adapter utilities
  • packages/plugins/: plugin system packages
  • packages/skills-catalog/: app-shipped skills catalog (@paperclipai/skills-catalog)
  • packages/teams-catalog/: app-shipped teams catalog (@paperclipai/teams-catalog)
  • cli/: paperclipai CLI package (published bin, agent-facing commands)
  • skills/: Paperclip runtime/operational skills (not part of the app catalog)
  • doc/: operational and product docs
  • rules/: scoped repository rules (see section 2)

4. Dev Setup (Auto DB)

Prepare a new or updated worktree with one command:

node scripts/agent-preflight.mjs

Use it instead of running pnpm install, the Runner build, and build:rust by hand. It skips unchanged steps and reuses other worktrees' builds from a content-keyed cache in ~/.cache/paperclip/agent-build. Do not share CARGO_TARGET_DIR between worktrees. See "Agent worktree preflight" in doc/DEVELOPING.md.

Start the app. Leave DATABASE_URL unset to use embedded PGlite:

pnpm dev

This serves the API and the UI at http://localhost:3100 (the API server serves the UI in dev middleware mode).

Quick checks:

curl http://localhost:3100/api/health
curl http://localhost:3100/api/companies

Reset the local dev DB. This deletes all local dev data:

rm -rf data/pglite
pnpm dev

5. Core Engineering Rules

  1. Keep changes company-scoped. Every domain entity should be scoped to a company and company boundaries must be enforced in routes/services.

Explicit exception: announcement dismissals are instance-wide user preferences, keyed by user and announcement so they persist across companies. Their audit context must still validate company membership. The announcement publication-ID registry is instance-level feed metadata; it contains no company or user data. Personal workspace presentation preferences are also instance-wide by user, with validated company membership supplying audit context. They never grant execution authority, change company capabilities or agent configuration, or rewrite canonical work records. Optional conversation guidance must retain the same action permissions.

  1. Keep contracts synchronized. If you change schema/API behavior, update all impacted layers:
  • packages/db schema and exports
  • packages/shared types/constants/validators
  • server routes/services
  • ui API clients and pages
  1. Preserve control-plane invariants.
  • Single-assignee task model
  • Atomic issue checkout semantics
  • Approval gates for governed actions
  • Budget hard-stop auto-pause behavior
  • Activity logging for mutating actions
  1. Do not replace strategic docs wholesale unless asked. Prefer additive updates.

  2. Keep repo plan docs dated and centralized. When you are creating a plan file in the repository itself, new plan documents belong in doc/plans/ and should use YYYY-MM-DD-slug.md filenames. This does not replace Paperclip issue planning: if a Paperclip issue asks for a plan, update the issue plan document per the paperclip skill instead of creating a repo markdown file.

  3. Attach inspectable generated artifacts. When your task produces a user-inspectable deliverable file, follow the Paperclip skill's "Generated Artifacts and Work Products" workflow before final disposition. In this repo, prefer the self-contained skill helper at skills/paperclip/scripts/paperclip-upload-artifact.sh so the file is available through the Paperclip API, create/update an artifact work product when the file is the deliverable, link the uploaded artifact in the final issue comment, and then set status. Do not rely on local filesystem paths as the only access path. If an important file intentionally remains workspace-only, create/update a work product with metadata.resourceRef.kind: "workspace_file" and a workspace-relative path, then name that work product and path in the final comment. Treat browse/search as a fallback for recovering workspace files, not the preferred deliverable path. See doc/AGENT-ARTIFACTS.md for details and .mp4/.webm examples.

  4. Name the three data paths correctly. This repo has three separate data paths. Do not confuse them. Match a change to a path by its file path, not by the word "observability" or "telemetry" alone.

  • Telemetry is the Paperclip first-party event system under packages/shared/src/telemetry/. It sends data to a Paperclip endpoint by default, so a change needs strict review: generated contract first, README update, privacy review.
  • Observability is the OpenTelemetry trace path. It is a no-operation until an operator sets an OTLP endpoint. A change needs lighter review while it keeps that gate and stays inside the span-attribute allowlist.
  • The run log holds rows in the local heartbeat_run_events table. The data stays in the instance database, so a change needs no extra review.

Before you change any of these paths or add a Telemetry caller, read rules/data-paths.mdc for the exact file paths and review requirements.

6. Database Change Workflow

When changing data model:

  1. Edit packages/db/src/schema/*.ts
  2. Ensure new tables are exported from packages/db/src/schema/index.ts
  3. Generate migration:
pnpm db:generate
  1. Validate compile:
pnpm -r typecheck

Notes:

  • packages/db/drizzle.config.ts reads compiled schema from dist/schema/*.js
  • pnpm db:generate compiles packages/db first

7. Verification Before Hand-off

Run the smallest check that proves the change. The default local and agent path is:

pnpm verify

This selects affected Vitest files with the same conservative dependency policy as CI. It includes committed, staged, unstaged, and untracked changes against the merge base with local origin/master (or master), and it reuses passing checks whose inputs are unchanged. Use --base <ref> for another base, --explain to inspect the selection, and --no-cache for fresh execution. See "Incremental local verification" in doc/DEVELOPING.md for how reuse and invalidation work.

Follow these rules:

  • Exit 2 means the change needs broader verification. Run focused checks and let required CI supply that coverage, or explicitly use pnpm verify --full for the full local Vitest suite. Do not automatically follow exit 2 with a full local run.
  • Do not default to repo-wide checks. Do not run repo-wide typecheck, build, or test on every heartbeat when a narrower check is enough to prove the change. Use the broad checks below only when they resolve an actual remaining gap, such as a local platform fault or explicit full-suite qualification.
  • Browser suites stay opt-in. Run pnpm test:e2e and pnpm test:release-smoke only when your change touches them or when you are explicitly verifying CI/release flows.
  • CI covers the final revision. For a PR-ready handoff, run the relevant local checks and require the applicable CI typecheck, build, and test checks to pass for the final tested revision. Record their scope, revision, environment, and result links. Fresh CI can supply broad coverage; do not duplicate a full local run merely to prepare a PR, resume a chat, or repeat unchanged passing verification. A selected local pass does not replace required CI, release qualification, browser acceptance, or a local/platform-specific regression.
  • Evidence expires. After edits or a rebase, rerun affected checks and invalidate evidence whose inputs or required coverage changed. Failed or interrupted attempts are never passes.
  • Report gaps. If anything cannot be run, explicitly report what was not run and why.

Broad local checks:

pnpm -r typecheck
pnpm test:run
pnpm build

pnpm test and pnpm test:run run the full suite. If memory is limited, use node scripts/typecheck-low-memory.mjs instead of pnpm -r typecheck. See doc/DEVELOPING.md.

Maps and Storybook

The feature map and the sibling agent access map are optional references for user entry points, agent entry points, permission boundaries, verification recipes, and coverage gaps. They record coverage scope, not proof that a live journey passed. Routine fixes, polish, refactors, and test changes do not require map updates. When you do edit a map, follow the feature-map scope rule and the map contract, then run node scripts/check-maps.mjs.

After story or recipe changes, update the affected source annotations or recipe and run node scripts/storybook-catalog.mjs. Indexes are generated and ignored; never commit them. See the Storybook feature catalog for the full workflow. Structural checks are not production acceptance.

8. API and Auth Expectations

  • Base path: /api
  • Board access is treated as full-control operator context
  • Agent access uses bearer API keys (agent_api_keys), hashed at rest
  • Agent keys must not access other companies

When adding endpoints:

  • apply company access checks
  • enforce actor permissions (board vs agent)
  • write activity log entries for mutations
  • return consistent HTTP errors (400/401/403/404/409/422/500)

9. UI Expectations

  • Keep routes and nav aligned with available API surface
  • Use company selection context for company-scoped pages
  • Surface failures clearly; do not silently ignore API errors
  • Form and wizard footers: keep Save & exit (or Cancel/Back) left and the primary action right in the same vertically aligned row. Each step owns the entire footer; never append Save & exit as a separate row. See DESIGN.md.

Design system

DESIGN.md at the repo root is the source of truth for UI design decisions. The token-only rule applies to all ui/ changes: every color, spacing, radius, type, shadow, and motion value in ui/src/components/** and ui/src/pages/** comes from the token layer in ui/src/index.css — no hex, raw px, arbitrary Tailwind bracket values, or raw font-size/fontSize declarations in components, outside the documented allowlist in ui/src/index.css. Run pnpm check:token-gates (scripts/check-token-gates.mjs) before committing UI changes — it fails on any violation not covered by that allowlist.

10. Pull Request Requirements

When creating a pull request (via gh pr create or any other method), you must read and fill in every section of .github/PULL_REQUEST_TEMPLATE.md. Do not craft ad-hoc PR bodies — use the template as the structure for your PR description. Required sections:

  • Thinking Path — trace reasoning from project context to this change (see CONTRIBUTING.md for examples)
  • What Changed — bullet list of concrete changes
  • Verification — how a reviewer can confirm it works
  • Risks — what could go wrong
  • Model Used — the AI model that produced or assisted with the change (provider, exact model ID, context window, capabilities). Write "None — human-authored" if no AI was used.
  • Checklist — all items checked

11. Definition of Done

A change is done when all are true:

  1. Behavior matches what the task asked for and preserves the invariants in section 5
  2. Relevant local verification and required CI typecheck, test, and build checks pass for the final revision, with any acceptance or platform-specific gaps resolved (section 7)
  3. Contracts are synced across db/shared/server/ui
  4. Docs updated when behavior or commands change
  5. PR description follows the PR template with all sections filled in (including Model Used)