| 1 | # Sharing and Safety Guide |
| 2 | |
| 3 | This guide helps contributors decide **what to share**, **where to share it**, and **what must stay private**. |
| 4 | |
| 5 | ## Start with the decision tree |
| 6 | |
| 7 | ### 1. Is this change meant for the Agent Zero core repository? |
| 8 | |
| 9 | Use the main `agent-zero` contribution flow when the change directly improves the framework itself, for example: |
| 10 | |
| 11 | - a bugfix in `webui/`, `helpers/`, `api/`, `tools/`, `extensions/`, or `docs/` |
| 12 | - a test that belongs with core framework behavior |
| 13 | - documentation for built-in functionality |
| 14 | |
| 15 | If yes: |
| 16 | |
| 17 | 1. Fork `agent0ai/agent-zero` publicly. |
| 18 | 2. Add `upstream` to your local clone. |
| 19 | 3. Sync from `upstream/main` (or the currently used upstream target branch). |
| 20 | 4. Create a focused branch. |
| 21 | 5. Open the PR across forks. |
| 22 | |
| 23 | See [`../guides/contribution.md`](../guides/contribution.md) for the detailed workflow. |
| 24 | |
| 25 | ### 2. Is this a community plugin? |
| 26 | |
| 27 | Use a **dedicated public plugin repository** when the work is a standalone plugin that users can install independently. |
| 28 | |
| 29 | Typical signals: |
| 30 | |
| 31 | - it lives cleanly under `usr/plugins/<plugin_name>/` |
| 32 | - it has its own `plugin.yaml` |
| 33 | - it can evolve independently from the core repository |
| 34 | - it should be discoverable in the Plugin Hub |
| 35 | |
| 36 | If yes: |
| 37 | |
| 38 | 1. Put the plugin contents at the root of its own repository. |
| 39 | 2. Include `plugin.yaml`, `README.md`, and `LICENSE`. |
| 40 | 3. Test it locally from `usr/plugins/`. |
| 41 | 4. Submit its `index.yaml` entry to `agent0ai/a0-plugins`. |
| 42 | |
| 43 | See [`agent0ai/a0-plugins`](https://github.com/agent0ai/a0-plugins) for the |
| 44 | current Plugin Index rules and packaging details. |
| 45 | |
| 46 | ### 3. Is this a reusable skill? |
| 47 | |
| 48 | Use the **skills workflow** when the work is mainly procedural knowledge in `SKILL.md` form. |
| 49 | |
| 50 | Typical signals: |
| 51 | |
| 52 | - it teaches the agent how to perform a task |
| 53 | - it is portable across Agent Zero, Cursor, Claude Code, or Copilot-style ecosystems |
| 54 | - it lives naturally under `usr/skills/` during development |
| 55 | |
| 56 | If yes: |
| 57 | |
| 58 | 1. Develop it locally in `usr/skills/`. |
| 59 | 2. Validate the structure and examples. |
| 60 | 3. Move it into `skills/` for an Agent Zero contribution, or publish it in a dedicated public repository/collection. |
| 61 | |
| 62 | See [`contributing-skills.md`](contributing-skills.md) for the authoring standard. |
| 63 | |
| 64 | ### 4. Should this stay private? |
| 65 | |
| 66 | Keep the work **out of public forks and upstream PRs** when it includes any of the following: |
| 67 | |
| 68 | - credentials, tokens, API keys, `.env` files, or customer secrets |
| 69 | - local-only experiments, snapshots, or temporary branch archaeology |
| 70 | - customer-specific logic or data |
| 71 | - machine-specific configuration, caches, local virtual environments, or editor debris |
| 72 | - plugin or skill prototypes that are not ready for public review |
| 73 | |
| 74 | If yes, keep it in a private repository, in `usr/`, or outside the public contribution path entirely. |
| 75 | |
| 76 | ## Safe publication rules |
| 77 | |
| 78 | ### Public forks and pull requests |
| 79 | |
| 80 | - Use a **public, pushable fork** for any branch that may become the head branch of an upstream PR. |
| 81 | - Keep the source branch alive until the PR is merged or intentionally closed. |
| 82 | - Search open and recently closed upstream PRs before opening a new one. |
| 83 | - Choose the base branch from current upstream practice; do not hardcode `development` if active comparable PRs target `main`. |
| 84 | - Record the exact tests you ran. |
| 85 | |
| 86 | ### Allow edits from maintainers |
| 87 | |
| 88 | GitHub lets you allow maintainers to edit a branch on your fork. |
| 89 | |
| 90 | If the fork branch contains GitHub Actions workflows, GitHub may show **"Allow edits and access to secrets by maintainers"**. Treat this carefully: |
| 91 | |
| 92 | - only enable it when you are comfortable with maintainers editing workflow files on that branch |
| 93 | - do not leave sensitive values or private automation in a fork branch you plan to share publicly |
| 94 | |
| 95 | ### Files that usually do not belong in public contributions |
| 96 | |
| 97 | - `.env` |
| 98 | - `.venv/` |
| 99 | - editor settings such as `.vscode/settings.json` |
| 100 | - temporary notes, scratch files, or machine-specific backups |
| 101 | - unrelated formatting churn |
| 102 | - private reports or internal strategy docs |
| 103 | |
| 104 | ## Recommended repository model |
| 105 | |
| 106 | For teams or maintainers juggling both private R&D and public contributions, this split keeps things sane: |
| 107 | |
| 108 | 1. **Private workspace or backup repository** |
| 109 | - plugin experiments |
| 110 | - customer-specific work |
| 111 | - snapshots and branch archaeology |
| 112 | - internal notes and strategy |
| 113 | |
| 114 | 2. **Clean fix-only clone for upstream-facing work** |
| 115 | - only branches that may become public PRs |
| 116 | - synced from upstream |
| 117 | - no snapshots, no unrelated experiments |
| 118 | |
| 119 | 3. **Public fork used only for PR head branches** |
| 120 | - only focused, reviewable public branches |
| 121 | - no internal scratch branches |
| 122 | |
| 123 | ## Before you publish anything |
| 124 | |
| 125 | - Confirm the work belongs in the chosen publication path. |
| 126 | - Remove secrets and local-only artifacts. |
| 127 | - Check for overlapping upstream work. |
| 128 | - Make sure the diff is narrow and reviewer-friendly. |
| 129 | - Verify the test evidence you plan to mention. |
| 130 | - Make sure the branch source is public if it will back an upstream PR. |