antigravity-skills-reference/.github/MAINTENANCE.md

# 🛠️ Repository Maintenance Guide (V5)

> **"If it's not documented, it's broken."**

This guide details the exact procedures for maintaining `antigravity-awesome-skills`.
It covers the **Quality Bar**, **Documentation Consistency**, and **Release Workflows**.

---

## 0. 🤖 Agent Protocol (THE BIBLE)

**AGENTS MUST READ AND FOLLOW THIS SECTION BEFORE MARKING ANY TASK AS COMPLETE.**

There are 3 things that usually fail/get forgotten. **DO NOT FORGET THEM:**

### 1. 📤 ALWAYS PUSH (Non-Negotiable)

Committing is NOT enough. You must PUSH to the remote.

- **BAD**: `git commit -m "feat: new skill"` (User sees nothing)
- **GOOD**: `git commit -m "..." && git push origin main`

### 2. 🔄 SYNC GENERATED FILES (Avoid CI Drift)

If you touch **any of these**:

- `skills/` (add/remove/modify skills)
- the **Full Skill Registry** section of `README.md`
- **counts/claims** about the number of skills (`560+ Agentic Skills...`, `(560/560)`, etc.)

…then you **MUST** run the Validation Chain **BEFORE** committing.

- Running `npm run chain` is **NOT optional**.
- Running `npm run catalog` is **NOT optional**.

If CI fails with:

> `❌ Detected uncommitted changes produced by registry/readme/catalog scripts.`

it means you **did not run or commit** the Validation Chain correctly.

### 3. 📝 EVIDENCE OF WORK

- You must create/update `walkthrough.md` or `CHANGELOG.md` to document what changed.
- If you made something new, **link it** in the artifacts.

### 4. 🚫 NO BRANCHES

- **ALWAYS use the `main` branch.**
- NEVER create feature branches (e.g., `feat/new-skill`).
- We commit directly to `main` to keep history linear and simple.

---

## 1. 🚦 Daily Maintenance Routine

### A. Validation Chain

Before ANY commit that adds/modifies skills, run the chain:

1.  **Validate, index, and update readme**:

    ```bash
    npm run chain
    ```

    _Must return 0 errors for new skills._

2.  **Build catalog**:

    ```bash
    npm run catalog
    ```

3.  **COMMIT GENERATED FILES**:
    ```bash
    git add README.md skills_index.json data/catalog.json data/bundles.json data/aliases.json CATALOG.md
    git commit -m "chore: sync generated files"
    ```
    > 🔴 **CRITICAL**: If you skip this, CI will fail with "Detected uncommitted changes".
    > See [docs/CI_DRIFT_FIX.md](../docs/CI_DRIFT_FIX.md) for details.

### B. Post-Merge Routine (Must Do)

After multiple PR merges or significant changes:

1.  **Sync Contributors List**:
    - Run: `git shortlog -sn --all`
    - Update `## Repo Contributors` in README.md.

2.  **Verify Table of Contents**:
    - Ensure all new headers have clean anchors.
    - **NO EMOJIS** in H2 headers.

3.  **Draft a Release**:
    - Go to [Releases Page](https://github.com/sickn33/antigravity-awesome-skills/releases).
    - Draft a new release for the merged changes.
    - Tag version (e.g., `v4.1.0`).

---

## 2. 📝 Documentation "Pixel Perfect" Rules

We discovered several consistency issues during V4 development. Follow these rules STRICTLY.

### A. Table of Contents (TOC) Anchors

GitHub's anchor generation breaks if headers have emojis.

- **BAD**: `## 🚀 New Here?` -> Anchor: `#--new-here` (Broken)
- **GOOD**: `## New Here?` -> Anchor: `#new-here` (Clean)

**Rule**: **NEVER put emojis in H2 (`##`) headers.** Put them in the text below if needed.

### B. The "Trinity" of Docs

If you update installation instructions or tool compatibility, you MUST update all 3 files:

1.  `README.md` (Source of Truth)
2.  `docs/GETTING_STARTED.md` (Beginner Guide)
3.  `docs/FAQ.md` (Troubleshooting)

_Common pitfall: Updating the clone URL in README but leaving an old one in FAQ._

### C. Statistics Consistency (CRITICAL)

If you add/remove skills, you **MUST** ensure the total count is identical in ALL locations.
**Do not allow drift** (e.g., 560 in title, 558 in header).

Locations to check:

1.  **Title of `README.md`**: "560+ Agentic Skills..."
2.  **`## Full Skill Registry (560/560)` header**.
3.  **`docs/GETTING_STARTED.md` intro**.

### D. Credits Policy (Who goes where?)

- **Credits & Sources**: Use this for **External Repos**.
  - _Rule_: "I extracted skills from this link you sent me." -> Add to `## Credits & Sources`.
- **Repo Contributors**: Use this for **Pull Requests**.
  - _Rule_: "This user sent a PR." -> Add to `## Repo Contributors`.

### E. Badges & Links

- **Antigravity Badge**: Must point to `https://github.com/sickn33/antigravity-awesome-skills`, NOT `anthropics/antigravity`.
- **License**: Ensure the link points to `LICENSE` file.

### F. Workflows Consistency (NEW in V5)

If you touch any Workflows-related artifact, keep all workflow surfaces in sync:

1. `docs/WORKFLOWS.md` (human-readable playbooks)
2. `data/workflows.json` (machine-readable schema)
3. `skills/antigravity-workflows/SKILL.md` (orchestration entrypoint)

Rules:

- Every workflow id referenced in docs must exist in `data/workflows.json`.
- If you add/remove a workflow step category, update prompt examples accordingly.
- If a workflow references optional skills not yet merged (example: `go-playwright`), mark them explicitly as **optional** in docs.
- If workflow onboarding text is changed, update the docs trinity:
  - `README.md`
  - `docs/GETTING_STARTED.md`
  - `docs/FAQ.md`

---

## 3. 🛡️ Governance & Quality Bar

### A. The 5-Point Quality Check

Reject any PR that fails this:

1.  **Metadata**: Has `name`, `description`?
2.  **Safety**: `risk: offensive` used for red-team tools?
3.  **Clarity**: Does it say _when_ to use it?
4.  **Examples**: Copy-pasteable code blocks?
5.  **Actions**: "Run this command" vs "Think about this".

### B. Risk Labels (V4)

- ⚪ **Safe**: Default.
- 🔴 **Risk**: Destructive/Security tools. MUST have `[Authorized Use Only]` warning.
- 🟣 **Official**: Vendor mirrors only.

---

## 4. 🚀 Release Workflow

When cutting a new version (e.g., V4):

1.  **Run Full Validation**: `python3 scripts/validate_skills.py --strict`
2.  **Update Changelog**: Add the new release section to `CHANGELOG.md`.
3.  **Bump Version**:
    - Update `package.json` → `"version": "X.Y.Z"` (source of truth for npm).
    - Update version header in `README.md` if it displays the number.
    - One-liner: `npm version patch` (or `minor`/`major`) — bumps `package.json` and creates a git tag; then amend if you need to tag after release.
4.  **Create GitHub Release** (REQUIRED):

    > ⚠️ **CRITICAL**: Pushing a tag (`git push --tags`) is NOT enough. You must create a **GitHub Release Object** for it to appear in the sidebar and trigger the NPM publish workflow.

    Use the GitHub CLI:

    ```bash
    # This creates the tag AND the release page automatically
    gh release create v4.0.0 --title "v4.0.0 - [Theme Name]" --notes-file release_notes.md
    ```

    _Or manually via the GitHub UI > Releases > Draft a new release._

5.  **Publish to npm** (so `npx antigravity-awesome-skills` works):
    - **Option A (manual):** From repo root, with npm logged in and 2FA/token set up:
      ```bash
      npm publish
      ```
      You cannot republish the same version; always bump `package.json` before publishing.
    - **Option B (CI):** On GitHub, create a **Release** (tag e.g. `v4.6.1`). The workflow [Publish to npm](.github/workflows/publish-npm.yml) runs on **Release published** and runs `npm publish` if the repo secret `NPM_TOKEN` is set (npm → Access Tokens → Granular token with Publish, then add as repo secret `NPM_TOKEN`).

6.  **Close linked issue(s)**:
    - If the release completes an issue scope (feature/fix), close it with `gh issue close <id> --comment "..."`
    - Include release tag reference in the closing note when applicable.

### 📋 Changelog Entry Template

Each new release section in `CHANGELOG.md` should follow [Keep a Changelog](https://keepachangelog.com/) and this structure:

```markdown
## [X.Y.Z] - YYYY-MM-DD - "[Theme Name]"

> **[One-line catchy summary of the release]**

[Brief 2-3 sentence intro about the release's impact]

## 🚀 New Skills

### [Emoji] [Skill Name](skills/skill-name/)

**[Bold high-level benefit]**
[Description of what it does]

- **Key Feature 1**: [Detail]
- **Key Feature 2**: [Detail]

> **Try it:** `(User Prompt) ...`

---

## 📦 Improvements

- **Registry Update**: Now tracking [N] skills.
- **[Component]**: [Change detail]

## 👥 Credits

A huge shoutout to our community contributors:

- **@username** for `skill-name`
- **@username** for `fix-name`

---

_Upgrade now: `git pull origin main` to fetch the latest skills._
```

---

## 5. 🚨 Emergency Fixes

If a skill is found to be harmful or broken:

1.  **Move to broken folder** (don't detect): `mv skills/bad-skill skills/.broken/`
2.  **Or Add Warning**: Add `> [!WARNING]` to the top of `SKILL.md`.
3.  **Push Immediately**.