DottaandPaperclip
a61cf38106
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The feature map describes product capabilities and user journeys. > - Small fixes and test changes have added long notes to that map. > - These notes make substantial features harder to find. > - This pull request removes those additions from the last week's changes and sets a clear rule for future additions. > - The benefit is a smaller map with stable capability IDs and accurate entry points. ## Linked Issues or Issue Description **Issue type** Unclear or confusing documentation. **Where is the issue?** `maps/feature-map/`, the map maintenance instructions, and repository rules. **What's wrong?** Between October 27 and November 3, 2026, 115 commits changed the feature map. Many additions describe bug fixes, performance details, small UI changes, or new tests. They do not introduce substantial product features. The old synchronization instructions also encouraged a map edit for every behavior change. **Suggested fix** Add a rule that requires a substantial new feature before expanding the map. Remove minor-update notes. Keep genuine feature additions and minimal corrections to existing instructions. The review covers master through `b22ef22d56`; it does not revert application code. Conflict resolution preserves later map changes from master outside that audit snapshot. Searched open GitHub PRs and issues for related feature-map work. No duplicate cleanup was found. Substantial feature additions retained here include Coordinator (#17983), the agent YAML editor (#18036), document image galleries (#18157), remote workspace storage (#18403), native Kimi (#18391), proactive chat messages (#18374), and the Sentry receiver added in #18714. ## What Changed - Add `rules/feature-map-scope.mdc` and register its `maps/**` scope with Greptile. - Align `AGENTS.md` and the shared map contract with that rule. Routine fixes and test changes no longer require incidental map edits. - Remove 755 net lines from 23 feature recipes. Preserve all 35 areas and 192 capability IDs. - Keep substantial features and the corrections needed for current navigation, provider availability, and access boundaries. Examples from the reviewed changes: | Removed or shortened addition | Why it does not need a feature-map expansion | | --- | --- | | Rounded composer image thumbnails (#18689) | Small UI change within existing task creation. | | Connection profile reads and review-count queries (#18687, #18688) | Performance details within existing app permissions. | | Warm-session, Retry, export-capacity, and tool-wait cases | Regression details for existing execution and recovery. | | New task-search, project-context, document-persistence, and routine test journeys | Test additions for existing capabilities. The tests remain in place. | | New task button placement (#18703) | Another entry to an existing task form. | | Local browser verification notes | Run evidence belongs in the PR or test report. | ## Verification - `node scripts/check-maps.mjs` passes: 35 areas, 192 capability IDs, valid references and contract fields. - `node scripts/storybook-catalog.mjs` passes: 328 files and 3,068 stories. Generated indexes remain ignored. - Compared capability keys and navigation metadata in every edited recipe with the original source. All are unchanged. - Checked rule frontmatter, Greptile registration, representative scope matches, and `git diff --check`. - `pnpm -r typecheck` and `pnpm build` pass on `9a60eef8eb8da9bc7c3a02203c79bec12e8c8b6b`. The final `a0801e8a939494ecde3739097a80258917428e94` commit only corrects two lines in the plugin-panel recipe; map and catalog checks pass again. - Greptile reviewed the final `a0801e8a939494ecde3739097a80258917428e94` head at 5/5 with no findings. The earlier review found one inaccurate phrase about unavailable plugin panels. The hook confirms that readiness gates automatic opening, while declared panels remain selectable. The final documentation commit corrects that phrase and the thread is resolved. Paperclip's refreshed review is advisory and remains queued. - The earlier CI run failed two assertions: [server 4/12](https://github.com/paperclipai/paperclip/actions/runs/41634761842/job/125914173960) counted three Anthropic identity calls instead of two in `connection-management.integration.test.ts`; [chat 1/3](https://github.com/paperclipai/paperclip/actions/runs/41634761842/job/125914174257) observed zero publications instead of one in the same-principal endpoint-settlement case. Both exact tests pass locally on the rebased head. This PR changes neither their source nor their expectations. These failed results remain historical evidence. - Final-head CI passed server 4/12 and all other suites except the first [chat 1/3 attempt](https://github.com/paperclipai/paperclip/actions/runs/41637834618/job/125925926131), which repeated the same zero-publication assertion. The browser gate passed. The single failed-job retry was accepted for this unchanged head in [workflow attempt 2](https://github.com/paperclipai/paperclip/actions/runs/41637834618/attempts/2). [Chat 1/3 passed on that retry](https://github.com/paperclipai/paperclip/actions/runs/41637834618/job/125933199635), and the aggregate verification gate passed. Both required gates, `ci / verify` and `ci / e2e`, are green on `a0801e8a939494ecde3739097a80258917428e94`. The one retry allowance is consumed. - The first full local `pnpm test:run` attempt was interrupted before completion so master could be rebased without changing source under running tests. It is not a passing test result. Full current-head CI remains required. - No application code, tests, schemas, or lockfiles changed. ## Risks - Low runtime risk. This change only edits documentation and review guidance. - Detailed regression instructions become less visible in the feature map. Their tests and technical documentation remain available. - Some additions mix a new feature with a small fix. Those blocks retain the feature and shorten the incidental detail. ## Model Used - OpenAI Codex, GPT-6 family, with reasoning, Git history inspection, repository tools, and code execution. The session does not expose a more specific model deployment ID or context-window size. ## 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 — map, catalog, capability-ID, and rule-scope checks; full Vitest limits are stated above - [x] I have added or updated tests where applicable — no new runtime tests apply to this documentation change - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <[email protected]>
11 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Agent conversations and project handoff
A person can hold a persistent conversation with an agent, return to its history, and hand useful work into a project or task. The gated conference-room chat is a separate conversation surface.
Feature ID: agent-chat.
Implementation: agent chat, chat landing, conference room.
Agent access: companion.
Sub-features
discovery:agent-chat/discovery— find an agent and reopen an accessible recent conversation.history:agent-chat/history— send messages, inspect replies/files, and return to the same conversation.handoff:agent-chat/handoff— create or identify a project/task from chat and follow the resulting work.conference-room:agent-chat/conference-room— use the separately gated board chat without assuming parity with agent chat.
How to get to it (user POV)
agent-conversation
Task and routine results can arrive proactively in the agent's standing chat. Each message has a source-task link; the agent row and Chat navigation indicate unread messages, including first delivery before any human chat. Foreground messages at the bottom of the chat are marked read with a comment cutoff. The existing ordering and per-human/company isolation remain in effect.
Open /chats, choose an agent, or use /chats/:agentRef and its conversation sidebar.
With Coordinator enabled, the composer exposes the shared model/thinking-level picker for supported agents. The agent stays fixed in this control; switching agents remains in the chat header. Choices save as conversation overrides on send, preserving the agent's configuration. A first message creates the conversation before saving settings and submitting through the ordered comments endpoint.
Coordinator answer receipts from this conversation jump to the answer bubble without leaving chat. Answer updates from an execution task link to that source task and its decision context. Compact document links read “Open [document title] in the sidebar”.
project-handoff
Ask for project work in Agent Chat and follow its created project/task links. New tasks and accepted task suggestions default to the agent in that conversation. An explicitly requested agent or person takes precedence; no best-fit agent routing is inferred. Ordinary task creation outside chat keeps its existing assignment behavior.
conference-room
Open /board-chat only when its conference-room gate is enabled.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Enable the applicable chat feature, use a configured test agent, and distinguish model replies from a mocked conversation fixture.
agent-conversation
Automated: chat landing checks recent-chat routing; conversation service covers persisted conversation behavior.
Automated: proactive delivery exercises native/HTTP delivery, concurrency, retries, authority, privacy, active turns, resets and unread cutoffs. Read visibility checks foreground/bottom gating and unseen arrivals. The routine digest journey uses real app APIs and a deterministic process agent to verify first-chat discovery, unread state across reloads, source navigation and follow-up context. It does not qualify live PR retrieval or a model's editorial choices.
Automated: composer picker covers fixed-agent model/effort selection on desktop and mobile; composer covers Coordinator gating and settings submission without reassignment. Task detail verifies canonical first/existing-chat IDs, settings-before-comment ordering, and no comment submission when settings fail to save. These tests mock the API and do not prove provider execution with the chosen model.
Automated: thread and composer keeps an in-flight attachment through first-chat creation on desktop and mobile, while initial history for an existing conversation stays deferred. The first-upload browser journey checks the visible file chip, server attachment, no premature agent run, and attachment count after send and reload. That journey uses a simulated agent.
Manual: In a conversation with no messages, attach a file before the first send. Confirm the same file stays in the composer after the chat is created. Send it once, reload, and confirm the file and message remain.
Manual: Start a conversation, send a recognizable request, and inspect its reply.
Navigate away and reopen the same history. Use /new for a fresh session within
the same standing conversation. Test an unavailable historical agent and an
inaccessible saved conversation; verify no cross-user or cross-company history appears.
project-handoff
Automated: chat project tools checks tool contracts; live model choice and UI handoff require a manual run.
Automated: Coordinator handoffs checks that a suggested task remains a proposal until acceptance, that its task, initial plan and source-chat audience are saved atomically, and that retries do not create another task. A conversation is a privacy/provenance source rather than a structural task parent. The same tests cover compact canonical decision receipts, exact uploaded-artifact bindings, current task access, reset-session boundaries, and pagination of older handoffs. Explicit live evals: chat feature journeys send natural requests to save a backlog task or delegate an announcement. They check project/assignee, execution or non-execution, saved output, return to chat, and click the actual same-instance task link after reload. Registration alone does not establish a pass. Production chat guidance uses company-prefixed relative task links unless the platform supplied a verified absolute origin.
Manual: Ask the configured agent to create bounded project work, inspect the proposed/created target, and open the resulting task. Verify the request context and intended project survived and the task produces a useful output.
Manual: With the personal Coordinator workspace enabled, discuss a vague request until the agent suggests a task. Confirm that no execution task exists before acceptance. Accept it, stay in chat, and open the created card on demand. An explicit request to create a task may create it directly under normal authority. Approve a work product or answer a question in its task or Needs You, then return to the originating chat. Its compact update should link to the exact recorded decision and reviewed artifact, without needing another coordinator turn. Approval of artifact quality alone must not publish it or complete the task.
Coordinator task clarification: create a task with only a description. When material context is missing, native task guidance asks one focused canonical question inside that task. Its actionable form is also projected into Needs You and the originating standing chat; direct user-created tasks appear in the assigned agent’s standing chat. Answer on either surface and verify the pending card/count clear and a compact recorded answer replaces it in chat. This projection is event-refreshed and does not wake another agent merely to repeat the question. Current direct-task questions survive a chat reset; their answered receipts start at the current chat boundary. The task brief remains editable context, not another stored question. Model choice and actual resumed execution still require live verification.
conference-room
Automated: board chat gate proves route gating, not a live conversation.
Preconditions for this entry point: local_trusted mode and an installed,
authenticated claude CLI, in addition to the Conference Room flag. These are
separate from Agent Chat's configured-agent prerequisites.
Manual: Check disabled access first, enable in the disposable instance, then send and reload a conversation. Inspect the actual responding agent and persisted history; report this result separately from Agent Chat.
Gotchas
- Idle chat is not failed execution.
- See steering for in-flight messages and questions for interactions.
- An API tool test does not prove that every harness will choose the same handoff tool.
Storybook verification
conference-room
Capability ID: agent-chat/conference-room.
Scope: ui Storybook: Conference-room flag disabled, empty/history/reply, busy and explicit failure states. Production: Exercise separate BoardChat route gate, local-trusted deployment and authenticated Claude CLI; send/reload real conversation with responding agent attribution. Sources: Source: BoardChat.tsx, board-chat.ts. Tests: BoardChat.test.tsx, board-chat-route-feature-flag.test.ts
Explicit output quality review (Coordinator functional slice)
Accepted suggestions and native explicit task creation may carry requiredQualityReview into the task's existing execution policy. The opt-in requirement names output slots and is separate from the existing reviewer eligibility policy. Each slot requires a canonical human verdict bound to an exact current output document revision or attachment identity. Plans, questions, file presence, model completion claims, rejected/deferred verdicts and stale versions do not satisfy it. Only a human may change an existing requirement. Quality approval does not publish or automatically complete the task. Tasks without this optional requirement retain existing completion behavior.
Owning service: server/src/services/required-quality-review.ts; enforcement: interaction creation, issue update, native completion feedback/finalization. Focused proof: server/src/__tests__/required-quality-review.test.ts plus native arbiter and chat completion delivery tests. Completion updates include bounded canonical output-decision identities for linking existing review, never worker-authored review prose. These tests do not establish unattended live provider reliability.
Attachment approval is for the exact immutable file identity. Removal or a mismatched hash invalidates that target; registering a replacement beside the approved file does not redefine its output slot. A replacement requires a fresh bound review. Document targets additionally track the current revision.