Ecosystem & Cross-Repo Discovery

One Manifest — One Source of Truth

Only the primary platform repository has a foundry.json. Satellite repos (API libraries, extracted services, docs) are referenced in the ecosystem block — they never get their own manifest.

Naming Convention

Cross-repo discovery is purely convention-based. Given a platform name, Foundry derives two values:

name: "An Average Platform"
  → repository: "an-average-platform"  (slug — all lowercase, spaces → hyphens)
  → prefix:     "aap"                  (first letter of each word)

Foundry then discovers repos in the GitHub org:

Primary repo: exact match on repository name (an-average-platform)
Satellite repos: name starts with {prefix}- (aap-api-lib, aap-billing-service)

Ecosystem Block

"ecosystem": {
  "organization": "FoundryMedia",
  "prefix": "aap",
  "repositories": {
    "api-lib": {
      "repository": "aap-api-lib",
      "relationship": "contracts"
    }
  },
  "apiLib": {
    "repository": "aap-api-lib",
    "packageRegistry": "github-packages",
    "groupId": "com.aap",
    "modules": { ... }
  }
}

Field	Description
`organization`	GitHub org that owns all platform repos
`prefix`	Short prefix for satellite repo naming (auto-derived if omitted)
`repositories`	Known satellite repos and their relationships
`apiLib`	API library config (Maven coordinates, modules, versions)

Repository Relationships

Relationship	Meaning
`contracts`	API specs, generated code, shared models
`extracted-service`	Service extracted from the primary repo
`package`	Shared library / utility package
`docs`	Documentation repository
`infra`	Infrastructure / Terraform / deployment
`other`	Anything else

GitHub Integration

Use foundry github discover to test discovery. Foundry calls the GitHub REST API to list repos in the org and filter by the naming convention.

Tokens are resolved from environment variables, the GitHub CLI, or .foundry/config.yml — never committed. See foundry github for details.