AGENTS.md

1# AGENTS.md
2 
3Guidance for human and AI contributors working in this repository.
4 
5## 1. Purpose
6 
7Paperclip is a control plane for AI-agent companies.
8The current implementation target is V1 and is defined in `doc/SPEC-implementation.md`.
9 
10## 2. Read This First
11 
12Before making changes, read in this order:
13 
141. `doc/GOAL.md`
152. `doc/PRODUCT.md`
163. `doc/SPEC-implementation.md`
174. `doc/DEVELOPING.md`
185. `doc/DATABASE.md`
19 
20`doc/SPEC.md` is long-horizon product context.
21`doc/SPEC-implementation.md` is the concrete V1 build contract.
22 
23## 3. Repo Map
24 
25- `server/`: Express REST API and orchestration services
26- `ui/`: React + Vite board UI
27- `packages/db/`: Drizzle schema, migrations, DB clients
28- `packages/shared/`: shared types, constants, validators, API path constants
29- `packages/adapters/`: agent adapter implementations (Claude, Codex, Cursor, etc.)
30- `packages/adapter-utils/`: shared adapter utilities
31- `packages/plugins/`: plugin system packages
32- `doc/`: operational and product docs
33 
34## 4. Dev Setup (Auto DB)
35 
36Use embedded PGlite in dev by leaving `DATABASE_URL` unset.
37 
38```sh
39pnpm install
40pnpm dev
41```
42 
43This starts:
44 
45- API: `http://localhost:3100`
46- UI: `http://localhost:3100` (served by API server in dev middleware mode)
47 
48Quick checks:
49 
50```sh
51curl http://localhost:3100/api/health
52curl http://localhost:3100/api/companies
53```
54 
55Reset local dev DB:
56 
57```sh
58rm -rf data/pglite
59pnpm dev
60```
61 
62## 5. Core Engineering Rules
63 
641. Keep changes company-scoped.
65Every domain entity should be scoped to a company and company boundaries must be enforced in routes/services.
66 
672. Keep contracts synchronized.
68If you change schema/API behavior, update all impacted layers:
69- `packages/db` schema and exports
70- `packages/shared` types/constants/validators
71- `server` routes/services
72- `ui` API clients and pages
73 
743. Preserve control-plane invariants.
75- Single-assignee task model
76- Atomic issue checkout semantics
77- Approval gates for governed actions
78- Budget hard-stop auto-pause behavior
79- Activity logging for mutating actions
80 
814. Do not replace strategic docs wholesale unless asked.
82Prefer additive updates. Keep `doc/SPEC.md` and `doc/SPEC-implementation.md` aligned.
83 
845. Keep repo plan docs dated and centralized.
85When 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.
86 
876. Attach inspectable generated artifacts.
88When 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.
89 
90## 6. Database Change Workflow
91 
92When changing data model:
93 
941. Edit `packages/db/src/schema/*.ts`
952. Ensure new tables are exported from `packages/db/src/schema/index.ts`
963. Generate migration:
97 
98```sh
99pnpm db:generate
100```
101 
1024. Validate compile:
103 
104```sh
105pnpm -r typecheck
106```
107 
108Notes:
109- `packages/db/drizzle.config.ts` reads compiled schema from `dist/schema/*.js`
110- `pnpm db:generate` compiles `packages/db` first
111 
112## 7. Verification Before Hand-off
113 
114Default local/agent test path:
115 
116```sh
117pnpm test
118```
119 
120This is the cheap default and only runs the Vitest suite. Browser suites stay opt-in:
121 
122```sh
123pnpm test:e2e
124pnpm test:release-smoke
125```
126 
127Run the browser suites only when your change touches them or when you are explicitly verifying CI/release flows.
128 
129For normal issue work, run the smallest relevant verification first. Do not default to repo-wide typecheck/build/test on every heartbeat when a narrower check is enough to prove the change.
130 
131Run this full check before claiming repo work done in a PR-ready hand-off, or when the change scope is broad enough that targeted checks are not sufficient:
132 
133```sh
134pnpm -r typecheck
135pnpm test:run
136pnpm build
137```
138 
139If anything cannot be run, explicitly report what was not run and why.
140 
141## 8. API and Auth Expectations
142 
143- Base path: `/api`
144- Board access is treated as full-control operator context
145- Agent access uses bearer API keys (`agent_api_keys`), hashed at rest
146- Agent keys must not access other companies
147 
148When adding endpoints:
149 
150- apply company access checks
151- enforce actor permissions (board vs agent)
152- write activity log entries for mutations
153- return consistent HTTP errors (`400/401/403/404/409/422/500`)
154 
155## 9. UI Expectations
156 
157- Keep routes and nav aligned with available API surface
158- Use company selection context for company-scoped pages
159- Surface failures clearly; do not silently ignore API errors
160 
161## 10. Pull Request Requirements
162 
163When 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`](.github/PULL_REQUEST_TEMPLATE.md). Do not craft ad-hoc PR bodies — use the template as the structure for your PR description. Required sections:
164 
165- **Thinking Path** — trace reasoning from project context to this change (see `CONTRIBUTING.md` for examples)
166- **What Changed** — bullet list of concrete changes
167- **Verification** — how a reviewer can confirm it works
168- **Risks** — what could go wrong
169- **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.
170- **Checklist** — all items checked
171 
172## 11. Definition of Done
173 
174A change is done when all are true:
175 
1761. Behavior matches `doc/SPEC-implementation.md`
1772. Typecheck, tests, and build pass
1783. Contracts are synced across db/shared/server/ui
1794. Docs updated when behavior or commands change
1805. PR description follows the [PR template](.github/PULL_REQUEST_TEMPLATE.md) with all sections filled in (including Model Used)
181 
182## 11. Fork-Specific: HenkDz/paperclip
183 
184This is a fork of `paperclipai/paperclip` with QoL patches and a **built-in** Hermes adapter story on branch `feat/externalize-hermes-adapter` ([tree](https://github.com/HenkDz/paperclip/tree/feat/externalize-hermes-adapter)).
185 
186### Branch Strategy
187 
188- `feat/externalize-hermes-adapter` now ships `hermes_local` and `hermes_gateway` as built-in core adapters.
189- Older fork branches may still document plugin-only Hermes; treat this file as authoritative for the current branch.
190 
191### Hermes (built-in)
192 
193- `hermes_local` is available without Adapter manager installation and runs the local Hermes CLI.
194- `hermes_gateway` is available without Adapter manager installation and calls an already-running Hermes API server.
195- Operators may still install external Hermes packages through Adapter manager to override/shadow the built-ins.
196- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` remains useful for local development of override packages.
197 
198### Local Dev
199 
200- Fork runs on port 3101+ (auto-detects if 3100 is taken by upstream instance)
201- `npx vite build` hangs on NTFS — use `node node_modules/vite/bin/vite.js build` instead
202- Server startup from NTFS takes 30-60s — don't assume failure immediately
203- Kill ALL paperclip processes before starting: `pkill -f "paperclip"; pkill -f "tsx.*index.ts"`
204- Vite cache survives `rm -rf dist` — delete both: `rm -rf ui/dist ui/node_modules/.vite`
205 
206### Fork QoL Patches (not in upstream)
207 
208These are local modifications in the fork's UI. If re-copying source, these must be re-applied:
209 
2101. **stderr_group** — amber accordion for MCP init noise in `RunTranscriptView.tsx`
2112. **tool_group** — accordion for consecutive non-terminal tools (write, read, search, browser)
2123. **Dashboard excerpt** — `LatestRunCard` strips markdown, shows first 3 lines/280 chars
213 
214### Plugin System
215 
216PR #2218 (`feat/external-adapter-phase1`) adds external adapter support. See root `AGENTS.md` for full details.
217 
218- Adapters can be loaded as external plugins via `~/.paperclip/adapter-plugins.json`
219- The plugin-loader should have ZERO hardcoded adapter imports — pure dynamic loading
220- `createServerAdapter()` must include ALL optional fields (especially `detectModel`)
221- Built-in UI adapters can shadow external plugin parsers; external override pause/resume should restore the built-in parser.
222- Reference external adapters: Droid (npm); Hermes can also be tested as an override package.
223 
224## Design system
225 
226`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.
227