0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-14 17:40:37 +02:00

Files

T

DottaandPaperclip 7ac0354b51 docs: track chat channel rules and Greptile configuration (#16172 )

## 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>

2026-10-13 08:59:27 -05:00

chat-channel-platform-boundaries.mdc

docs: track chat channel rules and Greptile configuration (#16172 )

2026-10-13 08:59:27 -05:00

pull-request-review.mdc

docs: track chat channel rules and Greptile configuration (#16172 )

2026-10-13 08:59:27 -05:00

README.md

docs: track chat channel rules and Greptile configuration (#16172 )

2026-10-13 08:59:27 -05:00

README.md

Repository rules

Keep architectural guidance in focused .mdc files here. Each file is Markdown with YAML frontmatter containing a description and an alwaysApply boolean. For scoped rules, set alwaysApply: false and provide comma-separated, repository-relative globs. For repository-wide rules, set alwaysApply: true and omit globs. Use ** for all descendants of a directory. Include sibling entry points explicitly when needed.

Root AGENTS.md tells coding agents to read matching rules before editing or reviewing code. This directory is a repository convention: Cursor does not automatically load it as .cursor/rules/, and the .mdc extension alone does not make a tool apply a rule.

Greptile reads matching rule files through .greptile/files.json and receives loading instructions from .greptile/rules.md. The rule body remains here as the single source of truth. Repository configuration takes effect when the files are available on the reviewed branch; local files alone are not visible to the hosted reviewer.

When adding or changing a rule:

State the scope, required behavior, examples, exceptions, and review criteria.
Add its path to .greptile/files.json. Copy its globs into that entry's scope array, one pattern per element. For alwaysApply: true, omit scope.
Keep the rule's frontmatter and the Greptile scope synchronized. Verify that the scope covers representative files and excludes unrelated directories.
Keep detailed policy in the rule file instead of copying it into tool settings.

See the Greptile file-reference documentation for the manifest format.