Org Architecture & Community Health

The Problem: Standards at Scale

Every multi-repository organization faces the same entropy: standards drift, security configurations diverge, and contributor onboarding becomes a per-repo archaeology exercise. Conway's law predicts this — organizations that design systems are constrained to produce designs which mirror their communication structures, and when those structures are fragmented across dozens of repositories, fragmentation is the inevitable output.^[1] The open-source world has known this for decades. Raymond's analysis of the bazaar model revealed that even decentralized projects require institutional infrastructure — mailing list conventions, patch formats, release protocols — to avoid collapsing under their own coordination costs.^[2] GitHub's special .github repository mechanism offers a solution: a single repository whose contents — workflows, templates, governance documents, AI configurations — are inherited by every other repository in the organization. This project takes that mechanism and builds a comprehensive organizational operating system on top of it, governing 81 repositories across 8 organizations from a single source of truth.

Community Health Layer

The foundation of any collaborative software project is not its code but its social contracts. GitHub's community health file inheritance means that a CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, and SUPPORT.md placed in the .github repository appear on every repository in the organization that has not defined its own — creating a baseline of contributor experience without requiring any per-repo configuration.^[3] Eghbal's research into the maintenance burden of open-source projects demonstrates that community health files are not bureaucratic overhead but essential load-bearing infrastructure: projects without clear contribution guidelines see higher friction in first-time contributions and higher maintainer burnout. Fogel extends this argument to the operational level, showing that explicit governance documents reduce "bike-shedding" — endless procedural debates — by providing authoritative answers to common questions before they are asked.^[4] In this system, the four health files are not boilerplate templates but carefully authored documents reflecting the specific governance philosophy of the eight-organ architecture: the Code of Conduct references the system's values, the Contributing guide maps onto the promotion state machine, and the Security policy defines responsible disclosure procedures tailored to the project's threat model.

name: CI Pipeline
on:
  workflow_call:
    inputs:
      language:
        required: true
        type: string

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
        with:
          fetch-depth: 0

      - name: Setup environment
        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8  # v4.0.2
        if: inputs.language == 'typescript'
        with:
          node-version: '22'

      - name: Security scan — Gitleaks
        uses: gitleaks/gitleaks-action@1f2d10fb689bc07a5f56f48e6c6b8ee4a47c1dab  # v2.3.6
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Security scan — CodeQL
        uses: github/codeql-action/analyze@c4fb451437765abf5018c6571834e2c3c6a21745  # v3.24.6
        with:
          languages: ${{ inputs.language }}

      - name: Run tests
        run: |
          if [ "${{ inputs.language }}" = "typescript" ]; then
            npm ci && npm test
          elif [ "${{ inputs.language }}" = "python" ]; then
            pip install -r requirements.txt && pytest
          fi

CI/CD Infrastructure

The second layer transforms GitHub Actions from per-repository configuration files into an organizational platform. Every workflow uses workflow_call to expose itself as a reusable component — individual repositories call these shared workflows with parameters rather than duplicating pipeline logic.^[5] Humble and Farley's core insight — that the deployment pipeline should be a first-class artifact, versioned and tested like application code — applies doubly at the organizational level, where pipeline drift across repositories creates silent security gaps and inconsistent quality gates. The critical security decision is SHA-pinning: every GitHub Action reference uses a full commit SHA rather than a mutable tag, preventing supply-chain attacks where a compromised action tag is silently replaced with malicious code.^[6] Bass et al. identify supply-chain integrity as a DevOps architectural concern — this repository implements that concern at the organizational boundary, ensuring that no repository in the system can accidentally reference an unvetted action version.

The three scanning tools form a defense-in-depth strategy. CodeQL operates at the semantic level, understanding language-specific vulnerability patterns — SQL injection, cross-site scripting, insecure deserialization — by modeling code as a queryable database. Gitleaks works at the git layer, scanning every commit in repository history for patterns matching API keys, tokens, and credentials, catching secrets that were committed and later "deleted" but remain in git history. TruffleHog complements both with high-entropy string detection and custom regex patterns, catching credential formats that Gitleaks' built-in patterns miss.^[5] Together, they implement what Humble and Farley call the "quality gate" pattern: no code reaches production without passing all three scans. The organizational inheritance model means this gate is not opt-in — every repository inherits it by default, and opting out requires an explicit, reviewable override.

AI Agent Framework

The third layer is the most forward-looking: a framework of production AI agents, each specialized for a domain within the organizational workflow. Security agents review pull requests for vulnerability patterns, infrastructure agents validate workflow configurations and dependency graphs, development agents assist with code generation within the established patterns, and documentation agents enforce consistency across the 81 repositories' README files and changelogs.^[7] Wooldridge's taxonomy of agent architectures — reactive, deliberative, and hybrid — maps onto the framework's design: security agents are reactive (trigger on PR events), documentation agents are deliberative (analyze repository state and generate updates), and development agents are hybrid (respond to immediate requests while maintaining context across sessions). The agents are implemented as GitHub Copilot-compatible configurations, meaning they integrate with the developer's existing IDE workflow rather than requiring a separate toolchain.^[8] Russell and Norvig's framework for rational agents — perceive, reason, act — is realized concretely: each agent perceives through GitHub event webhooks, reasons through its specialized prompt context, and acts through the GitHub API. The chatmodes layer adds specialized personas — a security auditor, a documentation editor, a dependency analyst — each with tailored system prompts and tool access policies.

name: security-reviewer
description: Reviews PRs for security vulnerabilities and compliance
triggers:
  - pull_request.opened
  - pull_request.synchronize

context:
  files:
    - SECURITY.md
    - .github/workflows/security-scan.yml
  instructions: |
    You are a security reviewer for the organvm ecosystem.
    Check for: hardcoded secrets, unsafe dependencies,
    missing input validation, SQL injection vectors,
    and OWASP Top 10 patterns.

permissions:
  contents: read
  pull-requests: write
  security-events: read

copilot:
  compatible: true
  slash-commands:
    - /security-review
    - /threat-model
  model-preference: claude-sonnet

Design Philosophy: Infrastructure as Culture

The deeper claim of this project is that organizational culture can be encoded as versionable, reviewable, inheritable artifacts. This is infrastructure-as-code thinking applied not to servers or networks but to governance, contributor experience, and development methodology.^[9] Morris argues that treating infrastructure as code provides four benefits — reproducibility, consistency, auditability, and recoverability — and every one of these applies to organizational standards. When the Code of Conduct is a file in a Git repository, it has a commit history, a blame log, a review trail. When CI policy changes, the diff is visible and the rollback path is clear. This transforms governance from an implicit social agreement into an explicit, testable system.^[10] Ostrom's Nobel Prize-winning research on institutional governance demonstrated that successful commons management requires clear boundaries, proportional rules, collective-choice arrangements, and monitoring — all of which this repository implements through GitHub's access controls, inherited workflow rules, PR-based governance changes, and automated health monitoring respectively.

The decision to make AI agents part of this governance layer — rather than a separate system — reflects a deliberate architectural position: AI tooling should be subject to the same review, versioning, and access control processes as any other piece of organizational infrastructure. An agent's prompt is as consequential as a CI pipeline's configuration, and should be governed accordingly.^[7] Wooldridge identifies trust and delegation as the central challenges of multi-agent systems; by placing agent configurations within the same governance framework as security policies and contribution guidelines, the system makes agent capabilities visible, auditable, and revocable through familiar Git-based workflows rather than opaque administrative interfaces.

Tradeoffs and Limitations

The inheritance model has a fundamental tension: uniformity versus autonomy. A repository that needs a custom CI pipeline must explicitly override the inherited one, creating a maintenance burden at the repository level and a coordination cost at the organizational level — every override is a potential drift point that the monthly health audit must track.^[2] Raymond's observation that open-source governance must balance centralized standards with decentralized innovation applies directly: too much inheritance and repositories become constrained; too little and the organizational operating system loses its coherence. The current design errs toward inheritance, with escape hatches for repositories that genuinely need custom behavior — a choice that reflects the system's scale (81 repositories) and its need for auditable consistency over per-repo flexibility.