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 1/2] 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: + +``` +/ + 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 From f3dfacf93eb942f5b5b051a13984995a636ba1a8 Mon Sep 17 00:00:00 2001 From: mateo Date: Sat, 8 Aug 2026 19:24:06 +0000 Subject: [PATCH 2/2] docs: move frog friction rules into CLAUDE.md Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .agents/friction-log/README.md | 7 +------ AGENTS.md | 7 ------- CLAUDE.md | 10 ++++++++++ 3 files changed, 11 insertions(+), 13 deletions(-) diff --git a/.agents/friction-log/README.md b/.agents/friction-log/README.md index db8e37970c3..29a4f0c3872 100644 --- a/.agents/friction-log/README.md +++ b/.agents/friction-log/README.md @@ -29,11 +29,6 @@ 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. +These rules live in `CLAUDE.md`, which `AGENTS.md` points at, so amend them there rather than duplicating them into `AGENTS.md`. Managed by [Frog](https://github.com/wevm/frog). diff --git a/AGENTS.md b/AGENTS.md index 76da7dc383e..41921fdff4d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1 @@ 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 diff --git a/CLAUDE.md b/CLAUDE.md index 59929143c46..9c97b640e57 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -84,6 +84,16 @@ Follow these coding conventions for new/updated code (a three-line fix in a lega Follow conventional commits for commit names and PR titles +Log papercuts and friction you hit in this repository (tooling, docs, APIs, tests, conventions) with `frog log`, and run `frog list` first so you don't re-report something already known. Only repo-level friction belongs in `.agents/friction-log/`, not global, system, or agent-harness friction. If `frog` is missing, install the pinned release instead of piping the installer into a shell (pick the asset matching your platform from https://github.com/wevm/frog/releases/tag/frog@1.1.0): + +```sh +ver=1.1.0 +asset=frog-linux-x64-glibc-baseline.gz +curl -fsSLO "https://github.com/wevm/frog/releases/download/frog@$ver/$asset" +curl -fsSL "https://github.com/wevm/frog/releases/download/frog@$ver/SHA256SUMS" | grep "$asset" | sha256sum -c - +gunzip -c "$asset" > ~/.local/bin/frog && chmod +x ~/.local/bin/frog +``` + ## Think Before Coding **Don't assume. Don't hide confusion. Surface tradeoffs**