AGENTS.md git:20261018.2621782A

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

# infra-skills — agent context

This repository *is* a set of agent instructions. When you are asked to change it, the
most likely way to get it wrong is to edit the wrong copy of a file.

## Rule 1: do not edit generated files

`skills/`, `.claude-plugin/`, `.codex-plugin/`, `.agents/plugins/` and the
Pi fields of `package.json` are generated from
`.ai-rulez/`. They are the obvious files to open — `skills/infra-setup/SKILL.md` looks like the
skill — and editing them is silently undone by the next `npm run generate`.

Before editing any file under those paths, check `.ai-rulez-generated.json`. If the path
is listed (59 are), edit its source under `.ai-rulez/` instead, then run `npm run generate`.

Most generated files carry an `AI-RULEZ :: GENERATED FILE — DO NOT EDIT` header, but
**28 of the 59 do not** — every non-Markdown output, because a Markdown comment is not
valid in them: the JSON manifests (`marketplace.json`, `plugin.json`),
`config.md.example`, `decisions.md.example`, `steps.yaml`, shell checks
(`gcp-wif-trust.sh`, `gha-apply-gate.sh`, `gha-latest-runs.sh`, `hcp-apply-scope.sh`,
`hcp-bootstrap-workspaces.sh`, `hcp-github-app.sh`, `hcp-current-plan.sh`, `leaf-cloud.sh`,
`provider-requirements.sh`, `status-check-context.sh`, `gha-provider-safety.sh`,
`leaf-routing.sh`, `workflow-routing.sh`, `gha-workflows.sh`, `state-transfer.sh`), App manifests
(`templates/apps/terraform-plan.json`, `templates/apps/terraform-apply.json`),
and the YAML workflow templates
(`terraform-apply.yml`, `terraform-plan.yml`), plus their CommonJS helper
(`terraform-destroy.cjs`). Absence of the header is not evidence a
file is safe to edit. The manifest is the authority; the header is only a convenience.

One writer is exempt: the release PR. release-please bumps the version in the three
generated JSON manifests alongside `package.json`, their version source, and the release
workflow then runs `npm run generate` on the PR branch and commits the result — the bump
changes the source hash every generated file records. That exemption covers only the
release workflow — hand edits to generated files are still wrong.

## File resolution

| To change… | Edit | Then |
|---|---|---|
| A skill's behavior | `.ai-rulez/skills/<name>/SKILL.md` | `npm run generate` |
| Shared protocol, phase manifest, provider docs | `.ai-rulez/skills/infra/references/…` | `npm run generate` |
| A host's question tool or capabilities | `.ai-rulez/skills/infra/references/hosts.md` | `npm run generate` |
| A host's install instructions | `docs/install-<host>.md` | hand-authored — edit directly |
| Plugin identity, keywords | `.ai-rulez/config.toml` | `npm run generate` |
| The plugin version or `CHANGELOG.md` | nothing — release-please's release PR bumps every copy | merge the release PR |
| What gets bumped at release | `release-please-config.json` | `npm run check:all` |
| Antigravity manifest | `plugin.json` | hand-authored — edit directly |
| Codex marketplace | `.ai-rulez/config.toml` (`[plugin.codex]`) | `npm run generate` — the file is generated |
| Repository validators | `scripts/validate.py`, `tests/` | `npm run check:all` |
| The SessionStart hook | `hooks/session-start.sh`, `hooks/hooks.json` (Claude only) | hand-authored — `ai-rulez` has no hook support |
| The `infra-auditor` subagent | `agents/` (root, Claude dialect) | hand-authored — `ai-rulez` has no agent support |
| Tool pins | `package.json` + `package-lock.json`; versions only here, exact, and Renovate keeps them current | `npm run check:all` |

## Rule 2: run `npm run check:all`

Never invoke `npx ai-rulez`, `python3 scripts/validate.py`, or the `skills` installer
directly in documentation, in a commit's verification step, or in the Linux CI job.
`npm run check:all` runs every check CI runs on Linux; CI also runs the Windows job below.

This governs **this repository's own workflow**. The install guides under `docs/` address
a different audience: those commands run in the *consuming* repo, which has no copy of
these npm scripts, so they name each host's native installer — `npx skills add` on OpenCode,
`/plugin install` on Claude Code. That is the supported public install path and has been
the README's since #4. The rule binds maintainer instructions, not user instructions.

One deliberate exception: the `windows-paths` job in `.github/workflows/check.yml` calls
`python scripts/validate.py` and the tests directly, because the npm scripts
are not installed on `windows-latest`. That job exists to prove paths stay portable, not to be
CI parity. Leave
it as it is.

## Architecture, in one paragraph

Five action skills — `infra-setup`, `infra-import`, `infra-prune`, `infra-add`, `infra-status` — are
thin routers over one hub
skill, `infra-skills`, whose `references/` directory owns the behavior: `steps.yaml` (a
phase-tagged step manifest with a `check` per step), `protocol.md` (the actor model, the
handoff block, the resume scan, preflight), provider deep-dives, and runbooks. Host
packages are adapters and must never become a second behavioral authority. State is never
assumed: every run re-derives it by executing each step's `check`.

## Conventions

- Conventional Branch names, Conventional Commits.
- No AI attribution in commits, PR titles, or bodies.
- Behavior in `.ai-rulez/skills/`; host-specific values in adapters only. One declared
  exception: `references/hosts.md` records what differs per host (native question tool
  and its capabilities, slash-command support) because the rules that read it are
  host-neutral and ship identically to all four hosts. The rule still binds what it was
  written for — a skill body must never name a host's tool; it reads the record instead.
  Change a capability there, not in an adapter.

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full loop and
[`docs/roadmap.md`](docs/roadmap.md) for what is deliberately unbuilt.

## Agent skills

### Issue tracker

Issues live as GitHub issues in `hasansezertasan/infra-skills`, driven with the `gh` CLI.
See [`docs/agents/issue-tracker.md`](docs/agents/issue-tracker.md).

### Triage labels

The five canonical triage roles, each label string equal to its name. See
[`docs/agents/triage-labels.md`](docs/agents/triage-labels.md).

### Domain docs

Single-context: one `GLOSSARY.md` and `docs/adr/` at the repo root, both created lazily.
See [`docs/agents/domain.md`](docs/agents/domain.md).