agentsys 5.0.3 → 5.2.0

package/agent-knowledge/github-org-project-management.md

@@ -0,0 +1,319 @@
+# Learning Guide: GitHub Organization Project Management for Multi-Repo Open Source Ecosystems
+
+**Generated**: 2026-02-21
+**Sources**: 15 resources analyzed
+**Depth**: deep
+
+## Prerequisites
+
+- Familiarity with GitHub Issues and Pull Requests
+- Basic understanding of GitHub Organizations
+- Awareness of multi-repo project structures
+- Optional: GraphQL API knowledge for automation
+
+## TL;DR
+
+- GitHub Projects v2 is the primary tool for cross-repo org-level project management, supporting up to 50,000 items and 50 custom fields across all repos in an org.
+- Issue Types (public preview, Jan 2025) and Sub-Issues enable structured work hierarchies at the org level without extra tooling.
+- Automation via built-in workflows, GitHub Actions (`actions/add-to-project@v1`), and the GraphQL API is essential for keeping cross-repo boards accurate at scale.
+- Successful open source orgs (Rust, Kubernetes, Astro, GitHub itself) combine a public roadmap project, RFC/enhancement-proposal repos, and working groups or SIGs to coordinate distributed contributors.
+- The GraphQL API with the `project` OAuth scope unlocks full programmatic control; `read:project` is sufficient for read-only integrations.
+
+## Core Concepts
+
+### GitHub Projects v2
+
+Projects v2 replaced the classic Projects board in 2022. It lives at the org level (not per-repo) and can aggregate items from any repository in the organization.
+
+Key capabilities:
+- **Views**: Table (spreadsheet-style), Board (kanban), Roadmap (Gantt-like timeline)
+- **Custom fields**: Up to 50 per project. Types: text, number, date, single-select, iteration
+- **Grouping, filtering, sorting**: Available across all views; filters use GitHub's advanced search syntax including AND/OR keywords and parentheses
+- **Capacity**: 50,000 items per project
+- **Cross-repo**: A single project can contain issues and PRs from any repo in the org
+
+### Issue Types
+
+Introduced in public preview January 2025. Org admins define up to 25 custom issue types (defaults: Task, Bug, Feature). Types are available across all repos and can be filtered in Projects and search.
+
+This replaces the common pattern of using label conventions (`type: bug`, `kind/feature`) with a first-class field.
+
+### Sub-Issues
+
+Also in public preview. Issues can have a parent-child relationship:
+- Break a large epic into sub-issues
+- Progress bar displayed on the parent issue
+- Sub-issues can live in different repos from the parent
+- Enables hierarchical tracking without external tools
+
+### Automation Tiers
+
+| Plan | Built-in Workflows |
+|------|--------------------|
+| Free | 1 active workflow |
+| Pro / Team | 5 active workflows |
+| Enterprise | 20 active workflows |
+
+Built-in workflow triggers:
+- Item closed → set status
+- PR merged → set status
+- Item added to repo → add to project (filter by label, status, or assignee)
+- Item archived by staleness (14 days, 3 weeks, or 1 month of inactivity)
+
+For more complex rules, use GitHub Actions or the GraphQL API.
+
+### GraphQL API
+
+All project mutations require the `project` OAuth scope. Read-only operations use `read:project`.
+
+Primary operations:
+- `addProjectV2ItemById` - add an issue/PR to a project
+- `updateProjectV2ItemFieldValue` - set a field value on an item
+- `createProjectV2` - create a new project
+
+Webhook events: `projects_v2_item` (created, edited, deleted, reordered, converted)
+
+## Code Examples
+
+### Auto-Add Issues from Any Repo via GitHub Actions
+
+```yaml
+# .github/workflows/add-to-project.yml
+# Place this in EACH repo that should auto-add items to the org project
+name: Add to Org Project
+
+on:
+  issues:
+    types: [opened]
+  pull_request:
+    types: [opened]
+
+jobs:
+  add-to-project:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v1
+        with:
+          project-url: https://github.com/orgs/MY-ORG/projects/42
+          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
+          # Optional: only add if issue has specific label
+          labeled: triage, bug, enhancement
+```
+
+The PAT must belong to an org member and have the `project` scope.
+
+### GraphQL: Add Issue to Project
+
+```graphql
+mutation AddIssueToProject($projectId: ID!, $contentId: ID!) {
+  addProjectV2ItemById(input: {
+    projectId: $projectId
+    contentId: $contentId
+  }) {
+    item {
+      id
+    }
+  }
+}
+```
+
+### GraphQL: Update a Field Value
+
+```graphql
+mutation SetStatus($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+  updateProjectV2ItemFieldValue(input: {
+    projectId: $projectId
+    itemId: $itemId
+    fieldId: $fieldId
+    value: {
+      singleSelectOptionId: $optionId
+    }
+  }) {
+    projectV2Item {
+      id
+    }
+  }
+}
+```
+
+### GraphQL: Find Project by Org and Number
+
+```graphql
+query FindProject($org: String!, $number: Int!) {
+  organization(login: $org) {
+    projectV2(number: $number) {
+      id
+      title
+      fields(first: 20) {
+        nodes {
+          ... on ProjectV2Field {
+            id
+            name
+          }
+          ... on ProjectV2SingleSelectField {
+            id
+            name
+            options {
+              id
+              name
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Advanced Search: Filter Issues by Type and Status
+
+```
+org:MY-ORG is:open type:feature label:roadmap
+org:MY-ORG is:open type:bug (label:priority-high OR label:priority-critical)
+```
+
+## Org-Level Patterns from Real Projects
+
+### GitHub's Public Roadmap
+
+GitHub maintains a public project at `github.com/orgs/github/projects/4247`. Key practices:
+- Quarterly columns map to release milestones
+- The `shipped` label is applied when a feature lands, and the issue body is updated with a changelog link
+- Items stay visible after shipping in a "Shipped" column (archive only after some time)
+- This gives external contributors a real-time view of planned and recent work
+
+### Kubernetes SIG Model
+
+Kubernetes uses Special Interest Groups (SIGs) to coordinate work across 100+ repos:
+- Each SIG owns a subset of repos and has a dedicated project board
+- Kubernetes Enhancement Proposals (KEPs) live in a single `kubernetes/enhancements` repo as structured markdown files
+- KEPs link to issues/PRs in implementation repos
+- SIG leads triage new issues weekly and apply standardized labels (`sig/network`, `kind/feature`, etc.)
+
+### Rust-lang RFC Process
+
+- RFCs live in `rust-lang/rfcs` as PRs
+- Working groups coordinate cross-team implementation
+- A dedicated project tracks RFC lifecycle stages (proposed → accepted → stabilized → closed)
+- Cross-repo coordination uses GitHub Projects with a single-select "Phase" field
+
+### Astro (withastro)
+
+- 51 repos under one org
+- `withastro/roadmap` repo hosts RFC discussions and a public-facing roadmap project
+- Uses pnpm workspaces for the core monorepo; satellite repos (integrations, adapters) auto-add to the roadmap project via GitHub Actions
+- Labels are org-wide and enforced consistently
+
+## Common Pitfalls
+
+| Pitfall | Why It Happens | How to Avoid |
+|---------|---------------|--------------|
+| Project scope creep | One project tracks everything; becomes unusable | One project per initiative or quarter; archive completed projects |
+| Label inconsistency across repos | Each repo grows its own labels organically | Manage labels programmatically; use a shared label config script or action |
+| Missing automation tokens | PATs expire or lack correct scopes; cross-repo actions silently fail | Use fine-grained PATs with explicit `project` scope; rotate with secrets manager |
+| Stale items clogging board | Closed issues not archived; old PRs linger | Enable auto-archive: set staleness to 14 days or archive on close/merge |
+| No triage process | New issues pile up without status | Add "Needs Triage" as default status; automate: new issue → Needs Triage |
+| Cross-repo sub-issue confusion | Contributors open sub-issues in wrong repo | Document in CONTRIBUTING.md which repo to use for which issue type |
+| Workflow count limits on Free plan | Only 1 built-in workflow on Free | Use GitHub Actions instead of built-in workflows for more rules |
+| Views not shared with team | Each person builds their own view | Create named saved views in the project for common filters (My Items, This Sprint, Blocked) |
+
+## Best Practices
+
+1. **One source of truth per initiative** - Each major feature or release gets exactly one project. Avoid tracking the same item in multiple projects.
+
+2. **Standardize labels org-wide** - Use a label sync action (e.g., `EndBug/add-or-update-label`) to keep labels consistent across all repos. Document the label taxonomy in a `CONTRIBUTING.md` or `.github` repo.
+
+3. **Use Issue Types instead of type labels** - Now that Issue Types are available (Jan 2025 public preview), prefer them over label conventions for `bug`, `feature`, `task`. Labels are better for priority, status, and component.
+
+4. **Automate triage with GitHub Actions** - New issues opened in any repo auto-add to the org triage project with status "Needs Triage". Maintainers process the triage board, not individual repos.
+
+5. **Keep the roadmap project public** - A public roadmap project builds contributor trust and reduces duplicate "when will X be done?" issues. Model: GitHub's own public roadmap.
+
+6. **Use Iteration fields for sprints or releases** - Iterations are time-boxed periods (e.g., 2-week sprints). Assign items to iterations instead of milestones for better burndown tracking.
+
+7. **Multiple saved views per audience** - Create views for: "My open items" (assignee filter), "This sprint" (iteration filter), "Blocked" (status filter), "Triage queue" (status = Needs Triage).
+
+8. **Sub-issues for epics, not just labels** - Break large epics into sub-issues rather than relying on a checklist in the parent body. Progress tracking is automatic and cross-repo linking is supported.
+
+9. **Automate status transitions** - Configure built-in workflows: PR merged → item status set to Done. Issue closed as not-planned → item archived. This removes manual housekeeping.
+
+10. **Use the `.github` meta-repo** - A `.github` repo in the org stores default issue templates, PR templates, `CONTRIBUTING.md`, and Actions workflows that apply to all repos with no files.
+
+## Field Design for Multi-Repo Projects
+
+Recommended custom fields for an org-level project:
+
+| Field Name | Type | Values / Notes |
+|------------|------|----------------|
+| Status | Single Select | Triage, Backlog, In Progress, In Review, Done, Blocked |
+| Priority | Single Select | Critical, High, Medium, Low |
+| Sprint / Iteration | Iteration | 2-week cadence |
+| Effort | Single Select | XS, S, M, L, XL |
+| Component | Single Select | Per-repo or per-area (e.g., Core, Docs, CLI, API) |
+| Target Release | Single Select | v1.0, v1.1, Backlog |
+| Repo | Text | Auto-populated via automation (helps when filtering Table view) |
+
+## GitHub Actions Automation Recipes
+
+### Auto-Set Status to "In Progress" When PR Opened
+
+```yaml
+name: PR Opened - Set In Progress
+
+on:
+  pull_request:
+    types: [opened, reopened]
+
+jobs:
+  update-project:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Move linked issues to In Progress
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROJECT_PAT }}
+          script: |
+            // Use GraphQL to find project item for this PR and update status
+            // Implementation varies by project ID and field IDs
+```
+
+### Sync Org Labels Across All Repos
+
+```yaml
+# Run in the .github meta-repo
+name: Sync Labels
+
+on:
+  push:
+    paths: ['labels.yml']
+  schedule:
+    - cron: '0 2 * * 1'  # Weekly Monday 2am
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: EndBug/label-sync@v2
+        with:
+          config-file: labels.yml
+          delete-other-labels: false
+          token: ${{ secrets.LABEL_SYNC_PAT }}
+          # Applies to all repos accessible to the PAT
+```
+
+## Further Reading
+
+| Resource | Type | Why Recommended |
+|----------|------|-----------------|
+| [GitHub Projects Docs](https://docs.github.com/en/issues/planning-and-tracking-with-projects) | Official Docs | Canonical reference for all Projects v2 features |
+| [GitHub's Public Roadmap](https://github.com/orgs/github/projects/4247) | Live Example | See how GitHub itself manages a public org project |
+| [actions/add-to-project](https://github.com/actions/add-to-project) | GitHub Action | Official action for cross-repo auto-add |
+| [Kubernetes SIG structure](https://github.com/kubernetes/community/blob/master/sig-list.md) | Reference | How Kubernetes scales to 100+ repos with SIGs |
+| [withastro/roadmap](https://github.com/withastro/roadmap) | Reference | Astro's RFC and roadmap coordination model |
+| [GitHub Issues API (GraphQL)](https://docs.github.com/en/graphql/reference/mutations#addprojectv2itembyid) | API Docs | GraphQL mutations for project automation |
+| [EndBug/label-sync](https://github.com/EndBug/label-sync) | GitHub Action | Sync labels across all org repos |
+
+---
+
+*This guide was synthesized from research on GitHub Projects v2, Issue Types, Sub-Issues, GraphQL API, and real-world org patterns (Rust-lang, Kubernetes, Astro, GitHub). See `resources/github-org-project-management-sources.json` for full source list.*

package/agent-knowledge/github-org-structure-patterns.md

@@ -0,0 +1,268 @@
+# Learning Guide: GitHub Organization Structure Patterns for Developer Tool Ecosystems
+
+**Generated**: 2026-02-21
+**Sources**: 18 resources analyzed
+**Depth**: deep
+
+## Prerequisites
+
+- Familiarity with GitHub repositories and basic git workflows
+- Understanding of GitHub Actions concepts (workflows, triggers)
+- Basic knowledge of open source project conventions (CONTRIBUTING, CODE_OF_CONDUCT)
+
+## TL;DR
+
+- The `.github` org (public repo) is the control plane for org-wide defaults: community health files, reusable workflows, profile README, and starter workflows
+- Real-world orgs fall into two archetypes: **focused** (few high-quality repos, e.g. oven-sh/Bun) and **ecosystem** (many small packages, e.g. unjs, sindresorhus)
+- Reusable workflows (`workflow_call`) are the primary mechanism for DRY CI across many repos in an org
+- CODEOWNERS + working groups (teams) is the dominant governance pattern for monorepos
+- AI usage disclosure policies are becoming a new category of org-level community health file
+
+## Core Concepts
+
+### The `.github` Repository as Org Control Plane
+
+Every GitHub org has a special `.github` repository that acts as the configuration and defaults layer for the entire org.
+
+**Profile README** (`profile/README.md`):
+- Public-facing org description shown on the org's GitHub page
+- Supports full markdown: badges, images, links, embedded stats
+- A separate `.github-private` repo can hold a `profile/README.md` visible only to org members — useful for internal runbooks and links
+
+**Default Community Health Files**:
+The `.github` repo (which MUST be public to cascade org-wide) can define default files that apply to every repo in the org that does not override them:
+
+| File | Purpose |
+|------|---------|
+| `CODE_OF_CONDUCT.md` | Community behavior standards |
+| `CONTRIBUTING.md` | How to contribute |
+| `FUNDING.yml` | Sponsorship links |
+| `GOVERNANCE.md` | Decision-making processes |
+| `SECURITY.md` | Vulnerability reporting policy |
+| `SUPPORT.md` | Where to get help |
+| Issue templates | Default issue forms |
+| PR templates | Default PR descriptions |
+
+**Important caveat**: If any individual repo has ANY files in its own `.github/ISSUE_TEMPLATE/` directory, the org-level issue template defaults no longer apply to that repo. The override is all-or-nothing per file type.
+
+**What cannot be org defaults**: License files must be defined per-repo.
+
+### Org-Level Pinned Repositories
+
+Orgs can pin up to 6 repositories on their public profile page. A separate set of up to 6 pins can be configured for the member-only view. Use pins to surface:
+- The primary product repo
+- The standard library or docs repo
+- Developer tooling repos (actions, setup tools, homebrew taps)
+- Community/contribution entry points (roadmap, good-first-issues)
+
+### Reusable GitHub Actions Workflows
+
+Reusable workflows eliminate CI duplication across many repos in an org. They use the `workflow_call` trigger.
+
+**Reference syntax**:
+```yaml
+jobs:
+  call-shared-workflow:
+    uses: myorg/.github/.github/workflows/ci.yml@main
+    with:
+      node-version: "22"
+    secrets: inherit
+```
+
+**Key constraints and features**:
+- Maximum 10 nesting levels (reusable workflows calling other reusable workflows)
+- Permissions can only be maintained or reduced, never elevated
+- `secrets: inherit` passes the caller's secrets implicitly — preferred for org-internal workflows
+- Matrix strategies are supported in callers
+- Inputs and outputs are typed (string, boolean, number, choice)
+
+**Pattern**: Keep reusable workflows in the org `.github` repo under `.github/workflows/`, then reference `{owner}/.github/.github/workflows/{name}.yml@{ref}`.
+
+### Starter Workflows
+
+Starter workflows appear in the "Actions" tab of new repos as suggested templates. They live in the `.github` repo under `workflow-templates/`.
+
+Each starter workflow requires two files:
+- `workflow-templates/{name}.yml` — the workflow definition
+- `workflow-templates/{name}.properties.json` — metadata (name, description, iconName, categories)
+
+**Five categories**: CI, Deployments, Automation, Code-scanning, Pages
+
+Variable substitution is supported: `$default-branch` resolves to the repo's default branch, `$cron-daily` to a daily cron expression.
+
+### CODEOWNERS and Working Groups
+
+CODEOWNERS files define who must review changes to specific paths. The **last matching pattern wins** (bottom-to-top precedence).
+
+**Tauri's two-team pattern** (simple and effective):
+```
+# .github/CODEOWNERS
+* @tauri-apps/wg-tauri
+.github @tauri-apps/wg-devops
+```
+
+This gives the main working group ownership of all code, while the DevOps working group exclusively owns CI and tooling changes — preventing accidental breakage of infrastructure by feature contributors.
+
+**Common patterns**:
+- `docs/ @org/docs-team` — separate docs ownership
+- `*.rs @org/core-team` — language-specific ownership
+- `/packages/plugin-* @org/plugin-maintainers` — plugin subsystem
+
+### GitHub Pages for Orgs
+
+| Type | Repo Name | URL |
+|------|-----------|-----|
+| Org site | `<owner>.github.io` | `https://<owner>.github.io` |
+| Project site | any repo | `https://<owner>.github.io/<repo>` |
+
+One org site per account. Custom domains are supported on all tiers. Free plan limits Pages to public repos.
+
+## Real-World Org Archetypes
+
+### The Focused Minimal Org (oven-sh / Bun)
+
+- ~7 visible repos: primary product, community list, setup action, homebrew tap, essential forks
+- High signal-to-noise: every repo has clear purpose
+- Pinned repos do the navigation work
+- Setup tooling (`setup-bun`) is a first-class citizen in the org
+
+**When to use**: Single primary product with companion tooling. Avoid repo sprawl that dilutes contributor attention.
+
+### The Ecosystem Org (denoland / Deno)
+
+- 216+ repos: runtime, standard library, framework (Fresh), toolchains, bindings
+- Standard library (`deno_std`) is its own monorepo, separately versioned
+- Distinct registries: Deno now publishes std to JSR (JavaScript Registry) alongside npm
+- Verified domain lends authority to the org
+
+**When to use**: Platform-level products where many independent but related modules need separate release cycles.
+
+### The Framework Org (withastro / Astro)
+
+- ~51 repos: core framework, docs site, compiler (separate language), roadmap (RFC process), deployment action, Starlight docs builder
+- `roadmap` repo used for public RFCs and planning — community-facing project management
+- pnpm workspaces for monorepo dependency management
+- `astro-action` for GitHub Pages deployment
+
+**When to use**: Frameworks with distinct subsystems (compiler, runtime, CLI) that benefit from separate contribution histories but shared releases.
+
+### The Working Group Org (tauri-apps)
+
+- Working groups as GitHub Teams: `wg-tauri`, `wg-devops`
+- CODEOWNERS maps paths to working groups
+- Monorepo with clear subsystem ownership
+
+**When to use**: Mature projects with specialized contributor groups. Teams enforce review requirements automatically.
+
+### The Utility Library Ecosystem (unjs / sindresorhus)
+
+- Dozens to hundreds of small, focused packages
+- Each package is its own repo with its own release cycle
+- Org profile README serves as the package index
+- Contributing to any package follows org-wide defaults from `.github`
+
+**When to use**: Utility ecosystems where each package solves one problem and has independent users.
+
+## Contributing Guide Patterns
+
+### Setup Complexity Tiers
+
+**Lightweight** (JS/TS projects like Astro):
+- Requires: Node >=22.12, pnpm >=10.28
+- GitHub Codespaces support for zero-install onboarding
+- Single `pnpm install && pnpm build` setup
+
+**Heavy** (compiled projects like Bun):
+- Requires: LLVM 21.1.8 (specific version), Zig (auto-installed by build script)
+- 10-30 minute first setup expectation set explicitly
+- Debug build alias (`bun bd`) documented prominently
+
+### Priority Labels
+
+Astro uses a p1-p5 priority scale for issues. This is more expressive than simple priority/non-priority and helps maintainers triage community PRs.
+
+### Branch Targeting Conventions
+
+Biome targets changes to `main` or `next` depending on stability. This should be explicitly documented — contributors who target the wrong branch create merge conflicts.
+
+### AI Contribution Policies
+
+Emerging pattern (Biome, OXC): explicit AI usage disclosure in CONTRIBUTING.md:
+
+- **Biome approach**: AI disclosure as the first section — sets tone before anything else
+- **OXC approach**: AI accountability policy — contributor is responsible for all AI-generated code quality, must review and test it, cannot use AI generation as excuse for quality issues
+
+This is becoming a community health default to consider for new orgs in 2025+.
+
+### Just Commands (Biome pattern)
+
+Using `just` (Justfile) for project commands standardizes the contributor experience across platforms:
+```
+just build
+just test
+just lint
+```
+Avoids npm script confusion and works identically in all shells.
+
+### Changesets for Versioning
+
+Biome and others use Changesets for coordinated multi-package version management. Contributors add a changeset file alongside their PR describing the change type (major/minor/patch), and release automation assembles the changelog.
+
+## Common Pitfalls
+
+| Pitfall | Why It Happens | How to Avoid |
+|---------|---------------|--------------|
+| Org defaults silently overridden | Repo has any file in `.github/ISSUE_TEMPLATE/` | Audit all repos; prefer org defaults where possible |
+| `.github` repo is private | Created as private by default | Must be public for defaults to cascade |
+| CODEOWNERS pattern order wrong | Assuming first match wins | Remember: last matching pattern wins |
+| Reusable workflow permissions escalation | Caller tries to grant more than caller has | Permissions are only reducible, never elevated |
+| Workflow nesting beyond 10 levels | Over-decomposed reusable workflows | Flatten; use composite actions for deeply nested logic |
+| Pinned repos not updated post-launch | Set once and forgotten | Review pins at each major release |
+| Contributing guide assumes one platform | Windows contributors fail silently | Test setup steps on Windows or document platform limits |
+
+## Best Practices
+
+1. **Create `.github` repo first** — Before any other repo. It's the org's foundation. (Source: GitHub Docs)
+2. **Pin repos strategically** — Primary product + setup action + docs + roadmap covers most navigation needs. (Source: oven-sh, withastro patterns)
+3. **Use working groups as GitHub Teams** — Map CODEOWNERS to teams, not individuals. Individuals leave; teams persist. (Source: tauri-apps)
+4. **Set contributing guide setup time expectations explicitly** — "This takes 10-30 minutes" prevents contributor abandonment. (Source: Bun contributing guide)
+5. **Add AI contribution policy early** — Easier to establish norms before your first AI-assisted PR than after. (Source: Biome, OXC)
+6. **Use `secrets: inherit` for org-internal reusable workflows** — Avoids secret enumeration and future maintenance. (Source: GitHub Actions docs)
+7. **Separate the standard library / docs into its own repo** — Deno, Astro, and others all do this. Separate release cadence, separate contributors. (Source: denoland, withastro)
+8. **Use a `roadmap` repo for public RFCs** — Gives contributors a place to discuss direction without polluting the main issue tracker. (Source: withastro)
+9. **Verify your org's domain** — GitHub org domain verification adds authority and enables SAML SSO. (Source: denoland example)
+10. **Consider Changesets from day one** — Retrofitting automated versioning is painful; starting with it is cheap. (Source: Biome pattern)
+
+## Org Structure Decision Guide
+
+```
+Single product?
+├── Yes → Focused minimal org (oven-sh model)
+│         Repos: product + setup-action + homebrew-tap + awesome-list
+└── No → Multiple products?
+         ├── Related subsystems → Framework org (withastro model)
+         │   Repos: core + compiler + docs + action + roadmap
+         ├── Many small utilities → Ecosystem org (unjs model)
+         │   Each utility = own repo, org README = index
+         └── Large platform → Ecosystem org (denoland model)
+             Repos: runtime + std + frameworks + toolchains
+```
+
+## Further Reading
+
+| Resource | Type | Why Recommended |
+|----------|------|-----------------|
+| [GitHub: Default community health files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file) | Official Docs | Primary reference for `.github` repo mechanics |
+| [GitHub: Reusing workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) | Official Docs | Complete `workflow_call` reference with constraints |
+| [GitHub: Starter workflows](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization) | Official Docs | How to create org-level workflow templates |
+| [withastro org](https://github.com/withastro) | Example | Framework org archetype with roadmap pattern |
+| [tauri-apps CODEOWNERS](https://github.com/tauri-apps/tauri/blob/dev/.github/CODEOWNERS) | Example | Working group CODEOWNERS pattern |
+| [biomejs CONTRIBUTING.md](https://github.com/biomejs/biome/blob/main/CONTRIBUTING.md) | Example | AI disclosure + just commands pattern |
+| [oxc-project CONTRIBUTING.md](https://github.com/oxc-project/oxc/blob/main/CONTRIBUTING.md) | Example | AI accountability policy |
+| [denoland org](https://github.com/denoland) | Example | Large ecosystem org structure |
+| [unjs org](https://github.com/unjs) | Example | Utility ecosystem, many small packages |
+| [GitHub: About CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) | Official Docs | CODEOWNERS syntax and precedence rules |
+
+---
+
+*This guide was synthesized from 18 sources. See `resources/github-org-structure-patterns-sources.json` for full source list.*