From e8f804b18173063cdab5844f7da2f9c946ad3487 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:01:53 -0700
Subject: [PATCH] ci: set up frog friction logging

---
 .agents/friction-log/README.md      | 39 +++++++++++++++++++++++++++++
 .agents/friction-log/config.json    |  6 +++++
 .github/ISSUE_TEMPLATE/friction.yml | 34 +++++++++++++++++++++++++
 .github/workflows/friction-log.yml  | 39 +++++++++++++++++++++++++++++
 AGENTS.md                           |  7 ++++++
 5 files changed, 125 insertions(+)
 create mode 100644 .agents/friction-log/README.md
 create mode 100644 .agents/friction-log/config.json
 create mode 100644 .github/ISSUE_TEMPLATE/friction.yml
 create mode 100644 .github/workflows/friction-log.yml

diff --git a/.agents/friction-log/README.md b/.agents/friction-log/README.md
new file mode 100644
index 00000000000..db8e37970c3
--- /dev/null
+++ b/.agents/friction-log/README.md
@@ -0,0 +1,39 @@
+# Friction log
+
+Friction hit while working in this repository, one directory per item:
+
+```
+<id>/
+  friction.md   the write-up
+  artifacts/    optional, whatever reproduces it
+```
+
+Reporting an entry gives it an owner. The write-up then carries an `issue:` link and mirrors what happens
+to it. The whole directory is deleted once the friction is resolved. Every entry left here is still
+outstanding, including friction in dependencies.
+
+Do not maintain an index here. This directory is the index.
+
+## Logging Friction
+
+```sh
+frog list    # what is already known
+frog log     # add one
+```
+
+`frog log` writes the sections to fill in. Each id is when the friction was hit plus its title, so
+the directory reads oldest-first.
+
+Put anything that reproduces the friction in that entry's `artifacts/` and reference it from the
+write-up. The next reader runs the reproduction instead of rebuilding it.
+
+## For Agents
+
+Add these rules near the top of `AGENTS.md`, under the appropriate section. Create the file if missing; otherwise amend it in place, preserve all existing content, and never replace the file.
+
+- If `frog` is not installed, install the binary: `curl -fsSL https://frog.fm/install | sh`.
+- Log papercuts and friction (tooling, docs, APIs, tests, conventions) as you hit them with `frog log`.
+- Do not add global, system, or internal friction.
+- Run `frog list` first to see what is already known.
+
+Managed by [Frog](https://github.com/wevm/frog).
diff --git a/.agents/friction-log/config.json b/.agents/friction-log/config.json
new file mode 100644
index 00000000000..67d0bc8f1c3
--- /dev/null
+++ b/.agents/friction-log/config.json
@@ -0,0 +1,6 @@
+{
+  "$schema": "https://unpkg.com/frog/schema.json",
+  "inbound": {
+    "enabled": true
+  }
+}
diff --git a/.github/ISSUE_TEMPLATE/friction.yml b/.github/ISSUE_TEMPLATE/friction.yml
new file mode 100644
index 00000000000..af53a113019
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/friction.yml
@@ -0,0 +1,34 @@
+name: Friction
+description: Something about this project cost you time.
+labels: [friction]
+body:
+  - type: textarea
+    attributes:
+      label: Expected Behavior
+      description: Describe what should happen.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Current Behavior
+      description: Describe what happens instead.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Possible Solution
+      description: Optional. Suggest a fix or a reason for the friction.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Minimal Reproducible Example
+      description: Add a minimal reproducible example under `artifacts/`, or an unambiguous set of steps to reproduce this. Include code where relevant.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Context
+      description: Describe how this affected you, and what you were trying to accomplish.
+    validations:
+      required: false
diff --git a/.github/workflows/friction-log.yml b/.github/workflows/friction-log.yml
new file mode 100644
index 00000000000..9927f80f788
--- /dev/null
+++ b/.github/workflows/friction-log.yml
@@ -0,0 +1,39 @@
+name: Friction Log
+on:
+  push:
+    branches: [litellm_internal_staging]
+  issues:
+    types: [closed, reopened]
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * *'
+
+concurrency:
+  group: friction-log
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  friction-log:
+    name: Friction Log
+    if: github.event_name != 'issues' || github.event.issue.user.login == 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+
+      - name: Report and reconcile frictions
+        uses: wevm/frog/action@702c4eadefe175a208290a99c36e7f4ac1390e53 # frog@1.1.0
+        with:
+          issue-author: github-actions[bot]
+          branch: frog-sync
+          version: 1.1.0
diff --git a/AGENTS.md b/AGENTS.md
index 41921fdff4d..76da7dc383e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1 +1,8 @@
 Read @CLAUDE.md for coding guidelines
+
+## Friction log
+
+- If `frog` is not installed, install the binary: `curl -fsSL https://frog.fm/install | sh`
+- Log papercuts and friction (tooling, docs, APIs, tests, conventions) as you hit them with `frog log`
+- Do not add global, system, or internal friction
+- Run `frog list` first to see what is already known