mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-18 05:23:39 +02:00
DottaandPaperclip
7ac0354b51
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Chat channels connect shared task workflows to several platforms. > - Recent refactors moved platform behavior into named channel folders. > - Authors and reviewers need a durable rule that preserves these boundaries. > - Review settings also need version control and an explicit source of rules. > - This pull request adds scoped MDC rules and a staged migration of supported Greptile settings into Git. ## Linked Issues or Issue Description **Issue type** Missing documentation and versioned review configuration. **Where is the issue?** Root contributor instructions, chat channel architecture guidance, and Greptile configuration for this repository. **What's wrong?** The channel folder boundary is established in the refactor but has no focused rule for future changes. Greptile settings and custom context are maintained in the dashboard. **Suggested fix** Keep canonical rule bodies under `rules/`. Route coding agents through `AGENTS.md` and load matching rules through `.greptile/files.json`. Preserve supported review settings in `.greptile/config.json` and document the remaining dashboard controls. Related work: #15823 and #16080. A search for related rule PRs found no duplicate configuration change. ## What Changed - Add `rules/chat-channel-platform-boundaries.mdc`. Its scope covers `server/src/services/chat-channels/**` and the sibling `chat-channels.ts` entry point. - Define provider folder ownership, shared workflow boundaries, typed dependencies, behavior-preserving extraction, and dispatch exceptions. - Add rule-loading instructions to root `AGENTS.md` and `.greptile/rules.md`. - Add explicit, scoped context references in `.greptile/files.json`. - Record observed review triggers, the Dependabot exclusion, Base tier, High strictness, summary options, fix prompts, status checks, and disabled auto-approval in `.greptile/config.json`. - Move existing PR-description, source-file growth, and repository-specific screenshot guidance into `rules/pull-request-review.mdc`. - Document supported settings, remaining dashboard controls, and the staged cutover. The dashboard was inspected read-only; no settings or saved rules were changed. ## Verification - Parse both MDC headers with Ruby `YAML.safe_load`: passed. - Parse both Greptile JSON files and verify documented field types and observed values: passed. - Verify all four context references resolve to repository files: passed. - Compare scoped MDC globs with the corresponding Greptile scope: passed. - Check ten positive and negative scope cases with Node `path.matchesGlob`: passed. Includes the service entry point, nested provider files, and unrelated runner, connection, and UI paths. - Verify the scope covers all 101 tracked chat-channel files: passed. - `git diff --check`: passed. - Application typecheck, `pnpm test:run`, and build were not run locally. This change contains only guidance and reviewer configuration, and this worktree has no installed application dependencies. No runtime behavior or application tests changed. - Greptile reviewed commit `32647dfd001289a297b9d43c381371da8575df38`: 5/5, eight files reviewed, zero comments. Hosted CI is still running. ## Risks - Instructions depend on agent and reviewer compliance; these files are not deterministic lint rules. - The new MDC directory is explicitly routed through `AGENTS.md` and Greptile. Cursor does not automatically discover arbitrary `rules/` directories. - This preserves the observed High strictness setting, which the dashboard says omits P2 comments. It does not change that review policy. - Dashboard instructions and custom rules remain additive. Their copies were not disabled during read-only inspection. The repository-specific no-screenshot rule explicitly takes precedence over the conflicting older organization instruction. - Draft review, the required 5/5 status threshold, image badges, and other controls without documented config equivalents remain in the dashboard. See `.greptile/README.md` for the inventory and cutover limitations. ## Model Used OpenAI Codex based on GPT-6. The exact runtime model ID and context-window size are not exposed in this session. Used reasoning, repository inspection, shell validation, official documentation, and read-only browser inspection. ## 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 (configuration parsing and scope checks described above; application suites were not run) - [x] I have added or updated tests where applicable (no runtime change; checked configuration directly) - [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 - [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 <noreply@paperclip.ing>
61 lines
3.3 KiB
Plaintext
61 lines
3.3 KiB
Plaintext
---
|
|
description: Keep chat channel platform implementations in their own folders and shared orchestration independent of platform details.
|
|
globs: "server/src/services/chat-channels/**,server/src/services/chat-channels.ts"
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Chat channel platform boundaries
|
|
|
|
## Scope and purpose
|
|
|
|
This rule applies to `server/src/services/chat-channels/` and its sibling
|
|
`server/src/services/chat-channels.ts` service entry point. Keep each platform's
|
|
implementation cohesive while letting common workflows support different
|
|
platforms through explicit contracts.
|
|
|
|
## Required structure
|
|
|
|
- Put platform-specific code in `chat-channels/<platform>/`. This includes
|
|
payload parsing, SDK and transport calls, protocol details, credential and
|
|
setup behavior, message formatting, and platform-specific workarounds.
|
|
- Use the existing platform directories, such as `telegram/`, `slack/`,
|
|
`discord/`, `github/`, `microsoft-teams/`, and `imessage-photon/`. Organize files
|
|
within each directory by responsibility, such as `messages.ts` or `setup.ts`.
|
|
- Keep shared product behavior in the service or cohesive workflow modules,
|
|
such as `inbound/`, `interactions/`, and `publications/`. Shared code owns common
|
|
company isolation, authorization, task lifecycle, ordering, and persistence
|
|
invariants. Provider details must not bypass those invariants.
|
|
- Use explicit typed inputs, outputs, capabilities, or callbacks at the boundary.
|
|
Shared workflows should consume normalized values rather than interpret one
|
|
platform's raw payloads. Pass the dependencies a module needs instead of a
|
|
large mutable service context.
|
|
- Reuse existing contracts and shared implementations when their behavior is
|
|
actually common. Preserve meaningful platform differences. Add a new
|
|
abstraction only when a concrete workflow needs it.
|
|
- When extracting code, preserve transaction ownership, queue ordering,
|
|
idempotency, runtime state lifetime, and callback timing. Moving code must not
|
|
create duplicate state or a second owner for a side effect.
|
|
|
|
## Examples and allowed exceptions
|
|
|
|
- Telegram edited-message parsing belongs in `telegram/messages.ts`; a shared
|
|
delivery workflow can consume its normalized message or lifecycle event.
|
|
- Shared orchestration may import platform modules and select an implementation
|
|
by provider name. Small registration tables and dispatch branches are valid;
|
|
the selected branch should delegate protocol behavior to the platform module.
|
|
- Keep behavior used by several platforms in a shared module when its inputs and
|
|
semantics are independent of those platforms. Do not make one platform import
|
|
another platform's implementation merely to reuse a helper.
|
|
- Existing code outside these boundaries can be migrated incrementally. Apply
|
|
the rule to new or materially changed behavior; an unrelated fix does not
|
|
require moving the whole subsystem.
|
|
|
|
## Review criteria
|
|
|
|
Flag new or expanded platform-specific implementation in the service entry
|
|
point or shared workflow modules, direct dependencies between unrelated
|
|
platform implementations, and shared contracts that expose a platform's raw
|
|
payload or SDK types. Identify the behavior and the appropriate owning folder.
|
|
Allow the registration and dispatch exceptions above, and do not request an
|
|
abstract provider framework solely to remove a small dispatch branch.
|