Files
PaperClipAI/AGENTS.md
T
DottaandClaude Fable 5.2 d6acbf50e6 refactor: cut DATABASE.md to setup and schema-change rules (#21700)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `AGENTS.md` tells every contributor and agent to read
`doc/DATABASE.md` before a schema or migration change
> - That file grew to 2,611 lines. About 1,950 of them were notes on the
tables of one feature, added one pull request at a time
> - The setup steps and the migration rules started at line 792, below
those notes
> - This pull request cuts `doc/DATABASE.md` to 377 lines: setup, and
the rules that apply to every schema change
> - The benefit is a guide that a person or an agent can read in full
before a schema change

## Linked Issues or Issue Description

Refs #21670 (the same cleanup for `doc/DEVELOPING.md`).

**Issue type**

Outdated or confusing documentation.

**Where is the issue?**

`doc/DATABASE.md`

**What's wrong?**

The file was 2,611 lines. It opened with a Better Auth upgrade note and
492 lines on task query performance. The schema change workflow started
at line 1367.

**Suggested fix**

Keep database setup and the general rules in `doc/DATABASE.md`. Remove
the notes on individual tables. The schema and its tests describe those.

## What Changed

- `doc/DATABASE.md` is now 377 lines. It keeps the three database modes,
client tuning, the schema change workflow, migration compatibility, the
migration authoring checklist, migration snapshots, the rule for retries
after a lost connection, transaction-aware work signals, plugin
namespaces, and backups. The wording of the kept text is unchanged.
- New `doc/database-client-internals.md` holds the response-size
diagnostic, the notes on the postgres.js patch, and the transaction
memory note. The text is moved without wording changes.
- "Experimental remote workspace snapshots" moved to
`doc/workspace-storage.md`, which links to it.
- "Execution admission accounting" moved to
`server/src/modules/README.md`, which links to it.
- Deleted about 1,950 lines of notes on one feature each. No other file
linked to them. The deleted sections are: Better Auth 1.7.16 upgrade,
Durable native provider backups, Workspace cohort admission proofs,
Original local Git sources for archived workspaces, Proactive agent chat
messages, Persistent case handoffs, Task query performance, Tool profile
reads, Execution identity row locks, Remote workspace row locks, Managed
adapter settings, Cloud configuration migration receipt, Cloud runtime
identity singleton, Unclaimed Cloud warm standby, Native finalization
history and idle sleep, Feedback history and idle sleep, Resource
membership tables, Decision training snapshot retention, Decision queues
and triage provenance, Native runner persistence, Chat communication
snapshots, Telegram private draft identities, Attachment upload
provenance, Question-response delivery receipts, Secret storage,
Persistent agent conversations, Resource lifecycle events, Legacy
controller ownership, Agent file persistence and legacy revisions, Large
API response snapshots, Runner API response reservations, Internal agent
commentary, Agent identity keys and backups, Slack app registration,
Slack manager workspace grants, Installed skill packages, Project
repository skill synchronization, Task workspace records, Execution
recovery query performance, Agent runtime synchronization journal,
Retired Pipelines storage, Prompt injection classification, Deferred
conversation requests, GitHub inherited review-wait reads, Sandbox
creation ownership, Object-backed run evidence, Cloud runtime
configuration singleton, Independent accounting and budget evaluation,
Standard workspace and Classic opt-in, Project environment rolling
compatibility.
- Also deleted from kept sections: the subscription-table note and the
issue-reference backfill note in the embedded mode section, the HTTP
access log note and the per-endpoint retry notes in the connection loss
section, and the notes on migrations `0355`, `0313`, and `0314` in the
authoring checklist.
- `AGENTS.md` now states what `doc/DATABASE.md` is for.

## Verification

- A script built the new files by line range from the old file. It
asserts the old line count and the first line of each range.
- A link check on every changed Markdown file, and on the four files
that link to a `DATABASE.md` anchor, found 0 missing files and 0 missing
anchors.
- `node scripts/check-maps.mjs` passes.
- `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail.
- `pnpm verify` was not run. This worktree has no installed
dependencies, and the change has no runtime code.

## Risks

- The deleted notes were not all read in full before deletion. The
decision was by section: a section about one feature's tables, with no
inbound link, was deleted. The text stays in git history.
- Two deleted sections describe procedures for an operator: the
duplicate-account check before the Better Auth 1.7.16 migration, and the
secret storage tables. Restore them into a focused doc if operators
still need them.
- No runtime behavior changes.

## Model Used

- Claude Fable 5.2 (`claude-fable-5-2`), Claude Code desktop, with tool
use.

## 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
- [x] I have run tests locally and they pass
- [ ] 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 Fable 5.2 <noreply@anthropic.com>
2026-11-14 20:01:28 -06:00

10 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. The focused docs under doc/ 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

rules/*.mdc holds the architecture rules that reviewers apply to a pull request. Each file starts with a short header: description is a one-sentence summary of the rule, globs lists the files it covers, and alwaysApply: true means it covers the whole repository.

You do not need to read the rule bodies before every change. List the headers to see which rules exist and what each one asks for:

grep -E '^(description|globs|alwaysApply):' rules/*.mdc

Write the change so that it satisfies the descriptions of the rules that cover your files. Read the full body of a rule only in these cases:

  • You are making a design decision in the area the rule covers, such as adding a module, a background worker, or persisted state.
  • The description does not tell you whether your change complies.
  • A reviewer cites the rule.

These rules supplement this file and any applicable nested AGENTS.md instructions. 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
  • doc/plans/: dated repo plan docs, named YYYY-MM-DD-slug.md. A plan for a Paperclip issue goes in the issue's plan document instead.
  • rules/: scoped repository rules (see section 2)

4. Dev Setup

node scripts/agent-preflight.mjs   # prepare a new or updated worktree
pnpm dev                           # API and UI at http://localhost:3100

Leave DATABASE_URL unset to use the embedded database. See "Agent worktree preflight", "Start Dev", "Quick Health Checks", and "Database in Dev" in doc/DEVELOPING.md.

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. The few instance-wide exceptions are listed in rules/company-scope-exceptions.mdc. Do not add another without adding it to that list.

  2. 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
  3. 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
  4. Keep behavior with its owning module. Provider protocols, payload parsing, and feature-specific sequencing belong to the module that owns them. Shared code uses narrow, normalized contracts. Explain any substantive change outside the owning module. See rules/module-boundaries.mdc.

6. Database Changes

Follow "Schema change workflow" in doc/DATABASE.md: edit the schema, run pnpm db:generate, then typecheck.

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.
  • Attach deliverables. When you work a Paperclip issue and produce a file for the user to inspect, attach it as the paperclip skill and doc/AGENT-ARTIFACTS.md describe. A local filesystem path is not enough.

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 "Typecheck memory" in doc/test-infrastructure.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

Every route under server/src/routes/ that reads or writes company data checks company access and actor permissions, logs mutations to the activity log, and returns consistent HTTP errors. See rules/api-route-expectations.mdc.

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
  • Follow DESIGN.md for every UI design decision, including the token-only rule and form footers.

10. Fixing a Bug

When you are asked to fix a bug, attempt to use test-driven development and prove the fix red-green:

  1. Reproduce the error yourself.
  2. Write a test that fails because of the bug.
  3. Write the fix.
  4. Run the test and confirm that it passes.
  5. Verify that the fix worked: repeat the reproduction from step 1 and confirm that the error is gone.

11. Pull Requests

Fill in every section of .github/PULL_REQUEST_TEMPLATE.md, however you create the pull request. Do not write an ad-hoc body. See "PR Requirements" in CONTRIBUTING.md for the details and thinking-path examples.

12. 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. doc/DEVELOPING.md holds setup, commands, and everyday workflow only, and doc/DATABASE.md holds database setup and the rules for every schema change. Put a note about how a subsystem behaves in that subsystem's doc (see "More documentation" in doc/DEVELOPING.md), or leave it in the PR description when the code and tests already say it.
  5. PR description follows the PR template with all sections filled in (including Model Used)