Apache Steward (to be renamed)

Name: airflow-steward
Author: apache

Heads-up — rename in flight, name not yet chosen. This
repository is currently served from apache/airflow-steward
and is going to be renamed to a different name — not
apache/steward. The current name carries airflow for
legacy reasons, but the framework is project-agnostic (it
stewards multiple ASF project workflows, not just Airflow's),
so the working group steering it will pick a new name that
reflects that. The final name will be chosen by discussion
followed by a poll among the working-group members.

Current candidate names (the list is open for additions
during the week of 4–9 May 2026, after which the poll
opens):

Apache Mentor

Apache Reeve

Apache Guild

Apache Minerva

Apache Magpie

Apache Beacon

Apache Compass

Apache Lexicon

Apache Polyglot

Until the rename lands on the GitHub side, every clone URL and
CI integration still uses the legacy apache/airflow-steward
slug — all path examples in this README and the linked docs use
that slug verbatim. The rename will only change the GitHub
repository slug; existing checkouts will keep working with a
single git remote set-url.

A reusable, project-agnostic framework for ASF-project automation.
Currently in development for ASF projects + Python Core team
friendlies. Not a public marketplace skill — adoption is by
invitation while the framework is pre-release; once we ship via
the ASF release policy,
the marketplace path opens up. See
release-distribution
for the canonical distribution mechanism we will adopt.

[!IMPORTANT]
The motivation, scope, and design commitments behind this work
live in MISSION.md — the draft project-
establishment proposal for an Apache Top-Level Project built on
this framework. Read that for the why; this README is the
how once you've decided to adopt.

How adoption works

The framework uses a snapshot + agentic-override adoption
model. An adopter project commits a single skill —
setup-steward —
into their repo. That skill manages everything else:

Snapshot. setup-steward downloads the framework into
a gitignored <adopter>/.apache-steward/ directory.
The snapshot is a build artefact, not source — refreshed
by /setup-steward upgrade, never committed.
Symlinks. setup-steward symlinks the framework's
skills (security, pr-management, the rest of setup) into
the adopter's existing skill directory, matching whichever
convention the adopter uses (flat .claude/skills/, or the
double-symlink .claude/skills/<n> → .github/skills/<n>/
pattern apache/airflow uses). The symlinks are also
gitignored — they target the gitignored snapshot, so they
would dangle on a fresh clone before /setup-steward runs.
Overrides. Adopter-specific modifications to framework
workflows live as agent-readable markdown under
<adopter>/.apache-steward-overrides/<skill>.md,
committed in the adopter repo. The framework's skills
consult those files at run-time and apply the overrides
before executing default behaviour. See
docs/setup/agentic-overrides.md
for the contract.

No git submodules. No marketplace. No vendored copies of
framework skills. Just one committed skill (the bootstrap),
a gitignored snapshot, and agent-readable override files.

Adopting the framework

Two phases — a shell bootstrap that gets setup-steward
into your repo, then the skill takeover that wires up the
rest interactively.

1. Bootstrap (copy-pasteable shell)

Pick an install method and follow the verbatim recipe in
docs/setup/install-recipes.md:

Method	When to use	Reproducibility
`svn-zip`	Production once ASF official releases ship to `dist.apache.org` (signed + checksummed)	Frozen by version
`git-tag`	Pin a specific framework version	Frozen by tag
`git-branch` (default `main`)	WIP path — track the framework's `main` directly. The default during the framework's pre-release phase.	Tracks tip

Each recipe is a single shell block that:

Adds .apache-steward/, .apache-steward.local.lock, and
the framework-skill symlinks to .gitignore.
Downloads + verifies + extracts the framework into
.apache-steward/ (gitignored — build artefact, not
source).
Copies the
setup-steward
skill into your skills directory, matching your existing
convention (flat .claude/skills/<n>/ or the
double-symlinked .claude/skills/<n> →
.github/skills/<n>/ pattern).

After the recipe completes, the framework snapshot is on
disk and the bootstrap skill is in your repo.

2. Skill takeover

Tell your agent: "adopt apache/airflow-steward in my repo"
(or invoke /setup-steward directly). The skill walks
through the rest:

writes .apache-steward.lock (committed) — the project's
pin: install method + URL + ref + verification anchor;
writes .apache-steward.local.lock (gitignored) — what
this machine actually fetched + when;
asks which skill families (security, pr-management) to
symlink in;
creates the gitignored framework-skill symlinks;
scaffolds .apache-steward-overrides/ (committed) for any
local workflow modifications;
installs a post-checkout git hook so worktrees re-create
runtime state automatically;
updates your project documentation with a brief mention.

After the skill finishes, you commit the small, focused
diff — the bootstrap skill, the .gitignore entries, the
two lock files (committed + gitignore exclusion for the
local one), the overrides scaffold, the doc note — and you're
done. Open a PR.

Subsequent contributors

Future contributors who clone your repo just say "adopt
apache-steward in this repo" (or invoke /setup-steward).
The skill reads .apache-steward.lock (already committed)
and re-installs to the same version your project pinned. No
need to redo the manual recipe — the committed lock is the
project's source-of-truth.

Drift detection

Every framework skill compares the gitignored
.apache-steward.local.lock against the committed
.apache-steward.lock at the top of its run. If they have
drifted (project lead bumped the pin, or the local install
is stale on a main-tracking adopter), the skill surfaces
the gap and proposes /setup-steward upgrade. upgrade
deletes the gitignored snapshot, re-installs per the
committed pin, refreshes the gitignored symlinks, and
reconciles any agentic overrides — see
docs/setup/install-recipes.md
and
.claude/skills/setup-steward/upgrade.md
for the full flow.

Skill families

Three skill families ship in the framework. Pick whichever the
adopter wants to use; symlinks for the picked families land in
the adopter's skill directory.

The Modes column maps each family to the MISSION agent-assistance
taxonomy — see docs/modes.md for what each mode
means and which modes are still proposed vs. shipping today.

Family	Modes	Purpose	Detail
setup	(infra)	Isolated agent setup, framework adoption + maintenance, shared-config sync. The prerequisite — at minimum the `setup-steward` skill itself runs out of this family.	6 skills, `docs/setup/`
security	A, C	16-step security-issue handling lifecycle — from `security@` import through CVE publication. Maintainer-only.	8 skills, `docs/security/`
pr-management	A	Maintainer-facing PR-queue management — triage, stats, deep code review.	3 skills, `docs/pr-management/`

Maintenance

After the initial adoption, the same skill handles ongoing
maintenance:

/setup-steward upgrade — refresh the snapshot to a newer
framework version + reconcile any overrides against the new
framework structure.
/setup-steward verify — read-only health check (snapshot
intact, symlinks live, .gitignore correct, etc.).
/setup-steward override <framework-skill> — open or
scaffold an override file for a framework skill.

Cross-references

MISSION.md — draft project-establishment proposal: motivation, scope, design commitments, initial PMC composition target.
docs/setup/agentic-overrides.md — the contract between adopters who write overrides and framework skills that read them.
docs/prerequisites.md — what a maintainer needs installed before invoking any framework skill (Claude Code, Gmail MCP, GitHub auth, browser, uv, etc.).
AGENTS.md — agent instructions, placeholder convention, framework conventions.
CONTRIBUTING.md — for framework contributors.