z-shell · ss-o · May 19, 2026 · May 19, 2026
@@ -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/<repo>
+**Branch/PR:** <branch and/or PR link>
+**Tracker/Issue:** <issue or tracker link>
+
+### Current state
+
+- <what is true now>
+
+### Verification
+
+- <command or check>: <result>
+
+### Blockers
+
+- <blocker or "None">
+
+### Next steps
+
+1. <next concrete action>
+2. <next concrete action>
+```
+
+## 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.
@@ -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/<repo>
+    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/<repo>/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
@@ -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.`
@@ -21,66 +21,68 @@ 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/<name>@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/<name>@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.
 
 ---
 
 ## 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                             |
 
 ---
 
 ## Shared Actions
 
 Composite actions available to all repositories via `z-shell/.github/actions/<name>`:
 
-| 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/<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/`

@@ -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."