|
| 1 | +--- |
| 2 | +name: upgrade-apache-steward |
| 3 | +description: | |
| 4 | + Pull the user's local `airflow-steward` framework checkout to the |
| 5 | + latest `origin/main` and surface what changed — the commits |
| 6 | + pulled, the files touched (with focus on the secure-setup blast |
| 7 | + radius: `.claude/settings.json`, `tools/agent-isolation/`, |
| 8 | + `secure-agent-setup.md`, `secure-agent-internals.md`, |
| 9 | + `pinned-versions.toml`), and the next-step recommendation. Never |
| 10 | + applies user-side propagation itself — that is the job of |
| 11 | + `update-secure-config` (drift report) and the framework |
| 12 | + maintainer's manual re-`cp` of any user-scope script copies that |
| 13 | + drifted. Refuses to act if the working tree is dirty or the |
| 14 | + branch has unpushed commits, since both states are signs the |
| 15 | + user has work in flight that a `git pull` could clobber. |
| 16 | +when_to_use: | |
| 17 | + Invoke when the user says "upgrade apache-steward", "pull the |
| 18 | + framework to latest", "bring my airflow-steward clone up to |
| 19 | + date", or after Claude Code surfaces something new from the |
| 20 | + framework's release notes. Also appropriate as the entry point |
| 21 | + to a periodic update routine — recommended cadence per |
| 22 | + secure-agent-setup.md is once per Claude Code upgrade or once |
| 23 | + a month, whichever comes first; this skill is the *first* step |
| 24 | + of that routine, with `update-secure-config` (read-only drift |
| 25 | + report) and any subsequent re-`cp` / `/sync-shared-config` runs |
| 26 | + following on. Do **not** invoke when the user has uncommitted |
| 27 | + changes in the framework checkout or when they have local |
| 28 | + commits ahead of origin — the skill will refuse and surface |
| 29 | + the state. |
| 30 | +--- |
| 31 | + |
| 32 | +<!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files): |
| 33 | + <project-config> → adopting project's `.apache-steward/` directory --> |
| 34 | + |
| 35 | +# upgrade-apache-steward |
| 36 | + |
| 37 | +This skill is the **upstream** half of the framework's update flow. |
| 38 | +It moves the user's local `airflow-steward` checkout forward to |
| 39 | +`origin/main` and reports what arrived. The downstream half — what |
| 40 | +this upgrade means for the user's *installed* secure setup |
| 41 | +(user-scope script copies, project `.claude/settings.json`, pinned |
| 42 | +tool versions on the host) — is the |
| 43 | +[`update-secure-config`](../update-secure-config/SKILL.md) skill, |
| 44 | +which is read-only and runs naturally as the next step. |
| 45 | + |
| 46 | +## Golden rules |
| 47 | + |
| 48 | +- **Refuse on a dirty working tree.** If `git status --short` in |
| 49 | + the framework checkout reports any modified, staged, or |
| 50 | + conflicted files, surface them and stop. A `git pull` on top of |
| 51 | + uncommitted edits is one of the quickest ways to lose work; the |
| 52 | + user is in flight on something and needs to commit / stash it |
| 53 | + themselves before any pull. Do not auto-stash. |
| 54 | +- **Refuse on local commits ahead of `origin/main`.** Adopters |
| 55 | + generally consume `airflow-steward` as a read-only checkout — |
| 56 | + modifications happen via PRs that land on `main` upstream, then |
| 57 | + the user's checkout is `git pull`ed. If the user has commits |
| 58 | + ahead of `origin/main`, that is either (a) work in progress for |
| 59 | + a PR they have not pushed, or (b) a local fork they are |
| 60 | + maintaining. Both cases need explicit user direction; the skill |
| 61 | + does not assume. |
| 62 | +- **`--ff-only` only.** Use `git pull --ff-only`. Never |
| 63 | + `--rebase`, never a merge commit. The skill is for the simple |
| 64 | + case where the user's checkout is strictly behind upstream; |
| 65 | + anything else is the user's call. If the fast-forward fails |
| 66 | + (history diverged), surface and stop. |
| 67 | +- **Show what arrived.** After a successful pull, surface the |
| 68 | + commit list and a per-file change summary, with explicit focus |
| 69 | + on the secure-setup blast radius (`.claude/settings.json`, |
| 70 | + `tools/agent-isolation/`, `secure-agent-setup.md`, |
| 71 | + `secure-agent-internals.md`, |
| 72 | + `tools/agent-isolation/pinned-versions.toml`). The user should |
| 73 | + walk away knowing whether this upgrade has user-side |
| 74 | + follow-through to do. |
| 75 | +- **Do not propagate to user-scope.** This skill ends at the |
| 76 | + framework checkout. It does not re-`cp` `claude-iso.sh`, |
| 77 | + `sandbox-bypass-warn.sh`, or `sandbox-status-line.sh` into |
| 78 | + `~/.claude/`. It does not edit any project's |
| 79 | + `.claude/settings.json`. It does not bump installed tool |
| 80 | + versions on the host. All of those are surfaced by the |
| 81 | + follow-on `update-secure-config` skill, which is read-only by |
| 82 | + design — the user decides what to apply. |
| 83 | + |
| 84 | +## Walk-through |
| 85 | + |
| 86 | +1. **Locate the framework checkout.** Confirm with the user the |
| 87 | + path to their local `airflow-steward` clone. If they don't |
| 88 | + have one, surface that and stop — they need to `git clone` |
| 89 | + first. |
| 90 | + |
| 91 | +2. **Pre-flight checks.** |
| 92 | + - `git -C <path> status --short` — must be empty. If not, list |
| 93 | + the modified files and stop. |
| 94 | + - `git -C <path> rev-parse --abbrev-ref HEAD` — must be `main` |
| 95 | + (or the local equivalent that tracks `origin/main`). If not, |
| 96 | + name the branch and stop; the user is on a feature branch |
| 97 | + and a pull would be the wrong action. |
| 98 | + - `git -C <path> rev-list --count @{u}..HEAD` — must be `0`. |
| 99 | + If not, surface the local commits and stop. |
| 100 | + |
| 101 | +3. **Fetch + diff against upstream.** |
| 102 | + - `git -C <path> fetch origin` (always, even if behind). |
| 103 | + - `git -C <path> rev-list --count HEAD..@{u}` — if `0`, the |
| 104 | + checkout is already up to date; report and stop. |
| 105 | + - Otherwise, list the commits that will land: |
| 106 | + `git -C <path> log --oneline HEAD..@{u}`. |
| 107 | + - List per-file changes with secure-setup focus: |
| 108 | + `git -C <path> diff --name-status HEAD..@{u}` — call out |
| 109 | + entries under `.claude/settings.json`, |
| 110 | + `tools/agent-isolation/**`, `secure-agent-setup.md`, |
| 111 | + `secure-agent-internals.md`, `pinned-versions.toml` if they |
| 112 | + appear. |
| 113 | + |
| 114 | +4. **Confirm with the user before pulling.** Show the commits |
| 115 | + and the file-touch summary, then ask for explicit OK. The |
| 116 | + skill does not auto-pull on a "looks routine" judgement — |
| 117 | + even a doc-only upgrade can move anchors that the user's |
| 118 | + bookmarks or scripts depend on. |
| 119 | + |
| 120 | +5. **Pull.** `git -C <path> pull --ff-only`. If the fast-forward |
| 121 | + fails for any reason, surface the error and stop. |
| 122 | + |
| 123 | +6. **Post-pull report.** Confirm the new HEAD SHA matches |
| 124 | + `origin/main`. Re-print the commit list (now landed) and the |
| 125 | + file-touch summary with the secure-setup focus. |
| 126 | + |
| 127 | +7. **Hand off to follow-up actions.** Always finish by naming |
| 128 | + the next-step skills the user is likely to want, with explicit |
| 129 | + conditions: |
| 130 | + |
| 131 | + - **If the framework checkout is a submodule of an adopter |
| 132 | + tracker repo** (the path is |
| 133 | + `<adopter-tracker>/.apache-steward/apache-steward/`), remind |
| 134 | + the user that **the parent tracker now has a stale submodule |
| 135 | + pointer**. Pulling the framework standalone moved the |
| 136 | + framework's `HEAD`, but the parent tracker's index still |
| 137 | + records the previous SHA. The user has two options: (a) |
| 138 | + commit the new pointer in the parent tracker |
| 139 | + (`git -C <tracker> add .apache-steward/apache-steward && git |
| 140 | + commit -m "Bump apache-steward submodule"`), or (b) revert |
| 141 | + the framework checkout to the SHA the parent tracker pins. |
| 142 | + Option (a) is the usual path. Either way, a follow-up |
| 143 | + `git -C <tracker> submodule update --init --recursive` on |
| 144 | + any other clone of the tracker is what makes that clone see |
| 145 | + the new framework. Mention the post-merge hook documented in |
| 146 | + `README.md → Adopting the framework` for users who want this |
| 147 | + automatic. |
| 148 | + |
| 149 | + - **Always after a successful pull**, recommend |
| 150 | + [`update-secure-config`](../update-secure-config/SKILL.md) |
| 151 | + to surface user-side drift the upgrade may have introduced |
| 152 | + (new `permissions.deny` patterns the user's tracker repo |
| 153 | + hasn't picked up, drift between user-scope `~/.claude/` |
| 154 | + copies and the just-updated framework source-of-truth, a |
| 155 | + pinned-tool version bump that warrants a host-side |
| 156 | + `npm install` / `apt-get install`). |
| 157 | + |
| 158 | + - **If `tools/agent-isolation/*.sh` files changed in the |
| 159 | + pulled commits AND the user maintains a `~/.claude-config` |
| 160 | + sync repo with copies of those scripts**, recommend |
| 161 | + re-`cp`'ing the updated framework scripts over the |
| 162 | + `~/.claude-config/scripts/` (or |
| 163 | + `~/.claude/agent-isolation/`) copies and then running |
| 164 | + [`sync-shared-config`](../sync-shared-config/SKILL.md) to |
| 165 | + push the propagated changes to the sync remote so other |
| 166 | + machines pick them up. |
| 167 | + |
| 168 | + - **If `pinned-versions.toml` changed**, name the specific |
| 169 | + tool(s) bumped and remind the user that the host install |
| 170 | + commands in `secure-agent-setup.md → Required tools` may |
| 171 | + now reference newer versions; the user runs the `apt-get` |
| 172 | + / `dnf` / `npm install` themselves (the skill does not |
| 173 | + touch system tools). |
| 174 | + |
| 175 | + - **If `.claude/settings.json` changed**, name the kinds of |
| 176 | + changes (new `denyRead`, new `allowedDomains`, new |
| 177 | + `permissions.ask` entry) and remind the user that adopter |
| 178 | + tracker repos copying the framework's settings will need a |
| 179 | + manual merge — the skill does not auto-merge into adopter |
| 180 | + repos. |
| 181 | + |
| 182 | +## What this skill is NOT for |
| 183 | + |
| 184 | +- Not for upgrading a tracker repo (the user's own private |
| 185 | + repo where they consume the framework). Tracker-repo updates |
| 186 | + are normal `git pull` operations the user does themselves. |
| 187 | +- Not for upgrading installed tools (`bubblewrap`, `socat`, |
| 188 | + `claude-code`). Those bumps happen on the host via the |
| 189 | + package manager, surfaced by `check-tool-updates.sh` and |
| 190 | + approved per the |
| 191 | + [Bumping a pinned version](../../../secure-agent-setup.md#bumping-a-pinned-version) |
| 192 | + flow. |
| 193 | +- Not for syncing user-scope edits to `~/.claude-config`. That |
| 194 | + is `sync-shared-config`'s job. |
| 195 | + |
| 196 | +## Failure modes |
| 197 | + |
| 198 | +- **Working tree dirty.** Stop. Surface `git status` output. The |
| 199 | + user commits / stashes themselves before re-invoking. |
| 200 | +- **Local commits ahead of upstream.** Stop. Surface the commit |
| 201 | + list. The user pushes their PR / decides what to do, then |
| 202 | + re-invokes. |
| 203 | +- **Not on `main` (or tracking branch).** Stop. Surface the |
| 204 | + current branch. The user switches branches themselves. |
| 205 | +- **`fetch` fails.** Network or auth issue. Stop and surface. |
| 206 | + The skill does not retry. |
| 207 | +- **`pull --ff-only` fails (diverged history).** This means |
| 208 | + someone force-pushed `main` upstream, or the user's local |
| 209 | + `main` has untracked commits. Stop and surface. The user |
| 210 | + resolves themselves; the skill never `--force`-pulls or |
| 211 | + resets. |
0 commit comments