Skip to content

AGENTS.md

Latest commit

 

History

History
216 lines (150 loc) · 7.63 KB

AGENTS.md

File metadata and controls

216 lines (150 loc) · 7.63 KB

AGENTS.md

Guidance for human and AI contributors working in this repository.

1. Purpose

Paperclip is a control plane for AI-agent companies. The current implementation target is V1 and is defined in doc/SPEC-implementation.md.

2. Read This First

Before making changes, read in this order:

  1. doc/GOAL.md
  2. doc/PRODUCT.md
  3. doc/SPEC-implementation.md
  4. doc/DEVELOPING.md
  5. doc/DATABASE.md

doc/SPEC.md is long-horizon product context. doc/SPEC-implementation.md is the concrete V1 build contract.

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
  • doc/: operational and product docs

4. Dev Setup (Auto DB)

Use embedded PGlite in dev by leaving DATABASE_URL unset.

pnpm install
pnpm dev

This starts:

  • API: http://localhost:3100
  • UI: http://localhost:3100 (served by API server in dev middleware mode)

Quick checks:

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

Reset local dev DB:

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.

  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
  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. Keep doc/SPEC.md and doc/SPEC-implementation.md aligned.

  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.

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

Default local/agent test path:

pnpm test

This is the cheap default and only runs the Vitest suite. Browser suites stay opt-in:

pnpm test:e2e
pnpm test:release-smoke

Run the browser suites only when your change touches them or when you are explicitly verifying CI/release flows.

Run this full check before claiming done:

pnpm -r typecheck
pnpm test:run
pnpm build

If anything cannot be run, explicitly report what was not run and why.

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

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 doc/SPEC-implementation.md
  2. Typecheck, tests, and build pass
  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)

11. Fork-Specific: HenkDz/paperclip

This is a fork of paperclipai/paperclip with QoL patches and an external-only Hermes adapter story on branch feat/externalize-hermes-adapter (tree).

Branch Strategy

  • feat/externalize-hermes-adapter → core has no hermes-paperclip-adapter dependency and no built-in hermes_local registration. Install Hermes via the Adapter Plugin manager (@henkey/hermes-paperclip-adapter or a file: path).
  • Older fork branches may still document built-in Hermes; treat this file as authoritative for the externalize branch.

Hermes (plugin only)

  • Register through Board → Adapter manager (same as Droid). Type remains hermes_local once the package is loaded.
  • UI uses generic config-schema + ui-parser.js from the package — no Hermes imports in server/ or ui/ source.
  • Optional: file: entry in ~/.paperclip/adapter-plugins.json for local dev of the adapter repo.

Local Dev

  • Fork runs on port 3101+ (auto-detects if 3100 is taken by upstream instance)
  • npx vite build hangs on NTFS — use node node_modules/vite/bin/vite.js build instead
  • Server startup from NTFS takes 30-60s — don't assume failure immediately
  • Kill ALL paperclip processes before starting: pkill -f "paperclip"; pkill -f "tsx.*index.ts"
  • Vite cache survives rm -rf dist — delete both: rm -rf ui/dist ui/node_modules/.vite

Fork QoL Patches (not in upstream)

These are local modifications in the fork's UI. If re-copying source, these must be re-applied:

  1. stderr_group — amber accordion for MCP init noise in RunTranscriptView.tsx
  2. tool_group — accordion for consecutive non-terminal tools (write, read, search, browser)
  3. Dashboard excerpt — LatestRunCard strips markdown, shows first 3 lines/280 chars

Plugin System

PR #2218 (feat/external-adapter-phase1) adds external adapter support. See root AGENTS.md for full details.

  • Adapters can be loaded as external plugins via ~/.paperclip/adapter-plugins.json
  • The plugin-loader should have ZERO hardcoded adapter imports — pure dynamic loading
  • createServerAdapter() must include ALL optional fields (especially detectModel)
  • Built-in UI adapters can shadow external plugin parsers — remove built-in when fully externalizing
  • Reference external adapters: Hermes (@henkey/hermes-paperclip-adapter or file:) and Droid (npm)