## 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/DEVELOPING.md` for setup, commands, testing, and worktrees > - That file grew to 5,495 lines. Most of it was notes on how one subsystem behaves, added one pull request at a time > - Readers could not find the commands. Agents also read behavior notes as rules > - This pull request cuts `doc/DEVELOPING.md` to a 660-line setup and workflow guide. It moves the subsystem notes to focused docs > - The benefit is a guide that a person or an agent can read in full, and a clear place for each kind of note ## Linked Issues or Issue Description **Issue type** Outdated or confusing documentation. **Where is the issue?** `doc/DEVELOPING.md` **What's wrong?** The file was 5,495 lines. It opened with 112 lines about case handoffs before it reached Prerequisites. Unrelated sections sat below the "OpenClaw Docker UI One-Command Script" heading. Statements about current behavior read like policy. **Suggested fix** Keep setup, commands, and workflow in `doc/DEVELOPING.md`. Move each subsystem note to a doc for that subsystem. Add an index. ## What Changed - `doc/DEVELOPING.md` is now 660 lines: prerequisites, start dev, health checks, local run, test drive, Docker, instance layout, database, storage, secrets, worktrees, test commands, Storybook, CLI, and an index of the other docs. - 15 new docs hold the moved text without wording changes: `ci-workflows`, `test-infrastructure`, `worktrees`, `hot-restart-deploys`, `heartbeat-internals`, `runner-internals`, `workspace-repositories`, `workspace-storage`, `skills-and-teams-catalog`, `ui-internals`, `case-handoffs`, `chat-connector-development`, `instance-configuration`, `integration-api-notes`, `database-backups`. - "Publish a branch Storybook" moved to `doc/STORYBOOK-DEPLOYMENT.md`. The privacy rollout notes moved to `doc/ISSUE-PRIVACY.md`. - Deleted about 280 lines: the story-by-story Storybook notes, "Agent Artifact Uploads" (a copy of `doc/AGENT-ARTIFACTS.md`), two pointer-only sections, "Workspace feature checks (2026-10-09)", and "Chat and task navigation caching". The test-drive build-lock paragraph is now four lines. - Repointed every inbound link and every script or workflow comment that named a moved section. - `AGENTS.md` now says where a behavior note goes, so the guide does not grow again. ## Verification - A script split the file by line range. It asserts that each of the 5,495 source lines is kept, moved, or dropped exactly one time. - A link check on every changed Markdown file 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. - `node --check` passes on the three scripts with changed comments. - `pnpm verify` was not run. This worktree has no installed dependencies, and the change has no runtime code. ## Risks - Low risk. The change is documentation and comments only. - A link to a moved section from outside this repository will land on the top of `doc/DEVELOPING.md`. - The new docs are not in the audited prose list in `.github/scripts/ci-inputs.mjs`. An edit to one of them runs full CI. An edit to `doc/DEVELOPING.md` does not. This PR does not change that list. ## 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>
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 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 docsdoc/plans/: dated repo plan docs, namedYYYY-MM-DD-slug.md. A plan for a Paperclip issue goes in the issue'splandocument 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
-
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. -
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
-
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 --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.
- Attach deliverables. When you work a Paperclip issue and produce a file for
the user to inspect, attach it as the
paperclipskill anddoc/AGENT-ARTIFACTS.mddescribe. 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.mdfor 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:
- Reproduce the error yourself.
- Write a test that fails because of the bug.
- Write the fix.
- Run the test and confirm that it passes.
- 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:
- 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.
doc/DEVELOPING.mdholds setup, commands, and everyday workflow only. Put a note about how a subsystem behaves in that subsystem's doc (see "More documentation" indoc/DEVELOPING.md), or leave it in the PR description when the code and tests already say it. - PR description follows the PR template with all sections filled in (including Model Used)