feat(skills): hook every framework skill into override-consultation protocol#39
Merged
Merged
Conversation
…rotocol
Each of the 15 framework skills (excluding setup-steward, the
bootstrap that is itself the override-management mechanism)
now declares an `## Adopter overrides` section that pins the
skill into the agentic-overrides protocol documented in
docs/setup/agentic-overrides.md.
The standard block in every skill:
## Adopter overrides
Before running the default behaviour documented below, this
skill consults
[`.apache-steward-overrides/<skill-name>.md`](../../../docs/setup/agentic-overrides.md)
in the adopter repo if it exists, and applies any
agent-readable overrides it finds. See
[`docs/setup/agentic-overrides.md`](../../../docs/setup/agentic-overrides.md)
for the contract — what overrides may contain, hard rules,
the reconciliation flow on framework upgrade, upstreaming
guidance.
**Hard rule**: agents NEVER modify the snapshot under
`<adopter-repo>/.apache-steward/`. Local modifications go in
the override file. Framework changes go via PR to
`apache/airflow-steward`.
Skills updated (15):
setup-isolated-setup-install security-issue-import
setup-isolated-setup-update security-issue-import-from-md
setup-isolated-setup-verify security-issue-import-from-pr
setup-shared-config-sync security-issue-invalidate
security-issue-sync
pr-management-code-review security-cve-allocate
pr-management-stats security-issue-deduplicate
pr-management-triage security-issue-fix
Skill not updated:
setup-steward — the bootstrap skill is itself the
override-management mechanism. Overriding it would create
a chicken-and-egg.
Per-skill substitution: the bracketed link target carries the
specific skill name (e.g. `pr-management-triage.md` for the
pr-management-triage skill), so adopter overrides land in the
right file by convention.
Insertion site is the line immediately before the first `##`
section in each SKILL.md — after the detail-files table where
present, before any `## Golden rules` / `## Inputs` /
`## Prerequisites` section. doctoc TOCs regenerated.
Generated-by: Claude Code (Claude Opus 4.7)
6 tasks
potiuk
added a commit
that referenced
this pull request
May 4, 2026
…ft detection (#40) Rewrite setup-steward to support three install methods, split the lock file into committed (project pin) and local (per-machine fetch), and drive every framework-skill invocation through a drift check that compares the two locks. Three install methods (copy-pasteable recipes in docs/setup/install-recipes.md) - svn-zip: signed zip from ASF dist (`https://dist.apache.org/repos/dist/release/<project>/`), the canonical ASF release distribution path. Verified via SHA-512 + OpenPGP. Recommended for production once the framework ships official releases. - git-tag: pinned to a specific git tag — frozen by tag. - git-branch: tracks a branch tip (default: main) — the WIP path during pre-release. Each recipe is a single shell block: adds the right gitignore entries, downloads + verifies + extracts, copies the setup-steward skill into the adopter's skills dir (matching the flat or double-symlinked convention), and tells the user to follow /setup-steward from there. Lock-file split - .apache-steward.lock (committed) — the project's pin: method, url, ref, plus a verification anchor (commit SHA for tag, sha512 for zip). Edited only by /setup-steward; bumping it is a deliberate project-level commit. - .apache-steward.local.lock (gitignored) — what THIS machine actually fetched: source_method, source_url, source_ref, fetched_commit, fetched_at. Per-developer, per-checkout. Drift detection Every framework skill (and /setup-steward verify) compares the local lock to the committed lock at the top of its run. On mismatch: - Method or URL differ → ✗ full re-install - Ref differs (project bumped tag, or git-branch local is behind upstream) → ⚠ sync - svn-zip SHA-512 differs from the committed anchor → ✗ security-flagged; investigate before upgrading The proposal is always /setup-steward upgrade. On user OK, upgrade: 1. Deletes the gitignored snapshot outright. 2. Re-installs per the committed lock. 3. Refreshes gitignored framework-skill symlinks (adds new skills, removes renamed-away ones). 4. Reconciles agentic overrides against the new framework structure (surfaces conflicts; never auto-rewrites). 5. Updates the local lock. Changes - Rewrite setup-steward/SKILL.md, adopt.md, upgrade.md, verify.md to express the new model. - New: docs/setup/install-recipes.md with the three copy-pasteable recipes + explanatory framing. - README's Adopting the framework section split into Bootstrap (shell) + Skill takeover + Subsequent contributors + Drift detection. Out of scope (follow-up): wire the drift check into each framework skill's pre-flight section (alongside the override-consultation hook from #39). 15 skills to touch; mechanical, deferred to keep this PR focused on the mechanism. Generated-by: Claude Code (Claude Opus 4.7)
4 tasks
potiuk
added a commit
that referenced
this pull request
May 4, 2026
#41) Mirror of #39's override-consultation hook for the new drift-detection mechanism that landed in #40. Every framework skill (excluding setup-steward, which IS the drift mechanism) now declares a `## Snapshot drift` section right after its `## Adopter overrides` section. The standard block in every skill: ## Snapshot drift Also at the top of every run, this skill compares the gitignored `.apache-steward.local.lock` (per-machine fetch) against the committed `.apache-steward.lock` (the project pin). On mismatch the skill surfaces the gap and proposes [`/setup-steward upgrade`]. The proposal is non-blocking — the user may defer if they want to run with the local snapshot for now. Drift severity: - method or URL differ → ✗ full re-install - ref differs → ⚠ sync needed - svn-zip SHA-512 mismatches → ✗ security-flagged 15 skills updated: setup-isolated-setup-install security-issue-import setup-isolated-setup-update security-issue-import-from-md setup-isolated-setup-verify security-issue-import-from-pr setup-shared-config-sync security-issue-invalidate security-issue-sync pr-management-code-review security-cve-allocate pr-management-stats security-issue-deduplicate pr-management-triage security-issue-fix Skill not updated: setup-steward — IS the bootstrap + upgrade + verify + override-management skill; the drift check it would perform is the same one its `verify` sub-action exposes. The hook is documented behaviour, not runtime injection. A skill that has the `## Snapshot drift` section commits to performing the check when invoked. Future tooling can enforce mechanically; for now the convention is binding via the published contract. Generated-by: Claude Code (Claude Opus 4.7)
6 tasks
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)
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
Wire every existing framework skill into the agentic-override protocol that landed in #38. Each of the 15 framework skills (excluding
setup-stewarditself) now carries an## Adopter overridessection that opts the skill into the run-time consultation pattern.What changed in each skill
A standard block was inserted right before the first
##section (after the detail-files table where present, before## Golden rules/## Inputs/## Prerequisites):The bracketed link target carries the specific skill's name (e.g.
pr-management-triage.mdfor thepr-management-triageskill), so adopter overrides land in the right file by convention.Skills updated (15)
setup-isolated-setup-installsecurity-issue-importpr-management-code-reviewsetup-isolated-setup-updatesecurity-issue-import-from-mdpr-management-statssetup-isolated-setup-verifysecurity-issue-import-from-prpr-management-triagesetup-shared-config-syncsecurity-issue-invalidatesecurity-issue-syncsecurity-cve-allocatesecurity-issue-deduplicatesecurity-issue-fixNot updated:
setup-steward— it is the bootstrap that manages the override mechanism. Overriding it would create a chicken-and-egg loop.Test plan
prek run --all-fileshooks pass (markdownlint, typos, doctoc, check-placeholders)setup-stewardhas the## Adopter overridessection (visual grep)Out of scope
## Adopter overridessection commits to consulting the file. Future tooling (e.g. a sentinel pre-flight check or a hooks-from-skills mechanism) can enforce mechanically; for now, the convention is binding via the published contract.apache/airflowre-adoption using the new mechanism (PR-C) — separate PR after this lands.🤖 Generated with Claude Code