# Pkg Bootstrap

> Initialize a new Arch Linux package in the repository. Use when adding a new package, creating a PKGBUILD from scratch, bootstrapping from an upstream AUR or Arch GitLab source, or setting up a package for the first time — even if the user doesn't explicitly mention "bootstrap" or "PKGBUILD."

- Skill: `pngdeity/pkg-bootstrap` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pngdeity/pkg-bootstrap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pngdeity/pkg-bootstrap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pngdeity (https://skillmd.com/u/pngdeity)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pngdeity/pkg-bootstrap

---


## Package Bootstrap Workflow

When adding a new package to `packages/`:

1. Create the package directory and a minimal `PKGBUILD`. For packages that mirror an existing Arch or AUR package, define the upstream source variable and the maintainer demotion flag:
   - `_upstream_aur_pkg` for AUR packages
   - `_upstream_arch_repo` for official Arch GitLab packages
   - `_demote_upstream_maintainer=true` to automatically demote upstream maintainers to contributors
   - `_pkgname=<canonical-name>` to declare the canonical software name (set on ALL packages in a variant family, including the base). If the package is standalone with no variants, omit `_pkgname`.
   - For `gemini-cli` variants, add `_use_common_gemini_settings=true`
   - `_deploy_aur=true` if this package should be published to the AUR by the CI/CD pipeline
   - For CPU-optimization variants, set `_repo_subarch` (e.g., `"x86_64_v3"`) — mutually exclusive with `_deploy_aur`
   If the package is entirely custom and does not mirror any upstream PKGBUILD, omit the `_upstream_*` variables and define a standard `source` array directly. In this case, skip step 2 and proceed to step 3.

2. For mirrored packages, run the bootstrap script. Look up the upstream version from the source repository (AUR web interface, Arch GitLab tags, or release page) before running:
   ```bash
   bash scripts/sync-package.sh <pkgname> <version>
   ```
   This fetches the upstream PKGBUILD, initializes tracking state, applies declarative identity rules (demotion, asset sync), and updates hashes. Only one invocation is needed.

3. Set up version checking from within the package directory:
   ```bash
   pkgctl version setup
   ```
   This generates a valid `.nvchecker.toml` from the PKGBUILD source array.

4. Create a package-local `AGENTS.md` ONLY if the package has non-standard build requirements, undocumented quirks, or specific environmental constraints. Otherwise skip this step. The file must follow the Hierarchical Policies in the root `AGENTS.md`.

5. Register the package in the root `.nvchecker.toml` for global version monitoring.

6. Run the full verification sequence:
   ```bash
   namcap PKGBUILD
   makepkg --printsrcinfo > .SRCINFO
   pkgctl build
   pkgctl diff --list
   ```

## Gotchas

- The `sync-package.sh` script expects the upstream source variable to be set correctly. If the upstream package uses a non-standard name, verify the variable before bootstrapping.
- `pkgctl version setup` must be run inside the package directory. The `.nvchecker.toml` it generates is package-specific.