AGENTS.md git:20261101.c6e32f6A

Immutable. This exact content never changes and is served at /api/v1/blob/bfea87cc0e974a82.

# AGENTS.md

Instructions for AI agents (Claude Code, Codex, Gemini, etc.) working in
this repo.

This is a **content-only** repo. The skills here are markdown documentation
that pairs with the `compose-preview` CLI and Gradle plugin published from
[yschimke/compose-ai-tools](https://github.com/yschimke/compose-ai-tools).
The CLI lives there; consumer guidance lives here.

**Generic skills, not harness wiring.** Skills here read the same in any agent
host: what to do, and which MCP tools or CLI commands to use. The set is meant
to grow beyond the preview toolchain into a wider range of Compose and Android
UI skills. Anything that names a particular host, or installs into, configures
or works around one (per-harness manifests, MCP client config, hooks, host
detection, a host's cloud sandbox, `claude.yml` sessions), belongs in
[yschimke/compose-agent-plugins](https://github.com/yschimke/compose-agent-plugins).
The full table, and the references still waiting to move, are in its
[`docs/repository-consolidation.md`](https://github.com/yschimke/compose-agent-plugins/blob/main/docs/repository-consolidation.md#the-two-agent-repositories).
Don't add new host-specific material here.

**Two upstream repos, not one.** The CLI, the Gradle plugin, the renderers and
the local daemon MCP ship from `compose-ai-tools`. The preview *server* —
everything behind `compose-preview serve`, including its catalog MCP endpoint,
the UI builder and the playground — ships from
[yschimke/compose-preview-server](https://github.com/yschimke/compose-preview-server),
on its own release line. When a skill cites `serve` source or a server-side
design doc, it belongs to that repo. (Its operator-facing manual,
`docs/public-preview-server.md`, still lives in `compose-ai-tools` — cite it
where it actually is rather than where the code is.)

## Git history

- Git history attributes work only to the human committer. Never add an AI
  `Co-authored-by:` trailer or use an agent identity as author or committer, in a commit or
  in a PR title or body. Session links and "Generated with" footers are fine.
- **Human reviewers: verify before reporting an attribution finding.** Automated reviewers do
  not report attribution at all; see [Review guidelines](#review-guidelines). Across these
  repositories it is the most-reported and least-real review finding, and reports have named
  commits that do not exist. Never infer the identity from the fact that an agent wrote the code: it
  is whatever `git config user.email` held, and here that is the human. Check the real range first:

      git cat-file -t <sha>          # a commit you are about to name must actually exist
      git log --format='%h %an <%ae> | %cn <%ce> | %(trailers:key=Co-authored-by,valueonly,separator=%x2C)' <base>..<head>

  `<head>` must be the pull request's head commit as GitHub reports it. A commit you made in your
  own checkout, for example by reapplying the PR's diff, carries your identity, not the author's;
  that is how every false report so far arose. Report only an agent name or an
  `@anthropic.com` / `@openai.com` address that this output shows for the PR's own commits, and
  quote it. `Yuri Schimke <yuri@schimke.ee>` is the human identity, and
  `github-actions[bot]` / `renovate[bot]` are exempt bot accounts. `GitHub <noreply@github.com>` is
  the committer of every squash merge. None of these is ever a finding.

## Review guidelines

- **Do not report commit author, committer or `Co-authored-by:` findings.** Your review sandbox
  applies the pull request as a new commit under your own identity (`Codex <codex@openai.com>`),
  so any identity you read from a local `git log` is yours, not the author's. Every such finding
  on these repositories has named a commit that exists only in the sandbox. Attribution is a
  human and CI concern; leave it out of reviews entirely. This overrides the human reviewer
  guidance on attribution elsewhere in this file.

## When adding, renaming, or removing a skill

1. **Update `README.md`** — keep the skills list in sync. Each entry links
   to the skill's `SKILL.md` and summarises what it covers. If you add a
   skill and don't update the README, the change is incomplete.
2. **Keep `scripts/install.sh` in sync.** Add the name to `COMPANION_SKILLS`
   (and to the `--skills` / `--all-skills` help text) so the curl installer
   can install it.

## Skill layout

- Skills live at `skills/<skill-name>/SKILL.md`. **Flat** — never nest by
  topic. Encode the topic in the directory name (e.g.
  `compose-preview-review`, not `compose-preview/review`).
- The `name:` in the SKILL.md frontmatter **must match the directory
  name** exactly. Use lowercase kebab-case for both.
- Supporting files (design notes, scripts) sit alongside `SKILL.md` in
  the skill dir.

## Harness plugins

Harness plugins live in
[yschimke/compose-agent-plugins](https://github.com/yschimke/compose-agent-plugins),
which vendors `compose-preview` and `compose-ui-builder` into its
`compose-preview` plugin and `compose-preview-review` + `compose-preview-ci`
into an optional `compose-review` plugin. This repo publishes no plugin or
marketplace.

## Cross-repo references

The `compose-preview` skill documents the CLI shipped from the
`compose-ai-tools` repo, so it cites release tags (e.g.
`v1.79.0`) and links into that repo. Keep those links stable. When the
CLI gets a new version, update referenced version strings here; do not
introduce a release-please marker in this repo — versions in skill text
track the upstream CLI, not this repo.

## What not to do

- Don't add CI, build tooling, or Gradle config here — this is a content
  repo. The exceptions are `scripts/install.sh` and its self-test, the
  skill-name check in CI, and the merge-policy checks shared with the
  sibling repositories (the PR-title and agent-attribution workflows, their
  scanner and tests, and the `.githooks`). CI, packaging, and the renderer live in `compose-ai-tools`.
- Don't rename existing skill directories "for consistency" without a
  concrete reason; renames break user references and bundled installs.