feat(setup-steward): richer Step 11 doc-update flow#111
Merged
Conversation
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.
Member
Author
|
I just removed stuff from our "security" repo and "airflow" repo - and adopted "steward" there very successfully - adoption is super easy :) . This one adds nice description in README/CONTRIBUTING explaining the setup / adoption of steward. This will make it easy for contributors and maintainers to set it up. |
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
1 participant
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
setup-steward/adopt.mdStep 11 (project doc updates) previously said only "add a brief paragraph to README.md or CONTRIBUTING.md noting three things", leaving every adopter to reinvent the wording. Replace it with:## Agent-assisted contribution (apache-steward)template forREADME.md, with substitution guidance for the picked skill families and the flat-vs-double-symlinked path convention;AGENTS.mdtemplate that agent harnesses see first, with a cross-reference back to the README section;AGENTS.mdif it does not already exist" guardrail (empty file is noise);CONTRIBUTING.mdas a documented fallback for projects whereREADME.mdis off-limits.setup-steward/verify.mdcheck 9 updated in parallel: grep for bothapache-stewardand/setup-stewardtokens inREADME.md(and the cross-reference link inAGENTS.mdif it exists) rather than the previous "mentions the framework somewhere" hand-wave. Stays at ⚠ severity.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 reverse-engineering the airflow diff.
Test plan
prek run --files .claude/skills/setup-steward/adopt.md .claude/skills/setup-steward/verify.md— all relevant hooks (markdownlint, typos, EOF/whitespace, skill-validate) pass.Was generative AI tooling used to co-author this PR?
Generated-by: Claude Opus 4.7 (1M context) following the framework's agent-authored-fixes pattern.