docs(git): delete unused git plugin config file and its read steps

Finding 21: `config.example.json` (and the never-tracked
`.claude/plugins/git/config.json` it documented) was read by
git-orchestrate and git-branches but written by nothing, and the
default-inference fallback (GitHub Flow, with Gitflow inferred from a
`develop`/`release/*` branch) already covered the no-config case.
Removed the config-read step from both, updated git-workflow's
description of the orchestrator to match, dropped the now-dangling
`applied_config` field from git-orchestrate's output shape, and
deleted the config file and its stale example reference in
docs/spec/architecture.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
2026-09-12 19:46:20 +00:00
parent 198eafd790
commit f5e4d0d082
9 changed files with 23 additions and 31 deletions

View File

@@ -119,7 +119,8 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research
20. **Collapse git 7 skills to 1; gitea 7 to 2.** Git references are man-page restatement: `git-log-format.md` (242 lines listing `%H`, `%ar`), `conventional-commits-spec.md` (170 lines), `worktrees.md` (178), `merging.md` explaining fast-forward. Roughly 60% of the plugin is generic. The genuinely house-specific content fits in about 150 lines: the `rtk` rule and ADR-0023 exceptions, main/master refusal, `--no-verify`, the `-i --autosquash` 2.39.5 trap, `--force-with-lease --force-if-includes`, bisect exit codes, submodule push ordering, the detached-HEAD worktree trap. Gitea is more legitimately specific (MCP schema quirks: `tree_sha`, `withLines`, silent drops on PR create, `per_page` 20 vs 30, 404 means 403) and splits naturally into `gitea-tracker` (issues, PRs, labels, milestones) and `gitea-repo` (branches, files, releases). Risk: one description must carry all trigger phrases; keep a dispatch table at the top of the body. Keep `pc-author` and `pc-run` (finding 38). Effort M. 20. **Collapse git 7 skills to 1; gitea 7 to 2.** Git references are man-page restatement: `git-log-format.md` (242 lines listing `%H`, `%ar`), `conventional-commits-spec.md` (170 lines), `worktrees.md` (178), `merging.md` explaining fast-forward. Roughly 60% of the plugin is generic. The genuinely house-specific content fits in about 150 lines: the `rtk` rule and ADR-0023 exceptions, main/master refusal, `--no-verify`, the `-i --autosquash` 2.39.5 trap, `--force-with-lease --force-if-includes`, bisect exit codes, submodule push ordering, the detached-HEAD worktree trap. Gitea is more legitimately specific (MCP schema quirks: `tree_sha`, `withLines`, silent drops on PR create, `per_page` 20 vs 30, 404 means 403) and splits naturally into `gitea-tracker` (issues, PRs, labels, milestones) and `gitea-repo` (branches, files, releases). Risk: one description must carry all trigger phrases; keep a dispatch table at the top of the body. Keep `pc-author` and `pc-run` (finding 38). Effort M.
21. **Delete `config.example.json` / `.claude/plugins/git/config.json`.** Read by two steps, written by nothing. Default to GitHub Flow with the existing `develop` / `release/*` inference. Effort S. 21. [x] ~~**Delete `config.example.json` / `.claude/plugins/git/config.json`.** Read by two steps, written by nothing. Default to GitHub Flow with the existing `develop` / `release/*` inference. Effort S.~~
> **Done (2026-09-12):** see commit `4bbd8a5`. Deleted `plugins/git/config.example.json` (the runtime `.claude/plugins/git/config.json` was never a tracked file). Removed the config-read step from `git-orchestrate`'s Process and from `git-branches`' Step 1, leaving the existing default-inference logic (GitHub Flow, with Gitflow inferred from a `develop`/`release/*` branch) as the sole path; updated `git-workflow`'s description of the orchestrator's behaviour to match. Dropped the now-dangling `applied_config` field from `git-orchestrate`'s output shape and the `config.example.json` example from `docs/spec/architecture.md`.
### 4.4 bin, core, lint (88 + 49 + 31 files incl. mirror) ### 4.4 bin, core, lint (88 + 49 + 31 files incl. mirror)

View File

@@ -47,7 +47,7 @@ Two compilers produce the plugin roots you see in the tree:
- **`apm pack` compiles the manifests** (ADR-0015). Per plugin: `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`, both generated from `plugins/<name>/apm.yml`. Repo-wide, from the root `apm.yml`'s `marketplace:` block: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file). Those two are the only marketplace outputs apm has profiles for — the third root manifest, `.github/plugin/marketplace.json` (Copilot CLI's legacy path), is a byte-identical mirror of the Claude one maintained by `scripts/sync-marketplace-mirror.sh` and gated by the `check-marketplace-mirror-sync` pre-push hook. - **`apm pack` compiles the manifests** (ADR-0015). Per plugin: `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`, both generated from `plugins/<name>/apm.yml`. Repo-wide, from the root `apm.yml`'s `marketplace:` block: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file). Those two are the only marketplace outputs apm has profiles for — the third root manifest, `.github/plugin/marketplace.json` (Copilot CLI's legacy path), is a byte-identical mirror of the Claude one maintained by `scripts/sync-marketplace-mirror.sh` and gated by the `check-marketplace-mirror-sync` pre-push hook.
- **`scripts/sync-plugin-content.sh` compiles the content mirror** (ADR-0017). It wraps `apm pack --format plugin` and copies the resulting bundle's flat `agents/`, `skills/`, `commands/`, `instructions/`, `extensions/`, and merged `hooks/hooks.json` back to the plugin root. Claude Code's installer convention-scans those flat paths and has no `.apm/` awareness whatsoever, so the mirror exists solely to satisfy the host's discovery contract. - **`scripts/sync-plugin-content.sh` compiles the content mirror** (ADR-0017). It wraps `apm pack --format plugin` and copies the resulting bundle's flat `agents/`, `skills/`, `commands/`, `instructions/`, `extensions/`, and merged `hooks/hooks.json` back to the plugin root. Claude Code's installer convention-scans those flat paths and has no `.apm/` awareness whatsoever, so the mirror exists solely to satisfy the host's discovery contract.
`.apm/` is the sole hand-edited authoring source for plugin content. An edit made in the flat mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, and per-plugin extras such as `plugins/git/config.example.json`, `plugins/gitea/references/` and `plugins/bin/evals/` — lives at the plugin **root** and is untouched by either compiler. `.apm/` is the sole hand-edited authoring source for plugin content. An edit made in the flat mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, and per-plugin extras such as `plugins/gitea/references/` and `plugins/bin/evals/` — lives at the plugin **root** and is untouched by either compiler.
That immunity is positional, not by filename. Anything placed *inside* a mirrored directory is destroyed regardless of what it is: `sync_dir` runs `rm -rf "$dst"` before every copy, and `sync_hooks_json` does the same to `hooks/`. A hand-written `README.md` under `plugins/<name>/hooks/` or `plugins/<name>/skills/` is deleted by the next sync with no drift report, because a file with no `.apm/` counterpart is simply absent from the regenerated tree. This has already cost the repo one document — `plugins/kyberforge/hooks/README.md`, since restored to `plugins/kyberforge/docs/hooks.md`. Plugin-root documentation belongs in `docs/`. That immunity is positional, not by filename. Anything placed *inside* a mirrored directory is destroyed regardless of what it is: `sync_dir` runs `rm -rf "$dst"` before every copy, and `sync_hooks_json` does the same to `hooks/`. A hand-written `README.md` under `plugins/<name>/hooks/` or `plugins/<name>/skills/` is deleted by the next sync with no drift report, because a file with no `.apm/` counterpart is simply absent from the regenerated tree. This has already cost the repo one document — `plugins/kyberforge/hooks/README.md`, since restored to `plugins/kyberforge/docs/hooks.md`. Plugin-root documentation belongs in `docs/`.

View File

@@ -63,11 +63,10 @@ When invoked, you:
1. Validate the request structure and check if operation is known 1. Validate the request structure and check if operation is known
2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm` 2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm`
3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error 3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error
4. Read plugin config from `.claude/plugins/git/config.json` if present — see `config.example.json` in the plugin root for the expected shape (`branching_pattern`, `commit_style`, `rebase_strategy`) — or fall back to sensible defaults 4. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, and context — each domain skill infers its own branching pattern and conventions (e.g. `git-branches` from `develop`/`release/*` branch presence) rather than reading shared config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above).
5. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, context, and config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above). 5. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections)
6. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections) 6. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions
7. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions 7. Aggregate all outputs and return as structured JSON
8. Aggregate all outputs and return as structured JSON
## Output ## Output
@@ -77,8 +76,7 @@ When invoked, you:
"operation": "<operation_name>", "operation": "<operation_name>",
"result": { "result": {
"output": "<command output or result>", "output": "<command output or result>",
"context": { "current_branch": "...", "workflow_intent": "..." }, "context": { "current_branch": "...", "workflow_intent": "..." }
"applied_config": { "commit_style": "...", "rebase_strategy": "..." }
}, },
"error": { "error": {
"message": "<human-readable error>", "message": "<human-readable error>",

View File

@@ -9,7 +9,7 @@ description: >
Not a Gitea remote's branches -> `gitea-branches`. Not a Gitea remote's branches -> `gitea-branches`.
metadata: metadata:
version: "1.0.2" version: "1.0.3"
category: git category: git
source_keys: source_keys:
- context7-git-htmldocs - context7-git-htmldocs
@@ -26,7 +26,7 @@ metadata:
## Step 1 — Determine the branching pattern ## Step 1 — Determine the branching pattern
Read `branching_pattern` from the git plugin config (`.claude/plugins/git/config.json`; the plugin root's `config.example.json` shows the shape). Default: `github-flow`. With no config, infer Gitflow from the presence of a `develop` or `release/*` branch, and GitHub Flow otherwise. Infer the branching pattern from the repo: Gitflow if a `develop` or `release/*` branch exists, GitHub Flow otherwise (the default).
The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`. The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`.

View File

@@ -8,7 +8,7 @@ description: >
agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`.
metadata: metadata:
version: "1.0.0" version: "1.0.1"
category: git category: git
source_keys: source_keys:
- nvie-gitflow-post - nvie-gitflow-post
@@ -55,8 +55,8 @@ owns the request.
touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule
before acting, not after. before acting, not after.
3. **Read the repo** — current branch, working-tree state, and which branching model the repo 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 follows (`git-branches` infers this from branch names: Gitflow if `develop`/`release/*` exists,
if absent); the last of those decides which tips are worth offering. GitHub Flow otherwise); the last of those decides which tips are worth offering.
4. **Gate destructive operations** — before force-push, branch deletion, rebase, or 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 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 declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not

View File

@@ -63,11 +63,10 @@ When invoked, you:
1. Validate the request structure and check if operation is known 1. Validate the request structure and check if operation is known
2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm` 2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm`
3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error 3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error
4. Read plugin config from `.claude/plugins/git/config.json` if present — see `config.example.json` in the plugin root for the expected shape (`branching_pattern`, `commit_style`, `rebase_strategy`) — or fall back to sensible defaults 4. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, and context — each domain skill infers its own branching pattern and conventions (e.g. `git-branches` from `develop`/`release/*` branch presence) rather than reading shared config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above).
5. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, context, and config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above). 5. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections)
6. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections) 6. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions
7. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions 7. Aggregate all outputs and return as structured JSON
8. Aggregate all outputs and return as structured JSON
## Output ## Output
@@ -77,8 +76,7 @@ When invoked, you:
"operation": "<operation_name>", "operation": "<operation_name>",
"result": { "result": {
"output": "<command output or result>", "output": "<command output or result>",
"context": { "current_branch": "...", "workflow_intent": "..." }, "context": { "current_branch": "...", "workflow_intent": "..." }
"applied_config": { "commit_style": "...", "rebase_strategy": "..." }
}, },
"error": { "error": {
"message": "<human-readable error>", "message": "<human-readable error>",

View File

@@ -1,5 +0,0 @@
{
"branching_pattern": "github-flow",
"commit_style": "conventional",
"rebase_strategy": "interactive"
}

View File

@@ -9,7 +9,7 @@ description: >
Not a Gitea remote's branches -> `gitea-branches`. Not a Gitea remote's branches -> `gitea-branches`.
metadata: metadata:
version: "1.0.2" version: "1.0.3"
category: git category: git
source_keys: source_keys:
- context7-git-htmldocs - context7-git-htmldocs
@@ -26,7 +26,7 @@ metadata:
## Step 1 — Determine the branching pattern ## Step 1 — Determine the branching pattern
Read `branching_pattern` from the git plugin config (`.claude/plugins/git/config.json`; the plugin root's `config.example.json` shows the shape). Default: `github-flow`. With no config, infer Gitflow from the presence of a `develop` or `release/*` branch, and GitHub Flow otherwise. Infer the branching pattern from the repo: Gitflow if a `develop` or `release/*` branch exists, GitHub Flow otherwise (the default).
The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`. The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`.

View File

@@ -8,7 +8,7 @@ description: >
agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`.
metadata: metadata:
version: "1.0.0" version: "1.0.1"
category: git category: git
source_keys: source_keys:
- nvie-gitflow-post - nvie-gitflow-post
@@ -55,8 +55,8 @@ owns the request.
touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule
before acting, not after. before acting, not after.
3. **Read the repo** — current branch, working-tree state, and which branching model the repo 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 follows (`git-branches` infers this from branch names: Gitflow if `develop`/`release/*` exists,
if absent); the last of those decides which tips are worth offering. GitHub Flow otherwise); the last of those decides which tips are worth offering.
4. **Gate destructive operations** — before force-push, branch deletion, rebase, or 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 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 declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not