From 3c74beb280b5c866d5e70871878ba9c68a45c83b Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 30 Aug 2026 13:10:53 +0000 Subject: [PATCH] refactor(git-workflow): retrofit to the ADR-0020 context contract Description 566 -> 249 chars, body 644 -> 398 words, Gotchas 12 -> 2. The eight organisational hard rules move to references/hard-rules.md. Its load trigger enumerates operations rather than rule topics: the first draft keyed on 'commit message form', which left the atomicity and working-state rules unreachable when a caller supplied a conventional message. Also promotes the destructive-op confirmation ahead of the orchestrator invocation, which it previously followed. --- .../git/.apm/skills/git-workflow/README.md | 3 +- plugins/git/.apm/skills/git-workflow/SKILL.md | 77 +++++++++---------- .../skills/git-workflow/references/README.md | 5 +- .../git-workflow/references/hard-rules.md | 25 ++++++ .../skills/git-workflow/references/sources.md | 3 +- plugins/git/skills/git-workflow/README.md | 3 +- plugins/git/skills/git-workflow/SKILL.md | 77 +++++++++---------- .../skills/git-workflow/references/README.md | 5 +- .../git-workflow/references/hard-rules.md | 25 ++++++ .../skills/git-workflow/references/sources.md | 3 +- 10 files changed, 136 insertions(+), 90 deletions(-) create mode 100644 plugins/git/.apm/skills/git-workflow/references/hard-rules.md create mode 100644 plugins/git/skills/git-workflow/references/hard-rules.md diff --git a/plugins/git/.apm/skills/git-workflow/README.md b/plugins/git/.apm/skills/git-workflow/README.md index c401e63..607924f 100644 --- a/plugins/git/.apm/skills/git-workflow/README.md +++ b/plugins/git/.apm/skills/git-workflow/README.md @@ -4,7 +4,7 @@ Human-friendly interface for interactive git workflows with conversational promp ## What it does -This skill wraps the `git-orchestrate` agent to provide an interactive, educational interface for humans performing git workflows. It handles commits, branch management, history inspection, submodules, worktrees, and remotes. The skill parses user intent, gathers session context, invokes the orchestrator, and presents results in plain language with inline help, progress updates, and explanations of what's happening. It enforces confirmation gates for destructive operations (force-push, branch deletion, rebasing with history loss, force-checkout) and provides best-practices guidance throughout. +This skill wraps the `git-orchestrate` agent to provide an interactive, educational interface for humans performing git workflows. It handles commits, branch management, history inspection, submodules, worktrees, and remotes. The skill parses user intent, gathers session context, invokes the orchestrator, and presents results in plain language with inline help, progress updates, and explanations of what's happening. It enforces confirmation gates for destructive operations (force-push, branch deletion, rebasing with history loss, force-checkout) and provides best-practices guidance throughout. The org's non-negotiable git rules live in `references/hard-rules.md` and are loaded only when a request could conflict with one. ## Usage @@ -20,5 +20,6 @@ Describe your git workflow: commit, create a branch, rebase, inspect history, ma |------|---------| | `SKILL.md` | Skill instructions for agents | | `README.md` | This file | +| `references/hard-rules.md` | The org's non-negotiable git rules; read when a request creates, amends, or rewrites a commit, pushes, or touches hooks, config, or credentials | | `references/README.md` | Describes the references directory contents | | `references/sources.md` | Research sources and provenance | diff --git a/plugins/git/.apm/skills/git-workflow/SKILL.md b/plugins/git/.apm/skills/git-workflow/SKILL.md index 197bf49..5dd21a8 100644 --- a/plugins/git/.apm/skills/git-workflow/SKILL.md +++ b/plugins/git/.apm/skills/git-workflow/SKILL.md @@ -2,12 +2,9 @@ name: git-workflow description: > - Use when a human user wants to perform git workflows interactively — commits, branch management, - history inspection, submodules, worktrees, or remotes. Provides a friendly, conversational - interface with clarification prompts ("Which branch base?"), progress updates, inline help, - best practices guidance, and confirmation dialogs for destructive operations. Guides users - through complex git patterns even if they don't mention every detail. Do not use when the - caller is an agent—agents should invoke git-orchestrate directly for deterministic, composable execution. + Use when a human wants to work through local git interactively — commits, branches, history, + submodules, worktrees, or remotes. Not an agent caller needing deterministic execution -> + `git-orchestrate`. Not server-side Gitea work -> `gitea-workflow`. metadata: category: git @@ -21,45 +18,41 @@ metadata: ## Gotchas -- This skill is specifically for **human interaction**. If the caller is an agent, invoke `git-orchestrate` directly instead—this skill adds UI overhead agents don't need. -- Session context from previous git operations (branch names, commit strategy) persists during a single multi-step user request, then clears. Users don't need to re-provide decisions within one workflow. -- Destructive operations require explicit confirmation: force-push, branch deletion, rebase with history loss, force-checkout. Users must confirm interactively; the skill never proceeds without their approval on destructive ops. -- Run git commands through `rtk git ` rather than bare `git ` for parent-repo operations — this is a mandated org wrapper, not an optional style choice. Drop into a submodule's own directory for submodule-specific commands (see `git-submodules`). - -### Hard rules - -These are non-negotiable regardless of what the user asks for — surface them proactively rather than waiting for the user to hit them (`org-git-conventions`; sub-skills invoked directly by humans, like this one, carry their own local copy of these rules for readers who won't chain through `git-orchestrate`, so state them plainly rather than assuming the user already knows them): - -- Never skip hooks with `--no-verify` — hooks are the automated QA gate, and bypassing them breaks the pipeline for everyone downstream. -- Never force-push `main` or `master`. -- Keep commits atomic — each commit should represent one logical, independently reviewable and reversible change. -- Every commit must leave the repository in a working state (buildable/testable where practical). -- Commit messages explain **why**, not **what** — the diff already documents what changed. -- Never commit secrets, credentials, or environment-specific config. -- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.). -- Reference related issues, ADRs, or design documents using Git trailers when applicable. - -If a user's request conflicts with a hard rule (e.g. "force-push main to fix this"), explain the rule and propose a safe alternative instead of complying. +- Session context built during one multi-step request — branch names, the chosen base, the commit + strategy — persists for that request and then clears. Do not re-ask the user for a decision they + already gave you earlier in the same workflow. +- Run parent-repo commands through `rtk git `, never bare `git `. This is a + mandated org wrapper, not a style preference. Submodule-specific commands run from inside the + submodule's own directory instead. ## Workflow -When a user wants to perform git workflows: - -1. **Parse the user's intent** — extract the high-level task (commit, create branch, rebase, inspect history, etc.) and any explicit options they mentioned. -2. **Build session context** — gather repo state, current branch, any prior decisions in this workflow (branch intent for commit messages, base branch for rebasing, etc.). -3. **Invoke git-orchestrate agent** — call it with: - - `operation`: the git operation (e.g., "commit", "create-branch", "rebase") - - `parameters`: user-provided or inferred options - - `context`: decisions and repo state from prior steps in this workflow - - `confirm`: `true` if a destructive op and the user confirmed, otherwise omit -4. **Handle the response** — if orchestrator succeeds, present results in plain language with progress updates and explanations. If it fails, show the error reason and suggest recovery actions. -5. **Clarification prompts** — if the orchestrator needs more information (e.g., "Which branch should this be based on?"), prompt the user conversationally and loop back with the user's input. -6. **Confirmation gates** — before executing any destructive op (force-push, branch deletion, rebase, force-checkout), show what will happen and ask "Proceed?" If the user declines, cancel gracefully. +1. **Parse intent** — extract the operation (commit, create branch, rebase, inspect history, …) + and any options the user named. +2. **Check the hard rules** — if the request creates, amends, or rewrites a commit, pushes, or + touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule + before acting, not after. +3. **Read the repo** — current branch, working-tree state, and which branching model the repo + follows (the orchestrator reads `branching_pattern` from plugin config; infer from branch names + if absent); the last of those decides which tips are worth offering. +4. **Gate destructive operations** — before force-push, branch deletion, rebase, or + force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user + declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not + confirmations: never offer "Proceed?" for a force-push of `main` or `master`. +5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or + inferred), `context` (step 3 plus the session context), and `confirm: true` only for a + destructive op the user approved in step 4. +6. **Clarify when the orchestrator asks for more** — put its question to the user in plain + language ("Which branch should this be based on?") and loop back to step 5 with the answer. +7. **Report the outcome** — on success, the result and what changed, in plain language; on + failure, the error reason and a recovery action. ## Interaction style -- **Conversational**: Use natural language, not technical jargon. "Let me rebase your changes onto main" not "Running git rebase --interactive main". -- **Pedagogical**: Explain what each step does and why. "I'm squashing your last 3 commits into one clean commit" not just "Squashing commits". -- **Guided**: Offer inline help. When users mention ambiguous steps, suggest best practices. Match the tip to the repo's branching model: for Gitflow-style repos, "Tip: Feature branches branch off `develop`, not `main` — `main` only tracks released code." For trunk-based/GitHub Flow repos, "Tip: Short-lived feature branches off `main` keep merges small and reviewable." -- **Transparent**: Show progress. "Creating branch feature/user-auth..." then "✓ Branch created. Ready to commit." Humans benefit from seeing workflow state. -- **Safe**: Always confirm before destructive ops. Never silently rewrite history or force-push without explicit user approval. +The caller is a human, so the interaction is the point. Explain each step and why it happens ("I'm +squashing your last 3 commits into one clean commit" beats "Squashing commits"), show progress as +you go, and prefer natural language to raw command lines. + +Match tips to the repo's branching model rather than offering generic advice: on a Gitflow repo, +feature branches come off `develop` and `main` tracks only released code; on a trunk-based or +GitHub Flow repo, short-lived branches off `main` keep merges small and reviewable. diff --git a/plugins/git/.apm/skills/git-workflow/references/README.md b/plugins/git/.apm/skills/git-workflow/references/README.md index 37edf15..bcf2db0 100644 --- a/plugins/git/.apm/skills/git-workflow/references/README.md +++ b/plugins/git/.apm/skills/git-workflow/references/README.md @@ -9,8 +9,11 @@ source_keys: # References -This directory contains provenance metadata and research sources for the `git-workflow` skill. +This directory contains the org git rules and the provenance metadata for the `git-workflow` +skill. ## Files +- `hard-rules.md` — The org's non-negotiable git rules, loaded when a request creates, amends, or + rewrites a commit, pushes, or touches hooks, config, or credentials - `sources.md` — Extracted research sources and their contributing documents diff --git a/plugins/git/.apm/skills/git-workflow/references/hard-rules.md b/plugins/git/.apm/skills/git-workflow/references/hard-rules.md new file mode 100644 index 0000000..fd2262d --- /dev/null +++ b/plugins/git/.apm/skills/git-workflow/references/hard-rules.md @@ -0,0 +1,25 @@ +--- +source_keys: + - org-git-conventions +--- + +# Org git hard rules + +Non-negotiable regardless of what the user asks for. Surface the relevant one proactively rather +than waiting for the user to hit it — a human invoking this skill directly never sees the +orchestrator's copy of these rules, so raise them here. + +- Never skip hooks with `--no-verify` — hooks are the automated QA gate, and bypassing them breaks + the pipeline for everyone downstream. +- Never force-push `main` or `master`. +- Keep commits atomic — each commit should represent one logical, independently reviewable and + reversible change. +- Every commit must leave the repository in a working state (buildable/testable where practical). +- Commit messages explain **why**, not **what** — the diff already documents what changed. +- Never commit secrets, credentials, or environment-specific config. +- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.). +- Reference related issues, ADRs, or design documents using Git trailers when applicable. + +If a user's request conflicts with one of these (e.g. "force-push main to fix this"), explain the +rule and propose a safe alternative instead of complying. Do not comply and note the rule +afterwards. diff --git a/plugins/git/.apm/skills/git-workflow/references/sources.md b/plugins/git/.apm/skills/git-workflow/references/sources.md index b5e6c4a..1d8177c 100644 --- a/plugins/git/.apm/skills/git-workflow/references/sources.md +++ b/plugins/git/.apm/skills/git-workflow/references/sources.md @@ -56,4 +56,5 @@ - **Research doc:** none — org convention, not part of the plugin's research corpus (no `plugins/git/docs/research/` topic file backs this entry) **Contributing files:** -- SKILL.md (Gotchas — Hard rules subsection, rtk git note) +- references/hard-rules.md (whole file — the eight hard rules and the conflict-handling rule) +- SKILL.md (Gotchas — `rtk git` wrapper note) diff --git a/plugins/git/skills/git-workflow/README.md b/plugins/git/skills/git-workflow/README.md index c401e63..607924f 100644 --- a/plugins/git/skills/git-workflow/README.md +++ b/plugins/git/skills/git-workflow/README.md @@ -4,7 +4,7 @@ Human-friendly interface for interactive git workflows with conversational promp ## What it does -This skill wraps the `git-orchestrate` agent to provide an interactive, educational interface for humans performing git workflows. It handles commits, branch management, history inspection, submodules, worktrees, and remotes. The skill parses user intent, gathers session context, invokes the orchestrator, and presents results in plain language with inline help, progress updates, and explanations of what's happening. It enforces confirmation gates for destructive operations (force-push, branch deletion, rebasing with history loss, force-checkout) and provides best-practices guidance throughout. +This skill wraps the `git-orchestrate` agent to provide an interactive, educational interface for humans performing git workflows. It handles commits, branch management, history inspection, submodules, worktrees, and remotes. The skill parses user intent, gathers session context, invokes the orchestrator, and presents results in plain language with inline help, progress updates, and explanations of what's happening. It enforces confirmation gates for destructive operations (force-push, branch deletion, rebasing with history loss, force-checkout) and provides best-practices guidance throughout. The org's non-negotiable git rules live in `references/hard-rules.md` and are loaded only when a request could conflict with one. ## Usage @@ -20,5 +20,6 @@ Describe your git workflow: commit, create a branch, rebase, inspect history, ma |------|---------| | `SKILL.md` | Skill instructions for agents | | `README.md` | This file | +| `references/hard-rules.md` | The org's non-negotiable git rules; read when a request creates, amends, or rewrites a commit, pushes, or touches hooks, config, or credentials | | `references/README.md` | Describes the references directory contents | | `references/sources.md` | Research sources and provenance | diff --git a/plugins/git/skills/git-workflow/SKILL.md b/plugins/git/skills/git-workflow/SKILL.md index 197bf49..5dd21a8 100644 --- a/plugins/git/skills/git-workflow/SKILL.md +++ b/plugins/git/skills/git-workflow/SKILL.md @@ -2,12 +2,9 @@ name: git-workflow description: > - Use when a human user wants to perform git workflows interactively — commits, branch management, - history inspection, submodules, worktrees, or remotes. Provides a friendly, conversational - interface with clarification prompts ("Which branch base?"), progress updates, inline help, - best practices guidance, and confirmation dialogs for destructive operations. Guides users - through complex git patterns even if they don't mention every detail. Do not use when the - caller is an agent—agents should invoke git-orchestrate directly for deterministic, composable execution. + Use when a human wants to work through local git interactively — commits, branches, history, + submodules, worktrees, or remotes. Not an agent caller needing deterministic execution -> + `git-orchestrate`. Not server-side Gitea work -> `gitea-workflow`. metadata: category: git @@ -21,45 +18,41 @@ metadata: ## Gotchas -- This skill is specifically for **human interaction**. If the caller is an agent, invoke `git-orchestrate` directly instead—this skill adds UI overhead agents don't need. -- Session context from previous git operations (branch names, commit strategy) persists during a single multi-step user request, then clears. Users don't need to re-provide decisions within one workflow. -- Destructive operations require explicit confirmation: force-push, branch deletion, rebase with history loss, force-checkout. Users must confirm interactively; the skill never proceeds without their approval on destructive ops. -- Run git commands through `rtk git ` rather than bare `git ` for parent-repo operations — this is a mandated org wrapper, not an optional style choice. Drop into a submodule's own directory for submodule-specific commands (see `git-submodules`). - -### Hard rules - -These are non-negotiable regardless of what the user asks for — surface them proactively rather than waiting for the user to hit them (`org-git-conventions`; sub-skills invoked directly by humans, like this one, carry their own local copy of these rules for readers who won't chain through `git-orchestrate`, so state them plainly rather than assuming the user already knows them): - -- Never skip hooks with `--no-verify` — hooks are the automated QA gate, and bypassing them breaks the pipeline for everyone downstream. -- Never force-push `main` or `master`. -- Keep commits atomic — each commit should represent one logical, independently reviewable and reversible change. -- Every commit must leave the repository in a working state (buildable/testable where practical). -- Commit messages explain **why**, not **what** — the diff already documents what changed. -- Never commit secrets, credentials, or environment-specific config. -- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.). -- Reference related issues, ADRs, or design documents using Git trailers when applicable. - -If a user's request conflicts with a hard rule (e.g. "force-push main to fix this"), explain the rule and propose a safe alternative instead of complying. +- Session context built during one multi-step request — branch names, the chosen base, the commit + strategy — persists for that request and then clears. Do not re-ask the user for a decision they + already gave you earlier in the same workflow. +- Run parent-repo commands through `rtk git `, never bare `git `. This is a + mandated org wrapper, not a style preference. Submodule-specific commands run from inside the + submodule's own directory instead. ## Workflow -When a user wants to perform git workflows: - -1. **Parse the user's intent** — extract the high-level task (commit, create branch, rebase, inspect history, etc.) and any explicit options they mentioned. -2. **Build session context** — gather repo state, current branch, any prior decisions in this workflow (branch intent for commit messages, base branch for rebasing, etc.). -3. **Invoke git-orchestrate agent** — call it with: - - `operation`: the git operation (e.g., "commit", "create-branch", "rebase") - - `parameters`: user-provided or inferred options - - `context`: decisions and repo state from prior steps in this workflow - - `confirm`: `true` if a destructive op and the user confirmed, otherwise omit -4. **Handle the response** — if orchestrator succeeds, present results in plain language with progress updates and explanations. If it fails, show the error reason and suggest recovery actions. -5. **Clarification prompts** — if the orchestrator needs more information (e.g., "Which branch should this be based on?"), prompt the user conversationally and loop back with the user's input. -6. **Confirmation gates** — before executing any destructive op (force-push, branch deletion, rebase, force-checkout), show what will happen and ask "Proceed?" If the user declines, cancel gracefully. +1. **Parse intent** — extract the operation (commit, create branch, rebase, inspect history, …) + and any options the user named. +2. **Check the hard rules** — if the request creates, amends, or rewrites a commit, pushes, or + touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule + before acting, not after. +3. **Read the repo** — current branch, working-tree state, and which branching model the repo + follows (the orchestrator reads `branching_pattern` from plugin config; infer from branch names + if absent); the last of those decides which tips are worth offering. +4. **Gate destructive operations** — before force-push, branch deletion, rebase, or + force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user + declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not + confirmations: never offer "Proceed?" for a force-push of `main` or `master`. +5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or + inferred), `context` (step 3 plus the session context), and `confirm: true` only for a + destructive op the user approved in step 4. +6. **Clarify when the orchestrator asks for more** — put its question to the user in plain + language ("Which branch should this be based on?") and loop back to step 5 with the answer. +7. **Report the outcome** — on success, the result and what changed, in plain language; on + failure, the error reason and a recovery action. ## Interaction style -- **Conversational**: Use natural language, not technical jargon. "Let me rebase your changes onto main" not "Running git rebase --interactive main". -- **Pedagogical**: Explain what each step does and why. "I'm squashing your last 3 commits into one clean commit" not just "Squashing commits". -- **Guided**: Offer inline help. When users mention ambiguous steps, suggest best practices. Match the tip to the repo's branching model: for Gitflow-style repos, "Tip: Feature branches branch off `develop`, not `main` — `main` only tracks released code." For trunk-based/GitHub Flow repos, "Tip: Short-lived feature branches off `main` keep merges small and reviewable." -- **Transparent**: Show progress. "Creating branch feature/user-auth..." then "✓ Branch created. Ready to commit." Humans benefit from seeing workflow state. -- **Safe**: Always confirm before destructive ops. Never silently rewrite history or force-push without explicit user approval. +The caller is a human, so the interaction is the point. Explain each step and why it happens ("I'm +squashing your last 3 commits into one clean commit" beats "Squashing commits"), show progress as +you go, and prefer natural language to raw command lines. + +Match tips to the repo's branching model rather than offering generic advice: on a Gitflow repo, +feature branches come off `develop` and `main` tracks only released code; on a trunk-based or +GitHub Flow repo, short-lived branches off `main` keep merges small and reviewable. diff --git a/plugins/git/skills/git-workflow/references/README.md b/plugins/git/skills/git-workflow/references/README.md index 37edf15..bcf2db0 100644 --- a/plugins/git/skills/git-workflow/references/README.md +++ b/plugins/git/skills/git-workflow/references/README.md @@ -9,8 +9,11 @@ source_keys: # References -This directory contains provenance metadata and research sources for the `git-workflow` skill. +This directory contains the org git rules and the provenance metadata for the `git-workflow` +skill. ## Files +- `hard-rules.md` — The org's non-negotiable git rules, loaded when a request creates, amends, or + rewrites a commit, pushes, or touches hooks, config, or credentials - `sources.md` — Extracted research sources and their contributing documents diff --git a/plugins/git/skills/git-workflow/references/hard-rules.md b/plugins/git/skills/git-workflow/references/hard-rules.md new file mode 100644 index 0000000..fd2262d --- /dev/null +++ b/plugins/git/skills/git-workflow/references/hard-rules.md @@ -0,0 +1,25 @@ +--- +source_keys: + - org-git-conventions +--- + +# Org git hard rules + +Non-negotiable regardless of what the user asks for. Surface the relevant one proactively rather +than waiting for the user to hit it — a human invoking this skill directly never sees the +orchestrator's copy of these rules, so raise them here. + +- Never skip hooks with `--no-verify` — hooks are the automated QA gate, and bypassing them breaks + the pipeline for everyone downstream. +- Never force-push `main` or `master`. +- Keep commits atomic — each commit should represent one logical, independently reviewable and + reversible change. +- Every commit must leave the repository in a working state (buildable/testable where practical). +- Commit messages explain **why**, not **what** — the diff already documents what changed. +- Never commit secrets, credentials, or environment-specific config. +- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.). +- Reference related issues, ADRs, or design documents using Git trailers when applicable. + +If a user's request conflicts with one of these (e.g. "force-push main to fix this"), explain the +rule and propose a safe alternative instead of complying. Do not comply and note the rule +afterwards. diff --git a/plugins/git/skills/git-workflow/references/sources.md b/plugins/git/skills/git-workflow/references/sources.md index b5e6c4a..1d8177c 100644 --- a/plugins/git/skills/git-workflow/references/sources.md +++ b/plugins/git/skills/git-workflow/references/sources.md @@ -56,4 +56,5 @@ - **Research doc:** none — org convention, not part of the plugin's research corpus (no `plugins/git/docs/research/` topic file backs this entry) **Contributing files:** -- SKILL.md (Gotchas — Hard rules subsection, rtk git note) +- references/hard-rules.md (whole file — the eight hard rules and the conflict-handling rule) +- SKILL.md (Gotchas — `rtk git` wrapper note)