Problem
Z-Shell has Zsh-first conventions, plugin examples, reviewer prompts, and CI
helpers, but no single organization standard that applies whenever Zsh source
is read, reviewed, diagnosed, created, or changed. The generic shell
instruction currently mixes Bash defaults into Zsh, and optional tools can be
mistaken for language authority.
Proposed outcome
- make the current released official Zsh manual the semantic authority
- add one canonical path-scoped Zsh instruction with stable rule IDs
- record stable-release, execution-profile, and source-class metadata in one
validated JSON policy
- classify standalone, sourced, autoload, and test execution profiles
- retain a repository-owned minimum Zsh version plus a current-stable CI model
- rewrite generic shell guidance as a dialect dispatcher
- deliver concise mandatory behavior through
AGENTS.md
- route the public standard through validated generated-composite delivery
- keep native Zsh validation authoritative over supplemental parsers, linters,
and formatters
First bounded increment
This issue's first implementation covers the proposed ADR, canonical standard,
machine policy, public validation and routing, reconciled optional consumers,
and generated-composite routing. It does not enroll another repository.
Deferred increments
- tracked-source classifier and exact-version CI
- repository enrollment and generated child delivery
- zsh-lint and formatter ratchets
- organization rollout and stable-release maintenance
Instruction impact review
- This is shared policy, scoped guidance, and enforcement.
- Codex, Claude Code, Copilot, humans, public standalone clones, and validated
generated composites must receive the applicable rule. Gemini CLI is
deprecated and is not a verification target.
- Public
AGENTS.md owns the concise mandate,
.github/instructions/zsh-scripting.instructions.md owns normative prose,
and lib/zsh-standard-policy.json owns machine-readable release and
classification data.
- The generic shell instruction, Zsh reviewer, plugin skill and template,
ZUnit skill, and PATTERNS.md must defer to those owners.
- The public manifest needs new Zsh instruction, policy, validator, and ADR
entries. Generated-composite consumers need separate task-only and path-only
Zsh routes.
- Every supported runtime receives mandatory behavior through public
AGENTS.md or the generated private composite. No optional hook, skill, or
agent is required.
- Public validators, applicable generator checks, route tests,
generated-output checks, and the 32,768-byte limit must pass.
Acceptance criteria
- official Zsh 5.9.2 metadata and documentation URLs are recorded and validated
- every normative rule has a stable ID and validated metadata
- recognized Zsh paths receive the canonical instruction for every task
- Zsh-in-
.sh is handled by dialect classification, not suffix assumptions
- ShellCheck is never prescribed for Zsh
- optional consumers link to canonical rule IDs without redefining policy
- public and applicable generated-delivery validation pass
- the ADR remains
PROPOSED
- no child repository is enrolled
Problem
Z-Shell has Zsh-first conventions, plugin examples, reviewer prompts, and CI
helpers, but no single organization standard that applies whenever Zsh source
is read, reviewed, diagnosed, created, or changed. The generic shell
instruction currently mixes Bash defaults into Zsh, and optional tools can be
mistaken for language authority.
Proposed outcome
validated JSON policy
AGENTS.mdand formatters
First bounded increment
This issue's first implementation covers the proposed ADR, canonical standard,
machine policy, public validation and routing, reconciled optional consumers,
and generated-composite routing. It does not enroll another repository.
Deferred increments
Instruction impact review
generated composites must receive the applicable rule. Gemini CLI is
deprecated and is not a verification target.
AGENTS.mdowns the concise mandate,.github/instructions/zsh-scripting.instructions.mdowns normative prose,and
lib/zsh-standard-policy.jsonowns machine-readable release andclassification data.
ZUnit skill, and
PATTERNS.mdmust defer to those owners.entries. Generated-composite consumers need separate task-only and path-only
Zsh routes.
AGENTS.mdor the generated private composite. No optional hook, skill, oragent is required.
generated-output checks, and the 32,768-byte limit must pass.
Acceptance criteria
.shis handled by dialect classification, not suffix assumptionsPROPOSED