Package Git Commit Conventions and Operational vs Release Workflow as Skills - #681
Merged
Conversation
… Skills Adds three fleet-wide Skills: git-commit-conventions (derived from GOVERNANCE.md "Git and Commit Rules"), operational-vs-release-workflow (derived from "Branching Model", "Release Model", and "Operational Repositories", triggered off registry/repos.json's workflowModel field per repo), and upstream-contribution-workflow (new content, the maintainer's own fork/dirty-branch/clean-branch third-party contribution workflow). Trims the four source GOVERNANCE.md sections to pointers, keeping their headings intact for spec/files.json's verbatim-section carrying. Updates AGENTS.md's "Where the Rules Live" table and pointer paragraph accordingly.
Contributor
There was a problem hiding this comment.
Pull request overview
Phase 6 of the hub-docs-to-Skills conversion: it packages additional fleet governance/workflow guidance as Skills (for Claude Code / opencode / Codex) and trims the corresponding GOVERNANCE.md sections down to pointer summaries so the skills become the canonical source.
Changes:
- Add three new Skills:
git-commit-conventions,operational-vs-release-workflow(plus reference docs), andupstream-contribution-workflow. - Replace the full text of four
GOVERNANCE.mdsections with short summaries that point to the Skills in the hub’s.agents/skills/. - Regenerate the Claude plugin distribution (
.claude-plugin/fleet-skills/) and update the manifest/digest accordingly.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| GOV-ERNANCE.md | Trims “Git and Commit Rules”, “Branching Model”, “Release Model”, “Operational Repositories” to summary + pointers to Skills. |
| AGENTS.md | Annotates the “Where the Rules Live” table rows with the Skill names that package those sections; mentions the new upstream workflow skill. |
| .claude-plugin/fleet-skills/skills/git-commit-conventions/SKILL.md | Generated plugin copy of the new git/commit conventions skill. |
| .claude-plugin/fleet-skills/skills/operational-vs-release-workflow/SKILL.md | Generated plugin copy of the new combined workflow-model skill. |
| .claude-plugin/fleet-skills/skills/operational-vs-release-workflow/references/branch-protection-and-promotion.md | Generated plugin reference doc for branching/protection/promotion mechanics. |
| .claude-plugin/fleet-skills/skills/operational-vs-release-workflow/references/release-publish-mechanics.md | Generated plugin reference doc for release build/publish mechanics. |
| .claude-plugin/fleet-skills/skills/upstream-contribution-workflow/SKILL.md | Generated plugin copy of the new workflow for contributing to third-party repos. |
| .claude-plugin/fleet-skills/.source-digest | Updated generated-tree digest stamp. |
| .claude-plugin/fleet-skills/.claude-plugin/plugin.json | Adds the new skills to the plugin manifest’s skills list. |
| .agents/skills/git-commit-conventions/SKILL.md | Canonical (hand-authored) git/commit conventions skill. |
| .agents/skills/operational-vs-release-workflow/SKILL.md | Canonical (hand-authored) combined workflow-model skill. |
| .agents/skills/operational-vs-release-workflow/references/branch-protection-and-promotion.md | Canonical reference doc for branching/protection/promotion mechanics. |
| .agents/skills/operational-vs-release-workflow/references/release-publish-mechanics.md | Canonical reference doc for release build/publish mechanics. |
| .agents/skills/upstream-contribution-workflow/SKILL.md | Canonical (hand-authored) upstream contribution workflow skill. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…ption Round 1 review (PRRT_kwDOQ5caqM6ZBXnj): step 5's re-squash mechanic said "pushing it again" without naming the operation, which reads as contradicting git-commit-conventions's never-force-push rule. States the operation explicitly (--force-with-lease, preferred over bare --force), scopes the exception tightly to the fork-only clean presentation branch, and explicitly bans force-pushing the dirty work branch.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.
Suppressed comments (2)
.agents/skills/upstream-contribution-workflow/SKILL.md:50
- The wording "This is the one narrow exception to
git-commit-conventions's never-force-push rule" conflicts withgit-commit-conventionsstating force-push is never allowed "under any circumstances". Since this workflow is explicitly about a fork/upstream repo (outside the fleet repos thatgit-commit-conventionsgoverns), consider rephrasing this to describe it as out-of-scope for the fleet rule (while keeping the tight scoping: only the clean presentation branch on the maintainer’s fork, only with--force-with-lease, never the dirty branch).
round rewrites the clean branch's history, and pushing a rewritten branch that is already
published requires `git push --force-with-lease` (prefer it over a bare `--force`, it refuses
the push if the remote moved since the last fetch). **This is the one narrow exception to
`git-commit-conventions`'s never-force-push rule, and it is scoped tightly**: force-with-lease
only the clean presentation branch, only on the maintainer's own fork, only while it carries
.claude-plugin/fleet-skills/skills/upstream-contribution-workflow/SKILL.md:50
- This skill calls the force-with-lease behavior "the one narrow exception" to
git-commit-conventions’ never-force-push rule, butgit-commit-conventionsitself says force-push is never allowed "under any circumstances". To avoid conflicting canonical guidance, rephrase this to make it explicit that the fleet no-force-push rule applies to fleet repos/branches, while this upstream/fork presentation-branch workflow is a separate context that permits--force-with-leaseunder tight constraints.
round rewrites the clean branch's history, and pushing a rewritten branch that is already
published requires `git push --force-with-lease` (prefer it over a bare `--force`, it refuses
the push if the remote moved since the last fetch). **This is the one narrow exception to
`git-commit-conventions`'s never-force-push rule, and it is scoped tightly**: force-with-lease
only the clean presentation branch, only on the maintainer's own fork, only while it carries
…cope, not an exception Round 2 review (2 suppressed findings, same wording flagged in both the source and generated dist copy): calling the force-with-lease allowance "the one narrow exception" to git-commit-conventions's never-force-push rule implied that rule itself carries an exception, contradicting its own "under any circumstances" wording. Rephrased: the fleet rule stays absolute for fleet repos and simply has no jurisdiction over a fork branch outside the fleet, rather than bending for it.
Owner
Author
|
Answering round 2's suppressed findings (2), both flagging the same wording in the source and generated dist copy of
Fixed in 3a95a5b. Both were correct: calling it "the one narrow exception" implied |
This was referenced Aug 14, 2026
Closed
ptr727
added a commit
that referenced
this pull request
Aug 15, 2026
…Python CI Gates (#718) Thirty-one squashes, `56f4d7d..d54862a`. 115 files, +20436/-5298. **Merge with a merge commit, never a squash, and never with `--delete-branch`.** This pull request's head is `develop` itself. ## What lands **Fleet Skills.** The `.agents/skills/` source tree, the generated `.claude-plugin/` distribution, `scripts/build_dist.py` with its `--check` gate, and `scripts/skills_install.py` with its host stamp (#676). Packaged as skills on top of the scaffold: PR review conduct and Copilot instructions upkeep (#677), comment and doc style (#678), resync-a-repo and fleet-conformance-check (#679), the per-language codestyles (#680), git commit conventions and operational vs release workflow (#681), stand up a repo (#683), and repo-worktree (#717). Coverage gaps closed in three passes (#690, #691, #692) plus the P4 sentence-length opt-in (#697). **Host setup.** The Windows host-setup tooling and its PowerShell gate (#674), the Windows bootstrap loader (#682), Docker install and upgrade on Linux and Windows with a version floor (#701, #705), a `uv` floor in `spec/host-tools.json` (#698), self-healing of a shadowing `uv`, `jq`, or `git-restore-mtime` copy (#689), node's real winget package id (#696), and a README for the Linux host-setup nuances (#710). **Python and CI.** Python tooling in CI with the script tests moved to `scripts/tests` (#704), `ruff format` adopted and gated (#709), and the PSScriptAnalyzer claim conditioned on repos that carry `.ps1` files (#686). **Conduct rules.** Triage-order and scope guardrails in pr-review-conduct (#684), `pr_review.py wait` requesting a review rather than only polling for one (#685), a tech-agnostic signed-commit verification (#708), execution rather than analogy to verify platform-specific code (#715), and a unique worktree for every task (#717). **Docs.** The fleet map and gap register with peer messaging declared (#687), mermaid flow diagrams in the kept-authority docs (#702), and the map pointed at the shipped diagrams and current tooling (#703). ## Issues this promotion closes Each landed on `develop` on its own pull request. The keyword fires only on a merge into `main`, so it sits here rather than on the feature pull requests. Closes #700 Closes #707 Closes #711 Closes #712 Closes #714 Closes #688 #699 stays open on purpose: #717 shipped the layout convention and the skill, and the physical migration of existing checkouts is still tracked there. ## Review record Every squash closed its own Copilot loop on its own pull request before merging to `develop`. This promotion carries no new content of its own, so its review is the merged tree as a whole. ## Consequence worth stating The `GOVERNANCE.md` and `AGENTS.md` sections these squashes changed become the canonical the moment this reaches `main`, and every carrying repository reads as drifted from that point until it resyncs. That is the ordinary consequence of a canonical moving rather than a defect. The Skills installer added here is also how a machine picks the new skills up, so a session that keeps restating a rule already packaged as a skill is the signal to run it.
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
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
Phase 6 of the hub-docs-to-Skills conversion project (see #676-#680 for prior phases).
Adds three fleet-wide Claude Code / opencode / Codex Skills, all
appliesTo: "*":git-commit-conventions, derived fromGOVERNANCE.md"Git and Commit Rules": staging vs.committing, commit-means-commit-and-push, signing verified not configured, identity verified
not set, never force push, careful history rewrites, no destructive git commands.
operational-vs-release-workflow, derived fromGOVERNANCE.md"Branching Model","Release Model", and "Operational Repositories". One skill serves both workflow models: its
own trigger description reads the registry's
workflowModelfield per repo rather than gatingby repo type. Two
references/files hold the deep CI-wiring detail (branch protection andpromotion mechanics; release build and publish mechanics) via progressive disclosure.
upstream-contribution-workflow(new content, not derived from anyGOVERNANCE.mdsection): the maintainer's own third-party-contribution workflow, a dirty work branch on his
own fork for the actual work and review iteration, squashed once clean to a second branch that
carries only the intended minimal history, that clean branch opened as the PR against the
upstream repo, reviewer feedback applied to the dirty branch first and then re-squashed.
Triggers independent of the target repo's own type or workflow model.
GOVERNANCE.md's four source sections are trimmed to short pointers, per the standing "skillbecomes sole canonical content" decision. Their
##headings stay in place, sincespec/files.jsoncarries all four atverbatimfidelity by heading name, only the body contentunder each shrank. Checked before trimming: no
scripts/test_*.pycouples to any of the foursections' content or subheadings (the Phase 3 gotcha).
AGENTS.md's "Where the Rules Live" table gains "packaged as theXSkill" annotations on thefour affected rows, and
upstream-contribution-workflowis added to the explanatory paragraphbelow the table (new content goes there, not a new table row, per the Phase 2/4 precedent, since
that table pairs a task with a real
GOVERNANCE.mdsection name).Verification
python3 scripts/build_dist.py: regenerated.claude-plugin/fleet-skills/from 12 skills clean.python3 scripts/test_build_dist.py,python3 scripts/test_skills_install.py: pass.python3 scripts/prose_lint.py . --diff HEAD: 0 violations (after fixing onedupwordfalsepositive caused by awkward phrasing).
python3 scripts/repo_gate.py --check eol: 0 issues (also re-verified by the pre-commit hook).npx markdownlint-cli2against every new/changed Markdown file: 0 issues.scripts/test_*.pycouples to any of the four trimmedGOVERNANCE.mdsections'content before trimming.
🤖 Generated with Claude Code