AGENTS.md

1# Repository Guidelines
2 
3## Project Structure & Module Organization
4 
5This repository publishes an installable library of agent skills and plugin bundles. Canonical skill sources live in `skills/<skill-id>/SKILL.md`; use lowercase, hyphenated skill IDs. Mirrored plugin distributions live under `plugins/`. Contributor and user docs live in `docs/`; localized docs live in `docs_zh-CN/` and `docs/vietnamese/`. Maintenance scripts and tests are in `tools/scripts/` and `tools/scripts/tests/`. The hosted catalog app is in `apps/web-app/`. Registry outputs such as `CATALOG.md`, `skills_index.json`, and `data/*.json` are generated artifacts.
6 
7## Build, Test, and Development Commands
8 
9- `npm ci`: install root dependencies for scripts and validation.
10- `npm run validate`: validate skill frontmatter, required sections, and schema rules.
11- `npm run security:docs`: run safety checks for command, install, credential, and network guidance.
12- `npm run test`: run the repository script test suite.
13- `npm run build`: regenerate core indexes and build the catalog data.
14- `npm run app:install`: install `apps/web-app` dependencies.
15- `npm run app:dev`: start the local Vite catalog app.
16- `npm run app:build`: build and prerender the catalog app.
17 
18Before PRs, run `npm run validate && npm run test && npm run security:docs`.
19 
20## Coding Style & Naming Conventions
21 
22Use Markdown for skills and docs, JavaScript/Node for most tooling, and Python for audits and sync helpers. Keep skill directories lowercase with hyphens, for example `skills/my-awesome-skill/SKILL.md`. Start new skills from `docs/contributors/skill-template.md`; include frontmatter, `## When to Use`, examples, and limitations. Keep generated-file edits out of community PRs unless doing maintainer release or sync work.
23 
24## Testing Guidelines
25 
26Tests live mainly in `tools/scripts/tests/` and use Node assertions or Python `unittest`. Name new tests after the behavior under test, for example `installer_filters.test.js` or `test_validate_skills_strict.py`. Run targeted tests during development, then run the relevant npm scripts above. Web app changes should also run `npm run app:test` or `npm run app:test:coverage`.
27 
28## Commit & Pull Request Guidelines
29 
30History uses conventional-style subjects such as `feat: add ...`, `fix: refresh ...`, `docs: add ...`, and `chore: release ...`. Keep commits focused. PRs must use the default template, include the Quality Bar Checklist, link an issue when applicable, and allow maintainer edits. Source PRs should avoid generated registry artifacts; CI enforces this source-only contract.
31 
32## Agent-Specific Instructions
33 
34Respect deeper `AGENTS.md` files inside skill subtrees. When changing canonical skill content that is mirrored under `plugins/agentic-awesome-skills/` or `plugins/agentic-awesome-skills-claude/`, check whether mirrors must be synchronized. For release work, follow the scripted `release:prepare` and `release:publish` flow rather than hand-editing version surfaces.
35 
36### Current-Base Instruction Guard
37 
38Repository instructions must match the exact Git base used for the task. After creating a clean clone, worktree, or topic branch, re-read that base's `AGENTS.md`, `.github/MAINTENANCE.md`, canonical maintainer skill, and `package.json`; those files supersede instructions inherited from the checkout that launched the task.
39 
40Every command, script, reviewer, or gate described as mandatory must exist on the current task base. If it is absent, do not recover or execute it from another branch, worktree, stash, installed copy, or historical commit. Treat the mismatch as evidence that the procedure may have been retired, inspect `origin/main` and the relevant removal history, then follow the current-base contract or report the unresolved conflict.
41 
42### Mandatory Maintainer Workflow
43 
44For every repository maintenance sweep, PR merge batch, maintainer-side PR repair, canonical synchronization, combined Security/Quality cleanup and merge, or tag/release request, **always invoke and follow the `antigravity-maintainer-batch-release` skill before triage or mutation**. If the client has not installed or discovered that skill, read and follow the repository-canonical copy at `skills/antigravity-maintainer-batch-release/SKILL.md`. This is a hard gate, including when the user asks for direct merges or a direct update to `main`; do not substitute a generic Git or GitHub workflow.
45 
46Treat `main` as pull-request-only. Perform maintainer edits on a topic branch or in a clean temporary clone, merge accepted source PRs with `npm run merge:batch`, and let the protected canonical-sync PR own generated state and contributor-credit drift. Never retry a rejected direct push to `main` and never use a generic push helper for releases.
47 
48Use the skill's end-to-end sequence: complete triage, repair mergeable source PRs, run checks in parallel, merge source PRs in conflict-aware order, perform one canonical synchronization after the source batch, use the scripted protected-release flow when requested, and verify final `main`, tag, GitHub Release, npm package, CI, and live public surfaces. For changed `SKILL.md` files, distinguish a real Tessl `review` from `manual-review-required`; the latter means Tessl did not run and requires a maintainer review attested to the exact full head SHA. If neither an installed skill nor the repository-canonical copy is available and readable, stop before making repository changes and report that blocker explicitly.
49 
50Every stable or prerelease version must finish with the full-release-alignment gate in the maintainer skill. Do not declare a release complete until clean local `main` equals `origin/main`; canonical generated state is drift-free; every Codex and Claude plugin mirror, editorial bundle, manifest, compatibility report, and marketplace is regenerated and version-aligned; the tag, GitHub Release, npm version and intended dist-tag agree; CI, CodeQL, and the release-only Pages deployment for the exact released commit are green; live catalog and legacy-bridge surfaces match; and every already-configured local AAS MCP host is pinned to and actually running the released version. A release request authorizes updating existing AAS host entries only, never creating an absent host configuration.
51 
52#### Skill Content Review Gate
53 
54For every canonical `SKILL.md` change or tracked bundle-file change, run `npm run validate`, `npm run validate:references`, `npm run security:docs`, and the relevant tests. Inspect semantics, safety, provenance, declared risk, limitations, and every bundled file. The official merge gate remains a truthful Tessl `review` or a maintainer review attested to the exact full head SHA; heuristic local scores and inferred risk labels are not merge authority.
55