diff --git a/SIMPLIFICATION-AUDIT.md b/SIMPLIFICATION-AUDIT.md index b273427..83b8af7 100644 --- a/SIMPLIFICATION-AUDIT.md +++ b/SIMPLIFICATION-AUDIT.md @@ -99,7 +99,8 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research 12. [x] ~~**Strip ADR and changelog narration from model-facing files.** `ADR-0020` is cited in 3 of 7 kyberforge SKILL.md files and 16 references; ADR-0023 is cited inline 21 times in the git plugin. Examples: "was the old house rule and ADR-0020 deleted it", "were removed per ADR-0015 once issue #90 landed", "this file previously recorded `list_issues` as having neither a `type` nor a `milestones` parameter". `skill-author/references/retrofit.md` (197 lines) is a one-time migration guide; it is loaded from `improve.md` and listed in `sources.md`, so remove those in the same change. These belong in git history or the ADR, not in context. Effort S.~~ > **Done (2026-09-12):** see commit `edcc57c` on `docs/simplification-audit`. Historical narration stripped from kyberforge (ADR-0020) and git (ADR-0023) skill content; `retrofit.md` deleted along with its load-step and `sources.md` entries. Caught in review: some `ADR-0023` tags were not narration but the `check-rtk-prefix` hook's required opt-out marker for intentionally-bare git commands — those 12 were restored, not left stripped. -13. **State repeated boilerplate once or delete it.** A near-identical "Resolve owner and repo" block in 5 of 7 gitea skills; 404-masks-403 in 6 files; manual pagination in 7; main/master refusal in 9 git files; the "use the project's domain glossary, respect ADRs" paragraph in 5 bin skills. Three git skills define three different structured-result JSON shapes whose only consumer is `git-orchestrate` (finding 19). Effort S. +13. [x] ~~**State repeated boilerplate once or delete it.** A near-identical "Resolve owner and repo" block in 5 of 7 gitea skills; 404-masks-403 in 6 files; manual pagination in 7; main/master refusal in 9 git files; the "use the project's domain glossary, respect ADRs" paragraph in 5 bin skills. Three git skills define three different structured-result JSON shapes whose only consumer is `git-orchestrate` (finding 19). Effort S.~~ + > **Done (2026-09-12):** see commit `b4c3d5e`. Trimmed each repeated instance in place — same meaning, fewer words — rather than extracting to a shared file (blocked by the one-file-per-skill install constraint, ADR-0014): the "Resolve owner and repo" block across 5 `gitea-*` skills, the 404-masks-403 note across 6 gitea files, the manual-pagination explanation across 8 gitea files, the main/master force-push refusal across 7 git plugin files (some with multiple internal restatements), and the domain-glossary/ADR paragraph across 5 `bin` skills. This was a trim-in-place pass, not a merge: the cross-skill duplication itself remains and is coupled to the (out-of-scope) skill-merge findings 19/20. Left the three git skills' structured-result JSON shapes untouched, as directed. Verified no regressions with `scripts/skill-size-check.sh` (pre/post diff) and `claude plugin validate` on both plugins. ### 4.2 kyberforge (290 files, 44,568 lines incl. mirror; the 7 SKILL.md bodies are 333 lines, under 1%) diff --git a/plugins/bin/.apm/skills/diagnose/SKILL.md b/plugins/bin/.apm/skills/diagnose/SKILL.md index ee85d02..38d8f4a 100644 --- a/plugins/bin/.apm/skills/diagnose/SKILL.md +++ b/plugins/bin/.apm/skills/diagnose/SKILL.md @@ -5,14 +5,14 @@ description: > broken, throwing, or failing, or says something got slow. Not filing or triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Diagnose A discipline for hard bugs. Skip phases only when explicitly justified. -When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching. +When exploring the codebase, use the domain glossary for a clear mental model of the relevant modules, and check ADRs in the area. ## Phase 1 — Build a feedback loop diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md index 00793b8..dca8068 100644 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md @@ -7,7 +7,7 @@ description: > into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a failure -> `diagnose`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Improve Codebase Architecture @@ -41,7 +41,7 @@ This skill is _informed_ by the project's domain model. The domain language give ### 1. Explore -Read the project's domain glossary and any ADRs in the area you're touching first. +Read the domain glossary and any ADRs in the area first. Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: diff --git a/plugins/bin/.apm/skills/tdd/SKILL.md b/plugins/bin/.apm/skills/tdd/SKILL.md index e76a480..48dc6b7 100644 --- a/plugins/bin/.apm/skills/tdd/SKILL.md +++ b/plugins/bin/.apm/skills/tdd/SKILL.md @@ -5,7 +5,7 @@ description: > red-green-refactor loop, one behaviour at a time. Not diagnosing an existing bug -> `diagnose`. Not throwaway exploratory code -> `prototype`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Test-Driven Development @@ -49,7 +49,7 @@ RIGHT (vertical): ### 1. Planning -When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching. +When exploring the codebase, use the domain glossary so test names and interface vocabulary match the project's language, and respect ADRs in the area. Before writing any code: diff --git a/plugins/bin/.apm/skills/triage/SKILL.md b/plugins/bin/.apm/skills/triage/SKILL.md index 7dc8f0e..fd63160 100644 --- a/plugins/bin/.apm/skills/triage/SKILL.md +++ b/plugins/bin/.apm/skills/triage/SKILL.md @@ -5,7 +5,7 @@ description: > tracker's triage states, or an issue prepared for an AFK agent. Not debugging the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Triage @@ -65,7 +65,7 @@ Show counts and a one-line summary per issue. Let the maintainer pick. ## Triage a specific issue -1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue. +1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue. 2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction. diff --git a/plugins/bin/.apm/skills/zoom-out/SKILL.md b/plugins/bin/.apm/skills/zoom-out/SKILL.md index 4ba619a..cac432d 100644 --- a/plugins/bin/.apm/skills/zoom-out/SKILL.md +++ b/plugins/bin/.apm/skills/zoom-out/SKILL.md @@ -3,7 +3,7 @@ name: zoom-out description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture. disable-model-invocation: true metadata: - version: "1.0.0" + version: "1.0.1" --- -I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary. +I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary. diff --git a/plugins/bin/skills/diagnose/SKILL.md b/plugins/bin/skills/diagnose/SKILL.md index ee85d02..38d8f4a 100644 --- a/plugins/bin/skills/diagnose/SKILL.md +++ b/plugins/bin/skills/diagnose/SKILL.md @@ -5,14 +5,14 @@ description: > broken, throwing, or failing, or says something got slow. Not filing or triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Diagnose A discipline for hard bugs. Skip phases only when explicitly justified. -When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching. +When exploring the codebase, use the domain glossary for a clear mental model of the relevant modules, and check ADRs in the area. ## Phase 1 — Build a feedback loop diff --git a/plugins/bin/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/skills/improve-codebase-architecture/SKILL.md index 00793b8..dca8068 100644 --- a/plugins/bin/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/skills/improve-codebase-architecture/SKILL.md @@ -7,7 +7,7 @@ description: > into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a failure -> `diagnose`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Improve Codebase Architecture @@ -41,7 +41,7 @@ This skill is _informed_ by the project's domain model. The domain language give ### 1. Explore -Read the project's domain glossary and any ADRs in the area you're touching first. +Read the domain glossary and any ADRs in the area first. Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: diff --git a/plugins/bin/skills/tdd/SKILL.md b/plugins/bin/skills/tdd/SKILL.md index e76a480..48dc6b7 100644 --- a/plugins/bin/skills/tdd/SKILL.md +++ b/plugins/bin/skills/tdd/SKILL.md @@ -5,7 +5,7 @@ description: > red-green-refactor loop, one behaviour at a time. Not diagnosing an existing bug -> `diagnose`. Not throwaway exploratory code -> `prototype`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Test-Driven Development @@ -49,7 +49,7 @@ RIGHT (vertical): ### 1. Planning -When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching. +When exploring the codebase, use the domain glossary so test names and interface vocabulary match the project's language, and respect ADRs in the area. Before writing any code: diff --git a/plugins/bin/skills/triage/SKILL.md b/plugins/bin/skills/triage/SKILL.md index 7dc8f0e..fd63160 100644 --- a/plugins/bin/skills/triage/SKILL.md +++ b/plugins/bin/skills/triage/SKILL.md @@ -5,7 +5,7 @@ description: > tracker's triage states, or an issue prepared for an AFK agent. Not debugging the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Triage @@ -65,7 +65,7 @@ Show counts and a one-line summary per issue. Let the maintainer pick. ## Triage a specific issue -1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue. +1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue. 2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction. diff --git a/plugins/bin/skills/zoom-out/SKILL.md b/plugins/bin/skills/zoom-out/SKILL.md index 4ba619a..cac432d 100644 --- a/plugins/bin/skills/zoom-out/SKILL.md +++ b/plugins/bin/skills/zoom-out/SKILL.md @@ -3,7 +3,7 @@ name: zoom-out description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture. disable-model-invocation: true metadata: - version: "1.0.0" + version: "1.0.1" --- -I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary. +I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary. diff --git a/plugins/git/.apm/agents/git-orchestrate.agent.md b/plugins/git/.apm/agents/git-orchestrate.agent.md index afb879e..7d6aaa6 100644 --- a/plugins/git/.apm/agents/git-orchestrate.agent.md +++ b/plugins/git/.apm/agents/git-orchestrate.agent.md @@ -40,7 +40,7 @@ Sub-skills carry their own local copies of these rules for humans who invoke the When invoked, you: 1. Parse the incoming workflow request (operation type, parameters, context overrides) -2. Check safety gates: if the operation is destructive (force-push, branch deletion, rebase with history loss, force-checkout) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm` +2. Check safety gates: a destructive operation (force-push, branch deletion, history-losing rebase, force-checkout) without `confirm: true` fails immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm` 3. Route to the appropriate domain skill: `git-commits`, `git-branches`, `git-history`, `git-submodules`, `git-worktrees`, `git-remotes` 4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill 5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics diff --git a/plugins/git/.apm/skills/git-branches/SKILL.md b/plugins/git/.apm/skills/git-branches/SKILL.md index 20bf965..e38514f 100644 --- a/plugins/git/.apm/skills/git-branches/SKILL.md +++ b/plugins/git/.apm/skills/git-branches/SKILL.md @@ -9,7 +9,7 @@ description: > Not a Gitea remote's branches -> `gitea-branches`. metadata: - version: "1.0.3" + version: "1.0.4" category: git source_keys: - context7-git-htmldocs @@ -22,7 +22,7 @@ metadata: - **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears. - **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list ` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list `; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/` or `refs/tags/`. -- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead. +- **`main`/`master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming either is rejected even with `confirm: true` — no flag recovers the remote's history. Offer a new branch instead. ## Step 1 — Determine the branching pattern diff --git a/plugins/git/.apm/skills/git-commits/SKILL.md b/plugins/git/.apm/skills/git-commits/SKILL.md index 296ec18..145bb79 100644 --- a/plugins/git/.apm/skills/git-commits/SKILL.md +++ b/plugins/git/.apm/skills/git-commits/SKILL.md @@ -8,7 +8,7 @@ description: > Not branch lifecycle -> `git-branches`. metadata: - version: "0.1.5" + version: "0.1.6" category: git source_keys: - conventional-commits-spec @@ -22,7 +22,7 @@ allowed-tools: Bash ## Gotchas - **Run git as `rtk git `, never bare `git`** — org convention, in `&&` chains too, except where a skill's Gotchas name a specific bare-git case (interactive rebase here). -- **Refuse to force-push `main`/`master`** — a rewrite leaves the branch diverged and the reflex is to force it back; safe only where nobody else has based work on it. +- **Refuse to force-push `main`/`master`.** A rewrite diverges the branch and the reflex is to force it back — safe only where nobody else has based work on it. - **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first. - **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning. diff --git a/plugins/git/.apm/skills/git-commits/references/rewrite-history.md b/plugins/git/.apm/skills/git-commits/references/rewrite-history.md index 793f2bb..d25b22c 100644 --- a/plugins/git/.apm/skills/git-commits/references/rewrite-history.md +++ b/plugins/git/.apm/skills/git-commits/references/rewrite-history.md @@ -6,14 +6,14 @@ source_keys: # Rewriting existing commits -Every flow on this page rewrites history. None of them runs before the caller has explicitly approved it, and none is followed by a force-push to `main`/`master` — refuse that and explain why instead. +Every flow here rewrites history. None runs without explicit approval, and none ends in a force-push to `main`/`master` — refuse that and explain why. ## Amend the last commit 1. Stage the new changes, or the changes that undo something. 2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is. 3. If the message should change, show the current one and prompt for the replacement. -4. The branch has now diverged from its remote. Amending is safe only on a branch nobody else has based work on; on `main`/`master`, refuse the force-push and explain, rather than warning and proceeding. +4. The branch has diverged from its remote. Amending is safe only where nobody else has based work on it; on `main`/`master`, refuse the force-push and explain rather than warn and proceed. ## Fold a commit into an earlier one (autosquash — preferred) @@ -50,9 +50,8 @@ date without a merge commit. 4. `rtk git rebase ` — for example `rtk git rebase main`. Use `rtk git rebase --onto ` to replay only the commits after ``, which is how a branch started from the wrong base gets moved. -5. The branch has now diverged from its remote. It needs - `--force-with-lease --force-if-includes` to push, never a bare `--force`, and never on - `main`/`master` — refuse that and explain. +5. The branch has diverged from its remote. Push needs `--force-with-lease --force-if-includes`, + never a bare `--force` — and never on `main`/`master`; refuse that and explain. ## Move the branch pointer back (`git reset`) diff --git a/plugins/git/.apm/skills/git-remotes/SKILL.md b/plugins/git/.apm/skills/git-remotes/SKILL.md index e21ddf3..5ef896a 100644 --- a/plugins/git/.apm/skills/git-remotes/SKILL.md +++ b/plugins/git/.apm/skills/git-remotes/SKILL.md @@ -10,7 +10,7 @@ description: > Not submodule pointers -> `git-submodules`. metadata: - version: "1.0.2" + version: "1.0.3" category: git source_keys: - git-scm-remote-docs @@ -28,7 +28,7 @@ metadata: ## Step 1 — Clear the force-push gate -`main` and `master` are a hard refusal: decline a force-push targeting either, whatever confirmation accompanies it, because no local approval can restore what the remote loses. On any other branch, `rtk git push --force` and `-f` run only after the caller passes `confirm: true` for that specific push — for a human caller, prompt instead of failing. +`main`/`master` are a hard refusal: decline a force-push to either regardless of confirmation — no local approval restores what the remote loses. Elsewhere, `rtk git push --force`/`-f` run only after `confirm: true` for that specific push; for a human caller, prompt instead of failing. ## Step 2 — Dispatch diff --git a/plugins/git/.apm/skills/git-workflow/SKILL.md b/plugins/git/.apm/skills/git-workflow/SKILL.md index 07ce074..528904d 100644 --- a/plugins/git/.apm/skills/git-workflow/SKILL.md +++ b/plugins/git/.apm/skills/git-workflow/SKILL.md @@ -8,7 +8,7 @@ description: > agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - nvie-gitflow-post @@ -60,7 +60,7 @@ owns the request. 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`. + confirmations — never offer "Proceed?" for a force-push of `main`/`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. diff --git a/plugins/git/agents/git-orchestrate.agent.md b/plugins/git/agents/git-orchestrate.agent.md index afb879e..7d6aaa6 100644 --- a/plugins/git/agents/git-orchestrate.agent.md +++ b/plugins/git/agents/git-orchestrate.agent.md @@ -40,7 +40,7 @@ Sub-skills carry their own local copies of these rules for humans who invoke the When invoked, you: 1. Parse the incoming workflow request (operation type, parameters, context overrides) -2. Check safety gates: if the operation is destructive (force-push, branch deletion, rebase with history loss, force-checkout) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm` +2. Check safety gates: a destructive operation (force-push, branch deletion, history-losing rebase, force-checkout) without `confirm: true` fails immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm` 3. Route to the appropriate domain skill: `git-commits`, `git-branches`, `git-history`, `git-submodules`, `git-worktrees`, `git-remotes` 4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill 5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics diff --git a/plugins/git/skills/git-branches/SKILL.md b/plugins/git/skills/git-branches/SKILL.md index 20bf965..e38514f 100644 --- a/plugins/git/skills/git-branches/SKILL.md +++ b/plugins/git/skills/git-branches/SKILL.md @@ -9,7 +9,7 @@ description: > Not a Gitea remote's branches -> `gitea-branches`. metadata: - version: "1.0.3" + version: "1.0.4" category: git source_keys: - context7-git-htmldocs @@ -22,7 +22,7 @@ metadata: - **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears. - **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list ` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list `; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/` or `refs/tags/`. -- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead. +- **`main`/`master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming either is rejected even with `confirm: true` — no flag recovers the remote's history. Offer a new branch instead. ## Step 1 — Determine the branching pattern diff --git a/plugins/git/skills/git-commits/SKILL.md b/plugins/git/skills/git-commits/SKILL.md index 296ec18..145bb79 100644 --- a/plugins/git/skills/git-commits/SKILL.md +++ b/plugins/git/skills/git-commits/SKILL.md @@ -8,7 +8,7 @@ description: > Not branch lifecycle -> `git-branches`. metadata: - version: "0.1.5" + version: "0.1.6" category: git source_keys: - conventional-commits-spec @@ -22,7 +22,7 @@ allowed-tools: Bash ## Gotchas - **Run git as `rtk git `, never bare `git`** — org convention, in `&&` chains too, except where a skill's Gotchas name a specific bare-git case (interactive rebase here). -- **Refuse to force-push `main`/`master`** — a rewrite leaves the branch diverged and the reflex is to force it back; safe only where nobody else has based work on it. +- **Refuse to force-push `main`/`master`.** A rewrite diverges the branch and the reflex is to force it back — safe only where nobody else has based work on it. - **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first. - **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning. diff --git a/plugins/git/skills/git-commits/references/rewrite-history.md b/plugins/git/skills/git-commits/references/rewrite-history.md index 793f2bb..d25b22c 100644 --- a/plugins/git/skills/git-commits/references/rewrite-history.md +++ b/plugins/git/skills/git-commits/references/rewrite-history.md @@ -6,14 +6,14 @@ source_keys: # Rewriting existing commits -Every flow on this page rewrites history. None of them runs before the caller has explicitly approved it, and none is followed by a force-push to `main`/`master` — refuse that and explain why instead. +Every flow here rewrites history. None runs without explicit approval, and none ends in a force-push to `main`/`master` — refuse that and explain why. ## Amend the last commit 1. Stage the new changes, or the changes that undo something. 2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is. 3. If the message should change, show the current one and prompt for the replacement. -4. The branch has now diverged from its remote. Amending is safe only on a branch nobody else has based work on; on `main`/`master`, refuse the force-push and explain, rather than warning and proceeding. +4. The branch has diverged from its remote. Amending is safe only where nobody else has based work on it; on `main`/`master`, refuse the force-push and explain rather than warn and proceed. ## Fold a commit into an earlier one (autosquash — preferred) @@ -50,9 +50,8 @@ date without a merge commit. 4. `rtk git rebase ` — for example `rtk git rebase main`. Use `rtk git rebase --onto ` to replay only the commits after ``, which is how a branch started from the wrong base gets moved. -5. The branch has now diverged from its remote. It needs - `--force-with-lease --force-if-includes` to push, never a bare `--force`, and never on - `main`/`master` — refuse that and explain. +5. The branch has diverged from its remote. Push needs `--force-with-lease --force-if-includes`, + never a bare `--force` — and never on `main`/`master`; refuse that and explain. ## Move the branch pointer back (`git reset`) diff --git a/plugins/git/skills/git-remotes/SKILL.md b/plugins/git/skills/git-remotes/SKILL.md index e21ddf3..5ef896a 100644 --- a/plugins/git/skills/git-remotes/SKILL.md +++ b/plugins/git/skills/git-remotes/SKILL.md @@ -10,7 +10,7 @@ description: > Not submodule pointers -> `git-submodules`. metadata: - version: "1.0.2" + version: "1.0.3" category: git source_keys: - git-scm-remote-docs @@ -28,7 +28,7 @@ metadata: ## Step 1 — Clear the force-push gate -`main` and `master` are a hard refusal: decline a force-push targeting either, whatever confirmation accompanies it, because no local approval can restore what the remote loses. On any other branch, `rtk git push --force` and `-f` run only after the caller passes `confirm: true` for that specific push — for a human caller, prompt instead of failing. +`main`/`master` are a hard refusal: decline a force-push to either regardless of confirmation — no local approval restores what the remote loses. Elsewhere, `rtk git push --force`/`-f` run only after `confirm: true` for that specific push; for a human caller, prompt instead of failing. ## Step 2 — Dispatch diff --git a/plugins/git/skills/git-workflow/SKILL.md b/plugins/git/skills/git-workflow/SKILL.md index 07ce074..528904d 100644 --- a/plugins/git/skills/git-workflow/SKILL.md +++ b/plugins/git/skills/git-workflow/SKILL.md @@ -8,7 +8,7 @@ description: > agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - nvie-gitflow-post @@ -60,7 +60,7 @@ owns the request. 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`. + confirmations — never offer "Proceed?" for a force-push of `main`/`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. diff --git a/plugins/gitea/.apm/skills/gitea-branches/SKILL.md b/plugins/gitea/.apm/skills/gitea-branches/SKILL.md index 47c113a..820a55e 100644 --- a/plugins/gitea/.apm/skills/gitea-branches/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-branches/SKILL.md @@ -23,19 +23,19 @@ allowed-tools: Bash mcp__gitea__list_branches mcp__gitea__create_branch mcp__git ## Gotchas -- **404 often means 403.** Gitea masks permission errors as not-found; on an unexpected one, check token scope before reporting a branch or commit missing. -- **Nothing auto-paginates.** `list_branches` and `list_commits` return one page; iterate `page` until the returned count is below `per_page`. +- **404 can mean 403.** Gitea masks permission errors as not-found — check token scope before reporting a branch or commit missing. +- **Nothing auto-paginates.** `list_branches`/`list_commits` return one page — iterate `page` until the count is below `per_page`. - **`delete_branch` has no force-push guard.** Treat deleting a protected branch as a hard refusal unless the user explicitly confirms it in the conversation. Check `protected` from `list_branches` first — a protected branch need not be named `main`. ## Step 1 — Resolve owner and repo -Before any tool call, extract `owner` and `repo` from the git remote: +Extract `owner` and `repo` from the git remote before any tool call — `get_me` and `list_my_repos` are blocked under this skill's token scope, so the remote is the only source: ```bash rtk git remote get-url origin ``` -`get_me` and `list_my_repos` are blocked under the token scope this skill assumes, so the remote is the only source. If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/.apm/skills/gitea-branches/references/branches.md b/plugins/gitea/.apm/skills/gitea-branches/references/branches.md index d4643a3..4e66709 100644 --- a/plugins/gitea/.apm/skills/gitea-branches/references/branches.md +++ b/plugins/gitea/.apm/skills/gitea-branches/references/branches.md @@ -29,8 +29,7 @@ list_branches owner: repo: **Response:** one object per branch: `name`, `protected` (bool), `commit_sha` (present when the underlying commit data is available). -Paginate if you need the full list (see Gotchas in SKILL.md) — iterate `page` until the returned -count is less than `per_page`. +Paginate for the full list (see Gotchas) — iterate `page` until the count is less than `per_page`. ## `create_branch` diff --git a/plugins/gitea/.apm/skills/gitea-files/SKILL.md b/plugins/gitea/.apm/skills/gitea-files/SKILL.md index 26265da..0923b56 100644 --- a/plugins/gitea/.apm/skills/gitea-files/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-files/SKILL.md @@ -11,7 +11,7 @@ compatibility: Requires the Gitea MCP server configured with a token scoped to a is not actually required for any of this domain's five tools. metadata: - version: "1.0.0" + version: "1.0.1" category: gitea source_keys: - gitea-mcp-repo @@ -23,7 +23,7 @@ allowed-tools: mcp__gitea__get_file_contents mcp__gitea__get_dir_contents mcp__g ## Gotchas -- **A 404 may mean an under-scoped token, not a missing path.** Every tool here gates on `write:repository`, and Gitea masks insufficient scope as 404. Check scopes first. +- **404 may mean an under-scoped token, not a missing path.** These tools gate on `write:repository`; check scope before concluding the path is missing. - **Reads take `ref` (`tree_sha` on `get_repository_tree`), writes take `branch_name`.** One concept, three names — carry the wrong key and the branch is dropped. - **`content` is base64 both ways — except under `withLines: true`.** Encode before a write, decode after a read; but with `withLines: true` `content` is already plain JSON text and the reported `"encoding": "base64"` is a lie. Decoding it yields garbage. diff --git a/plugins/gitea/.apm/skills/gitea-files/references/reading.md b/plugins/gitea/.apm/skills/gitea-files/references/reading.md index db2aa15..f10366a 100644 --- a/plugins/gitea/.apm/skills/gitea-files/references/reading.md +++ b/plugins/gitea/.apm/skills/gitea-files/references/reading.md @@ -32,8 +32,8 @@ size. No recursion, no content, no `sha`. `get_repository_tree(owner, repo, tree_sha, recursive)`. Set `recursive: true` to walk subdirectories in one call. -The response sets `truncated: true` when one page does not hold every entry. Page through with -`page`/`per_page` (defaults `1` and `30`) until a page returns fewer entries than `per_page`. +The response sets `truncated: true` when one page doesn't hold every entry — page with +`page`/`per_page` (defaults `1`/`30`) until a page returns fewer than `per_page`. ## Neither listing is a SHA source for a write @@ -44,7 +44,6 @@ the canonical path for a write's SHA: one call returns the decoded content and t ## A 404 that is really a 403 -These reads gate on `write:repository`, not on read access alone, and some Gitea endpoints answer -an under-scoped token with 404 instead of 403 so they do not leak whether the resource exists. A -404 on a path you are confident about is a scope problem until proven otherwise — check the token's -configured scopes before concluding the file or directory does not exist. +These reads gate on `write:repository`; an under-scoped token gets 404 instead of 403 so the +endpoint doesn't leak whether the resource exists. On a path you're confident about, check token +scope before concluding it doesn't exist. diff --git a/plugins/gitea/.apm/skills/gitea-issues/SKILL.md b/plugins/gitea/.apm/skills/gitea-issues/SKILL.md index ab785f8..cc9ce3a 100644 --- a/plugins/gitea/.apm/skills/gitea-issues/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-issues/SKILL.md @@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with write:issue and write:r metadata: category: integration - version: "0.1.4" + version: "0.1.5" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go @@ -29,17 +29,17 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i - **`list_issues` mixes in PRs unless you filter.** Issues and PRs share one number space; pass `type: "issues"` to exclude PRs (or `"pulls"`). `is_pull` is returned only by `issue_read method: "get"` — on a list item the only tell is `html_url`'s path segment (`/issues/` vs `/pulls/`). - **Label IDs and names are not interchangeable.** `issue_write` takes numeric IDs only; `list_issues` and `search_issues` filter by name; `issue_read "get"` returns names but `"get_labels"` returns full objects with IDs. Resolve via `gitea-labels-milestones` unless the caller named exact labels. - **A merge does not itself close the issue.** Gitea has no close-on-merge event, but a `Fixes #N` in the merged commits can, depending on merge style (`gitea-prs`). Re-read its state after a merge before closing it manually. -- **A 404 may really be a 403.** Gitea hides permission errors as not-found — check the token's `write:issue` scope before concluding the issue does not exist. +- **404 may mean 403.** Gitea hides permission errors as not-found — check `write:issue` scope before concluding the issue doesn't exist. ## Step 1 — Resolve owner and repo -An orchestrating caller may pass `owner` and `repo` in already, and the `search` row is cross-repository and needs only a query — both skip this step. Otherwise, before any tool call: +Skip if an orchestrating caller already passed `owner`/`repo` in, or the action is `search` (cross-repository, needs only a query). Otherwise, before any tool call: ```bash rtk git remote get-url origin ``` -If origin is unset or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/.apm/skills/gitea-issues/references/issues.md b/plugins/gitea/.apm/skills/gitea-issues/references/issues.md index fe4248b..6292633 100644 --- a/plugins/gitea/.apm/skills/gitea-issues/references/issues.md +++ b/plugins/gitea/.apm/skills/gitea-issues/references/issues.md @@ -45,7 +45,7 @@ list_issues owner: repo: state: "open" type: "issues" `updated_at`, and optionally `labels` (`[]string`), `milestone` (`{id, title}`), `ref`, `deadline`. Body and `closed_at` are omitted from list responses — call `issue_read method: "get"` for those. -Paginate with `page`/`per_page` until the returned count is less than `per_page`. +Paginate: `page`/`per_page`, stop once the count is below `per_page`. ## `issue_read` diff --git a/plugins/gitea/.apm/skills/gitea-labels-milestones/SKILL.md b/plugins/gitea/.apm/skills/gitea-labels-milestones/SKILL.md index 6619a29..aa744ce 100644 --- a/plugins/gitea/.apm/skills/gitea-labels-milestones/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-labels-milestones/SKILL.md @@ -16,30 +16,30 @@ metadata: - gitea-mcp-slim-go - context7-websites-gitea - context7-gitea-tea-cli - version: "0.1.5" + version: "0.1.6" allowed-tools: Bash mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write --- ## Gotchas -- **Applying a label takes a numeric ID, but issue/PR responses slim labels down to name strings.** An issue's existing labels yield no IDs — resolve name → ID with `label_read`. -- **`pull_request_read` returns `milestone` as a bare title string** where `issue_read` returns `{id, title}` — recover the milestone's ID by listing milestones and matching the title. -- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's own `exclusive` field.** `list_repo_labels` returns it on every repo label, so it is always *readable* per label; `label_write` documents it as "(org only)" because it is only *settable* through the org create methods. Where it is `true` Gitea enforces one-per-scope itself, and replacing rather than stacking on a label whose `exclusive` is `false` destroys a valid label. +- **Applying a label needs a numeric ID; issue/PR responses give only name strings.** Resolve name → ID with `label_read` first. +- **`pull_request_read` returns `milestone` as a bare title string, `issue_read` as `{id, title}`.** Recover the ID by listing milestones and matching the title. +- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's `exclusive` field.** `list_repo_labels` always returns it; `label_write` can only set it via org create methods ("org only"). `true` means Gitea enforces one-per-scope; replacing instead of stacking on a `false` label destroys a valid one. ## Step 1 — Resolve owner, repo and org -Before any tool call, extract `owner` and `repo` from the git remote (skip this if an orchestrating caller already passed them in): +Extract `owner` and `repo` from the git remote before any tool call (skip if an orchestrating caller already passed them in): ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." -The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it is the org name whenever the owner is an organisation, and the remote URL does not say whether it is one. +The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it's the org name whenever the owner is an organisation, which the remote URL doesn't say. -Read the failure text before interpreting it. `list_org_labels` needs the `read:organization` token scope, which this skill's declared scopes (`write:issue`, `write:repository`) do not carry, so it fails with `token does not have at least one of required scope(s), required=[read:organization]` *before* it ever determines org-vs-user. Report that: the org pool went unchecked, not empty. Only a not-found response is evidence the owner is a user account with no org pool. +Read the failure text before interpreting it: `list_org_labels` needs `read:organization`, which this skill's declared scopes don't carry, so it fails with a scope error *before* it ever checks org-vs-user. Report the unchecked scope, not an empty pool — only a genuine not-found means the owner is a user account with no org pool. ## Step 2 — Dispatch @@ -58,6 +58,6 @@ Read the failure text before interpreting it. `list_org_labels` needs the `read: | Update / close a milestone | `milestone_write` | `"update"` | | Delete a milestone | `milestone_write` | `"delete"` | -Every list method paginates manually — `per_page` defaults to 30, so iterate `page: 1, 2, ...` until a page returns fewer results than `per_page`. A truncated list silently breaks name → ID resolution. +Every list method paginates manually (`per_page` default 30) — iterate `page: 1, 2, ...` until a page returns fewer than `per_page`. A truncated list silently breaks name → ID resolution. If the task is a label operation, read `references/labels.md`; if a milestone operation, read `references/milestones.md`. If the label to apply has to be derived from conversation context rather than named, read `references/label-inference.md`. diff --git a/plugins/gitea/.apm/skills/gitea-labels-milestones/references/labels.md b/plugins/gitea/.apm/skills/gitea-labels-milestones/references/labels.md index 172cea2..ef44e16 100644 --- a/plugins/gitea/.apm/skills/gitea-labels-milestones/references/labels.md +++ b/plugins/gitea/.apm/skills/gitea-labels-milestones/references/labels.md @@ -51,8 +51,8 @@ runtime error from Gitea rather than a client-side validation error. label_read method: "list_repo_labels" owner: repo: per_page: 50 ``` -Paginate (`page: 1, 2, ...`) until the returned count is less than `per_page`. This is the only way -to build a complete name → ID map — there is no lookup-by-name endpoint. +Paginate (`page: 1, 2, ...`) until the count is below `per_page` — the only way to build a complete +name → ID map, since there's no lookup-by-name endpoint. Every returned repo label carries its own `exclusive` boolean, so exclusivity is always *readable* per repo label. That does not contradict `label_write`'s schema, which annotates `exclusive` as diff --git a/plugins/gitea/.apm/skills/gitea-prs/SKILL.md b/plugins/gitea/.apm/skills/gitea-prs/SKILL.md index 37ab15d..5b0ea59 100644 --- a/plugins/gitea/.apm/skills/gitea-prs/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-prs/SKILL.md @@ -19,7 +19,7 @@ metadata: - gitea-mcp-slim-go - context7-websites-gitea - context7-gitea-tea-cli - version: "0.1.3" + version: "0.1.4" allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp__gitea__pull_request_write mcp__gitea__pull_request_review_write --- @@ -31,13 +31,13 @@ allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read ## Step 1 — Resolve owner and repo -Extract them from the git remote before any tool call, skipping this when an orchestrating caller already passed them in: +Extract from the git remote before any tool call, skipping this when an orchestrating caller already passed them in: ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/.apm/skills/gitea-releases/SKILL.md b/plugins/gitea/.apm/skills/gitea-releases/SKILL.md index f55cd7d..6e7ccc6 100644 --- a/plugins/gitea/.apm/skills/gitea-releases/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-releases/SKILL.md @@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with a token with write:repo metadata: category: integration - version: "0.1.1" + version: "0.1.2" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go @@ -33,13 +33,13 @@ allowed-tools: Bash mcp__gitea__list_releases mcp__gitea__get_release mcp__gitea ## Step 1 — Resolve owner and repo -`owner` and `repo` are required on every tool below. Extract them from the git remote, unless an orchestrating caller passed them in already: +`owner` and `repo` are required on every tool below. Extract from the git remote, unless an orchestrating caller already passed them in: ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch @@ -68,6 +68,6 @@ These four are mutually exclusive — pick the one row the request lands on. | Create a release | Call `create_release` with `tag_name`, `target`, `title`, and `is_draft`/`is_pre_release` set explicitly — never left to default. This surface carries no update or edit tool, so a wrong flag is repairable only by delete-and-recreate (`references/conventions.md`). A separate `create_tag` is only needed to tag a commit without wrapping it in a release — whether `create_release` creates a missing tag is unconfirmed, so verify with `get_tag`. | | Delete a release | Resolve the numeric `id` per the first Gotcha, confirm intent, then call `delete_release`. The tag survives. | | Delete a tag along with its release | Delete the release first, then call `delete_tag` — confirm both are intended before proceeding, since each is irreversible on its own. | -| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries. Nothing here auto-paginates. | +| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries — nothing auto-paginates. | If exact input params or response field shapes are needed, read `references/call-signatures.md`. If the caller raises semver tag naming, draft/prerelease semantics, release-notes sourcing, or how a release relates to its tag, read `references/conventions.md`. diff --git a/plugins/gitea/.apm/skills/gitea-releases/references/call-signatures.md b/plugins/gitea/.apm/skills/gitea-releases/references/call-signatures.md index b81a6f9..46ca117 100644 --- a/plugins/gitea/.apm/skills/gitea-releases/references/call-signatures.md +++ b/plugins/gitea/.apm/skills/gitea-releases/references/call-signatures.md @@ -70,7 +70,6 @@ id, tag_name, target, title, body, draft, prerelease, html_url, author, created_ ## Pagination -None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then -`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and -`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list -tools, so a caller assuming 30 will under-count pages needed for a fixed total. +Nothing auto-paginates. Loop `page: 1, 2, ...` until a page returns fewer items than `per_page`. +`list_releases`/`list_tags` default `per_page` to 20, not the usual 30 — assuming 30 under-counts +pages needed. diff --git a/plugins/gitea/.apm/skills/gitea-workflow/SKILL.md b/plugins/gitea/.apm/skills/gitea-workflow/SKILL.md index b0d64f6..1528c14 100644 --- a/plugins/gitea/.apm/skills/gitea-workflow/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-workflow/SKILL.md @@ -13,7 +13,7 @@ compatibility: Requires Gitea MCP server configured with a token; delegates all metadata: category: integration - version: "0.1.3" + version: "0.1.4" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go diff --git a/plugins/gitea/.apm/skills/gitea-workflow/references/number-resolution.md b/plugins/gitea/.apm/skills/gitea-workflow/references/number-resolution.md index 357514b..ea8c8e6 100644 --- a/plugins/gitea/.apm/skills/gitea-workflow/references/number-resolution.md +++ b/plugins/gitea/.apm/skills/gitea-workflow/references/number-resolution.md @@ -14,7 +14,7 @@ The user has referenced a bare number without saying "issue" or "PR" (e.g. "what 2. Check the response's `is_pull` field: - `true` → it's a PR. Invoke `gitea-prs` for full PR detail (status, diff, reviews as appropriate to the request) and present that instead. - `false` or absent → it's an issue. Present the issue detail already retrieved. -3. If the resolution call 404s, don't conclude the number doesn't exist. Gitea hides permission errors as not-found (documented in `gitea-issues`' Gotchas), so report the 404 and suggest verifying the token carries `write:issue` rather than reporting "no such issue or PR." +3. A 404 here isn't proof the number doesn't exist — Gitea hides permission errors as not-found (see `gitea-issues` Gotchas). Report the 404 and suggest checking the token's `write:issue` scope rather than reporting "no such issue or PR." If the user stated an action on the number rather than asking about it, resolution is only step one: hand the action, with the resolved domain, to `gitea-issues` or `gitea-prs` to carry out. Presenting detail is not a substitute for performing the write. diff --git a/plugins/gitea/skills/gitea-branches/SKILL.md b/plugins/gitea/skills/gitea-branches/SKILL.md index 47c113a..820a55e 100644 --- a/plugins/gitea/skills/gitea-branches/SKILL.md +++ b/plugins/gitea/skills/gitea-branches/SKILL.md @@ -23,19 +23,19 @@ allowed-tools: Bash mcp__gitea__list_branches mcp__gitea__create_branch mcp__git ## Gotchas -- **404 often means 403.** Gitea masks permission errors as not-found; on an unexpected one, check token scope before reporting a branch or commit missing. -- **Nothing auto-paginates.** `list_branches` and `list_commits` return one page; iterate `page` until the returned count is below `per_page`. +- **404 can mean 403.** Gitea masks permission errors as not-found — check token scope before reporting a branch or commit missing. +- **Nothing auto-paginates.** `list_branches`/`list_commits` return one page — iterate `page` until the count is below `per_page`. - **`delete_branch` has no force-push guard.** Treat deleting a protected branch as a hard refusal unless the user explicitly confirms it in the conversation. Check `protected` from `list_branches` first — a protected branch need not be named `main`. ## Step 1 — Resolve owner and repo -Before any tool call, extract `owner` and `repo` from the git remote: +Extract `owner` and `repo` from the git remote before any tool call — `get_me` and `list_my_repos` are blocked under this skill's token scope, so the remote is the only source: ```bash rtk git remote get-url origin ``` -`get_me` and `list_my_repos` are blocked under the token scope this skill assumes, so the remote is the only source. If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/skills/gitea-branches/references/branches.md b/plugins/gitea/skills/gitea-branches/references/branches.md index d4643a3..4e66709 100644 --- a/plugins/gitea/skills/gitea-branches/references/branches.md +++ b/plugins/gitea/skills/gitea-branches/references/branches.md @@ -29,8 +29,7 @@ list_branches owner: repo: **Response:** one object per branch: `name`, `protected` (bool), `commit_sha` (present when the underlying commit data is available). -Paginate if you need the full list (see Gotchas in SKILL.md) — iterate `page` until the returned -count is less than `per_page`. +Paginate for the full list (see Gotchas) — iterate `page` until the count is less than `per_page`. ## `create_branch` diff --git a/plugins/gitea/skills/gitea-files/SKILL.md b/plugins/gitea/skills/gitea-files/SKILL.md index 26265da..0923b56 100644 --- a/plugins/gitea/skills/gitea-files/SKILL.md +++ b/plugins/gitea/skills/gitea-files/SKILL.md @@ -11,7 +11,7 @@ compatibility: Requires the Gitea MCP server configured with a token scoped to a is not actually required for any of this domain's five tools. metadata: - version: "1.0.0" + version: "1.0.1" category: gitea source_keys: - gitea-mcp-repo @@ -23,7 +23,7 @@ allowed-tools: mcp__gitea__get_file_contents mcp__gitea__get_dir_contents mcp__g ## Gotchas -- **A 404 may mean an under-scoped token, not a missing path.** Every tool here gates on `write:repository`, and Gitea masks insufficient scope as 404. Check scopes first. +- **404 may mean an under-scoped token, not a missing path.** These tools gate on `write:repository`; check scope before concluding the path is missing. - **Reads take `ref` (`tree_sha` on `get_repository_tree`), writes take `branch_name`.** One concept, three names — carry the wrong key and the branch is dropped. - **`content` is base64 both ways — except under `withLines: true`.** Encode before a write, decode after a read; but with `withLines: true` `content` is already plain JSON text and the reported `"encoding": "base64"` is a lie. Decoding it yields garbage. diff --git a/plugins/gitea/skills/gitea-files/references/reading.md b/plugins/gitea/skills/gitea-files/references/reading.md index db2aa15..f10366a 100644 --- a/plugins/gitea/skills/gitea-files/references/reading.md +++ b/plugins/gitea/skills/gitea-files/references/reading.md @@ -32,8 +32,8 @@ size. No recursion, no content, no `sha`. `get_repository_tree(owner, repo, tree_sha, recursive)`. Set `recursive: true` to walk subdirectories in one call. -The response sets `truncated: true` when one page does not hold every entry. Page through with -`page`/`per_page` (defaults `1` and `30`) until a page returns fewer entries than `per_page`. +The response sets `truncated: true` when one page doesn't hold every entry — page with +`page`/`per_page` (defaults `1`/`30`) until a page returns fewer than `per_page`. ## Neither listing is a SHA source for a write @@ -44,7 +44,6 @@ the canonical path for a write's SHA: one call returns the decoded content and t ## A 404 that is really a 403 -These reads gate on `write:repository`, not on read access alone, and some Gitea endpoints answer -an under-scoped token with 404 instead of 403 so they do not leak whether the resource exists. A -404 on a path you are confident about is a scope problem until proven otherwise — check the token's -configured scopes before concluding the file or directory does not exist. +These reads gate on `write:repository`; an under-scoped token gets 404 instead of 403 so the +endpoint doesn't leak whether the resource exists. On a path you're confident about, check token +scope before concluding it doesn't exist. diff --git a/plugins/gitea/skills/gitea-issues/SKILL.md b/plugins/gitea/skills/gitea-issues/SKILL.md index ab785f8..cc9ce3a 100644 --- a/plugins/gitea/skills/gitea-issues/SKILL.md +++ b/plugins/gitea/skills/gitea-issues/SKILL.md @@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with write:issue and write:r metadata: category: integration - version: "0.1.4" + version: "0.1.5" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go @@ -29,17 +29,17 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i - **`list_issues` mixes in PRs unless you filter.** Issues and PRs share one number space; pass `type: "issues"` to exclude PRs (or `"pulls"`). `is_pull` is returned only by `issue_read method: "get"` — on a list item the only tell is `html_url`'s path segment (`/issues/` vs `/pulls/`). - **Label IDs and names are not interchangeable.** `issue_write` takes numeric IDs only; `list_issues` and `search_issues` filter by name; `issue_read "get"` returns names but `"get_labels"` returns full objects with IDs. Resolve via `gitea-labels-milestones` unless the caller named exact labels. - **A merge does not itself close the issue.** Gitea has no close-on-merge event, but a `Fixes #N` in the merged commits can, depending on merge style (`gitea-prs`). Re-read its state after a merge before closing it manually. -- **A 404 may really be a 403.** Gitea hides permission errors as not-found — check the token's `write:issue` scope before concluding the issue does not exist. +- **404 may mean 403.** Gitea hides permission errors as not-found — check `write:issue` scope before concluding the issue doesn't exist. ## Step 1 — Resolve owner and repo -An orchestrating caller may pass `owner` and `repo` in already, and the `search` row is cross-repository and needs only a query — both skip this step. Otherwise, before any tool call: +Skip if an orchestrating caller already passed `owner`/`repo` in, or the action is `search` (cross-repository, needs only a query). Otherwise, before any tool call: ```bash rtk git remote get-url origin ``` -If origin is unset or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/skills/gitea-issues/references/issues.md b/plugins/gitea/skills/gitea-issues/references/issues.md index fe4248b..6292633 100644 --- a/plugins/gitea/skills/gitea-issues/references/issues.md +++ b/plugins/gitea/skills/gitea-issues/references/issues.md @@ -45,7 +45,7 @@ list_issues owner: repo: state: "open" type: "issues" `updated_at`, and optionally `labels` (`[]string`), `milestone` (`{id, title}`), `ref`, `deadline`. Body and `closed_at` are omitted from list responses — call `issue_read method: "get"` for those. -Paginate with `page`/`per_page` until the returned count is less than `per_page`. +Paginate: `page`/`per_page`, stop once the count is below `per_page`. ## `issue_read` diff --git a/plugins/gitea/skills/gitea-labels-milestones/SKILL.md b/plugins/gitea/skills/gitea-labels-milestones/SKILL.md index 6619a29..aa744ce 100644 --- a/plugins/gitea/skills/gitea-labels-milestones/SKILL.md +++ b/plugins/gitea/skills/gitea-labels-milestones/SKILL.md @@ -16,30 +16,30 @@ metadata: - gitea-mcp-slim-go - context7-websites-gitea - context7-gitea-tea-cli - version: "0.1.5" + version: "0.1.6" allowed-tools: Bash mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write --- ## Gotchas -- **Applying a label takes a numeric ID, but issue/PR responses slim labels down to name strings.** An issue's existing labels yield no IDs — resolve name → ID with `label_read`. -- **`pull_request_read` returns `milestone` as a bare title string** where `issue_read` returns `{id, title}` — recover the milestone's ID by listing milestones and matching the title. -- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's own `exclusive` field.** `list_repo_labels` returns it on every repo label, so it is always *readable* per label; `label_write` documents it as "(org only)" because it is only *settable* through the org create methods. Where it is `true` Gitea enforces one-per-scope itself, and replacing rather than stacking on a label whose `exclusive` is `false` destroys a valid label. +- **Applying a label needs a numeric ID; issue/PR responses give only name strings.** Resolve name → ID with `label_read` first. +- **`pull_request_read` returns `milestone` as a bare title string, `issue_read` as `{id, title}`.** Recover the ID by listing milestones and matching the title. +- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's `exclusive` field.** `list_repo_labels` always returns it; `label_write` can only set it via org create methods ("org only"). `true` means Gitea enforces one-per-scope; replacing instead of stacking on a `false` label destroys a valid one. ## Step 1 — Resolve owner, repo and org -Before any tool call, extract `owner` and `repo` from the git remote (skip this if an orchestrating caller already passed them in): +Extract `owner` and `repo` from the git remote before any tool call (skip if an orchestrating caller already passed them in): ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." -The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it is the org name whenever the owner is an organisation, and the remote URL does not say whether it is one. +The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it's the org name whenever the owner is an organisation, which the remote URL doesn't say. -Read the failure text before interpreting it. `list_org_labels` needs the `read:organization` token scope, which this skill's declared scopes (`write:issue`, `write:repository`) do not carry, so it fails with `token does not have at least one of required scope(s), required=[read:organization]` *before* it ever determines org-vs-user. Report that: the org pool went unchecked, not empty. Only a not-found response is evidence the owner is a user account with no org pool. +Read the failure text before interpreting it: `list_org_labels` needs `read:organization`, which this skill's declared scopes don't carry, so it fails with a scope error *before* it ever checks org-vs-user. Report the unchecked scope, not an empty pool — only a genuine not-found means the owner is a user account with no org pool. ## Step 2 — Dispatch @@ -58,6 +58,6 @@ Read the failure text before interpreting it. `list_org_labels` needs the `read: | Update / close a milestone | `milestone_write` | `"update"` | | Delete a milestone | `milestone_write` | `"delete"` | -Every list method paginates manually — `per_page` defaults to 30, so iterate `page: 1, 2, ...` until a page returns fewer results than `per_page`. A truncated list silently breaks name → ID resolution. +Every list method paginates manually (`per_page` default 30) — iterate `page: 1, 2, ...` until a page returns fewer than `per_page`. A truncated list silently breaks name → ID resolution. If the task is a label operation, read `references/labels.md`; if a milestone operation, read `references/milestones.md`. If the label to apply has to be derived from conversation context rather than named, read `references/label-inference.md`. diff --git a/plugins/gitea/skills/gitea-labels-milestones/references/labels.md b/plugins/gitea/skills/gitea-labels-milestones/references/labels.md index 172cea2..ef44e16 100644 --- a/plugins/gitea/skills/gitea-labels-milestones/references/labels.md +++ b/plugins/gitea/skills/gitea-labels-milestones/references/labels.md @@ -51,8 +51,8 @@ runtime error from Gitea rather than a client-side validation error. label_read method: "list_repo_labels" owner: repo: per_page: 50 ``` -Paginate (`page: 1, 2, ...`) until the returned count is less than `per_page`. This is the only way -to build a complete name → ID map — there is no lookup-by-name endpoint. +Paginate (`page: 1, 2, ...`) until the count is below `per_page` — the only way to build a complete +name → ID map, since there's no lookup-by-name endpoint. Every returned repo label carries its own `exclusive` boolean, so exclusivity is always *readable* per repo label. That does not contradict `label_write`'s schema, which annotates `exclusive` as diff --git a/plugins/gitea/skills/gitea-prs/SKILL.md b/plugins/gitea/skills/gitea-prs/SKILL.md index 37ab15d..5b0ea59 100644 --- a/plugins/gitea/skills/gitea-prs/SKILL.md +++ b/plugins/gitea/skills/gitea-prs/SKILL.md @@ -19,7 +19,7 @@ metadata: - gitea-mcp-slim-go - context7-websites-gitea - context7-gitea-tea-cli - version: "0.1.3" + version: "0.1.4" allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp__gitea__pull_request_write mcp__gitea__pull_request_review_write --- @@ -31,13 +31,13 @@ allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read ## Step 1 — Resolve owner and repo -Extract them from the git remote before any tool call, skipping this when an orchestrating caller already passed them in: +Extract from the git remote before any tool call, skipping this when an orchestrating caller already passed them in: ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/skills/gitea-releases/SKILL.md b/plugins/gitea/skills/gitea-releases/SKILL.md index f55cd7d..6e7ccc6 100644 --- a/plugins/gitea/skills/gitea-releases/SKILL.md +++ b/plugins/gitea/skills/gitea-releases/SKILL.md @@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with a token with write:repo metadata: category: integration - version: "0.1.1" + version: "0.1.2" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go @@ -33,13 +33,13 @@ allowed-tools: Bash mcp__gitea__list_releases mcp__gitea__get_release mcp__gitea ## Step 1 — Resolve owner and repo -`owner` and `repo` are required on every tool below. Extract them from the git remote, unless an orchestrating caller passed them in already: +`owner` and `repo` are required on every tool below. Extract from the git remote, unless an orchestrating caller already passed them in: ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch @@ -68,6 +68,6 @@ These four are mutually exclusive — pick the one row the request lands on. | Create a release | Call `create_release` with `tag_name`, `target`, `title`, and `is_draft`/`is_pre_release` set explicitly — never left to default. This surface carries no update or edit tool, so a wrong flag is repairable only by delete-and-recreate (`references/conventions.md`). A separate `create_tag` is only needed to tag a commit without wrapping it in a release — whether `create_release` creates a missing tag is unconfirmed, so verify with `get_tag`. | | Delete a release | Resolve the numeric `id` per the first Gotcha, confirm intent, then call `delete_release`. The tag survives. | | Delete a tag along with its release | Delete the release first, then call `delete_tag` — confirm both are intended before proceeding, since each is irreversible on its own. | -| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries. Nothing here auto-paginates. | +| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries — nothing auto-paginates. | If exact input params or response field shapes are needed, read `references/call-signatures.md`. If the caller raises semver tag naming, draft/prerelease semantics, release-notes sourcing, or how a release relates to its tag, read `references/conventions.md`. diff --git a/plugins/gitea/skills/gitea-releases/references/call-signatures.md b/plugins/gitea/skills/gitea-releases/references/call-signatures.md index b81a6f9..46ca117 100644 --- a/plugins/gitea/skills/gitea-releases/references/call-signatures.md +++ b/plugins/gitea/skills/gitea-releases/references/call-signatures.md @@ -70,7 +70,6 @@ id, tag_name, target, title, body, draft, prerelease, html_url, author, created_ ## Pagination -None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then -`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and -`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list -tools, so a caller assuming 30 will under-count pages needed for a fixed total. +Nothing auto-paginates. Loop `page: 1, 2, ...` until a page returns fewer items than `per_page`. +`list_releases`/`list_tags` default `per_page` to 20, not the usual 30 — assuming 30 under-counts +pages needed. diff --git a/plugins/gitea/skills/gitea-workflow/SKILL.md b/plugins/gitea/skills/gitea-workflow/SKILL.md index b0d64f6..1528c14 100644 --- a/plugins/gitea/skills/gitea-workflow/SKILL.md +++ b/plugins/gitea/skills/gitea-workflow/SKILL.md @@ -13,7 +13,7 @@ compatibility: Requires Gitea MCP server configured with a token; delegates all metadata: category: integration - version: "0.1.3" + version: "0.1.4" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go diff --git a/plugins/gitea/skills/gitea-workflow/references/number-resolution.md b/plugins/gitea/skills/gitea-workflow/references/number-resolution.md index 357514b..ea8c8e6 100644 --- a/plugins/gitea/skills/gitea-workflow/references/number-resolution.md +++ b/plugins/gitea/skills/gitea-workflow/references/number-resolution.md @@ -14,7 +14,7 @@ The user has referenced a bare number without saying "issue" or "PR" (e.g. "what 2. Check the response's `is_pull` field: - `true` → it's a PR. Invoke `gitea-prs` for full PR detail (status, diff, reviews as appropriate to the request) and present that instead. - `false` or absent → it's an issue. Present the issue detail already retrieved. -3. If the resolution call 404s, don't conclude the number doesn't exist. Gitea hides permission errors as not-found (documented in `gitea-issues`' Gotchas), so report the 404 and suggest verifying the token carries `write:issue` rather than reporting "no such issue or PR." +3. A 404 here isn't proof the number doesn't exist — Gitea hides permission errors as not-found (see `gitea-issues` Gotchas). Report the 404 and suggest checking the token's `write:issue` scope rather than reporting "no such issue or PR." If the user stated an action on the number rather than asking about it, resolution is only step one: hand the action, with the resolved domain, to `gitea-issues` or `gitea-prs` to carry out. Presenting detail is not a substitute for performing the write.