tvproductions/gzkit / .agents/skills/gz-init
gz-init
VerifiedUse to bootstrap, reinitialize or repair a repository's gzkit governance scaffolding.
gz init
Overview
gz init (init in src/gzkit/commands/init_cmd.py) has three modes, chosen
by the state of the working directory and the flags. It always acts on the
current directory; it never searches upward for a project.
- First init — no
.gzkit/yet, or--force. Writes.gzkit.jsonfrom the detected project structure, the manifest, thedesign/directories (prd,constitutions,adr), the Python skeleton unless--no-skeleton(pyproject.toml,README.md,src/<package>/__init__.py,tests/__init__.py, thenuv syncwhen.venvis absent),.gitignore,.pre-commit-config.yamlwith the pre-pushgz checkgate, anddata/audit_thresholds.json. In a git worktree it runspre-commit installfor every declared hook type, installs the commit-locus recorder whenpost-commitis declared, and registers thegzkit-jsonlmerge driver. It copies the wheel's canonical skills, chores, personas, templates and rules into.gzkit/, runs the sync preflight, syncs the control surfaces, and offers to register PRDs and ADRs it finds. Ledger: oneproject_initand anagent_sync_completedper sync. - Repair —
.gzkit/exists, no--force, no--update. Adds what is missing and never overwrites: skeleton,design/directories,.gitignore, pre-commit config, new canonical skills, rules, personas, templates and chores, the chores registry merge (--yesaccepts its prompt), the manifest, andauthorship.attestor_handlewhen--attestor-handleis given. Then it syncs the control surfaces, listing only files the sync changes; an already-synced tree runs no sync and appends no ledger row. In a git worktree with a pre-commit config, every repair re-runspre-commit installand rewrites the recorder hook, so it always reports at least those. - Update (
--update) — refreshes.gzkit/skills, rules, chores, personas and templates from the installed wheel by_detect_refresh_state:IDENTICALis skipped;STALE(the copy equals a version gzkit shipped, per the wheel'scanonical_history.json, or is missing) is overwritten;EDITED(any other difference, so an operator edit) is reported and left. It writes only what delivery defines:gz upgrade's classifiers pick the skills, rules, templates and personas, chores follow first-init delivery, andchores/registry.jsonis merged, keeping project-local entries (--yesaccepts the merge). Nothing else runs: no manifest, no sync, no ledger event.
Exit codes: 0 on success; 1 for --update with --force or
--attestor-handle, --update on an uninitialized project, a handle
containing whitespace, or a canonical-skill sync preflight failure; 3 when
--update leaves an EDITED conflict.
Workflow
- Choose the mode. A new repository:
uv run gz init(default--mode lite), with--attestor-handle <handle>to record the operator's handle. An existing one: repair, or--updateafter a gzkit upgrade.--modeis read only by first init. - Preview with
--dry-run. In repair and update it writes nothing and lists what the real run would write; for an artifact repair would newly scaffold, itsWould scaffoldline stands in for that artifact's mirrors (GHI #1098). A first-init dry run prints a fixed list of steps. - Run it. When repair exits 1 on the sync preflight, it has already made the
listed repairs and left every mirror unchanged: fix the canonical skills
under
.gzkit/skills/and re-run. - After
--update, runuv run gz agent sync control-surfaces:--updaterefreshes canon only, and the mirrors keep the old content until a sync. AnEDITEDconflict (exit 3) persists until the operator deletes the project copy and re-runs, or keeps the edit. - Use
--forceonly for full reinitialization, and only with the operator's agreement. It re-copies the wheel's skills, rules, templates and chores over the project's copies, so operator edits to them are lost; it never overwrites personas and deletes nothing. It rewrites.gzkit.jsonfrom the detected structure, which drops hand-set keys such as avendorsblock, custom paths, or an attestor handle not passed again. It appends anotherproject_initevent. - Report the mode, the listed writes, the exit code and any gate the output says is not installed.
Cautions
- In gzkit's own repository the installed wheel is the editable
src/gzkit/, a copy synced from.gzkit/. A.gzkit/edit not yet synced matches no shipped version, so--updatereports itEDITEDrather than reverting it; sync first.
Validation
- Repair and update print each write; confirm the list matches the request.
- After a first init with the skeleton:
pyproject.toml,README.md,<source_root>/<package>/__init__.pyand<tests_root>/__init__.pyexist. uv run gz validate --surfacespasses after init or a follow-up sync.
Example
uv run gz init --mode heavy --attestor-handle <handle> # first init
uv run gz init --dry-run # initialized project: list the repair writes
uv run gz init # repair
uv run gz init --update --dry-run
uv run gz init --update # then: uv run gz agent sync control-surfaces
Related
gz-agent-sync— the sync that init, repair and--forcerun, and that--updateneeds afterwardsuv run gz upgrade— surface-only refresh with per-surface classifiers,--surfaceand--forcedocs/user/manpages/init.md— the full contract
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |