From b56467d495da4d70ab9b2ea5c9b4f122c7fb7693 Mon Sep 17 00:00:00 2001 From: Salvydas Lukosius Date: Wed, 20 May 2026 05:25:51 +0100 Subject: [PATCH 1/3] chore(meta): establish llm management foundation --- .github/ISSUE_TEMPLATE/01_bug_report.yml | 2 +- .github/ISSUE_TEMPLATE/02_feature_request.yml | 2 +- .../03_codebase_improvement.yml | 2 +- .github/ISSUE_TEMPLATE/04_documentation.yml | 2 +- .github/ISSUE_TEMPLATE/05_membership.yml | 2 +- .github/ISSUE_TEMPLATE/06_agent_handoff.yml | 2 +- .github/README.md | 78 ++++---- .github/copilot-instructions.md | 3 + .github/hook.sh | 4 + .github/lib/labels.yml | 187 ++++++++---------- .github/workflows/dependency-review.yml | 1 - .github/workflows/lychee.yml | 2 +- .github/workflows/stars.yml | 20 -- .github/workflows/zsh-n.yml | 11 +- AGENTS.md | 141 +++++++++++++ CLAUDE.md | 5 + PATTERNS.md | 101 ++++++++++ decisions/0001-meta-repo-and-agents-md.md | 83 ++++++++ .../0002-zi-as-canonical-plugin-manager.md | 68 +++++++ decisions/0003-conventional-commits.md | 106 ++++++++++ renovate-config.json | 2 +- runbooks/adr.md | 55 ++++++ runbooks/labels.md | 109 ++++++++++ runbooks/org-review.md | 71 +++++++ runbooks/release.md | 131 ++++++++++++ runbooks/triage.md | 159 +++++++++++++++ 26 files changed, 1174 insertions(+), 175 deletions(-) create mode 100644 .github/copilot-instructions.md create mode 100755 .github/hook.sh delete mode 100644 .github/workflows/stars.yml create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 PATTERNS.md create mode 100644 decisions/0001-meta-repo-and-agents-md.md create mode 100644 decisions/0002-zi-as-canonical-plugin-manager.md create mode 100644 decisions/0003-conventional-commits.md create mode 100644 runbooks/adr.md create mode 100644 runbooks/labels.md create mode 100644 runbooks/org-review.md create mode 100644 runbooks/release.md create mode 100644 runbooks/triage.md diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.yml b/.github/ISSUE_TEMPLATE/01_bug_report.yml index 5230149dd..3215646d8 100644 --- a/.github/ISSUE_TEMPLATE/01_bug_report.yml +++ b/.github/ISSUE_TEMPLATE/01_bug_report.yml @@ -1,7 +1,7 @@ name: "๐Ÿž Bug report" description: File a bug report title: "[bug]: " -labels: ["bug ๐Ÿž", "triage ๐Ÿ“‘"] +labels: ["type:bug", "status:triage"] assignees: ["ss-o"] body: - type: markdown diff --git a/.github/ISSUE_TEMPLATE/02_feature_request.yml b/.github/ISSUE_TEMPLATE/02_feature_request.yml index 84d3586ef..5fcbd89b4 100644 --- a/.github/ISSUE_TEMPLATE/02_feature_request.yml +++ b/.github/ISSUE_TEMPLATE/02_feature_request.yml @@ -1,7 +1,7 @@ name: "๐Ÿ’ก Feature request" description: Suggest an idea for this project title: "[feat]: " -labels: ["feature-request ๐Ÿ’ก"] +labels: ["type:feature"] assignees: ["ss-o"] body: - type: markdown diff --git a/.github/ISSUE_TEMPLATE/03_codebase_improvement.yml b/.github/ISSUE_TEMPLATE/03_codebase_improvement.yml index 21d854c19..0a266263c 100644 --- a/.github/ISSUE_TEMPLATE/03_codebase_improvement.yml +++ b/.github/ISSUE_TEMPLATE/03_codebase_improvement.yml @@ -1,7 +1,7 @@ name: "โœจ Codebase improvement" description: Suggest a better solution for algorithms, annexes, packages, development tools, etc. title: "[dev]: " -labels: ["enhancement โœจ"] +labels: ["type:maintenance"] assignees: ["ss-o"] body: - type: textarea diff --git a/.github/ISSUE_TEMPLATE/04_documentation.yml b/.github/ISSUE_TEMPLATE/04_documentation.yml index a4febf4b7..d5b39fbb2 100644 --- a/.github/ISSUE_TEMPLATE/04_documentation.yml +++ b/.github/ISSUE_TEMPLATE/04_documentation.yml @@ -1,7 +1,7 @@ name: "๐Ÿ“š Documentation" description: The issue request for changes in documentation title: "[docs]: " -labels: ["documentation ๐Ÿ“"] +labels: ["type:docs", "area:docs"] assignees: ["ss-o"] body: - type: markdown diff --git a/.github/ISSUE_TEMPLATE/05_membership.yml b/.github/ISSUE_TEMPLATE/05_membership.yml index 40de199ce..b574ea80f 100644 --- a/.github/ISSUE_TEMPLATE/05_membership.yml +++ b/.github/ISSUE_TEMPLATE/05_membership.yml @@ -1,6 +1,6 @@ name: "๐Ÿ‘ฅ Community Membership Request" description: Request memeber privileges -labels: ["๐Ÿ‘ฅ member"] +labels: ["type:membership", "area:meta"] title: "team: " body: diff --git a/.github/ISSUE_TEMPLATE/06_agent_handoff.yml b/.github/ISSUE_TEMPLATE/06_agent_handoff.yml index eacfb0027..7f0c129e0 100644 --- a/.github/ISSUE_TEMPLATE/06_agent_handoff.yml +++ b/.github/ISSUE_TEMPLATE/06_agent_handoff.yml @@ -1,7 +1,7 @@ name: "๐Ÿง  Agent handoff" description: Record cross-agent progress, blockers, and next steps for active or deferred work. title: "[handoff]: " -labels: ["maintenance ๐Ÿ“ˆ", "triage ๐Ÿ“‘", "agent-memory ๐Ÿง "] +labels: ["type:handoff", "area:meta"] assignees: ["ss-o"] body: - type: markdown diff --git a/.github/README.md b/.github/README.md index 88cc4f9fc..bc3b53246 100644 --- a/.github/README.md +++ b/.github/README.md @@ -39,6 +39,10 @@ The `.github` repository is a [special GitHub repository](https://docs.github.co | Path | Purpose | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| [`AGENTS.md`](../AGENTS.md) | Canonical org-wide instructions for AI coding agents and maintainers | +| [`PATTERNS.md`](../PATTERNS.md) | Cross-repo implementation idioms grounded in real repositories | +| [`decisions/`](../decisions/) | Architectural decision records for non-obvious org-wide choices | +| [`runbooks/`](../runbooks/) | Repeatable operational workflows such as org review, triage, ADR drafting, and release coordination | | [`profile/`](../profile/) | Organization profile โ€” the README and visual assets displayed on the [org page](https://github.com/z-shell) | | [`actions/`](../actions/) | Reusable composite GitHub Actions shared across all org repositories | | [`workflow-templates/`](../workflow-templates/) | Starter workflow templates available in the **Actions > New workflow** tab | @@ -49,40 +53,33 @@ The `.github` repository is a [special GitHub repository](https://docs.github.co These files in `.github/` act as **organization-wide defaults** โ€” automatically used by any repository that doesn't have its own version: -| File | Purpose | -| ------------------------------------------------ | ------------------------------------------------------------- | -| [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Contributor Covenant code of conduct | -| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contribution guidelines and requirements | -| [`SECURITY.md`](SECURITY.md) | Security vulnerability reporting policy | -| [`GOVERNANCE.md`](GOVERNANCE.md) | Project governance roles and decision-making | -| [`CHARTER.md`](CHARTER.md) | Organizational charter and mission | -| [`STEERING_COMMITTEE.md`](STEERING_COMMITTEE.md) | Steering committee membership | -| [`MAINTAINERS.md`](MAINTAINERS.md) | Project maintainer list | -| [`AGENT_MEMORY.md`](AGENT_MEMORY.md) | Cross-agent handoff and progress-tracking protocol | -| [`TRADEMARKS.md`](TRADEMARKS.md) | Trademark usage policy | -| [`ANTITRUST.md`](ANTITRUST.md) | Antitrust compliance policy | -| [`ISSUE_TEMPLATE/`](ISSUE_TEMPLATE/) | Default issue forms (bug reports, features, docs, membership) | -| [`DISCUSSION_TEMPLATE/`](DISCUSSION_TEMPLATE/) | Default discussion category forms | +| File | Purpose | +| ---------------------------------------------------- | ------------------------------------------------------------- | +| [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Contributor Covenant code of conduct | +| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contribution guidelines and requirements | +| [`SECURITY.md`](SECURITY.md) | Security vulnerability reporting policy | +| [`GOVERNANCE.md`](GOVERNANCE.md) | Project governance roles and decision-making | +| [`CHARTER.md`](CHARTER.md) | Organizational charter and mission | +| [`STEERING_COMMITTEE.md`](STEERING_COMMITTEE.md) | Steering committee membership | +| [`MAINTAINERS.md`](MAINTAINERS.md) | Project maintainer list | +| [`AGENT_MEMORY.md`](AGENT_MEMORY.md) | Cross-agent handoff and progress-tracking protocol | +| [`copilot-instructions.md`](copilot-instructions.md) | Copilot entry point that defers to the canonical `AGENTS.md` | +| [`TRADEMARKS.md`](TRADEMARKS.md) | Trademark usage policy | +| [`ANTITRUST.md`](ANTITRUST.md) | Antitrust compliance policy | +| [`ISSUE_TEMPLATE/`](ISSUE_TEMPLATE/) | Default issue forms (bug reports, features, docs, membership) | +| [`DISCUSSION_TEMPLATE/`](DISCUSSION_TEMPLATE/) | Default discussion category forms | --- ## Shared Actions -Composite actions available to all repositories via `z-shell/.github/actions/`: - -| Action | Description | -| ----------------------------------------------------------- | ---------------------------------- | -| [`setup-zsh`](../actions/setup-zsh) | Set up Zsh environment for CI | -| [`setup-zsh-development`](../actions/setup-zsh-development) | Set up Zsh development environment | -| [`build-zpmod-module`](../actions/build-zpmod-module) | Build the Zpmod Zsh module | -| [`test-zpmod-module`](../actions/test-zpmod-module) | Test the Zpmod module | -| [`test-zsh-module`](../actions/test-zsh-module) | Test Zsh modules | -| [`commit`](../actions/commit) | Automated commit action | -| [`rebase`](../actions/rebase) | Automated rebase action | -| [`mirror`](../actions/mirror) | Repository mirroring | -| [`rclone`](../actions/rclone) | File sync with rclone | -| [`determine-branch`](../actions/determine-branch) | Determine target branch | -| [`verify-pr-labels`](../actions/verify-pr-labels) | Verify PR label compliance | +Composite actions currently available to all repositories via `z-shell/.github/actions/`: + +| Action | Description | +| ----------------------------------- | --------------------------- | +| [`setup-zsh`](../actions/setup-zsh) | Set up Zsh for CI workflows | +| [`commit`](../actions/commit) | Commit generated changes | +| [`rclone`](../actions/rclone) | Sync files with rclone | **Usage example:** @@ -95,16 +92,15 @@ steps: Starter workflows available in every org repository under **Actions > New workflow**: -| Template | Description | -| ---------------- | ---------------------------- | -| Commit Action | Automated commit workflow | -| Rebase Action | PR auto-rebase workflow | -| Lock Action | Issue/PR auto-lock | -| Stale Action | Stale issue management | -| Trunk | Trunk.io linting integration | -| Sync Labels | Label synchronization | -| Verify PR Labels | PR label validation | -| Rclone Action | File sync with rclone | +| Template | Description | +| ------------- | --------------------------- | +| Trunk | Trunk code-quality workflow | +| Zsh CI | Starter Zsh CI workflow | +| Rclone Action | File sync with rclone | + +Label definitions live in [`./lib/labels.yml`](lib/labels.yml) and should be applied through org maintenance scripts or API-driven automation, not via a generic starter workflow template. + +Tracker and project automation should be configured at the project or owning-repository level, then documented here when it becomes a shared org convention. ## Renovate @@ -124,7 +120,11 @@ Shared [Renovate](https://docs.renovatebot.com/) preset for automated dependency This repository is the right place for any **organization-level** configuration: - **Adding a new default issue/PR template** โ€” add it to `.github/ISSUE_TEMPLATE/` +- **Updating agent instructions, ADRs, runbooks, or patterns** โ€” edit `AGENTS.md`, `decisions/`, `runbooks/`, or `PATTERNS.md` +- **Defining weekly review, ADR, or release coordination workflows** โ€” add or update the relevant file under `runbooks/` - **Recording cross-agent progress** โ€” follow `.github/AGENT_MEMORY.md` and keep active state in issues, PRs, and the Z-Shell Tracker +- **Updating the shared label set** โ€” edit `.github/lib/labels.yml` and roll it out via the org's maintenance automation +- **Cleaning legacy labels** โ€” follow `../runbooks/labels.md` before deleting labels from live repositories - **Creating a reusable CI action** โ€” add a composite action under `actions//action.yml` - **Providing a starter workflow** โ€” add `.yml` + `.properties.json` to `workflow-templates/` - **Updating the organization profile** โ€” edit `profile/README.md` or add assets to `profile/img/` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..176e521fb --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,3 @@ +Follow the canonical instructions in [`../AGENTS.md`](../AGENTS.md). + +For shared progress and handoffs, also follow [`AGENT_MEMORY.md`](AGENT_MEMORY.md). diff --git a/.github/hook.sh b/.github/hook.sh new file mode 100755 index 000000000..0b981ed0f --- /dev/null +++ b/.github/hook.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env sh +set -eu + +trunk check --show-existing --no-progress diff --git a/.github/lib/labels.yml b/.github/lib/labels.yml index af9079d3e..df9f8e2ab 100644 --- a/.github/lib/labels.yml +++ b/.github/lib/labels.yml @@ -1,117 +1,94 @@ --- -- name: "breaking-change ๐Ÿ’ฅ" - color: d93f0b - description: "A change that changes the API or breaks backward compatibility for users." -- name: "bug ๐Ÿž" +# Canonical organization label definitions. +# Apply these through gh/API-based maintenance automation rather than a starter workflow template. +- name: "type:bug" color: b60205 - description: "Inconsistencies or issues which will cause a problem for users or implementors." -- name: "documentation ๐Ÿ“" - color: 0052cc - description: "Solely about the documentation of the project." -- name: "i18n ๐ŸŒ" - color: "0052cc" - description: "Internationalization" -- name: "l10n ๐Ÿ—ฃ" - color: "0052cc" - description: "Localization" -- name: "enhancement โœจ" - color: 006b75 - description: "Enhancement of the code, not introducing new features." -- name: "refactor โ™ป๏ธ" - color: 006b75 - description: "Simplified code that is easier to understand or more efficient syntax or methods." -- name: "performance ๐Ÿš€" - color: 1d76db - description: "Improving performance of the project, not introducing new features." -- name: "new-feature ๐ŸŽ‰" + description: "Something is broken or behaving incorrectly." +- name: "type:feature" color: 0e8a16 - description: "Introduces new feature" -- name: "security ๐Ÿ›ก๏ธ" - color: ee0701 - description: "Addressing a vulnerability or security risk in this project." -- name: "maintenance ๐Ÿ“ˆ" - color: 531999 - description: "Generic maintenance tasks." -- name: "agent-memory ๐Ÿง " + description: "A request for new behavior or capability." +- name: "type:docs" + color: 0052cc + description: "Documentation-only work." +- name: "type:question" + color: d4c5f9 + description: "Support, clarification, or usage question." +- name: "type:maintenance" color: 531999 - description: "Cross-agent handoffs, blockers, and resumable progress context." -- name: "ci ๐Ÿค–" + description: "Non-feature maintenance, cleanup, or org work." +- name: "type:membership" + color: 6f42c1 + description: "Membership and organization-role requests." +- name: "type:handoff" color: 5319e7 - description: "Work that improves the continuous integration." -- name: "dependencies ๐Ÿ“ฆ" - color: fbca04 - description: "Change in project Javascript dependencies." -- name: "javascript ๐Ÿ“ฆ" - color: fbca04 - description: "Change in project dependencies." -- name: "submodules โš™๏ธ" - color: fbca04 - description: "Change in project dependencies." -- name: "github-actions :octocat:" - color: 5319E7 - description: "GitHub Actions" + description: "Cross-agent or cross-maintainer handoff context." -- name: "fix โšก" - color: f510f4 - description: "Has been fixed and is therefore considered resolved." -- name: "triage ๐Ÿ“‘" +- name: "area:zi" + color: 1d76db + description: "Zi core behavior, APIs, or documentation." +- name: "area:plugin" + color: 3e16f3 + description: "Plugin behavior or plugin-facing work." +- name: "area:annex" + color: 3e16f3 + description: "Annex behavior or annex-facing work." +- name: "area:package" + color: 3e16f3 + description: "Package or package-management work." +- name: "area:docs" + color: 0052cc + description: "Documentation systems, content, or publishing." +- name: "area:ci" + color: 5319e7 + description: "Continuous integration or GitHub Actions work." +- name: "area:dependencies" color: fbca04 - description: "The issue is awaiting investigation." -- name: "stale ๐Ÿ‘ป" - color: ffffff - description: "No activity for quite some time." -- name: "no-stale ๐Ÿ”’" - color: fef2c0 - description: "This is exempt from the stale bot" - -- name: "Q&A โœ๏ธ" - color: fef2c0 - description: "Questions and answers." -- name: "Poll ๐Ÿ’Œ" - color: fef2c0 - description: "Community vote" -- name: "invalid โš ๏ธ" - color: 0b467f - description: "This is off-topic or incorrect." -- name: "beginner-friendly" - color: 5319E7 - description: "Beginner friendy to people wanting to contribute to this project." -- name: "good first issue" - color: 5319E7 - description: "Good first issue for people wanting to contribute to this project." -- name: "help-wanted" - color: 5319E7 - description: "We need some extra helping hands or expertise in order to resolve this!" -- name: "feature-request ๐Ÿ’ก" - color: 0e8a16 - description: "Suggests new feature." -- name: "locked โ€ผ๏ธ" + description: "Dependency updates or dependency-management work." +- name: "area:release" color: d93f0b - description: "Spam, inappropriate or otherwise doesn't apply to this project." -- name: "resolved โ˜‘๏ธ" - color: 0e8a16 - description: "The issue has been fixed and is therefore considered resolved." -- name: "high-priority ๐Ÿ”ฅ" + description: "Release process, versioning, or changelog work." +- name: "area:meta" + color: 1d76db + description: "Organization-wide policy, templates, or meta-repo work." + +- name: "priority:high" color: ee0701 - description: "Must be addressed as soon as possible." -- name: "priority-low ๐Ÿ”–" + description: "Needs prompt attention." +- name: "regression" + color: b60205 + description: "Previously working behavior is broken." +- name: "security" + color: ee0701 + description: "Security-sensitive issue or hardening work." +- name: "breaking-change" + color: d93f0b + description: "Breaks backward compatibility or changes a public contract." + +- name: "status:triage" + color: fbca04 + description: "Awaiting initial review or classification." +- name: "status:blocked" + color: e4e669 + description: "Cannot proceed until an external dependency or decision changes." +- name: "needs-info" + color: f9d0c4 + description: "Waiting on more detail before work can continue." +- name: "good first issue" + color: 7057ff + description: "Well-scoped starter task for a new contributor." +- name: "help wanted" + color: 008672 + description: "Maintainers would welcome outside help." +- name: "invalid" + color: 0b467f + description: "Off-topic, incorrect, or not actionable." +- name: "duplicate" + color: cfd3d7 + description: "Covered by another issue or pull request." +- name: "wontfix" color: ffffff - description: "This issue currently can't be resolved." + description: "Acknowledged but not planned for implementation." -- name: "annex ๐ŸŒ€" - color: 3e16f3 - description: "Related with annex" -- name: "plugin โš™๏ธ" - color: 3e16f3 - description: "Related with plugin" -- name: "package ๐Ÿ“ฆ" - color: 3e16f3 - description: "Related with package" -- name: "major ๐Ÿ”บ" - color: b60205 - description: "This PR causes a major bump in the version number." -- name: "minor ๐Ÿ”ธ" - color: 5319e7 - description: "This PR causes a minor bump in the version number." -- name: "misc โฌฃ" +- name: "meta:org-tracked" color: 5319e7 + description: "Auto-add this issue to the org-wide Z-Shell Tracker." diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml index 794dfa2d6..f5ec9ef58 100644 --- a/.github/workflows/dependency-review.yml +++ b/.github/workflows/dependency-review.yml @@ -2,7 +2,6 @@ name: "๐Ÿ“ฆ Dependency Review" on: - pull_request: {} workflow_call: {} permissions: diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index b205daf3f..e582e0280 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -65,5 +65,5 @@ jobs: with: title: " ๐Ÿ“ข Link Checker Report" content-filepath: ./.github/LINKS_REPORT.md - labels: maintenance ๐Ÿ“ˆ + labels: "type:maintenance" issue-number: 102 diff --git a/.github/workflows/stars.yml b/.github/workflows/stars.yml deleted file mode 100644 index a44c7b37a..000000000 --- a/.github/workflows/stars.yml +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: "โญ Star" -on: - watch: - types: [started] - -jobs: - star: - runs-on: ubuntu-latest - if: github.repository == 'z-shell/.github' - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 - - run: | - echo -e "\nA :star: from [@${{github.actor}}](https://github.com/${{github.actor}})" >> .github/stars.md - - uses: z-shell/.github/actions/commit@main - env: - GITHUB_TOKEN: ${{ github.token }} - PUSH_BRANCH: "main" - with: - commitMessage: "Repository star" diff --git a/.github/workflows/zsh-n.yml b/.github/workflows/zsh-n.yml index 0995718fd..a2662b04c 100644 --- a/.github/workflows/zsh-n.yml +++ b/.github/workflows/zsh-n.yml @@ -13,6 +13,13 @@ on: - "functions/.*" workflow_dispatch: {} +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + jobs: zsh-matrix: runs-on: ubuntu-latest @@ -20,7 +27,7 @@ jobs: matrix: ${{ steps.set-matrix.outputs.matrix }} steps: - name: โคต๏ธ Check out code from GitHub - uses: actions/checkout@v4.2.2 + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - name: "โšก Set matrix output" id: set-matrix run: | @@ -35,7 +42,7 @@ jobs: matrix: ${{ fromJSON(needs.zsh-matrix.outputs.matrix) }} steps: - name: โคต๏ธ Check out code from GitHub - uses: actions/checkout@v4.2.2 + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - name: "โšก Install dependencies" run: sudo apt update && sudo apt-get install -yq zsh - name: "โšก zsh -n: ${{ matrix.file }}" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..cc0d68fb2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,141 @@ +# Agent instructions โ€” z-shell + +This file is the canonical instruction set for AI coding agents working in the z-shell organization. Read it before doing non-trivial work. If repository-local instructions conflict with this file, follow the repo-local file for repo-specific detail and raise the mismatch in an issue or handoff. + +This file is intentionally short. It complements, not replaces: + +- `.github/AGENT_MEMORY.md` for GitHub-native handoffs and shared progress +- `PATTERNS.md` for cross-repo implementation idioms +- `decisions/` for ADRs and durable architectural choices +- `runbooks/` for repeatable operational workflows + +## What z-shell is + +z-shell is an ecosystem of tools, plugins, annexes, modules, and documentation centered on Zsh and the `zi` plugin manager. + +The broad shapes are: + +1. **`zi`** โ€” the canonical plugin manager for the ecosystem +2. **Annexes** (`z-a-*`) โ€” extensions that target `zi` +3. **Plugins** (`zsh-*`) โ€” end-user features, preferably plugin-manager-agnostic where practical +4. **Modules and libraries** โ€” lower-level building blocks such as `zredis` +5. **Documentation and org infrastructure** โ€” `wiki`, `.github`, CI, templates, and shared policy + +## Sources of truth + +Use the right home for each kind of knowledge: + +| Kind of information | Source of truth | +| ---------------------------------- | ----------------------------------------------------- | +| Active work, blockers, next steps | GitHub issues, pull requests, and the Z-Shell Tracker | +| Durable architectural decisions | `decisions/` in this repo | +| Cross-repo operational procedures | `runbooks/` in this repo | +| Reusable implementation idioms | `PATTERNS.md` in this repo | +| Long-form user and maintainer docs | `wiki/` where practical | +| Local LLM memory | Optional cache only, never the only record | + +For handoffs, follow `.github/AGENT_MEMORY.md`. + +## Core objective for AI assistants + +When working in z-shell repositories, optimize for: + +1. **Better context** โ€” read the relevant issues, PRs, tracker items, ADRs, patterns, and repo instructions first +2. **Better reuse** โ€” prefer existing org patterns, shared workflows, and established helper scripts over one-off inventions +3. **Better verification** โ€” run the repo's existing checks when code changes or behavior changes +4. **Better durability** โ€” turn non-trivial deferred work and learnings into issues, PR notes, ADRs, runbook updates, or pattern proposals + +## Conventions + +- **Language:** Zsh-first. Bash-only constructs are bugs in Zsh code unless the file is explicitly POSIX `sh`. +- **Naming:** plugins use `zsh-`, annexes use `z-a-`, modules keep short descriptive names. +- **Canonical plugin manager:** `zi`. See `decisions/0002-zi-as-canonical-plugin-manager.md`. +- **Commits and PR titles:** Conventional Commits. See `decisions/0003-conventional-commits.md`. +- **Documentation placement:** keep long-form docs in the wiki when practical; keep repo-local docs focused on policy, workflow, and source-adjacent guidance. +- **Workflow files:** follow the org workflow conventions and keep permissions explicit, actions pinned, and concurrency defined. + +## Before editing + +1. Read this file, then any repo-local `AGENTS.md` or `.github/copilot-instructions.md`. +2. Search the owning repository for open issues and pull requests related to the task. +3. Check linked tracker items and previous handoff comments. +4. Read the relevant ADRs, patterns, and runbooks. +5. For cross-repo questions, search the organization before assuming the local repo is unique. +6. If no issue exists for non-trivial planned work, create one in the owning repository. + +## While editing + +- Match the nearest established pattern instead of introducing a new local style. +- Keep changes reviewable and scoped; separate mechanical cleanup from behavioral change. +- Update nearby docs, templates, or runbooks when your change makes them inaccurate. +- Avoid creating a second conflicting source of truth. Extend the canonical file instead. + +## Before claiming done + +- Run the repo's existing checks when the change affects behavior, CI, workflows, or generated outputs. +- For documentation-only edits, at minimum make sure links, paths, and examples are internally consistent. +- If work is unfinished, blocked, or likely to be resumed later, leave an `Agent handoff` comment using `.github/AGENT_MEMORY.md`. +- Convert deferred follow-up work into issues instead of leaving it only in local notes. + +## Triage and prioritization + +Use `runbooks/triage.md` for the full process. + +Short version: + +- Classify issues by work type, area, and severity. +- Use the canonical labels from `.github/lib/labels.yml`. +- Search for prior art across the org before responding. +- Put cross-repo, release-blocking, security, or strategic work on the Z-Shell Tracker. + +## Draft-only workflows + +For recurring organization workflows, prefer the runbooks and keep the first pass non-destructive: + +- weekly org review: `runbooks/org-review.md` +- issue and PR triage: `runbooks/triage.md` +- label maintenance: `runbooks/labels.md` +- ADR drafting: `runbooks/adr.md` +- release coordination and release-model classification: `runbooks/release.md` + +Unless a maintainer asks otherwise, these workflows produce drafts only. + +## Security + +- Never print, commit, or hand off secrets, tokens, or personal data. +- Never commit `.env*` files other than placeholders such as `.env.example`. +- Do not add network activity to plugin load paths unless it is an explicit user action. +- Treat all user-supplied shell input as untrusted. + +## PR conventions + +- Prefer squash merges unless a branch genuinely needs separate commits preserved. +- Link the related issue, PR, tracker item, or ADR. +- When a PR makes or codifies a non-obvious decision, draft or update an ADR. +- For unfinished work, include an `Agent handoff` section in the PR body or issue thread. + +## Learning capture + +Non-trivial sessions should end with durable follow-up, not silent local memory. If you discover: + +- a pattern used in at least two repositories +- a decision that should be recorded +- a runbook gap +- a tooling gap + +capture it in the relevant issue, PR, or draft change to `PATTERNS.md`, `decisions/`, or `runbooks/` for human review. + +## When this file is wrong + +Do not silently work around drift. Open or update an issue in `z-shell/.github`, explain what is wrong, and link the contradicting repository state. + +## See also + +- `.github/AGENT_MEMORY.md` +- `PATTERNS.md` +- `decisions/` +- `runbooks/org-review.md` +- `runbooks/adr.md` +- `runbooks/labels.md` +- `runbooks/release.md` +- `runbooks/triage.md` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..fd7469ea2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +# Claude instructions + +The canonical instructions for this repository and the wider z-shell organization live in [AGENTS.md](AGENTS.md). + +Also follow the GitHub-native handoff workflow in [.github/AGENT_MEMORY.md](.github/AGENT_MEMORY.md). diff --git a/PATTERNS.md b/PATTERNS.md new file mode 100644 index 000000000..4f482104f --- /dev/null +++ b/PATTERNS.md @@ -0,0 +1,101 @@ +# Patterns โ€” z-shell + +This file records implementation idioms already observed in multiple z-shell repositories. It exists to reduce drift, not to invent new style rules. + +Admission rule: + +- only record patterns already present in at least two real repositories +- prefer linking to the wiki or plugin standard when a deeper explanation already exists +- supersede patterns by updating this file, not by relying on private memory + +## Plugin entry-point skeleton + +Observed in: + +- `zsh-plugins/zsh-eza/zsh-eza.plugin.zsh` +- `zsh-plugins/zsh-fancy-completions/zsh-fancy-completions.plugin.zsh` +- `zsh-plugins/z-a-meta-plugins/z-a-meta-plugins.plugin.zsh` +- `zsh-lint/zsh-lint.plugin.zsh` + +Pattern: + +1. Start `.zsh` entry files with the standard modeline. +2. Resolve `$0` via the `ZERO`-aware absolute-path pattern. +3. Keep path-sensitive initialization near the top of the file. + +```zsh +# -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*- +# vim: ft=zsh sw=2 ts=2 et + +0="${ZERO:-${${0:#$ZSH_ARGZERO}:-${(%):-%N}}}" +0="${${(M)0:#/*}:-$PWD/$0}" +``` + +Reference: + +## Register the repository directory in `Plugins` + +Observed in: + +- `zsh-plugins/zsh-eza/zsh-eza.plugin.zsh` +- `zsh-plugins/zsh-fancy-completions/zsh-fancy-completions.plugin.zsh` +- `zsh-plugins/z-a-meta-plugins/z-a-meta-plugins.plugin.zsh` + +Pattern: + +```zsh +typeset -gA Plugins +Plugins[PLUGIN_KEY]="${0:h}" +``` + +Use a stable, repo-specific key and treat the registered directory as the root for cleanup and sibling-path resolution. + +Reference: + +## Guard `fpath` additions + +Observed in: + +- `zsh-plugins/zsh-fancy-completions/zsh-fancy-completions.plugin.zsh` +- `zsh-plugins/z-a-meta-plugins/z-a-meta-plugins.plugin.zsh` +- `zsh-lint/zsh-lint.plugin.zsh` +- `zsh-plugins/zsh-eza/zsh-eza.plugin.zsh` + +Pattern: + +- add `functions/` only when the plugin manager or current shell setup has not already done so +- the common Zi-aware form is: + +```zsh +if [[ $PMSPEC != *f* ]]; then + fpath+=( "${0:h}/functions" ) +fi +``` + +- an explicit membership guard is also acceptable when the entry point must tolerate non-Zi loader paths: + +```zsh +if [[ ${fpath[(r)${0:h}/functions]} != "${0:h}/functions" ]]; then + fpath+=( "${0:h}/functions" ) +fi +``` + +Prefer the simpler Zi-aware form when the repository is clearly targeting Zi-managed loading. + +## Provide an unload function for side-effectful plugins + +Observed in: + +- `zsh-plugins/zsh-eza/zsh-eza.plugin.zsh` +- `zsh-plugins/zsh-fancy-completions/zsh-fancy-completions.plugin.zsh` + +Pattern: + +- provide `_plugin_unload` +- remove `fpath` additions +- undo hooks, widgets, aliases, and globals +- self-destruct with `unfunction` + +This keeps plugin behavior reversible and makes side effects explicit. + +Reference: diff --git a/decisions/0001-meta-repo-and-agents-md.md b/decisions/0001-meta-repo-and-agents-md.md new file mode 100644 index 000000000..ed18bb266 --- /dev/null +++ b/decisions/0001-meta-repo-and-agents-md.md @@ -0,0 +1,83 @@ +# 1. Adopt a meta-repo pattern centered on `AGENTS.md` + +- **Status:** PROPOSED +- **Date:** 2026-05-19 +- **Deciders:** TBD +- **Supersedes:** None +- **Superseded by:** None + +## Context + +The z-shell organization spans many repositories with a small maintainer group responsible for triage, releases, documentation, templates, workflows, and cross-repo coordination. + +Until now, conventions and decisions have been split across: + +- individual repository READMEs +- commit history and pull-request context +- GitHub Discussions and issues +- local LLM memory and ad hoc prompts + +That creates predictable failure modes: + +- cross-repo conventions drift +- new maintainers and LLM agents re-derive the same answers +- recurring workflows are executed differently each time +- org-level changes fan out slowly and inconsistently + +At the same time, `AGENTS.md` has emerged as a common cross-tool entry point for coding-agent instructions, while GitHub-native files in `.github` already serve as the default organization health and workflow hub. + +## Decision + +Adopt `z-shell/.github` as the canonical meta-repository for organization-wide agent instructions, ADRs, runbooks, patterns, templates, and shared GitHub workflow assets. + +The top-level structure is: + +```text +AGENTS.md canonical org-wide agent instructions +CLAUDE.md thin Claude entry point to AGENTS.md +PATTERNS.md cross-repo implementation idioms +decisions/ architectural decision records +runbooks/ repeatable operational workflows +.github/ default community files and GitHub-native workflow assets +``` + +Rules: + +- `AGENTS.md` stays short and operational. +- `decisions/` is append-only; supersede with a new ADR instead of rewriting history. +- `PATTERNS.md` records only patterns already observed in at least two repositories. +- `runbooks/` must be executable, not aspirational. +- Active progress lives in issues, PRs, and the tracker, per `.github/AGENT_MEMORY.md`. + +## Consequences + +### Positive + +- One canonical place for "how this org works" +- Shared entry point for human maintainers and AI coding agents +- Better cross-repo consistency for workflows, templates, and decisions +- Reviewable, versioned institutional memory + +### Negative / costs + +- Initial migration and curation effort +- Ongoing discipline required to keep docs current +- Risk of drift if files become aspirational instead of grounded in real work + +### Neutral + +- Repository-specific instructions can still exist where the local workflow is meaningfully different. +- Long-form user documentation still belongs in the wiki where practical. + +## Alternatives considered + +1. **Status quo:** rejected because conventions and context already drift. +2. **Wiki-only governance:** rejected because ADRs, templates, and agent instructions benefit from pull-request review and repo-local discoverability. +3. **Per-repo-only instructions:** rejected because org-level guidance would be duplicated across many repositories. +4. **One giant file for everything:** rejected because decisions, runbooks, and patterns evolve differently and should not be mixed. + +## References + +- `AGENTS.md` +- `.github/AGENT_MEMORY.md` +- `PATTERNS.md` diff --git a/decisions/0002-zi-as-canonical-plugin-manager.md b/decisions/0002-zi-as-canonical-plugin-manager.md new file mode 100644 index 000000000..6ddb7ec00 --- /dev/null +++ b/decisions/0002-zi-as-canonical-plugin-manager.md @@ -0,0 +1,68 @@ +# 2. `zi` is the canonical plugin manager for the z-shell ecosystem + +- **Status:** PROPOSED +- **Date:** 2026-05-19 +- **Deciders:** TBD +- **Supersedes:** None +- **Superseded by:** None + +## Context + +The z-shell organization contains several kinds of repositories: + +- `zi` itself +- annexes that extend `zi` +- plugins that are commonly loaded through `zi` +- modules and shell libraries +- documentation and org-infrastructure repositories + +This relationship is already visible in code, examples, naming, and maintenance practice, but it has not been stated clearly in a durable decision record. + +That ambiguity hurts: + +- contributor onboarding +- documentation consistency +- LLM-assisted maintenance +- breaking-change coordination when `zi` changes behavior + +## Decision + +`zi` is the canonical plugin manager for the z-shell ecosystem. + +Specifically: + +1. **Annexes** target `zi` directly and may depend on `zi` internals. +2. **Plugins** should remain plugin-manager-agnostic where practical, but `zi` is the reference manager for examples, testing, and documentation. +3. **Cross-manager compatibility** is welcome when it does not compromise `zi`-first behavior. +4. **Breaking changes in `zi`** must be reviewed against in-org consumers before release. +5. **Org documentation** should lead with `zi` examples unless a document is explicitly about cross-manager comparison. + +## Consequences + +### Positive + +- Clear answer to "which plugin manager should I assume?" +- Annexes can rely on `zi` intentionally rather than implicitly +- Cross-repo change analysis becomes more tractable +- Default docs and examples become consistent + +### Negative / costs + +- Some users of other plugin managers may see the org as more opinionated. +- The ecosystem becomes more tightly coupled to `zi` as the load-bearing center. + +### Neutral + +- This does not require removing cross-manager support from compatible plugins. +- This ADR documents an existing reality more than it changes behavior. + +## Alternatives considered + +1. **No preferred plugin manager:** rejected because it diffuses maintenance and testing effort. +2. **Multiple co-equal canonical managers:** rejected because the org does not maintain a second equivalent center. +3. **Leave it implicit:** rejected because the ambiguity is the problem. + +## References + +- `https://github.com/z-shell/zi` +- `AGENTS.md` diff --git a/decisions/0003-conventional-commits.md b/decisions/0003-conventional-commits.md new file mode 100644 index 000000000..df76d9d2b --- /dev/null +++ b/decisions/0003-conventional-commits.md @@ -0,0 +1,106 @@ +# 3. Adopt Conventional Commits across z-shell repositories + +- **Status:** PROPOSED +- **Date:** 2026-05-19 +- **Deciders:** TBD +- **Supersedes:** None +- **Superseded by:** None + +## Context + +The organization maintains many repositories with inconsistent commit-message and pull-request title styles. + +That inconsistency makes several jobs harder: + +- release-note generation +- cross-repo impact analysis +- review of what changed since a tag or milestone +- consistent machine-readable history for tooling and LLM agents + +Conventional Commits is a widely supported standard that solves the history-format problem. Release automation can then be layered on selectively where it genuinely fits the repository's publication model. + +## Decision + +Adopt Conventional Commits as the canonical commit-message and PR-title format across z-shell repositories. + +Recommended form: + +```text +(): +``` + +Allowed types: + +- `feat` +- `fix` +- `docs` +- `chore` +- `refactor` +- `test` +- `build` +- `ci` +- `perf` +- `style` +- `revert` + +`scope` is optional but encouraged in larger repositories such as `zi`. + +Breaking changes use either: + +```text +feat!: change the public behavior +``` + +or: + +```text +feat(scope): change the public behavior + +BREAKING CHANGE: explanation +``` + +## Release automation policy + +Conventional Commits is org-wide. Release automation is **repo-type-aware**, not universal. + +- **Versioned tools and packages** may adopt release automation such as `release-please` when semantic tags are the publication boundary. +- **Continuously deployed repositories** such as hosted docs or images should keep deployment and release policy aligned with their existing delivery model instead of forcing tag-driven release tooling. +- **Meta and infrastructure repositories** such as `.github` should adopt Conventional Commits for history quality, but should not add release automation unless they gain a user-facing packaged artifact that benefits from it. + +## Rollout + +1. Pilot Conventional Commits enforcement in active repositories where maintainers want cleaner history immediately. +2. Pilot release automation only in repositories whose release model benefits from semantic tags and generated changelogs. +3. Expand incrementally as repositories are actively maintained. +4. Do not churn quiet, stable repositories just to standardize tooling. + +## Consequences + +### Positive + +- Consistent, machine-readable history across the organization +- Easier changelog, release, and cross-repo analysis +- Better guidance for contributors and LLM agents +- Release automation can be introduced where it creates real leverage + +### Negative / costs + +- Contributors need to learn a small formatting convention. +- PR-title validation may initially feel stricter than the current workflow. +- Selective automation requires maintainers to classify repositories by release model instead of assuming one size fits all. + +### Neutral + +- This does not rewrite history. +- This does not require every repository to adopt release automation. + +## Alternatives considered + +1. **Status quo:** rejected because inconsistent history is already a maintenance cost. +2. **Conventional Commits plus universal release automation:** rejected because not every z-shell repository releases via semantic tags. +3. **Custom commit convention:** rejected because Conventional Commits has the best ecosystem support. + +## References + +- +- `AGENTS.md` diff --git a/renovate-config.json b/renovate-config.json index d4c80a0e5..780913b2b 100644 --- a/renovate-config.json +++ b/renovate-config.json @@ -37,5 +37,5 @@ "dependencyDashboardHeader": "[Z-Shell](https://www.zshell.dev) | [Renovate Preset](https://github.com/z-shell/.github/blob/main/renovate-config.json)", "assigneesFromCodeOwners": true, "postUpdateOptions": ["npmDedupe", "pnpmDedupe", "yarnDedupeHighest"], - "labels": ["renovate ๐Ÿ“ฆ"] + "labels": ["type:maintenance", "area:dependencies"] } diff --git a/runbooks/adr.md b/runbooks/adr.md new file mode 100644 index 000000000..4348aaf9a --- /dev/null +++ b/runbooks/adr.md @@ -0,0 +1,55 @@ +# Runbook โ€” ADR drafting + +Use this workflow when a discussion, issue, or pull request makes a non-obvious decision that should become durable project memory. + +**Hard rule:** draft the ADR, but do not silently mark it accepted. New ADRs start as `PROPOSED` until maintainers confirm them. + +## When to use this + +Draft an ADR when: + +- a cross-repo policy changes +- a release or compatibility rule becomes explicit +- maintainers choose one non-obvious architectural direction over another +- a repeated "why do we do it this way?" question needs a durable answer + +Do not create an ADR for trivia, temporary experiments, or decisions that are still purely exploratory. + +## ADR workflow + +1. Read the source discussion, issue, or PR carefully. +2. Identify the actual decision, not just the implementation details. +3. Summarize the context, decision, consequences, and alternatives. +4. Number the ADR after the highest existing file in `decisions/`. +5. Set status to `PROPOSED`. +6. Link the source issue, PR, or discussion in `References`. + +## Prompt template + +```text +Read . + +Draft an ADR for z-shell/.github/decisions/ using the existing ADR format in this repository. + +Requirements: +- summarize the real decision +- include context, decision, consequences, and alternatives +- status must be PROPOSED +- number it after the highest existing ADR + +Draft only. Do not claim it is accepted. +``` + +## ADR quality checks + +- The title states the decision plainly. +- The decision section is actionable and specific. +- The consequences section covers both upside and cost. +- The alternatives are real alternatives, not strawmen. +- The ADR explains why the decision matters to future maintainers. + +## See also + +- `decisions/` +- `runbooks/org-review.md` +- `.github/AGENT_MEMORY.md` diff --git a/runbooks/labels.md b/runbooks/labels.md new file mode 100644 index 000000000..b236495d8 --- /dev/null +++ b/runbooks/labels.md @@ -0,0 +1,109 @@ +# Runbook โ€” Label maintenance + +Use this runbook when cleaning or syncing labels across z-shell repositories. + +## Source of truth + +`.github/lib/labels.yml` is the canonical organization label set. + +Use compact namespace names: + +- `type:bug`, not `type: bug` +- `area:docs`, not `area: docs` +- `priority:high`, not `priority: high` +- `status:triage`, not `status: triage` + +The org tracker auto-add label is `meta:org-tracked`. + +## Canonical groups + +### Work type + +- `type:bug` +- `type:feature` +- `type:docs` +- `type:question` +- `type:maintenance` +- `type:membership` +- `type:handoff` + +### Area + +- `area:zi` +- `area:plugin` +- `area:annex` +- `area:package` +- `area:docs` +- `area:ci` +- `area:dependencies` +- `area:release` +- `area:meta` + +### Severity and modifiers + +- `priority:high` +- `regression` +- `security` +- `breaking-change` +- `status:triage` +- `status:blocked` +- `needs-info` +- `good first issue` +- `help wanted` +- `invalid` +- `duplicate` +- `wontfix` +- `meta:org-tracked` + +## Retire old labels + +Retire old labels only after preserving labels on open issues and pull requests. + +Common legacy labels: + +| Legacy label | Canonical label | +| -------------------------- | ------------------- | +| `bug ๐Ÿž` | `type:bug` | +| `feature-request ๐Ÿ’ก` | `type:feature` | +| `new-feature ๐ŸŽ‰` | `type:feature` | +| `documentation ๐Ÿ“` | `type:docs` | +| `Q&A โœ๏ธ` | `type:question` | +| `enhancement โœจ` | `type:maintenance` | +| `maintenance ๐Ÿ“ˆ` | `type:maintenance` | +| `agent-memory ๐Ÿง ` | `type:handoff` | +| `๐Ÿ‘ฅ member` | `type:membership` | +| `annex ๐ŸŒ€` | `area:annex` | +| `plugin โš™๏ธ` | `area:plugin` | +| `package ๐Ÿ“ฆ` | `area:package` | +| `ci ๐Ÿค–` | `area:ci` | +| `github-actions :octocat:` | `area:ci` | +| `dependencies ๐Ÿ“ฆ` | `area:dependencies` | +| `javascript ๐Ÿ“ฆ` | `area:dependencies` | +| `submodules โš™๏ธ` | `area:dependencies` | +| `high-priority ๐Ÿ”ฅ` | `priority:high` | +| `triage ๐Ÿ“‘` | `status:triage` | +| `priority-low ๐Ÿ”–` | `status:blocked` | +| `beginner-friendly` | `good first issue` | +| `help-wanted` | `help wanted` | +| `breaking-change ๐Ÿ’ฅ` | `breaking-change` | +| `security ๐Ÿ›ก๏ธ` | `security` | +| `invalid โš ๏ธ` | `invalid` | + +Also retire spaced namespace variants such as `type: bug`, `area: docs`, `priority: high`, and `status: triage`. + +## Safe cleanup order + +1. List labels in the target repository. +2. Create or update every canonical label from `.github/lib/labels.yml`. +3. For each legacy label, find open issues and pull requests using it. +4. Add the canonical replacement to each item before removing the legacy label. +5. Delete legacy labels only after they are no longer used. +6. Re-run the label list and compare it with `.github/lib/labels.yml`. + +Do not delete unknown labels in bulk. If a repository has a local label that is not obviously legacy, open or update an issue before removing it. + +## See also + +- `.github/lib/labels.yml` +- `runbooks/triage.md` +- `runbooks/org-review.md` diff --git a/runbooks/org-review.md b/runbooks/org-review.md new file mode 100644 index 000000000..e2f35f913 --- /dev/null +++ b/runbooks/org-review.md @@ -0,0 +1,71 @@ +# Runbook โ€” Weekly org review + +Use this workflow to turn organization-wide GitHub activity into a short prioritized draft for maintainers. + +**Hard rule:** this workflow produces a draft only. Do not label, comment, close, merge, or file follow-up issues automatically unless a maintainer explicitly asks for that as a separate step. + +## Goal + +Create a one-pass weekly review that answers: + +- what changed across the organization in the last 7 days +- what needs attention now +- which issues or PRs appear to be part of the same cross-repo pattern +- which follow-up items should be proposed to maintainers + +## Inputs + +- GitHub issues and pull requests across the z-shell organization +- relevant tracker items +- recent workflow failures where they materially affect maintainer priority + +## Output shape + +Return a draft with these sections: + +1. **Urgent** +2. **Needs review** +3. **Cross-repo patterns** +4. **Suggested follow-ups** + +Each item should link the source issue, PR, or workflow and explain why it matters in one sentence. + +## Review steps + +1. Summarize new issues opened in the last 7 days by repository. +2. List PRs waiting for review longer than 3 days. +3. Flag regressions, security issues, or release blockers. +4. Look for repeated symptoms or the same maintenance task across multiple repositories. +5. Suggest the smallest useful follow-up action for each important item. + +## Prompt template + +```text +Using GitHub tools, review the last 7 days across the z-shell organization. + +- summarize new issues by repository +- flag regressions, security-sensitive issues, and release blockers +- list PRs waiting for review for more than 3 days +- identify repeated patterns across repositories +- suggest a prioritized maintainer action list + +Output sections: +1. Urgent +2. Needs review +3. Cross-repo patterns +4. Suggested follow-ups + +Do not act. Draft only. +``` + +## Follow-up discipline + +- If the review suggests a non-trivial new task, propose a GitHub issue in the owning repository. +- If an item is already tracked, link it instead of duplicating it. +- If the review exposes a recurring rule or process gap, propose a `PATTERNS.md`, ADR, or runbook update. + +## See also + +- `runbooks/triage.md` +- `runbooks/adr.md` +- `.github/AGENT_MEMORY.md` diff --git a/runbooks/release.md b/runbooks/release.md new file mode 100644 index 000000000..d65203a4f --- /dev/null +++ b/runbooks/release.md @@ -0,0 +1,131 @@ +# Runbook โ€” Release coordination + +Use this runbook to decide whether a repository should adopt release automation and to coordinate releases without forcing one model onto every z-shell repository. + +## Hard rules + +1. Conventional Commits are the organization-wide history format. +2. Release automation is **repo-type-aware**, not universal. +3. Do not add `release-please` to a repository just because it exists elsewhere. + +## Repository classes + +### 1. Continuously deployed artifacts + +Examples: + +- `wiki` +- `src` +- `zd` image workflows + +Policy: + +- validate continuously on the development branch +- deploy according to the repository's existing delivery model +- do **not** force tag-driven changelog or release-please workflows onto these repositories unless the repository gains a separate packaged release artifact + +### 2. Versioned tools and packages + +Examples likely to fit: + +- `zunit` +- `zsh-lint` + +Policy: + +- use Conventional Commits +- semantic tags are the publication boundary +- these repositories are candidates for release automation such as `release-please` + +### 3. Git-consumed source repositories + +Examples likely to fit: + +- `zi` +- most plugins and annexes + +Policy: + +- use Conventional Commits for clean history and cross-repo reasoning +- keep CI focused on validation +- do **not** add release automation unless the repository later gains a separate packaged artifact or a clear tag-driven release workflow with maintainer buy-in + +### 4. Meta and infrastructure repositories + +Examples: + +- `.github` + +Policy: + +- use Conventional Commits +- no release automation unless the repository gains a user-facing packaged artifact that benefits from it + +## Suggested pilot set + +Based on the current workspace and org policy, the safest first `release-please` pilot candidates are versioned tool repositories such as: + +- `zunit` +- `zsh-lint` + +Repositories that should stay out of the first pilot: + +- `wiki` +- `.github` +- `zi` + +## Release-automation decision checklist + +Before proposing `release-please` for a repository, confirm: + +1. The repo already uses semantic tags meaningfully. +2. A generated changelog would actually help maintainers and users. +3. The repo is not primarily consumed directly from Git `main` or `next`. +4. The release boundary is deliberate and not just "whatever is currently on the default branch". +5. Maintainers want the repo to publish from tags rather than from continuous deployment. + +If any answer is "no", prefer Conventional Commits without release automation. + +## Cross-repo breaking-change workflow + +When `zi` or another core repo makes a breaking change: + +1. identify the public contract that changed +2. search the organization for in-org consumers +3. list affected repositories and the likely adaptation work +4. draft, but do not apply, follow-up issues or PRs + +## Prompt template โ€” release classification + +```text +Review z-shell/ and classify its release model using the z-shell release runbook. + +Answer: +1. Which repository class does it fit? +2. Should it use Conventional Commits only, or Conventional Commits plus release automation? +3. If release automation is appropriate, why? +4. If it is not appropriate, what is the correct publication model? + +Draft only. Do not modify workflows. +``` + +## Prompt template โ€” breaking-change coordination + +```text +Read describing a breaking change in z-shell/. + +Search the z-shell organization for likely consumers of the changed API, behavior, or workflow. + +Output: +- affected repositories +- likely impact +- proposed follow-up issue titles or PR scopes + +Draft only. Do not act. +``` + +## See also + +- `decisions/0003-conventional-commits.md` +- `runbooks/org-review.md` +- `runbooks/triage.md` diff --git a/runbooks/triage.md b/runbooks/triage.md new file mode 100644 index 000000000..515f98171 --- /dev/null +++ b/runbooks/triage.md @@ -0,0 +1,159 @@ +# Runbook โ€” Triage + +How to classify, prioritize, and respond to issues and pull requests across the z-shell organization. + +**Hard rule:** LLM agents draft; humans apply labels, post comments, and close items. + +## When triage happens + +- **New issue or PR:** within 48 hours, sooner for active repositories such as `zi` and `wiki` +- **Weekly sweep:** review anything missed during the week +- **Ad hoc:** immediately for security, regression, release-blocking, or cross-repo issues + +## Step 1 โ€” Read and classify + +For each item, answer: + +1. What kind of work is this: bug, feature, docs, question, maintenance, or meta? +2. What area does it touch: `zi`, plugin, annex, docs, CI, release, org infrastructure, or unknown? +3. Is it a real bug, a design request, or a configuration/support question? +4. Has this shown up before in this repository or elsewhere in the org? + +If classification takes more than a few minutes, mark it for investigation and move on. + +## Step 2 โ€” Apply the canonical labels + +The organization label set in `.github/lib/labels.yml` is the source of truth. Apply at least one work-type label and one area label when the area is known. + +### Work type + +| Intent | Label | +| ----------------------- | ------------------ | +| bug | `type:bug` | +| feature request | `type:feature` | +| documentation only | `type:docs` | +| maintenance or org work | `type:maintenance` | +| support or usage | `type:question` | +| membership | `type:membership` | +| agent handoff | `type:handoff` | + +### Area / shape + +| Area | Label | +| -------------------- | ------------------- | +| `zi` core | `area:zi` | +| plugin | `area:plugin` | +| annex | `area:annex` | +| package | `area:package` | +| docs | `area:docs` | +| CI or GitHub Actions | `area:ci` | +| dependencies | `area:dependencies` | +| release | `area:release` | +| org infrastructure | `area:meta` | + +### Severity / modifiers + +| Meaning | Label | +| ---------------------- | ------------------ | +| needs initial review | `status:triage` | +| blocked | `status:blocked` | +| waiting on more detail | `needs-info` | +| regression | `regression` | +| high priority | `priority:high` | +| breaking change | `breaking-change` | +| security-sensitive | `security` | +| good first issue | `good first issue` | +| help wanted | `help wanted` | +| invalid | `invalid` | +| duplicate | `duplicate` | +| not planned | `wontfix` | + +## Step 3 โ€” Cross-reference + +Before responding: + +1. Search the same repository for related closed issues or PRs. +2. Search the organization for the same symptom or pattern. +3. Check `decisions/` for relevant ADRs. +4. Check `PATTERNS.md` and the wiki when a known implementation pattern may answer the question. + +If the issue conflicts with an accepted ADR or established pattern, say so directly and link it. + +## Step 4 โ€” Draft the first response + +The first response should: + +1. acknowledge the report or PR +2. restate the issue in one sentence +3. give exactly one concrete next step + +Typical next steps: + +- reproduced and tracking +- needs more detail +- duplicate of another issue +- by design, with documentation or ADR link +- PR welcome, with guidance + +Do not promise delivery dates. + +## Step 5 โ€” Decide whether it belongs on the tracker + +Add the work to the Z-Shell Tracker when it: + +- crosses repositories +- blocks a release +- has security impact +- has strategic or roadmap significance + +Apply `meta:org-tracked` to issues that should appear on the org-wide tracker. Do not apply it to ordinary single-repository bugs, questions, or cleanup tasks. + +When the project fields exist, populate: + +- `Impact`: `low`, `medium`, or `high` +- `Effort`: `XS`, `S`, `M`, or `L` +- `Strategic value`: one short sentence explaining why the item matters beyond the source issue +- `Status`: `Triage`, `Ready`, `In Progress`, `In Review`, or `Done` + +## Step 6 โ€” Close with an explicit reason + +When closing an issue or PR, always leave the reason in the thread: + +- resolved, with the fixing PR or commit +- duplicate, with the canonical issue +- wontfix, with the reasoning and ADR link where applicable +- invalid, with a respectful explanation + +Avoid silent closures and bulk cleanup without context. + +## Special cases + +### Security reports + +Do not handle exploit details publicly. + +1. Mark the item with `security`. +2. Ask the reporter to continue privately via the security policy. +3. Remove or hide exploit details when appropriate. +4. Continue investigation off the public thread. + +### New-contributor pull requests + +- lower the friction +- be specific about requested changes +- prefer mentoring and takeover help over vague "needs work" feedback + +## Anti-patterns + +- labels with no explanation +- bulk stale closures with no human context +- demanding excessive reproduction steps for obvious bugs +- leaving `needs investigation` items to rot forever + +## See also + +- `AGENTS.md` +- `.github/AGENT_MEMORY.md` +- `PATTERNS.md` +- `decisions/` +- `runbooks/labels.md` From 49878cb3546ab826798b07fb229c74de66716ee1 Mon Sep 17 00:00:00 2001 From: Sall <59910950+ss-o@users.noreply.github.com> Date: Wed, 20 May 2026 06:15:52 +0100 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Sall <59910950+ss-o@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/05_membership.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/05_membership.yml b/.github/ISSUE_TEMPLATE/05_membership.yml index b574ea80f..748645cba 100644 --- a/.github/ISSUE_TEMPLATE/05_membership.yml +++ b/.github/ISSUE_TEMPLATE/05_membership.yml @@ -1,5 +1,5 @@ name: "๐Ÿ‘ฅ Community Membership Request" -description: Request memeber privileges +description: Request member privileges labels: ["type:membership", "area:meta"] title: "team: " From 7a27aaf591b26bc35a1cb2ccd50b95c59ba9d9c2 Mon Sep 17 00:00:00 2001 From: Sall <59910950+ss-o@users.noreply.github.com> Date: Wed, 20 May 2026 06:16:23 +0100 Subject: [PATCH 3/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Sall <59910950+ss-o@users.noreply.github.com> --- runbooks/release.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/runbooks/release.md b/runbooks/release.md index d65203a4f..9f12a7327 100644 --- a/runbooks/release.md +++ b/runbooks/release.md @@ -2,9 +2,9 @@ Use this runbook to decide whether a repository should adopt release automation and to coordinate releases without forcing one model onto every z-shell repository. -## Hard rules +## Release coordination guidance -1. Conventional Commits are the organization-wide history format. +1. Conventional Commits are the proposed default history format until the corresponding ADR is accepted. 2. Release automation is **repo-type-aware**, not universal. 3. Do not add `release-please` to a repository just because it exists elsewhere.