Project-agnosticism (de-ASF coupling)

September 8, 2026 · View on GitHub

title: Project-agnosticism (de-ASF coupling) status: experimental kind: feature mode: infra source: > MISSION.md § Abstract and § Affordability and vendor neutrality ("'project' means both an ASF PMC and any non-ASF community, neither is a second-class citizen"). README.md § Skill families. The placeholder + adapter contract in adapters.md and adoption-and-setup.md, and the backend-flag model proven in docs/release-management/ (distribution / approval / announcement backends). acceptance:

  • No shipped skill hardcodes an ASF-only assumption a non-ASF adopter cannot satisfy; every ASF-specific surface is a placeholder, an adapter backend, or a capability-flag branch with a documented non-ASF path and a sensible default.
  • Behavioural branches that differ by ecosystem (list vote vs PR-approval, svn dist vs github-releases, ICLA vs DCO, mailing-list intake vs GitHub discussion) are selected by a declared <project-config> flag, not by editing the skill.
  • The catalogue stays runnable by an ASF adopter unchanged: ASF is the default profile, not a removed one.

Project-agnosticism (de-ASF coupling)

What it does

Keeps the skill catalogue usable by any open-source community, not just ASF projects, by ensuring every ASF-specific assumption lives behind one of three generalisation mechanisms rather than being baked into a skill. MISSION makes non-ASF adopters first-class; this area is the standing audit and the mechanism that holds that promise as the catalogue grows.

The three mechanisms, in order of preference:

  1. Placeholders for project-specific values (<tracker>, <upstream>, <security-list>, <default-branch>, …), resolved from <project-config>/. This is the default and already widely used.
  2. Adapters for swapping the backing system a step talks to (tools/gmail, tools/ponymail, tools/jira, tools/github, tools/mail-source). See adapters.md.
  3. Capability / backend flags for the harder case: a step whose workflow itself differs by ecosystem. The adopter declares the profile in <project-config> and the skill branches on it, keeping the step sequence identical while only the emitted commands / wording change. This is the "conditional flags" mechanism, already modelled in docs/release-management/ (release_dist_backend, release_approval_mechanism, release_announce_backend).

Where it lives

  • The placeholder + config-resolution contract: adapters.md, adoption-and-setup.md, and the adopter scaffold projects/_template/.
  • The backend-flag precedent: docs/release-management/README.md (§ adopter backends) and projects/_template/release-management-config.md.
  • The per-family organization: scope (formerly the binary asf: true / asf: false flag), declared in each family's scope banner at the top of docs/<family>/README.md and surfaced in the Scope column of the family tables in README.md and docs/index.md. An organization-scoped family declares organization: <org> (naming a directory under organizations/); an organization-agnostic family declares no scope key at all. Only release-management and contributor-growth carry organization: ASF: their core purpose is an ASF Foundation process (the release lifecycle, the contributor-to-committer path). This is a narrower lens than the residual-coupling audit list below — a family can be agnostic (no organization:, runs anywhere) and still carry ASF-flavoured defaults that the coupling audit tracks (security is the clearest case; those defaults now live in organizations/ASF/). Skills, tools, and tool adapters declare the same membership — see organizations/README.md § Membership.
  • The skills carrying residual ASF coupling to audit, by family:
    • security (agnostic): generic at its core, but ships an ASF-flavoured default profile — security@-style intake and the ASF security-team relay (security-issue-import-via-forwarder), CVE allocation assuming an ASF CNA (security-cve-allocate), Vulnogram as the CVE tool — all swappable for GHSA / MITRE-CNA via the config layer.
    • contributor / committer growth (organization: ASF): committer-onboarding (ICLA gate, PMC vote semantics, dev@ announce), contributor-nomination (committer-vs-PMC roster framing).
    • release-management (organization: ASF): the whole ASF release ritual, already designed with backend flags; the audit confirms the non-ASF paths stay first-class as the skills land.
    • any skill whose prose names apache.org lists, svn dist trees, incubator, or ASF-only governance steps without a flag.

Behaviour & contract

  • ASF is the default profile, never the only one. Generalising a skill must not regress the ASF path; the ASF behaviour becomes the default value of the new flag / adapter, so an ASF adopter sees no change.
  • Prefer the lightest mechanism. A value goes in a placeholder; a system swap goes in an adapter; only a genuine workflow fork gets a capability flag. Do not add a flag where a placeholder suffices.
  • Every flag has a documented non-ASF path. A capability flag that only enumerates ASF options (e.g. an approval mechanism with just dev-list-vote) is incomplete; it must name at least one non-ASF option (pr-approval, maintainer-roster, github-discussion, …) and describe the adopter-facing default.
  • <PROJECT> and <project> are two placeholders, not one casing choice. <PROJECT> is the display name (Apache Foo); <project> is the infrastructure slug used inside hostnames, addresses, and URL paths (foo). Substituting one for the other yields a value that is wrong rather than mis-cased. Because they differ only by case, a fixed-string lint written for one does not catch the other, so tools/dev/check-placeholders.sh carries both spellings and also matches spaced variants (name: "<project>" as well as name:"<project>"), since YAML, JSON, and GraphQL all accept either form and pinning one lets the other through.
  • Advisory, not paternalistic. The audit surfaces candidate coupling for a maintainer to judge; some ASF strings are legitimate (examples, the ASF default profile, ASF-specific docs). It does not auto-rewrite.
  • Template and example profiles stay comparable. projects/_template/ is the adopter contract; projects/non-asf-example/ is the proof that a non-ASF adopter can satisfy that contract. Required files and config keys should be structurally comparable, with omissions explained rather than silently drifting.

Out of scope

  • Removing or de-prioritising ASF support: ASF is the reference adopter and the default profile.
  • The privacy gate and sandbox (privacy-llm-gate.md, agent-isolation-sandbox.md), which are already project-agnostic.
  • The runtime adapter implementations themselves (that is adapters.md); this area governs the coupling audit and the flag contract, not the adapter code.

Acceptance criteria

  1. Every shipped skill is auditable for ASF coupling, and each residual coupling is a placeholder, an adapter backend, or a capability-flag branch with a non-ASF default.
  2. Ecosystem-divergent workflow steps branch on a declared <project-config> flag, not on skill edits.
  3. The ASF profile runs the catalogue unchanged (default-valued flags), and a non-ASF profile can be declared without editing any skill body.
  4. The template profile and non-ASF example expose the same required config surfaces, except where the example documents an intentional omission or an organization-inherited default.

Validation

# Advisory sweep: surface ASF-coupled tokens in skill bodies that should
# be a placeholder, an adapter backend, or a capability-flag branch.
# Expected to flag legitimate ASF-default examples too; a human judges.
grep -rInE 'apache\.org|[[:alpha:]]+@apache|\bdev@|\bannounce@|\bICLA\b|\bsvn (mv|co|commit)|\bincubator\b|Vulnogram' skills/ \
  | grep -vE '<[a-z-]+>' | head -40
uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate

Known gaps

  • ASF-coupling lint is advisory only. Check #10 in tools/skill-and-tool-validator (SOFT category asf_coupling) surfaces coupled tokens automatically on every validator run. As of the low-confidence-asf-coupling-pass work (mechanical cleanup + suppression of low-confidence hits for organization:-scoped families), the live catalogue produces 3 asf-coupling warnings — release-audit-report and release-promote (svn invocations, remedy:adapter, pending the #602 Subversion backend) and dependency-license-audit (a bare PMC reference). Other bare PMC / ICLA / announce@apache.org references are inside org-scoped skills where ASF-specific text is appropriate. No remaining tooling gap — the lint exists and a human judges any new hits. In the same pass: skills/pr-management-triage/comment-templates.md was generalised — security@apache.org replaced with the <security-list> placeholder and the "ASF vulnerability-handling process" wording replaced with a project-agnostic phrase; the design rationale in skills/pr-management-triage/rationale.md was anonymised to remove the project-specific mailing list reference that appeared in a historical note.
  • Non-ASF adopter profile fixture shipped — projects/non-asf-example/ contains a worked non-ASF profile (Velox Stream: GitHub-hosted, DCO, GHSA intake, MITRE CNA, GitHub Releases). The tools/skill-evals/evals/non-asf-profile-smoke/ eval suite (15 cases across 6 steps) drives issue-stale-sweep, security intake, release-backend selection, contributor governance, and reviewer routing through it, and asserts each proceeds without any Apache-specific fields, turning acceptance #3 into a measurable gate.
  • The capability-flag vocabulary for security intake and CVE allocation is now documented in projects/_template/security-intake-config.md (intake channel, forwarder relay, CNA tool, allocation gate, and new disclosure_governance flags). Skills read these flags in follow-on updates as each flag is wired in.
  • Contributor intake and governance capability flags are now declared in projects/_template/committer-onboarding-config.md (icla / dco / no-cla for intake; asf-pmc / github-codeowners / maintainer-roster for governance), added by the capability-flags-committer-intake work item. The committer-onboarding skill currently defaults to ASF-PMC / ICLA; a follow-on update will wire it to read these flags at run time. Remaining coupling in the live catalogue (bare PMC, ICLA, announce@apache.org) is surfaced by the advisory lint (check #10 in skill-and-tool-validator) for human judgement.
  • Template/profile drift is now mechanically checked. Check #15 in tools/skill-and-tool-validator (template-drift category, SOFT) compares projects/_template/ and projects/non-asf-example/: files linked in the example README must exist on disk, every config file in the example must be documented in its README, and shared config files (all except project.md and README.md, which differ by design) must have the same h2 section headings. The live tree produces no template-drift violations.