## 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>
7.3 KiB
Persistent case handoffs
Developer notes for the Cases experiment: handoff delivery, native case tools, and where the tests live.
The Cases experiment supports prompt-driven agent workflows on one ordinary task.
The application service owns transaction/idempotency and assignment policy;
case-handoff-delivery.ts owns durable retry/lease and wake admission;
heartbeat/case-handoff-lifecycle.ts owns execution release proof and stale-run
mutation fencing. Keep network/process work outside the acceptance transaction.
heartbeat/process-settlement.ts checks local process-tree absence independently
of scratch-directory preparation. A local process handoff stays pending while
the owned PID or process group is alive, or termination evidence is missing.
HTTP adapters use their awaited nonprocess invocation contract instead of host
PID probes. Stopping a run cancels its own intents; cancelling an unbound
terminal intent additionally requires fenced, current task ownership.
case-context.ts builds the bounded authorized case snapshot shared by native
and legacy task preparation, including resumed sessions.
Native case tools are create_case, read_case, update_case, and
handoff_case. Native creation requires kickoff and delegates to the same
principal-idempotent handoff service. Both kickoff and nonblank
workflow_document_text are mandatory; missing either fails before any writes.
The text is preserved in ordinary Markdown task document workflow, title
Workflow, in the acceptance transaction. New-case handoff API requests require
the same field. The workflow plus optional document seeds share a 200,000-character
budget; workflow cannot appear in initialDocuments. Later phase handoffs omit
the text; normal revision tools manage changes. Read workflow before routing:
its reference is prioritized in case context, without injecting its full body.
Recommend both a Mermaid stateDiagram-v2 map and prose defining each transition's
trigger, evidence, next agent, human wait/resume behavior and correction/escalation
limits. State IDs match phase names and prose defines named edge outcomes.
This guidance adds no server-enforced transition semantics. There is
no passive creation branch or createOnly REST extension. Historical
generic REST upsert semantics remain compatible. initialDocuments is valid only for
new first-task kickoff; ordinary task documents and audit are committed before
delivery. Case detail/context roll up authorized task document metadata through
case-task-documents.ts; system keys and inaccessible task documents are
excluded before the document limit. Standard task document tools handle new
documents; historical case document REST/storage remains intact.
read_case keeps small responses structured. Large responses return bounded
readPage.text JSON chunks with case/task routing versions on every page. Use
section: "fields" to retrieve the entire fields object, including large keys,
strings, and arrays. Continue with the same section and snapshot, passing
offsetBytes: readPage.nextOffsetBytes until it is null; concatenate the text
before parsing JSON. A 409 means facts, accessible references, or routing changed:
restart at offset zero without the old snapshot. Each page reauthorizes current case access through
GET /api/cases/:id?agentRead=true; no generic API tool or asset grant is needed.
limitBytes is 4–8192 UTF-8 bytes. Ordinary REST reads retain their existing full
response, and ordinary update_case mutation receipts remain unchanged.
Use section: "document" and documentKey for a historical case-owned body;
add documentIssueId for a primary or currently linked task document. This
selection retains the same bounded JSON paging and does not enable generic API
tools. Each page checks current case access, task access, linkage, and document
trust. System and quarantined documents are excluded. Document edits and routing
changes invalidate the snapshot; restart from zero after a 409.
Each page reloads case metadata and the complete selected body to check access
and compute its snapshot. These limits bound the response, not total database
work; the read cost grows with source size and the number of pages.
Keep native schemas aligned with their services/routes. Transactional source
run checks must precede case writes, so Stop or an accepted handoff cannot race
an HTTP request into a late mutation. Generic API rollout settings do not remove
these dedicated tools; case, mode and resource authorization still apply.
Company deletion removes cases before task/agent dependencies. Individual agent
purge preserves handoff attribution and returns agent_case_history_retained
before destructive cleanup when history references that agent. Termination stays available.
The native constructor preserves full case context for bootstrap and resume
failure. Compatible continuations carry a versioned case projection tied to the
actual prior native input and exact agent/task/session. Stable facts fingerprints
include document revisions and accessible references, while phase/version and
incoming instructions are refreshed separately. Do not use a prepared
contextSnapshot.paperclipCase as proof that a compact provider turn received
those facts. Legacy adapters continue to receive their bounded case snapshot.
Start work through handoff_case or
POST /api/companies/:companyId/case-handoffs. Subsequent calls use the same
primary task and observed case/task revisions. GET the case's /handoffs for
history; /handoffs/:handoffId/retry retries delivery without creating new work,
and /cancel cancels pending delivery without reversing an applied assignment.
Ordinary task completion leaves the case unchanged. For an existing primary
task, to: "done" records a non-yielding terminal handoff; its awaiting_completion
intent is settled atomically by the normal issue-service completion transaction.
The case remains open during review or user waits. Stop/cancel/reassignment
invalidate the intent. Keep terminal intents outside agent-transfer mutation
fencing, outgoing yield detection and recipient dispatch.
The board case list/detail pages are read-only. URL query parameters retain
search/status/type/project filters through detail navigation; list paging and
the GET /api/companies/:companyId/cases/types read use authorized server data.
Storybook's Cases / Read-only pages stories mount those same production pages
with HTTP fixtures, including document previews, waiting handoffs and mobile.
Cases do not have a quarantine/promotion contract. Low-trust runs must save findings through their governed task/review path rather than write case data. Historical low-trust case provenance also blocks automatic execution context and handoffs; operator reads remain available for review. Skill-test runs omit workflow context to preserve their task-only scope. Cancelled or unapplied handoff intent is history, not an incoming phase instruction.
Focused verification lives in the case route, handoff service, native handoff, durable admission, and legacy process integration tests. Run the explicit-only case-handoffs Product E2E workflow for provider/browser qualification; fixture and service tests do not establish that a live model followed the workflow. See implementation and acceptance and the agent case reference.