Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: trim skill READMEs and ADR/changelog narration

Browse Source 
Two related simplification-audit findings, bundled because they edit
some of the same skill-audit files and splitting would fragment
single-file diffs.

Finding 10: delete 48 per-skill/reference README.md files (they
restated SKILL.md in narrative form and no agent ever loads them) plus
2 scaffold templates. Drop the README criterion from skill-audit's
file-structure.md and finding-criteria.md, and the README-generation
step from skill-author's new-skill.sh; update new-skill.bats to match.
Plugin-root READMEs are kept intentionally, out of scope.

Finding 12: strip historical ADR-0020/ADR-0023 citations and
changelog-style narration from model-facing skill content across
kyberforge and git plugin skills. Delete skill-author's one-time
retrofit.md migration guide and its references. Some ADR-0023 tags
were not narration but check-rtk-prefix's required opt-out marker for
intentionally-bare git commands -- those were restored, not stripped.

Mirror re-synced and full pre-commit/pre-push suite verified green.

Refs: SIMPLIFICATION-AUDIT.md findings 10, 12

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
Defame1297
2026-09-12 18:38:09 +00:00
parent 9eb8bc7e48
commit edcc57c0d6
167 changed files with 132 additions and 3897 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
plugins/bin/.apm/skills/caveman/README.md
View File

@@ -1,29 +0,0 @@
# caveman
Ultra-compressed output mode: drop articles, filler and pleasantries, keep the technical substance exact.
## What it does
Switches the agent into a terse register — no articles, no hedging, no pleasantries, fragments allowed, arrows for causality — while leaving technical terms, code blocks and quoted error strings untouched. The mode is *sticky*: once turned on it stays on for every subsequent response until the user says "stop caveman" or "normal mode", rather than decaying back to normal prose after a few turns.
It carries one built-in escape hatch. Security warnings, confirmations for irreversible actions, multi-step sequences where fragment order could be misread, and any request to clarify are answered in normal prose, then the compressed register resumes.
## Hand-invoked only
`SKILL.md` sets `disable-model-invocation: true`. This is the single most important thing to know about this skill: **the model cannot route to it.** No other skill can hand off to it, and no phrasing in a user's request will cause it to be selected automatically. The only way in is the human typing `/caveman`.
That is deliberate — output style is the user's choice, not an inference the router should make on their behalf. It is also why the description reads as one plain human-facing sentence rather than carrying the trigger phrasing and boundary clause a routable skill needs.
## Usage
```text
/caveman
```
Then keep working normally. To leave the mode, say "stop caveman" or "normal mode".
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The whole skill — persistence rule, compression rules, worked examples, and the auto-clarity exception |

35
plugins/bin/.apm/skills/diagnose/README.md
View File

@@ -1,35 +0,0 @@
# diagnose
A six-phase discipline for hard bugs and performance regressions: feedback loop → reproduce → hypothesise → instrument → fix with a regression test → clean up.
## What it does
Imposes an order of operations on debugging so the agent cannot skip to guessing. The load-bearing phase is the first one: build a fast, deterministic, agent-runnable pass/fail signal for the bug. Everything downstream — bisection, hypothesis testing, instrumentation — just consumes that signal, so the skill refuses to advance to Phase 2 without one, and says so explicitly rather than hypothesising blind.
The remaining phases each carry a constraint worth knowing about: hypotheses are generated 3–5 at a time and must be falsifiable, so the first plausible idea cannot anchor the whole investigation; every debug log is tagged with a unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep; the regression test is written before the fix and only at a seam that exercises the real bug pattern; and the run closes by asking what would have prevented the bug, handing off to `improve-codebase-architecture` when the answer is architectural.
Performance regressions take a branch of their own inside Phase 4 — baseline measurement and bisection, not logs.
## Conditional reading
Neither reference file is read on every run; `SKILL.md` names the condition for each.
- `references/feedback-loops.md` is read when Phase 1 has no signal yet, or when the loop you have is slow or intermittent.
- `references/regression-seams.md` is read when Phase 5 leaves you unsure whether the available seam is deep enough — or whether one exists at all.
## Usage
```text
/diagnose
```
Describe the bug or the regression. For filing and triaging a reported bug rather than diagnosing it, use `triage`; for test-first feature work, use `tdd`.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The six phases and their gates — what must be true before each one ends |
| `references/feedback-loops.md` | Loaded when Phase 1 has no loop or the loop is too weak: ten ways to construct one ordered by cost, how to sharpen an existing loop, handling intermittent bugs, and what to ask the user for when the bug resists reproduction |
| `references/regression-seams.md` | Loaded when Phase 5 is unsure about the seam: what makes a seam correct, the four shapes of a too-shallow seam, and what to do when no correct seam exists |
| `assets/hitl-loop.template.sh` | Copy-and-edit bash template for the last-resort human-in-the-loop feedback loop, cited by `references/feedback-loops.md`. Provides `step` and `capture` helpers and prints captured values as `KEY=VALUE` for the agent to parse |

27
plugins/bin/.apm/skills/grill-me/README.md
View File

@@ -1,27 +0,0 @@
# grill-me
Interview the user relentlessly about a plan or design until the decision tree is fully resolved.
## What it does
Turns the agent into an interviewer rather than an implementer. It walks the design tree branch by branch, resolving dependencies between decisions one at a time, and offers its own recommended answer alongside each question so the user has something concrete to push against. Two rules give it its shape: **one question at a time**, and **never ask what the codebase can answer** — if a question is settleable by reading the code, the agent goes and reads the code instead of spending the user's attention on it.
## Composition
This is the plain grilling loop, with no documentation side effects. The sibling `grill-with-docs` skill runs the same interview but additionally challenges answers against the project's `CONTEXT.md` glossary and existing ADRs, and writes decisions back into those files as they crystallise. Reach for that one when the project has a domain model worth defending; reach for this one when it does not, or when nothing should be written down yet.
`triage` composes the documented variant, not this one, when an issue needs fleshing out.
## Usage
```text
/grill-me
```
Describe the plan or design to be stress-tested. Expect questions one at a time, each with a recommended answer.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The whole skill — the interview instruction, the one-question-at-a-time rule, and the explore-instead-of-asking rule |

37
plugins/bin/.apm/skills/grill-with-docs/README.md
View File

@@ -1,37 +0,0 @@
# grill-with-docs
The grilling interview, run against the project's domain model — and writing decisions back into `CONTEXT.md` and ADRs as they land.
## What it does
Runs the same relentless one-question-at-a-time interview as `grill-me`, with the project's own documentation as an active participant. During codebase exploration it also locates the domain documentation — a root `CONTEXT.md` and `docs/adr/`, or a `CONTEXT-MAP.md` pointing at per-context glossaries and ADR directories in a multi-context repo — and then uses it five ways:
- **Challenges terms against the glossary.** When the user's usage conflicts with what `CONTEXT.md` already defines, that is raised immediately rather than absorbed.
- **Sharpens fuzzy language** by proposing a precise canonical term ("you're saying 'account' — do you mean the Customer or the User?").
- **Stress-tests domain relationships with concrete scenarios**, inventing edge cases that force the user to be precise about where one concept ends and the next begins.
- **Cross-references claims against the code**, and surfaces contradictions between what the user says happens and what the code does.
- **Updates `CONTEXT.md` inline**, the moment a term is resolved, rather than batching changes to the end of the session where they get lost.
Files are created lazily — only when there is something real to write.
ADRs are offered *sparingly*, and only when all three tests pass: the decision is hard to reverse, it would surprise a future reader without the context, and it was a genuine trade-off with real alternatives. Missing any one of the three means no ADR.
## Composition
`grill-me` is the same interview without the documentation side effects — use it when there is no domain model to defend or nothing should be written down yet. `triage` composes this skill (not `grill-me`) at step 4 when an issue needs fleshing out. `improve-codebase-architecture` runs its own grilling loop and borrows this skill's `CONTEXT.md` and ADR discipline for the decisions that come out of it.
## Usage
```text
/grill-with-docs
```
Describe the plan or design. Expect questions one at a time, each with a recommended answer, and expect `CONTEXT.md` to be edited during the session rather than after it.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the five during-session behaviours, and the three-part ADR test |
| `references/context-format.md` | Cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry |
| `references/adr-format.md` | Cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template |

36
plugins/bin/.apm/skills/improve-codebase-architecture/README.md
View File

@@ -1,36 +0,0 @@
# improve-codebase-architecture
Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones.
## What it does
Looks for places where a codebase is hard to understand, hard to test, or hard for an agent to navigate, and proposes refactors that concentrate behaviour behind smaller interfaces. It runs in three stages:
1. **Explore.** Reads the domain glossary and any ADRs in the area first, then walks the codebase with an `Explore` sub-agent — organically, noting friction rather than applying fixed heuristics. The **deletion test** is the filter: imagine deleting the module; if complexity vanishes it was a pass-through, if complexity reappears across N callers it was earning its keep.
2. **Present candidates.** A numbered list, each with files, problem, solution and benefits — benefits stated in terms of *locality* and *leverage* and of how tests would improve. No interfaces are proposed yet; the user picks one.
3. **Grilling loop.** Walks the design tree for the chosen candidate, with documentation side effects landing inline as decisions crystallise.
The skill is opinionated about vocabulary, and that is the point: **module, interface, implementation, depth, seam, adapter, leverage, locality**, used exactly, with no drift into "component", "service", "API" or "boundary". Domain nouns come from `CONTEXT.md`, architecture nouns from `references/language.md` — so a proposal reads as "the Order intake module", never "the FooBarHandler".
ADRs are treated as decisions not to be re-litigated. A candidate that contradicts one is surfaced only when the friction is real enough to warrant reopening it, and is marked as such.
## Composition
`diagnose` hands off here when a bug's post-mortem concludes that no correct test seam exists, or that callers are tangled — the recommendation is made after the fix is in, not before. The grilling loop follows `grill-with-docs`'s discipline for `CONTEXT.md` entries and ADR offers, and `SKILL.md` names that skill's format documents directly.
## Usage
```text
/improve-codebase-architecture
```
Point at a codebase or an area of one. Expect a numbered candidate list and a "which of these would you like to explore?" before any interface design happens.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Condensed glossary, key principles, and the three-stage process |
| `references/language.md` | Cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list |
| `references/interface-design.md` | Read at stage 3 when the user wants alternative interfaces explored: the parallel sub-agent "Design It Twice" pattern, framing the problem space, and the per-agent design constraints |
| `references/deepening.md` | Cited from `references/interface-design.md`: how to deepen a cluster of shallow modules safely, the four dependency categories (in-process, local-substitutable, remote-but-owned, true external), seam discipline, and the replace-don't-layer testing strategy |

32
plugins/bin/.apm/skills/prototype/README.md
View File

@@ -1,32 +0,0 @@
# prototype
Build a throwaway prototype that answers one design question — either a runnable terminal app or several UI variations.
## What it does
Treats a prototype as **throwaway code that answers a question**, and lets the question decide the artifact. `SKILL.md` opens with a two-row dispatch table and the run resolves exactly one row before doing anything else:
- *"Does this logic / state model feel right?"* → a tiny interactive terminal app that pushes the state machine through the cases that are hard to reason about on paper.
- *"What should this look like?"* → several radically different UI variations on one route, switchable from a floating bottom bar via a URL search param.
The two branches produce fundamentally different artifacts, so picking wrong wastes the whole prototype. When the question is genuinely ambiguous and the user is unreachable, the skill defaults on the shape of the surrounding code (backend module → logic, page or component → UI) and states the assumption at the top of the prototype rather than silently choosing.
Six rules apply to both branches: throwaway and visibly named as such, one command to run, no persistence by default, no polish, surface the full state after every action or variant switch, and delete or absorb the prototype when it is done. The *answer* is the only durable output — the skill captures it in a commit message, ADR, issue or `NOTES.md` before the code is deleted.
## Usage
```text
/prototype
```
State the design question. For production code, use `tdd`; for talking a design through without building anything, use `grill-me`.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The branch dispatch table and the rules that apply to both branches |
| `references/logic.md` | The logic branch, read only when that row is selected: when it is the right shape, and how to build the interactive terminal app |
| `references/ui.md` | The UI branch, read only when that row is selected: when it is the right shape, and how to build and switch between the variations |
Each reference is self-contained — a run reads one of the two, never both.

31
plugins/bin/.apm/skills/research/README.md
View File

@@ -1,31 +0,0 @@
# research
Research a tool, library or API from canonical documentation into a directory of structured per-topic reference files.
## What it does
Runs a six-step pipeline: scope against the working directory (what version is actually in use, what is already documented), resolve the topic through Context7, websearch for canonical docs covering whatever Context7 missed, read those sources, deepen one level into the links worth following, then write one markdown file per topic area plus a `sources.md` provenance record.
Four gotchas at the top of `SKILL.md` shape the whole run, and each exists because of a specific failure: the output path is never inferred (a guessed destination scatters a directory's worth of files through someone's source tree); nothing is written outside that path; no empty topic file is ever written (a stub `troubleshooting.md` reads downstream as researched and closed); and a Context7 "no results", redirect or header-only response does not count as coverage. If no topic area has content, the run writes nothing at all — `sources.md` included — and reports what it searched.
The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably it grants no subagent tool, so every `WebFetch` is serial and each fetched page lands in the run's own context — which is why steps 4 and 5 insist on reducing each page to notes before fetching the next, and cap deepening at roughly ten extra pages.
## Composition
Both reference files are read on condition, never on every run — `SKILL.md` inlines the minimum each step needs (the seven default topic areas at step 1, the four `sources.md` field names and the topic-file frontmatter keys at step 6) and sends the run to the reference only for what it does not carry. Those four field names are matched literally by the downstream provenance validator, so prose written in their place parses as nothing and the check passes having verified nothing — which is why they are inlined rather than deferred.
## Usage
```text
/research
```
Name the topic and the output path — the skill will stop and ask if the path is missing. Supplying starting URLs is treated as a deliberate source choice and skips Context7 resolution and discovery. For documentation derived from existing code or specs, use `write-docs`; for a bug or incident, use `diagnose`.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The four gotchas and the six research steps |
| `references/topics.md` | Read at Step 1 only when what belongs in a default topic is unclear or a custom topic is needed: the per-topic coverage table and the custom-topic naming rule |
| `references/file-format.md` | Read at Step 6 only when the inlined field names do not settle the case: slug derivation, the Context7 slug and URL convention, and what belongs in a topic body |

32
plugins/bin/.apm/skills/tdd/README.md
View File

@@ -1,32 +0,0 @@
# tdd
Test-driven development as a strict red-green-refactor loop, one behaviour at a time.
## What it does
Two convictions drive this skill. The first is about what a test is for: tests verify behaviour through public interfaces, not implementation details. A good test reads like a specification ("user can checkout with valid cart") and survives refactors because it does not care about internal structure. The warning sign for a bad one is precise — the test breaks when you refactor but behaviour has not changed.
The second is an explicit anti-pattern: **do not write all the tests first, then all the implementation.** Horizontal slicing treats RED as "write every test" and GREEN as "write every implementation", and it produces tests of *imagined* behaviour — tests of the shape of things, insensitive to real change, committed to before the implementation was understood. The correct shape is vertical: one test → one implementation → repeat, each cycle informed by what the last one taught you.
The workflow is four stages: plan (confirm the interface and which behaviours matter, with the user — you cannot test everything), fire a tracer bullet (one test proving the path works end to end), loop incrementally one behaviour at a time, then refactor once everything is green. Refactoring while RED is forbidden.
Codebase exploration uses the project's domain glossary, so test names and interface vocabulary match the project's language, and ADRs in the area are respected.
## Usage
```text
/tdd
```
Describe the feature or bug. Expect the skill to ask what the public interface should look like and which behaviours matter most before any code is written. For diagnosing an existing bug rather than building test-first, use `diagnose`; for throwaway exploratory code, use `prototype`.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Philosophy, the horizontal-slicing anti-pattern, the four-stage workflow, and the per-cycle checklist |
| `references/tests.md` | Cited from Philosophy: worked good and bad test examples |
| `references/mocking.md` | Cited from Philosophy: mock at system boundaries only, and what not to mock |
| `references/deep-modules.md` | Cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for |
| `references/interface-design.md` | Cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them |
| `references/refactoring.md` | Cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession |

35
plugins/bin/.apm/skills/triage/README.md
View File

@@ -1,35 +0,0 @@
# triage
Move issues on the project issue tracker through a small state machine of triage roles.
## What it does
Gives issue triage an explicit state model and a fixed set of moves. Every issue carries exactly one **category** role (`bug`, `enhancement`) and one **state** role (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`); conflicting state roles are flagged to the maintainer before anything else happens. Unlabeled issues normally enter at `needs-triage`; `needs-info` returns there once the reporter replies. The maintainer can override at any point, and unusual transitions are questioned rather than executed silently.
A run does one of three things depending on what the maintainer asks for:
- **Show what needs attention** — three buckets, oldest first: unlabeled, `needs-triage`, and `needs-info` with reporter activity since the last triage notes.
- **Triage a specific issue** — gather context (including prior triage notes, so resolved questions are not re-asked, and `.out-of-scope/` records that resemble the issue), recommend a category and state with reasoning, attempt reproduction for bugs *before* any grilling, run a `grill-with-docs` session if the issue needs fleshing out, then apply the outcome.
- **Quick state override** — "move #42 to ready-for-agent" is trusted and applied directly, skipping grilling, after confirming the exact changes.
Two hard rules: every comment or issue the skill posts during triage must open with the AI-generated disclaimer, and the canonical role names above are *not* necessarily the label strings in the tracker — each is resolved against the tracker's live label set before it is applied, and a name with no counterpart there is reported to the maintainer as a gap rather than guessed at.
## Composition
`grill-with-docs` is invoked at step 4 when an issue needs fleshing out; whatever that session establishes is carried into the triage notes so the work is not lost. The reverse direction also exists: `diagnose` names this skill as the place to send a *reported* bug that needs filing rather than debugging.
## Usage
```text
/triage
```
Then describe what you want in natural language — "show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent", "what's ready for agents to pick up?".
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The roles and state machine, the three invocation modes, the needs-info template, and how to resume a prior session |
| `references/agent-brief.md` | Cited when an issue moves to `ready-for-agent` (and reused for `ready-for-human`): how to write a brief that stays durable for weeks while the codebase moves under it — describe interfaces and behavioural contracts, not line numbers |
| `references/out-of-scope.md` | Cited when an enhancement is closed `wontfix` and when checking for prior rejections: how the `.out-of-scope/` knowledge base is laid out and what it is for — institutional memory, and deduplication against re-litigated requests |

30
plugins/bin/.apm/skills/write-docs/README.md
View File

@@ -1,30 +0,0 @@
# write-docs
Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section.
## What it does
Casts the agent as a technical writer with one non-negotiable constraint: **every claim must be traceable to a source file line, a spec section, or an explicit user statement.** Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away.
The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human:
- Files are read only after the user approves them by name. The skill may propose candidates; it waits.
- The **gap check** presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects.
- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical.
- **Reader testing** predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting.
Summary and overview sections are written last, once the detail sections are stable.
## Usage
```text
/write-docs
```
Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use `grill-me` or `grill-with-docs` instead — those have dedicated handling.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check |

25
plugins/bin/.apm/skills/zoom-out/README.md
View File

@@ -1,25 +0,0 @@
# zoom-out
Ask the agent to go up a layer of abstraction and map the modules and callers around unfamiliar code.
## What it does
A single-purpose prompt for the moment you land in a part of the codebase you do not know. Instead of answering at the level of the file in front of it, the agent climbs one layer and produces a map of the relevant modules and their callers — and names them using the project's own domain glossary vocabulary, so the map lines up with the language the rest of the repo already uses.
## Hand-invoked only
`SKILL.md` sets `disable-model-invocation: true`, so the router never selects this skill on its own and no other skill can hand off to it. It runs when the human asks for it. That also means its description is written as one plain human-facing sentence — it carries no trigger phrasing or boundary clause, because nothing routes on it.
## Usage
```text
/zoom-out
```
Best used with the unfamiliar code already in context — the skill widens the view around what you are looking at rather than picking a starting point for you.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The whole skill — a single instruction, no supporting files |

29
plugins/bin/skills/caveman/README.md
View File

@@ -1,29 +0,0 @@
# caveman
Ultra-compressed output mode: drop articles, filler and pleasantries, keep the technical substance exact.
## What it does
Switches the agent into a terse register — no articles, no hedging, no pleasantries, fragments allowed, arrows for causality — while leaving technical terms, code blocks and quoted error strings untouched. The mode is *sticky*: once turned on it stays on for every subsequent response until the user says "stop caveman" or "normal mode", rather than decaying back to normal prose after a few turns.
It carries one built-in escape hatch. Security warnings, confirmations for irreversible actions, multi-step sequences where fragment order could be misread, and any request to clarify are answered in normal prose, then the compressed register resumes.
## Hand-invoked only
`SKILL.md` sets `disable-model-invocation: true`. This is the single most important thing to know about this skill: **the model cannot route to it.** No other skill can hand off to it, and no phrasing in a user's request will cause it to be selected automatically. The only way in is the human typing `/caveman`.
That is deliberate — output style is the user's choice, not an inference the router should make on their behalf. It is also why the description reads as one plain human-facing sentence rather than carrying the trigger phrasing and boundary clause a routable skill needs.
## Usage
```text
/caveman
```
Then keep working normally. To leave the mode, say "stop caveman" or "normal mode".
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The whole skill — persistence rule, compression rules, worked examples, and the auto-clarity exception |

35
plugins/bin/skills/diagnose/README.md
View File

@@ -1,35 +0,0 @@
# diagnose
A six-phase discipline for hard bugs and performance regressions: feedback loop → reproduce → hypothesise → instrument → fix with a regression test → clean up.
## What it does
Imposes an order of operations on debugging so the agent cannot skip to guessing. The load-bearing phase is the first one: build a fast, deterministic, agent-runnable pass/fail signal for the bug. Everything downstream — bisection, hypothesis testing, instrumentation — just consumes that signal, so the skill refuses to advance to Phase 2 without one, and says so explicitly rather than hypothesising blind.
The remaining phases each carry a constraint worth knowing about: hypotheses are generated 3–5 at a time and must be falsifiable, so the first plausible idea cannot anchor the whole investigation; every debug log is tagged with a unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep; the regression test is written before the fix and only at a seam that exercises the real bug pattern; and the run closes by asking what would have prevented the bug, handing off to `improve-codebase-architecture` when the answer is architectural.
Performance regressions take a branch of their own inside Phase 4 — baseline measurement and bisection, not logs.
## Conditional reading
Neither reference file is read on every run; `SKILL.md` names the condition for each.
- `references/feedback-loops.md` is read when Phase 1 has no signal yet, or when the loop you have is slow or intermittent.
- `references/regression-seams.md` is read when Phase 5 leaves you unsure whether the available seam is deep enough — or whether one exists at all.
## Usage
```text
/diagnose
```
Describe the bug or the regression. For filing and triaging a reported bug rather than diagnosing it, use `triage`; for test-first feature work, use `tdd`.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The six phases and their gates — what must be true before each one ends |
| `references/feedback-loops.md` | Loaded when Phase 1 has no loop or the loop is too weak: ten ways to construct one ordered by cost, how to sharpen an existing loop, handling intermittent bugs, and what to ask the user for when the bug resists reproduction |
| `references/regression-seams.md` | Loaded when Phase 5 is unsure about the seam: what makes a seam correct, the four shapes of a too-shallow seam, and what to do when no correct seam exists |
| `assets/hitl-loop.template.sh` | Copy-and-edit bash template for the last-resort human-in-the-loop feedback loop, cited by `references/feedback-loops.md`. Provides `step` and `capture` helpers and prints captured values as `KEY=VALUE` for the agent to parse |

27
plugins/bin/skills/grill-me/README.md
View File

@@ -1,27 +0,0 @@
# grill-me
Interview the user relentlessly about a plan or design until the decision tree is fully resolved.
## What it does
Turns the agent into an interviewer rather than an implementer. It walks the design tree branch by branch, resolving dependencies between decisions one at a time, and offers its own recommended answer alongside each question so the user has something concrete to push against. Two rules give it its shape: **one question at a time**, and **never ask what the codebase can answer** — if a question is settleable by reading the code, the agent goes and reads the code instead of spending the user's attention on it.
## Composition
This is the plain grilling loop, with no documentation side effects. The sibling `grill-with-docs` skill runs the same interview but additionally challenges answers against the project's `CONTEXT.md` glossary and existing ADRs, and writes decisions back into those files as they crystallise. Reach for that one when the project has a domain model worth defending; reach for this one when it does not, or when nothing should be written down yet.
`triage` composes the documented variant, not this one, when an issue needs fleshing out.
## Usage
```text
/grill-me
```
Describe the plan or design to be stress-tested. Expect questions one at a time, each with a recommended answer.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The whole skill — the interview instruction, the one-question-at-a-time rule, and the explore-instead-of-asking rule |

37
plugins/bin/skills/grill-with-docs/README.md
View File

@@ -1,37 +0,0 @@
# grill-with-docs
The grilling interview, run against the project's domain model — and writing decisions back into `CONTEXT.md` and ADRs as they land.
## What it does
Runs the same relentless one-question-at-a-time interview as `grill-me`, with the project's own documentation as an active participant. During codebase exploration it also locates the domain documentation — a root `CONTEXT.md` and `docs/adr/`, or a `CONTEXT-MAP.md` pointing at per-context glossaries and ADR directories in a multi-context repo — and then uses it five ways:
- **Challenges terms against the glossary.** When the user's usage conflicts with what `CONTEXT.md` already defines, that is raised immediately rather than absorbed.
- **Sharpens fuzzy language** by proposing a precise canonical term ("you're saying 'account' — do you mean the Customer or the User?").
- **Stress-tests domain relationships with concrete scenarios**, inventing edge cases that force the user to be precise about where one concept ends and the next begins.
- **Cross-references claims against the code**, and surfaces contradictions between what the user says happens and what the code does.
- **Updates `CONTEXT.md` inline**, the moment a term is resolved, rather than batching changes to the end of the session where they get lost.
Files are created lazily — only when there is something real to write.
ADRs are offered *sparingly*, and only when all three tests pass: the decision is hard to reverse, it would surprise a future reader without the context, and it was a genuine trade-off with real alternatives. Missing any one of the three means no ADR.
## Composition
`grill-me` is the same interview without the documentation side effects — use it when there is no domain model to defend or nothing should be written down yet. `triage` composes this skill (not `grill-me`) at step 4 when an issue needs fleshing out. `improve-codebase-architecture` runs its own grilling loop and borrows this skill's `CONTEXT.md` and ADR discipline for the decisions that come out of it.
## Usage
```text
/grill-with-docs
```
Describe the plan or design. Expect questions one at a time, each with a recommended answer, and expect `CONTEXT.md` to be edited during the session rather than after it.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the five during-session behaviours, and the three-part ADR test |
| `references/context-format.md` | Cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry |
| `references/adr-format.md` | Cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template |

36
plugins/bin/skills/improve-codebase-architecture/README.md
View File

@@ -1,36 +0,0 @@
# improve-codebase-architecture
Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones.
## What it does
Looks for places where a codebase is hard to understand, hard to test, or hard for an agent to navigate, and proposes refactors that concentrate behaviour behind smaller interfaces. It runs in three stages:
1. **Explore.** Reads the domain glossary and any ADRs in the area first, then walks the codebase with an `Explore` sub-agent — organically, noting friction rather than applying fixed heuristics. The **deletion test** is the filter: imagine deleting the module; if complexity vanishes it was a pass-through, if complexity reappears across N callers it was earning its keep.
2. **Present candidates.** A numbered list, each with files, problem, solution and benefits — benefits stated in terms of *locality* and *leverage* and of how tests would improve. No interfaces are proposed yet; the user picks one.
3. **Grilling loop.** Walks the design tree for the chosen candidate, with documentation side effects landing inline as decisions crystallise.
The skill is opinionated about vocabulary, and that is the point: **module, interface, implementation, depth, seam, adapter, leverage, locality**, used exactly, with no drift into "component", "service", "API" or "boundary". Domain nouns come from `CONTEXT.md`, architecture nouns from `references/language.md` — so a proposal reads as "the Order intake module", never "the FooBarHandler".
ADRs are treated as decisions not to be re-litigated. A candidate that contradicts one is surfaced only when the friction is real enough to warrant reopening it, and is marked as such.
## Composition
`diagnose` hands off here when a bug's post-mortem concludes that no correct test seam exists, or that callers are tangled — the recommendation is made after the fix is in, not before. The grilling loop follows `grill-with-docs`'s discipline for `CONTEXT.md` entries and ADR offers, and `SKILL.md` names that skill's format documents directly.
## Usage
```text
/improve-codebase-architecture
```
Point at a codebase or an area of one. Expect a numbered candidate list and a "which of these would you like to explore?" before any interface design happens.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Condensed glossary, key principles, and the three-stage process |
| `references/language.md` | Cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list |
| `references/interface-design.md` | Read at stage 3 when the user wants alternative interfaces explored: the parallel sub-agent "Design It Twice" pattern, framing the problem space, and the per-agent design constraints |
| `references/deepening.md` | Cited from `references/interface-design.md`: how to deepen a cluster of shallow modules safely, the four dependency categories (in-process, local-substitutable, remote-but-owned, true external), seam discipline, and the replace-don't-layer testing strategy |

32
plugins/bin/skills/prototype/README.md
View File

@@ -1,32 +0,0 @@
# prototype
Build a throwaway prototype that answers one design question — either a runnable terminal app or several UI variations.
## What it does
Treats a prototype as **throwaway code that answers a question**, and lets the question decide the artifact. `SKILL.md` opens with a two-row dispatch table and the run resolves exactly one row before doing anything else:
- *"Does this logic / state model feel right?"* → a tiny interactive terminal app that pushes the state machine through the cases that are hard to reason about on paper.
- *"What should this look like?"* → several radically different UI variations on one route, switchable from a floating bottom bar via a URL search param.
The two branches produce fundamentally different artifacts, so picking wrong wastes the whole prototype. When the question is genuinely ambiguous and the user is unreachable, the skill defaults on the shape of the surrounding code (backend module → logic, page or component → UI) and states the assumption at the top of the prototype rather than silently choosing.
Six rules apply to both branches: throwaway and visibly named as such, one command to run, no persistence by default, no polish, surface the full state after every action or variant switch, and delete or absorb the prototype when it is done. The *answer* is the only durable output — the skill captures it in a commit message, ADR, issue or `NOTES.md` before the code is deleted.
## Usage
```text
/prototype
```
State the design question. For production code, use `tdd`; for talking a design through without building anything, use `grill-me`.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The branch dispatch table and the rules that apply to both branches |
| `references/logic.md` | The logic branch, read only when that row is selected: when it is the right shape, and how to build the interactive terminal app |
| `references/ui.md` | The UI branch, read only when that row is selected: when it is the right shape, and how to build and switch between the variations |
Each reference is self-contained — a run reads one of the two, never both.

31
plugins/bin/skills/research/README.md
View File

@@ -1,31 +0,0 @@
# research
Research a tool, library or API from canonical documentation into a directory of structured per-topic reference files.
## What it does
Runs a six-step pipeline: scope against the working directory (what version is actually in use, what is already documented), resolve the topic through Context7, websearch for canonical docs covering whatever Context7 missed, read those sources, deepen one level into the links worth following, then write one markdown file per topic area plus a `sources.md` provenance record.
Four gotchas at the top of `SKILL.md` shape the whole run, and each exists because of a specific failure: the output path is never inferred (a guessed destination scatters a directory's worth of files through someone's source tree); nothing is written outside that path; no empty topic file is ever written (a stub `troubleshooting.md` reads downstream as researched and closed); and a Context7 "no results", redirect or header-only response does not count as coverage. If no topic area has content, the run writes nothing at all — `sources.md` included — and reports what it searched.
The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably it grants no subagent tool, so every `WebFetch` is serial and each fetched page lands in the run's own context — which is why steps 4 and 5 insist on reducing each page to notes before fetching the next, and cap deepening at roughly ten extra pages.
## Composition
Both reference files are read on condition, never on every run — `SKILL.md` inlines the minimum each step needs (the seven default topic areas at step 1, the four `sources.md` field names and the topic-file frontmatter keys at step 6) and sends the run to the reference only for what it does not carry. Those four field names are matched literally by the downstream provenance validator, so prose written in their place parses as nothing and the check passes having verified nothing — which is why they are inlined rather than deferred.
## Usage
```text
/research
```
Name the topic and the output path — the skill will stop and ask if the path is missing. Supplying starting URLs is treated as a deliberate source choice and skips Context7 resolution and discovery. For documentation derived from existing code or specs, use `write-docs`; for a bug or incident, use `diagnose`.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The four gotchas and the six research steps |
| `references/topics.md` | Read at Step 1 only when what belongs in a default topic is unclear or a custom topic is needed: the per-topic coverage table and the custom-topic naming rule |
| `references/file-format.md` | Read at Step 6 only when the inlined field names do not settle the case: slug derivation, the Context7 slug and URL convention, and what belongs in a topic body |

32
plugins/bin/skills/tdd/README.md
View File

@@ -1,32 +0,0 @@
# tdd
Test-driven development as a strict red-green-refactor loop, one behaviour at a time.
## What it does
Two convictions drive this skill. The first is about what a test is for: tests verify behaviour through public interfaces, not implementation details. A good test reads like a specification ("user can checkout with valid cart") and survives refactors because it does not care about internal structure. The warning sign for a bad one is precise — the test breaks when you refactor but behaviour has not changed.
The second is an explicit anti-pattern: **do not write all the tests first, then all the implementation.** Horizontal slicing treats RED as "write every test" and GREEN as "write every implementation", and it produces tests of *imagined* behaviour — tests of the shape of things, insensitive to real change, committed to before the implementation was understood. The correct shape is vertical: one test → one implementation → repeat, each cycle informed by what the last one taught you.
The workflow is four stages: plan (confirm the interface and which behaviours matter, with the user — you cannot test everything), fire a tracer bullet (one test proving the path works end to end), loop incrementally one behaviour at a time, then refactor once everything is green. Refactoring while RED is forbidden.
Codebase exploration uses the project's domain glossary, so test names and interface vocabulary match the project's language, and ADRs in the area are respected.
## Usage
```text
/tdd
```
Describe the feature or bug. Expect the skill to ask what the public interface should look like and which behaviours matter most before any code is written. For diagnosing an existing bug rather than building test-first, use `diagnose`; for throwaway exploratory code, use `prototype`.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Philosophy, the horizontal-slicing anti-pattern, the four-stage workflow, and the per-cycle checklist |
| `references/tests.md` | Cited from Philosophy: worked good and bad test examples |
| `references/mocking.md` | Cited from Philosophy: mock at system boundaries only, and what not to mock |
| `references/deep-modules.md` | Cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for |
| `references/interface-design.md` | Cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them |
| `references/refactoring.md` | Cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession |

35
plugins/bin/skills/triage/README.md
View File

@@ -1,35 +0,0 @@
# triage
Move issues on the project issue tracker through a small state machine of triage roles.
## What it does
Gives issue triage an explicit state model and a fixed set of moves. Every issue carries exactly one **category** role (`bug`, `enhancement`) and one **state** role (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`); conflicting state roles are flagged to the maintainer before anything else happens. Unlabeled issues normally enter at `needs-triage`; `needs-info` returns there once the reporter replies. The maintainer can override at any point, and unusual transitions are questioned rather than executed silently.
A run does one of three things depending on what the maintainer asks for:
- **Show what needs attention** — three buckets, oldest first: unlabeled, `needs-triage`, and `needs-info` with reporter activity since the last triage notes.
- **Triage a specific issue** — gather context (including prior triage notes, so resolved questions are not re-asked, and `.out-of-scope/` records that resemble the issue), recommend a category and state with reasoning, attempt reproduction for bugs *before* any grilling, run a `grill-with-docs` session if the issue needs fleshing out, then apply the outcome.
- **Quick state override** — "move #42 to ready-for-agent" is trusted and applied directly, skipping grilling, after confirming the exact changes.
Two hard rules: every comment or issue the skill posts during triage must open with the AI-generated disclaimer, and the canonical role names above are *not* necessarily the label strings in the tracker — each is resolved against the tracker's live label set before it is applied, and a name with no counterpart there is reported to the maintainer as a gap rather than guessed at.
## Composition
`grill-with-docs` is invoked at step 4 when an issue needs fleshing out; whatever that session establishes is carried into the triage notes so the work is not lost. The reverse direction also exists: `diagnose` names this skill as the place to send a *reported* bug that needs filing rather than debugging.
## Usage
```text
/triage
```
Then describe what you want in natural language — "show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent", "what's ready for agents to pick up?".
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The roles and state machine, the three invocation modes, the needs-info template, and how to resume a prior session |
| `references/agent-brief.md` | Cited when an issue moves to `ready-for-agent` (and reused for `ready-for-human`): how to write a brief that stays durable for weeks while the codebase moves under it — describe interfaces and behavioural contracts, not line numbers |
| `references/out-of-scope.md` | Cited when an enhancement is closed `wontfix` and when checking for prior rejections: how the `.out-of-scope/` knowledge base is laid out and what it is for — institutional memory, and deduplication against re-litigated requests |

30
plugins/bin/skills/write-docs/README.md
View File

@@ -1,30 +0,0 @@
# write-docs
Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section.
## What it does
Casts the agent as a technical writer with one non-negotiable constraint: **every claim must be traceable to a source file line, a spec section, or an explicit user statement.** Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away.
The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human:
- Files are read only after the user approves them by name. The skill may propose candidates; it waits.
- The **gap check** presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects.
- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical.
- **Reader testing** predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting.
Summary and overview sections are written last, once the detail sections are stable.
## Usage
```text
/write-docs
```
Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use `grill-me` or `grill-with-docs` instead — those have dedicated handling.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check |

25
plugins/bin/skills/zoom-out/README.md
View File

@@ -1,25 +0,0 @@
# zoom-out
Ask the agent to go up a layer of abstraction and map the modules and callers around unfamiliar code.
## What it does
A single-purpose prompt for the moment you land in a part of the codebase you do not know. Instead of answering at the level of the file in front of it, the agent climbs one layer and produces a map of the relevant modules and their callers — and names them using the project's own domain glossary vocabulary, so the map lines up with the language the rest of the repo already uses.
## Hand-invoked only
`SKILL.md` sets `disable-model-invocation: true`, so the router never selects this skill on its own and no other skill can hand off to it. It runs when the human asks for it. That also means its description is written as one plain human-facing sentence — it carries no trigger phrasing or boundary clause, because nothing routes on it.
## Usage
```text
/zoom-out
```
Best used with the unfamiliar code already in context — the skill widens the view around what you are looking at rather than picking a starting point for you.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | The whole skill — a single instruction, no supporting files |

38
plugins/core/.apm/skills/agentsmd-audit/README.md
View File

@@ -1,38 +0,0 @@
# agentsmd-audit
Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift.
## What it does
Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything.
## Usage
```
/agentsmd-audit
```
Provide the path to the repo root to audit when invoking.
Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a
hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings |
| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication |
| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo |
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
| `scripts/README.md` | Directory documentation for `scripts/` |
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` |
| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` |
| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

27
plugins/core/.apm/skills/agentsmd-author/README.md
View File

@@ -1,27 +0,0 @@
# agentsmd-author
Create or update a target repo's AGENTS.md file(s) by exploring the repo for real conventions.
## What it does
Explores a target repo (package manager scripts, Makefile/task runner, CI config, linter config, existing docs) and writes or updates `AGENTS.md` with only verified commands and conventions — never invented ones. Supports nested monorepo placement, following the agents.md standard's nearest-file-wins precedence. Closes every run by invoking `agentsmd-audit` inline, and hands off to `provider-adapter-author` when an existing provider-specific file (CLAUDE.md, etc.) now duplicates content AGENTS.md owns.
## Before you start
The `agentsmd-audit` skill must be available (co-installed in the `core` plugin) — this skill invokes it as a mandatory closeout step.
## Usage
```
/agentsmd-author
```
Provide the target repo root (defaults to the current directory) and, if relevant, which subdirectory should get a nested AGENTS.md.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/content-guide.md` | Section-by-section AGENTS.md content guidance, a worked example, and monorepo/nested-file precedence rules |
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |

36
plugins/core/.apm/skills/provider-adapter-author/README.md
View File

@@ -1,36 +0,0 @@
# provider-adapter-author
Convert a target repo's provider-specific instruction file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) into a thin adapter over AGENTS.md.
## What it does
Detects a provider-specific AI instruction file in a target repo, diffs it against the repo's `AGENTS.md`, and rewrites it down to a minimal reference — an `@AGENTS.md`-style import for providers that support one, or a text pointer for those that don't — plus only genuinely provider-specific additions. Self-validates its own output with a bundled deterministic script (no LLM judgment, no separate audit skill) before finishing.
## Before you start
The target repo must already have an `AGENTS.md`. If it doesn't, run `agentsmd-author` first — this skill never creates or edits `AGENTS.md` itself.
## Usage
```
/provider-adapter-author
```
Provide the path to the provider-specific file to convert (and the target repo root, if not inferable). Can be invoked directly, or composed into by `agentsmd-author` when it detects an existing provider file with content overlapping AGENTS.md.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, the validator flag each needs, and the rule that a standalone run and a run composed into by `agentsmd-author` behave identically |
| `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on |
| `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin |
| `scripts/README.md` | Directory documentation for `scripts/` |
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
| `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` |
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`)
but are not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

38
plugins/core/skills/agentsmd-audit/README.md
View File

@@ -1,38 +0,0 @@
# agentsmd-audit
Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift.
## What it does
Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything.
## Usage
```
/agentsmd-audit
```
Provide the path to the repo root to audit when invoking.
Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a
hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings |
| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication |
| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo |
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
| `scripts/README.md` | Directory documentation for `scripts/` |
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` |
| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` |
| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

27
plugins/core/skills/agentsmd-author/README.md
View File

@@ -1,27 +0,0 @@
# agentsmd-author
Create or update a target repo's AGENTS.md file(s) by exploring the repo for real conventions.
## What it does
Explores a target repo (package manager scripts, Makefile/task runner, CI config, linter config, existing docs) and writes or updates `AGENTS.md` with only verified commands and conventions — never invented ones. Supports nested monorepo placement, following the agents.md standard's nearest-file-wins precedence. Closes every run by invoking `agentsmd-audit` inline, and hands off to `provider-adapter-author` when an existing provider-specific file (CLAUDE.md, etc.) now duplicates content AGENTS.md owns.
## Before you start
The `agentsmd-audit` skill must be available (co-installed in the `core` plugin) — this skill invokes it as a mandatory closeout step.
## Usage
```
/agentsmd-author
```
Provide the target repo root (defaults to the current directory) and, if relevant, which subdirectory should get a nested AGENTS.md.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/content-guide.md` | Section-by-section AGENTS.md content guidance, a worked example, and monorepo/nested-file precedence rules |
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |

36
plugins/core/skills/provider-adapter-author/README.md
View File

@@ -1,36 +0,0 @@
# provider-adapter-author
Convert a target repo's provider-specific instruction file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) into a thin adapter over AGENTS.md.
## What it does
Detects a provider-specific AI instruction file in a target repo, diffs it against the repo's `AGENTS.md`, and rewrites it down to a minimal reference — an `@AGENTS.md`-style import for providers that support one, or a text pointer for those that don't — plus only genuinely provider-specific additions. Self-validates its own output with a bundled deterministic script (no LLM judgment, no separate audit skill) before finishing.
## Before you start
The target repo must already have an `AGENTS.md`. If it doesn't, run `agentsmd-author` first — this skill never creates or edits `AGENTS.md` itself.
## Usage
```
/provider-adapter-author
```
Provide the path to the provider-specific file to convert (and the target repo root, if not inferable). Can be invoked directly, or composed into by `agentsmd-author` when it detects an existing provider file with content overlapping AGENTS.md.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, the validator flag each needs, and the rule that a standalone run and a run composed into by `agentsmd-author` behave identically |
| `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on |
| `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin |
| `scripts/README.md` | Directory documentation for `scripts/` |
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
| `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` |
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`)
but are not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

34
plugins/git/.apm/skills/git-branches/README.md
View File

@@ -1,34 +0,0 @@
# git-branches
Manage the full lifecycle of git branches — create, switch, delete, rename, track, merge, and compare feature/hotfix/release branches under GitHub Flow or Gitflow.
## What it does
This skill handles branch operations within the git workflow suite. It creates branches following GitHub Flow or Gitflow conventions (configurable), switches and tracks branches, handles safe deletion with unmerged-work checks, and retrieves branch intent metadata for use by other skills (e.g., commit message context). It returns structured results suitable for agent composition.
## Usage
```
/git-branches
```
Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, track, merge, or compare two branches. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/branch-patterns.md` | Loaded when a branch's base, name prefix, or merge rule depends on GitHub Flow vs. Gitflow |
| `references/branch-operations.md` | Loaded when running a create/switch/delete/rename/track/list/stash action, or resolving `get-intent` |
| `references/merging.md` | Loaded when merging one branch into another or resolving merge conflicts |
| `references/comparing-branches.md` | Loaded when comparing two branches or finding where they diverged |
| `references/orchestrator-contract.md` | Loaded when `git-orchestrate` or another calling agent supplies a structured request rather than prose |
| `references/sources.md` | Research sources backing the branching/gitflow guidance |
## Composition
`git-orchestrate` calls this skill for the branch step of a multi-step workflow and parses its
structured result. Revert is `git-history`'s; commit authoring, rebase, reset and cherry-pick are
`git-commits`'; deleting a remote branch is `git-remotes`'; branch operations against a
Gitea-hosted remote are `gitea-branches`'.

4
plugins/git/.apm/skills/git-branches/SKILL.md
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.1" version: "1.0.2"
category: git category: git
source_keys: source_keys:
- context7-git-htmldocs - context7-git-htmldocs
@@ -21,7 +21,7 @@ metadata:
## Gotchas ## Gotchas
- **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. - **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 <name>` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous — ADR-0023) and `rtk git tag --list <name>`; 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/<name>` or `refs/tags/<name>`. - **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list <name>` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list <name>`; 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/<name>` or `refs/tags/<name>`.
- **`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` 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.
## Step 1 — Determine the branching pattern ## Step 1 — Determine the branching pattern

4
plugins/git/.apm/skills/git-branches/references/branch-operations.md
View File

@@ -45,10 +45,10 @@ past it: it shelves the working tree and index so the branch pointer can move.
reports `No local changes to save` and stashes nothing. Bare `git stash` is `push` with no message. reports `No local changes to save` and stashes nothing. Bare `git stash` is `push` with no message.
- **restore** — `git stash pop` applies the newest entry and deletes it. Bare, not `rtk`: on a - **restore** — `git stash pop` applies the newest entry and deletes it. Bare, not `rtk`: on a
conflict rtk prints only `FAILED: git stash pop` and swallows the conflict report the paragraph conflict rtk prints only `FAILED: git stash pop` and swallows the conflict report the paragraph
below tells you to read (ADR-0023). `rtk git stash apply stash@{n}` below tells you to read. `rtk git stash apply stash@{n}`
applies without deleting, for replaying one shelf onto more than one branch. applies without deleting, for replaying one shelf onto more than one branch.
- **list** — `git stash list` — bare, not `rtk`: rtk prints `No stashes` where git prints nothing, - **list** — `git stash list` — bare, not `rtk`: rtk prints `No stashes` where git prints nothing,
so an empty-output test misfires (ADR-0023). `rtk git stash show -p stash@{n}` prints that entry's diff. so an empty-output test misfires. `rtk git stash show -p stash@{n}` prints that entry's diff.
- **drop** — `rtk git stash drop stash@{n}` deletes one entry. `rtk git stash clear` deletes all of them - **drop** — `rtk git stash drop stash@{n}` deletes one entry. `rtk git stash clear` deletes all of them
and nothing recovers them — confirm before running it. and nothing recovers them — confirm before running it.
- **branch from a stash** — `rtk git stash branch <branch> stash@{n}` creates a branch at the commit the - **branch from a stash** — `rtk git stash branch <branch> stash@{n}` creates a branch at the commit the

2
plugins/git/.apm/skills/git-branches/references/merging.md
View File

@@ -27,5 +27,5 @@ list the conflicted files, edit each to resolve its markers, then `rtk git add <
- `rtk git merge --abort` restores the pre-merge state. - `rtk git merge --abort` restores the pre-merge state.
- `git mergetool` opens the configured merge tool — bare, not `rtk`: it hands control to an - `git mergetool` opens the configured merge tool — bare, not `rtk`: it hands control to an
interactive child process, and a token filter has nothing to offer there (ADR-0023). interactive child process, and a token filter has nothing to offer there.
- `rtk git diff --diff-filter=U` shows only the still-conflicted files. - `rtk git diff --diff-filter=U` shows only the still-conflicted files.

31
plugins/git/.apm/skills/git-commits/README.md
View File

@@ -1,31 +0,0 @@
# git-commits
Create, amend, squash, and cherry-pick commits with Conventional Commits formatting and validation.
## What it does
This skill handles commit operations within the git workflow suite. It generates well-formatted commit messages following the Conventional Commits spec, validates against commitlint config-conventional constraints, and communicates SemVer impact. It enforces confirmation gates for history-altering operations (amend, rebase, squash) and returns structured JSON output for agent consumption.
## Usage
```
/git-commits
```
Describe your commit task: create a new commit, amend, squash, or cherry-pick. The skill will guide message formatting and handle confirmation for destructive operations.
## Files
| File | Loaded when |
|------|-------------|
| `SKILL.md` | Always — gotchas, the flow dispatch table, the gates common to every flow, and the output shape |
| `references/create-commit.md` | Composing a new commit from staged changes |
| `references/rewrite-history.md` | Amending, squashing, or folding a `fixup!`/`squash!` commit into an earlier one |
| `references/cherry-pick.md` | Replaying an existing commit onto the current branch |
| `references/conventional-commits-spec.md` | A type, footer, or breaking-change edge case is not obvious — full spec, 11-type set, commitlint constraint table |
| `references/commit-template.md` | Writing a body for a non-trivial commit — Why / Implementation Notes / Impact structure and the full trailer list |
| `references/sources.md` | Research sources and provenance |
## Composition
Part of the git plugin's domain suite. This skill owns commit authoring and history-rewriting operations only; `git-history` inspects history, `git-branches` owns branch lifecycle, and `git-workflow` is the conversational entry point that routes between them.

4
plugins/git/.apm/skills/git-commits/SKILL.md
View File

@@ -8,7 +8,7 @@ description: >
Not branch lifecycle -> `git-branches`. Not branch lifecycle -> `git-branches`.
metadata: metadata:
version: "0.1.4" version: "0.1.5"
category: git category: git
source_keys: source_keys:
- conventional-commits-spec - conventional-commits-spec
@@ -21,7 +21,7 @@ allowed-tools: Bash
## Gotchas ## Gotchas
- **Run git as `rtk git <subcommand>`, never bare `git`** — org convention, in `&&` chains too. Exceptions: ADR-0023 clause 3. - **Run git as `rtk git <subcommand>`, 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 leaves the branch diverged 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. - **`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. - **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.

2
plugins/git/.apm/skills/git-commits/references/rewrite-history.md
View File

@@ -21,7 +21,7 @@ Prefer this whenever a commit is written to be folded, because git does the mark
1. `rtk git commit --fixup=<commit>` keeps the target's message; `rtk git commit --squash=<commit>` lets you edit the combined message later. Both prefix the message with `fixup!`/`squash!` and name the target commit. 1. `rtk git commit --fixup=<commit>` keeps the target's message; `rtk git commit --squash=<commit>` lets you edit the combined message later. Both prefix the message with `fixup!`/`squash!` and name the target commit.
2. Get explicit approval — the rebase still rewrites history. 2. Get explicit approval — the rebase still rewrites history.
3. Run `git rebase -i --autosquash HEAD~N` — bare, not `rtk`: `-i` opens an interactive sequence editor (ADR-0023). Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply. 3. Run `git rebase -i --autosquash HEAD~N` — bare, not `rtk`: `-i` opens an interactive sequence editor. Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply.
**`-i` is not optional here.** On Git 2.39.5, `git rebase --autosquash HEAD~N` without `-i` prints `Successfully rebased and updated refs/heads/<branch>.` and exits 0 while leaving the `fixup!` commit in place at its original SHA — `--autosquash` is honoured only by the interactive machinery, and the false success is the trap: the fold is reported as done, and the surviving `fixup!` subject then fails the Conventional Commits `commit-msg` hook. Later Git versions taught the non-interactive rebase to honour the flag, but `-i --autosquash` is correct on every version, so always write that. **`-i` is not optional here.** On Git 2.39.5, `git rebase --autosquash HEAD~N` without `-i` prints `Successfully rebased and updated refs/heads/<branch>.` and exits 0 while leaving the `fixup!` commit in place at its original SHA — `--autosquash` is honoured only by the interactive machinery, and the false success is the trap: the fold is reported as done, and the surviving `fixup!` subject then fails the Conventional Commits `commit-msg` hook. Later Git versions taught the non-interactive rebase to honour the flag, but `-i --autosquash` is correct on every version, so always write that.

29
plugins/git/.apm/skills/git-history/README.md
View File

@@ -1,29 +0,0 @@
# git-history
Inspect git history — log queries, bisect, and locating problematic commits.
## What it does
This skill handles history inspection within the git workflow suite. It queries logs with pickaxe/line-range/custom formats, runs bisect to find bug-introducing commits, and locates commits for downstream cherry-picking or reverting. It returns structured results for agent composition. Rebase, squash, fixup, and other history-rewriting operations are owned by git-commits, not this skill.
## Composition
`git-branches` delegates revert here (see `git-branches`'s `references/merging.md`), which is why this skill carries that operation rather than treating it as out of scope; it is general git knowledge, not drawn from the `history-inspection.md` research corpus. Cherry-pick is **not** this skill's: `git-commits` owns it, and this skill's job ends at locating the SHA to hand over. Server-side commit history on a Gitea-hosted repository belongs to `gitea-branches`; this skill reads the local working copy.
## Usage
```
/git-history
```
Describe your history task: search logs, bisect for a regression, or locate a specific commit. The skill will query history and return structured results.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/bisect.md` | Loaded when the entry procedure is bisect: manual and automated flows, exit codes, skip, replay, narrowing, custom terms |
| `references/git-log-format.md` | Loaded when a log or diff flag needs looking up: format placeholders, presets, diff-filter letters, `-L` syntax, ancestry filters, pickaxe binary-file behaviour, diff output-control flags |
| `references/sources.md` | Research sources and provenance |
| `references/README.md` | Index of the references directory |

4
plugins/git/.apm/skills/git-history/SKILL.md
View File

@@ -8,7 +8,7 @@ description: >
`git-commits`. Not a Gitea server's history -> `gitea-branches`. `git-commits`. Not a Gitea server's history -> `gitea-branches`.
metadata: metadata:
version: "1.0.1" version: "1.0.2"
category: git category: git
source_keys: source_keys:
- git-scm-bisect-docs - git-scm-bisect-docs
@@ -38,7 +38,7 @@ allowed-tools: Bash
Default to `rtk git log --oneline`, then narrow by whatever is known: Default to `rtk git log --oneline`, then narrow by whatever is known:
- **Content**: `rtk git log -S"string"`, or `-G"regex"` to match any diff line. `--pickaxe-regex` makes the `-S` argument a POSIX ERE; `--pickaxe-all` shows every file in a matching changeset. - **Content**: `rtk git log -S"string"`, or `-G"regex"` to match any diff line. `--pickaxe-regex` makes the `-S` argument a POSIX ERE; `--pickaxe-all` shows every file in a matching changeset.
- **A line or function**: `git log -L <start>,<end>:<file>` or `git log -L :<function>:<file>` — bare, not `rtk`: rtk truncates each diff line at ~72 characters (ADR-0023). Confirm the range resolves before reporting on it — an off-by-one silently omits the target. - **A line or function**: `git log -L <start>,<end>:<file>` or `git log -L :<function>:<file>` — bare, not `rtk`: rtk truncates each diff line at ~72 characters. Confirm the range resolves before reporting on it — an off-by-one silently omits the target.
- **A file across renames**: `rtk git log --follow -- <file>`. Without `--follow` the history stops at the rename boundary. - **A file across renames**: `rtk git log --follow -- <file>`. Without `--follow` the history stops at the rename boundary.
- **Mainline only**: `--first-parent` follows the integration branch and skips commits merged in from side branches. - **Mainline only**: `--first-parent` follows the integration branch and skips commits merged in from side branches.
- **Structured output**: `rtk git log --format="%h | %s | %an (%ar)"`. - **Structured output**: `rtk git log --format="%h | %s | %an (%ar)"`.

16
plugins/git/.apm/skills/git-history/references/README.md
View File

@@ -1,16 +0,0 @@
---
source_keys:
- git-scm-bisect-docs
- git-scm-log-docs
- git-scm-diff-docs
---
# References
This directory contains provenance metadata and research sources for the `git-history` skill.
## Files
- `sources.md` — Extracted research sources and their contributing documents
- `bisect.md` — The full `git bisect` procedure: manual and automated flows, exit-code semantics, skip and replay, narrowing options, and custom good/bad terms
- `git-log-format.md` — Full `git log` format placeholder catalogue, named format presets, `--diff-filter` letters, `-L` line-range syntax, ancestry filters, pickaxe binary-file behaviour, and `git diff` output-control flags

20
plugins/git/.apm/skills/git-history/references/git-log-format.md
View File

@@ -166,10 +166,10 @@ line at roughly 72 characters with an ellipsis, on the one query whose whole poi
is showing line content. is showing line content.
```bash ```bash
git log -L 10,20:file.txt # bare per ADR-0023 git log -L 10,20:file.txt # bare (ADR-0023)
git log -L /start_pattern/,/end_pattern/:file.txt # bare per ADR-0023 git log -L /start_pattern/,/end_pattern/:file.txt # bare (ADR-0023)
git log -L :myfunction:src/app.c # bare per ADR-0023 git log -L :myfunction:src/app.c # bare (ADR-0023)
git log -L /init/,+15:config.py # bare per ADR-0023; 15 lines after first /init/ match git log -L /init/,+15:config.py # bare (ADR-0023); 15 lines after first /init/ match
``` ```
Range formats: Range formats:
@@ -213,8 +213,8 @@ Bare `git`, not `rtk git`: rtk appends a blank line and a `Changes:` trailer, so
the output is no longer one record per line. the output is no longer one record per line.
```bash ```bash
git diff --name-only # bare per ADR-0023; only filenames, one per line git diff --name-only # bare (ADR-0023); only filenames, one per line
git diff --name-status # bare per ADR-0023; status letter + filename per line git diff --name-status # bare (ADR-0023); status letter + filename per line
``` ```
`--name-status` uses the same status letters as `--diff-filter`. `--name-status` uses the same status letters as `--diff-filter`.
@@ -225,10 +225,10 @@ Bare `git`, not `rtk git`: rtk replaces the word-diff with its own diffstat
renderer and emits none of the `[-removed-] {+added+}` markers. renderer and emits none of the `[-removed-] {+added+}` markers.
```bash ```bash
git diff --word-diff # bare per ADR-0023; inline word-level diff, [-removed-] {+added+} markers git diff --word-diff # bare (ADR-0023); inline word-level diff, [-removed-] {+added+} markers
git diff --word-diff=color # bare per ADR-0023; color only, no markers git diff --word-diff=color # bare (ADR-0023); color only, no markers
git diff --word-diff=porcelain # bare per ADR-0023; machine-readable: +/- prefixed lines, ~ for newlines git diff --word-diff=porcelain # bare (ADR-0023); machine-readable: +/- prefixed lines, ~ for newlines
git diff --word-diff-regex=<re> # bare per ADR-0023; define what counts as a "word" git diff --word-diff-regex=<re> # bare (ADR-0023); define what counts as a "word"
``` ```
### Whitespace Flags ### Whitespace Flags

34
plugins/git/.apm/skills/git-remotes/README.md
View File

@@ -1,34 +0,0 @@
# git-remotes
Manage git remote repositories — add/remove/configure remotes, push/pull with safety checks, fetch with pruning, and multi-remote workflows.
## What it does
This skill handles remote operations within the git workflow suite. It manages remote configuration (add, remove, rename), fetch operations with pruning, push operations with force-push safety (`--force-with-lease --force-if-includes`), and pull strategies (fast-forward, rebase, merge). It returns structured results suitable for agent composition.
## Usage
```
/git-remotes
```
Describe your remote operation: add a remote, push, pull, fetch, or configure tracking. The skill will handle the operation with appropriate safety checks and return results.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — force-push gate, dispatch table, return format |
| `references/README.md` | Describes the references directory contents |
| `references/remote-config.md` | Read when adding, removing, renaming, inspecting or re-pointing a remote, or configuring tracking, mirroring, or `set-url` |
| `references/fetch.md` | Read when fetching or pruning remote-tracking refs, or doing a shallow or partial fetch |
| `references/push.md` | Read when pushing branches or tags, writing refspecs, or force-pushing |
| `references/pull.md` | Read when integrating remote changes into the current branch, including the divergence rule |
| `references/sources.md` | Research sources and provenance |
## Composition
Callers that need submodule initialization after a `--recurse-submodules` pull hand off to
`git-submodules`; local-only work (commits, branches, history) belongs to `git-commits`,
`git-branches`, and `git-history`. The `git-workflow` skill routes humans here for any
remote-touching request.

2
plugins/git/.apm/skills/git-remotes/SKILL.md
View File

@@ -10,7 +10,7 @@ description: >
Not submodule pointers -> `git-submodules`. Not submodule pointers -> `git-submodules`.
metadata: metadata:
version: "1.0.1" version: "1.0.2"
category: git category: git
source_keys: source_keys:
- git-scm-remote-docs - git-scm-remote-docs

20
plugins/git/.apm/skills/git-remotes/references/README.md
View File

@@ -1,20 +0,0 @@
---
source_keys:
- git-scm-remote-docs
- git-scm-fetch-docs
- git-scm-push-docs
- git-scm-pull-docs
- context7-git-htmldocs
---
# References
This directory contains provenance metadata and research sources for the `git-remotes` skill.
## Files
- `sources.md` — Extracted research sources and their contributing documents
- `remote-config.md` — Remote add/remove/rename/inspect, tracking and mirror options, housekeeping, and the full `set-url` form
- `fetch.md` — Fetch and prune options, shallow and partial fetch, the default fetch refspec
- `push.md` — Push options, refspec syntax, force-push safety in full, server-side deny policies
- `pull.md` — Pull strategies, submodule caveat, the divergence rule, and pull config precedence

2
plugins/git/.apm/skills/git-remotes/references/push.md
View File

@@ -50,7 +50,7 @@ Two mitigations:
# poisoned by an unrelated fetch. # poisoned by an unrelated fetch.
# The inner `git config` is bare: its stdout becomes a remote URL, so any # The inner `git config` is bare: its stdout becomes a remote URL, so any
# output rewriting would poison the remote silently. # output rewriting would poison the remote silently.
rtk git remote add origin-push $(git config remote.origin.url) # inner bare per ADR-0023 rtk git remote add origin-push $(git config remote.origin.url) # inner bare (ADR-0023)
rtk git push --force-with-lease origin-push rtk git push --force-with-lease origin-push
# Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state # Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state

35
plugins/git/.apm/skills/git-submodules/README.md
View File

@@ -1,35 +0,0 @@
# git-submodules
Add, initialize, update, pin, inspect, and remove git submodules in multi-repository projects.
## What it does
This skill handles submodule operations within the git workflow suite: cloning a superproject with
its nested repositories, adding a dependency as a submodule, initializing and updating with
pinning or branch tracking, parallel and recursive traversal, rebinding URLs and tracked branches,
and the full removal sequence including the `.git/modules/` cleanup git leaves behind. It returns
structured results suitable for agent composition.
It sits alongside the other git skills rather than duplicating them: `git-worktrees` covers
multiple checkouts of a single repository, and `git-remotes` covers the superproject's own remotes.
## Usage
```
/git-submodules
```
Describe the submodule task. The skill applies the shared working rules, dispatches to the
reference for that task, and returns structured results (operation, status, per-submodule details,
conflicts, and a recovery `next_step` when applicable).
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — gotchas, shared working rules, and the task dispatch table |
| `references/README.md` | Describes contents of references/ |
| `references/setup-and-update.md` | Loaded when cloning a superproject, adding a submodule, initializing, updating, or re-pinning one, or running a command across all of them — includes the full `add` and `update` flag tables, the pinning workflows, and the `foreach` shell-variable table |
| `references/urls-and-config.md` | Loaded when changing where a submodule points or how it is configured — `.gitmodules` vs `.git/config` anatomy, both key tables, `sync`/`set-url`/`set-branch`, local mirror overrides, relative URLs, the custom-`update` security gate, and `absorbgitdirs` |
| `references/removal.md` | Loaded when removing or deinitializing a submodule — why `deinit` is not removal, and the four-step removal sequence |
| `references/sources.md` | Research sources and provenance |

31
plugins/git/.apm/skills/git-submodules/references/README.md
View File

@@ -1,31 +0,0 @@
---
source_keys:
- git-scm-submodule-docs
---
# References
One file per task branch in SKILL.md's dispatch table. Load only the one that matches the request.
## setup-and-update.md
Cloning a superproject that has submodules, adding a dependency as a submodule, initializing
without cloning, updating or re-pinning, and running one command across every submodule. Carries
the `add` and `update` flag tables, the keep-pinned and move-the-pin-forward workflows, and the
`foreach` shell-variable table (`$name`, `$sm_path`, `$displaypath`, `$sha1`, `$toplevel`).
## urls-and-config.md
Where a submodule points and how it is configured: the `.gitmodules` vs `.git/config` split, both
key tables, `sync` / `set-url` / `set-branch`, local mirror overrides, relative URL resolution, the
security gate on custom `update` commands, and `absorbgitdirs`.
## removal.md
Removing a submodule, and why `deinit` alone does not remove one. Carries the full four-step
removal sequence including the manual `.git/modules/<name>/` cleanup.
## sources.md
Research sources that informed this skill — provenance chain for git-scm-submodule-docs reference
material.

25
plugins/git/.apm/skills/git-workflow/README.md
View File

@@ -1,25 +0,0 @@
# git-workflow
Human-friendly interface for interactive git workflows with conversational prompts, progress guidance, and safety confirmations.
## What it does
This skill wraps the `git-orchestrate` agent to provide an interactive, educational interface for humans performing git workflows. It is the router for the six local-git domain skills — `git-commits`, `git-branches`, `git-history`, `git-remotes`, `git-submodules` and `git-worktrees` — and `SKILL.md` carries a table mapping each of them to the requests it owns, so an ambiguous request resolves to exactly one domain before anything runs. The skill parses user intent, gathers session context, invokes the orchestrator, and presents results in plain language with inline help, progress updates, and explanations of what's happening. It enforces confirmation gates for destructive operations (force-push, branch deletion, rebasing with history loss, force-checkout) and provides best-practices guidance throughout. The org's non-negotiable git rules live in `references/hard-rules.md` and are loaded only when a request could conflict with one.
## Usage
```
/git-workflow
```
Describe your git workflow: commit, create a branch, rebase, inspect history, manage submodules, switch worktrees, or manage remotes. The skill will prompt for any missing details and guide you through the workflow.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — the six-domain routing table, the workflow steps, and the interaction style |
| `README.md` | This file |
| `references/hard-rules.md` | The org's non-negotiable git rules; read when a request creates, amends, or rewrites a commit, pushes, or touches hooks, config, or credentials |
| `references/README.md` | Describes the references directory contents |
| `references/sources.md` | Research sources and provenance |

19
plugins/git/.apm/skills/git-workflow/references/README.md
View File

@@ -1,19 +0,0 @@
---
source_keys:
- nvie-gitflow-post
- atlassian-gitflow-tutorial
- gitflow-cheatsheet
- context7-git-htmldocs
- org-git-conventions
---
# References
This directory contains the org git rules and the provenance metadata for the `git-workflow`
skill.
## Files
- `hard-rules.md` — The org's non-negotiable git rules, loaded when a request creates, amends, or
rewrites a commit, pushes, or touches hooks, config, or credentials
- `sources.md` — Extracted research sources and their contributing documents

24
plugins/git/.apm/skills/git-worktrees/README.md
View File

@@ -1,24 +0,0 @@
# git-worktrees
Manage git worktrees to enable multi-branch parallel development across isolated directories.
## What it does
This skill handles worktree operations within the git workflow suite. It creates, lists, locks/unlocks, moves, removes, prunes, and repairs worktrees — letting an agent work on multiple branches simultaneously without stashing. It returns structured results (paths, branches, lock status) suitable for agent composition. For multi-step flows spanning branch strategy plus worktree setup, `git-workflow` handles the broader orchestration and delegates the worktree mechanics here.
## Usage
```
/git-worktrees
```
Describe your worktree task: create a worktree for a branch, list existing worktrees, lock one for removable media, move, remove, prune, or repair. The skill will handle the operation with appropriate safety checks and return results.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Dispatch table, per-operation gates, and the report format |
| `references/README.md` | Describes the references directory contents |
| `references/worktrees.md` | Read when an operation needs more than the dispatch table: shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout, removable-media locking, remote disambiguation, where to run `repair` from, config keys, and the emergency-fix and PR-review patterns |
| `references/sources.md` | Research sources and provenance |

6
plugins/git/.apm/skills/git-worktrees/SKILL.md
View File

@@ -8,7 +8,7 @@ description: >
Not interactive multi-step git guidance -> `git-workflow`. Not interactive multi-step git guidance -> `git-workflow`.
metadata: metadata:
version: "1.0.1" version: "1.0.2"
category: git category: git
source_keys: source_keys:
- git-scm-worktree-docs - git-scm-worktree-docs
@@ -32,7 +32,7 @@ metadata:
| Create a local branch tracking a remote one | `rtk git worktree add --track -b <branch> <path> <remote>/<branch>` — always correct. `git worktree add <path> <branch>` expands to exactly this, but **only** under the conditions in `references/worktrees.md` | | Create a local branch tracking a remote one | `rtk git worktree add --track -b <branch> <path> <remote>/<branch>` — always correct. `git worktree add <path> <branch>` expands to exactly this, but **only** under the conditions in `references/worktrees.md` |
| Throwaway experiment, no branch | `rtk git worktree add -d <path>` — detached HEAD | | Throwaway experiment, no branch | `rtk git worktree add -d <path>` — detached HEAD |
| **Never** `git worktree add <path> <remote>/<branch>` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above | | **Never** `git worktree add <path> <remote>/<branch>` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above |
| List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare per ADR-0023: rtk re-renders the output and drops the porcelain flags | | List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare (ADR-0023): rtk re-renders the output and drops the porcelain flags |
| Lock or unlock | `rtk git worktree lock [--reason <str>] <path>` / `rtk git worktree unlock <path>` | | Lock or unlock | `rtk git worktree lock [--reason <str>] <path>` / `rtk git worktree unlock <path>` |
| Move | `rtk git worktree move <from> <to>` | | Move | `rtk git worktree move <from> <to>` |
| Remove | `rtk git worktree remove <path>` | | Remove | `rtk git worktree remove <path>` |
@@ -63,6 +63,6 @@ worktrees:
``` ```
Derive those fields from `git worktree list --porcelain -z` — bare, not `rtk`: Derive those fields from `git worktree list --porcelain -z` — bare, not `rtk`:
rtk drops both flags and never emits `locked`/`lock_reason` (ADR-0023). For a single rtk drops both flags and never emits `locked`/`lock_reason`. For a single
operation, report its outcome instead — `created: true`, `moved: true`, operation, report its outcome instead — `created: true`, `moved: true`,
`removed: true`. `removed: true`.

13
plugins/git/.apm/skills/git-worktrees/references/README.md
View File

@@ -1,13 +0,0 @@
---
source_keys:
- git-scm-worktree-docs
---
# References
This directory contains provenance metadata and research sources for the `git-worktrees` skill.
## Files
- `sources.md` — Extracted research sources and their contributing documents
- `worktrees.md` — Shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout setup, removable-media locking, remote-branch disambiguation, where to run `repair` from, the config key reference, and the emergency-fix and PR-review workflow patterns

26
plugins/git/.apm/skills/pc-author/README.md
View File

@@ -1,26 +0,0 @@
# pc-author
Create, add, remove, update, and configure `.pre-commit-config.yaml`.
## What it does
Manages the pre-commit configuration file in any git repo. When invoked, it scans the repo for languages, proposes appropriate hooks with rationale, and writes or modifies `.pre-commit-config.yaml`. It validates every write with `pre-commit validate-config` and flags stale revision pins. It does not run hooks or install them into `.git/hooks/` — use `pc-run` for that.
## Usage
```
/pc-author
```
Invoke with no arguments. The skill determines from context whether to create a new config or modify an existing one.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/create-config.md` | Loaded when the repo has no `.pre-commit-config.yaml` — the create-from-scratch flow |
| `references/modify-config.md` | Loaded when a `.pre-commit-config.yaml` already exists — add, remove, top-level keys, rev staleness |
| `references/hooks-by-language.md` | Hook recommendations by detected language/extension |
| `references/README.md` | Index of files in references/ |
| `references/sources.md` | Provenance — research sources that informed this skill |

16
plugins/git/.apm/skills/pc-author/references/README.md
View File

@@ -1,16 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
- context7-pre-commit-hooks
- pre-commit-hooks-github
---
# references/
| File | Purpose |
|---|---|
| `create-config.md` | The create flow — read when the repo has no `.pre-commit-config.yaml` |
| `modify-config.md` | The modify flow — read when a `.pre-commit-config.yaml` already exists |
| `hooks-by-language.md` | Hook recommendations by language/context — repo, rev, and rationale for adding hooks |
| `sources.md` | Provenance: research sources that informed this skill |

32
plugins/git/.apm/skills/pc-run/README.md
View File

@@ -1,32 +0,0 @@
# pc-run
Runs, installs, updates, and maintains pre-commit hooks in a local git clone.
## What it does
`pc-run` handles everything that happens *after* `.pre-commit-config.yaml` exists: wiring hooks into git, running them, bumping their versions, and maintaining the cache. When hooks fail, it identifies the cause and suggests a concrete fix — it does not auto-fix files or edit the config. For creating or editing `.pre-commit-config.yaml`, use `pc-author` instead.
## Before you start
- `pre-commit` must be installed and available on `PATH`
- A `.pre-commit-config.yaml` must exist at the repo root (use `pc-author` to create one)
## Usage
Common invocations:
- `/pc-run` — run all hooks against all files (default)
- `/pc-run install` — wire hooks into `.git/hooks/`
- `/pc-run autoupdate` — bump all `rev` values to latest
- `/pc-run clean` — wipe the pre-commit cache (requires confirmation)
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/install.md` | The install flow — loaded when the user asks to install or set up hooks |
| `references/autoupdate.md` | The autoupdate flow — loaded when the user asks to bump hook revs |
| `references/clean.md` | The clean flow — loaded when the user asks to wipe the cache or rebuild environments |
| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when a hook fails or never fires |
| `references/sources.md` | Provenance: research sources that informed this skill |
| `references/README.md` | Directory index for references/ |

17
plugins/git/.apm/skills/pc-run/references/README.md
View File

@@ -1,17 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
- context7-pre-commit-hooks
- pre-commit-hooks-github
---
# references/
| File | Purpose |
|---|---|
| `install.md` | The install flow — read when the user asks to install or set up hooks |
| `autoupdate.md` | The autoupdate flow — read when the user asks to bump hook revs |
| `clean.md` | The clean flow — read when the user asks to wipe the cache or rebuild environments |
| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — read when a hook fails or never fires |
| `sources.md` | Provenance: research sources that informed this skill |

34
plugins/git/skills/git-branches/README.md
View File

@@ -1,34 +0,0 @@
# git-branches
Manage the full lifecycle of git branches — create, switch, delete, rename, track, merge, and compare feature/hotfix/release branches under GitHub Flow or Gitflow.
## What it does
This skill handles branch operations within the git workflow suite. It creates branches following GitHub Flow or Gitflow conventions (configurable), switches and tracks branches, handles safe deletion with unmerged-work checks, and retrieves branch intent metadata for use by other skills (e.g., commit message context). It returns structured results suitable for agent composition.
## Usage
```
/git-branches
```
Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, track, merge, or compare two branches. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/branch-patterns.md` | Loaded when a branch's base, name prefix, or merge rule depends on GitHub Flow vs. Gitflow |
| `references/branch-operations.md` | Loaded when running a create/switch/delete/rename/track/list/stash action, or resolving `get-intent` |
| `references/merging.md` | Loaded when merging one branch into another or resolving merge conflicts |
| `references/comparing-branches.md` | Loaded when comparing two branches or finding where they diverged |
| `references/orchestrator-contract.md` | Loaded when `git-orchestrate` or another calling agent supplies a structured request rather than prose |
| `references/sources.md` | Research sources backing the branching/gitflow guidance |
## Composition
`git-orchestrate` calls this skill for the branch step of a multi-step workflow and parses its
structured result. Revert is `git-history`'s; commit authoring, rebase, reset and cherry-pick are
`git-commits`'; deleting a remote branch is `git-remotes`'; branch operations against a
Gitea-hosted remote are `gitea-branches`'.

4
plugins/git/skills/git-branches/SKILL.md
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.1" version: "1.0.2"
category: git category: git
source_keys: source_keys:
- context7-git-htmldocs - context7-git-htmldocs
@@ -21,7 +21,7 @@ metadata:
## Gotchas ## Gotchas
- **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. - **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 <name>` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous — ADR-0023) and `rtk git tag --list <name>`; 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/<name>` or `refs/tags/<name>`. - **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list <name>` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list <name>`; 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/<name>` or `refs/tags/<name>`.
- **`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` 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.
## Step 1 — Determine the branching pattern ## Step 1 — Determine the branching pattern

4
plugins/git/skills/git-branches/references/branch-operations.md
View File

@@ -45,10 +45,10 @@ past it: it shelves the working tree and index so the branch pointer can move.
reports `No local changes to save` and stashes nothing. Bare `git stash` is `push` with no message. reports `No local changes to save` and stashes nothing. Bare `git stash` is `push` with no message.
- **restore** — `git stash pop` applies the newest entry and deletes it. Bare, not `rtk`: on a - **restore** — `git stash pop` applies the newest entry and deletes it. Bare, not `rtk`: on a
conflict rtk prints only `FAILED: git stash pop` and swallows the conflict report the paragraph conflict rtk prints only `FAILED: git stash pop` and swallows the conflict report the paragraph
below tells you to read (ADR-0023). `rtk git stash apply stash@{n}` below tells you to read. `rtk git stash apply stash@{n}`
applies without deleting, for replaying one shelf onto more than one branch. applies without deleting, for replaying one shelf onto more than one branch.
- **list** — `git stash list` — bare, not `rtk`: rtk prints `No stashes` where git prints nothing, - **list** — `git stash list` — bare, not `rtk`: rtk prints `No stashes` where git prints nothing,
so an empty-output test misfires (ADR-0023). `rtk git stash show -p stash@{n}` prints that entry's diff. so an empty-output test misfires. `rtk git stash show -p stash@{n}` prints that entry's diff.
- **drop** — `rtk git stash drop stash@{n}` deletes one entry. `rtk git stash clear` deletes all of them - **drop** — `rtk git stash drop stash@{n}` deletes one entry. `rtk git stash clear` deletes all of them
and nothing recovers them — confirm before running it. and nothing recovers them — confirm before running it.
- **branch from a stash** — `rtk git stash branch <branch> stash@{n}` creates a branch at the commit the - **branch from a stash** — `rtk git stash branch <branch> stash@{n}` creates a branch at the commit the

2
plugins/git/skills/git-branches/references/merging.md
View File

@@ -27,5 +27,5 @@ list the conflicted files, edit each to resolve its markers, then `rtk git add <
- `rtk git merge --abort` restores the pre-merge state. - `rtk git merge --abort` restores the pre-merge state.
- `git mergetool` opens the configured merge tool — bare, not `rtk`: it hands control to an - `git mergetool` opens the configured merge tool — bare, not `rtk`: it hands control to an
interactive child process, and a token filter has nothing to offer there (ADR-0023). interactive child process, and a token filter has nothing to offer there.
- `rtk git diff --diff-filter=U` shows only the still-conflicted files. - `rtk git diff --diff-filter=U` shows only the still-conflicted files.

31
plugins/git/skills/git-commits/README.md
View File

@@ -1,31 +0,0 @@
# git-commits
Create, amend, squash, and cherry-pick commits with Conventional Commits formatting and validation.
## What it does
This skill handles commit operations within the git workflow suite. It generates well-formatted commit messages following the Conventional Commits spec, validates against commitlint config-conventional constraints, and communicates SemVer impact. It enforces confirmation gates for history-altering operations (amend, rebase, squash) and returns structured JSON output for agent consumption.
## Usage
```
/git-commits
```
Describe your commit task: create a new commit, amend, squash, or cherry-pick. The skill will guide message formatting and handle confirmation for destructive operations.
## Files
| File | Loaded when |
|------|-------------|
| `SKILL.md` | Always — gotchas, the flow dispatch table, the gates common to every flow, and the output shape |
| `references/create-commit.md` | Composing a new commit from staged changes |
| `references/rewrite-history.md` | Amending, squashing, or folding a `fixup!`/`squash!` commit into an earlier one |
| `references/cherry-pick.md` | Replaying an existing commit onto the current branch |
| `references/conventional-commits-spec.md` | A type, footer, or breaking-change edge case is not obvious — full spec, 11-type set, commitlint constraint table |
| `references/commit-template.md` | Writing a body for a non-trivial commit — Why / Implementation Notes / Impact structure and the full trailer list |
| `references/sources.md` | Research sources and provenance |
## Composition
Part of the git plugin's domain suite. This skill owns commit authoring and history-rewriting operations only; `git-history` inspects history, `git-branches` owns branch lifecycle, and `git-workflow` is the conversational entry point that routes between them.

4
plugins/git/skills/git-commits/SKILL.md
View File

@@ -8,7 +8,7 @@ description: >
Not branch lifecycle -> `git-branches`. Not branch lifecycle -> `git-branches`.
metadata: metadata:
version: "0.1.4" version: "0.1.5"
category: git category: git
source_keys: source_keys:
- conventional-commits-spec - conventional-commits-spec
@@ -21,7 +21,7 @@ allowed-tools: Bash
## Gotchas ## Gotchas
- **Run git as `rtk git <subcommand>`, never bare `git`** — org convention, in `&&` chains too. Exceptions: ADR-0023 clause 3. - **Run git as `rtk git <subcommand>`, 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 leaves the branch diverged 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. - **`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. - **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.

2
plugins/git/skills/git-commits/references/rewrite-history.md
View File

@@ -21,7 +21,7 @@ Prefer this whenever a commit is written to be folded, because git does the mark
1. `rtk git commit --fixup=<commit>` keeps the target's message; `rtk git commit --squash=<commit>` lets you edit the combined message later. Both prefix the message with `fixup!`/`squash!` and name the target commit. 1. `rtk git commit --fixup=<commit>` keeps the target's message; `rtk git commit --squash=<commit>` lets you edit the combined message later. Both prefix the message with `fixup!`/`squash!` and name the target commit.
2. Get explicit approval — the rebase still rewrites history. 2. Get explicit approval — the rebase still rewrites history.
3. Run `git rebase -i --autosquash HEAD~N` — bare, not `rtk`: `-i` opens an interactive sequence editor (ADR-0023). Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply. 3. Run `git rebase -i --autosquash HEAD~N` — bare, not `rtk`: `-i` opens an interactive sequence editor. Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply.
**`-i` is not optional here.** On Git 2.39.5, `git rebase --autosquash HEAD~N` without `-i` prints `Successfully rebased and updated refs/heads/<branch>.` and exits 0 while leaving the `fixup!` commit in place at its original SHA — `--autosquash` is honoured only by the interactive machinery, and the false success is the trap: the fold is reported as done, and the surviving `fixup!` subject then fails the Conventional Commits `commit-msg` hook. Later Git versions taught the non-interactive rebase to honour the flag, but `-i --autosquash` is correct on every version, so always write that. **`-i` is not optional here.** On Git 2.39.5, `git rebase --autosquash HEAD~N` without `-i` prints `Successfully rebased and updated refs/heads/<branch>.` and exits 0 while leaving the `fixup!` commit in place at its original SHA — `--autosquash` is honoured only by the interactive machinery, and the false success is the trap: the fold is reported as done, and the surviving `fixup!` subject then fails the Conventional Commits `commit-msg` hook. Later Git versions taught the non-interactive rebase to honour the flag, but `-i --autosquash` is correct on every version, so always write that.

29
plugins/git/skills/git-history/README.md
View File

@@ -1,29 +0,0 @@
# git-history
Inspect git history — log queries, bisect, and locating problematic commits.
## What it does
This skill handles history inspection within the git workflow suite. It queries logs with pickaxe/line-range/custom formats, runs bisect to find bug-introducing commits, and locates commits for downstream cherry-picking or reverting. It returns structured results for agent composition. Rebase, squash, fixup, and other history-rewriting operations are owned by git-commits, not this skill.
## Composition
`git-branches` delegates revert here (see `git-branches`'s `references/merging.md`), which is why this skill carries that operation rather than treating it as out of scope; it is general git knowledge, not drawn from the `history-inspection.md` research corpus. Cherry-pick is **not** this skill's: `git-commits` owns it, and this skill's job ends at locating the SHA to hand over. Server-side commit history on a Gitea-hosted repository belongs to `gitea-branches`; this skill reads the local working copy.
## Usage
```
/git-history
```
Describe your history task: search logs, bisect for a regression, or locate a specific commit. The skill will query history and return structured results.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/bisect.md` | Loaded when the entry procedure is bisect: manual and automated flows, exit codes, skip, replay, narrowing, custom terms |
| `references/git-log-format.md` | Loaded when a log or diff flag needs looking up: format placeholders, presets, diff-filter letters, `-L` syntax, ancestry filters, pickaxe binary-file behaviour, diff output-control flags |
| `references/sources.md` | Research sources and provenance |
| `references/README.md` | Index of the references directory |

4
plugins/git/skills/git-history/SKILL.md
View File

@@ -8,7 +8,7 @@ description: >
`git-commits`. Not a Gitea server's history -> `gitea-branches`. `git-commits`. Not a Gitea server's history -> `gitea-branches`.
metadata: metadata:
version: "1.0.1" version: "1.0.2"
category: git category: git
source_keys: source_keys:
- git-scm-bisect-docs - git-scm-bisect-docs
@@ -38,7 +38,7 @@ allowed-tools: Bash
Default to `rtk git log --oneline`, then narrow by whatever is known: Default to `rtk git log --oneline`, then narrow by whatever is known:
- **Content**: `rtk git log -S"string"`, or `-G"regex"` to match any diff line. `--pickaxe-regex` makes the `-S` argument a POSIX ERE; `--pickaxe-all` shows every file in a matching changeset. - **Content**: `rtk git log -S"string"`, or `-G"regex"` to match any diff line. `--pickaxe-regex` makes the `-S` argument a POSIX ERE; `--pickaxe-all` shows every file in a matching changeset.
- **A line or function**: `git log -L <start>,<end>:<file>` or `git log -L :<function>:<file>` — bare, not `rtk`: rtk truncates each diff line at ~72 characters (ADR-0023). Confirm the range resolves before reporting on it — an off-by-one silently omits the target. - **A line or function**: `git log -L <start>,<end>:<file>` or `git log -L :<function>:<file>` — bare, not `rtk`: rtk truncates each diff line at ~72 characters. Confirm the range resolves before reporting on it — an off-by-one silently omits the target.
- **A file across renames**: `rtk git log --follow -- <file>`. Without `--follow` the history stops at the rename boundary. - **A file across renames**: `rtk git log --follow -- <file>`. Without `--follow` the history stops at the rename boundary.
- **Mainline only**: `--first-parent` follows the integration branch and skips commits merged in from side branches. - **Mainline only**: `--first-parent` follows the integration branch and skips commits merged in from side branches.
- **Structured output**: `rtk git log --format="%h | %s | %an (%ar)"`. - **Structured output**: `rtk git log --format="%h | %s | %an (%ar)"`.

16
plugins/git/skills/git-history/references/README.md
View File

@@ -1,16 +0,0 @@
---
source_keys:
- git-scm-bisect-docs
- git-scm-log-docs
- git-scm-diff-docs
---
# References
This directory contains provenance metadata and research sources for the `git-history` skill.
## Files
- `sources.md` — Extracted research sources and their contributing documents
- `bisect.md` — The full `git bisect` procedure: manual and automated flows, exit-code semantics, skip and replay, narrowing options, and custom good/bad terms
- `git-log-format.md` — Full `git log` format placeholder catalogue, named format presets, `--diff-filter` letters, `-L` line-range syntax, ancestry filters, pickaxe binary-file behaviour, and `git diff` output-control flags

20
plugins/git/skills/git-history/references/git-log-format.md
View File

@@ -166,10 +166,10 @@ line at roughly 72 characters with an ellipsis, on the one query whose whole poi
is showing line content. is showing line content.
```bash ```bash
git log -L 10,20:file.txt # bare per ADR-0023 git log -L 10,20:file.txt # bare (ADR-0023)
git log -L /start_pattern/,/end_pattern/:file.txt # bare per ADR-0023 git log -L /start_pattern/,/end_pattern/:file.txt # bare (ADR-0023)
git log -L :myfunction:src/app.c # bare per ADR-0023 git log -L :myfunction:src/app.c # bare (ADR-0023)
git log -L /init/,+15:config.py # bare per ADR-0023; 15 lines after first /init/ match git log -L /init/,+15:config.py # bare (ADR-0023); 15 lines after first /init/ match
``` ```
Range formats: Range formats:
@@ -213,8 +213,8 @@ Bare `git`, not `rtk git`: rtk appends a blank line and a `Changes:` trailer, so
the output is no longer one record per line. the output is no longer one record per line.
```bash ```bash
git diff --name-only # bare per ADR-0023; only filenames, one per line git diff --name-only # bare (ADR-0023); only filenames, one per line
git diff --name-status # bare per ADR-0023; status letter + filename per line git diff --name-status # bare (ADR-0023); status letter + filename per line
``` ```
`--name-status` uses the same status letters as `--diff-filter`. `--name-status` uses the same status letters as `--diff-filter`.
@@ -225,10 +225,10 @@ Bare `git`, not `rtk git`: rtk replaces the word-diff with its own diffstat
renderer and emits none of the `[-removed-] {+added+}` markers. renderer and emits none of the `[-removed-] {+added+}` markers.
```bash ```bash
git diff --word-diff # bare per ADR-0023; inline word-level diff, [-removed-] {+added+} markers git diff --word-diff # bare (ADR-0023); inline word-level diff, [-removed-] {+added+} markers
git diff --word-diff=color # bare per ADR-0023; color only, no markers git diff --word-diff=color # bare (ADR-0023); color only, no markers
git diff --word-diff=porcelain # bare per ADR-0023; machine-readable: +/- prefixed lines, ~ for newlines git diff --word-diff=porcelain # bare (ADR-0023); machine-readable: +/- prefixed lines, ~ for newlines
git diff --word-diff-regex=<re> # bare per ADR-0023; define what counts as a "word" git diff --word-diff-regex=<re> # bare (ADR-0023); define what counts as a "word"
``` ```
### Whitespace Flags ### Whitespace Flags

34
plugins/git/skills/git-remotes/README.md
View File

@@ -1,34 +0,0 @@
# git-remotes
Manage git remote repositories — add/remove/configure remotes, push/pull with safety checks, fetch with pruning, and multi-remote workflows.
## What it does
This skill handles remote operations within the git workflow suite. It manages remote configuration (add, remove, rename), fetch operations with pruning, push operations with force-push safety (`--force-with-lease --force-if-includes`), and pull strategies (fast-forward, rebase, merge). It returns structured results suitable for agent composition.
## Usage
```
/git-remotes
```
Describe your remote operation: add a remote, push, pull, fetch, or configure tracking. The skill will handle the operation with appropriate safety checks and return results.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — force-push gate, dispatch table, return format |
| `references/README.md` | Describes the references directory contents |
| `references/remote-config.md` | Read when adding, removing, renaming, inspecting or re-pointing a remote, or configuring tracking, mirroring, or `set-url` |
| `references/fetch.md` | Read when fetching or pruning remote-tracking refs, or doing a shallow or partial fetch |
| `references/push.md` | Read when pushing branches or tags, writing refspecs, or force-pushing |
| `references/pull.md` | Read when integrating remote changes into the current branch, including the divergence rule |
| `references/sources.md` | Research sources and provenance |
## Composition
Callers that need submodule initialization after a `--recurse-submodules` pull hand off to
`git-submodules`; local-only work (commits, branches, history) belongs to `git-commits`,
`git-branches`, and `git-history`. The `git-workflow` skill routes humans here for any
remote-touching request.

2
plugins/git/skills/git-remotes/SKILL.md
View File

@@ -10,7 +10,7 @@ description: >
Not submodule pointers -> `git-submodules`. Not submodule pointers -> `git-submodules`.
metadata: metadata:
version: "1.0.1" version: "1.0.2"
category: git category: git
source_keys: source_keys:
- git-scm-remote-docs - git-scm-remote-docs

20
plugins/git/skills/git-remotes/references/README.md
View File

@@ -1,20 +0,0 @@
---
source_keys:
- git-scm-remote-docs
- git-scm-fetch-docs
- git-scm-push-docs
- git-scm-pull-docs
- context7-git-htmldocs
---
# References
This directory contains provenance metadata and research sources for the `git-remotes` skill.
## Files
- `sources.md` — Extracted research sources and their contributing documents
- `remote-config.md` — Remote add/remove/rename/inspect, tracking and mirror options, housekeeping, and the full `set-url` form
- `fetch.md` — Fetch and prune options, shallow and partial fetch, the default fetch refspec
- `push.md` — Push options, refspec syntax, force-push safety in full, server-side deny policies
- `pull.md` — Pull strategies, submodule caveat, the divergence rule, and pull config precedence

2
plugins/git/skills/git-remotes/references/push.md
View File

@@ -50,7 +50,7 @@ Two mitigations:
# poisoned by an unrelated fetch. # poisoned by an unrelated fetch.
# The inner `git config` is bare: its stdout becomes a remote URL, so any # The inner `git config` is bare: its stdout becomes a remote URL, so any
# output rewriting would poison the remote silently. # output rewriting would poison the remote silently.
rtk git remote add origin-push $(git config remote.origin.url) # inner bare per ADR-0023 rtk git remote add origin-push $(git config remote.origin.url) # inner bare (ADR-0023)
rtk git push --force-with-lease origin-push rtk git push --force-with-lease origin-push
# Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state # Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state

35
plugins/git/skills/git-submodules/README.md
View File

@@ -1,35 +0,0 @@
# git-submodules
Add, initialize, update, pin, inspect, and remove git submodules in multi-repository projects.
## What it does
This skill handles submodule operations within the git workflow suite: cloning a superproject with
its nested repositories, adding a dependency as a submodule, initializing and updating with
pinning or branch tracking, parallel and recursive traversal, rebinding URLs and tracked branches,
and the full removal sequence including the `.git/modules/` cleanup git leaves behind. It returns
structured results suitable for agent composition.
It sits alongside the other git skills rather than duplicating them: `git-worktrees` covers
multiple checkouts of a single repository, and `git-remotes` covers the superproject's own remotes.
## Usage
```
/git-submodules
```
Describe the submodule task. The skill applies the shared working rules, dispatches to the
reference for that task, and returns structured results (operation, status, per-submodule details,
conflicts, and a recovery `next_step` when applicable).
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — gotchas, shared working rules, and the task dispatch table |
| `references/README.md` | Describes contents of references/ |
| `references/setup-and-update.md` | Loaded when cloning a superproject, adding a submodule, initializing, updating, or re-pinning one, or running a command across all of them — includes the full `add` and `update` flag tables, the pinning workflows, and the `foreach` shell-variable table |
| `references/urls-and-config.md` | Loaded when changing where a submodule points or how it is configured — `.gitmodules` vs `.git/config` anatomy, both key tables, `sync`/`set-url`/`set-branch`, local mirror overrides, relative URLs, the custom-`update` security gate, and `absorbgitdirs` |
| `references/removal.md` | Loaded when removing or deinitializing a submodule — why `deinit` is not removal, and the four-step removal sequence |
| `references/sources.md` | Research sources and provenance |

31
plugins/git/skills/git-submodules/references/README.md
View File

@@ -1,31 +0,0 @@
---
source_keys:
- git-scm-submodule-docs
---
# References
One file per task branch in SKILL.md's dispatch table. Load only the one that matches the request.
## setup-and-update.md
Cloning a superproject that has submodules, adding a dependency as a submodule, initializing
without cloning, updating or re-pinning, and running one command across every submodule. Carries
the `add` and `update` flag tables, the keep-pinned and move-the-pin-forward workflows, and the
`foreach` shell-variable table (`$name`, `$sm_path`, `$displaypath`, `$sha1`, `$toplevel`).
## urls-and-config.md
Where a submodule points and how it is configured: the `.gitmodules` vs `.git/config` split, both
key tables, `sync` / `set-url` / `set-branch`, local mirror overrides, relative URL resolution, the
security gate on custom `update` commands, and `absorbgitdirs`.
## removal.md
Removing a submodule, and why `deinit` alone does not remove one. Carries the full four-step
removal sequence including the manual `.git/modules/<name>/` cleanup.
## sources.md
Research sources that informed this skill — provenance chain for git-scm-submodule-docs reference
material.

25
plugins/git/skills/git-workflow/README.md
View File

@@ -1,25 +0,0 @@
# git-workflow
Human-friendly interface for interactive git workflows with conversational prompts, progress guidance, and safety confirmations.
## What it does
This skill wraps the `git-orchestrate` agent to provide an interactive, educational interface for humans performing git workflows. It is the router for the six local-git domain skills — `git-commits`, `git-branches`, `git-history`, `git-remotes`, `git-submodules` and `git-worktrees` — and `SKILL.md` carries a table mapping each of them to the requests it owns, so an ambiguous request resolves to exactly one domain before anything runs. The skill parses user intent, gathers session context, invokes the orchestrator, and presents results in plain language with inline help, progress updates, and explanations of what's happening. It enforces confirmation gates for destructive operations (force-push, branch deletion, rebasing with history loss, force-checkout) and provides best-practices guidance throughout. The org's non-negotiable git rules live in `references/hard-rules.md` and are loaded only when a request could conflict with one.
## Usage
```
/git-workflow
```
Describe your git workflow: commit, create a branch, rebase, inspect history, manage submodules, switch worktrees, or manage remotes. The skill will prompt for any missing details and guide you through the workflow.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — the six-domain routing table, the workflow steps, and the interaction style |
| `README.md` | This file |
| `references/hard-rules.md` | The org's non-negotiable git rules; read when a request creates, amends, or rewrites a commit, pushes, or touches hooks, config, or credentials |
| `references/README.md` | Describes the references directory contents |
| `references/sources.md` | Research sources and provenance |

19
plugins/git/skills/git-workflow/references/README.md
View File

@@ -1,19 +0,0 @@
---
source_keys:
- nvie-gitflow-post
- atlassian-gitflow-tutorial
- gitflow-cheatsheet
- context7-git-htmldocs
- org-git-conventions
---
# References
This directory contains the org git rules and the provenance metadata for the `git-workflow`
skill.
## Files
- `hard-rules.md` — The org's non-negotiable git rules, loaded when a request creates, amends, or
rewrites a commit, pushes, or touches hooks, config, or credentials
- `sources.md` — Extracted research sources and their contributing documents

24
plugins/git/skills/git-worktrees/README.md
View File

@@ -1,24 +0,0 @@
# git-worktrees
Manage git worktrees to enable multi-branch parallel development across isolated directories.
## What it does
This skill handles worktree operations within the git workflow suite. It creates, lists, locks/unlocks, moves, removes, prunes, and repairs worktrees — letting an agent work on multiple branches simultaneously without stashing. It returns structured results (paths, branches, lock status) suitable for agent composition. For multi-step flows spanning branch strategy plus worktree setup, `git-workflow` handles the broader orchestration and delegates the worktree mechanics here.
## Usage
```
/git-worktrees
```
Describe your worktree task: create a worktree for a branch, list existing worktrees, lock one for removable media, move, remove, prune, or repair. The skill will handle the operation with appropriate safety checks and return results.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Dispatch table, per-operation gates, and the report format |
| `references/README.md` | Describes the references directory contents |
| `references/worktrees.md` | Read when an operation needs more than the dispatch table: shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout, removable-media locking, remote disambiguation, where to run `repair` from, config keys, and the emergency-fix and PR-review patterns |
| `references/sources.md` | Research sources and provenance |

6
plugins/git/skills/git-worktrees/SKILL.md
View File

@@ -8,7 +8,7 @@ description: >
Not interactive multi-step git guidance -> `git-workflow`. Not interactive multi-step git guidance -> `git-workflow`.
metadata: metadata:
version: "1.0.1" version: "1.0.2"
category: git category: git
source_keys: source_keys:
- git-scm-worktree-docs - git-scm-worktree-docs
@@ -32,7 +32,7 @@ metadata:
| Create a local branch tracking a remote one | `rtk git worktree add --track -b <branch> <path> <remote>/<branch>` — always correct. `git worktree add <path> <branch>` expands to exactly this, but **only** under the conditions in `references/worktrees.md` | | Create a local branch tracking a remote one | `rtk git worktree add --track -b <branch> <path> <remote>/<branch>` — always correct. `git worktree add <path> <branch>` expands to exactly this, but **only** under the conditions in `references/worktrees.md` |
| Throwaway experiment, no branch | `rtk git worktree add -d <path>` — detached HEAD | | Throwaway experiment, no branch | `rtk git worktree add -d <path>` — detached HEAD |
| **Never** `git worktree add <path> <remote>/<branch>` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above | | **Never** `git worktree add <path> <remote>/<branch>` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above |
| List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare per ADR-0023: rtk re-renders the output and drops the porcelain flags | | List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare (ADR-0023): rtk re-renders the output and drops the porcelain flags |
| Lock or unlock | `rtk git worktree lock [--reason <str>] <path>` / `rtk git worktree unlock <path>` | | Lock or unlock | `rtk git worktree lock [--reason <str>] <path>` / `rtk git worktree unlock <path>` |
| Move | `rtk git worktree move <from> <to>` | | Move | `rtk git worktree move <from> <to>` |
| Remove | `rtk git worktree remove <path>` | | Remove | `rtk git worktree remove <path>` |
@@ -63,6 +63,6 @@ worktrees:
``` ```
Derive those fields from `git worktree list --porcelain -z` — bare, not `rtk`: Derive those fields from `git worktree list --porcelain -z` — bare, not `rtk`:
rtk drops both flags and never emits `locked`/`lock_reason` (ADR-0023). For a single rtk drops both flags and never emits `locked`/`lock_reason`. For a single
operation, report its outcome instead — `created: true`, `moved: true`, operation, report its outcome instead — `created: true`, `moved: true`,
`removed: true`. `removed: true`.

13
plugins/git/skills/git-worktrees/references/README.md
View File

@@ -1,13 +0,0 @@
---
source_keys:
- git-scm-worktree-docs
---
# References
This directory contains provenance metadata and research sources for the `git-worktrees` skill.
## Files
- `sources.md` — Extracted research sources and their contributing documents
- `worktrees.md` — Shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout setup, removable-media locking, remote-branch disambiguation, where to run `repair` from, the config key reference, and the emergency-fix and PR-review workflow patterns

26
plugins/git/skills/pc-author/README.md
View File

@@ -1,26 +0,0 @@
# pc-author
Create, add, remove, update, and configure `.pre-commit-config.yaml`.
## What it does
Manages the pre-commit configuration file in any git repo. When invoked, it scans the repo for languages, proposes appropriate hooks with rationale, and writes or modifies `.pre-commit-config.yaml`. It validates every write with `pre-commit validate-config` and flags stale revision pins. It does not run hooks or install them into `.git/hooks/` — use `pc-run` for that.
## Usage
```
/pc-author
```
Invoke with no arguments. The skill determines from context whether to create a new config or modify an existing one.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/create-config.md` | Loaded when the repo has no `.pre-commit-config.yaml` — the create-from-scratch flow |
| `references/modify-config.md` | Loaded when a `.pre-commit-config.yaml` already exists — add, remove, top-level keys, rev staleness |
| `references/hooks-by-language.md` | Hook recommendations by detected language/extension |
| `references/README.md` | Index of files in references/ |
| `references/sources.md` | Provenance — research sources that informed this skill |

16
plugins/git/skills/pc-author/references/README.md
View File

@@ -1,16 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
- context7-pre-commit-hooks
- pre-commit-hooks-github
---
# references/
| File | Purpose |
|---|---|
| `create-config.md` | The create flow — read when the repo has no `.pre-commit-config.yaml` |
| `modify-config.md` | The modify flow — read when a `.pre-commit-config.yaml` already exists |
| `hooks-by-language.md` | Hook recommendations by language/context — repo, rev, and rationale for adding hooks |
| `sources.md` | Provenance: research sources that informed this skill |

32
plugins/git/skills/pc-run/README.md
View File

@@ -1,32 +0,0 @@
# pc-run
Runs, installs, updates, and maintains pre-commit hooks in a local git clone.
## What it does
`pc-run` handles everything that happens *after* `.pre-commit-config.yaml` exists: wiring hooks into git, running them, bumping their versions, and maintaining the cache. When hooks fail, it identifies the cause and suggests a concrete fix — it does not auto-fix files or edit the config. For creating or editing `.pre-commit-config.yaml`, use `pc-author` instead.
## Before you start
- `pre-commit` must be installed and available on `PATH`
- A `.pre-commit-config.yaml` must exist at the repo root (use `pc-author` to create one)
## Usage
Common invocations:
- `/pc-run` — run all hooks against all files (default)
- `/pc-run install` — wire hooks into `.git/hooks/`
- `/pc-run autoupdate` — bump all `rev` values to latest
- `/pc-run clean` — wipe the pre-commit cache (requires confirmation)
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/install.md` | The install flow — loaded when the user asks to install or set up hooks |
| `references/autoupdate.md` | The autoupdate flow — loaded when the user asks to bump hook revs |
| `references/clean.md` | The clean flow — loaded when the user asks to wipe the cache or rebuild environments |
| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when a hook fails or never fires |
| `references/sources.md` | Provenance: research sources that informed this skill |
| `references/README.md` | Directory index for references/ |

17
plugins/git/skills/pc-run/references/README.md
View File

@@ -1,17 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
- context7-pre-commit-hooks
- pre-commit-hooks-github
---
# references/
| File | Purpose |
|---|---|
| `install.md` | The install flow — read when the user asks to install or set up hooks |
| `autoupdate.md` | The autoupdate flow — read when the user asks to bump hook revs |
| `clean.md` | The clean flow — read when the user asks to wipe the cache or rebuild environments |
| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — read when a hook fails or never fires |
| `sources.md` | Provenance: research sources that informed this skill |

50
plugins/gitea/.apm/skills/gitea-branches/README.md
View File

@@ -1,50 +0,0 @@
# gitea-branches
Manage Gitea repository branches and inspect commit history via the Gitea MCP server.
## What it does
This skill handles branch lifecycle operations (list, create, rename, delete) and read-only commit
history (list commits, get a single commit's full detail) against a Gitea repository. It resolves
`owner`/`repo` from the git remote, dispatches to the right MCP tool, and applies safety and
pagination conventions specific to Gitea's API (e.g. refusing to delete a protected branch without
explicit confirmation, and treating unexpected 404s as possible masked 403s).
## Boundaries
This skill operates on the Gitea server via the MCP tools, never on your local checkout. Branch
and commit-history work against the working copy belongs to `git-branches` and `git-history`.
Branch references that only exist relative to a pull request — a PR's head or base branch, and
cross-repo fork PR heads in particular — belong to `gitea-prs`; `list_branches` cannot see a fork's
head at all.
The skill triggers on phrasings like "list branches", "create a branch", "rename a branch", "delete a branch",
"what commits are on this branch", "show commit <sha>", and "what changed in that commit", even
when the user does not say "Gitea", as long as the repo's remote is a Gitea instance.
## Before you start
Requires a Gitea MCP server configured with a token that has `write:repository` scope. This is
confirmed for `list_branches`, `create_branch`, and `delete_branch` (and inferred for
`rename_branch`) (Gitea gates reads behind write
scope for repo-scoped operations); `list_commits` and `get_commit` are inferred to need the same
scope by analogy, not explicitly confirmed — see `references/commits.md`. Requires a git remote
named `origin` pointing at the Gitea instance.
## Usage
```text
/gitea-branches
```
Describe your task: list/create/rename/delete a branch, or list/inspect commits. See `SKILL.md`'s
dispatch table for the full set of recognized invocations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — dispatch table, gotchas |
| `references/branches.md` | Verified call signatures and mechanics for list/create/rename/delete branch |
| `references/commits.md` | Verified call signatures and mechanics for list/get commit |
| `references/sources.md` | Research sources backing the branch/commit guidance |

24
plugins/gitea/.apm/skills/gitea-files/README.md
View File

@@ -1,24 +0,0 @@
# gitea-files
Read and write individual files and directory/repository trees in a Gitea repository via the Gitea MCP server.
## What it does
This skill handles file-domain operations within the Gitea integration suite: reading a single file's contents, listing one directory level, walking a full repository tree (optionally recursive), creating or updating a file, and deleting a file. It owns the SHA-based optimistic-concurrency pattern that Gitea requires for file writes — the domain's sharpest gotcha — and defers branch creation, commit history, and pull request mechanics to `gitea-branches` and `gitea-prs`.
## Usage
```text
/gitea-files
```
Describe the file task: read a file or directory, walk a tree, create/update a file, or delete a file. Provide `owner`/`repo`/branch (or ask the user if not given) — this skill does not resolve them from a git remote itself.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/reading.md` | Loaded for the read flow: the three read tools, `ref`/`tree_sha` selection, tree pagination, and why a listing is not a SHA source |
| `references/writing.md` | Loaded for the write flow: the SHA-first create/update/delete sequences, `new_branch_name`, the worked branch + file + PR sequence, and failed-write triage |
| `references/sources.md` | Research sources backing the SHA/concurrency and direct-commit-vs-PR guidance |

51
plugins/gitea/.apm/skills/gitea-issues/README.md
View File

@@ -1,51 +0,0 @@
# gitea-issues
Read and write Gitea issues — list, get, create, comment, close, and search — via the Gitea MCP server.
## What it does
This skill handles the issue lifecycle (`list_issues`, `issue_read`, `issue_write`, `search_issues`):
listing repo issues, reading a single issue's details/comments/labels, creating an issue, updating
its state, adding/editing comments, applying labels, and searching issues/PRs across repositories.
The create flow closes out four enrichments deferred from issue #6 comment #848: label inference
and milestone assignment (both by composing `gitea-labels-milestones`), an assignee workaround for
the blocked `get_me` scope, and the "Depends on #N" dependency-linking convention. It supersedes the
`issue`/`issue <N>`/`issue close <N>`/`issue comment <N>` dispatch this plugin's old single flat
Gitea skill carried, retired when the plugin was split into per-domain deep modules.
## Before you start
Requires a Gitea MCP server configured with a token holding `write:issue` + `write:repository`.
Requires a git remote named `origin` pointing at the Gitea instance, unless an orchestrating caller
(e.g. `gitea-workflow`) already resolved `owner`/`repo` for you.
## How it composes
This skill composes `gitea-labels-milestones` for *all* label inference, label-name-to-ID
resolution, and milestone lookup, rather than duplicating that taxonomy or its resolution logic —
see `references/enrichments.md` for the call protocol. Managing the label and milestone definitions
themselves (create/edit/delete a label, create/close a milestone) is out of scope here and goes to
`gitea-labels-milestones` directly.
One boundary the description does not spend characters on, because it was never going to win an
issue request: local git branch or commit work belongs to `gitea-branches` (Gitea-side) or
`git-branches` (working copy).
## Usage
```text
/gitea-issues
```
Describe your task: list issues, create one, get/comment/close/label a specific issue number, or
search across repos. See `SKILL.md`'s dispatch table for the full set of recognized invocations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — dispatch table, Gotchas |
| `references/issues.md` | Verified call signatures and mechanics for `list_issues`/`issue_read`/`issue_write` |
| `references/search.md` | Verified call signature and mechanics for `search_issues` |
| `references/enrichments.md` | Create-flow enrichments — label inference, milestone assignment, assignee workaround, dependency-linking convention |
| `references/sources.md` | Research sources backing the issue guidance |

31
plugins/gitea/.apm/skills/gitea-labels-milestones/README.md
View File

@@ -1,31 +0,0 @@
# gitea-labels-milestones
Read and write Gitea labels and milestones, and resolve label/milestone identity for the skills that apply them to issues and PRs.
## What it does
This skill handles label and milestone CRUD (`label_read`/`label_write`, `milestone_read`/`milestone_write`) — listing repo or org labels, creating/editing/deleting a label, resolving a label name to the numeric ID required to apply it to an issue or PR, and listing/creating/updating/closing/deleting a milestone. It also owns label inference: mapping conversation context (bug report, feature request, urgency language) to this repo's `Kind/*`/`Priority/*`/`Status/*` taxonomy.
## Composition
This is a cross-cutting shared skill. `gitea-issues` and `gitea-prs` both compose it whenever they need to apply a label or assign a milestone, rather than duplicating label/milestone logic: they call in for name/title → ID resolution, then their own `issue_write`/`pull_request_write` calls apply the resolved IDs. The split is deliberate — identity resolution lives here once, and the write that attaches an ID to a specific issue or PR lives with the skill that owns that object.
That relationship is documented here rather than in the skill description, which is preloaded into every session and carries routing information only: an agent reaches this skill because the user asked about labels or milestones, not because two other skills call it.
## Usage
```text
/gitea-labels-milestones
```
Describe the label or milestone task: list labels, resolve a name to an ID, create/edit/delete a label, or list/create/update/close/delete a milestone. For applying already-resolved labels or a milestone to a specific issue or PR, use `gitea-issues` or `gitea-prs` instead.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — dispatch table and Gotchas |
| `references/labels.md` | Execution detail for `label_read`/`label_write` |
| `references/milestones.md` | Execution detail for `milestone_read`/`milestone_write` |
| `references/label-inference.md` | Context-pattern → `Kind/*`/`Priority/*`/`Status/*` label inference guide |
| `references/sources.md` | Research sources backing the label/milestone guidance |

31
plugins/gitea/.apm/skills/gitea-prs/README.md
View File

@@ -1,31 +0,0 @@
# gitea-prs
List, read, create, update, merge, and review Gitea pull requests.
## What it does
This skill handles the pull request lifecycle within the Gitea integration suite — listing and reading PRs (details, diff, changed files, CI status, reviews), creating them (title, body, labels), updating them (title, body, assignees, labels, milestone), adding and removing reviewers, closing/reopening, merging with a chosen strategy and post-merge branch cleanup, and the full code-review flow (create a review with inline comments, submit it, dismiss or delete it, reply to a review comment, and resolve or unresolve a comment thread). It composes `gitea-labels-milestones` for label/milestone ID resolution rather than duplicating that logic — `milestone` applies on an update only, never on create — and defers to `gitea-issues` for anything that turns out to be an issue rather than a PR (they share one number space) and to `gitea-branches`/`gitea-files` for the underlying branch/file operations behind a PR.
## Usage
```text
/gitea-prs
```
Describe the PR or review task: list PRs, get a PR's status/diff/reviews, create or update a PR, merge one, or create/submit/dismiss a code review. The skill resolves `owner`/`repo` from the `origin` git remote (or takes them from an orchestrating caller) and resolves any label or milestone names via `gitea-labels-milestones` before writing them.
## Before you start
Requires a Gitea MCP server configured with a token holding `write:issue` + `write:repository`.
Requires a git remote named `origin` pointing at the Gitea instance, unless an orchestrating caller
(e.g. `gitea-workflow`) already resolved `owner`/`repo` for you.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — Gotchas, the dispatch table, and label/milestone ID resolution via `gitea-labels-milestones` |
| `references/pull-requests.md` | Execution detail for `list_pull_requests`, `pull_request_read` (get/get_diff/get_files/get_status), and `pull_request_write` (create/update/close/reopen/update_branch/add_reviewers/remove_reviewers) |
| `references/reviews.md` | Execution detail for `pull_request_review_write` (create/submit/delete/dismiss, plus the comment-thread methods reply_comment/resolve_thread/unresolve_thread) and the review-related `pull_request_read` methods |
| `references/merging.md` | The merge workflow — CI vs. review/branch-protection gates, merge styles, branch cleanup, and the post-merge issue-close check |
| `references/sources.md` | Research sources backing the PR/review guidance |

30
plugins/gitea/.apm/skills/gitea-releases/README.md
View File

@@ -1,30 +0,0 @@
# gitea-releases
Manage Gitea releases and tags — list, create, and delete releases (with draft/prerelease flags and notes) and their underlying tags.
## What it does
This skill handles release and tag operations for a Gitea repository. It creates releases from a tag/target commitish with title, notes, and draft/prerelease flags; lists and paginates releases and tags; retrieves the latest release; and deletes releases and tags as separate, independent destructive operations. It resolves the numeric release id required for deletion instead of assuming a tag name will work.
## Before you start
Requires a Gitea MCP server configured with a token holding `write:repository`. Requires a git remote
named `origin` pointing at the Gitea instance, unless an orchestrating caller already resolved
`owner`/`repo` for you.
## Usage
```text
/gitea-releases
```
Describe your release/tag task: list releases, get the latest release, create a release (with a tag, target, and title), or delete a release or tag. The skill handles resolving the numeric release id where required and keeps release/tag deletion as distinct operations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/call-signatures.md` | Tool parameters and response shapes derived from gitea-mcp source (see `references/sources.md`); input params for all nine tools additionally cross-checked live against gitea-mcp v1.7.0 |
| `references/conventions.md` | Semver/draft/prerelease practitioner conventions and pagination behavior |
| `references/sources.md` | Research sources backing the call signatures and conventions |

25
plugins/gitea/.apm/skills/gitea-workflow/README.md
View File

@@ -1,25 +0,0 @@
# gitea-workflow
Human-facing entry point and router for the Gitea integration.
## What it does
This skill is the conversational front door to the Gitea suite — it replaces the old flat `/gitea` skill. On its own it never calls a Gitea MCP tool; it composes the six domain skills (`gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-branches`, `gitea-files`, `gitea-releases`). It handles the no-args status check-in (open issues + open PRs), which preserves the original flat `/gitea` skill's default behavior; resolves ambiguous issue-or-PR numbers before dispatching (issues and PRs share one number space); and points a user or agent to the right domain skill when it's unclear which one applies.
## Usage
```text
/gitea-workflow
```
Invoke with no arguments for a status check-in, with a bare number to resolve and show issue or PR detail, or with a general request to be routed to the right domain skill.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — Gotchas, the dispatch table keyed on invocation shape, and the common report gate every branch ends in — each branch's own format lives with its reference file |
| `references/status-checkin.md` | Loaded when the skill is invoked with no specific request — the two parallel open-issue/open-PR reads and the two-section report |
| `references/number-resolution.md` | Loaded when the request carries a bare number that says neither "issue" nor "PR" — the `is_pull` resolution call and the hidden-permission-error 404 |
| `references/skill-index.md` | Loaded when the request names a capability but not which skill owns it — the six-skill routing index |
| `references/sources.md` | Research sources backing the routing/status guidance |

50
plugins/gitea/skills/gitea-branches/README.md
View File

@@ -1,50 +0,0 @@
# gitea-branches
Manage Gitea repository branches and inspect commit history via the Gitea MCP server.
## What it does
This skill handles branch lifecycle operations (list, create, rename, delete) and read-only commit
history (list commits, get a single commit's full detail) against a Gitea repository. It resolves
`owner`/`repo` from the git remote, dispatches to the right MCP tool, and applies safety and
pagination conventions specific to Gitea's API (e.g. refusing to delete a protected branch without
explicit confirmation, and treating unexpected 404s as possible masked 403s).
## Boundaries
This skill operates on the Gitea server via the MCP tools, never on your local checkout. Branch
and commit-history work against the working copy belongs to `git-branches` and `git-history`.
Branch references that only exist relative to a pull request — a PR's head or base branch, and
cross-repo fork PR heads in particular — belong to `gitea-prs`; `list_branches` cannot see a fork's
head at all.
The skill triggers on phrasings like "list branches", "create a branch", "rename a branch", "delete a branch",
"what commits are on this branch", "show commit <sha>", and "what changed in that commit", even
when the user does not say "Gitea", as long as the repo's remote is a Gitea instance.
## Before you start
Requires a Gitea MCP server configured with a token that has `write:repository` scope. This is
confirmed for `list_branches`, `create_branch`, and `delete_branch` (and inferred for
`rename_branch`) (Gitea gates reads behind write
scope for repo-scoped operations); `list_commits` and `get_commit` are inferred to need the same
scope by analogy, not explicitly confirmed — see `references/commits.md`. Requires a git remote
named `origin` pointing at the Gitea instance.
## Usage
```text
/gitea-branches
```
Describe your task: list/create/rename/delete a branch, or list/inspect commits. See `SKILL.md`'s
dispatch table for the full set of recognized invocations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — dispatch table, gotchas |
| `references/branches.md` | Verified call signatures and mechanics for list/create/rename/delete branch |
| `references/commits.md` | Verified call signatures and mechanics for list/get commit |
| `references/sources.md` | Research sources backing the branch/commit guidance |

24
plugins/gitea/skills/gitea-files/README.md
View File

@@ -1,24 +0,0 @@
# gitea-files
Read and write individual files and directory/repository trees in a Gitea repository via the Gitea MCP server.
## What it does
This skill handles file-domain operations within the Gitea integration suite: reading a single file's contents, listing one directory level, walking a full repository tree (optionally recursive), creating or updating a file, and deleting a file. It owns the SHA-based optimistic-concurrency pattern that Gitea requires for file writes — the domain's sharpest gotcha — and defers branch creation, commit history, and pull request mechanics to `gitea-branches` and `gitea-prs`.
## Usage
```text
/gitea-files
```
Describe the file task: read a file or directory, walk a tree, create/update a file, or delete a file. Provide `owner`/`repo`/branch (or ask the user if not given) — this skill does not resolve them from a git remote itself.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/reading.md` | Loaded for the read flow: the three read tools, `ref`/`tree_sha` selection, tree pagination, and why a listing is not a SHA source |
| `references/writing.md` | Loaded for the write flow: the SHA-first create/update/delete sequences, `new_branch_name`, the worked branch + file + PR sequence, and failed-write triage |
| `references/sources.md` | Research sources backing the SHA/concurrency and direct-commit-vs-PR guidance |

51
plugins/gitea/skills/gitea-issues/README.md
View File

@@ -1,51 +0,0 @@
# gitea-issues
Read and write Gitea issues — list, get, create, comment, close, and search — via the Gitea MCP server.
## What it does
This skill handles the issue lifecycle (`list_issues`, `issue_read`, `issue_write`, `search_issues`):
listing repo issues, reading a single issue's details/comments/labels, creating an issue, updating
its state, adding/editing comments, applying labels, and searching issues/PRs across repositories.
The create flow closes out four enrichments deferred from issue #6 comment #848: label inference
and milestone assignment (both by composing `gitea-labels-milestones`), an assignee workaround for
the blocked `get_me` scope, and the "Depends on #N" dependency-linking convention. It supersedes the
`issue`/`issue <N>`/`issue close <N>`/`issue comment <N>` dispatch this plugin's old single flat
Gitea skill carried, retired when the plugin was split into per-domain deep modules.
## Before you start
Requires a Gitea MCP server configured with a token holding `write:issue` + `write:repository`.
Requires a git remote named `origin` pointing at the Gitea instance, unless an orchestrating caller
(e.g. `gitea-workflow`) already resolved `owner`/`repo` for you.
## How it composes
This skill composes `gitea-labels-milestones` for *all* label inference, label-name-to-ID
resolution, and milestone lookup, rather than duplicating that taxonomy or its resolution logic —
see `references/enrichments.md` for the call protocol. Managing the label and milestone definitions
themselves (create/edit/delete a label, create/close a milestone) is out of scope here and goes to
`gitea-labels-milestones` directly.
One boundary the description does not spend characters on, because it was never going to win an
issue request: local git branch or commit work belongs to `gitea-branches` (Gitea-side) or
`git-branches` (working copy).
## Usage
```text
/gitea-issues
```
Describe your task: list issues, create one, get/comment/close/label a specific issue number, or
search across repos. See `SKILL.md`'s dispatch table for the full set of recognized invocations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — dispatch table, Gotchas |
| `references/issues.md` | Verified call signatures and mechanics for `list_issues`/`issue_read`/`issue_write` |
| `references/search.md` | Verified call signature and mechanics for `search_issues` |
| `references/enrichments.md` | Create-flow enrichments — label inference, milestone assignment, assignee workaround, dependency-linking convention |
| `references/sources.md` | Research sources backing the issue guidance |

31
plugins/gitea/skills/gitea-labels-milestones/README.md
View File

@@ -1,31 +0,0 @@
# gitea-labels-milestones
Read and write Gitea labels and milestones, and resolve label/milestone identity for the skills that apply them to issues and PRs.
## What it does
This skill handles label and milestone CRUD (`label_read`/`label_write`, `milestone_read`/`milestone_write`) — listing repo or org labels, creating/editing/deleting a label, resolving a label name to the numeric ID required to apply it to an issue or PR, and listing/creating/updating/closing/deleting a milestone. It also owns label inference: mapping conversation context (bug report, feature request, urgency language) to this repo's `Kind/*`/`Priority/*`/`Status/*` taxonomy.
## Composition
This is a cross-cutting shared skill. `gitea-issues` and `gitea-prs` both compose it whenever they need to apply a label or assign a milestone, rather than duplicating label/milestone logic: they call in for name/title → ID resolution, then their own `issue_write`/`pull_request_write` calls apply the resolved IDs. The split is deliberate — identity resolution lives here once, and the write that attaches an ID to a specific issue or PR lives with the skill that owns that object.
That relationship is documented here rather than in the skill description, which is preloaded into every session and carries routing information only: an agent reaches this skill because the user asked about labels or milestones, not because two other skills call it.
## Usage
```text
/gitea-labels-milestones
```
Describe the label or milestone task: list labels, resolve a name to an ID, create/edit/delete a label, or list/create/update/close/delete a milestone. For applying already-resolved labels or a milestone to a specific issue or PR, use `gitea-issues` or `gitea-prs` instead.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — dispatch table and Gotchas |
| `references/labels.md` | Execution detail for `label_read`/`label_write` |
| `references/milestones.md` | Execution detail for `milestone_read`/`milestone_write` |
| `references/label-inference.md` | Context-pattern → `Kind/*`/`Priority/*`/`Status/*` label inference guide |
| `references/sources.md` | Research sources backing the label/milestone guidance |

31
plugins/gitea/skills/gitea-prs/README.md
View File

@@ -1,31 +0,0 @@
# gitea-prs
List, read, create, update, merge, and review Gitea pull requests.
## What it does
This skill handles the pull request lifecycle within the Gitea integration suite — listing and reading PRs (details, diff, changed files, CI status, reviews), creating them (title, body, labels), updating them (title, body, assignees, labels, milestone), adding and removing reviewers, closing/reopening, merging with a chosen strategy and post-merge branch cleanup, and the full code-review flow (create a review with inline comments, submit it, dismiss or delete it, reply to a review comment, and resolve or unresolve a comment thread). It composes `gitea-labels-milestones` for label/milestone ID resolution rather than duplicating that logic — `milestone` applies on an update only, never on create — and defers to `gitea-issues` for anything that turns out to be an issue rather than a PR (they share one number space) and to `gitea-branches`/`gitea-files` for the underlying branch/file operations behind a PR.
## Usage
```text
/gitea-prs
```
Describe the PR or review task: list PRs, get a PR's status/diff/reviews, create or update a PR, merge one, or create/submit/dismiss a code review. The skill resolves `owner`/`repo` from the `origin` git remote (or takes them from an orchestrating caller) and resolves any label or milestone names via `gitea-labels-milestones` before writing them.
## Before you start
Requires a Gitea MCP server configured with a token holding `write:issue` + `write:repository`.
Requires a git remote named `origin` pointing at the Gitea instance, unless an orchestrating caller
(e.g. `gitea-workflow`) already resolved `owner`/`repo` for you.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — Gotchas, the dispatch table, and label/milestone ID resolution via `gitea-labels-milestones` |
| `references/pull-requests.md` | Execution detail for `list_pull_requests`, `pull_request_read` (get/get_diff/get_files/get_status), and `pull_request_write` (create/update/close/reopen/update_branch/add_reviewers/remove_reviewers) |
| `references/reviews.md` | Execution detail for `pull_request_review_write` (create/submit/delete/dismiss, plus the comment-thread methods reply_comment/resolve_thread/unresolve_thread) and the review-related `pull_request_read` methods |
| `references/merging.md` | The merge workflow — CI vs. review/branch-protection gates, merge styles, branch cleanup, and the post-merge issue-close check |
| `references/sources.md` | Research sources backing the PR/review guidance |

30
plugins/gitea/skills/gitea-releases/README.md
View File

@@ -1,30 +0,0 @@
# gitea-releases
Manage Gitea releases and tags — list, create, and delete releases (with draft/prerelease flags and notes) and their underlying tags.
## What it does
This skill handles release and tag operations for a Gitea repository. It creates releases from a tag/target commitish with title, notes, and draft/prerelease flags; lists and paginates releases and tags; retrieves the latest release; and deletes releases and tags as separate, independent destructive operations. It resolves the numeric release id required for deletion instead of assuming a tag name will work.
## Before you start
Requires a Gitea MCP server configured with a token holding `write:repository`. Requires a git remote
named `origin` pointing at the Gitea instance, unless an orchestrating caller already resolved
`owner`/`repo` for you.
## Usage
```text
/gitea-releases
```
Describe your release/tag task: list releases, get the latest release, create a release (with a tag, target, and title), or delete a release or tag. The skill handles resolving the numeric release id where required and keeps release/tag deletion as distinct operations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/call-signatures.md` | Tool parameters and response shapes derived from gitea-mcp source (see `references/sources.md`); input params for all nine tools additionally cross-checked live against gitea-mcp v1.7.0 |
| `references/conventions.md` | Semver/draft/prerelease practitioner conventions and pagination behavior |
| `references/sources.md` | Research sources backing the call signatures and conventions |

25
plugins/gitea/skills/gitea-workflow/README.md
View File

@@ -1,25 +0,0 @@
# gitea-workflow
Human-facing entry point and router for the Gitea integration.
## What it does
This skill is the conversational front door to the Gitea suite — it replaces the old flat `/gitea` skill. On its own it never calls a Gitea MCP tool; it composes the six domain skills (`gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-branches`, `gitea-files`, `gitea-releases`). It handles the no-args status check-in (open issues + open PRs), which preserves the original flat `/gitea` skill's default behavior; resolves ambiguous issue-or-PR numbers before dispatching (issues and PRs share one number space); and points a user or agent to the right domain skill when it's unclear which one applies.
## Usage
```text
/gitea-workflow
```
Invoke with no arguments for a status check-in, with a bare number to resolve and show issue or PR detail, or with a general request to be routed to the right domain skill.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — Gotchas, the dispatch table keyed on invocation shape, and the common report gate every branch ends in — each branch's own format lives with its reference file |
| `references/status-checkin.md` | Loaded when the skill is invoked with no specific request — the two parallel open-issue/open-PR reads and the two-section report |
| `references/number-resolution.md` | Loaded when the request carries a bare number that says neither "issue" nor "PR" — the `is_pull` resolution call and the hidden-permission-error 404 |
| `references/skill-index.md` | Loaded when the request names a capability but not which skill owns it — the six-skill routing index |
| `references/sources.md` | Research sources backing the routing/status guidance |

79
plugins/kyberforge/.apm/skills/agent-audit/README.md
View File

@@ -1,79 +0,0 @@
# agent-audit
Audits an agent definition for correctness and quality against the Claude Code and Copilot agent
references and the house context-budget contract (ADR-0020) — a single vendor-neutral file at
plugin/APM scope, or a Claude Code and Copilot file pair at project/user scope.
## What it does
1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance
checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags
non-imperative description openers, composition and architecture notes, vague wording, padding
phrases, "There is/are" sentence openers, and CC-specific "Use proactively" phrasing in a
Copilot or vendor-neutral description
2. Reads the agent file, and its counterpart when one exists, then loads the contract for its scope
3. Applies qualitative checks across description, body, delegation and comment discipline, loading
one rubric from `references/` per group
4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix —
and a result block with handoff to `agent-author`
Two things follow from ADR-0020 and are easy to get backwards. Agents take the **same** description
gates a skill takes — 250 characters SUGGESTION, 400 FAIL, since a `name` + `description` is
preloaded into every session either way — and **no body word gate at all**, because an agent body
becomes the system prompt of a fresh context rather than competing with the caller's live
conversation. Body length is judged through the delegation check instead: an agent body that
restates a procedure owned by a skill it can invoke is a FAIL, because a plugin-scope agent has no
sibling `references/` directory to disclose to and can only delegate.
At **plugin/APM scope** the audit accepts the single `.apm/agents/<name>.agent.md` file — there is
no counterpart, and pair consistency does not apply. `validate.sh` hard-`FAIL`s any frontmatter
field outside the vendor-neutral allowlist, since `apm compile` copies frontmatter verbatim to both
harnesses and an unsafe field cannot be silently dropped for just one of them. The allowlist lives
in the `apm-agent-allowlist` section of `references/field-inventory.md`, is read from there as data
by the script, and is deliberately not restated anywhere else in this skill (ADR-0009).
At **project/user scope** the audit accepts either file in a CC `.md` / Copilot `.agent.md` pair,
derives the counterpart automatically, and validates both, including the field-leakage checks in
each direction.
## Usage
```
/agent-audit
```
Pass the path to either agent file as the argument.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `assets/vale/.vale.ini` | Vale config: scopes `Kyberforge` to `**/agents/*.md`, `Kyberforge`+`KyberforgeCopilot` to `**/*.agent.md` |
| `assets/vale/styles/Kyberforge/CompositionNote.yml` | Flags composition and architecture notes in a description ("cross-cutting", "entry point", "composes", "rather than duplicating") that belong in README.md |
| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Flags descriptions opening with "This..." instead of an imperative "Use when..." |
| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Flags generic "see references/ for info" pointers instead of specific file references |
| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Flags sentences opening with "There is/are" instead of naming the subject directly |
| `assets/vale/styles/Kyberforge/VagueWording.yml` | Flags vague capability wording ("helps with", "utilize", "assists with", "used for") in descriptions |
| `assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml` | Flags CC-specific "Use proactively" phrasing with no effect in Copilot descriptions |
| `references/README.md` | Directory documentation for references/ |
| `references/finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading |
| `references/description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions |
| `references/body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for |
| `references/scope-plugin-apm.md` | Scope contract for a single vendor-neutral APM agent file — allowlist, dimension routing, and the dimensions that do not apply |
| `references/scope-project-user.md` | Scope contract for a CC / Copilot pair — counterpart derivation, provider field rules, pair consistency |
| `references/validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, known script failures |
| `references/field-inventory.md` | Authoritative field lists read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM-scope allowlist |
| `references/sources.md` | Research provenance for skill content |
| `scripts/README.md` | Directory documentation for scripts/ |
| `scripts/validate.sh` | Structural validator — required fields, name format, placeholder detection, the ADR-0020 description budget, and the field rules for the detected scope |
| `scripts/validate-provenance.sh` | Provenance chain validation against `sources.md` at the package root (plugin/APM scope only) |
| `scripts/vale-wrap.sh` | Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation |
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
| `tests/validate.bats` | (source-only) Bats tests for validate.sh |
| `tests/validate-provenance.bats` | (source-only) Bats tests for validate-provenance.sh |
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-audit/`) but are
not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

4
plugins/kyberforge/.apm/skills/agent-audit/SKILL.md
View File

@@ -7,7 +7,7 @@ description: >
directory -> skill-audit. directory -> skill-audit.
allowed-tools: Bash Read allowed-tools: Bash Read
metadata: metadata:
version: "1.0.1" version: "1.0.2"
category: factory category: factory
source_keys: source_keys:
- context7-websites-code-claude - context7-websites-code-claude
@@ -34,7 +34,7 @@ bash scripts/validate-provenance.sh <agent-file>
bash scripts/vale-wrap.sh <agent-file> [<counterpart-file>] bash scripts/vale-wrap.sh <agent-file> [<counterpart-file>]
``` ```
`validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the ADR-0020 description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes. `validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes.
If a validation script fails or cannot run — Bash denied, `python3` or `vale` absent, `references/field-inventory.md` missing — read `references/validation-scripts.md`; what these scripts measure is not reproducible by reading. If a validation script fails or cannot run — Bash denied, `python3` or `vale` absent, `references/field-inventory.md` missing — read `references/validation-scripts.md`; what these scripts measure is not reproducible by reading.

20
plugins/kyberforge/.apm/skills/agent-audit/references/README.md
View File

@@ -1,20 +0,0 @@
---
source_keys: []
---
# references/
Additional documentation agents load on demand.
## Files
| File | Purpose |
|------|---------|
| `finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading. |
| `description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions. |
| `body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for. |
| `scope-plugin-apm.md` | Contract for a single vendor-neutral `.apm/agents/<name>.agent.md` file — allowlist, dimension routing, and the dimensions that do not apply. |
| `scope-project-user.md` | Contract for a Claude Code / Copilot file pair — counterpart derivation, provider field rules, and pair consistency. |
| `validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, and known script failures. |
| `field-inventory.md` | Authoritative field lists, read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM allowlist. |
| `sources.md` | Research provenance records for skill content. Load only when tracing the origin of a specific rule or field constraint. |

6
plugins/kyberforge/.apm/skills/agent-audit/references/body-and-delegation.md
View File

@@ -10,7 +10,7 @@ source_keys:
# Body, Delegation and Comment Discipline Reference # Body, Delegation and Comment Discipline Reference
Upstream source: Claude Code subagent and plugin references, GitHub Copilot custom-agents Upstream source: Claude Code subagent and plugin references, GitHub Copilot custom-agents
configuration. House contract: ADR-0020, the context budget. configuration. House contract: the context budget.
Read this when judging the **body**, **delegation** and **comment-discipline** dimensions. Read this when judging the **body**, **delegation** and **comment-discipline** dimensions.
@@ -23,8 +23,8 @@ dilutes the signal of what matters.
## Agents take no body word gate ## Agents take no body word gate
ADR-0020 gates a skill body at 600 words SUGGESTION / 900 FAIL and deliberately gates an agent body A skill body is gated at 600 words SUGGESTION / 900 FAIL; an agent body is deliberately gated at
at nothing. The two are not the same construct: a skill body is loaded into the caller's live nothing. The two are not the same construct: a skill body is loaded into the caller's live
context and competes with the conversation already there, while an agent body *becomes* the system context and competes with the conversation already there, while an agent body *becomes* the system
prompt of a fresh context that has nothing else in it. The rationale for the 900-word ceiling does prompt of a fresh context that has nothing else in it. The rationale for the 900-word ceiling does
not transfer, so: not transfer, so:

2
plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md
View File

@@ -9,7 +9,7 @@ source_keys:
# Agent Description Quality Reference # Agent Description Quality Reference
Upstream source: Claude Code subagent reference, GitHub Copilot custom-agents configuration. Upstream source: Claude Code subagent reference, GitHub Copilot custom-agents configuration.
House contract: ADR-0020, the context budget. The house contract is narrower than either House contract: the context budget. The house contract is narrower than either
platform's schema rather than a reinterpretation of it: where both speak, both must be satisfied. platform's schema rather than a reinterpretation of it: where both speak, both must be satisfied.
## Why the description is the expensive part ## Why the description is the expensive part

4
plugins/kyberforge/.apm/skills/agent-audit/references/finding-criteria.md
View File

@@ -90,8 +90,8 @@ Flag as SUGGESTION if:
- A rationale is missing from a rule the agent is expected to enforce — present but unexplained - A rationale is missing from a rule the agent is expected to enforce — present but unexplained
- Comments are useful but verbose enough to bury the field they annotate - Comments are useful but verbose enough to bury the field they annotate
**Never report an agent body as too long on a word count.** ADR-0020 gates a skill body at **Never report an agent body as too long on a word count.** A skill body is gated at 600/900 words;
600/900 words and deliberately gates an agent body at nothing, because an agent body *becomes* the an agent body is deliberately gated at nothing, because an agent body *becomes* the
system prompt of a fresh context rather than competing with a live conversation. No number exists system prompt of a fresh context rather than competing with a live conversation. No number exists
to cite. The one length signal that applies is the Copilot runtime's 30,000-character body limit, to cite. The one length signal that applies is the Copilot runtime's 30,000-character body limit,
which `validate.sh` already reports as a SUGGESTION. Length is judged through the delegation FAIL which `validate.sh` already reports as a SUGGESTION. Length is judged through the delegation FAIL

Some files were not shown because too many files have changed in this diff Show More