From 3de7b2943206fe60b279b03c226f1fea374b3b65 Mon Sep 17 00:00:00 2001 From: Gemini CLI Date: Mon, 8 Jun 2026 20:06:11 -0400 Subject: [PATCH] feat(governance): add governed remote PR workflow skill Add a plugin skill that focuses on sorting changes and creating remote PRs with governance evidence, and include it in installer skill projections for Cursor, agents, and Claude paths. --- MANIFEST.toml | 23 ++++++++ scripts/render-from-config.sh | 2 +- skills/governed-pr-flow/PROJECT.md.template | 28 +++++++++ skills/governed-pr-flow/SKILL.md | 63 +++++++++++++++++++++ 4 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 skills/governed-pr-flow/PROJECT.md.template create mode 100644 skills/governed-pr-flow/SKILL.md diff --git a/MANIFEST.toml b/MANIFEST.toml index 23be54b..15d0fd0 100644 --- a/MANIFEST.toml +++ b/MANIFEST.toml @@ -105,6 +105,11 @@ source = "skills/task-registry-flow" destination = ".cursor/skills/task-registry-flow" recursive = true +[[copy]] +source = "skills/governed-pr-flow" +destination = ".cursor/skills/governed-pr-flow" +recursive = true + [[copy]] source = "skills/gap-closure-contract" destination = ".agents/skills/gap-closure-contract" @@ -115,6 +120,11 @@ source = "skills/task-registry-flow" destination = ".agents/skills/task-registry-flow" recursive = true +[[copy]] +source = "skills/governed-pr-flow" +destination = ".agents/skills/governed-pr-flow" +recursive = true + [[copy]] source = "skills/gap-closure-contract" destination = ".claude/skills/gap-closure-contract" @@ -125,6 +135,11 @@ source = "skills/task-registry-flow" destination = ".claude/skills/task-registry-flow" recursive = true +[[copy]] +source = "skills/governed-pr-flow" +destination = ".claude/skills/governed-pr-flow" +recursive = true + [[generated]] destination = ".agents/skills/gap-closure-contract.md" from = "skills/gap-closure-contract/SKILL.md" @@ -133,6 +148,10 @@ from = "skills/gap-closure-contract/SKILL.md" destination = ".agents/skills/task-registry-flow.md" from = "skills/task-registry-flow/SKILL.md" +[[generated]] +destination = ".agents/skills/governed-pr-flow.md" +from = "skills/governed-pr-flow/SKILL.md" + [[generated]] destination = ".codex/governance-cli.env" from_config = "mutation_gate.verify_hook_command" @@ -195,6 +214,8 @@ tracked_for_ci = [ ".agents/skills/gap-closure-contract.md", ".agents/skills/task-registry-flow", ".agents/skills/task-registry-flow.md", + ".agents/skills/governed-pr-flow", + ".agents/skills/governed-pr-flow.md", ".cursor/rules/agent-governance.mdc", ".cursor/hooks.json", ".cursor/hooks/gap-closure-gate.sh", @@ -202,9 +223,11 @@ tracked_for_ci = [ "GEMINI.md", ".cursor/skills/gap-closure-contract/PROJECT.md", ".cursor/skills/task-registry-flow/PROJECT.md", + ".cursor/skills/governed-pr-flow/PROJECT.md", ".claude/settings.json", ".claude/skills/gap-closure-contract/PROJECT.md", ".claude/skills/task-registry-flow/PROJECT.md", + ".claude/skills/governed-pr-flow/PROJECT.md", "docs/task-registry.toml", "docs/task-registry/events.jsonl", ] diff --git a/scripts/render-from-config.sh b/scripts/render-from-config.sh index 1598cbd..6c1ba95 100755 --- a/scripts/render-from-config.sh +++ b/scripts/render-from-config.sh @@ -596,7 +596,7 @@ def render_agy_skill(skill: str) -> str: dest = target_root / ".agents/skills" / f"{skill}.md" return f"{rel(dest)}: {write_file(dest, src.read_text())}" -for skill in ("gap-closure-contract", "task-registry-flow"): +for skill in ("gap-closure-contract", "task-registry-flow", "governed-pr-flow"): actions.append(sync_skill(skill, target_root / ".cursor/skills")) actions.append(sync_skill(skill, target_root / ".agents/skills")) actions.append(sync_skill(skill, target_root / ".claude/skills")) diff --git a/skills/governed-pr-flow/PROJECT.md.template b/skills/governed-pr-flow/PROJECT.md.template new file mode 100644 index 0000000..0a98442 --- /dev/null +++ b/skills/governed-pr-flow/PROJECT.md.template @@ -0,0 +1,28 @@ +# Project extensions for governed-pr-flow + +Optional. Copy to `PROJECT.md` beside the installed skill and edit for your repository. + +## Repository and branches + +- Repository root: `` +- Default PR base branch: `` +- Protected branches: `` + +## Required gates before PR + +- Focused gates: + - `` +- Full gates: + - `` + +## Task-registry mapping + +- Plan location: `docs/plans/.md` +- Activation command: `.codex/scripts/task-registry activate docs/plans/.md` +- Landing command: `.codex/scripts/task-registry verify-landing --plan-id --changed-files ` + +## PR template conventions + +- Title format: `` +- Required body sections: `` +- Required labels/reviewers: `` diff --git a/skills/governed-pr-flow/SKILL.md b/skills/governed-pr-flow/SKILL.md new file mode 100644 index 0000000..f1575a1 --- /dev/null +++ b/skills/governed-pr-flow/SKILL.md @@ -0,0 +1,63 @@ +--- +name: governed-pr-flow +description: Governed workflow for preparing, sorting, and submitting pull requests to remote repositories. Use when the user asks to create a branch, push commits, and open a PR with gh while preserving task-registry validation and proof. +--- + +# Governed PR Flow + +Use this workflow to take already-implemented or staged work to a remote PR under task-registry governance. + +**Project extensions:** when `PROJECT.md` exists beside this skill, load it after this file for repo-specific branch policy, base branch, CI gates, and PR templates. + +## 1) Confirm PR intent and scope + +- Confirm repo root (`git rev-parse --show-toplevel`) matches the intended project. +- Confirm user wants a remote PR (not only local commit). +- Read current project `AGENTS.md` and active plan/task context. + +## 2) Validate governance readiness for PR + +- Ensure the implementation plan has been activated: + - `.codex/scripts/task-registry activate docs/plans/.md` +- Confirm landing and verifier proof are complete for files in scope: + - `.codex/scripts/task-registry verify-landing --plan-id --changed-files ...` +- When registry state changed, verify receipts: + - `.codex/scripts/task-registry verify-chain --format json` + +## 3) Sort changes into coherent buckets + +- Sort changes into coherent buckets by intent (feature, fix, refactor, docs/tests/governance). +- Keep each bucket minimal, reviewable, and tied to task/behavior proof. +- Exclude unrelated dirty files from the PR branch. + +## 4) Stage and commit by bucket + +- Stage only the files for one bucket. +- Commit with message style used by the repository. +- Repeat until all intended buckets are committed. + +## 5) Prepare branch for remote + +- Create or switch to a review branch. +- Confirm branch is correct and ready to publish. + +## 6) Push branch and create remote PR + +- Push and set upstream: + - `git push -u origin HEAD` +- Open PR with GitHub CLI: + - `gh pr create --title "" --body "<body>"` +- Include in PR body: + - Scope summary tied to plan/task. + - Validation commands executed. + - Deferred/blocked tasks with reason, if any. + +## 7) Final PR handoff + +- Run final report for traceability: + - `.codex/scripts/task-registry report <plan_id>` +- Share: PR URL, commands run, outcomes, and remaining risk/deferred items. + +## Example first use + +- Use this skill to submit the `governed-pr-flow` skill addition itself as the first remote PR from the current branch.