docs: Organization Practices

[Copilot]

Adds Organization Practices pages under Guides in the sidebar.

Changes Made

• Safe Rollout: New page describing the rollout ladder from report-only to production writes, including staged mode and shadow evaluation techniques.
• Sharing Workflows: New page covering the 7 layers of enterprise workflow sharing:
  1. Copy/install whole workflows via gh aw add with version refs and source: tracking
  2. Reusable workflow components via imports: for tools, MCP servers, steps, and prompt snippets
  3. Parameterized templates via uses/with for shared imports with runtime inputs
  4. Versioning and update flow — semantic versions, branch refs, SHA pins, and gh aw update with 3-way merge
  5. Private/internal sharing controls via private: true and org-internal repository visibility
  6. Import caching and lock behavior — .lock.yml and .github/aw/imports/ SHA cache for reproducibility
  7. Cross-repository execution model via target-repo/allowed-repos for runtime cross-repo reads and writes
• Enterprise pattern: Documents the recommended model of one central agentic-workflows repository with versioned templates and shared components, consumed via gh aw add and imports:.
• Future-change banner: Added a note banner on the Sharing Workflows page and the Reusing Workflows guide indicating these patterns may change in future releases.
• Sidebar: Organization Practices is nested as a sub-group under Guides (not a standalone top-level section).
• Glossary: No entries added for Organization Practices topics.

[mnkiefer]

@copilot No glossary entries for this. Also put "Organization Practices" section under "Guides" and not "Design patterns".

[Copilot]

@copilot No glossary entries for this. Also put "Organization Practices" section under "Guides" and not "Design patterns".

Done in 210ab9f:

• Removed the Organization Practices, Safe Rollout, and Shadow Evaluation glossary entries.
• Moved Organization Practices as a nested sub-group inside Guides in the sidebar (no longer a standalone top-level section).

[github-actions]

✅ Smoke CI completed successfully!

[github-actions]

✅ Smoke CI completed successfully!

[github-actions]

✅ smoke-ci: safeoutputs CLI comment + comment-memory run (24995461080)

Generated by Smoke CI for issue #28688 · ◷

[mnkiefer]

@copilot Update text: For sharing GitHub Agentic Workflows, they should support a few layers:

1. Copy/install whole workflows: A repo should be able to pull in a workflow from another repo:
   gh aw add acme-org/agentic-workflows/ci-doctor@v1.2.0
   GitHub AW already supports this via gh aw add, gh aw add-wizard, version refs, and a source: field for later updates.
2. Reusable workflow components: Shared pieces should be importable:

imports:
  - acme-org/shared-workflows/shared/security-setup.md@v2.1.0
  - acme-org/shared-workflows/shared/mcp/tavily.md@v1.0.0

AW supports imports: for shared tools, MCP servers, steps, jobs, and prompt snippets.
3. Parameterized templates: Shared workflows should take inputs:

imports:
  - uses: acme-org/shared-workflows/shared/reviewer.md@v1
    with:
      languages: ["go", "typescript"]
      severity: "high"

AW supports uses / with for parameterized imports.
4. Versioning and update flow: Enterprise sharing needs:

• Semantic versions for stable workflows
• Branch refs for dev
• SHA pins for strict reproducibility
• gh aw update to pull upstream changes
• 3-way merge to preserve local edits
  AW documents this model directly.

5. Private/internal sharing controls
   They should support:

• Org-internal workflow catalogs
• Private workflows that cannot be imported elsewhere
• Access checks before install
• Trusted-source warnings
  AW has access-based imports and private: true to block adding workflows to other repos.

6. Import caching / lock behavior: Shared imports should be cached and compiled into .lock.yml so runs are reproducible. AW caches remote imports under .github/aw/imports/ by commit SHA.
7. Cross-repo execution model: Separate from sharing definitions, workflows should support operating across repos: read other repos, check out code, and create safe outputs in target repos with explicit auth and allowlists. AW has cross-repo checkout, reading, and safe outputs via target-repo / allowed-repos.
   Currently, the guide should describe that the ideal enterprise pattern is one central "agentic-workflows" repo with versioned workflow templates and shared components, then consuming repos use gh aw add for full workflows and imports: for common modules.Note, that this may change in the future so add a banner a on other pages (this is new).

[Copilot]

@copilot Update text: For sharing GitHub Agentic Workflows, they should support a few layers:

1. Copy/install whole workflows: A repo should be able to pull in a workflow from another repo:
   `gh aw a...

Done in 0e3f274. The sharing-workflows.md page has been rewritten to cover all 7 layers:

1. Copy/install whole workflows — gh aw add acme-org/agentic-workflows/ci-doctor@v1.2.0 with source: tracking
2. Reusable workflow components — imports: for shared tools, MCP servers, and prompt snippets
3. Parameterized templates — uses/with for parameterized shared imports
4. Versioning and update flow — semantic versions, branch refs, SHA pins, and gh aw update with 3-way merge
5. Private/internal sharing controls — private: true, repo visibility, and org-internal catalogs
6. Import caching and lock behavior — .lock.yml + .github/aw/imports/ SHA cache
7. Cross-repository execution model — target-repo/allowed-repos for runtime cross-repo reads and writes

A "Recommended Enterprise Pattern" section describes the central agentic-workflows repo model. The "may change in the future" banner has been added to both sharing-workflows.md and packaging-imports.mdx.