Skip to content

The open-source app everyone uses to manage agents at work

docs: keep routine product work in the harness (#16193)

Dotta9cb3e157b309
diff --git a/.greptile/files.json b/.greptile/files.json
index fc2430e09f..a537dbd352 100644
--- a/.greptile/files.json
+++ b/.greptile/files.json
@@ -12,6 +12,10 @@
"path": "rules/pull-request-review.mdc",
"description": "Existing Paperclip review guidance for PR descriptions, UI evidence, and growth of large source files."
},
+ {
+ "path": "rules/product-harness-responsibility.mdc",
+ "description": "Product requirements and review criteria for harness responsibility, minimal user-facing internals, truthful progress, and human decisions."
+ },
{
"path": "rules/chat-channel-platform-boundaries.mdc",
"description": "Architecture requirements and review criteria for separating chat channel platform implementations from shared orchestration.",
diff --git a/rules/README.md b/rules/README.md
index 2e7edf1d70..4fa6390aa9 100644
--- a/rules/README.md
+++ b/rules/README.md
@@ -27,5 +27,10 @@ When adding or changing a rule:
the scope covers representative files and excludes unrelated directories.
4. Keep detailed policy in the rule file instead of copying it into tool settings.
+Product behavior is covered by
+[`product-harness-responsibility.mdc`](product-harness-responsibility.mdc): routine
+work belongs to the harness, and user-facing detail must support an outcome or a
+real decision. This applies to orchestration as well as UI.
+
See the [Greptile file-reference documentation](https://www.greptile.com/docs/code-review/greptile-config-reference)
for the manifest format.
diff --git a/rules/product-harness-responsibility.mdc b/rules/product-harness-responsibility.mdc
new file mode 100644
index 0000000000..4297181583
--- /dev/null
+++ b/rules/product-harness-responsibility.mdc
@@ -0,0 +1,26 @@
+---
+description: Keep routine work in the harness and expose only useful product details.
+alwaysApply: true
+---
+
+# Let the harness handle routine work
+
+Applies to product design, implementation and review across UI, orchestration,
+setup, settings and user-facing errors.
+
+If the system knows the next step and can safely perform it under existing
+authority, the harness owns it.
+
+- Implement routine retries, reconnection, lease maintenance and finalization in
+ the owning service. Do not turn orchestration gaps into user checklists.
+- Each control and detail must enable a real decision, resolve uncertainty or help
+ use a result. Keep incidental internal states and identifiers out of default views.
+- Keep normal operation quiet. Show brief, contextual status only when useful,
+ backed by observed server state. Never hide blockers or imply progress that has
+ not occurred.
+- Do not ask task users to certify infrastructure facts.
+
+**Review:** Check that harness responsibility is implemented, visible details
+serve a purpose the user should affect.
+
+Apply this rule to changed flows; unrelated redesign is not required.