AGENTS.md · diff
git:20260725.2a588be to git:20261020.e42a531
28 added, 23 removed. Audit A to A.
# PerfGraph — AI Agent Instructions
This file tells AI coding agents (Claude, ChatGPT, Copilot, etc.) how to work with PerfGraph.
## What PerfGraph is
- A CLI tool that collects real browser performance data via CDP, runs it through a 5-stage pipeline, and produces a structured JSON report with causal chains and prioritized fixes. Designed to be consumed by AI agents.
+ A CLI tool that collects real browser performance data via CDP, runs it through a 5-stage pipeline, and produces a structured report (TOON for agents, Markdown for humans) with causal chains and prioritized fixes. Designed to be consumed by AI agents.
```
collect → normalize → extract → analyze → report
```
## How AI agents should use PerfGraph
### Quick entry point
```bash
npx perfgraph run --url https://example.com --pretty
```
- This runs the full pipeline. The output is a `report.json` with:
- - `summary.score` — `good` / `moderate` / `poor`
- - `issues[]` — each with severity, confidence, metric value, threshold, remediation
- - `chains[]` — causal degradation paths from root cause to user-facing impact
- - `recommendations[]` — prioritized, with evidence and expected impact
+ This runs the full pipeline. The output directory contains:
+ - `insights.toon` — compact triage, metrics, warnings, and top recommendations
+ - `report.toon` — issues, evidence, causal chains, and prioritized remediation
+ - `report.md` — human-readable report
+ - `manifest.toon` — artifact index and read order
- ### MCP mode (for AI agents with MCP support)
+ `summary.score` is `good` / `moderate` / `poor` and lives inside `insights.toon`
+ and `report.toon`.
- ```bash
- perfgraph mcp
- ```
+ The CLI needs Playwright's Chromium build. If it is missing, install it once
+ with `npx playwright install chromium` — the CLI reports the expected binary
+ path instead of a cryptic launch error.
- Starts an MCP stdio server. Agents can call `perfgraph_analyze` with a URL and get structured results back. The response includes paths to:
+ ### AI agent workflow
- | File | When to read |
- |------|-------------|
- | `insights.json` | **Read first.** Agent-optimized ~5-15 KB summary: Lighthouse scores, LCP element selector, render-blocking URLs, critical path depth |
- | `report.json` | Read for causal chains and prioritized recommendations |
- | `manifest.json` | File index with descriptions. Only needed if you want raw data |
- | `lighthouse.json` / `trace.json` | Deep dives only — these are large |
+ For a URL plus performance, speed, loading, Core Web Vitals, Lighthouse,
+ bottleneck, degradation, or causal-graph request, run:
- ### Workflow for agents
+ ```bash
+ perfgraph run --url <url> --output ./perfgraph-output --pretty
+ ```
- 1. Call `perfgraph_analyze` or run `perfgraph run --url ... --pretty`
- 2. Read `insights.json` for the quick picture
- 3. Read `report.json` for causal analysis and prioritized fixes
- 4. Only open raw files (`lighthouse.json`, `trace.json`, `network.json`) when you need specifics not covered by insights
+ Read `manifest.toon`, then `insights.toon`, then `report.toon`. Read
+ `graph.toon` and raw `trace.json`, `network.json`, or `lighthouse.json` only for
+ targeted deep dives. `.toon` files are text, not JSON.
+ The response should contain a short status, the 1–3 main causal chains as an
+ ASCII graph, 3–5 prioritized actions, evidence/confidence, warnings, and a
+ repeat-measurement plan. Do not treat `Possible INP delay` as measured INP or
+ analyze a failed collection as a slow page. See `skills/perfgraph/SKILL.md` for
+ the complete interpretation workflow.
+
## Diagnostics categories
| Category | What it detects |
|----------|----------------|
| LCP | Large Contentful Paint, TTFB, render-blocking resources |
| JavaScript | Long tasks, Total Blocking Time, heavy execution, unused code |
| Network | Request chains, bandwidth bottlenecks, waterfall depth |
| Layout | Layout shifts (CLS), DOM size, forced reflows |
| Third-party | Overhead from embedded scripts, tracking pixels, widgets |
## Development commands
```bash
npm install # install deps
+ npm run setup:browser # download Playwright Chromium (one-time)
npm run build # compile TypeScript
npm run typecheck # type-check only
npm test # run tests
npm run dev # tsx watch mode
```
## Type system
- Strict TypeScript with `noUncheckedIndexedAccess`
- Zod schemas at every data boundary: `src/*/types.ts`
- CDP data, Lighthouse audits, file I/O — all validated on ingress
- Internal code works with typed interfaces, not raw JSON
## Project conventions
- **kebab-case** for files (`lcp-breakdown.ts`, not `lcpBreakdown.ts`)
- **camelCase** for variables and functions
- **PascalCase** for types, interfaces, and classes
- Early returns. Keep nesting ≤ 3.
- No `@ts-ignore`, `@ts-expect-error`, or `as any` — ever.
## Causal rules
Rules live in `src/causal/rules/`. Each rule file exports an array of `CausalRule` objects. A rule:
- Has a unique `id`, `label`, `category`
- Has a `build()` function that takes `FeatureSet` and returns an array of `CausalNode` + `CausalEdge`
- Can attach `evidence` (URLs, selectors, metric values) to nodes
Adding a new rule: create a file in `src/causal/rules/`, register it in `src/causal/builder.ts`, write a test in `test/causal/`.
## Reporting issues
If PerfGraph gives wrong results, file an issue with:
- The URL tested
- The command run
- - The `report.json` (or at least the summary section)
+ - The `report.toon` (or at least the summary section)