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 a6d4a87 feat(setup-steward): richer Step 11 doc-update flow (#111)
a6d4a87 is described below
commit a6d4a8798530e0061e781e046fe88953730d0f18
Author: Jarek Potiuk <[email protected]>
AuthorDate: Mon May 11 04:00:14 2026 +0200
feat(setup-steward): richer Step 11 doc-update flow (#111)
Step 11 (project doc updates) previously said only "add a brief
paragraph to README.md or CONTRIBUTING.md noting three things",
which left every adopter to reinvent the wording. Replace it with:
- a copy-pasteable `## Agent-assisted contribution
(apache-steward)` section for README.md, with substitution
guidance for the adopter's skill-family choices and the
flat-vs-double-symlinked path convention;
- an explicit note about PyPI sync markers (avoid leaking the
adoption blurb into the published PyPI description on
projects that round-trip README.md to PyPI);
- a separate AGENTS.md template that agent harnesses see first,
with a cross-reference back to the README section so the
agent lands on the human-readable summary rather than
duplicating the prose;
- a "do not create AGENTS.md if it does not already exist"
guardrail (empty file is more noise than signal);
- a doctoc/TOC-hook note so adopters know to expect a second
commit touching the auto-updated TOC block;
- CONTRIBUTING.md as a documented fallback when README.md is
absent or strictly off-limits.
Update verify.md check 9 in parallel: grep for both
`apache-steward` and `/setup-steward` tokens in README.md (and
the cross-reference link in AGENTS.md if the file exists)
rather than the previous "mentions the framework somewhere"
hand-wave. Stay at ⚠ severity — these are nice-to-have, not
blocking.
Motivated by the apache/airflow adoption PR
(apache/airflow#66677) which added both files by hand; the
templates here capture what landed there so the next adopter
gets it from the skill rather than from the airflow PR diff.
---
.claude/skills/setup-steward/adopt.md | 127 +++++++++++++++++++++++++++++----
.claude/skills/setup-steward/verify.md | 26 +++++--
2 files changed, 137 insertions(+), 16 deletions(-)
diff --git a/.claude/skills/setup-steward/adopt.md
b/.claude/skills/setup-steward/adopt.md
index d85befe..33e3842 100644
--- a/.claude/skills/setup-steward/adopt.md
+++ b/.claude/skills/setup-steward/adopt.md
@@ -379,18 +379,121 @@ hook content to the user before writing.
## Step 11 — Project doc updates (FRESH only)
-Add (or extend) a brief paragraph in the adopter's
-`README.md` or `CONTRIBUTING.md` (whichever already mentions
-agents / skills) noting:
-
-- the project adopts apache-steward via the snapshot
- mechanism;
-- a fresh clone needs `/setup-steward` to populate the
- framework before any framework skill is invocable;
-- adopter-specific modifications live in
- `.apache-steward-overrides/`.
-
-Surface the doc diff to the user before writing.
+Update two adopter-facing docs so contributors discover the
+framework before they hit a "skill not found" error:
+
+1. **`README.md` (contributor-facing summary, REQUIRED if
+ the file exists).** This is the doc most fresh-clone
+ contributors read first. Add a dedicated section. If the
+ project uses PyPI-sync markers (e.g.
+ `<!-- START Contributing ... -->` / `<!-- END Contributing ... -->`),
+ place the new section **outside** any sync block so the
+ adoption note does not leak into the published PyPI
+ description.
+
+ Suggested template — substitute the adopter's name and
+ the skill families they actually installed:
+
+ ```markdown
+ ## Agent-assisted contribution (apache-steward)
+
+ This repo adopts the
+ [`apache/airflow-steward`](https://github.com/apache/airflow-steward)
+ framework via a snapshot mechanism. The framework provides
+ maintainer-facing skills (e.g. `pr-management-triage`,
+ `pr-management-code-review`, `pr-management-stats`,
+ `pr-management-mentor`, and the `security-*` family)
+ exposed as agent skills in agent harnesses such as Claude
+ Code.
+
+ The framework is **not** vendored — it lives as a
+ gitignored snapshot under `.apache-steward/`, fetched on
+ demand from the version pinned in the committed
+ [`.apache-steward.lock`](.apache-steward.lock). The only
+ framework artefact committed to this repo is the
+ `setup-steward` skill at
+ [`.github/skills/setup-steward/`](.github/skills/setup-steward/);
+ everything else is a gitignored symlink the setup skill
+ wires up.
+
+ A fresh clone needs the snapshot populated before any
+ framework skill is invocable. In your agent harness, run:
+
+ /setup-steward
+
+ (or follow [`.claude/skills/setup-steward/`](.claude/skills/setup-steward/))
+ to fetch the snapshot per the committed lock, scaffold the
+ gitignored symlinks, and install the post-checkout hook
+ that re-creates them on each worktree checkout.
+
+ Adopter-specific modifications to framework workflows live
+ in [`.apache-steward-overrides/`](.apache-steward-overrides/)
+ (committed) — never edit the snapshot directly. Framework
+ changes go via PR to
+ [`apache/airflow-steward`](https://github.com/apache/airflow-steward).
+ ```
+
+ Trim the skill-family list to what was actually picked in
+ Step 5 (only mention `security-*` if the adopter installed
+ that family, etc.). Adjust the skill paths to the adopter's
+ convention (flat vs double-symlinked — see
+ [`conventions.md`](conventions.md)). Skip this sub-step
+ entirely if `README.md` does not exist.
+
+2. **`AGENTS.md` (agent-facing detail, ONLY if the file
+ already exists).** Agent harnesses load this file
+ automatically; a short section here tells the agent the
+ adoption is in place and where to find the contributor
+ summary. Cross-reference back to the `README.md` section
+ you just wrote so the agent lands on the human-readable
+ summary first.
+
+ Suggested template:
+
+ ```markdown
+ ## apache-steward framework
+
+ This repo adopts the
+ [`apache/airflow-steward`](https://github.com/apache/airflow-steward)
+ framework via the snapshot mechanism. The framework
+ provides the `pr-management-*` skills; they are gitignored
+ symlinks into the `.apache-steward/` snapshot directory.
+
+ A fresh clone needs the snapshot populated before any
+ framework skill is invocable. Run `/setup-steward` (or
+ follow [`.claude/skills/setup-steward/`](.claude/skills/setup-steward/))
+ to fetch it per the committed
+ [`.apache-steward.lock`](.apache-steward.lock). The
+ contributor-facing summary of the adoption + setup flow
+ lives in the
+ [Agent-assisted contribution section of
`README.md`](README.md#agent-assisted-contribution-apache-steward).
+
+ Adopter-specific modifications to framework-skill
+ workflows live in
+ [`.apache-steward-overrides/`](.apache-steward-overrides/)
+ — never edit the snapshot directly. Framework changes go
+ via PR to
+ [`apache/airflow-steward`](https://github.com/apache/airflow-steward).
+ ```
+
+ Do not create `AGENTS.md` if it does not already exist —
+ the contributor-facing section in `README.md` is the
+ authoritative entry-point, and an empty `AGENTS.md` would
+ be more noise than signal.
+
+3. **`CONTRIBUTING.md` (fallback only).** If `README.md` is
+ absent or strictly off-limits (some projects vendor it
+ from another source and rebuild on release), add the
+ `README.md` template content here instead.
+
+**Doctoc and other auto-update hooks.** If the adopter
+runs `doctoc` or similar README-TOC hooks, expect the next
+commit to also touch the TOC block. Either run the hook
+yourself before staging or note it in the commit message.
+
+Surface the rendered diff (`git diff README.md AGENTS.md`)
+to the user before writing. The user confirms once for the
+whole doc set; do not ask separately per file.
## Step 12 — Sanity check
diff --git a/.claude/skills/setup-steward/verify.md
b/.claude/skills/setup-steward/verify.md
index 2c638b1..e9bfc21 100644
--- a/.claude/skills/setup-steward/verify.md
+++ b/.claude/skills/setup-steward/verify.md
@@ -169,10 +169,28 @@ executable, and contains the
### 9. Project documentation mentions the framework
-`<repo-root>/README.md` (or another committed doc the
-adopter picked) mentions the steward adoption with a link
-into the framework. Cheap to skip if absent — surface as
-⚠ only.
+Two files to check (per
+[`adopt.md` Step 11](adopt.md#step-11--project-doc-updates-fresh-only)):
+
+- **`<repo-root>/README.md`** — should have a contributor-facing
+ section (typically `## Agent-assisted contribution
+ (apache-steward)`) that mentions the snapshot mechanism, the
+ `/setup-steward` invocation for fresh clones, the
+ `.apache-steward.lock` pin, and `.apache-steward-overrides/`.
+ Grep for `apache-steward` and `/setup-steward` together as a
+ proxy. ⚠ if either token is absent.
+- **`<repo-root>/AGENTS.md`** — if the file exists, it should
+ have an `## apache-steward framework` section that
+ cross-references the README section. Grep for
+ `apache-steward` and a link to the README anchor. ⚠ if the
+ file exists but lacks the section; not applicable if the
+ file does not exist (do not create one just to satisfy
+ the check).
+
+Cheap to skip if both are absent on a minimal repo — surface
+as ⚠ overall only, never ✗. `CONTRIBUTING.md` counts as a
+fallback for `README.md` if the adopter declared it so during
+adoption.
## After the report
