From 1e44e50360d36fb05f0336dbf01bff39c7b59d26 Mon Sep 17 00:00:00 2001 From: Santhi Prakash <38608178+santhiprakash@users.noreply.github.com> Date: Wed, 5 Aug 2026 09:10:27 +0530 Subject: [PATCH] docs: remove leaked fork-specific section from AGENTS.md (#9935) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `AGENTS.md` is the contributor guide read by every human and AI agent before making changes > - Section "## 11. Fork-Specific: HenkDz/paperclip" describes a downstream fork's own dev setup (custom ports, NTFS quirks, fork-only QoL patches) but was accidentally left in the upstream `paperclipai/paperclip` copy of AGENTS.md > - This causes two concrete problems: (1) it duplicates the "## 11." heading number with the preceding "Definition of Done" section, and (2) it tells contributors/agents working on the real upstream repo to follow fork-only instructions (e.g. "Fork runs on port 3101+ (auto-detects if 3100 is taken by upstream instance)") that don't apply here and could cause confusion during setup > - This PR removes the leaked fork-specific section entirely, which also resolves the duplicate numbering as a side effect > - The benefit is a cleaner, correct AGENTS.md with no duplicate section numbers and no instructions that reference a different repository ## Linked Issues or Issue Description Refs #4188 — that issue's "Proposed behavior" section explicitly calls out this same duplicate-`§11` numbering bug in AGENTS.md ("Definition of Done and Fork-Specific HenkDz section both numbered §11") as one incidental item inside a much larger proposal (issue templates, triage labels, PR-link enforcement workflows). That issue is still open. Related PRs (checked before opening this one): - #4189 — closed, not merged. Would have addressed the broader issue-templates work. - #4260 — closed, not merged. Would have expanded CONTRIBUTING.md and issue templates. - #7522 — merged (2026-06-05). Added the search-first / linked-issue / gates guidance to CONTRIBUTING.md, but did not touch AGENTS.md and did not remove the leaked section. None of these removed the leaked "## 11. Fork-Specific: HenkDz/paperclip" section — it is still present verbatim on `master` as of this PR. This PR intentionally scopes down to just the AGENTS.md fix so it can land as a small, independent, easy-to-review change rather than waiting on the larger issue-template proposal. ## What Changed - Removed the entire "## 11. Fork-Specific: HenkDz/paperclip" section from `AGENTS.md` (Branch Strategy, Hermes (built-in), Local Dev, Fork QoL Patches, Plugin System subsections) — this content describes a personal fork's dev environment, not the upstream repo, and does not belong in the file every contributor and agent reads first. - No other files touched. ## Verification - `grep -n "^## " AGENTS.md` now shows a single "## 11. Definition of Done" with no duplicate section number. - `grep -rn "HenkDz\|Fork-Specific" --include="*.md" .` (outside `releases/*.md` changelog credits, which are unrelated and untouched) returns nothing — confirms no other file references the removed section. - Checked `ROADMAP.md` — no planned work overlaps this change (the only AGENTS.md-related roadmap item, "Easy AGENTS.md configurations", is marked done and is a general feature, unrelated to this cleanup). - Searched open/closed PRs touching AGENTS.md and open issues mentioning "HenkDz"/"Fork-Specific" — no duplicate or in-flight PR does this specific removal (see Linked Issues section above). - No code, schema, or behavior changes — this is a docs-only removal, so no typecheck/test/build impact. ## Risks Low risk. Docs-only change, single file, pure deletion of inapplicable content. No behavior, schema, or API impact. ## Model Used Claude Sonnet 5 (claude-sonnet-5), via Claude Code CLI. Standard reasoning, no extended thinking mode. Used for repo exploration (fork, clone, issue/PR search, verifying the section was still present and unresolved on current `master`) and to author this fix and PR description. All commits authored by the human contributor (Santhi Prakash); no AI co-authorship attribution on commits. ## 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 (`docs/remove-leaked-fork-section-agents-md`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass — N/A, docs-only change (see Verification) - [ ] I have added or updated tests where applicable — N/A, docs-only - [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 — confirm after opening the PR - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups — confirm after opening the PR - [x] I will address all Greptile and reviewer comments before requesting merge --- AGENTS.md | 42 ------------------------------------------ 1 file changed, 42 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a5fc286535..3f8581b808 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -183,48 +183,6 @@ A change is done when all are true: 4. Docs updated when behavior or commands change 5. PR description follows the [PR template](.github/PULL_REQUEST_TEMPLATE.md) with all sections filled in (including Model Used) -## 11. Fork-Specific: HenkDz/paperclip - -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)). - -### Branch Strategy - -- `feat/externalize-hermes-adapter` now ships `hermes_local` and `hermes_gateway` as built-in core adapters. -- Older fork branches may still document plugin-only Hermes; treat this file as authoritative for the current branch. - -### Hermes (built-in) - -- `hermes_local` is available without Adapter manager installation and runs the local Hermes CLI. -- `hermes_gateway` is available without Adapter manager installation and calls an already-running Hermes API server. -- Operators may still install external Hermes packages through Adapter manager to override/shadow the built-ins. -- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` remains useful for local development of override packages. - -### 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; external override pause/resume should restore the built-in parser. -- Reference external adapters: Droid (npm); Hermes can also be tested as an override package. - ## Design system `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.