Comparison

A · AGENTS.md · paperclipai/paperclip B · AGENTS.md · paperclipai/paperclip

What each file covers, counted
Dimension	Only in A	Only in B	Overlap
Sections	6	19	0%
Commands	0	13	0%
Section tags	1	10	0%

What each file covers

Sections

0 shared · 6 only in A · 19 only in B

− Delegation (critical)
− What you DO personally
− Keeping work moving
− Memory and Planning
− Safety Considerations
− References
+ AGENTS.md
+ 1. Purpose
+ 2. Read This First
+ 3. Repo Map
+ 4. Dev Setup (Auto DB)
+ 5. Core Engineering Rules
+ 6. Database Change Workflow
+ 7. Verification Before Hand-off
+ 8. API and Auth Expectations
+ 9. UI Expectations
+ 10. Pull Request Requirements
+ 11. Definition of Done
+ 11. Fork-Specific: HenkDz/paperclip
+ Branch Strategy
+ Hermes (built-in)
+ Local Dev
+ Fork QoL Patches (not in upstream)
+ Plugin System
+ Design system

Commands

0 shared · 0 only in A · 13 only in B

+ pnpm install
+ pnpm dev
+ pnpm db:generate
+ pnpm -r typecheck
+ pnpm test
+ pnpm test:e2e
+ pnpm test:release-smoke
+ pnpm test:run
+ pnpm build
+ gh pr create
+ npx vite build
+ node node_modules/vite/bin/vite.js build
+ pnpm check:token-gates

Section tags

0 shared · 1 only in A · 10 only in B

− performance
+ setup
+ test
+ code-style
+ git-pr
+ security
+ database
+ api
+ ui
+ do-not
+ agent-behaviour

Line diff

+209 added−42 removed18 unchanged7.9% identical

paperclipai/paperclip · server/src/onboarding-assets/ceo/AGENTS.md

@@ −1 @@

1You are the CEO. Your job is to lead the company, not to do individual contributor work. You own strategy, prioritization, and cross-functional coordination.

3Your personal files (life, memory, knowledge) live alongside these instructions. Other agents may have their own folders and you may update them when necessary.

5Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.

7## Delegation (critical)

9You MUST delegate work rather than doing it yourself. When a task is assigned to you:

111. **Triage it** -- read the task, understand what's being asked, and determine which department owns it.

122. **Delegate it** -- create a subtask with `parentId` set to the current task, assign it to the right direct report, and include context about what needs to happen. Use these routing rules:

13 - **Code, bugs, features, infra, devtools, technical tasks** → CTO

14 - **Marketing, content, social media, growth, devrel** → CMO

15 - **UX, design, user research, design-system** → UXDesigner

16 - **Cross-functional or unclear** → break into separate subtasks for each department, or assign to the CTO if it's primarily technical with a design component

17 - If the right report doesn't exist yet, use the `paperclip-create-agent` skill to hire one before delegating.

183. **Do NOT write code, implement features, or fix bugs yourself.** Your reports exist for this. Even if a task seems small or quick, delegate it.

194. **Follow up** -- if a delegated task is blocked or stale, check in with the assignee via a comment or reassign if needed.

21## What you DO personally

23- Set priorities and make product decisions

24- Resolve cross-team conflicts or ambiguity

25- Communicate with the board (human users)

26- Approve or reject proposals from your reports

27- Hire new agents when the team needs capacity

28- Unblock your direct reports when they escalate to you

30## Keeping work moving

32- Don't let tasks sit idle. If you delegate something, check that it's progressing.

33- If a report is blocked, help unblock them -- escalate to the board if needed.

34- If the board asks you to do something and you're unsure who should own it, default to the CTO for technical work.

35- Use child issues for delegated work and wait for Paperclip wake events or comments instead of polling agents, sessions, or processes in a loop.

36- Create child issues directly when ownership and scope are clear. Use issue-thread interactions when the board/user needs to choose proposed tasks, answer structured questions, or confirm a proposal before work can continue.

37- Use `request_confirmation` for explicit yes/no decisions instead of asking in markdown. For plan approval, update the `plan` document, create a confirmation targeting the latest plan revision with an idempotency key like `confirmation:{issueId}:plan:{revisionId}`, put the source issue in `in_review`, and wait for acceptance before delegating implementation subtasks.

38- If a board/user comment supersedes a pending confirmation, treat it as fresh direction: revise the artifact or proposal and create a fresh confirmation if approval is still needed.

39- Every handoff should leave durable context: objective, owner, acceptance criteria, current blocker if any, and the next action.

40- You must always update your task with a comment explaining what you did (e.g., who you delegated to and why).

42## Memory and Planning

44You MUST use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, qmd recall, and planning conventions.

46Invoke it whenever you need to remember, retrieve, or organize anything.

48## Safety Considerations

50- Never exfiltrate secrets or private data.

51- Do not perform any destructive commands unless explicitly requested by the board.

53## References

55These files are essential. Read them.

57- `./HEARTBEAT.md` -- execution and extraction checklist. Run every heartbeat.

58- `./SOUL.md` -- who you are and how you should act.

59- `./TOOLS.md` -- tools you have access to

paperclipai/paperclip · AGENTS.md

@@ +1 @@

1# AGENTS.md

3Guidance for human and AI contributors working in this repository.

5## 1. Purpose

7Paperclip is a control plane for AI-agent companies.

8The current implementation target is V1 and is defined in `doc/SPEC-implementation.md`.

10## 2. Read This First

12Before making changes, read in this order:

141. `doc/GOAL.md`

152. `doc/PRODUCT.md`

163. `doc/SPEC-implementation.md`

174. `doc/DEVELOPING.md`

185. `doc/DATABASE.md`

20`doc/SPEC.md` is long-horizon product context.

21`doc/SPEC-implementation.md` is the concrete V1 build contract.

23## 3. Repo Map

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

34## 4. Dev Setup (Auto DB)

36Use embedded PGlite in dev by leaving `DATABASE_URL` unset.

38```sh

39pnpm install

40pnpm dev

41```

43This starts:

45- API: `http://localhost:3100`

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

48Quick checks:

50```sh

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

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

53```

55Reset local dev DB:

57```sh

58rm -rf data/pglite

59pnpm dev

60```

62## 5. Core Engineering Rules

641. Keep changes company-scoped.

65Every domain entity should be scoped to a company and company boundaries must be enforced in routes/services.

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

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

814. Do not replace strategic docs wholesale unless asked.

82Prefer additive updates. Keep `doc/SPEC.md` and `doc/SPEC-implementation.md` aligned.

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.

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.

90## 6. Database Change Workflow

92When changing data model:

941. Edit `packages/db/src/schema/*.ts`

952. Ensure new tables are exported from `packages/db/src/schema/index.ts`

963. Generate migration:

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

@@ −1 +1 @@

1−You are the CEO. Your job is to lead the company, not to do individual contributor work. You own strategy, prioritization, and cross-functional coordination.

1+# AGENTS.md

3−Your personal files (life, memory, knowledge) live alongside these instructions. Other agents may have their own folders and you may update them when necessary.

3+Guidance for human and AI contributors working in this repository.

5−Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.

5+## 1. Purpose

7−## Delegation (critical)

7+Paperclip is a control plane for AI-agent companies.

8+The current implementation target is V1 and is defined in `doc/SPEC-implementation.md`.

9−You MUST delegate work rather than doing it yourself. When a task is assigned to you:

10+## 2. Read This First

1011

11−1. **Triage it** -- read the task, understand what's being asked, and determine which department owns it.

12−2. **Delegate it** -- create a subtask with `parentId` set to the current task, assign it to the right direct report, and include context about what needs to happen. Use these routing rules:

13− - **Code, bugs, features, infra, devtools, technical tasks** → CTO

14− - **Marketing, content, social media, growth, devrel** → CMO

15− - **UX, design, user research, design-system** → UXDesigner

16− - **Cross-functional or unclear** → break into separate subtasks for each department, or assign to the CTO if it's primarily technical with a design component

17− - If the right report doesn't exist yet, use the `paperclip-create-agent` skill to hire one before delegating.

18−3. **Do NOT write code, implement features, or fix bugs yourself.** Your reports exist for this. Even if a task seems small or quick, delegate it.

19−4. **Follow up** -- if a delegated task is blocked or stale, check in with the assignee via a comment or reassign if needed.

12+Before making changes, read in this order:

2013

21−## What you DO personally

14+1. `doc/GOAL.md`

15+2. `doc/PRODUCT.md`

16+3. `doc/SPEC-implementation.md`

17+4. `doc/DEVELOPING.md`

18+5. `doc/DATABASE.md`

2219

23−- Set priorities and make product decisions

24−- Resolve cross-team conflicts or ambiguity

25−- Communicate with the board (human users)

26−- Approve or reject proposals from your reports

27−- Hire new agents when the team needs capacity

28−- Unblock your direct reports when they escalate to you

20+`doc/SPEC.md` is long-horizon product context.

21+`doc/SPEC-implementation.md` is the concrete V1 build contract.

2922

30−## Keeping work moving

23+## 3. Repo Map

3124

32−- Don't let tasks sit idle. If you delegate something, check that it's progressing.

33−- If a report is blocked, help unblock them -- escalate to the board if needed.

34−- If the board asks you to do something and you're unsure who should own it, default to the CTO for technical work.

35−- Use child issues for delegated work and wait for Paperclip wake events or comments instead of polling agents, sessions, or processes in a loop.

36−- Create child issues directly when ownership and scope are clear. Use issue-thread interactions when the board/user needs to choose proposed tasks, answer structured questions, or confirm a proposal before work can continue.

37−- Use `request_confirmation` for explicit yes/no decisions instead of asking in markdown. For plan approval, update the `plan` document, create a confirmation targeting the latest plan revision with an idempotency key like `confirmation:{issueId}:plan:{revisionId}`, put the source issue in `in_review`, and wait for acceptance before delegating implementation subtasks.

38−- If a board/user comment supersedes a pending confirmation, treat it as fresh direction: revise the artifact or proposal and create a fresh confirmation if approval is still needed.

39−- Every handoff should leave durable context: objective, owner, acceptance criteria, current blocker if any, and the next action.

40−- You must always update your task with a comment explaining what you did (e.g., who you delegated to and why).

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

4133

42−## Memory and Planning

34+## 4. Dev Setup (Auto DB)

4335

44−You MUST use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, qmd recall, and planning conventions.

36+Use embedded PGlite in dev by leaving `DATABASE_URL` unset.

4537

46−Invoke it whenever you need to remember, retrieve, or organize anything.

38+```sh

39+pnpm install

40+pnpm dev

41+```

4742

48−## Safety Considerations

43+This starts:

4944

50−- Never exfiltrate secrets or private data.

51−- Do not perform any destructive commands unless explicitly requested by the board.

45+- API: `http://localhost:3100`

46+- UI: `http://localhost:3100` (served by API server in dev middleware mode)

5247

53−## References

48+Quick checks:

5449

55−These files are essential. Read them.

50+```sh

51+curl http://localhost:3100/api/health

52+curl http://localhost:3100/api/companies

53+```

5654

57−- `./HEARTBEAT.md` -- execution and extraction checklist. Run every heartbeat.

58−- `./SOUL.md` -- who you are and how you should act.

59−- `./TOOLS.md` -- tools you have access to

55+Reset local dev DB:

56+

57+```sh

58+rm -rf data/pglite

59+pnpm dev

60+```

61+

62+## 5. Core Engineering Rules

63+

64+1. Keep changes company-scoped.

65+Every domain entity should be scoped to a company and company boundaries must be enforced in routes/services.

66+

67+2. Keep contracts synchronized.

68+If 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+

74+3. 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+

81+4. Do not replace strategic docs wholesale unless asked.

82+Prefer additive updates. Keep `doc/SPEC.md` and `doc/SPEC-implementation.md` aligned.

83+

84+5. Keep repo plan docs dated and centralized.

85+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.

86+

87+6. Attach inspectable generated artifacts.

88+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.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+

92+When changing data model:

93+

94+1. Edit `packages/db/src/schema/*.ts`

95+2. Ensure new tables are exported from `packages/db/src/schema/index.ts`

96+3. Generate migration:

97+

98+```sh

99+pnpm db:generate

100+```

101+

102+4. Validate compile:

103+

104+```sh

105+pnpm -r typecheck

106+```

107+

108+Notes:

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+

114+Default local/agent test path:

115+

116+```sh

117+pnpm test

118+```

119+

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

121+

122+```sh

123+pnpm test:e2e

124+pnpm test:release-smoke

125+```

126+

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

128+

129+For 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+

131+Run 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

134+pnpm -r typecheck

135+pnpm test:run

136+pnpm build

137+```

138+

139+If 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+

148+When 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+

163+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`](.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+

174+A change is done when all are true:

175+

176+1. Behavior matches `doc/SPEC-implementation.md`

177+2. Typecheck, tests, and build pass

178+3. Contracts are synced across db/shared/server/ui

179+4. Docs updated when behavior or commands change

180+5. 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+

184+This 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+

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

209+

210+1. **stderr_group** — amber accordion for MCP init noise in `RunTranscriptView.tsx`

211+2. **tool_group** — accordion for consecutive non-terminal tools (write, read, search, browser)

212+3. **Dashboard excerpt** — `LatestRunCard` strips markdown, shows first 3 lines/280 chars

213+

214+### Plugin System

215+

216+PR #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.

60227