Z-Shell — Organization Configuration

Shared GitHub Actions, workflow templates, organization profile, and community assets.

---

About the .github Repository

The .github repository is a special GitHub repository that serves as the organization-wide configuration hub. Files placed here apply as defaults across all repositories in the Z-Shell organization, without needing to duplicate them into every individual repository.

What Makes It Special

Feature	How It Works
Organization Profile	profile/README.md is rendered on the organization's GitHub page as the public-facing profile.
Default Community Health Files	Files like CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, and GOVERNANCE.md in .github/ are used as fallbacks by any org repository that doesn't define its own.
Default Issue & PR Templates	Templates in .github/ISSUE_TEMPLATE/ and discussion forms in .github/DISCUSSION_TEMPLATE/ are inherited by repositories without their own templates.
Agent Memory Protocol	.github/AGENT_MEMORY.md defines the GitHub-native handoff workflow used to keep cross-LLM and cross-repository progress visible.
Reusable Composite Actions	The actions/ directory hosts composite actions that any org repository can reference via uses: z-shell/.github/actions/<name>@main.
Workflow Templates	The workflow-templates/ directory provides starter workflows available in every org repository under Actions > New workflow.
Shared Dependency Config	renovate-config.json defines a shared Renovate preset that org repositories can extend for consistent automated dependency updates.

Note: The .github repository must be public for default community health files to apply across the organization.

---

Repository Structure

Path	Purpose
AGENTS.md	Canonical org-wide instructions for AI coding agents and maintainers
PATTERNS.md	Cross-repo implementation idioms grounded in real repositories
decisions/	Architectural decision records for non-obvious org-wide choices
runbooks/	Repeatable operational workflows such as org review, triage, ADR drafting, and release coordination
profile/	Organization profile — the README and visual assets displayed on the org page
actions/	Reusable composite GitHub Actions shared across all org repositories
workflow-templates/	Starter workflow templates available in the Actions > New workflow tab
metrics/	Auto-generated organization metrics and analytics
renovate-config.json	Shared Renovate bot preset for dependency updates

Community Health Files

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	Contributor Covenant code of conduct
CONTRIBUTING.md	Contribution guidelines and requirements
SECURITY.md	Security vulnerability reporting policy
GOVERNANCE.md	Project governance roles and decision-making
CHARTER.md	Organizational charter and mission
STEERING_COMMITTEE.md	Steering committee membership
MAINTAINERS.md	Project maintainer list
AGENT_MEMORY.md	Cross-agent handoff and progress-tracking protocol
copilot-instructions.md	Copilot entry point that defers to the canonical AGENTS.md
TRADEMARKS.md	Trademark usage policy
ANTITRUST.md	Antitrust compliance policy
ISSUE_TEMPLATE/	Default issue forms (bug reports, features, docs, membership)
DISCUSSION_TEMPLATE/	Default discussion category forms

---

Shared Actions

Composite actions currently available to all repositories via z-shell/.github/actions/<name>:

Action	Description
setup-zsh	Set up Zsh for CI workflows
commit	Commit generated changes
rclone	Sync files with rclone

Usage example:

steps:
  - uses: z-shell/.github/actions/setup-zsh@main

Workflow Templates

Starter workflows available in every org repository under Actions > New workflow:

Template	Description
Trunk	Trunk code-quality workflow
Zsh CI	Starter Zsh CI workflow
Rclone Action	File sync with rclone
Project Tracker	Adds meta:org-tracked issues to the org-wide tracker

Label definitions live in ./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 are documented in ../runbooks/project-tracker.md. Project 28 is the org-wide tracker, and issues labelled meta:org-tracked should be added there automatically by either the Project v2 built-in workflow or the repository workflow fallback.

Renovate

Shared Renovate preset for automated dependency updates. Reference from any org repository:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["local>z-shell/.github:renovate-config"]
}

---

Common Use Cases

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
• Configuring tracker auto-add — follow ../runbooks/project-tracker.md
• 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/<name>/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/
• Changing contribution or security policies — edit the corresponding file in .github/
• Updating shared Renovate config — edit renovate-config.json

For repository-specific overrides, add the same file to that repository directly — it will take precedence over the defaults from here.

Links

• Z-Shell Organization — All repositories
• Wiki & Documentation — Guides and reference
• Discussions — Community forum
• GitHub Docs: Default Community Health Files
• GitHub Docs: Workflow Templates

---

_{Part of the Z-Shell organization}