Add Zig 0.16 support to zig-claude-kit with auto-detection#2
Conversation
zig-claude-kit now supports both Zig 0.15.x and 0.16. The
session-start hook and skills auto-detect which version the
project targets by reading minimum_zig_version from
build.zig.zon (falling back to `zig version`, then to 0.16).
Per-version artifacts:
- docs/claude-md-fragment-{0.15,0.16}.md -- CLAUDE.md fragments
- docs/ZIG_BREAKING_CHANGES-{0.15,0.16}.md -- reference sheets
- scripts/zig-knowledge-audit-{0.15,0.16}.sh -- probe suites
The 0.16 reference distills vibeutils's migration documentation:
"Juicy Main" (std.process.Init), std.io -> std.Io rename,
std.fs.File/Dir -> std.Io.File/Dir move, every blocking call
takes io, std.mem.indexOf* -> find*, args/env no longer global,
sync primitives moved to Io (Pool replaced by Io.async/Group),
@type split into 8 builtins, error renames (CrossDevice,
FileBusy, StreamTooLong), managed hash maps removed.
Carry-over 0.15 corrections (usingnamespace, async/await,
BoundedArray, signed division, tokenize renames, for-loop
index, format method signature, build.zig root_module,
ArrayList allocator-per-method) still apply in 0.16.
The /zig-check skill now applies the version-matched ruleset
and reports detected target in its header. /zig-patterns shows
both versions inline. /zig-init injects the right fragment.
Bumps plugin to 0.3.0; updates marketplace.json description.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit b786644. Configure here.
| changes doc when relevant: | ||
|
|
||
| - 0.15: `${CLAUDE_PLUGIN_ROOT}/docs/ZIG_BREAKING_CHANGES-0.15.md` | ||
| - 0.16: `${CLAUDE_PLUGIN_ROOT}/docs/ZIG_BREAKING_CHANGES-0.16.md` |
There was a problem hiding this comment.
Report/fix steps nested under 0.16-only section heading
Medium Severity
Procedure steps ### 5. Report results and ### 6. Suggest fixes are placed after the ## Rules When Project Targets 0.16 heading (line 105), making them structurally nested under the 0.16-only section in the markdown heading hierarchy. For a 0.15 project, Claude may interpret these steps as 0.16-specific and skip reporting results and suggesting fixes entirely. Previously these steps lived directly under ## Procedure alongside the other numbered steps.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit b786644. Configure here.
2 participants
Summary
Extend zig-claude-kit to support both Zig 0.15.x and 0.16, with automatic version detection from
build.zig.zon. Zig 0.16 is a major breaking-change release ("I/O as an Interface") that requires entirely different patterns for I/O, filesystem, process management, and threading. The plugin now detects the target version and injects the correct training corrections.Key Changes
scripts/detect-zig-version.sh): Readsminimum_zig_versionfrombuild.zig.zon, falls back tozig version, defaults to 0.16docs/ZIG_BREAKING_CHANGES-0.16.md): 900-line document covering the I/O-as-Interface redesign, filesystem moves (std.fs→std.Io), "Juicy Main" pattern, process state changes, sync primitive moves, and 40+ API renamesscripts/zig-knowledge-audit-0.16.sh): 469-line test suite with 40+ probes validating breaking change claims against the installed Zig compilerclaude-md-fragment-0.15.mdandclaude-md-fragment-0.16.mdfor injection into project CLAUDE.md/zig-patternsand/zig-checknow auto-detect version and show matching patterns;/zig-initinjects version-appropriate correctionszig-knowledge-audit.sh→zig-knowledge-audit-0.15.shfor clarity; 0.16 variant addedaudit-0.15andaudit-0.16targetsNotable Implementation Details
build.zig.zonor unrecognized version strings default to 0.16 (current release as of 2026-04-14)Rationale
Zig 0.16's I/O redesign is so extensive that a single "correct pattern" document is insufficient. The plugin must now understand which version the user's project targets and provide matching guidance. This prevents Claude from generating code that compiles under 0.15 but fails under 0.16 (or vice versa).
https://claude.ai/code/session_016FCgpoqJGUY1fGpiB3R3Fj
Note
Low Risk
Changes are confined to plugin docs, shell/Python tooling, and skill instructions—no application runtime or auth/data paths. Main review focus is accuracy of 0.16 guidance and detection edge cases (e.g. wrong fragment if
minimum_zig_versionis stale).Overview
zig-claude-kit now targets Zig 0.15.x and 0.16, with auto-detection (
detect-zig-version.sh:build.zig.zon→ installedzig→ default 0.16). Session start,/zig-init,/zig-patterns, and/zig-checkpick the matching training fragment and ruleset instead of a single 0.15-only path.Adds 0.16-specific reference material:
ZIG_BREAKING_CHANGES-0.16.md,claude-md-fragment-0.16.md, andzig-knowledge-audit-0.16.sh(compile probes for Io-as-Interface, Juicy Main,find*, etc.). The 0.15 audit is renamed tozig-knowledge-audit-0.15.sh;make auditroutes by installed Zig, with explicitaudit-0.15/audit-0.16. Eval output goes underprobes/<TARGET>/via--target(default 0.16). Marketplace/README/CLAUDE.md and plugin manifest bump to 0.3.0 with expanded descriptions.Reviewed by Cursor Bugbot for commit b786644. Bugbot is set up for automated code reviews on this repo. Configure here.