AGENTS.md · diff

git:20260712.f2df0ed to git:20261012.f4be45c

38 added, 54 removed. Audit A to A.

# Perfetto Skills Agent Guide

- Perfetto Skills is an independently developed, portable Agent Skill for

- Perfetto analysis. It synchronizes selected knowledge from SmartPerfetto and

- official Perfetto through explicit, pinned workflows. Reply to maintainers in

- the language they use.

+ Perfetto Skills is an independent, portable Agent Skill. Reply in the

+ maintainer's language. Inspect current source, tests, and worktree before

+ editing; preserve unrelated changes and review the task-owned diff before

+ landing.

- ## Source boundaries

+ ## Source and evidence boundaries

- - The pinned SmartPerfetto snapshot is the source of truth only for imported

- assets. Perfetto-Skills-native behavior and reviewed overlays live under

- `src/` and evolve independently.

- - Files marked `GENERATED FILE` are output. Fix the exporter, immutable import,

- native source, or explicit overlay and recompile; never patch generated

- output directly.

- - The public Skill must work without SmartPerfetto services, MCP, DataEnvelope,

- provider runtimes, session state, reports, snapshots, or UI actions.

- - Do not commit trace processor binaries, credentials, proprietary traces, or

- unbounded query results.

- - Normal development and verification use this repository's owned real-trace

- fixtures. A sibling SmartPerfetto checkout is only an explicit sync input.

+ - `src/` owns native behavior and reviewed overlays. Pinned SmartPerfetto

+ snapshots own imported assets only. A sibling checkout is an explicit sync

+ input, never a development or runtime dependency.

+ - Files marked `GENERATED FILE` are output: fix the exporter, immutable import,

+ native source, or overlay and recompile. Never patch generated output.

+ - Public Skills must run without SmartPerfetto services, MCP, DataEnvelope,

+ providers, sessions, reports, snapshots, or UI actions.

+ - Preserve missing-evidence, identity, timestamps, durations, units, trace-side,

+ and claim-verification contracts. Do not commit processor binaries,

+ credentials, proprietary traces, or unbounded query results.

- ## Skill rules

+ ## Skill layout

- - Keep `skills/perfetto-performance-analysis/SKILL.md` under 500 lines and use

- imperative instructions.

- - Frontmatter must begin at byte zero and remain accepted by both

- `quick_validate.py` and the `agentskills` validator from `skills-ref`.

- - Put Agent-readable detail in `references/`, deterministic operations in

- `scripts/`, output templates in `assets/`, and optional Codex UI metadata in

- `agents/openai.yaml`.

- - Preserve missing-evidence, identity, timestamp, duration, units, trace-side,

- and claim-verification boundaries.

+ Keep the main `SKILL.md` under 500 lines with imperative instructions and

+ frontmatter at byte zero, accepted by both `quick_validate.py` and

+ `agentskills`. Put detail in `references/`, deterministic operations in

+ `scripts/`, templates in `assets/`, and optional UI metadata in

+ `agents/openai.yaml`.

- ## Cross-repository impact

+ ## Verification and landing

- Before committing or pushing a change that can alter portable Skill behavior,

- run:

+ Use Python 3.11+ and `uv sync --extra dev`. For iteration, choose the smallest

+ applicable repository check from [verification](docs/maintenance/verification.md).

+ Behavior fixes need focused regression coverage; local SQL changes need a

+ failing owned real-trace assertion. Documentation-only changes do not need an

+ artificial failing test. Before push, run the complete independent gate:

```bash

- uv run python tools/check_cross_repo_impact.py --repository perfetto-skills \

- --base "$(git merge-base HEAD origin/main)"

+ uv run python tools/verify.py

```

- The command includes branch, staged, unstaged, and untracked paths. For a

- matched change, record exactly one semantic decision: `required`,

- `not_required`, or `deferred`. Every decision needs a reason; `deferred` also

- needs a durable handoff. If the decision is `required`, pass `--paired-path`

- and an immutable `--paired-ref` equal to the paired checkout HEAD, update and

- verify SmartPerfetto before landing, and record the emitted fingerprint/paired

- evidence in commit or PR notes; otherwise use `deferred` with the tracking

- location. Do not mechanically copy local overlays upstream.

- The complete trigger list, paired checks, and SmartPerfetto, Google official

- Skill, and PerfettoSQL synchronization procedures live in

- `docs/maintenance/upstream-sync.md`.

- ## Development

- Use Python 3.11+ and write a failing test before behavior changes.

+ Scoped tiers, selected tests, and offline smoke are not a complete gate. Review

+ cross-repository impact before committing or pushing portable-behavior changes:

```bash

- uv sync --extra dev

- uv run python tools/verify.py

+ uv run python tools/check_cross_repo_impact.py --repository perfetto-skills \

+ --base "$(git merge-base HEAD origin/main)"

```

- Only this repository-defined command may be used as the complete gate. Use

- `--offline` for the committed smoke trace and `--smartperfetto PATH` only for

- an explicit synchronization check; neither is a substitute for the complete

- independent gate before push.

+ Record `required`, `not_required`, or `deferred` with reason and fingerprint;

+ `deferred` needs a durable handoff. A required pairing must use the paired

+ checkout's exact immutable HEAD and pass both projects' gates before landing.

+ Trigger paths, evidence fields, pinned sync procedures, and overlay maintenance

+ are defined in [upstream synchronization](docs/maintenance/upstream-sync.md).

+ Do not mechanically copy local overlays upstream.