feat(skills): add setup-steward — snapshot+overrides adoption mechanism#38
Merged
potiuk merged 1 commit intoMay 3, 2026
Merged
Conversation
Replace the submodule-based adoption design with snapshot +
agentic overrides. One skill (setup-steward) lives committed in
the adopter repo; everything else flows from it.
The setup-steward skill (multi-file)
.claude/skills/setup-steward/
├── SKILL.md entry point + sub-action dispatch + golden rules
├── adopt.md first-time install — detect convention,
│ download snapshot, gitignore, symlinks,
│ .apache-steward-overrides/ scaffold,
│ post-checkout hook, project-doc note
├── upgrade.md refresh snapshot + reconcile overrides
├── verify.md read-only health check
├── conventions.md skills-dir convention auto-detection
│ (flat vs double-symlinked)
└── overrides.md interactive override scaffolder
Sub-actions
/setup-steward — first-time adoption (default)
/setup-steward upgrade — refresh the gitignored snapshot
/setup-steward verify — health check
/setup-steward override <skill>
— open / scaffold an override
Replaces (folded into setup-steward as sub-actions)
- setup-steward-upgrade → /setup-steward upgrade (snapshot
mechanics, not git pull)
- setup-steward-verify → /setup-steward verify
Adoption mechanism
- The framework lives at <adopter>/.apache-steward/ as a
gitignored --depth=1 git checkout (or, once official ASF
releases ship per
https://www.apache.org/legal/release-policy.html, a signed
tarball from the canonical ASF dist mirrors per
https://infra.apache.org/release-distribution.html).
- Framework skills are accessed via gitignored symlinks in the
adopter's existing skill directory, matching whichever
convention the adopter uses (flat or double-symlinked).
- Adopter modifications to framework workflows live as
agent-readable markdown under .apache-steward-overrides/,
committed in the adopter repo. The framework's skills consult
those files at run-time and apply the overrides before
executing default behaviour. Hard rule: agents NEVER modify
the snapshot — local mods go to overrides; framework changes
go via PR to apache/airflow-steward.
Agentic-override design contract
New top-level docs/setup/agentic-overrides.md captures:
- where override files live and what they may contain
- how a framework skill consults overrides at run-time
- hard rules on what the framework agent will never do
- reconciliation flow on framework upgrade
- upstreaming an override (PR against the framework)
- why agentic, not declarative (variance trade-off accepted
in exchange for restructure-survival + free-form expression)
README rewrite
Top-level README is reshaped around the new adoption flow:
- "How adoption works" (snapshot + overrides in 3 bullets)
- "Adopting the framework" (`tell your agent: 'adopt
apache/airflow-steward in my repo'` + the 3-step agentic
flow that follows)
- The rename heads-up + candidate-name list (kept from apache#37)
- Skill-family overview (setup / security / pr-management)
- Maintenance commands
Generated-by: Claude Code (Claude Opus 4.7)
This was referenced May 3, 2026
potiuk
added a commit
that referenced
this pull request
May 4, 2026
…to framework PR (#43) New framework skill that walks an adopter through promoting a local `.apache-steward-overrides/<skill>.md` file into a PR against `apache/airflow-steward`. Closes the loop on the override mechanism: overrides start out as adopter-local modifications (per #38 + #39), and when one stops being project-specific and starts looking like a missing feature, this skill is the path to upstream it. Walkthrough Step 0 — Pre-flight (adopter has overrides + snapshot is current + framework clone available) Step 1 — Pick the override (auto-pick when only one; prompt when multiple) Step 2 — Read the override + the framework skill it modifies Step 3 — Decide if upstreamable. Four buckets: - project-specific → STOP (keep as override) - missing feature → continue - better default → continue - refactor a step → continue Step 4 — Design the framework-level abstraction. Four possible shapes (config knob / change default / new optional step / refactor existing step) Step 5 — Implement in user's apache-steward clone, run framework pre-commit Step 6 — Confirm + open PR (assistant proposes, user fires) Step 7 — Surface post-merge cleanup pointer (after merge + /setup-steward upgrade, delete the override file) Golden rules 1. Not every override should be upstreamed. 2. Write to the framework clone, never to the gitignored snapshot. 3. Assistant proposes, user fires (clone, branch, commit, push, PR — every state-changing action confirmed first). 4. Decouple PR open from override deletion (the cleanup happens AFTER the PR merges, not preemptively). Includes the standard pre-flight blocks per the framework's conventions: - ## Adopter overrides — consults .apache-steward-overrides/setup-override-upstream.md (per #39). - ## Snapshot drift — compares local lock vs committed lock (per #41), with a doubly-important note: the skill designs against the snapshot's framework code, so stale snapshot leads to wrong abstraction design. Generated-by: Claude Code (Claude Opus 4.7)
potiuk
pushed a commit
that referenced
this pull request
May 4, 2026
…d-overrides/user.md (#45) The framework adopted a snapshot+overrides architecture in PR #38. Under that design, per-user configuration (PMC status, local clone paths, optional tool backends) lives in the adopter repo, not in the framework. The security skills, however, still referenced the legacy config/user.md path from the pre-snapshot architecture. Changes: - Update 4 security skills (sync, import, fix, cve-allocate) to read from .apache-steward-overrides/user.md instead of config/user.md. - Add Step 9b to setup-steward/adopt.md to scaffold a user.md template during first-time adoption. - Update docs and tool adapters that referenced config/user.md: onboarding, prerequisites, gmail, ponymail, fix-workflow template. The fallback-interactive behaviour is preserved: when the file is missing, skills ask the user and offer to save the answer back. Fixes the structural gap where the framework docs described a config/ layer that was never created in the snapshot-based architecture. Signed-off-by: André Ahlert <andre@aex.partners>
andreahlert
added
the
mode:platform
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replace the submodule-based adoption design with snapshot + agentic overrides. Adopters commit a single skill (
setup-steward); everything else flows from it.The previous design (
apache/airflow#66283, the submodule + adopter-config PR) is closed and superseded.How the new mechanism works
setup-stewarddownloads the framework as a--depth=1git checkout (or, once ASF official releases ship, a signed tarball from the canonical ASF distribution mirror) into a gitignored<adopter>/.apache-steward/. Snapshot is a build artefact, not source.setup-stewardsymlinks the framework's skills into the adopter's existing skill directory, matching whichever convention the adopter uses (flat.claude/skills/<name>/or the double-symlinked.claude/skills/<n>→.github/skills/<n>/pattern apache/airflow uses today). The symlinks are also gitignored — they target the gitignored snapshot.<adopter>/.apache-steward-overrides/<framework-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.Hard rule baked into agent instructions: NEVER modify the snapshot. Local mods go to overrides. Framework changes go via PR to
apache/airflow-steward.What lands in this PR
.claude/skills/setup-steward/— multi-file skill:SKILL.md— entry, sub-action dispatch, 5 golden rulesadopt.md— first-time install walk-through (Step 0–8)upgrade.md— refresh snapshot + reconcile overridesverify.md— read-only 8-check health reportconventions.md— skills-dir convention auto-detectionoverrides.md— interactive override scaffolderSub-actions:
/setup-steward/setup-steward upgrade/setup-steward verify/setup-steward override <framework-skill>docs/setup/agentic-overrides.md— design contract for the override mechanism: where override files live, what they may contain, how framework skills consult them at run-time, hard rules, reconciliation flow on framework upgrade, upstreaming guidance, and the rationale for agentic-not-declarative.README rewrite — top-level README reshaped around the new adoption flow:
Folded into setup-steward, removed:
setup-steward-upgrade→/setup-steward upgrade(snapshot mechanics, not git pull)setup-steward-verify→/setup-steward verifyTest plan
prek run --all-fileshooks pass (markdownlint, typos, doctoc, check-placeholders)apache/airflowliterals in framework files (allowlisted viae.g.markers where the airflow project is the canonical example for the double-symlinked convention)setup-stewardskill registers with Claude Code's available-skills list (live-detection picked it up in-session)docs/setup/agentic-overrides.mdfor soundnessadopt.mdSteps 0–8 against a fresh adopter repo to spot gapsOut of scope (follow-ups)
security-*andpr-management-*skills into the override-consultation protocol (one-line per skill: "before running, check.apache-steward-overrides/<this-skill>.md"). Tracked as PR-B.apache/airflowre-adoption using this mechanism (was#66283; tracked as PR-C).🤖 Generated with Claude Code