diff --git a/.github/AGENT_MEMORY.md b/.github/AGENT_MEMORY.md new file mode 100644 index 000000000..08257eddd --- /dev/null +++ b/.github/AGENT_MEMORY.md @@ -0,0 +1,72 @@ +# Z-Shell Agent Memory Protocol + +Z-Shell uses GitHub-native records as the shared memory between humans and LLM agents. Local LLM memory is useful as a cache, but it is never the source of truth for organization progress. + +## Sources of Truth + +| State | Source of truth | +| ---------------------------------------- | ------------------------------------------------------------- | +| Active work, blockers, and next steps | GitHub issues, pull requests, and the Z-Shell Tracker project | +| Deferred or planned work | GitHub issues in the owning repository | +| Durable decisions and long-form guidance | Z-Shell wiki | +| Local agent recall | Optional cache only; must not be the only record | + +## Agent Workflow + +Before starting non-trivial work: + +1. Search the owning repository for open issues and pull requests related to the task. +2. Check linked tracker items and previous handoff comments. +3. Prefer the most recent GitHub-visible state over local notes or LLM memory. +4. If no issue exists for planned or deferred work, create one in the owning repository. + +While working: + +1. Keep progress attached to the relevant issue or pull request. +2. Update the thread when status changes materially, especially when work becomes blocked. +3. Link branches, pull requests, CI runs, and follow-up issues instead of relying on prose-only status. + +Before stopping or handing off: + +1. Leave a handoff comment on the owning issue or pull request when work is unfinished, blocked, or non-trivial. +2. Include verification that was actually run. +3. Include exact next steps that a fresh agent or maintainer can execute without guessing. +4. Convert deferred work into tracker issues instead of leaving it only in a handoff. + +## Handoff Comment Format + +Use this structure for issue and pull request comments: + +```markdown +## Agent handoff + +**Status:** In progress | Blocked | Ready for review | Complete +**Repository:** z-shell/ +**Branch/PR:** +**Tracker/Issue:** + +### Current state + +- + +### Verification + +- : + +### Blockers + +- + +### Next steps + +1. +2. +``` + +## Rules + +- Do not store secrets, credentials, private hostnames, private IP addresses, personal local paths, or machine-specific state. +- Do not create repo-local memory logs unless that repository has a specific, documented need. +- Do not use a central append-only Markdown file for active progress; it will drift and conflict. +- Keep durable documentation in the wiki and link to it from repository-local files when needed. +- Keep the tracker issue body or PR thread concise, factual, and actionable. diff --git a/.github/ISSUE_TEMPLATE/06_agent_handoff.yml b/.github/ISSUE_TEMPLATE/06_agent_handoff.yml new file mode 100644 index 000000000..eacfb0027 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/06_agent_handoff.yml @@ -0,0 +1,85 @@ +name: "🧠 Agent handoff" +description: Record cross-agent progress, blockers, and next steps for active or deferred work. +title: "[handoff]: " +labels: ["maintenance 📈", "triage 📑", "agent-memory 🧠"] +assignees: ["ss-o"] +body: + - type: markdown + attributes: + value: | + Use this only for work that needs shared context between maintainers or LLM agents. + If the work is a bug, feature, or documentation request, prefer the specific template and add the handoff details there. + - type: input + id: repository + attributes: + label: Repository + description: Owning repository for this work. + placeholder: z-shell/ + validations: + required: true + - type: input + id: branch-pr + attributes: + label: Branch or pull request + description: Branch name, pull request URL, or both. + placeholder: feature-example, https://github.com/z-shell//pull/123 + validations: + required: false + - type: dropdown + id: status + attributes: + label: Status + options: + - Planned + - In progress + - Blocked + - Ready for review + - Complete + validations: + required: true + - type: textarea + id: current-state + attributes: + label: Current state + description: What is true now? Include completed work and important decisions. + placeholder: | + - ... + validations: + required: true + - type: textarea + id: verification + attributes: + label: Verification + description: Commands, checks, CI runs, or review performed. Say "Not run" if nothing was run. + placeholder: | + - trunk check --no-fix: passed + - CI: pending + validations: + required: true + - type: textarea + id: blockers + attributes: + label: Blockers + description: Anything preventing completion. Write "None" if unblocked. + placeholder: None + validations: + required: true + - type: textarea + id: next-steps + attributes: + label: Next steps + description: Exact next actions for a fresh maintainer or agent. + placeholder: | + 1. ... + 2. ... + validations: + required: true + - type: textarea + id: links + attributes: + label: Links + description: Related issues, pull requests, tracker items, CI runs, or wiki pages. + placeholder: | + - ... + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..99bf65c86 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## Summary + +- + +## Verification + +- + +## Agent handoff + +If this PR is unfinished, blocked, or expected to be resumed by another maintainer or LLM agent, include: + +- **Status:** In progress | Blocked | Ready for review | Complete +- **Current state:** +- **Blockers:** +- **Next steps:** +- **Related tracker/issues:** + +If no handoff is needed, write: `No handoff needed.` diff --git a/.github/README.md b/.github/README.md index cfbdf8b82..88cc4f9fc 100644 --- a/.github/README.md +++ b/.github/README.md @@ -21,14 +21,15 @@ The `.github` repository is a [special GitHub repository](https://docs.github.co ### What Makes It Special -| Feature | How It Works | -| --- | --- | -| **Organization Profile** | `profile/README.md` is rendered on the [organization's GitHub page](https://github.com/z-shell) 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. | -| **Reusable Composite Actions** | The `actions/` directory hosts [composite actions](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) that any org repository can reference via `uses: z-shell/.github/actions/@main`. | -| **Workflow Templates** | The `workflow-templates/` directory provides [starter workflows](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization) available in every org repository under **Actions > New workflow**. | -| **Shared Dependency Config** | `renovate-config.json` defines a shared [Renovate](https://docs.renovatebot.com/) preset that org repositories can extend for consistent automated dependency updates. | +| Feature | How It Works | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Organization Profile** | `profile/README.md` is rendered on the [organization's GitHub page](https://github.com/z-shell) 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](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) that any org repository can reference via `uses: z-shell/.github/actions/@main`. | +| **Workflow Templates** | The `workflow-templates/` directory provides [starter workflows](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization) available in every org repository under **Actions > New workflow**. | +| **Shared Dependency Config** | `renovate-config.json` defines a shared [Renovate](https://docs.renovatebot.com/) 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. @@ -36,31 +37,32 @@ The `.github` repository is a [special GitHub repository](https://docs.github.co ## Repository Structure -| Path | Purpose | -| --- | --- | -| [`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 | -| [`metrics/`](../metrics/) | Auto-generated organization metrics and analytics | -| [`renovate-config.json`](../renovate-config.json) | Shared Renovate bot preset for dependency updates | +| Path | Purpose | +| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| [`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 | +| [`metrics/`](../metrics/) | Auto-generated organization metrics and analytics | +| [`renovate-config.json`](../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`](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 | -| [`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 | +| [`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 | --- @@ -68,19 +70,19 @@ These files in `.github/` act as **organization-wide defaults** — automaticall Composite actions available to all repositories via `z-shell/.github/actions/`: -| Action | Description | -| --- | --- | -| [`setup-zsh`](../actions/setup-zsh) | Set up Zsh environment for CI | +| 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 | +| [`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 | **Usage example:** @@ -93,16 +95,16 @@ 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 | +| ---------------- | ---------------------------- | +| 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 | ## Renovate @@ -122,6 +124,7 @@ 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/` +- **Recording cross-agent progress** — follow `.github/AGENT_MEMORY.md` and keep active state in issues, PRs, and the Z-Shell Tracker - **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/lib/labels.yml b/.github/lib/labels.yml index b687b7ddb..af9079d3e 100644 --- a/.github/lib/labels.yml +++ b/.github/lib/labels.yml @@ -32,6 +32,9 @@ - name: "maintenance 📈" color: 531999 description: "Generic maintenance tasks." +- name: "agent-memory 🧠" + color: 531999 + description: "Cross-agent handoffs, blockers, and resumable progress context." - name: "ci 🤖" color: 5319e7 description: "Work that improves the continuous integration."