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.json from the detected project structure, the manifest, the design/ directories (prd, constitutions, adr), the Python skeleton unless --no-skeleton (pyproject.toml, README.md, src/<package>/__init__.py, tests/__init__.py, then uv sync when .venv is absent), .gitignore, .pre-commit-config.yaml with the pre-push gz check gate, and data/audit_thresholds.json. In a git worktree it runs pre-commit install for every declared hook type, installs the commit-locus recorder when post-commit is declared, and registers the gzkit-jsonl merge 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: one project_init and an agent_sync_completed per 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 (--yes accepts its prompt), the manifest, and authorship.attestor_handle when --attestor-handle is 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-runs pre-commit install and 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: IDENTICAL is skipped; STALE (the copy equals a version gzkit shipped, per the wheel's canonical_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, and chores/registry.json is merged, keeping project-local entries (--yes accepts 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

1. 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 --update after a gzkit upgrade. --mode is read only by first init.
2. 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, its Would scaffold line stands in for that artifact's mirrors (GHI #1098). A first-init dry run prints a fixed list of steps.
3. 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.
4. After --update, run uv run gz agent sync control-surfaces: --update refreshes canon only, and the mirrors keep the old content until a sync. An EDITED conflict (exit 3) persists until the operator deletes the project copy and re-runs, or keeps the edit.
5. Use --force only 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.json from the detected structure, which drops hand-set keys such as a vendors block, custom paths, or an attestor handle not passed again. It appends another project_init event.
6. 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 --update reports it EDITED rather 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__.py and <tests_root>/__init__.py exist.
• uv run gz validate --surfaces passes 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 --force run, and that --update needs afterwards
• uv run gz upgrade — surface-only refresh with per-surface classifiers, --surface and --force
• docs/user/manpages/init.md — the full contract