docs: Organization Practices

docs/astro.config.mjs

@@ -131,6 +131,7 @@ export default defineConfig({
 		'/patterns/researchplanassignops/': '/gh-aw/patterns/research-plan-assign-ops/',
 		'/patterns/batchops/': '/gh-aw/patterns/batch-ops/',
 		'/patterns/taskops/': '/gh-aw/patterns/task-ops/',
+		'/patterns/shadowops/': '/gh-aw/organization-practices/safe-rollout/',
 		'/patterns/trialops/': '/gh-aw/patterns/trial-ops/',
 		'/patterns/workqueueops/': '/gh-aw/patterns/workqueue-ops/',
 	},
@@ -277,6 +278,14 @@ export default defineConfig({
 						{ label: 'Ephemerals', link: '/guides/ephemerals/' },
 						{ label: 'Web Search', link: '/guides/web-search/' },
 						{ label: 'Audit Reports', link: '/guides/audit-with-agents/' },
+						{
+							label: 'Organization Practices',
+							items: [
+								{ label: 'Overview', link: '/organization-practices/' },
+								{ label: 'Safe Rollout', link: '/organization-practices/safe-rollout/' },
+								{ label: 'Sharing Workflows', link: '/organization-practices/sharing-workflows/' },
+							],
+						},
 					],
 				},
 				{

docs/src/content/docs/guides/packaging-imports.mdx

@@ -7,6 +7,9 @@ sidebar:
 
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 
+> [!NOTE]
+> The workflow sharing and import model described here reflects the current state of GitHub Agentic Workflows. The recommended patterns, commands, and configuration options may change in future releases as the platform evolves.
+
 ## Adding Workflows
 
 You can add any existing workflow you have access to from external repositories.

docs/src/content/docs/organization-practices/index.mdx

@@ -0,0 +1,27 @@
+---
+title: Organization Practices
+description: Guidance for adopting, sharing, and governing agentic workflows across teams and repositories.
+---
+
+Organization Practices collects guidance that matters at team and enterprise scale such as:
+
+- Safe rollout strategies before production writes are enabled
+- Workflow sharing across repositories and organizations
+- Centralized ownership models for workflow infrastructure
+- Platform conventions for versioning, review, and promotion
+
+## Included Topics
+
+### Safe Rollout
+
+[Safe Rollout](/gh-aw/organization-practices/safe-rollout/) describes how to move from report-only or staged behavior to production writes with evidence and control. One technique inside that progression is shadow evaluation, where the workflow writes to a safe non-production target before promotion.
+
+### Sharing Workflows
+
+[Sharing Workflows](/gh-aw/organization-practices/sharing-workflows/) describes how workflows can be reused across repositories and organizations. It covers imports, reusable components, central workflow repositories, and when to use templates or starter repositories.
+
+## Relationship To Other Sections
+
+- Use [Design Patterns](/gh-aw/patterns/) to learn reusable workflow shapes.
+- Use [Guides](/gh-aw/guides/) for task-oriented instructions such as [Reusing Workflows](/gh-aw/guides/packaging-imports/).
+- Use [Reference](/gh-aw/reference/) for exact configuration syntax and field behavior.

docs/src/content/docs/organization-practices/safe-rollout.md

@@ -0,0 +1,75 @@
+---
+title: Safe Rollout
+description: Move from report-only or staged behavior to direct production writes with evidence and control.
+sidebar:
+  badge: { text: 'Rollout', variant: 'caution' }
+---
+
+Safe rollout is the practice of increasing workflow autonomy in steps instead of enabling direct production writes immediately.
+
+The main question is not whether a workflow is useful, but whether it is trusted enough to act on the live system. In practice, teams usually move through a ladder: report-only first, then staged behavior, then a more realistic safe-write technique if needed, and finally direct production writes.
+
+## Rollout Ladder
+
+The usual progression is:
+
+1. Start in report-only mode.
+2. Enable `staged` behavior when proposed writes need to be previewed.
+3. Use shadow evaluation when preview mode is not enough and the real write path needs to be exercised safely.
+4. Promote the same workflow to direct production writes.
+
+`staged` and shadow evaluation are not interchangeable. Staged mode is sufficient when the question is what the workflow would do. Shadow evaluation is needed when the question is whether the real write path behaves correctly on a safe non-production target.
+
+## When Staged Is Enough
+
+Use staged mode when the main risk is decision quality rather than operational behavior.
+
+It is usually enough when maintainers only need to review proposed actions, compare alternatives, or inspect whether the workflow's judgment is reasonable before any write is allowed.
+
+## When Shadow Evaluation Is Needed
+
+Use shadow evaluation when staged mode is too weak because the real write path itself needs validation.
+
+This is a good fit when:
+
+- the workflow must update real target objects to prove the behavior is correct
+- concurrency, deduplication, or serialization needs to be tested on a live-like surface
+- maintainers need to inspect the actual produced state, not only proposed intent
+- cross-repository writes, permissions, or dispatch boundaries need to be exercised safely
+
+Shadow evaluation is one technique inside safe rollout, not a separate top-level pattern.
+
+## Design Rules
+
+### Production truth stays authoritative
+
+Do not let the evaluation surface become the new source of truth. Production events and later trusted human actions should remain authoritative.
+
+### Prediction snapshots should be explicit
+
+If later comparison matters, persist what the workflow predicted at decision time. Do not reconstruct predictions from logs.
+
+### Correction evidence needs provenance
+
+Not every later edit should count as trustworthy truth. Record provenance such as actor type, manual versus automated source, trust status, and origin repository role.
+
+### Evaluation surfaces should remain disposable
+
+Keep the shadow target thin. It should support measurement and rollout, not become a second long-lived control plane.
+
+## Example Shape
+
+The common repository split is:
+
+- production repository: emits live events and contains authoritative later human truth
+- ops repository: persists predictions, collects corrections, publishes reports, and updates instructions
+- shadow repository: temporary non-production write target during rollout
+
+That shape is often useful, but it is still rollout guidance rather than a primary pattern.
+
+## Related Documentation
+
+- [SideRepoOps](/gh-aw/patterns/side-repo-ops/)
+- [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/)
+- [Staged Mode](/gh-aw/reference/staged-mode/)
+- [Safe Outputs Reference](/gh-aw/reference/safe-outputs/)

docs/src/content/docs/organization-practices/sharing-workflows.md

@@ -0,0 +1,140 @@
+---
+title: Sharing Workflows
+description: Share, reuse, and govern workflows across repositories and organizations.
+sidebar:
+  badge: { text: 'Platform', variant: 'tip' }
+---
+
+> [!NOTE]
+> The enterprise sharing model described here reflects the current state of GitHub Agentic Workflows. The recommended patterns, commands, and configuration options may change in future releases as the platform evolves.
+
+Sharing workflows across an organization involves several independent layers. Each layer can be adopted independently; teams do not need all of them at once.
+
+The recommended enterprise pattern is to maintain one central `agentic-workflows` repository with versioned workflow templates and shared components. Consuming repositories then use `gh aw add` to install full workflows and `imports:` to pull in common modules.
+
+## Sharing Layers
+
+### 1. Copy and install whole workflows
+
+A repository can pull in a complete workflow from another repository:
+
+```bash
+gh aw add acme-org/agentic-workflows/ci-doctor@v1.2.0
+```
+
+The `source:` field is automatically added to the installed workflow's frontmatter so the origin and version are tracked. Use `gh aw add-wizard` for interactive installation with guided prompts. Use `gh aw add` for scripted or CI-driven installation.
+
+See [Reusing Workflows](/gh-aw/guides/packaging-imports/) for the full command reference and options.
+
+### 2. Reusable workflow components
+
+Shared building blocks — tool configurations, MCP server definitions, safety policies, and prompt snippets — can be imported into any workflow:
+
+```yaml
+imports:
+  - acme-org/shared-workflows/shared/security-setup.md@v2.1.0
+  - acme-org/shared-workflows/shared/mcp/tavily.md@v1.0.0
+```
+
+Remote imports are cached under `.github/aw/imports/` by commit SHA after the first fetch. This enables reproducible offline compilation and avoids redundant downloads when multiple refs point to the same commit.
+
+See [Imports Reference](/gh-aw/reference/imports/) for path formats, merge semantics, and field-specific behavior.
+
+### 3. Parameterized templates
+
+Shared workflows that declare an `import-schema` accept runtime parameters via `uses`/`with`:
+
+```yaml
+imports:
+  - uses: acme-org/shared-workflows/shared/reviewer.md@v1
+    with:
+      languages: ["go", "typescript"]
+      severity: "high"
+```
+
+This lets a single shared component serve multiple consuming workflows with different configurations without requiring separate copies.
+
+See [Imports Reference](/gh-aw/reference/imports/#parameterized-imports-useswith) for schema declaration and validation details.
+
+### 4. Versioning and update flow
+
+Enterprise workflow sharing needs a clear versioning model:
+
+- **Semantic versions** (`@v1.2.0`) pin to a stable release and update to the latest compatible patch or minor within the same major via `gh aw update`.
+- **Branch refs** (`@develop`) track the latest commit on a branch — useful for development integration.
+- **SHA pins** (`@abc123def`) provide strict reproducibility and never move without an explicit change.
+
+To pull upstream changes into an already-installed workflow:
+
+```bash
+gh aw update ci-doctor          # update one workflow
+gh aw update                    # update all tracked workflows
+```
+
+Updates use a 3-way merge by default to preserve local edits. Use `--no-merge` to replace the local copy with the upstream version without merging. Semantic version updates stay within the same major version unless `--major` is passed.
+
+### 5. Private and internal sharing controls
+
+Not all workflows are safe to share across organizations. GitHub Agentic Workflows provides controls at multiple levels:
+
+- **`private: true`** in frontmatter blocks a workflow from being installed into other repositories via `gh aw add`. Attempting to add a private workflow from another repository fails with an error.
+- **Repository visibility** controls which workflows are discoverable. Private repositories require access before any workflow can be fetched.
+- **Org-internal catalogs** can be implemented by placing workflows in a private or internal organization repository, ensuring only organization members can install them.
+
+See [Private Workflows](/gh-aw/reference/frontmatter/#private-workflows-private) for configuration details.
+
+### 6. Import caching and lock behavior
+
+When a workflow is compiled, remote imports are resolved and locked. The compiled `.lock.yml` file records the exact commit SHA for every remote import, making runs reproducible regardless of upstream branch movement.
+
+Imports are cached locally under `.github/aw/imports/` by commit SHA. Cached imports are used for all subsequent compilations until you explicitly update them. This means the lock file and the import cache together form the reproducibility guarantee for shared workflows.
+
+### 7. Cross-repository execution model
+
+Separate from sharing workflow definitions, workflows can operate across repositories at runtime:
+
+- Read files and metadata from other repositories during execution.
+- Check out code from target repositories for analysis or modification.
+- Write safe outputs to target repositories with explicit authentication and allowlists.
+
+```yaml
+safe-outputs:
+  create-issue:
+    target-repo: "acme-org/target-repo"
+    allowed-repos: ["acme-org/repo1", "acme-org/repo2"]
+```
+
+Cross-repository operations require appropriate GitHub token permissions and explicit `allowed-repos` declarations. See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for authentication, permissions, and safe output configuration.
+
+## Recommended Enterprise Pattern
+
+The recommended pattern for organizations sharing workflows at scale:
+
+1. **One central `agentic-workflows` repository** holds versioned workflow templates and shared components under `workflows/` and `shared/`.
+2. **Consuming repositories** use `gh aw add acme-org/agentic-workflows/<workflow>@<version>` to install complete workflows.
+3. **Common modules** (MCP configurations, safety policies, shared prompts) live in `shared/` and are imported via `imports:` in consuming workflows.
+4. **Version tags** on the central repository provide stable anchors for production consumers while branches support development integration.
+5. **`private: true`** marks internal-only workflows that should not be exported outside the organization.
+
+This model gives platform teams centralized ownership and update control while giving consuming teams reproducibility through version pins and the ability to preserve local customizations through 3-way merge.
+
+## Governance Questions
+
+When workflows are shared across an organization, the important decisions are usually operational rather than technical:
+
+- Who owns the source workflow and reviews proposed changes.
+- How updates are tested, tagged, and promoted to consuming repositories.
+- Which repositories may consume or dispatch to shared workflows.
+- How secrets, permissions, and safe outputs are standardized across consumers.
+- When a consuming team may fork a workflow rather than stay on the shared version.
+
+Those decisions affect reliability more than the file format does.
+
+## Related Documentation
+
+- [Reusing Workflows](/gh-aw/guides/packaging-imports/)
+- [Imports Reference](/gh-aw/reference/imports/)
+- [Cross-Repository Operations](/gh-aw/reference/cross-repository/)
+- [Private Workflows](/gh-aw/reference/frontmatter/#private-workflows-private)
+- [SideRepoOps](/gh-aw/patterns/side-repo-ops/)
+- [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/)