Document org-level agent pattern and deployment mirror repos

Open
#24 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
70/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
github

Research direction

Start by reviewing the existing documentation structure, then use the mentioned .github/copilot-instructions.md, .github/agents/, .github/skills/, .azure/deployments/, and .github/workflows/ paths as the guide's anchors. Document the org-level governance pattern, the minimal deployment mirror layout, and how workflows and inherited guardrails fit together; done means all four acceptance criteria are covered.

Written by the indexing model from the issue text.

Description

documentation

Description

The manifesto distinguishes repo-level agents from org-level agents that encode enterprise-wide standards. Git-ape doesn't need to build this mechanism — GitHub Copilot already supports org-level custom instructions. What's needed is documentation showing how to structure the org-level pattern for infrastructure governance.

The key concept: a deployment mirror repo contains no agents or skills — only deployment artifacts (.azure/deployments/, state, metadata). All agent intelligence lives in the org-level .github repository and is inherited automatically. The deployment repo is a pure ledger of infrastructure state.

Scope

  1. Org-level pattern guide — Document how to set up an organization .github repo with:
    • copilot-instructions.md containing security baselines, naming conventions, approved regions, compliance rules.
    • Git-ape agents and skills installed at org level (inherited by all repos).
    • Org-level guardrails that repo-level instructions cannot weaken.
  2. Deployment mirror repo guide — Document the pattern where:
    • A repo contains only .azure/deployments/ with templates, state, metadata, and architecture diagrams.
    • No .github/agents/ or .github/skills/ — all agent capabilities come from the org-level plugin/repo.
    • Workflows (.github/workflows/) are the only repo-level config (plan, deploy, destroy).
    • The repo is a pure infrastructure state ledger, versioned in Git.
  3. Example repo structure — Show the minimal deployment mirror repo layout.
  4. Multi-repo governance — How multiple deployment mirror repos share consistent guardrails from one org-level source.

Acceptance Criteria

  • Guide documenting org-level agent setup for infrastructure governance.
  • Guide documenting deployment mirror repo pattern (no agents, state only).
  • Example minimal repo structure for a deployment mirror.
  • Explanation of how org-level guardrails flow to deployment repos.
Dominant language
JavaScript
Stars
269
Forks
45
Avg merge
1d 4h
Merged PRs (30d)
15

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Azure/git-ape

All issues in Azure/git-ape

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.