This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 7623ab1 feat(setup-steward): add issue family to adopt + upgrade
flows (#209)
7623ab1 is described below
commit 7623ab1179c6bc71e8f8dfbb17d1379c21e38bf3
Author: Yeonguk Choo <[email protected]>
AuthorDate: Mon May 18 19:06:40 2026 +0900
feat(setup-steward): add issue family to adopt + upgrade flows (#209)
---
.claude/skills/setup-steward/SKILL.md | 6 ++---
.claude/skills/setup-steward/adopt.md | 39 ++++++++++++++++++++-------------
.claude/skills/setup-steward/upgrade.md | 37 +++++++++++++++++++++++++++++--
.claude/skills/setup-steward/verify.md | 6 ++---
docs/setup/install-recipes.md | 6 ++++-
5 files changed, 70 insertions(+), 24 deletions(-)
diff --git a/.claude/skills/setup-steward/SKILL.md
b/.claude/skills/setup-steward/SKILL.md
index a585f14..84ac1fd 100644
--- a/.claude/skills/setup-steward/SKILL.md
+++ b/.claude/skills/setup-steward/SKILL.md
@@ -50,7 +50,7 @@ license: Apache-2.0
This skill is **the only framework artefact an adopter
project commits**. Every other apache-steward skill (security,
-pr-management) is a gitignored symlink into the gitignored
+pr-management, issue) is a gitignored symlink into the gitignored
snapshot at `<snapshot-dir>` that this skill manages.
The adoption model is **snapshot + agentic overrides + drift-
@@ -259,7 +259,7 @@ These two families are not exposed in the `skill-families:`
prompt and not stored as user-selectable in the lock files;
every sub-action that wires symlinks always covers them in
addition to the user's opt-in family picks (`security`,
-`pr-management`). Dropping them is *not* a supported
+`pr-management`, `issue`). Dropping them is *not* a supported
configuration — the secure-setup and discovery flows the
framework ships depend on those skills being callable.
@@ -329,7 +329,7 @@ first, then continue.
|---|---|
| `from:<git-ref>` / `from:<version>` | Adopt or upgrade from a specific
framework ref or version. Used during `adopt` (overrides the user prompt) and
`upgrade` (overrides the committed lock for *this run only* — does NOT update
the committed lock). |
| `method:<git-branch\|git-tag\|svn-zip>` | Pick the install method
explicitly. Default during `adopt`: prompt the user. |
-| `skill-families:<list>` | Comma-separated **opt-in** families to symlink
(`security`, `pr-management`). Default on `adopt`: prompt. Default on
`upgrade`: read the families list from `<committed-lock>` / `<local-lock>` and
**ensure every framework skill in those families has a valid symlink** — create
or repair missing / broken symlinks, not just add new ones. The flag never
accepts the always-on families (`setup-*` minus `setup-steward` itself, and
`list-steward-*`); per [Golden rule 8 [...]
+| `skill-families:<list>` | Comma-separated **opt-in** families to symlink
(`security`, `pr-management`, `issue`). Default on `adopt`: prompt. Default on
`upgrade`: read the families list from `<committed-lock>` / `<local-lock>`,
**auto-include any opt-in family the framework has introduced since the lock
was written** (recorded back into the lock), and **ensure every framework skill
in the effective family set has a valid symlink** — create or repair missing /
broken symlinks, not just [...]
| `--purge-overrides` | *(unadopt only)* Also `git rm -r`
`.apache-steward-overrides/`. Default: preserve. |
| `dry-run` | Show what the skill would do without writing anything. |
diff --git a/.claude/skills/setup-steward/adopt.md
b/.claude/skills/setup-steward/adopt.md
index 1a56ce8..b9d9e9b 100644
--- a/.claude/skills/setup-steward/adopt.md
+++ b/.claude/skills/setup-steward/adopt.md
@@ -37,9 +37,9 @@ between automatically:
(overrides the prompt).
- `skill-families:<list>` — comma-separated **opt-in**
families to symlink (default: prompt). Valid values:
- `security`, `pr-management`. The flag does **not** accept
- the always-on families (`setup-*` minus `setup-steward`
- itself, and `list-steward-*`); per
+ `security`, `pr-management`, `issue`. The flag does **not**
+ accept the always-on families (`setup-*` minus
+ `setup-steward` itself, and `list-steward-*`); per
[`SKILL.md` Golden rule 8](SKILL.md#golden-rules) those
are wired up unconditionally on every adopt run and the
user is never asked about them.
@@ -137,7 +137,7 @@ fetch — the recipe ran first and left the snapshot in place.
After the fetch (or skip), confirm
`<snapshot-dir>/.claude/skills/` lists the framework skills
-(`pr-management-*`, `security-*`, `setup-*`,
+(`pr-management-*`, `security-*`, `issue-*`, `setup-*`,
`list-steward-*`). If not, the fetch produced an unexpected
layout — surface and stop.
@@ -241,17 +241,24 @@ for the opt-in set. Otherwise prompt the user with:
has a security tracker.
- **`pr-management`** — five skills for maintainer-facing
PR queue work.
+- **`issue`** — five skills for general-issue tracker work
+ (triage, reassess, reproducer, fix-workflow, stats).
+ Maintainer-only; for projects with a general-issue tracker
+ (JIRA, GitHub Issues, Bugzilla, GitLab Issues) that is
+ *not* the security tracker. See
+
[`docs/issue-management/README.md`](../../../docs/issue-management/README.md).
**Prefer structured Q&A.** When the agent harness offers a
structured-question tool, use a *multi-select* prompt for
-the two opt-in families (`security`, `pr-management`) — the
-families are not mutually exclusive. Pre-select whichever
-family the user named in their initial "adopt" request (e.g.
-*"adopt apache-steward for PR triage"* → `pr-management`
-pre-selected; the user can also tick `security`). If the
-user named no family, default to selecting both for an
-adopter that is a maintainer-driven repo, or to no
-pre-selection otherwise. Free-form chat is the fallback.
+the three opt-in families (`security`, `pr-management`,
+`issue`) — the families are not mutually exclusive.
+Pre-select whichever family the user named in their initial
+"adopt" request (e.g. *"adopt apache-steward for PR triage"*
+→ `pr-management` pre-selected; the user can also tick the
+others). If the user named no family, default to selecting
+all three for an adopter that is a maintainer-driven repo,
+or to no pre-selection otherwise. Free-form chat is the
+fallback.
Do **not** offer `setup-*` or `list-steward-*` as
selectable options in the prompt — they are wired up
@@ -283,12 +290,14 @@ idempotent — re-add them if they're missing.
/.claude/settings.local.json
/.claude/skills/security-*
/.claude/skills/pr-management-*
+/.claude/skills/issue-*
/.claude/skills/setup-isolated-setup-*
/.claude/skills/setup-override-upstream
/.claude/skills/setup-shared-config-sync
/.claude/skills/list-steward-*
/.github/skills/security-*
/.github/skills/pr-management-*
+/.github/skills/issue-*
/.github/skills/setup-isolated-setup-*
/.github/skills/setup-override-upstream
/.github/skills/setup-shared-config-sync
@@ -325,9 +334,9 @@ relative path into
The set of skills to link is the **union** of:
1. **The opt-in families the user picked in Step 5**
- (`security`, `pr-management`, or both). Each contributes
- every framework skill in the snapshot whose name starts
- with that family's prefix.
+ (`security`, `pr-management`, `issue`, or any
+ combination). Each contributes every framework skill in
+ the snapshot whose name starts with that family's prefix.
2. **The always-on families** (no user input — per
[`SKILL.md` Golden rule 8](SKILL.md#golden-rules)):
every `setup-*` skill *except* `setup-steward` itself,
diff --git a/.claude/skills/setup-steward/upgrade.md
b/.claude/skills/setup-steward/upgrade.md
index 82de293..9112ea2 100644
--- a/.claude/skills/setup-steward/upgrade.md
+++ b/.claude/skills/setup-steward/upgrade.md
@@ -226,7 +226,22 @@ silent on families). Compose the **effective family set**
for this upgrade as:
- **Opt-in families** the project recorded (`security`,
- `pr-management`, or both).
+ `pr-management`, `issue`, or any combination).
+- **Newly-introduced opt-in families** — families the
+ framework now ships that did not exist when the lock was
+ written. Detect by enumerating the prefixes of opt-in
+ families in the snapshot (`security-*`, `pr-management-*`,
+ `issue-*`) and comparing against the lock's recorded set.
+ Any family present in the snapshot but absent from the
+ lock is auto-added to the effective set on this run, and
+ the addition is **written back to `<committed-lock>`**
+ (same fields as
+ [`adopt.md` Step 4](adopt.md#step-4--write-committed-lock-fresh-only)).
+ Surface the added family in the upgrade summary so the
+ operator sees it; do not prompt — per the framework's
+ policy each opt-in family is maintainer-grade and an
+ adopter that has already adopted the framework is in scope
+ for any opt-in family the framework grows.
- **Always-on families** (always added — never read from
the lock, never user-configurable, per
[`SKILL.md` Golden rule 8](SKILL.md#golden-rules)):
@@ -239,6 +254,18 @@ on disk — it expands automatically when the framework adds
a new `setup-*` or `list-steward-*` skill in a release, and
contracts on a rename / removal without code changes here.
+Before creating symlinks for a newly-introduced opt-in
+family, reconcile the adopter's `.gitignore` so the new
+family's snapshot symlinks are gitignored. Append the
+`.gitignore` lines from
+[`adopt.md` Step 7](adopt.md#step-7--gitignore-entries-fresh-only)
+for the new family's prefix (e.g. `/.claude/skills/issue-*`
+and the `.github/skills/` mirror when the adopter uses the
+double-symlinked convention). The append is idempotent —
+skip lines that already exist. The same idempotence covers
+adopters whose `.gitignore` already had the entries (e.g.
+from a manually-edited block or a previous adopt run).
+
The post-upgrade state must be: *every framework skill in
the new snapshot that belongs to the effective family set
has a valid symlink in `<adopter-skills-dir>`*, and *no
@@ -441,7 +468,8 @@ setup-steward (bootstrap):
✓ in sync OR ↻ overwritten from snapshot (reloaded in-flight)
Symlinks (main checkout):
- Opt-in families: <security>, <pr-management> (from lock)
+ Opt-in families: <security>, <pr-management>, <issue> (from lock)
+ Newly added opt-in: <issue> (introduced since lock was written; lock
updated)
Always-on families: setup-*, list-steward-* (per Golden rule 8)
✓ <list of unchanged symlinks>
+ <list of newly-created symlinks (skill present in the
@@ -450,6 +478,11 @@ Symlinks (main checkout):
at the wrong path)>
- <list of removed stale symlinks>
+.gitignore reconcile:
+ ✓ all opt-in family prefixes already gitignored OR
+ + <list of /.claude/skills/<prefix>-* and /.github/skills/<prefix>-*
+ lines appended for newly-introduced opt-in families>
+
Hooks + local config:
✓ <list of files in sync>
↻ <list of files re-synced from the snapshot>
diff --git a/.claude/skills/setup-steward/verify.md
b/.claude/skills/setup-steward/verify.md
index 7b56603..6f02157 100644
--- a/.claude/skills/setup-steward/verify.md
+++ b/.claude/skills/setup-steward/verify.md
@@ -115,9 +115,9 @@ Check that the entries from
Recommended:
- The framework-skill symlink patterns (`security-*`,
- `pr-management-*`, `setup-isolated-setup-*`,
- `setup-shared-config-sync`) under both `.claude/skills/`
- and `.github/skills/` per convention.
+ `pr-management-*`, `issue-*`, `setup-isolated-setup-*`,
+ `setup-shared-config-sync`, `list-steward-*`) under both
+ `.claude/skills/` and `.github/skills/` per convention.
- ✗ if `/.apache-steward/` is not gitignored — the snapshot
is at risk of being accidentally committed.
diff --git a/docs/setup/install-recipes.md b/docs/setup/install-recipes.md
index 4e2c6b7..6a8ca43 100644
--- a/docs/setup/install-recipes.md
+++ b/docs/setup/install-recipes.md
@@ -118,14 +118,18 @@ cat >> .gitignore <<'GITIGNORE'
# Symlinks created by /setup-steward into the gitignored snapshot.
/.claude/skills/security-*
/.claude/skills/pr-management-*
+/.claude/skills/issue-*
/.claude/skills/setup-isolated-setup-*
/.claude/skills/setup-shared-config-sync
+/.claude/skills/list-steward-*
# Mirror the same patterns under .github/skills/ if your repo uses
# the double-symlinked convention.
/.github/skills/security-*
/.github/skills/pr-management-*
+/.github/skills/issue-*
/.github/skills/setup-isolated-setup-*
/.github/skills/setup-shared-config-sync
+/.github/skills/list-steward-*
GITIGNORE
# 4. Tell your agent: "follow /setup-steward to finish adopting steward."
@@ -205,7 +209,7 @@ follow .claude/skills/setup-steward to adopt steward
the rest:
1. **Pick the skill families** to symlink in (`security`,
- `pr-management`).
+ `pr-management`, `issue`).
2. **Write the lock files**:
- `.apache-steward.lock` (**committed**) — the project's pin
(the method + URL + ref you used in the recipe). Future
