From 64673ae81cac9ef0c295ab0a7ca1f115ef6ed6b9 Mon Sep 17 00:00:00 2001 From: nivSwisa1 Date: Tue, 6 Oct 2026 17:15:39 +0300 Subject: [PATCH 1/3] docs: professional root README with badges, quick start and diagram; fix stale plugin example Co-Authored-By: Claude Opus 5.5 --- README.md | 105 +++++++++++++++++++++++++++--- plugins/agentic-advisor/README.md | 2 +- 2 files changed, 97 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 34b37da..a178a06 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,108 @@ -# LinearB Agent Plugins +

LinearB Agent Plugins

-LinearB plugins for AI coding agents: engineering context from LinearB, right inside your agent. +

+ Engineering context from LinearB, right inside your AI coding agent. +

-## Install (Claude Code) +

+ License: Apache-2.0 + Claude Code plugin marketplace + agentic-advisor version + Last commit +

-``` -/plugin marketplace add linear-b/agent-plugins -/plugin install @linearb-ai -``` +

+ Quick start · + Plugins · + How it works · + Privacy · + Security +

+ +--- -Then restart Claude Code so the plugin's hooks load. +AI agents write code the same way whether the target is a calm, well-tested module or a file that's been rewritten five times this quarter. These plugins give the agent the context a senior engineer would have: how healthy the repo is, how fragile the files are, and how much care the change deserves. ## Plugins | Plugin | What it does | | --- | --- | -| [`agentic-advisor`](plugins/agentic-advisor) | Before writing code, grades how fragile the target is (LinearB rework, incidents, unreviewed merges + local git history) and holds the agent to a matching LOW / MEDIUM / HIGH effort level. | +| [**agentic-advisor**](plugins/agentic-advisor) | Before writing code, grades how fragile the target is (LinearB rework, incidents and unreviewed merges, plus local git history on the files being touched) and holds the agent to a matching **LOW / MEDIUM / HIGH** effort level: lean on calm repos, defensive on fragile ones. | + +## Quick start + +**1. Add the marketplace and install** (in Claude Code): + +```text +/plugin marketplace add linear-b/agent-plugins +/plugin install agentic-advisor@linearb-ai +``` + +**2. Create a LinearB API token** (**LinearB → Settings → API Tokens → Create API Token**) and export it: + +```sh +export LINEARB_API_TOKEN="" +``` + +**3. Restart Claude Code** from that shell. Hooks and the skill read the environment at launch. + +That's it. Start a code task (`fix the retry bug in billing/client.ts`) and the agent prints its verdict before it edits anything: + +> LinearB: api-service — LOW effort (healthy: rework 0.4%, 0 unreviewed merges, no incidents). + +> LinearB: payments-service — HIGH effort (rework 9.5% NEEDS FOCUS; target PaymentForm.tsx: ~140 lines rewritten/90d) — smallest viable change, defensive validation, focused test. + +## How it works + +```mermaid +flowchart LR + A[Code task starts] --> B{Trivial edit?} + B -- yes --> L[LOW] + B -- no --> C[Repo health
LinearB API] + C --> D[Task complexity
from the prompt] + D --> E[Change area
local git history] + E --> F[effort = max of the three] + F --> G[Agent works at that level] +``` + +- **Repo health** comes from LinearB's public API: rework rate (bands match LinearB's own benchmark), unreviewed merges and recent incidents. It's cached per repo for 24 hours. +- **Task complexity** is graded from the request itself, so a demanding change in a calm repo still gets real care. +- **Change area** looks at the exact files being touched, using local git history only: how much existing code was rewritten over 90 days, and who owns it. +- **It never blocks.** If LinearB is unreachable or no token is set, the grade falls back to MEDIUM and work continues. + +See the [plugin README](plugins/agentic-advisor) for triggers, the full grading rules and configuration. + +## Requirements + +- [Claude Code](https://docs.claude.com/en/docs/claude-code) with plugin support +- A LinearB account and an org API token (`LINEARB_API_TOKEN`) +- `git`, `curl` and `jq` on your `PATH`; `python3` is optional (enables token accounting) +- macOS or Linux + +## Configuration + +| Variable | Default | Purpose | +| --- | --- | --- | +| `LINEARB_API_TOKEN` | *(none)* | LinearB org API token. Used to read health signals and to report usage. | +| `LINEARB_API_URL` | `https://public-api.linearb.io` | Point at a regional or on-prem LinearB API. | +| `LINEARB_TELEMETRY` | `1` | Set to `0` to turn off usage reporting. The plugin keeps working. | + +## Privacy & telemetry + +The plugin reports each effort decision to **your own LinearB org**, the one your token belongs to, as the custom metric `agentic_advisor.effort_decision`. That lets you see adoption and grades per developer and repo inside LinearB. Nothing is sent anywhere else. + +- **What's sent:** the grade and its one-line evidence, repo, branch, session title, contributor email and token counts. The [full field list](plugins/agentic-advisor#usage-telemetry-on-by-default) is in the plugin README. +- **What's never sent:** source code, file contents or the full text of your prompts. +- **Turn it off** with `export LINEARB_TELEMETRY=0`. +- **Token handling:** the API token is passed to `curl` on stdin, never as a command-line argument, and is never printed or logged. + +## Security + +Please report vulnerabilities privately to **security@linearb.io**. Don't open a public issue. See [SECURITY.md](SECURITY.md). + +## Support + +Questions or problems? Open a [GitHub issue](https://github.com/linear-b/agent-plugins/issues) or email **support@linearb.io**. ## License diff --git a/plugins/agentic-advisor/README.md b/plugins/agentic-advisor/README.md index 40739e8..882b654 100644 --- a/plugins/agentic-advisor/README.md +++ b/plugins/agentic-advisor/README.md @@ -19,7 +19,7 @@ The agent prints a one-line verdict before writing code, e.g.: > LinearB: api-service — LOW effort (healthy: rework 0.4%, 0 unreviewed merges, no incidents). -> LinearB: payments-service — HIGH effort (rework 9.5% NEEDS FOCUS; target PaymentForm.tsx: 3 fix/revert commits/90d) — smallest viable change, defensive validation, focused test. +> LinearB: payments-service — HIGH effort (rework 9.5% NEEDS FOCUS; target PaymentForm.tsx: ~140 lines rewritten/90d) — smallest viable change, defensive validation, focused test. ## How it decides From b4efea858c0207128448988efbda35f9d9606dd0 Mon Sep 17 00:00:00 2001 From: nivSwisa1 Date: Tue, 6 Oct 2026 17:19:13 +0300 Subject: [PATCH 2/3] docs: change-area check is conditional (fragile repo or sensitive files) Co-Authored-By: Claude Opus 5.5 --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a178a06..6bb7cee 100644 --- a/README.md +++ b/README.md @@ -60,14 +60,16 @@ flowchart LR B -- yes --> L[LOW] B -- no --> C[Repo health
LinearB API] C --> D[Task complexity
from the prompt] - D --> E[Change area
local git history] - E --> F[effort = max of the three] + D --> H{Repo MEDIUM/HIGH or
sensitive files?} + H -- yes --> E[Change area
local git history] + H -- no --> F + E --> F[effort = highest axis] F --> G[Agent works at that level] ``` - **Repo health** comes from LinearB's public API: rework rate (bands match LinearB's own benchmark), unreviewed merges and recent incidents. It's cached per repo for 24 hours. - **Task complexity** is graded from the request itself, so a demanding change in a calm repo still gets real care. -- **Change area** looks at the exact files being touched, using local git history only: how much existing code was rewritten over 90 days, and who owns it. +- **Change area** runs when the repo already grades MEDIUM/HIGH or the change touches sensitive code (auth, payments, migrations, concurrency, public API, crypto). It looks at the exact files being touched, using local git history only: how much existing code was rewritten over 90 days, and who owns it. - **It never blocks.** If LinearB is unreachable or no token is set, the grade falls back to MEDIUM and work continues. See the [plugin README](plugins/agentic-advisor) for triggers, the full grading rules and configuration. From 5c6bcce3f23ca936516468d8007d8e0021709fab Mon Sep 17 00:00:00 2001 From: nivSwisa1 Date: Tue, 6 Oct 2026 17:49:03 +0300 Subject: [PATCH 3/3] docs: link API token guide; advise keeping telemetry on Co-Authored-By: Claude Opus 5.5 --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6bb7cee..ffaacd5 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ AI agents write code the same way whether the target is a calm, well-tested modu /plugin install agentic-advisor@linearb-ai ``` -**2. Create a LinearB API token** (**LinearB → Settings → API Tokens → Create API Token**) and export it: +**2. Create a LinearB API token** (**LinearB → Settings → API Tokens → Create API Token**, [step-by-step guide](https://linearb.helpdocs.io/article/79fmogrxw3-how-to-generate-release-api-tokens)) and export it: ```sh export LINEARB_API_TOKEN="" @@ -77,7 +77,7 @@ See the [plugin README](plugins/agentic-advisor) for triggers, the full grading ## Requirements - [Claude Code](https://docs.claude.com/en/docs/claude-code) with plugin support -- A LinearB account and an org API token (`LINEARB_API_TOKEN`) +- A [LinearB](https://linearb.io) account and an org API token (`LINEARB_API_TOKEN`). See [Generating a LinearB API Token](https://linearb.helpdocs.io/article/79fmogrxw3-how-to-generate-release-api-tokens) - `git`, `curl` and `jq` on your `PATH`; `python3` is optional (enables token accounting) - macOS or Linux @@ -87,7 +87,7 @@ See the [plugin README](plugins/agentic-advisor) for triggers, the full grading | --- | --- | --- | | `LINEARB_API_TOKEN` | *(none)* | LinearB org API token. Used to read health signals and to report usage. | | `LINEARB_API_URL` | `https://public-api.linearb.io` | Point at a regional or on-prem LinearB API. | -| `LINEARB_TELEMETRY` | `1` | Set to `0` to turn off usage reporting. The plugin keeps working. | +| `LINEARB_TELEMETRY` | `1` | Set to `0` to turn off usage reporting. Not recommended: the plugin keeps working, but your usage won't show up in LinearB dashboards. | ## Privacy & telemetry @@ -95,7 +95,7 @@ The plugin reports each effort decision to **your own LinearB org**, the one you - **What's sent:** the grade and its one-line evidence, repo, branch, session title, contributor email and token counts. The [full field list](plugins/agentic-advisor#usage-telemetry-on-by-default) is in the plugin README. - **What's never sent:** source code, file contents or the full text of your prompts. -- **Turn it off** with `export LINEARB_TELEMETRY=0`. +- **Turn it off** with `export LINEARB_TELEMETRY=0`. We don't recommend it: your usage then won't appear in your LinearB dashboards. - **Token handling:** the API token is passed to `curl` on stdin, never as a command-line argument, and is never printed or logged. ## Security