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 de2905a docs(agents): require a spec-sync pre-check before pushing a
functionality PR (#583)
de2905a is described below
commit de2905afd1eeb2d0228420c62409546d185b3dcf
Author: Jarek Potiuk <[email protected]>
AuthorDate: Fri Jun 26 22:43:43 2026 -0400
docs(agents): require a spec-sync pre-check before pushing a functionality
PR (#583)
Add a Commit-and-PR convention: before pushing a PR that ships or changes a
skill/tool/mode — or a rebase of one onto a moved `main` — verify the
spec-loop specs and `.last-sync` reflect what actually shipped, and sync if
they have drifted. Prevents the failure where a "sync specs" PR lands
already
stale because more functionality shipped while it sat. Mechanical PRs
(no-new-functionality rebases, lint, docs-only) are exempt.
Generated-by: Claude Code (Opus 4.8)
---
AGENTS.md | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
index 419d44f..f05582d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -430,6 +430,21 @@ to a home-dir path and update the tool to read from there.
staging branch for the private-PR fallback described in
[`README.md`](README.md). Unless the user explicitly says otherwise, base
PRs on the tracker's default branch.
+- **Spec-sync pre-check before pushing a functionality PR.** The specs in
+ [`tools/spec-loop/specs/`](tools/spec-loop/specs/) are the source of truth
+ and must not fall behind the code. Before pushing a PR that ships or changes
+ a skill, tool, or mode — **and before pushing a rebase of one onto a `main`
+ that has moved** — confirm `tools/spec-loop/.last-sync` is at (or near) the
+ current `main` tip and that the affected specs reflect what actually
+ shipped. If they have drifted, run the sync
+ (`tools/spec-loop/loop.sh update`, which writes to a `spec/sync-specs`
+ branch — see
+ [`docs/spec-driven-development.md`](docs/spec-driven-development.md)) or,
+ for a small known gap, update the spec(s) and bump `.last-sync` by hand;
+ then either fold it into the PR or open a companion `sync-specs` PR. The
+ failure this prevents: a "sync specs" PR that lands already stale because
+ more functionality shipped while it sat. Pure-mechanical PRs (a rebase that
+ ships no new functionality, lint, docs-only edits) are exempt.
- Keep the commit message focused on the user-visible change, not the
mechanics of how the edit
was made.
