## 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>
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 servicesui/: React + Vite board UIpackages/db/: Drizzle schema, migrations, DB clientspackages/shared/: shared types, constants, validators, API path constantspackages/adapters/: agent adapter implementations (Claude, Codex, Cursor, etc.)packages/adapter-utils/: shared adapter utilitiespackages/plugins/: plugin system packagespackages/skills-catalog/: app-shipped skills catalog (@paperclipai/skills-catalog)packages/teams-catalog/: app-shipped teams catalog (@paperclipai/teams-catalog)cli/:paperclipaiCLI package (published bin, agent-facing commands)skills/: Paperclip runtime/operational skills (not part of the app catalog)doc/: operational and product docsrules/: 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
- 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.
- Keep contracts synchronized. If you change schema/API behavior, update all impacted layers:
packages/dbschema and exportspackages/sharedtypes/constants/validatorsserverroutes/servicesuiAPI clients and pages
- 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
-
Do not replace strategic docs wholesale unless asked. Prefer additive updates.
-
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 useYYYY-MM-DD-slug.mdfilenames. This does not replace Paperclip issue planning: if a Paperclip issue asks for a plan, update the issueplandocument per thepaperclipskill instead of creating a repo markdown file. -
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.shso 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 withmetadata.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. Seedoc/AGENT-ARTIFACTS.mdfor details and.mp4/.webmexamples. -
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_eventstable. 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:
- Edit
packages/db/src/schema/*.ts - Ensure new tables are exported from
packages/db/src/schema/index.ts - Generate migration:
pnpm db:generate
- Validate compile:
pnpm -r typecheck
Notes:
packages/db/drizzle.config.tsreads compiled schema fromdist/schema/*.jspnpm db:generatecompilespackages/dbfirst
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 --fullfor 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:e2eandpnpm test:release-smokeonly 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.mdfor 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:
- Behavior matches what the task asked for and preserves the invariants in section 5
- 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)
- Contracts are synced across db/shared/server/ui
- Docs updated when behavior or commands change
- PR description follows the PR template with all sections filled in (including Model Used)