Define the Zi package contract before building a package skill #614

Objective

Make Zi packages consistent from repository layout through to package.json, so that new packages can be scaffolded correctly and existing ones can be brought into line, without relying on anyone remembering an unwritten contract.

The eventual goal is an agent skill that creates and repairs packages. This issue deliberately stops short of that: the skill is the last layer, and it cannot be built usefully until the contract it enforces exists in machine-readable form.

Measured baseline

All 18 published package manifests were surveyed.

The part Zi actually parses is already consistent: every manifest has exactly zsh-data: {plugin-info, zi-ices}. None nests an object inside plugin-info, and none carries a top-level _from, which means the _from branch in lib/zsh/install.zsh is currently dead for every published package.

The human-authored layer around it was never specified, and it shows.

plugin-info uses 8 different key sets across 18 repositories:

Zi reads exactly five fields from plugin-info (install.zsh:258): user, plugin, url, message, and required falling back to requires. Everything else in that object is inert.

Top-level npm metadata varies across 8 distinct key sets. Profile names use three incompatible systems at once: capability (bgn, binary, rootless), feature toggle (no-zsh-completion, no-color-swaps, man-only, html-only, minimal), and version pin (5.3.1 through 5.9), plus +keys suffixes.

requires carries two different kinds of token in one semicolon-separated field: annex capabilities (bgn, dl, rdl) and required commands (cc, make, cp, rm, tar, go, npm, gem, bash). Zi does branch on this (install.zsh treats bgn|dl|rdl as annex checks and everything else as a command check), so the behaviour is intentional but undocumented.

Anomalies a validator would catch today

Proposed layering

The skill is layer four. Layers one to three deliver consistency even with no agent involved.

1. A JSON Schema for the manifest. The contract: which fields exist, which Zi reads, which profile names are legal, what requires accepts. This does not exist today.
2. A validator that checks a manifest against the schema, runnable locally and in each package repository's CI.
3. A conformance test in zi that parses the published manifests and asserts the schema matches what the parser actually reads. This is what makes the contract self-correcting: a parser change that invalidates manifests fails Zi's own CI immediately, rather than surfacing at install time later.
4. The skill, which runs the validator, interprets its failures, scaffolds new packages, and handles the genuine judgment: which profiles a package needs, what the install recipe should be, whether it wants bgn.

Ownership follows enforcement. The schema, validator and conformance test belong in z-shell/zi, because Zi's parser is the contract and the two should change in the same pull request. This repository owns the policy decisions below and the skill.

Decisions needed

Each of these is exposed by the survey and cannot be settled by a validator alone.

1. version in plugin-info. Remove it from all six manifests, or give it a meaning Zi reads. Recommend removing: nothing consumes it, and a field that looks authoritative but is inert is worse than absent.
2. url versus user/plugin. Are they alternatives, is url legacy, and which wins when both are present as in ecs-cli? Recommend making them mutually exclusive and rejecting both-present in the validator.
3. required versus requires. Zi accepts both in two places. Recommend requires as canonical, since 23 profiles use it against 1, and keep reading required for compatibility while the schema forbids it in new manifests.
4. requires token vocabulary. Split the annex capabilities from required commands, or document that one field carries both. Recommend documenting the current behaviour rather than changing the format, and having the schema enumerate the known capability tokens so a typo is caught.
5. Profile naming. Three systems coexist. Recommend that default stays mandatory, capability suffixes stay free-form, and the schema requires default to be present. A stricter taxonomy can come later once the schema exists.
6. Top-level npm fields. Decide the minimum set (probably name, description, homepage, keywords, license, bugs) and whether dependencies, devDependencies and contributors are forbidden.
7. Minimum repository layout. What a package repository must contain beyond package.json: docs/README.md is present in all 18, so codify that, plus whatever CI is expected.

Skill distribution, which blocks layer four

Organization skills currently have no working distribution into repositories.

This repository's AGENTS.md already requires every repository-health evaluation to assess .github/skills/code-review/SKILL.md in the owning repository, and that file is absent almost everywhere. A package skill added today would be invisible in the 18 repositories that need it. Distribution needs deciding before layer four, or the skill only works from a checkout that happens to have it.

Scope

Packages only. Plugins already have the new-zsh-plugin skill and the canonical Zsh Plugin Standard. Annexes have no written standard at all, so a skill for them would be inventing one rather than enforcing one. Extend after packages proves out.

Acceptance

• Decisions 1 to 7 recorded, with the survey as evidence.
• A JSON Schema in z-shell/zi covering zsh-data, plugin-info and zi-ices.
• A validator, and a conformance test in zi that checks the published manifests against both the schema and the parser.
• Every anomaly in the table above either fixed or explicitly accepted.
• A decision on skill distribution into repositories.
• Only then, the zi-package skill under .github/skills/.

Context

The survey was produced while closing #612. Related: z-shell/zi#518 reaches the same conclusion from the parser side, that the manifest schema is the missing artifact and should be written down before any further work on the parser.