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

chore: drop the flat content mirror and native install support (ADR-0024)

Browse Source 
apm becomes the only supported install path. The flat mirror at each plugin
root existed solely so Claude Code's native `claude plugin install` could
convention-scan plugin content (ADR-0017). With no native consumers, it cost
~20,000 tracked lines plus ~2,100 lines of sync tooling and ~88s of every
push to guard content apm never reads — and its only automated gate,
`claude plugin validate --strict`, passes on a plugin with zero content, so
it could not detect the defect ADR-0017 was created to fix.

Removes the mirror (213 files), the six per-plugin manifest pairs,
sync-plugin-content.sh, its 1,289-line test, the orphaned
marketplace-plugins.sh, and the check-plugin-content-sync and
validate-plugins pre-push hooks. The root `marketplace:` block and
.claude-plugin/ catalogue stay: apm's own marketplace consumers read that
same file, so `<name>@holocron` short names keep working.

tests/run-bats.sh now excludes .claude/skills/. apm installs from .apm/,
which carries the tests/ dirs the mirror stripped, so deployed .bats files
would otherwise be discovered and double-run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
Defame1297
2026-09-14 16:59:42 +00:00
parent 0dffff3c21
commit 718c79af70
245 changed files with 298 additions and 22602 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
plugins/bin/.claude-plugin/plugin.json
View File

@@ -1,30 +0,0 @@
{
"name": "bin",
"version": "1.1.7",
"description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"url": "https://git.dev.rkdr.net/Defame1297/"
},
"license": "MIT",
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin",
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin",
"keywords": [
"utility",
"diagnostics",
"prototyping",
"tdd",
"research"
],
"mcpServers": {
"obsidian": {
"args": [
"@bitbonsai/mcpvault@0.15.0",
"docs/"
],
"command": "npx",
"type": "stdio"
}
}
}

21
plugins/bin/.github/plugin/plugin.json vendored
View File

@@ -1,21 +0,0 @@
{
"name": "bin",
"version": "1.1.7",
"description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"url": "https://git.dev.rkdr.net/Defame1297/"
},
"license": "MIT",
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin",
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin",
"keywords": [
"utility",
"diagnostics",
"prototyping",
"tdd",
"research"
],
"mcpServers": ".mcp.json"
}

50
plugins/bin/skills/caveman/SKILL.md
View File

@@ -1,50 +0,0 @@
---
name: caveman
disable-model-invocation: true
description: >
Ultra-compressed output mode that drops articles, filler and pleasantries while
keeping technical substance exact, cutting token usage by roughly 75%.
metadata:
version: "1.0.0"
---
Respond terse like smart caveman. All technical substance stay. Only fluff die.
## Persistence
ACTIVE EVERY RESPONSE once user type `/caveman`. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
## Rules
Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
Pattern: `[thing] [action] [reason]. [next step].`
Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
### Examples
**"Why React component re-render?"**
> Inline obj prop -> new ref -> re-render. `useMemo`.
**"Explain database connection pooling."**
> Pool = reuse DB conn. Skip handshake -> fast under load.
## Auto-Clarity Exception
Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
Example -- destructive op:
> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
>
> ```sql
> DROP TABLE users;
> ```
>
> Caveman resume. Verify backup exist first.

91
plugins/bin/skills/diagnose/SKILL.md
View File

@@ -1,91 +0,0 @@
---
name: diagnose
description: >
Use when the user says "diagnose this" or "debug this", reports something
broken, throwing, or failing, or says something got slow. Not filing or
triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`.
metadata:
version: "1.0.1"
---
# Diagnose
A discipline for hard bugs. Skip phases only when explicitly justified.
When exploring the codebase, use the domain glossary for a clear mental model of the relevant modules, and check ADRs in the area.
## Phase 1 — Build a feedback loop
**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
**If you do not yet have such a signal, read `references/feedback-loops.md`** — ten ways to build one ordered by cost, and what to ask the user for when the bug resists reproduction entirely.
**If you do have one, it is probably not sharp enough yet.** Make it faster and more deterministic, and make it assert on the exact symptom rather than "didn't crash" — a 30-second flaky loop is barely better than no loop. If it stays slow or intermittent after that, read that file's "Iterate on the loop itself" and "Intermittent bugs" sections.
Do not proceed to Phase 2 until you have a loop you believe in. If you cannot build one, stop and say so explicitly, listing what you tried — never hypothesise without a signal.
## Phase 2 — Reproduce
Run the loop. Watch the bug appear.
Confirm:
- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
- [ ] The failure is reproducible across multiple runs. If it is intermittent, `references/feedback-loops.md` defines the rate high enough to debug against — go back to Phase 1 and raise it.
- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
Do not proceed until you reproduce the bug.
## Phase 3 — Hypothesise
Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
Each hypothesis must be **falsifiable**: state the prediction it makes.
> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
## Phase 4 — Instrument
Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
Tool preference:
1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
2. **Targeted logs** at the boundaries that distinguish hypotheses.
3. Never "log everything and grep".
**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
## Phase 5 — Fix + regression test
Write the regression test **before the fix** — but only at a **correct seam**: one where the test exercises the real bug pattern as it occurs at the call site. If the available seam looks too shallow, or you cannot tell whether it is, read `references/regression-seams.md`.
**If no correct seam exists, that itself is the finding.** Note it and carry it into Phase 6 — the architecture is preventing the bug from being locked down.
At a correct seam:
1. Turn the Phase 1 loop into a failing test at that seam, narrowed to the symptom captured in Phase 2.
2. Watch it fail.
3. Apply the fix.
4. Watch it pass.
5. Re-run the Phase 1 feedback loop against the original, un-narrowed scenario.
## Phase 6 — Cleanup + post-mortem
Required before declaring done:
- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
- [ ] Regression test passes (or absence of seam is documented)
- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

41
plugins/bin/skills/diagnose/assets/hitl-loop.template.sh
View File

@@ -1,41 +0,0 @@
#!/usr/bin/env bash
# Human-in-the-loop reproduction loop.
# Copy this file, edit the steps below, and run it.
# The agent runs the script; the user follows prompts in their terminal.
#
# Usage:
# bash hitl-loop.template.sh
#
# Two helpers:
# step "<instruction>" → show instruction, wait for Enter
# capture VAR "<question>" → show question, read response into VAR
#
# At the end, captured values are printed as KEY=VALUE for the agent to parse.
set -euo pipefail
step() {
printf '\n>>> %s\n' "$1"
read -r -p " [Enter when done] " _
}
capture() {
local var="$1" question="$2" answer
printf '\n>>> %s\n' "$question"
read -r -p " > " answer
printf -v "$var" '%s' "$answer"
}
# --- edit below ---------------------------------------------------------
step "Open the app at http://localhost:3000 and sign in."
capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
capture ERROR_MSG "Paste the error message (or 'none'):"
# --- edit above ---------------------------------------------------------
printf '\n--- Captured ---\n'
printf 'ERRORED=%s\n' "$ERRORED"
printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

40
plugins/bin/skills/diagnose/references/feedback-loops.md
View File

@@ -1,40 +0,0 @@
# Constructing and sharpening a feedback loop
A feedback loop is a fast, deterministic, agent-runnable pass/fail signal for the bug. Build the right one and the bug is 90% fixed. This file covers the whole arc: building a loop, sharpening one you already have, and escalating when the bug resists reproduction.
## Ways to construct one — try them in roughly this order
1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
2. **Curl / HTTP script** against a running dev server.
3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `assets/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
## Iterate on the loop itself
Treat the loop as a product. Once you have _a_ loop, ask:
- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
## Intermittent bugs — raise the reproduction rate
If the loop only sometimes fails, the goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
## When you genuinely cannot build a loop
Stop and say so explicitly. List what you tried. Ask the user for:
- access to whatever environment reproduces it,
- a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or
- permission to add temporary production instrumentation.
Do **not** proceed to hypothesise without a loop. A hypothesis you cannot falsify against a signal is a guess, and the fix that follows it is unverifiable.

24
plugins/bin/skills/diagnose/references/regression-seams.md
View File

@@ -1,24 +0,0 @@
# Judging a regression-test seam
Read this when Phase 5 leaves you unsure whether the seam available for the regression test is the correct one — either because the obvious seam looks shallow, or because there appears to be no seam at all.
## What makes a seam correct
A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site: the same entry point, the same participants, the same ordering, and the same state the real caller holds when it goes wrong.
## Seams that are too shallow
- A single-caller test when the bug only appears with multiple callers.
- A unit test that cannot replicate the chain of calls that triggered the bug.
- A test that reproduces the symptom by construction — asserting on a value the test itself set — rather than by driving the code path that produces it.
- A test that mocks out the collaborator the bug actually lives in.
A regression test at a shallow seam gives false confidence. It passes forever, including after a change reintroduces the bug at the real call site, and it will be read by the next maintainer as proof the bug is locked down.
## When there is no correct seam
Do not force one, and do not settle for a shallow seam to have something green. Instead:
1. Apply the fix and verify it against the Phase 1 loop directly.
2. Write down which seams you considered and why each was too shallow.
3. Carry that into Phase 6's "what would have prevented this bug" question. A missing seam is an architecture finding — tangled callers, hidden coupling, or a module with no testable boundary — and the handoff is the `improve-codebase-architecture` skill, with those specifics attached.

16
plugins/bin/skills/grill-me/SKILL.md
View File

@@ -1,16 +0,0 @@
---
name: grill-me
description: >
Use when the user says "grill me" or wants a plan or design stress-tested by
relentless interview — one question at a time, down each branch of the
decision tree. Not a plan to challenge against `CONTEXT.md` and ADRs ->
`grill-with-docs`.
metadata:
version: "1.0.0"
---
Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
Ask the questions one at a time.
If a question can be answered by exploring the codebase, explore the codebase instead.

93
plugins/bin/skills/grill-with-docs/SKILL.md
View File

@@ -1,93 +0,0 @@
---
name: grill-with-docs
description: >
Use when a plan should be stress-tested against the project's domain model —
the interview challenges terms against `CONTEXT.md` and writes decisions into
it and into ADRs as they land. Not a plain interview -> `grill-me`.
metadata:
version: "1.0.0"
---
<what-to-do>
Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
Ask the questions one at a time, waiting for feedback on each question before continuing.
If a question can be answered by exploring the codebase, explore the codebase instead.
</what-to-do>
<supporting-info>
## Domain awareness
During codebase exploration, also look for existing documentation:
### File structure
Most repos have a single context:
```
/
├── CONTEXT.md
├── docs/
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
```
If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
```
/
├── CONTEXT-MAP.md
├── docs/
│ └── adr/ ← system-wide decisions
├── src/
│ ├── ordering/
│ │ ├── CONTEXT.md
│ │ └── docs/adr/ ← context-specific decisions
│ └── billing/
│ ├── CONTEXT.md
│ └── docs/adr/
```
Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
## During the session
### Challenge against the glossary
When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
### Sharpen fuzzy language
When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
### Discuss concrete scenarios
When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
### Cross-reference with code
When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
### Update CONTEXT.md inline
When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [context-format.md](references/context-format.md).
Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.
### Offer ADRs sparingly
Only offer to create an ADR when all three are true:
1. **Hard to reverse** — the cost of changing your mind later is meaningful
2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
If any of the three is missing, skip the ADR. Use the format in [adr-format.md](references/adr-format.md).
</supporting-info>

47
plugins/bin/skills/grill-with-docs/references/adr-format.md
View File

@@ -1,47 +0,0 @@
# ADR Format
ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
Create the `docs/adr/` directory lazily — only when the first ADR is needed.
## Template
```md
# {Short title of the decision}
{1-3 sentences: what's the context, what did we decide, and why.}
```
That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
## Optional sections
Only include these when they add genuine value. Most ADRs won't need them.
- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
- **Considered Options** — only when the rejected alternatives are worth remembering
- **Consequences** — only when non-obvious downstream effects need to be called out
## Numbering
Scan `docs/adr/` for the highest existing number and increment by one.
## When to offer an ADR
All three of these must be true:
1. **Hard to reverse** — the cost of changing your mind later is meaningful
2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
### What qualifies
- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

77
plugins/bin/skills/grill-with-docs/references/context-format.md
View File

@@ -1,77 +0,0 @@
# CONTEXT.md Format
## Structure
```md
# {Context Name}
{One or two sentence description of what this context is and why it exists.}
## Language
**Order**:
{A concise description of the term}
_Avoid_: Purchase, transaction
**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request
**Customer**:
A person or organization that places orders.
_Avoid_: Client, buyer, account
## Relationships
- An **Order** produces one or more **Invoices**
- An **Invoice** belongs to exactly one **Customer**
## Example dialogue
> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
## Flagged ambiguities
- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.
```
## Rules
- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
- **Show relationships.** Use bold term names and express cardinality where obvious.
- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
## Single vs multi-context repos
**Single context (most repos):** One `CONTEXT.md` at the repo root.
**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
```md
# Context Map
## Contexts
- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
## Relationships
- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
```
The skill infers which structure applies:
- If `CONTEXT-MAP.md` exists, read it to find contexts
- If only a root `CONTEXT.md` exists, single context
- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

80
plugins/bin/skills/improve-codebase-architecture/SKILL.md
View File

@@ -1,80 +0,0 @@
---
name: improve-codebase-architecture
description: >
Use when the user wants to improve architecture, find refactoring
opportunities, consolidate tightly-coupled modules, or make a codebase more
testable and AI-navigable — deepening opportunities that turn shallow modules
into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a
failure -> `diagnose`.
metadata:
version: "1.0.1"
---
# Improve Codebase Architecture
Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
## Glossary
Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary."
- **Module** — anything with an interface and an implementation (function, class, package, slice).
- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
- **Implementation** — the code inside.
- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
- **Adapter** — a concrete thing satisfying an interface at a seam.
- **Leverage** — what callers get from depth.
- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
Key principles:
- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
- **The interface is the test surface.**
- **One adapter = hypothetical seam. Two adapters = real seam.**
If a term or principle above is ambiguous in the case in front of you, or you need the definitions and the principles the two lists leave out, read `references/language.md`.
This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
## Process
### 1. Explore
Read the domain glossary and any ADRs in the area first.
Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
- Where does understanding one concept require bouncing between many small modules?
- Where are modules **shallow** — interface nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
- Where do tightly-coupled modules leak across their seams?
- Which parts of the codebase are untested, or hard to test through their current interface?
Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
### 2. Present candidates
Present a numbered list of deepening opportunities. For each candidate:
- **Files** — which files/modules are involved
- **Problem** — why the current architecture is causing friction
- **Solution** — plain English description of what would change
- **Benefits** — explained in terms of locality and leverage, and also in how tests would improve
**Use CONTEXT.md vocabulary for the domain, and the architecture glossary above for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
### 3. Grilling loop
Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
Side effects happen inline as decisions crystallize:
- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `grill-with-docs`, in the format `grill-with-docs`'s `references/context-format.md` defines. Create the file lazily if it doesn't exist.
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See `grill-with-docs`'s `references/adr-format.md`.
- **Want to explore alternative interfaces for the deepened module?** Read `references/interface-design.md`.

37
plugins/bin/skills/improve-codebase-architecture/references/deepening.md
View File

@@ -1,37 +0,0 @@
# Deepening
How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**.
## Dependency categories
When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
### 1. In-process
Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
### 2. Local-substitutable
Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
### 3. Remote but owned (Ports & Adapters)
Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
### 4. True external (Mock)
Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
## Seam discipline
- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
## Testing strategy: replace, don't layer
- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
- Write new tests at the deepened module's interface. The **interface is the test surface**.
- Tests assert on observable outcomes through the interface, not internal state.
- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

44
plugins/bin/skills/improve-codebase-architecture/references/interface-design.md
View File

@@ -1,44 +0,0 @@
# Interface Design
When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
Uses the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
## Process
### 1. Frame the problem space
Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
- The constraints any new interface would need to satisfy
- The dependencies it would rely on, and which category they fall into (see [deepening.md](deepening.md))
- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
### 2. Spawn sub-agents
Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [deepening.md](deepening.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
- Agent 2: "Maximise flexibility — support many use cases and extension."
- Agent 3: "Optimise for the most common caller — make the default case trivial."
- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
Include both [language.md](language.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
Each sub-agent outputs:
1. Interface (types, methods, params — plus invariants, ordering, error modes)
2. Usage example showing how callers use it
3. What the implementation hides behind the seam
4. Dependency strategy and adapters (see [deepening.md](deepening.md))
5. Trade-offs — where leverage is high, where it's thin
### 3. Present and compare
Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

53
plugins/bin/skills/improve-codebase-architecture/references/language.md
View File

@@ -1,53 +0,0 @@
# Language
Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
## Terms
**Module**
Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice.
_Avoid_: unit, component, service.
**Interface**
Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
_Avoid_: API, signature (too narrow — those refer only to the type-level surface).
**Implementation**
What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
**Depth**
Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
**Seam** _(from Michael Feathers)_
A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
_Avoid_: boundary (overloaded with DDD's bounded context).
**Adapter**
A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
**Leverage**
What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
**Locality**
What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
## Principles
- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
## Relationships
- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
- **Depth** is a property of a **Module**, measured against its **Interface**.
- A **Seam** is where a **Module**'s **Interface** lives.
- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
## Rejected framings
- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.

38
plugins/bin/skills/prototype/SKILL.md
View File

@@ -1,38 +0,0 @@
---
name: prototype
description: >
Use when the user wants a throwaway prototype to answer a design question about
a data model, state machine or business logic, or to mock up a UI in several
variations. Not production code -> `tdd`. Not talking a design through ->
`grill-me`.
metadata:
version: "1.0.0"
---
# Prototype
A prototype is **throwaway code that answers a question**. The question decides the shape.
## Pick a branch
| Question being answered | Build | Reference |
|---|---|---|
| "Does this logic / state model feel right?" | A tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper | `references/logic.md` |
| "What should this look like?" | Several radically different UI variations on one route, switchable via a URL search param and a floating bottom bar | `references/ui.md` |
Resolve the row from the user's prompt, the surrounding code, or by asking if the user is around, then read only that reference — each is self-contained.
The two branches produce fundamentally different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
## Rules that apply to both
1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is *checking*, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
4. **Skip the polish.** No tests, no error handling beyond what makes the prototype *runnable*, no abstractions. The point is to learn something fast and then delete it.
5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
## When done
The *answer* is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.

79
plugins/bin/skills/prototype/references/logic.md
View File

@@ -1,79 +0,0 @@
# Logic Prototype
A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
## When this is the right shape
- "I'm not sure if this state machine handles the edge case where X then Y."
- "Does this data model actually let me represent the case where..."
- "I want to feel out what the API should look like before writing it."
- Anything where the user wants to **press buttons and watch state change**.
If the question is "what should this look like" — wrong branch. Read `references/ui.md`.
## Process
### 1. State the question
Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
### 2. Pick the language
Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype.
### 3. Isolate the logic in a portable module
Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
The right shape depends on the question:
- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted.
### 4. Build the smallest TUI that exposes the state
Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
Each frame has two parts, in this order:
1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
2. **Keyboard shortcuts**, listed at the bottom: `[a] add user [d] delete user [t] tick clock [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
Behaviour:
1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
3. **Re-render** the full frame after every action — don't append, replace.
4. **Loop until quit.**
The whole frame should fit on one screen.
### 5. Make it runnable in one command
Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
If the host project has no task runner, just put the command at the top of the prototype's README.
### 6. Hand it over
Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
### 7. Capture the answer
When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted.
## Anti-patterns
- **Don't add tests.** A prototype that needs tests is no longer a prototype.
- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence.
- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.

112
plugins/bin/skills/prototype/references/ui.md
View File

@@ -1,112 +0,0 @@
# UI Prototype
Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
If the question is about logic/state rather than what something looks like — wrong branch. Read `references/logic.md`.
## When this is the right shape
- "What should this page look like?"
- "I want to see a few options for this dashboard before committing."
- "Try a different layout for the settings screen."
- Any time the user would otherwise spend a day picking between three vague mockups in their head.
## Two sub-shapes — strongly prefer sub-shape A
A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
### Sub-shape A — adjustment to an existing page (preferred)
The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
### Sub-shape B — a new page (last resort)
Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
In both sub-shapes the floating bottom bar is identical.
## Process
### 1. State the question and pick N
Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
Write down the plan in one line, in the prototype's location or a top-of-file comment:
> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
This works whether the user is here to push back or not.
### 2. Generate radically different variants
Draft each variant. Hold each one to:
- The page's purpose and the data it has access to.
- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
### 3. Wire them together
Create a single switcher component on the route:
```tsx
// pseudo-code — adapt to the project's framework
const variant = searchParams.get('variant') ?? 'A';
return (
<>
{variant === 'A' && <VariantA {...data} />}
{variant === 'B' && <VariantB {...data} />}
{variant === 'C' && <VariantC {...data} />}
<PrototypeSwitcher variants={['A','B','C']} current={variant} />
</>
);
```
For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
### 4. Build the floating switcher
A small fixed-position bar at the bottom-centre of the screen with three pieces:
- **Left arrow** — cycles to the previous variant (wraps around).
- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
- **Right arrow** — cycles forward (wraps around).
Behaviour:
- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
### 5. Hand it over
Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"** — that's the actual design they want.
### 6. Capture the answer and clean up
Once a variant has won, write down which one and why (commit message, ADR, issue, or a `NOTES.md` next to the prototype if running AFK and the user hasn't responded yet). Then:
- **Sub-shape A** — delete the losing variants and the switcher; fold the winner into the existing page.
- **Sub-shape B** — promote the winning variant to a real route, delete the throwaway route and the switcher.
Don't leave variant components or the switcher lying around. They rot fast and confuse the next reader.
## Anti-patterns
- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

79
plugins/bin/skills/research/SKILL.md
View File

@@ -1,79 +0,0 @@
---
name: research
description: >-
Use when the user wants a tool, library, or API researched from canonical
documentation into structured per-topic reference markdown files. Not
documentation written from existing code or specs -> `write-docs`. Not a bug
or incident -> `diagnose`.
metadata:
version: "1.0.0"
category: research
allowed-tools:
- Grep
- Glob
- Read
- Write
- WebSearch
- WebFetch
- mcp__context7__resolve-library-id
- mcp__context7__query-docs
model: sonnet
---
## Gotchas
- Never infer the output path. A run writes a directory's worth of files, and a guessed destination scatters them through someone's source tree. If the user named no path, stop and ask.
- Write nothing outside the given output path. A file placed beside the agreed directory is one the user never asked for and will not think to look for.
- Never write an empty topic file. A stub `troubleshooting.md` reads downstream as researched and closed.
- A Context7 response that is a "no results" message, a redirect notice, or header-only boilerplate is not coverage. A topic area counts as covered only when the response carries at least one substantive paragraph.
## Step 1 — Scope against the working directory
Search for existing use of the topic — imports, config files, version pins, reference files already written — and narrow the research to what is missing: the version actually in use, the topics not yet documented.
The default topic areas are `overview`, `installation`, `configuration`, `cli-reference`,
`api-reference`, `examples` and `troubleshooting` — one file each, and only where content exists.
If what belongs in one of them is unclear, or the topic needs a file outside that set, read
`references/topics.md` for the per-topic coverage table and the custom-topic naming rule.
## Step 2 — Resolve against Context7
If the topic is a library, framework, or API and the user gave no starting URLs, call `resolve-library-id` with the topic name and the user's full question — match quality depends on the question, not the bare name — then `query-docs` once per default topic area. Record each response as a source with slug `context7-<library-slug>`, and mark which topic areas it covered — those skip the web reads at step 4.
If the library does not resolve, or the user gave starting URLs, go to step 3. Explicit URLs are a source choice; do not second-guess them with a resolution attempt.
## Step 3 — Discover sources
If the user gave starting URLs, skip discovery: those URLs are the source list and go straight to step 4.
Otherwise, for every topic area Context7 did not cover, websearch for canonical documentation — `llms.txt`, official developer docs, and API references ahead of tutorials or blog posts. Collect three to five candidate URLs before reading any of them.
If nothing usable comes back, stop and report what was searched, then ask for starting URLs rather than settling for tutorials.
## Step 4 — Read the sources
`WebFetch` each URL in turn. No subagent tool is granted here, so the reads are serial and every fetched page lands in this context: reduce each page to notes by topic area, plus the links worth deepening, before fetching the next one.
## Step 5 — Deepen
`WebFetch` the links worth following, still one at a time and still reducing each page to notes. Stop a branch once its content turns repetitive or leaves the topic, and cap the whole step at roughly ten additional pages — serial reads make that cap a real budget, not a formality.
## Step 6 — Write
Merge every set of notes, Context7 and web alike, by topic area, then write, in the output path:
- `<topic>.md` for each topic area that has content, default or custom. Frontmatter carries `topic:` (the filename without `.md`) and `source_keys:` (kebab-case slugs matching `sources.md`); the body is prose in `##` sections, with no inline URLs.
- `sources.md`, always, one `##` section per source — including sources that yielded nothing — with exactly these four fields:
```markdown
- **URL:** <full URL>
- **Description:** <one-line summary>
- **Contributing files:** <topic files this source contributed to>
- **Status:** `extracted` | `no content extracted`
```
Spell those four field names exactly as given. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing.
Read `references/file-format.md` when the four fields above do not settle the case: what a slug should be, the `context7-<library-slug>` slug and `context7:<library-id>` URL convention for a Context7 source, or what belongs in a topic body versus a verbatim copy of the source.
If no topic area has content, write nothing at all, `sources.md` included, and report what was searched.

39
plugins/bin/skills/research/references/file-format.md
View File

@@ -1,39 +0,0 @@
# Reference file format
Every topic file follows this structure.
## Frontmatter
```yaml
---
topic: <topic-slug> # matches the filename without .md (e.g. "api-reference")
source_keys: # kebab-case slugs of sources that contributed; must match sources.md entries
- <slug>
- <slug>
---
```
## Body
Plain prose organized into markdown sections (`##`, `###`). Extract the content most relevant to skill authoring or implementation — not a verbatim copy of the source. Focus on:
- Decisions that affect how to call the API or tool
- Options, flags, or parameters with non-obvious behavior
- Constraints, rate limits, or gotchas
- Canonical patterns the skill should follow
No inline URLs in the body — all source traceability lives in `sources.md` via `source_keys`.
## sources.md format
```markdown
# Sources
## <slug>
- **URL:** <full URL>
- **Description:** <one-line summary of what this source covers>
- **Contributing files:** <comma-separated list of topic files this source contributed to>
- **Status:** `extracted` | `no content extracted`
```
Use one `##` section per source. Slugs are kebab-case derived from the domain or page title (e.g. `stripe-api-docs`, `openai-python-sdk-readme`). For Context7 sources, use the slug `context7-<library-slug>` (e.g. `context7-vercel-next-js`) and set **URL** to `context7:<library-id>` (e.g. `context7:/vercel/next.js`).

17
plugins/bin/skills/research/references/topics.md
View File

@@ -1,17 +0,0 @@
# Default topic list
Create one file per topic when relevant content is found. Skip topics with no content. Add custom topics when content warrants it.
| File | Covers |
|---|---|
| `overview.md` | What it is, key concepts, mental model, architecture summary |
| `installation.md` | Setup, dependencies, prerequisites, version requirements |
| `configuration.md` | Config files, options, environment variables, defaults |
| `cli-reference.md` | Commands, subcommands, flags, exit codes |
| `api-reference.md` | Endpoints, SDK methods, types, request/response shapes |
| `examples.md` | Common usage patterns, recipes, quickstart walkthroughs |
| `troubleshooting.md` | Known issues, error codes, gotchas, workarounds |
## Custom topics
Create additional topic files when content doesn't fit the defaults. Examples: `webhooks.md`, `rate-limits.md`, `authentication.md`, `migrations.md`, `security.md`. Use kebab-case filenames.

114
plugins/bin/skills/tdd/SKILL.md
View File

@@ -1,114 +0,0 @@
---
name: tdd
description: >
Use when the user wants a feature built or a bug fixed test-first, in a strict
red-green-refactor loop, one behaviour at a time. Not diagnosing an existing
bug -> `diagnose`. Not throwaway exploratory code -> `prototype`.
metadata:
version: "1.0.1"
---
# Test-Driven Development
## Philosophy
**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
If you need worked examples of the difference — a behaviour-level test beside the implementation-coupled version of the same check — read `references/tests.md`. If a test needs a collaborator faked, read `references/mocking.md` before reaching for a mock.
## Anti-Pattern: Horizontal Slices
**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
This produces **crap tests**:
- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
- You outrun your headlights, committing to test structure before understanding the implementation
**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
```
WRONG (horizontal):
RED: test1, test2, test3, test4, test5
GREEN: impl1, impl2, impl3, impl4, impl5
RIGHT (vertical):
RED→GREEN: test1→impl1
RED→GREEN: test2→impl2
RED→GREEN: test3→impl3
...
```
## Workflow
### 1. Planning
When exploring the codebase, use the domain glossary so test names and interface vocabulary match the project's language, and respect ADRs in the area.
Before writing any code:
- [ ] Confirm with user what interface changes are needed
- [ ] Confirm with user which behaviors to test (prioritize)
- [ ] Identify opportunities for [deep modules](references/deep-modules.md) (small interface, deep implementation)
- [ ] Design interfaces for [testability](references/interface-design.md)
- [ ] List the behaviors to test (not implementation steps)
- [ ] Get user approval on the plan
Ask: "What should the public interface look like? Which behaviors are most important to test?"
**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
### 2. Tracer Bullet
Write ONE test that confirms ONE thing about the system:
```
RED: Write test for first behavior → test fails
GREEN: Write minimal code to pass → test passes
```
This is your tracer bullet - proves the path works end-to-end.
### 3. Incremental Loop
For each remaining behavior:
```
RED: Write next test → fails
GREEN: Minimal code to pass → passes
```
Rules:
- One test at a time
- Only enough code to pass current test
- Don't anticipate future tests
- Keep tests focused on observable behavior
### 4. Refactor
After all tests pass, look for [refactor candidates](references/refactoring.md):
- [ ] Extract duplication
- [ ] Deepen modules (move complexity behind simple interfaces)
- [ ] Apply SOLID principles where natural
- [ ] Consider what new code reveals about existing code
- [ ] Run tests after each refactor step
**Never refactor while RED.** Get to GREEN first.
## Checklist Per Cycle
```
[ ] Test describes behavior, not implementation
[ ] Test uses public interface only
[ ] Test would survive internal refactor
[ ] Code is minimal for this test
[ ] No speculative features added
```

33
plugins/bin/skills/tdd/references/deep-modules.md
View File

@@ -1,33 +0,0 @@
# Deep Modules
From "A Philosophy of Software Design":
**Deep module** = small interface + lots of implementation
```
┌─────────────────────┐
│ Small Interface │ ← Few methods, simple params
├─────────────────────┤
│ │
│ │
│ Deep Implementation│ ← Complex logic hidden
│ │
│ │
└─────────────────────┘
```
**Shallow module** = large interface + little implementation (avoid)
```
┌─────────────────────────────────┐
│ Large Interface │ ← Many methods, complex params
├─────────────────────────────────┤
│ Thin Implementation │ ← Just passes through
└─────────────────────────────────┘
```
When designing interfaces, ask:
- Can I reduce the number of methods?
- Can I simplify the parameters?
- Can I hide more complexity inside?

31
plugins/bin/skills/tdd/references/interface-design.md
View File

@@ -1,31 +0,0 @@
# Interface Design for Testability
Good interfaces make testing natural:
1. **Accept dependencies, don't create them**
```typescript
// Testable
function processOrder(order, paymentGateway) {}
// Hard to test
function processOrder(order) {
const gateway = new StripeGateway();
}
```
2. **Return results, don't produce side effects**
```typescript
// Testable
function calculateDiscount(cart): Discount {}
// Hard to test
function applyDiscount(cart): void {
cart.total -= discount;
}
```
3. **Small surface area**
- Fewer methods = fewer tests needed
- Fewer params = simpler test setup

59
plugins/bin/skills/tdd/references/mocking.md
View File

@@ -1,59 +0,0 @@
# When to Mock
Mock at **system boundaries** only:
- External APIs (payment, email, etc.)
- Databases (sometimes - prefer test DB)
- Time/randomness
- File system (sometimes)
Don't mock:
- Your own classes/modules
- Internal collaborators
- Anything you control
## Designing for Mockability
At system boundaries, design interfaces that are easy to mock:
**1. Use dependency injection**
Pass external dependencies in rather than creating them internally:
```typescript
// Easy to mock
function processPayment(order, paymentClient) {
return paymentClient.charge(order.total);
}
// Hard to mock
function processPayment(order) {
const client = new StripeClient(process.env.STRIPE_KEY);
return client.charge(order.total);
}
```
**2. Prefer SDK-style interfaces over generic fetchers**
Create specific functions for each external operation instead of one generic function with conditional logic:
```typescript
// GOOD: Each function is independently mockable
const api = {
getUser: (id) => fetch(`/users/${id}`),
getOrders: (userId) => fetch(`/users/${userId}/orders`),
createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
};
// BAD: Mocking requires conditional logic inside the mock
const api = {
fetch: (endpoint, options) => fetch(endpoint, options),
};
```
The SDK approach means:
- Each mock returns one specific shape
- No conditional logic in test setup
- Easier to see which endpoints a test exercises
- Type safety per endpoint

10
plugins/bin/skills/tdd/references/refactoring.md
View File

@@ -1,10 +0,0 @@
# Refactor Candidates
After TDD cycle, look for:
- **Duplication** → Extract function/class
- **Long methods** → Break into private helpers (keep tests on public interface)
- **Shallow modules** → Combine or deepen
- **Feature envy** → Move logic to where data lives
- **Primitive obsession** → Introduce value objects
- **Existing code** the new code reveals as problematic

61
plugins/bin/skills/tdd/references/tests.md
View File

@@ -1,61 +0,0 @@
# Good and Bad Tests
## Good Tests
**Integration-style**: Test through real interfaces, not mocks of internal parts.
```typescript
// GOOD: Tests observable behavior
test("user can checkout with valid cart", async () => {
const cart = createCart();
cart.add(product);
const result = await checkout(cart, paymentMethod);
expect(result.status).toBe("confirmed");
});
```
Characteristics:
- Tests behavior users/callers care about
- Uses public API only
- Survives internal refactors
- Describes WHAT, not HOW
- One logical assertion per test
## Bad Tests
**Implementation-detail tests**: Coupled to internal structure.
```typescript
// BAD: Tests implementation details
test("checkout calls paymentService.process", async () => {
const mockPayment = jest.mock(paymentService);
await checkout(cart, payment);
expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
});
```
Red flags:
- Mocking internal collaborators
- Testing private methods
- Asserting on call counts/order
- Test breaks when refactoring without behavior change
- Test name describes HOW not WHAT
- Verifying through external means instead of interface
```typescript
// BAD: Bypasses interface to verify
test("createUser saves to database", async () => {
await createUser({ name: "Alice" });
const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
expect(row).toBeDefined();
});
// GOOD: Verifies through interface
test("createUser makes user retrievable", async () => {
const user = await createUser({ name: "Alice" });
const retrieved = await getUser(user.id);
expect(retrieved.name).toBe("Alice");
});
```

108
plugins/bin/skills/triage/SKILL.md
View File

@@ -1,108 +0,0 @@
---
name: triage
description: >
Use when the user wants an issue created, triaged, or moved through the
tracker's triage states, or an issue prepared for an AFK agent. Not debugging
the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`.
metadata:
version: "1.0.1"
---
# Triage
Move issues on the project issue tracker through a small state machine of triage roles.
Every comment or issue posted to the issue tracker during triage **must** start with this disclaimer:
```
> *This was generated by AI during triage.*
```
## Reference docs
- [agent-brief.md](references/agent-brief.md) — how to write durable agent briefs
- [out-of-scope.md](references/out-of-scope.md) — how the `.out-of-scope/` knowledge base works
## Roles
Two **category** roles:
- `bug` — something is broken
- `enhancement` — new feature or improvement
Five **state** roles:
- `needs-triage` — maintainer needs to evaluate
- `needs-info` — waiting on reporter for more information
- `ready-for-agent` — fully specified, ready for an AFK agent
- `ready-for-human` — needs human implementation
- `wontfix` — will not be actioned
Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
These are canonical role names — the actual label strings used in the issue tracker may differ. Resolve each canonical name against the tracker's live label set before applying it, using whichever tracker skill this install provides. If a name has no counterpart there, report the gap and ask the maintainer for the mapping — never substitute a guess.
State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
## Invocation
The maintainer invokes `/triage` and describes what they want in natural language. Interpret the request and act. Examples:
- "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?"
## Show what needs attention
Query the issue tracker and present three buckets, oldest first:
1. **Unlabeled** — never triaged.
2. **`needs-triage`** — evaluation in progress.
3. **`needs-info` with reporter activity since the last triage notes** — needs re-evaluation.
Show counts and a one-line summary per issue. Let the maintainer pick.
## Triage a specific issue
1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction.
3. **Reproduce (bugs only).** Before any grilling, attempt reproduction: read the reporter's steps, trace the relevant code, run tests or commands. Report what happened — successful repro with code path, failed repro, or insufficient detail (a strong `needs-info` signal). A confirmed repro makes a much stronger agent brief.
4. **Grill (if needed).** If the issue needs fleshing out, run a `/grill-with-docs` session.
5. **Apply the outcome:**
- `ready-for-agent` — post an agent brief comment ([agent-brief.md](references/agent-brief.md)).
- `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
- `needs-info` — post triage notes (template below).
- `wontfix` (bug) — polite explanation, then close.
- `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([out-of-scope.md](references/out-of-scope.md)).
- `needs-triage` — apply the role. Optional comment if there's partial progress.
## Quick state override
If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent brief.
## Needs-info template
```markdown
## Triage Notes
**What we've established so far:**
- point 1
- point 2
**What we still need from you (@reporter):**
- question 1
- question 2
```
Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".
## Resuming a previous session
If prior triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.

168
plugins/bin/skills/triage/references/agent-brief.md
View File

@@ -1,168 +0,0 @@
# Writing Agent Briefs
An agent brief is a structured comment posted on an issue in the issue tracker when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original issue body and discussion are context — the agent brief is the contract.
## Principles
### Durability over precision
The issue may sit in `ready-for-agent` for days or weeks. The codebase will change in the meantime. Write the brief so it stays useful even as files are renamed, moved, or refactored.
- **Do** describe interfaces, types, and behavioral contracts
- **Do** name specific types, function signatures, or config shapes that the agent should look for or modify
- **Don't** reference file paths — they go stale
- **Don't** reference line numbers
- **Don't** assume the current implementation structure will remain the same
### Behavioral, not procedural
Describe **what** the system should do, not **how** to implement it. The agent will explore the codebase fresh and make its own implementation decisions.
- **Good:** "The `SkillConfig` type should accept an optional `schedule` field of type `CronExpression`"
- **Bad:** "Open src/types/skill.ts and add a schedule field on line 42"
- **Good:** "When a user runs `/triage` with no arguments, they should see a summary of issues needing attention"
- **Bad:** "Add a switch statement in the main handler function"
### Complete acceptance criteria
The agent needs to know when it's done. Every agent brief must have concrete, testable acceptance criteria. Each criterion should be independently verifiable.
- **Good:** "Querying the issue tracker for the `needs-triage` label returns issues that have been through initial classification"
- **Bad:** "Triage should work correctly"
### Explicit scope boundaries
State what is out of scope. This prevents the agent from gold-plating or making assumptions about adjacent features.
## Template
```markdown
## Agent Brief
**Category:** bug / enhancement
**Summary:** one-line description of what needs to happen
**Current behavior:**
Describe what happens now. For bugs, this is the broken behavior.
For enhancements, this is the status quo the feature builds on.
**Desired behavior:**
Describe what should happen after the agent's work is complete.
Be specific about edge cases and error conditions.
**Key interfaces:**
- `TypeName` — what needs to change and why
- `functionName()` return type — what it currently returns vs what it should return
- Config shape — any new configuration options needed
**Acceptance criteria:**
- [ ] Specific, testable criterion 1
- [ ] Specific, testable criterion 2
- [ ] Specific, testable criterion 3
**Out of scope:**
- Thing that should NOT be changed or addressed in this issue
- Adjacent feature that might seem related but is separate
```
## Examples
### Good agent brief (bug)
```markdown
## Agent Brief
**Category:** bug
**Summary:** Skill description truncation drops mid-word, producing broken output
**Current behavior:**
When a skill description exceeds 1024 characters, it is truncated at exactly
1024 characters regardless of word boundaries. This produces descriptions
that end mid-word (e.g. "Use when the user wants to confi").
**Desired behavior:**
Truncation should break at the last word boundary before 1024 characters
and append "..." to indicate truncation.
**Key interfaces:**
- The `SkillMetadata` type's `description` field — no type change needed,
but the validation/processing logic that populates it needs to respect
word boundaries
- Any function that reads SKILL.md frontmatter and extracts the description
**Acceptance criteria:**
- [ ] Descriptions under 1024 chars are unchanged
- [ ] Descriptions over 1024 chars are truncated at the last word boundary
before 1024 chars
- [ ] Truncated descriptions end with "..."
- [ ] The total length including "..." does not exceed 1024 chars
**Out of scope:**
- Changing the 1024 char limit itself
- Multi-line description support
```
### Good agent brief (enhancement)
```markdown
## Agent Brief
**Category:** enhancement
**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests
**Current behavior:**
When a feature request is rejected, the issue is closed with a `wontfix` label
and a comment. There is no persistent record of the decision or reasoning.
Future similar requests require the maintainer to recall or search for the
prior discussion.
**Desired behavior:**
Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
files that capture the decision, reasoning, and links to all issues that
requested the feature. When triaging new issues, these files should be
checked for matches.
**Key interfaces:**
- Markdown file format in `.out-of-scope/` — each file should have a
`# Concept Name` heading, a `**Decision:**` line, a `**Reason:**` line,
and a `**Prior requests:**` list with issue links
- The triage workflow should read all `.out-of-scope/*.md` files early
and match incoming issues against them by concept similarity
**Acceptance criteria:**
- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
- [ ] The file includes the decision, reasoning, and link to the closed issue
- [ ] If a matching `.out-of-scope/` file already exists, the new issue is
appended to its "Prior requests" list rather than creating a duplicate
- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
when a new issue matches a prior rejection
**Out of scope:**
- Automated matching (human confirms the match)
- Reopening previously rejected features
- Bug reports (only enhancement rejections go to `.out-of-scope/`)
```
### Bad agent brief
```markdown
## Agent Brief
**Summary:** Fix the triage bug
**What to do:**
The triage thing is broken. Look at the main file and fix it.
The function around line 150 has the issue.
**Files to change:**
- src/triage/handler.ts (line 150)
- src/types.ts (line 42)
```
This is bad because:
- No category
- Vague description ("the triage thing is broken")
- References file paths and line numbers that will go stale
- No acceptance criteria
- No scope boundaries
- No description of current vs desired behavior

101
plugins/bin/skills/triage/references/out-of-scope.md
View File

@@ -1,101 +0,0 @@
# Out-of-Scope Knowledge Base
The `.out-of-scope/` directory in a repo stores persistent records of rejected feature requests. It serves two purposes:
1. **Institutional memory** — why a feature was rejected, so the reasoning isn't lost when the issue is closed
2. **Deduplication** — when a new issue comes in that matches a prior rejection, the skill can surface the previous decision instead of re-litigating it
## Directory structure
```
.out-of-scope/
├── dark-mode.md
├── plugin-system.md
└── graphql-api.md
```
One file per **concept**, not per issue. Multiple issues requesting the same thing are grouped under one file.
## File format
The file should be written in a relaxed, readable style — more like a short design document than a database entry. Use paragraphs, code samples, and examples to make the reasoning clear and useful to someone encountering it for the first time.
```markdown
# Dark Mode
This project does not support dark mode or user-facing theming.
## Why this is out of scope
The rendering pipeline assumes a single color palette defined in
`ThemeConfig`. Supporting multiple themes would require:
- A theme context provider wrapping the entire component tree
- Per-component theme-aware style resolution
- A persistence layer for user theme preferences
This is a significant architectural change that doesn't align with the
project's focus on content authoring. Theming is a concern for downstream
consumers who embed or redistribute the output.
```ts
// The current ThemeConfig interface is not designed for runtime switching:
interface ThemeConfig {
colors: ColorPalette; // single palette, resolved at build time
fonts: FontStack;
}
```
## Prior requests
- #42 — "Add dark mode support"
- #87 — "Night theme for accessibility"
- #134 — "Dark theme option"
```
### Naming the file
Use a short, descriptive kebab-case name for the concept: `dark-mode.md`, `plugin-system.md`, `graphql-api.md`. The name should be recognizable enough that someone browsing the directory understands what was rejected without opening the file.
### Writing the reason
The reason should be substantive — not "we don't want this" but why. Good reasons reference:
- Project scope or philosophy ("This project focuses on X; theming is a downstream concern")
- Technical constraints ("Supporting this would require Y, which conflicts with our Z architecture")
- Strategic decisions ("We chose to use A instead of B because...")
The reason should be durable. Avoid referencing temporary circumstances ("we're too busy right now") — those aren't real rejections, they're deferrals.
## When to check `.out-of-scope/`
During triage (Step 1: Gather context), read all files in `.out-of-scope/`. When evaluating a new issue:
- Check if the request matches an existing out-of-scope concept
- Matching is by concept similarity, not keyword — "night theme" matches `dark-mode.md`
- If there's a match, surface it to the maintainer: "This is similar to `.out-of-scope/dark-mode.md` — we rejected this before because [reason]. Do you still feel the same way?"
The maintainer may:
- **Confirm** — the new issue gets added to the existing file's "Prior requests" list, then closed
- **Reconsider** — the out-of-scope file gets deleted or updated, and the issue proceeds through normal triage
- **Disagree** — the issues are related but distinct, proceed with normal triage
## When to write to `.out-of-scope/`
Only when an **enhancement** (not a bug) is rejected as `wontfix`. The flow:
1. Maintainer decides a feature request is out of scope
2. Check if a matching `.out-of-scope/` file already exists
3. If yes: append the new issue to the "Prior requests" list
4. If no: create a new file with the concept name, decision, reason, and first prior request
5. Post a comment on the issue explaining the decision and mentioning the `.out-of-scope/` file
6. Close the issue with the `wontfix` label
## Updating or removing out-of-scope files
If the maintainer changes their mind about a previously rejected concept:
- Delete the `.out-of-scope/` file
- The skill does not need to reopen old issues — they're historical records
- The new issue that triggered the reconsideration proceeds through normal triage

109
plugins/bin/skills/write-docs/SKILL.md
View File

@@ -1,109 +0,0 @@
---
name: write-docs
description: >
Use when the user wants technical documentation produced or updated from code
or spec, every claim traced to a source — "write docs for X", "document this
module", "create docs for this feature", "write a README for this". Not an ADR
or other decision record -> `grill-with-docs`. Not an external tool researched
from its docs -> `research`.
updated: 2026-05-17
when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec
metadata:
version: "1.0.0"
category: implement
source:
- repo: anthropics/skills
commit: f458cee31a7577a47ba0c9a101976fa599385174
files:
- skills/doc-coauthoring/SKILL.md # Reader Testing stage, surgical-edit constraint, gap-check step
updated: 2026-05-17
- repo: mattpocock/skills
commit: e74f0061bb67222181640effa98c675bdb2fdaa7
files:
- skills/productivity/write-a-skill/SKILL.md # trigger pattern, review checklist items
updated: 2026-05-17
- repo: bmad-code-org/BMAD-METHOD
commit: 71136bc6af77cbf507d3768494311d5b6ca95cc5
files:
- src/core-skills/bmad-advanced-elicitation/SKILL.md # confirmation gate before applying changes
updated: 2026-05-17
---
## Role
You are a technical writer that produces documentation by reading code and spec — you derive every claim from a source file or explicit user input and never invent behaviour.
## When to use / When not to use
**Use when:**
- User wants to document a module, class, function, feature, CLI flag, API endpoint, config file, or README section
- User says "write docs for X", "document this", "create docs for this feature", "write a README for this"
**Do not use when:**
- User wants an ADR, decision doc, or architecture proposal → `grill-with-docs`, which writes ADRs
- User wants a PRD → no skill in this set produces one; say so rather than redirecting
- User wants to document a skill file (skill files are self-describing)
- User wants marketing or blog copy
- Documentation requires tacit organisational knowledge that cannot be read from code or spec
## Required inputs
- Specific file(s) or module(s) to document, or enough description to propose candidates
- Target audience: developer / user / contributor / internal
- Documentation type: reference, guide, README section, inline comment, changelog entry
## Constraints
- Every claim must be traceable to a source file line, spec section, or explicit user statement — never invent behaviour
- User must approve specific files before the skill reads them; skill may propose candidates but waits for approval
- Stage skipping is allowed only with an explicit user request and a one-sentence logged reason
- Show the full revised section before each confirmation gate — never gate on output the user has not seen
- Never reprint the whole document; all edits are surgical
- Produce a one-line delta summary after each refinement round
- Reader Testing sub-agent receives only the finished doc and the question list — no source files
- Write summary and overview sections last, after all detail sections are stable
## Process
1. **Identify scope.** User names specific files or sections. If not provided, propose candidates based on the description — wait for explicit approval before reading.
2. **Read and extract.** Read approved files. Extract: public API surface, described behaviour, visible constraints, non-obvious invariants. Note what the code does NOT explain (caller intent, error handling rationale, non-obvious side effects).
3. **Gap check.** Present extracted behaviour to the user. Ask them to fill only the gaps — what the code does not explain. Log any explicitly deferred gaps. If the user requests to skip this step, log the reason and proceed.
4. **Draft section by section.** For each section: state the proposed content and its source (code line / spec section / user input). Show; confirm before moving to the next section.
5. **Confirmation gate.** Before finalising any section, show the full revised section. Wait for explicit confirmation or correction — never apply changes the user has not seen.
6. **Delta summary.** After each round of revisions: "Round N: changed [sections], added [X], removed [Y]."
7. **Reader Testing.** Predict 5–10 questions a target reader would ask. Spawn a scoped sub-agent that receives only the finished doc and the questions — no source files. Report its answers. If any answers fail, loop back to step 4.
8. **Finalise.** Write summary and overview sections last. Prompt the user to review the complete document before committing.
## Output format
- Markdown artifact with section headers; produced one section at a time — never as a single large dump
- Delta summary after each refinement round: "Round N: [what changed]"
- Reader Testing report: numbered question list with sub-agent answers
- Final doc at the user-specified or conventionally appropriate path
## Failure handling
- Files not named and description too vague to propose candidates → ask for specific names before reading
- Stage skipped without a logged reason → flag and require the one-sentence log before continuing
- Code behaviour is undocumentable (internal implementation detail, no public spec) → note as out-of-scope in the doc; do not invent an explanation
- Reader Testing sub-agent fails on multiple questions → surface the failures, return to step 4; do not mark complete
- Requested output is an ADR, decision doc, or architecture proposal → redirect to `grill-with-docs`; for a PRD, say no skill here produces one instead of redirecting
## Self-check
- [ ] All claims traceable to a source file or explicit user input
- [ ] No invented behaviour — unverifiable claims removed
- [ ] User approved specific files before reading
- [ ] Any stage skips logged with reason
- [ ] Full revised section shown before each confirmation gate
- [ ] Delta summary produced after each refinement round
- [ ] Reader Testing completed with scoped sub-agent (doc + questions only)
- [ ] Summary/overview written last
- [ ] User prompted to review before committing

9
plugins/bin/skills/zoom-out/SKILL.md
View File

@@ -1,9 +0,0 @@
---
name: zoom-out
description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
disable-model-invocation: true
metadata:
version: "1.0.1"
---
I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary.

20
plugins/core/.claude-plugin/plugin.json
View File

@@ -1,20 +0,0 @@
{
"name": "core",
"version": "1.1.2",
"description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"url": "https://git.dev.rkdr.net/Defame1297/"
},
"license": "MIT",
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core",
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core",
"keywords": [
"agents-md",
"documentation",
"audit",
"provider-adapter",
"governance"
]
}

20
plugins/core/.github/plugin/plugin.json vendored
View File

@@ -1,20 +0,0 @@
{
"name": "core",
"version": "1.1.2",
"description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"url": "https://git.dev.rkdr.net/Defame1297/"
},
"license": "MIT",
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core",
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core",
"keywords": [
"agents-md",
"documentation",
"audit",
"provider-adapter",
"governance"
]
}

46
plugins/core/skills/agentsmd-audit/SKILL.md
View File

@@ -1,46 +0,0 @@
---
name: agentsmd-audit
description: >
Use when the user wants a repo's AGENTS.md audited for secrets, structure
and drift — "is this AGENTS.md safe to commit" — or after a hand-edit
outside `agentsmd-author`.
Not converting a provider file -> `provider-adapter-author`.
Not writing AGENTS.md -> `agentsmd-author`.
allowed-tools: Bash Read
metadata:
category: docs
source_keys:
- agents-md-official
- context7-websites-agents-md
- context7-agentsmd-agents-md
- governance-secrets-hard-prohibition
version: "0.1.2"
---
## Gotchas
- Always run all three checks — this skill does a single combined pass, not staged/gated passes. Don't skip structure or drift checks just because a secrets FAIL was found.
- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope.
- Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report.
## Step 1 — Run the validators
```bash
bash scripts/validate-secrets.sh <repo-root>
bash scripts/validate-structure.sh <repo-root>
bash scripts/validate-drift.sh <repo-root>
```
Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL` lines, plus `INFO`/`SUGGESTION` where applicable, with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. Grade a manual finding the way the scripts grade theirs: a missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference.
## Step 2 — Report
Open with a coverage line:
```text
Checked: secrets · structure · drift
```
Then output only findings that were found, in this order within a repo: `### Secrets`, `### Structure`, `### Drift`. Omit a dimension heading entirely if it produced nothing — its absence confirms it passed. Report each finding verbatim as emitted by the scripts (they already carry file:line, Why/Fix or Note).
Close with a `## Result` block holding one line: `PASS`, `PASS (N suggestions)`, or `FAIL (N fails · M suggestions)`, each optionally followed by ` · P info`. Omit the suggestion count when there are none, and omit `· P info` when there are none. INFO and SUGGESTION findings are observational — they never flip PASS to FAIL. Do not fix anything — this skill reports and proposes only. Point the user to `agentsmd-author` to apply fixes.

33
plugins/core/skills/agentsmd-audit/references/sources.md
View File

@@ -1,33 +0,0 @@
# Sources
## agents-md-official
- **URL:** https://agents.md/
- **Description:** Official agents.md website — format spec, common-sections checklist, precedence rules (nearest-file-wins, no merge across files), monorepo nesting patterns
- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
- **Contributing files:** SKILL.md
- **Status:** `extracted`
## context7-websites-agents-md
- **URL:** context7:/websites/agents_md
- **Description:** Context7 index of the official agents.md website — overview, governance, cross-tool compatibility, configuration examples
- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
- **Contributing files:** SKILL.md
- **Status:** `extracted`
## context7-agentsmd-agents-md
- **URL:** context7:/agentsmd/agents.md
- **Description:** Context7 index of the agentsmd/agents.md repository — format spec, nested monorepo patterns, file structure examples
- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
- **Contributing files:** SKILL.md
- **Status:** `extracted`
## governance-secrets-hard-prohibition
- **URL:** (org convention — not a plugin research corpus entry)
- **Description:** Hard prohibition on placing secrets, API keys, tokens, or credentials in code, config, prompts, or any output. Grounds the secrets/credentials check in `scripts/validate-secrets.sh` and Step 1 of SKILL.md — AGENTS.md is committed content, so an embedded real secret is a hard-prohibition violation, not a style nit.
- **Research doc:** core/instructions/governance.md (org convention file, not a plugin research corpus entry; content is inlined here since plugins must be self-contained and this file may not exist wherever the plugin is installed)
- **Contributing files:** SKILL.md
- **Status:** `extracted`

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

@@ -1,11 +0,0 @@
# scripts/
Deterministic validators this skill shells out to instead of relying on LLM judgment for mechanical checks.
| File | Purpose |
|------|---------|
| `validate-secrets.sh` | Scans every AGENTS.md file (root + nested) for embedded secrets, API keys, tokens, and connection strings |
| `validate-structure.sh` | Checks for empty/placeholder content, the common-sections checklist, and nested-vs-root duplication |
| `validate-drift.sh` | Resolves referenced npm/make commands and file paths against the actual repo state |
All three take a single `<repo-root>` argument, print `FAIL`/`INFO`/`SUGGESTION` findings to stdout, and exit non-zero only on FAIL.

137
plugins/core/skills/agentsmd-audit/scripts/validate-drift.sh
View File

@@ -1,137 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<EOF
Usage: validate-drift.sh <repo-root>
Check every AGENTS.md file in a repo (root and nested) for drift: package
manager scripts and file paths referenced in the text that no longer exist
in the repo. Catches the failure mode that matters most in practice — an
agent running a documented command that was renamed or deleted.
Arguments:
repo-root Path to the repository root to scan.
Exit codes:
0 No FAIL findings (INFO may still be printed, e.g. no package.json found)
1 One or more FAIL findings
EOF
}
if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
usage
exit 0
fi
if [[ $# -lt 1 ]]; then
echo "Error: repo-root is required." >&2
echo "" >&2
usage >&2
exit 1
fi
python3 -u - "$1" <<'PYTHON'
import sys
import os
import re
import json
repo_root = os.path.abspath(sys.argv[1])
if not os.path.isdir(repo_root):
print(f"Error: '{repo_root}' is not a directory.", file=sys.stderr)
sys.exit(1)
EXCLUDE_DIRS = {".git", "node_modules", "vendor", ".venv", "venv", "dist", "build"}
def find_agents_md(root):
results = []
for dirpath, dirnames, filenames in os.walk(root):
dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS and not d.startswith(".")]
for fname in filenames:
if fname == "AGENTS.md":
results.append(os.path.join(dirpath, fname))
return sorted(results)
def load_package_scripts(root):
pkg_path = os.path.join(root, "package.json")
if not os.path.isfile(pkg_path):
return None
try:
with open(pkg_path, encoding="utf-8") as f:
data = json.load(f)
except (json.JSONDecodeError, OSError):
return None
return set(data.get("scripts", {}).keys())
def load_make_targets(root):
make_path = os.path.join(root, "Makefile")
if not os.path.isfile(make_path):
return None
with open(make_path, encoding="utf-8", errors="replace") as f:
content = f.read()
return set(re.findall(r'(?m)^([a-zA-Z0-9_-]+)\s*:(?!=)', content))
NPM_RUN_RE = re.compile(r'\b(?:npm|pnpm|yarn)\s+run\s+([a-zA-Z0-9:_-]+)')
MAKE_RE = re.compile(r'\bmake\s+([a-zA-Z0-9_-]+)')
# Backticked relative file paths, e.g. `scripts/bootstrap.sh`, `src/index.ts`.
# Requires a path separator and file extension to avoid matching bare commands/words.
PATH_RE = re.compile(r'`([A-Za-z0-9_.\-]+(?:/[A-Za-z0-9_.\-]+)+\.[A-Za-z0-9]+)`')
has_fail = False
package_scripts = load_package_scripts(repo_root)
make_targets = load_make_targets(repo_root)
for fpath in find_agents_md(repo_root):
rel = os.path.relpath(fpath, repo_root)
with open(fpath, encoding="utf-8", errors="replace") as f:
content = f.read()
for m in NPM_RUN_RE.finditer(content):
script_name = m.group(1)
if package_scripts is None:
print(f"INFO Cannot verify referenced script '{script_name}' — {rel}")
print(f" Note: AGENTS.md references an npm/pnpm/yarn script, but no package.json was found at the repo root to check it against.")
print()
elif script_name not in package_scripts:
has_fail = True
print(f"FAIL Referenced script '{script_name}' not found in package.json — {rel}")
print(f" Why: AGENTS.md tells agents to run '{script_name}', but package.json has no matching \"scripts\" entry — the command will fail.")
print(f" Fix: Update AGENTS.md to reference an existing script, or add '{script_name}' to package.json's scripts.")
print()
for m in MAKE_RE.finditer(content):
target_name = m.group(1)
if make_targets is None:
print(f"INFO Cannot verify referenced make target '{target_name}' — {rel}")
print(f" Note: AGENTS.md references a make target, but no Makefile was found at the repo root to check it against.")
print()
elif target_name not in make_targets:
has_fail = True
print(f"FAIL Referenced make target '{target_name}' not found in Makefile — {rel}")
print(f" Why: AGENTS.md tells agents to run 'make {target_name}', but the Makefile has no matching target — the command will fail.")
print(f" Fix: Update AGENTS.md to reference an existing target, or add '{target_name}' to the Makefile.")
print()
file_dir = os.path.dirname(fpath)
for m in PATH_RE.finditer(content):
candidate = m.group(1)
resolved = (
os.path.isfile(os.path.join(repo_root, candidate))
or os.path.isfile(os.path.join(file_dir, candidate))
or os.path.isdir(os.path.join(repo_root, candidate))
or os.path.isdir(os.path.join(file_dir, candidate))
)
if not resolved:
has_fail = True
print(f"FAIL Referenced path '{candidate}' does not exist — {rel}")
print(f" Why: AGENTS.md points agents to '{candidate}', but it isn't present in the repo (checked relative to repo root and to the AGENTS.md's own directory).")
print(f" Fix: Update AGENTS.md to reference the correct path, or restore/create '{candidate}'.")
print()
if has_fail:
sys.exit(1)
sys.exit(0)
PYTHON

120
plugins/core/skills/agentsmd-audit/scripts/validate-secrets.sh
View File

@@ -1,120 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<EOF
Usage: validate-secrets.sh <repo-root>
Scan every AGENTS.md file in a repo (root and nested) for embedded secrets,
API keys, tokens, or connection strings. AGENTS.md is committed content —
real credentials in it are a hard-prohibition violation, not a style nit.
Placeholders (<your-key>, \$ENV_VAR, YOUR_TOKEN_HERE, example.com, etc.) are
not flagged.
Arguments:
repo-root Path to the repository root to scan.
Exit codes:
0 No findings
1 One or more FAIL findings
EOF
}
if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
usage
exit 0
fi
if [[ $# -lt 1 ]]; then
echo "Error: repo-root is required." >&2
echo "" >&2
usage >&2
exit 1
fi
python3 -u - "$1" <<'PYTHON'
import sys
import os
import re
repo_root = os.path.abspath(sys.argv[1])
if not os.path.isdir(repo_root):
print(f"Error: '{repo_root}' is not a directory.", file=sys.stderr)
sys.exit(1)
EXCLUDE_DIRS = {".git", "node_modules", "vendor", ".venv", "venv", "dist", "build"}
def find_agents_md(root):
results = []
for dirpath, dirnames, filenames in os.walk(root):
dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS and not d.startswith(".")]
for fname in filenames:
if fname == "AGENTS.md":
results.append(os.path.join(dirpath, fname))
return sorted(results)
PLACEHOLDER_RE = re.compile(
r'(?i)(your[_-]|my[_-]|example|xxx+|placeholder|changeme|<[^>]+>|\$\{|\$[A-Z_][A-Z0-9_]*|\.\.\.|redacted)'
)
PATTERNS = [
("AWS access key ID", re.compile(r'AKIA[0-9A-Z]{16}')),
("Private key block", re.compile(r'-----BEGIN [A-Z ]*PRIVATE KEY-----')),
("GitHub token", re.compile(r'gh[pousr]_[A-Za-z0-9]{36,}')),
("Slack token", re.compile(r'xox[baprs]-[A-Za-z0-9-]{10,}')),
("GitLab token", re.compile(r'glpat-[A-Za-z0-9_-]{20,}')),
("Generic API-style secret token", re.compile(r'\bsk-[A-Za-z0-9]{20,}\b')),
(
"Credential-bearing connection string",
re.compile(r'[a-zA-Z][a-zA-Z0-9+.-]*://[^:@/\s]+:[^@/\s]+@[^\s\'"]+'),
),
(
"Assigned secret/password/token literal",
re.compile(
r'(?i)\b(api[_-]?key|secret|token|password|passwd|pwd|access[_-]?key)\b'
r'\s*[:=]\s*[\'"]?([A-Za-z0-9+/_.\-]{12,})[\'"]?'
),
),
]
findings = []
def emit_fail(desc, fpath, lineno, why, fix):
findings.append((desc, fpath, lineno, why, fix))
for fpath in find_agents_md(repo_root):
rel = os.path.relpath(fpath, repo_root)
with open(fpath, encoding="utf-8", errors="replace") as f:
lines = f.readlines()
for i, line in enumerate(lines, start=1):
for label, pattern in PATTERNS:
m = pattern.search(line)
if not m:
continue
# Scope the placeholder allowlist to the matched secret-candidate
# substring only. Checking the whole line would let an unrelated
# placeholder-looking token elsewhere on the line (e.g. in a
# trailing comment) suppress detection of a real credential.
value = m.group(0)
if PLACEHOLDER_RE.search(value):
continue
emit_fail(
f"Possible {label}",
f"{rel}:{i}",
i,
"AGENTS.md is committed content; this line matches a real-looking credential pattern rather than a placeholder.",
"Remove the embedded credential and replace it with an environment variable reference or placeholder (e.g. $API_KEY, <your-token>).",
)
break
if not findings:
sys.exit(0)
for desc, fpath, _lineno, why, fix in findings:
print(f"FAIL {desc} — {fpath}")
print(f" Why: {why}")
print(f" Fix: {fix}")
print()
sys.exit(1)
PYTHON

118
plugins/core/skills/agentsmd-audit/scripts/validate-structure.sh
View File

@@ -1,118 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<EOF
Usage: validate-structure.sh <repo-root>
Check every AGENTS.md file in a repo (root and nested) for structural
completeness against the agents.md spec's common-sections checklist
(setup/build, code style, testing, security, commit/PR conventions).
Missing individual sections are informational (not every repo needs every
section) — only an empty or entirely unfilled file is a hard failure.
Arguments:
repo-root Path to the repository root to scan.
Exit codes:
0 No FAIL findings (INFO/SUGGESTION may still be printed)
1 One or more FAIL findings
EOF
}
if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
usage
exit 0
fi
if [[ $# -lt 1 ]]; then
echo "Error: repo-root is required." >&2
echo "" >&2
usage >&2
exit 1
fi
python3 -u - "$1" <<'PYTHON'
import sys
import os
import re
PLACEHOLDER_RE = re.compile(r'(?i)FILL IN:|TODO:\s*write|lorem ipsum')
COMMON_SECTIONS = [
("setup/build commands", re.compile(r'(?im)^#{1,3}\s*(setup|install|build|getting started)')),
("code style", re.compile(r'(?im)^#{1,3}\s*(code style|style guide|conventions)')),
("testing instructions", re.compile(r'(?im)^#{1,3}\s*(test|testing)')),
("security considerations", re.compile(r'(?im)^#{1,3}\s*security')),
("commit/PR conventions", re.compile(r'(?im)^#{1,3}\s*(commit|pr|pull request)')),
]
repo_root = os.path.abspath(sys.argv[1])
if not os.path.isdir(repo_root):
print(f"Error: '{repo_root}' is not a directory.", file=sys.stderr)
sys.exit(1)
EXCLUDE_DIRS = {".git", "node_modules", "vendor", ".venv", "venv", "dist", "build"}
def find_agents_md(root):
results = []
for dirpath, dirnames, filenames in os.walk(root):
dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS and not d.startswith(".")]
for fname in filenames:
if fname == "AGENTS.md":
results.append(os.path.join(dirpath, fname))
return sorted(results)
has_fail = False
file_contents = {} # rel path -> content, for the duplication pass below
for fpath in find_agents_md(repo_root):
rel = os.path.relpath(fpath, repo_root)
with open(fpath, encoding="utf-8", errors="replace") as f:
content = f.read()
file_contents[rel] = content
if not content.strip():
has_fail = True
print(f"FAIL AGENTS.md is empty — {rel}")
print(" Why: An empty file provides no instructions and gives agents nothing to act on.")
print(" Fix: Add at least a project overview and setup/test commands, per the agents.md common-sections checklist.")
print()
continue
if PLACEHOLDER_RE.search(content):
has_fail = True
print(f"FAIL Unfilled placeholder content — {rel}")
print(" Why: A 'FILL IN:' or template stub left in place means the file has no repo-specific instructions yet.")
print(" Fix: Replace the placeholder with real, repo-specific content.")
print()
continue
for label, pattern in COMMON_SECTIONS:
if not pattern.search(content):
print(f"INFO No {label} section — {rel}")
print(f" Note: The agents.md common-sections checklist includes {label}; not every repo needs every section, but confirm this omission is deliberate.")
print()
# --- Nested-vs-root duplication check ---
root_content = file_contents.get("AGENTS.md")
if root_content:
root_lines = {ln.strip() for ln in root_content.splitlines() if ln.strip()}
for rel, content in file_contents.items():
if rel == "AGENTS.md":
continue
nested_lines = [ln.strip() for ln in content.splitlines() if ln.strip()]
if not nested_lines:
continue
overlap = sum(1 for ln in nested_lines if ln in root_lines)
ratio = overlap / len(nested_lines)
if ratio >= 0.7:
print(f"SUGGESTION Nested AGENTS.md largely duplicates the root file — {rel}")
print(f" Why: {ratio:.0%} of this file's content lines already appear in the root AGENTS.md; per the spec's nearest-file-wins precedence, nested files don't inherit from the root, but they also shouldn't just restate it.")
print(f" Fix: Trim {rel} down to only what's specific to this package/directory.")
print()
if has_fail:
sys.exit(1)
sys.exit(0)
PYTHON

43
plugins/core/skills/agentsmd-author/SKILL.md
View File

@@ -1,43 +0,0 @@
---
name: agentsmd-author
description: >
Use when the user wants a repo's AGENTS.md written or updated, root or
nested, including "document this for AI coding tools". Writes only verified
conventions. Not review-only -> `agentsmd-audit`. Not converting CLAUDE.md ->
`provider-adapter-author`.
allowed-tools: Bash Read Write Edit
metadata:
category: docs
source_keys:
- agents-md-official
- context7-websites-agents-md
- context7-agentsmd-agents-md
version: "0.1.2"
---
## Gotchas
- Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (`package.json` scripts, a `Makefile` target, a CI workflow step, a README). If you can't verify a command, don't include it.
- Never write to a provider file yourself, in any circumstance: `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md` and their equivalents are `provider-adapter-author`'s to own. That holds even when the user asks for one in the same breath as AGENTS.md, and even when the file is merely stale or missing a pointer rather than duplicating anything. Detect it and hand off.
## Step 1 — Explore the target repo
Before writing anything, gather real facts: package manager and scripts (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.), a `Makefile` or task runner, CI config (`.github/workflows/`, etc.) for the commands it actually runs, linter/formatter config files, and any existing docs (`README.md`, existing `AGENTS.md`) describing conventions. Note whether any subdirectory looks like its own package with a different stack.
## Step 2 — Decide placement
- No `AGENTS.md` at the repo root yet → create one there first, covering whole-repo conventions.
- A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested `AGENTS.md` there, scoped to what's different. Convenience is not a reason to create one — without a distinct stack you are duplicating content the root already covers. **Don't repeat root-level content** in a nested file: the nearest-file-wins rule means it is read alone, never merged back with the root.
- Otherwise → update the existing file(s) in place.
## Step 3 — Write or update
AGENTS.md has no required schema. Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists, because a thin accurate file beats a padded generic one. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
## Step 4 — Check for an existing provider file
Look for `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, or similar in the target repo. If one exists, invoke the `provider-adapter-author` skill on it to reconcile — whether it duplicates content the AGENTS.md you just wrote/updated now owns, or is merely stale or missing a pointer to it. Never edit it yourself in either case.
## Step 5 — Audit and report
Invoke the `agentsmd-audit` skill on the target repo root — its validators take a `<repo-root>` and walk the tree for every AGENTS.md themselves; there is no per-file entry point. This closeout is mandatory, not optional, even when the change looks trivial — never sign the work off on your own judgment. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.

118
plugins/core/skills/agentsmd-author/references/content-guide.md
View File

@@ -1,118 +0,0 @@
---
source_keys:
- agents-md-official
- context7-websites-agents-md
- context7-agentsmd-agents-md
---
# What good AGENTS.md content looks like
AGENTS.md has no required schema — there's no field to fill in, only sections that either
earn their place or don't. Agents treat this file as a set of live directives, not
documentation: they will actually run the commands it lists and fix failures before
finishing a task. That means a wrong or stale line is worse than a missing one. Verify
every command against something real in the repo before writing it down.
## Section-by-section guidance
**Setup / build commands** — the install and dev-server commands, exactly as they appear
in `package.json` scripts, a `Makefile`, or a `Cargo.toml`/`pyproject.toml` equivalent. One
line per command, each with a one-clause note on what it does if the name alone isn't
obvious. Skip this section if there's genuinely nothing beyond "clone and run" — don't pad
it with a restated `git clone`.
**Code style** — only conventions that aren't already enforced by a linter/formatter config
the agent will pick up on its own (a `.eslintrc`, `rustfmt.toml`, etc. speaks for itself).
Write down the conventions that live only in people's heads: naming patterns, module
boundaries, patterns to avoid, anything a linter can't catch. If the repo has no
undocumented conventions beyond what tooling enforces, skip this section.
**Testing instructions** — the exact command(s) to run the suite, where to find
per-package or per-workflow test configuration (e.g. `.github/workflows/`), and any
non-obvious requirement (a service that must be running, an env var that must be set).
State plainly that the agent should run tests before considering a change done and fix
failures — don't leave this implicit.
**Security considerations** — only repo-specific hazards: a data-handling boundary, a
credential pattern to never hardcode, a destructive command that needs a confirmation
step. Do not restate general security advice ("don't commit secrets") that any agent
already assumes — that's padding, not a directive.
**Commit / PR conventions** — the title/format convention if one exists (e.g. a
Conventional Commits type prefix, a ticket-number requirement), and any check that must
pass before a PR is opened (lint, test, type-check). Point at the real command, not
"make sure it passes."
**Dev environment tips** — the handful of things that save real time and are easy to miss:
how to jump to a specific package in a monorepo without `ls`-ing around, how to register a
new package so the toolchain sees it, where to look up a canonical name/id. This section
is for genuine friction points observed in this repo, not generic advice.
## What separates useful content from padding
A useful section names a real file, command, or path that exists in this repo right now.
A padded section could be pasted into any repo unchanged and still "make sense" — that's
the tell. If a sentence would read the same in a different codebase, it doesn't belong.
Prefer four accurate lines over twelve generic ones.
## Worked example (minimal project)
```markdown
# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`
## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible
## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Check the `name` field inside each package's `package.json` to confirm the right name.
## Testing instructions
- Find the CI plan in the `.github/workflows` folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- Fix any test or type errors until the whole suite is green.
- Add or update tests for the code you change, even if nobody asked.
## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.
```
Every line above names a real command or path — that's the standard to hold this repo's
version to, not the specific tooling shown (a Python/Cargo/Go repo's AGENTS.md should look
nothing like this one in its specifics, only in how concrete each line is).
## Monorepo / nested placement
```
my-monorepo/
├── AGENTS.md # Root-level: applies to the whole repo
├── packages/
│ ├── api/
│ │ └── AGENTS.md # API-specific instructions; overrides root for this package
│ ├── web/
│ │ └── AGENTS.md # Web app-specific instructions
│ └── shared/
│ └── AGENTS.md # Shared library instructions
```
Precedence rule: the file nearest the edited path wins. Nested files are **not** merged
with the root file — an agent editing inside `packages/api/` reads only
`packages/api/AGENTS.md`, never the root file in addition. Consequences:
- A nested file must stand alone. Don't write "also see the root file" — write what the
agent needs, full stop.
- Don't duplicate root content in a nested file "just in case." If a nested file repeats
root-level setup instructions verbatim, that's a sign it shouldn't exist as a separate
file at all — the subtree isn't actually different enough to warrant one.
- Only create a nested file when the subtree has a genuinely different stack, build tool,
or convention than the root (see `SKILL.md` Step 2 for the placement decision itself).

25
plugins/core/skills/agentsmd-author/references/sources.md
View File

@@ -1,25 +0,0 @@
# Sources
## agents-md-official
- **URL:** https://agents.md/
- **Description:** Official agents.md website — format spec, common-sections checklist, precedence rules (nearest-file-wins, no merge across files), monorepo nesting patterns
- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
- **Contributing files:** SKILL.md, references/content-guide.md
- **Status:** `extracted`
## context7-websites-agents-md
- **URL:** context7:/websites/agents_md
- **Description:** Context7 index of the official agents.md website — overview, governance, cross-tool compatibility, configuration examples
- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
- **Contributing files:** SKILL.md, references/content-guide.md
- **Status:** `extracted`
## context7-agentsmd-agents-md
- **URL:** context7:/agentsmd/agents.md
- **Description:** Context7 index of the agentsmd/agents.md repository — format spec, nested monorepo patterns, file structure examples
- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
- **Contributing files:** SKILL.md, references/content-guide.md
- **Status:** `extracted`

52
plugins/core/skills/provider-adapter-author/SKILL.md
View File

@@ -1,52 +0,0 @@
---
name: provider-adapter-author
description: >
Use when a provider file (CLAUDE.md, .cursor rules, copilot-instructions)
duplicating the repo's AGENTS.md should be cut to a thin adapter — "make
CLAUDE.md just import AGENTS.md".
Not writing the AGENTS file -> `agentsmd-author`.
Not auditing the AGENTS file -> `agentsmd-audit`.
allowed-tools: Bash Read Edit Write
metadata:
category: docs
source_keys:
- adr-0002-0003-two-tier-claude-md
version: "0.1.1"
---
## Gotchas
- Assume a provider has no cross-file import mechanism until you have confirmed it has one. Claude Code is the exception, not the rule: a `CLAUDE.md` may consist of nothing but `@path` lines, while the same `@AGENTS.md` line in a Cursor rule or a Copilot instructions file is inert text no tool resolves. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for those providers.
- Works standalone or composed-into by `agentsmd-author` — behave identically either way; do not assume a caller skill exists. Detect the provider file, confirm `AGENTS.md`, and run the closeout validator yourself in both cases (`references/provider-matrix.md`).
## Step 1 — Detect
Find the provider instruction file to convert. Before searching, read `references/provider-matrix.md` — skip it only when the target is already a known root `CLAUDE.md`, which is the common case.
Then confirm `AGENTS.md` exists at the repo root. If it does not, stop and tell the user to run `agentsmd-author` first — there is nothing to adapt to.
## Step 2 — Diff and rewrite
Read the provider file and `AGENTS.md` side by side. Separate the provider file's content into two buckets: lines that restate what `AGENTS.md` already owns (universal rules, conventions, project overview) versus lines that are genuinely provider-specific (tool syntax, IDE behavior, model-specific instructions). Rewrite the provider file:
- **Providers with import syntax** (Claude Code): replace the redundant bucket with an `@AGENTS.md` (or correct relative path) import on a line of its own, keep the provider-specific bucket below it. An import folded into a sentence is not the thin-adapter shape and `scripts/validate-adapter.sh` will not credit it — nor one inside a code fence, an indented block, or an HTML comment, nor one whose path does not resolve to a real, non-empty file on disk.
- **Providers without import syntax** (Cursor, Copilot, etc.): replace the redundant bucket with a short sentence pointing at `AGENTS.md` ("See AGENTS.md at the repo root for ..."), keep the provider-specific bucket. A bare or negated mention is not a pointer and will not be credited.
The provider file is the only file this skill ever writes. Never create or edit `AGENTS.md` — not in this step, not in any step, whatever the payoff looks like.
Strip only what is genuinely redundant. Provider-specific material stays even when it is short — the goal is thin, not empty.
## Step 3 — Self-validate
Run the bundled check before finishing — this is the skill's own closeout gate; there is no separate paired audit skill for this concern:
```bash
bash scripts/validate-adapter.sh [--no-import-syntax] [--max-lines N] <adapter-file> <agents-md-file>
```
Fix any `FAIL` by editing the provider file, and re-run until it exits `0`. Exits `2` and `3` are not `FAIL`s and nothing was graded under either, so neither is a reason to touch the adapter: `2` means the invocation or the input is wrong (a bad, missing, or extra argument, an unknown option, or a file that is not UTF-8), and `3` means a named file exists but could not be read.
## Step 4 — Report
State which file was converted, what was removed versus kept, and the validator's final result.

32
plugins/core/skills/provider-adapter-author/references/provider-matrix.md
View File

@@ -1,32 +0,0 @@
---
source_keys:
- adr-0002-0003-two-tier-claude-md
---
# Known provider instruction files
Which files to look for when detecting a provider-specific instruction file, whether each provider
resolves a cross-file import, and what a thin adapter therefore looks like for it.
| Provider | File(s) | Import syntax | Thin adapter shape | Validator flag |
|---|---|---|---|---|
| Claude Code | `CLAUDE.md` at the repo root, plus any deployed copies | Yes — `@path` lines, e.g. `@AGENTS.md` | One or more `@` import lines; no other content is required | none |
| Cursor | `.cursor/rules/*.mdc` | No | A short sentence pointing at `AGENTS.md`, plus the rule's own frontmatter and provider-specific body | `--no-import-syntax` |
| GitHub Copilot | `.github/copilot-instructions.md` | No | A short sentence pointing at `AGENTS.md`, plus Copilot-only instructions | `--no-import-syntax` |
| Anything else | tool-specific instruction file at whatever path the tool documents | Assume no | Text pointer, as above | `--no-import-syntax` |
A provider not listed here is not evidence it has an import mechanism. Confirm against that tool's
own documentation before emitting an `@`-style line; an unresolved import reads as literal text and
silently drops every rule the adapter was supposed to defer to.
Detection is a search, not a lookup: a repo may hold more than one of these, and each one converts
independently against the same `AGENTS.md`.
## Standalone and composed runs behave identically
This skill is reached two ways: invoked directly by a user, and composed into by `agentsmd-author`
once it has written or updated the repo's `AGENTS.md`. Behave identically either way — do not
assume a caller skill exists. Detect the provider file yourself, confirm `AGENTS.md` yourself, and
run the closeout validator yourself, rather than treating any step as already done by the caller or
as something the caller will do afterwards. No handshake exists to rely on, and no state is
passed in beyond the file paths.

9
plugins/core/skills/provider-adapter-author/references/sources.md
View File

@@ -1,9 +0,0 @@
# Sources
## adr-0002-0003-two-tier-claude-md
- **URL:** (in-repo precedent — not an external source or plugin research corpus entry)
- **Description:** This repo's own two-tier CLAUDE.md/AGENTS.md pattern: AGENTS.md is the provider-agnostic source of always-on rules; provider-specific files (CLAUDE.md) become thin adapters that import it (`@AGENTS.md` plus provider-specific additions). Grounds this skill's entire adapter-conversion design — the "thin adapter" shape, the `@`-import convention, and the size/duplication expectations enforced by `scripts/validate-adapter.sh`.
- **Research doc:** docs/adr/0002-two-tier-claude-md.md, docs/adr/0003-agents-md-provider-agnostic-entry-point.md, providers/claude-code/CLAUDE.md (in-repo ADRs and a live example, not a plugin research corpus entry; referenced here since this skill's design is modeled directly on an existing implementation rather than external research)
- **Contributing files:** SKILL.md, references/provider-matrix.md
- **Status:** `extracted`

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

@@ -1,28 +0,0 @@
# scripts/
Deterministic self-check this skill shells out to instead of relying on LLM judgment for a mechanical check.
| File | Purpose |
|------|---------|
| `validate-adapter.sh` | Checks a rewritten provider file (CLAUDE.md, etc.) has a working reference to AGENTS.md, doesn't duplicate its content, and stays under a thin-file line threshold |
Takes exactly `<adapter-file> <agents-md-file>`, with optional `--no-import-syntax` and `--max-lines N` flags (also accepted as `--max-lines=N`). A third positional argument or an unknown option is an error, not something quietly ignored.
## What counts as a reference to AGENTS.md
Both modes require the named path to be a real path segment ending in `AGENTS.md` — `AGENTS.md` or `…/AGENTS.md`, not `NOTAGENTS.md` — that resolves on disk, relative to the adapter file, to a non-empty file. An adapter deferring to a path that is not there defers to nothing, so the check has to touch the disk rather than pattern-match the line.
A reference only counts where something would actually resolve it. A line inside a fenced code block, an indented code block, or an HTML comment is not credited in either mode: Claude Code resolves an import in none of those, so a fenced `@AGENTS.md` is the silent-drop failure this gate exists to catch, not a pass.
Default mode wants a real import: `@AGENTS.md` alone on its own line, indented no more than three spaces. `--no-import-syntax` wants a prose pointer that reads as one — the sentence naming `AGENTS.md` must carry a deference cue (see, read, refer to, documented in, conventions, …) and must not be negated. `Do NOT read AGENTS.md; it is obsolete.` and `We deleted AGENTS.md last year.` name the file while pointing the reader away from it, and neither is a pointer.
## Exit codes
The distinction matters because the skill's closeout tells the agent to fix any non-zero exit by editing the provider file. That is right for exactly one of these.
| Code | Meaning | What to do |
|------|---------|------------|
| `0` | Passes every check | Nothing |
| `1` | One or more `FAIL` findings printed to stdout — empty adapter, no working reference to AGENTS.md, excessive duplication, or not thin | Edit the provider file |
| `2` | Usage or input error: a bad, missing, or extra argument, an unknown option, a path that is not a file, or a file that is not UTF-8. Nothing was graded, so there is no `FAIL` line | Fix the invocation or the file's encoding — do not edit the adapter |
| `3` | A named input file exists but could not be read (permissions, I/O error). Nothing was graded and the adapter's contents are unknown | Fix the file's readability — do not edit the adapter |

496
plugins/core/skills/provider-adapter-author/scripts/validate-adapter.sh
View File

@@ -1,496 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<EOF
Usage: validate-adapter.sh [--no-import-syntax] [--max-lines N] <adapter-file> <agents-md-file>
Self-check gate for provider-adapter-author. Checks that a rewritten
provider-specific instruction file (CLAUDE.md, .cursor/rules/*.mdc,
copilot-instructions.md, etc.) is actually a thin adapter over AGENTS.md,
not a duplicate copy of it.
Arguments:
adapter-file Path to the provider-specific file to check.
agents-md-file Path to the AGENTS.md file it should defer to.
Exactly two positional arguments are accepted. Extra ones are rejected
rather than ignored: a third path silently graded nothing but the first
two, so a typo'd invocation passed against the wrong file.
Options:
--no-import-syntax The target provider has no native cross-file import
mechanism. Require a plain-text pointer line naming
"AGENTS.md" instead of an @import-style line; an
@AGENTS.md line alone does not satisfy it, because
such a provider never resolves it. Without this flag
an actual @import line is required, and naming
AGENTS.md in prose alone does not satisfy it.
--max-lines N Max non-blank lines allowed in the adapter file before
it's considered no longer "thin". Must be a
non-negative integer. Default: 60.
--help, -h Show this help and exit 0.
-- End of options; every later argument is positional.
Both flags also accept the --flag=value form (--max-lines=40). An unknown
option is reported as an unknown option, not as a missing file.
What counts as a reference:
In both modes the named path must be a real path segment ending in
AGENTS.md ("AGENTS.md" or ".../AGENTS.md" — not NOTAGENTS.md), and it must
resolve on disk, relative to the adapter file, to a non-empty file. An
adapter deferring to a path that is not there defers to nothing.
A mention inside a fenced code block, an indented code block, or an HTML
comment is not credited in either mode. Nothing resolves those, so an
adapter whose only "import" is fenced silently defers to nothing.
With --no-import-syntax the pointer must read as a pointer: the sentence
naming AGENTS.md has to carry a deference cue (see, read, refer to,
documented in, conventions, ...) and must not be a negation ("do not read
AGENTS.md", "we deleted AGENTS.md"). A bare mention is not a pointer.
Exit codes:
0 Adapter file passes all checks
1 One or more checks failed (empty file, no reference to AGENTS.md,
excessive duplication, or file too long)
2 Usage or input error — a bad, missing, or extra argument, an unknown
option, a path that is not a file, or a file that is not UTF-8. Nothing
was graded, so there is no FAIL line and no adapter edit to make: fix
the invocation or the file's encoding and re-run. Kept distinct from 1
because the skill's own closeout tells the agent to fix every non-zero
exit by editing the provider file, which for a mistyped flag edits the
wrong file forever.
3 A named input file exists but could not be read (permissions, a
directory swapped in mid-run, I/O error). Also not a FAIL: nothing was
graded and the adapter's contents are unknown, so editing it is
guesswork. Fix the file's readability and re-run.
EOF
}
NO_IMPORT_SYNTAX=0
MAX_LINES=60
ARGS=()
END_OF_OPTS=0
require_int() {
# $1 = the value to validate
if [[ ! "$1" =~ ^[0-9]+$ ]]; then
echo "Error: --max-lines expects a non-negative integer, got '$1'." >&2
exit 2
fi
}
while [[ $# -gt 0 ]]; do
if [[ $END_OF_OPTS -eq 1 ]]; then
ARGS+=("$1")
shift
continue
fi
case "$1" in
--)
END_OF_OPTS=1
shift
;;
--help|-h)
usage
exit 0
;;
--no-import-syntax)
NO_IMPORT_SYNTAX=1
shift
;;
--no-import-syntax=*)
echo "Error: --no-import-syntax is a flag and takes no value (got '$1')." >&2
exit 2
;;
--max-lines)
if [[ $# -lt 2 ]]; then
echo "Error: --max-lines requires a value (a non-negative integer)." >&2
exit 2
fi
MAX_LINES="$2"
require_int "$MAX_LINES"
shift 2
;;
--max-lines=*)
MAX_LINES="${1#--max-lines=}"
if [[ -z "$MAX_LINES" ]]; then
echo "Error: --max-lines requires a value (a non-negative integer)." >&2
exit 2
fi
require_int "$MAX_LINES"
shift
;;
-*)
# Reported as an unknown option rather than falling through to the
# positional bucket, where it used to surface as "'--bogus' is not a
# file" — the right exit code attached to a diagnostic that sends the
# reader looking for a path they never typed.
echo "Error: unknown option '$1'." >&2
echo "" >&2
usage >&2
exit 2
;;
*)
ARGS+=("$1")
shift
;;
esac
done
if [[ ${#ARGS[@]} -lt 2 ]]; then
echo "Error: adapter-file and agents-md-file are required." >&2
echo "" >&2
usage >&2
exit 2
fi
if [[ ${#ARGS[@]} -gt 2 ]]; then
echo "Error: expected exactly 2 positional arguments (adapter-file and agents-md-file), got ${#ARGS[@]}: ${ARGS[*]}." >&2
echo "" >&2
usage >&2
exit 2
fi
python3 -u - "${ARGS[0]}" "${ARGS[1]}" "$NO_IMPORT_SYNTAX" "$MAX_LINES" <<'PYTHON'
import sys
import os
import re
adapter_path, agents_md_path, no_import_syntax, max_lines = sys.argv[1:5]
no_import_syntax = no_import_syntax == "1"
max_lines = int(max_lines)
EXIT_FAIL = 1
EXIT_USAGE = 2
EXIT_UNREADABLE = 3
if not os.path.isfile(adapter_path):
print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr)
sys.exit(EXIT_USAGE)
if not os.path.isfile(agents_md_path):
print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr)
sys.exit(EXIT_USAGE)
def read_text(path):
r"""File contents as text, UTF-8, every BOM stripped.
The BOM strip is not cosmetic. IMPORT_RE anchors on `^ {0,3}@`, and a BOM
is not whitespace in Python, so a CLAUDE.md saved by an editor that emits
one had its first line — the `@AGENTS.md` import, which is the whole
adapter — silently treated as prose. The check then said "no reference to
AGENTS.md" and told the author to add the line already sitting in front of
them. Same class of silent BOM miss recorded in scripts/skill-size-check.sh;
strip it at the reader so no later check has to know about it.
Every U+FEFF goes, not just one at offset 0. Stripping exactly the first
one left the mirror-image false FAIL for a doubled BOM (two concatenated
files, or a tool that re-adds one) and for a BOM mid-file at the head of
the import line. U+FEFF has no meaning as a character in a markdown
instruction file, so removing all of them cannot lose signal.
Decoding is strict, not errors="replace". Replacement mangles the file and
the checks then grade the mangling: a UTF-16 adapter whose first line is
`@AGENTS.md` decoded to interleaved NULs and failed as "no reference",
which is a true FAIL for a false reason and points the fix at the wrong
thing. But strict UTF-8 alone does not catch it — BOM-less UTF-16LE/BE and
UTF-32LE are *valid* UTF-8, because NUL is a legal code point, so they
decoded clean and produced exactly that false diagnosis anyway. The NUL
byte is the complete signal and is checked first: no plausible markdown
adapter contains one, and every UTF-16/32 encoding of ASCII is full of
them. A file this gate cannot read gets an encoding diagnostic and exit 2,
the same policy the ADR-0020 validators' read_text() uses.
A file that exists but cannot be read at all is neither a pass nor a FAIL —
nothing was graded — so it exits 3 rather than 1. Exit 1 sends the skill's
closeout into "fix the FAIL by editing the provider file", which for a file
it cannot open is an instruction to edit blind.
"""
try:
with open(path, "rb") as fh:
raw = fh.read()
except OSError as exc:
print(f"Error: '{path}' exists but could not be read ({exc.strerror}). "
"Nothing was checked — fix whatever is blocking the read "
"(permissions, ownership, the underlying device) and re-run; do "
"not edit the adapter on the strength of this.", file=sys.stderr)
sys.exit(EXIT_UNREADABLE)
if b"\x00" in raw:
print(f"Error: '{path}' is not valid UTF-8 — it contains NUL bytes, so "
"it is almost certainly UTF-16 or UTF-32 (with or without a BOM). "
"Re-save it as UTF-8; this check does not guess at other "
"encodings.", file=sys.stderr)
sys.exit(EXIT_USAGE)
try:
text = raw.decode("utf-8")
except UnicodeDecodeError as exc:
print(f"Error: '{path}' is not valid UTF-8 ({exc.reason} at byte "
f"{exc.start}) — re-save it as UTF-8; this check does not guess "
"at other encodings.", file=sys.stderr)
sys.exit(EXIT_USAGE)
return text.replace("\ufeff", "")
adapter_content = read_text(adapter_path)
agents_md_content = read_text(agents_md_path)
adapter_dir = os.path.dirname(os.path.abspath(adapter_path))
has_fail = False
if not adapter_content.strip():
print(f"FAIL Adapter file is empty — {adapter_path}")
print(" Why: An empty adapter carries no reference to AGENTS.md and no provider-specific content.")
print(" Fix: Add at least an import (or text pointer) to AGENTS.md.")
print()
sys.exit(EXIT_FAIL)
# --- Inert regions -----------------------------------------------------------
#
# A reference only counts where something would actually resolve it. Fenced
# code blocks, indented code blocks and HTML comments are shown to the reader
# (or hidden from them) as literal text; Claude Code resolves an @import in
# none of them. Without this, a ```-fenced `@AGENTS.md` — the exact
# copy-the-example-into-the-file mistake this gate exists to catch — exited 0
# with the adapter deferring to nothing.
#
# Indented code blocks are handled by IMPORT_RE's `^ {0,3}` instead of by the
# mask: four leading spaces is what opens an indented code block in CommonMark,
# so an import has to sit within three. The mask deliberately does not apply
# that rule to prose pointers, where four-space indentation is ordinary list
# continuation rather than code.
FENCE_RE = re.compile(r'^( {0,3})(`{3,}|~{3,})(.*)$')
COMMENT_RE = re.compile(r'<!--.*?(?:-->|\Z)', re.DOTALL)
def line_offsets(text):
"""[(char offset, line without its terminator)] over `text`."""
out = []
off = 0
for raw in text.splitlines(keepends=True):
out.append((off, raw.rstrip("\r\n")))
off += len(raw)
return out
def build_inert_mask(text, offsets):
"""Per-character flags: 1 where a reference would never be resolved."""
mask = bytearray(len(text))
fence = None # (fence char, opening run length)
for start, line in offsets:
m = FENCE_RE.match(line)
if fence is None:
if m:
fence = (m.group(2)[0], len(m.group(2)))
for i in range(start, start + len(line)):
mask[i] = 1
continue
for i in range(start, start + len(line)):
mask[i] = 1
if (m and m.group(2)[0] == fence[0]
and len(m.group(2)) >= fence[1]
and not m.group(3).strip()):
fence = None
for m in COMMENT_RE.finditer(text):
if m.start() < len(mask) and mask[m.start()]:
continue # a literal "<!--" printed inside a fence opens nothing
for i in range(m.start(), min(m.end(), len(mask))):
mask[i] = 1
return mask
# --- Reference shapes --------------------------------------------------------
#
# `\S*AGENTS\.md` had no path-separator boundary, so `@NOTAGENTS.md` and
# `@zzzAGENTS.md` counted as imports of AGENTS.md. The matched path must end in
# AGENTS.md as a whole segment.
IMPORT_RE = re.compile(r'^ {0,3}@(?P<path>\S+?)\s*$')
# A mention in prose: an optional relative path, then AGENTS.md, with no
# identifier character glued to the front (so NOTAGENTS.md does not match) and
# nothing glued to the back.
MENTION_RE = re.compile(r'(?<![0-9A-Za-z_.\-/])((?:[\w.\-~]+/)*AGENTS\.md)(?![0-9A-Za-z])')
# A pointer has to read as a pointer. `"AGENTS.md" in ln` passed
# "Do NOT read AGENTS.md; it is obsolete." and "We deleted AGENTS.md last
# year." — both of which point the reader away from the file. Require a
# deference cue in the naming sentence, and reject a negated one.
DIRECTIVE_RE = re.compile(
r'\b(see|read|refer|refers|referring|consult|consults|follow|follows|'
r'defer|defers|deferring|described|documented|documents|covered|covers|'
r'found|listed|specified|defined|governed|per|use|uses|using|apply|obey|'
r'start|check|live|lives|contains|holds|carries|inherit|inherits|import|'
r'imports|conventions|instructions|guidelines|guidance|rules|standards|'
r'reference|setup)\b', re.I)
NEGATION_RE = re.compile(
r"(\bnot\b|n't\b|\bnever\b|\bno longer\b|\bdeleted\b|\bremoved\b|"
r"\bobsolete\b|\bdeprecated\b|\bignore\b|\bignores\b|\bignoring\b|"
r"\bdisregard\b|\bsuperseded\b|\bgone\b|\bunused\b|\bstale\b)", re.I)
SENTENCE_SPLIT_RE = re.compile(r'(?<=[.;:!?])\s+')
def sentence_around(line, index):
"""(sentence of `line` containing character `index`, its start offset)."""
bounds = [0]
for m in SENTENCE_SPLIT_RE.finditer(line):
bounds.append(m.end())
bounds.append(len(line) + 1)
for i in range(len(bounds) - 1):
if bounds[i] <= index < bounds[i + 1]:
return line[bounds[i]:bounds[i + 1]], bounds[i]
return line, 0
def reads_as_pointer(line, match):
"""Does the sentence naming AGENTS.md actually point the reader at it?
The matched path is blanked out before the cues are applied. It is a
filename, not prose, and leaving it in let its own characters vote: the
perfectly ordinary `docs/does/not/exist/AGENTS.md` tripped the negation
cue on the `not` path segment, so a pointer got rejected for the wrong
reason and the near-miss line then reported the wrong diagnosis.
"""
sentence, sentence_start = sentence_around(line, match.start())
rel_start = match.start() - sentence_start
rel_end = match.end() - sentence_start
probe = sentence[:rel_start] + " AGENTS.md " + sentence[rel_end:]
if NEGATION_RE.search(probe):
return False
return bool(DIRECTIVE_RE.search(probe))
def resolve(raw_path):
"""An import/pointer path resolved the way the provider would resolve it."""
p = os.path.expanduser(raw_path)
if not os.path.isabs(p):
p = os.path.join(adapter_dir, p)
return os.path.normpath(p)
def target_problem(raw_path):
"""None if `raw_path` names a real, non-empty file; else why not."""
resolved = resolve(raw_path)
if not os.path.isfile(resolved):
return f"'{raw_path}' resolves to {resolved}, which does not exist"
try:
if os.path.getsize(resolved) == 0:
return f"'{raw_path}' resolves to {resolved}, which is empty"
with open(resolved, "rb") as fh:
if not fh.read().strip():
return f"'{raw_path}' resolves to {resolved}, which is blank"
except OSError as exc:
return f"'{raw_path}' resolves to {resolved}, which cannot be read ({exc.strerror})"
return None
def names_agents_md(path):
return path == "AGENTS.md" or path.endswith("/AGENTS.md")
offsets = line_offsets(adapter_content)
lines = [line for _, line in offsets]
mask = build_inert_mask(adapter_content, offsets)
def is_inert(abs_index):
return abs_index < len(mask) and bool(mask[abs_index])
# Lines shaped like an @AGENTS.md import, whether or not the target resolves.
# Used to exclude them from the duplication denominator and from the prose
# pointer scan, both of which only care about the shape.
import_shaped_lines = set()
# (line, raw path) for every import whose target actually resolves.
live_imports = []
# Diagnostics for imports that are the right shape but resolve to nothing.
dead_imports = []
# Imports that exist only inside a fence or an HTML comment.
inert_imports = []
for start, line in offsets:
m = IMPORT_RE.match(line)
if not m or not names_agents_md(m.group("path")):
continue
at_index = start + line.index("@")
if is_inert(at_index):
inert_imports.append(line.strip())
continue
import_shaped_lines.add(line)
problem = target_problem(m.group("path"))
if problem:
dead_imports.append(problem)
else:
live_imports.append(line)
live_pointers = []
dead_pointers = []
inert_pointers = []
mention_only = []
for start, line in offsets:
if line in import_shaped_lines:
continue
for m in MENTION_RE.finditer(line):
if is_inert(start + m.start()):
inert_pointers.append(line.strip())
continue
if not reads_as_pointer(line, m):
mention_only.append(sentence_around(line, m.start())[0].strip())
continue
problem = target_problem(m.group(1))
if problem:
dead_pointers.append(problem)
else:
live_pointers.append(line)
if no_import_syntax:
has_reference = bool(live_pointers)
near_misses = dead_pointers + [f"{d} (inside a code fence or HTML comment)" for d in inert_pointers]
near_misses += [f"'{s}' names AGENTS.md but does not point at it" for s in mention_only]
else:
has_reference = bool(live_imports)
near_misses = dead_imports + [f"'{d}' is inside a code fence or HTML comment, where no import is resolved" for d in inert_imports]
if not has_reference:
has_fail = True
print(f"FAIL Adapter has no reference to AGENTS.md — {adapter_path}")
if no_import_syntax:
print(" Why: This provider resolves no cross-file import, so the adapter must point at AGENTS.md in prose; an `@AGENTS.md` line here is inert text. The pointer has to read as a pointer and name a file that is really there — a bare or negated mention (\"we deleted AGENTS.md\") defers nothing, and neither does a mention buried in a code fence or an HTML comment.")
print(" Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\", outside any fence, naming a path that exists relative to this file.")
else:
print(" Why: A thin adapter must import AGENTS.md with an `@AGENTS.md` line of its own, indented no more than three spaces, and the path must resolve to a real non-empty file. Naming the file mid-sentence or inside backticks is prose this check will not credit; putting the line inside a ``` fence, an indented code block, or an HTML comment is worse, because nothing resolves it and it looks right.")
print(" Fix: Put `@AGENTS.md` (or the equivalent relative path) alone on its own line at the top level of the file, or pass --no-import-syntax if this provider resolves no imports.")
for miss in near_misses:
print(f" Near miss: {miss}")
print()
# --- Duplication check ---
non_import_lines = [ln for ln in lines if ln not in import_shaped_lines]
adapter_lines = [ln.strip() for ln in non_import_lines if ln.strip()]
agents_lines = {ln.strip() for ln in agents_md_content.splitlines() if ln.strip()}
if adapter_lines:
overlap = sum(1 for ln in adapter_lines if ln in agents_lines)
ratio = overlap / len(adapter_lines)
if ratio > 0.3:
has_fail = True
print(f"FAIL Adapter duplicates AGENTS.md content — {adapter_path}")
print(f" Why: {ratio:.0%} of the adapter's non-import lines already appear verbatim in AGENTS.md. A thin adapter should import shared content, not restate it.")
print(" Fix: Remove the duplicated lines and rely on the AGENTS.md import (or pointer) instead.")
print()
# --- Size check ---
non_blank_count = len([ln for ln in lines if ln.strip()])
if non_blank_count > max_lines:
has_fail = True
print(f"FAIL Adapter is not thin — {adapter_path}")
print(f" Why: {non_blank_count} non-blank lines exceeds the {max_lines}-line threshold for a thin adapter.")
print(" Fix: Delete the lines already covered by AGENTS.md; keep only genuinely provider-specific additions here.")
print()
if has_fail:
sys.exit(EXIT_FAIL)
sys.exit(0)
PYTHON

19
plugins/git/.claude-plugin/plugin.json
View File

@@ -1,19 +0,0 @@
{
"name": "git",
"version": "1.3.7",
"description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"url": "https://git.dev.rkdr.net/Defame1297/"
},
"license": "MIT",
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git",
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git",
"keywords": [
"git",
"vcs",
"commit",
"branch"
]
}

19
plugins/git/.github/plugin/plugin.json vendored
View File

@@ -1,19 +0,0 @@
{
"name": "git",
"version": "1.3.7",
"description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"url": "https://git.dev.rkdr.net/Defame1297/"
},
"license": "MIT",
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git",
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git",
"keywords": [
"git",
"vcs",
"commit",
"branch"
]
}

88
plugins/git/agents/git-orchestrate.agent.md
View File

@@ -1,88 +0,0 @@
---
name: git-orchestrate
description: Orchestrates git workflow operations for other agents. Invoke when a caller needs a multi-step or destructive git operation (rebase, force-push, branch deletion) coordinated across domain skills with safety gates, session context, and structured results.
source_keys:
- context7-git-htmldocs
- git-scm-docs
- git-scm-worktree-docs
- git-scm-submodule-docs
- git-scm-remote-docs
- conventional-commits-spec
---
You are the orchestrator for the git plugin—a composable workflow dispatcher designed for other agents to invoke multi-step git operations reliably. Your one job is routing and safety-gating: you do not execute git logic yourself, you delegate to domain skills and enforce confirmation on destructive operations.
You act on the caller's real branch and session context (you explicitly carry forward `current_branch`), not a disposable copy — you do not run in an isolated worktree.
**Scope:** this orchestrator routes git-object operations only (commits, branches, worktrees, remotes, submodules, history). `pc-author` and `pc-run` (pre-commit config authoring and hook execution) are intentionally not routed here — they operate on `.pre-commit-config.yaml` and hook installation, not git objects. `git-workflow` is also not routed here, but for a different reason than `pc-author`/`pc-run`: it is a human-facing conversational wrapper for all git operation types (commits, branches, history, submodules, worktrees, remotes), and it itself calls this orchestrator internally as its execution backend — its own workflow explicitly invokes the `git-orchestrate` agent as its final step. It is not a peer to invoke instead of this dispatcher, and its own boundary clause sends agent callers here ("Not an agent caller -> `git-orchestrate`"). Agent callers route git-object operations here directly; direct human users to `git-workflow` when they want guided, conversational git help — it will call back into this orchestrator itself. Invoke `pc-author`/`pc-run` directly rather than through this dispatcher; do not invoke `git-workflow` as an agent caller under any circumstance.
## Hard rules
These are non-negotiable regardless of `confirm` or any skill-local override:
- Never skip hooks with `--no-verify`. Hooks are the automated QA gate; bypassing them breaks the pipeline.
- Never force-push `main` or `master`.
- Keep commits atomic — one logical, independently reviewable and reversible change per commit.
- Every commit must leave the repository in a working state (buildable/testable where practical).
- Commit messages explain **why**, not **what** — the diff already documents what changed.
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
- Never commit secrets, credentials, or environment-specific config.
- Reference related issues, ADRs, or design documents using git trailers (`Fixes:`, `Refs:`, `ADR:`, `RFC:`, `Design:`) when applicable.
### Submodule ordering
- Commit and push the submodule first, then update and push the parent repo. Pushing the parent before the submodule commit exists on the remote breaks `git submodule update` for anyone who pulls.
- Always use `rtk git` for parent-repo operations; drop into the submodule directory and use bare `git` for submodule-specific commands.
- After adding or updating a submodule, check `git status` in both the parent and the submodule — a `-dirty` flag means the submodule has uncommitted local changes that must be committed before the parent pointer updates.
Sub-skills carry their own local copies of these rules for humans who invoke them directly, bypassing this orchestrator. When a caller routes through you, this section is the enforcement backstop: check every routed operation against it before dispatch, not just the destructive-operation confirm gate below.
When invoked, you:
1. Parse the incoming workflow request (operation type, parameters, context overrides)
2. Check safety gates: a destructive operation (force-push, branch deletion, history-losing rebase, force-checkout) without `confirm: true` fails immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm`
3. Route to the appropriate domain skill: `git-commits`, `git-branches`, `git-history`, `git-submodules`, `git-worktrees`, `git-remotes`
4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill
5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics
6. Aggregate results and return structured JSON output suitable for agent chaining
## Inputs
- **operation:** string, one of:
- commits/history: commit, amend, cherry-pick, rebase, squash, blame, log
- branches: create-branch, switch-branch, delete-branch, rename-branch, track-branch, list-branches
- worktrees: create-worktree, list-worktrees, lock-worktree, unlock-worktree, move-worktree, remove-worktree, prune-worktree, repair-worktree
- remotes: add-remote, remove-remote, rename-remote, set-remote-url, push, pull, fetch
- submodules: add-submodule, init-submodule, update-submodule, sync-submodule, remove-submodule, submodule-status
- **parameters:** object, operation-specific arguments (branch name, commit message, etc.)
- **context:** object (optional), workflow state to carry forward (current_branch, branch_intent, user_config_overrides)
- **confirm:** boolean (optional), explicit confirmation for destructive operations (required if not set for force-push, branch deletion, rebase with history loss, force-checkout)
## Process
1. Validate the request structure and check if operation is known
2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm`
3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error
4. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, and context — each domain skill infers its own branching pattern and conventions (e.g. `git-branches` from `develop`/`release/*` branch presence) rather than reading shared config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above).
5. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections)
6. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions
7. Aggregate all outputs and return as structured JSON
## Output
```json
{
"status": "success" | "error",
"operation": "<operation_name>",
"result": {
"output": "<command output or result>",
"context": { "current_branch": "...", "workflow_intent": "..." }
},
"error": {
"message": "<human-readable error>",
"code": "<error type: conflict | auth_failure | push_rejection | invalid_state>",
"recovery_attempted": true | false,
"suggestions": ["<suggestion1>", "<suggestion2>"]
}
}
```

1
plugins/git/docs/research/docs/pre-commit/hooks-reference.md
View File

@@ -168,5 +168,4 @@ Local hooks in this repo:
| Hook | Stage | Entry |
|------|-------|-------|
| `run-tests` | pre-push | `bash tests/run-tests.sh` |
| `validate-plugins` | pre-push | `claude plugin validate --strict` per plugin dir |
| `validate-marketplace` | pre-push | `claude plugin validate --strict .claude-plugin/marketplace.json` |

76
plugins/git/skills/git-branches/SKILL.md
View File

@@ -1,76 +0,0 @@
---
name: git-branches
description: >
Use when creating, switching, deleting, renaming, tracking, merging, or comparing
local git branches under GitHub Flow or Gitflow.
Not writing or rewriting commits -> `git-commits`.
Not history inspection -> `git-history`.
Not a Gitea remote's branches -> `gitea-branches`.
metadata:
version: "1.0.4"
category: git
source_keys:
- context7-git-htmldocs
- nvie-gitflow-post
- atlassian-gitflow-tutorial
- gitflow-cheatsheet
---
## 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.
- **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`/`master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming either is rejected even with `confirm: true` — no flag recovers the remote's history. Offer a new branch instead.
## Step 1 — Determine the branching pattern
Infer the branching pattern from the repo: Gitflow if a `develop` or `release/*` branch exists, GitHub Flow otherwise (the default).
The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`.
## Step 2 — Dispatch on the action
| Action | Reference |
|---|---|
| create, switch, delete, rename, track, list, get-intent, stash | `references/branch-operations.md` |
| merge a branch, resolve merge conflicts | `references/merging.md` |
| compare two branches, find their divergence | `references/comparing-branches.md` |
Load only the file the action needs. A destructive action still passes Step 3 first.
## Step 3 — Gate destructive operations
Before any delete or force-delete that loses history:
- [ ] Does the branch track a remote? Warn if so.
- [ ] Are there unpushed commits on it? Warn if so.
- [ ] Did the caller pass `confirm: true`? Fail if not — for a human caller, prompt interactively instead of failing.
These gates are passable. The `main`/`master` refusal in Gotchas is not.
## Step 4 — Set tracking
A new branch's first push must be `rtk git push -u origin <branch>`. The push itself is `git-remotes`' — every remote-side gate lives there, which is why Step 2's remote-delete row hands off the same way — but the upstream requirement originates here, so carry it in the handoff. Without an upstream, later pushes and pulls either fail or silently target the wrong remote branch, and the caller has no way to tell which happened.
## Step 5 — Return a structured result
Return every operation in this shape rather than prose, including failures — a calling agent chains its next operation on the result and cannot parse a sentence.
```json
{
"success": true,
"action": "create|switch|delete|rename|track|list|get-intent",
"branch": "<name>",
"message": "descriptive message",
"intent": "<intent if tracked>",
"tracking": "origin/<branch, if set>",
"error": "<error message if success=false>",
"suggestion": "<recovery suggestion if applicable>"
}
```
When the failure is uncommitted local changes, set `"suggestion": "stash changes and retry"` so the caller can offer recovery rather than surfacing a dead end.
When a calling agent supplies a structured request rather than prose, read `references/orchestrator-contract.md` for the request schema.

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

@@ -1,59 +0,0 @@
---
source_keys:
- context7-git-htmldocs
---
# Per-action command mapping
One command per action. Where two forms exist, the first is the default and the second the escape
hatch.
- **create** — `rtk git switch -c <branch> <base>`. Base comes from the config's `base_branch`
(`main` under GitHub Flow, usually `develop` under Gitflow).
- **switch** — `rtk git switch <branch>` moves to an existing local branch; it aborts rather than
clobbering conflicting local changes. `rtk git switch -` returns to the previous branch.
- **delete (local)** — `rtk git branch -d <branch>` refuses when the branch holds unmerged commits,
which is why it is the default. `rtk git branch -D <branch>` forces the deletion and discards that
work — only after the destructive-operation gates pass and `confirm: true` is set.
- **delete (remote)** — not this skill's. Deleting a remote branch is a push, and every remote-side
gate lives in `git-remotes`; hand it there rather than running the push from here. Its
`references/push.md` carries the command and the refspec form.
- **rename** — `rtk git branch -m <old> <new>`.
- **list** — `rtk git branch` (local), `-a` (local plus remote-tracking), `-r` (remote-tracking only),
`--merged` / `--no-merged` (filter by merge status into the current branch).
- **track** — `rtk git branch --set-upstream-to=origin/<branch>` sets an upstream without pushing.
`rtk git branch -vv` shows the tracking state of every local branch.
## get-intent
Git has no native field for free-text branch metadata, and this skill does not persist any. On
`create`, the `intent` value is only returned in the structured result — the caller decides
whether to store it.
On `get-intent`, either parse the intent back out of the branch-name convention
(`feature/<intent-slug>`) or return `{ "intent": null }` when the caller never persisted the
create-time value. Never fabricate an intent: a downstream commit message built on a guessed
intent is worse than one built on none.
## Stashing work in progress
A switch aborts rather than clobbering conflicting local changes (see Gotchas). Stash is the way
past it: it shelves the working tree and index so the branch pointer can move.
- **save** — `rtk git stash push -m "<message>"`. Add `-u` to include untracked files; verified on Git
2.39.5, a plain `push` leaves them in place, and a plain `push` with *only* untracked changes
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
conflict rtk prints only `FAILED: git stash pop` and swallows the conflict report the paragraph
below tells you to read. `rtk git stash apply stash@{n}`
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,
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
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
stash was taken from and pops it there. Use it when the stash no longer applies to the current tip.
**A conflicting `pop` keeps the entry.** Verified on 2.39.5: it exits 1, writes conflict markers,
prints "The stash entry is kept in case you need it again", and `git stash list` still shows it.
Resolve, `rtk git add`, then `rtk git stash drop` the entry by hand — otherwise it silently accumulates.

31
plugins/git/skills/git-branches/references/branch-patterns.md
View File

@@ -1,31 +0,0 @@
---
source_keys:
- nvie-gitflow-post
- atlassian-gitflow-tutorial
- gitflow-cheatsheet
---
# Branch patterns
Which pattern is in play decides the base branch, the branch name prefix, and whether merges are
allowed to fast-forward. Default to GitHub Flow — simpler, and what CI/CD-oriented repos expect.
Fall back to Gitflow only when the config says so or the repo already carries `develop` or
`release/*` branches.
## GitHub Flow
- Base: `main`
- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
- Merge: fast-forward where possible, to keep history linear
- Delete the branch after merge
## Gitflow
- Base: `main` (production) plus `develop` (integration)
- Feature branches: `feature/<feature-name>`, cut from `develop`
- Release branches: `release/X.Y.Z`, cut from `develop`, merged to both `main` and `develop`
- Hotfix branches: `hotfix/X.Y.Z`, cut from `main`, merged to both `main` and `develop`
- Merge: always `--no-ff`, so the branch structure survives in the history
The two are not mixable. A `--no-ff` merge into a GitHub Flow repo leaves merge commits nobody
expects; a fast-forward merge of a Gitflow release branch erases the release boundary.

16
plugins/git/skills/git-branches/references/comparing-branches.md
View File

@@ -1,16 +0,0 @@
---
source_keys:
- context7-git-htmldocs
---
# Comparing two branches
The two-dot and three-dot forms mean different things and are easy to swap by accident — check the
direction before reporting a result.
- `rtk git log main..feature` — commits on `feature` that are not on `main`.
- `rtk git log feature..main` — the reverse direction: commits on `main` not on `feature`.
- `rtk git log --left-right main...feature` — both diverging sets at once (symmetric difference).
- `rtk git diff main...feature` — the diff from the common ancestor to `feature`'s tip, which is what
a reviewer sees, rather than the diff between the two tips.
- `rtk git merge-base main feature` — print the common ancestor commit.

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

@@ -1,31 +0,0 @@
---
source_keys:
- context7-git-htmldocs
- atlassian-gitflow-tutorial
---
# Merging one branch into another
Scope is fast-forward and merge-commit mechanics plus conflict resolution. Rebase and cherry-pick
belong to `git-commits`; revert to `git-history`.
- **Fast-forward** — `rtk git merge <branch>` advances the pointer with no merge commit when the
target has not diverged.
- **True merge** — `rtk git merge --no-ff <branch>` forces a merge commit even when a fast-forward is
possible. Gitflow requires it on every supporting-branch merge.
- **Squash merge** — `rtk git merge --squash <branch>` stages the combined diff without committing.
Follow it with a `rtk git commit`.
- **Octopus merge** — `rtk git merge branch-a branch-b branch-c` merges more than two branches at
once, but fails outright on any conflict. Use sequential two-way merges when conflicts are
likely.
## Conflict resolution
When Git cannot auto-merge it writes conflict markers and stops mid-merge. Run `rtk git status` to
list the conflicted files, edit each to resolve its markers, then `rtk git add <file>` and
`rtk git merge --continue`.
- `rtk git merge --abort` restores the pre-merge state.
- `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.
- `rtk git diff --diff-filter=U` shows only the still-conflicted files.

20
plugins/git/skills/git-branches/references/orchestrator-contract.md
View File

@@ -1,20 +0,0 @@
---
source_keys: []
---
# Orchestrator request contract
`git-orchestrate` and other calling agents send this shape. The result shape they parse back is in
`SKILL.md` Step 5, because every run emits one.
Request:
```json
{
"action": "create|switch|delete|rename|track|list|get-intent",
"branch": "<branch-name>",
"base": "<base branch, optional, defaults to config>",
"intent": "<human-readable intent, optional>",
"confirm": "<true for destructive ops, omit for read ops>"
}
```

54
plugins/git/skills/git-branches/references/sources.md
View File

@@ -1,54 +0,0 @@
---
# Research sources referenced by this skill
# Each entry documents where the skill's guidance came from.
---
## nvie-gitflow-post
**Description:** Original 2010 post by Vincent Driessen introducing the Gitflow branching model, including a 2020 reflection note recommending GitHub Flow for continuous delivery teams.
**Source:** https://nvie.com/posts/a-successful-git-branching-model/
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
**Contributing files:**
- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
- references/branch-patterns.md (Gitflow vs. GitHub Flow structure, defaults, and why the two are not mixable)
## atlassian-gitflow-tutorial
**Description:** Atlassian's comprehensive Gitflow tutorial covering all five branch types, lifecycle steps, and CLI usage.
**Source:** https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
**Contributing files:**
- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
- references/branch-patterns.md (Gitflow branch types, base/merge targets, `--no-ff` requirement)
- references/merging.md (`--no-ff` requirement on Gitflow supporting-branch merges)
## gitflow-cheatsheet
**Description:** Visual cheatsheet for the git-flow CLI commands (git-flow-avh fork), covering all subcommands for feature, release, and hotfix branches.
**Source:** https://danielkummer.github.io/git-flow-cheatsheet/
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
**Contributing files:**
- references/branch-patterns.md (feature/release/hotfix naming conventions)
## context7-git-htmldocs
**Description:** Official Git HTML documentation from the git/htmldocs repository — covers all commands, concepts, and internals.
**Source:** context7:/git/htmldocs
- **Research doc:** plugins/git/docs/research/docs/git/branching-merging.md (whole-document reference)
**Contributing files:**
- SKILL.md (Gotchas — `git switch` abort-on-conflict behaviour, branch/tag name ambiguity)
- references/branch-operations.md (`git switch`/`git branch` command vocabulary and flags)
- references/merging.md (`git merge` strategies and conflict-resolution commands)
- references/comparing-branches.md (`git log`/`git diff`/`git merge-base` range syntax)

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

@@ -1,76 +0,0 @@
---
name: git-commits
description: >
Use when creating, amending, squashing, or cherry-picking commits, including
writing and validating the Conventional Commits message.
Not history inspection -> `git-history`.
Not branch lifecycle -> `git-branches`.
metadata:
version: "0.1.6"
category: git
source_keys:
- conventional-commits-spec
- commitlint-config-conventional
- org-commit-conventions
- context7-git-htmldocs
allowed-tools: Bash
---
## Gotchas
- **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 diverges the branch and the reflex is to force it back — safe only where nobody else has based work on it.
- **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first.
- **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning.
## Dispatch
Read exactly one flow file. Each is self-contained.
| Condition | Flow | Read |
|---|---|---|
| Composing a new commit from staged changes | create | `references/create-commit.md` |
| Amending, squashing, folding a fixup, rebasing onto a new base, or resetting HEAD | rewrite | `references/rewrite-history.md` |
| Replaying an existing commit onto the current branch | cherry-pick | `references/cherry-pick.md` |
## Gates on every flow
1. **Confirmation.** No history rewrite executes without explicit approval from the user or the calling agent. Cherry-pick needs the destination branch confirmed first.
2. **Atomicity.** The result must be one logical, independently reviewable and reversible change that leaves the repository buildable and testable. This binds an amend or a squashed result as much as a fresh commit — say so before writing it, not after.
3. **Secrets.** Before any commit or amend, scan the staged diff for anything resembling an API key,
token, password, connection string, or environment-specific config. Stop and flag it rather than
committing it.
4. **Validation.** Check the message against commitlint `config-conventional` before committing. If a type, footer, or breaking-change edge case is not obvious, read `references/conventional-commits-spec.md` — it carries the constraint table, the 11-type set, and the footer token rules.
5. **SemVer impact.** Report the bump the commit implies: `feat` → MINOR, `fix`/`perf`/`revert` → PATCH, any breaking change → MAJOR, everything else → none. Callers decide releases from this, so never omit it.
6. **Conflicts.** If a rebase or cherry-pick halts, offer resolution or an abort. Do not resolve automatically without confirmation.
## Output
For an agent caller, return:
```json
{
"operation": "create|amend|squash|cherry-pick",
"status": "success|conflict|rejected",
"message": "commit message or error description",
"commit_hash": "abc1234",
"semver_impact": "MAJOR|MINOR|PATCH|none",
"breaking_change": false,
"confirmation_required": false,
"details": {
"type": "feat",
"scope": "api",
"description": "add user authentication",
"body": "optional body text, or null",
"footers": ["Fixes: #123", "Refs: #456", "Co-authored-by: Bob <bob@example.com>"]
}
}
```
`details.footers` is an array of the resolved trailer lines, empty when there are none — never a
single joined string, and never omitted. Downstream agents index it.
For a human caller, show the same fields as a prose preview with a confirmation prompt.

12
plugins/git/skills/git-commits/references/cherry-pick.md
View File

@@ -1,12 +0,0 @@
---
source_keys:
- context7-git-htmldocs
---
# Cherry-picking a commit
1. **Identify the source commit** — a hash or a branch reference.
2. **Confirm the destination** — cherry-pick replays onto the branch currently checked out, so verify that is the intended branch before running anything.
3. **Execute** — `rtk git cherry-pick <commit-hash>`. A range is `<a>..<b>` (exclusive of `<a>`) or `<a>^..<b>` (inclusive); `-n` stages without committing, for when the replay needs editing first.
4. **Handle conflicts** — if the replay halts, offer resolution or `rtk git cherry-pick --abort`. Never resolve automatically without confirmation.
5. **Report the outcome** — which commits replayed, which conflicted, and which were rejected.

66
plugins/git/skills/git-commits/references/commit-template.md
View File

@@ -1,66 +0,0 @@
---
source_keys:
- org-commit-conventions
---
# Commit Message Body Template
Use this structure for the body/footer of any non-trivial commit (skip sections that don't apply — do not leave placeholders in the actual commit).
```text
<type>(<scope>): <concise summary>
```
The header is required. Describe the intended outcome, not the implementation.
## Why
Explain why this change exists. This is the most valuable part of the commit — the diff already shows *what* changed; future maintainers (human or AI) need *why*.
Include, where applicable:
- Problem being solved
- User or business need
- Bug or root cause
- Important context not visible in the code
Omit if the reason is immediately obvious.
## Implementation Notes
Capture decisions that are difficult to infer from the code:
- Why this approach was chosen
- Important assumptions or invariants
- Constraints imposed by external systems
- Tradeoffs or intentional compromises
- Non-obvious implementation details
- Workarounds or temporary solutions
Do NOT describe the diff ("renamed X", "added Y"). Omit if there's nothing worth preserving.
## Impact
Document effects future developers should know about:
- Behavior changes
- Breaking changes
- Performance implications
- Security considerations
- Migration or deployment requirements
- Compatibility concerns
- Follow-up work or known limitations
Omit if there are no noteworthy impacts.
## Trailers
Structured metadata for traceability and tooling. Use only the trailers that apply:
```text
Fixes:
Refs:
ADR:
RFC:
Design:
Co-authored-by:
Reviewed-by:
Signed-off-by:
BREAKING CHANGE:
```

170
plugins/git/skills/git-commits/references/conventional-commits-spec.md
View File

@@ -1,170 +0,0 @@
---
source_keys:
- conventional-commits-spec
- commitlint-config-conventional
---
# Conventional Commits Specification (v1.0.0)
Conventional Commits is a lightweight convention on top of commit messages that provides a set of rules for creating an explicit commit history. It enables automated tooling (CHANGELOG generation, semantic version bumping) and structured filtering.
## Message Format
```text
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
Each section is separated by a blank line. The header is the only required part.
## Rules
| Element | Rule |
|---|---|
| `type` | Required. Lowercase noun. |
| `scope` | Optional. Noun in parentheses directly after type: `feat(api):`. |
| `description` | Required. Immediately follows `type/scope: `. Imperative mood, no trailing period. |
| `body` | Optional. Begins one blank line after description. Free-form prose, multiple paragraphs allowed. Lines max 100 characters. |
| `footer(s)` | Optional. Begins one blank line after body (or description). `<token>: <value>` format. Lines max 100 characters. |
| `BREAKING CHANGE` | Must be uppercase. Either a footer token or signalled by `!` before the colon. |
## Standard Types
The spec itself mandates only `feat` and `fix`. The 11-type set below is the de-facto standard from `@commitlint/config-conventional` (Angular commit message guidelines), not a spec requirement — but it is what this skill validates against.
### 11-type set (commitlint/config-conventional)
| Type | Meaning | SemVer impact | Appears in CHANGELOG |
|---|---|---|---|
| `feat` | New user-visible feature | MINOR | Yes |
| `fix` | Bug fix | PATCH | Yes |
| `perf` | Performance improvement, no API change | PATCH | Yes |
| `revert` | Reverts a previous commit | PATCH | Yes |
| `docs` | Documentation only | none | No |
| `style` | Formatting, whitespace — no logic change | none | No |
| `refactor` | Code restructuring — no feature or fix | none | No |
| `test` | Adding or fixing tests | none | No |
| `build` | Build system or external dependency changes | none | No |
| `ci` | CI configuration and scripts | none | No |
| `chore` | Anything not fitting above | none | No |
A `BREAKING CHANGE` footer or `!` on **any** type always triggers a MAJOR bump.
## Breaking Changes
Two equivalent notations:
**`!` in header** (preferred — visible in `git log --oneline`):
```text
feat!: drop support for Node 6
feat(api)!: remove deprecated endpoint
```
**`BREAKING CHANGE` footer** (machine-readable body):
```text
feat: allow config to extend other configs
BREAKING CHANGE: `extends` key now used for extending config files
```
**Both together** (most explicit):
```text
feat!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
```
Rules:
- `BREAKING CHANGE` must be all caps.
- `BREAKING-CHANGE` (hyphenated) is an accepted synonym.
- Any type can carry a breaking change, not just `feat`.
- The footer value must describe what broke.
## Footer Token Rules
```text
<token>: <value>
<token> #<value> # for issue references
```
- Tokens use hyphens for word separation: `Reviewed-by`, `Co-authored-by`, `Refs`.
- Exception: `BREAKING CHANGE` (space allowed, uppercase).
- Multiple footers allowed, one per line.
- Blank line required before the footer block.
Valid footer examples:
```text
Reviewed-by: Z
Refs: #123
Co-authored-by: Alice <alice@example.com>
BREAKING CHANGE: the `--format` flag now requires a value
```
## Examples
Minimal — no body, no footer:
```text
docs: correct spelling of CHANGELOG
```
With scope:
```text
feat(lang): add Polish language
```
Breaking change via `!`:
```text
feat!: send an email to the customer when a product is shipped
```
Breaking change via footer:
```text
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
```
Multi-paragraph body with multiple footers:
```text
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Reviewed-by: Z
Refs: #123
```
Revert:
```text
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868
```
## commitlint Constraints (config-conventional)
| Constraint | Value |
|---|---|
| Header max length | 100 characters |
| Subject must not end with `.` | enforced |
| Subject must be lowercase (not sentence-case or UPPER-CASE) | enforced |
| Body / footer line max length | 100 characters |
| Type must be one of the 11 standard types | error if not |
| Blank line before body | warning |
| Blank line before footer | warning |
## SemVer Mapping Summary
| Condition | SemVer bump |
|---|---|
| `fix`, `perf`, `revert` | PATCH |
| `feat` | MINOR |
| Any type with `BREAKING CHANGE` or `!` | MAJOR |
| All other types (`docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore`) | none |

17
plugins/git/skills/git-commits/references/create-commit.md
View File

@@ -1,17 +0,0 @@
---
source_keys:
- conventional-commits-spec
- commitlint-config-conventional
- org-commit-conventions
---
# Creating a new commit
1. **Gather context** — what changed and why, from the staged diff, the PR description, or the issue. Confirm the staged diff is one logical, independently reviewable and reversible change that leaves the repository buildable and testable. If it bundles unrelated work, suggest splitting it before going further.
2. **Determine the type** — read it off the change itself: a new user-visible feature is `feat`, a bug fix is `fix`. For the full 11-type set and each type's SemVer impact, read `references/conventional-commits-spec.md`.
3. **Determine the scope** — use the scope from plugin config where one is set, otherwise infer it from the files changed (`api`, `db`, `cli`, `config`). Scope is optional, but it identifies which part of the system moved and is worth setting.
4. **Write the description** — imperative mood, no trailing period: "add user authentication", "fix race condition in cache". Neither source spec sets a target below the 100-character header maximum, but convention favours roughly 50 characters so `git log --oneline` stays readable.
5. **Add a body when the change is non-trivial** — blank line first, wrapped at 100 characters. Explain *why*, not what: the diff already shows what changed, and the message's job is the context the diff cannot carry — motivation, root cause, tradeoffs. Follow the Why / Implementation Notes / Impact structure in `references/commit-template.md`.
6. **Add footers where they apply** — `Fixes: #123`, `Refs: #123`, `ADR: 0012`, `Co-authored-by: Name <email>`, `BREAKING CHANGE: description`. For the full trailer list, read `references/commit-template.md`.
7. **Signal a breaking change with `!` before the colon** — `feat!: drop Node 6` is visible in `git log --oneline`, where the `BREAKING CHANGE:` footer alone is machine-readable but hidden. Use both when the break needs describing.
8. **Validate, confirm, execute** — check header length, type, lowercase subject and trailing period against commitlint, show the message, and commit only once the caller has approved. Never add `--no-verify`.

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

@@ -1,75 +0,0 @@
---
source_keys:
- org-commit-conventions
- context7-git-htmldocs
---
# Rewriting existing commits
Every flow here rewrites history. None runs without explicit approval, and none ends in a force-push to `main`/`master` — refuse that and explain why.
## Amend the last commit
1. Stage the new changes, or the changes that undo something.
2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is.
3. If the message should change, show the current one and prompt for the replacement.
4. The branch has diverged from its remote. Amending is safe only where nobody else has based work on it; on `main`/`master`, refuse the force-push and explain rather than warn and proceed.
## Fold a commit into an earlier one (autosquash — preferred)
Prefer this whenever a commit is written to be folded, because git does the marking:
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.
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.
## Squash by hand (interactive rebase)
Use this when the commits were not tagged at commit time. **Interactive rebase has no undo once `rebase -i` starts — `git reflog` is the recovery path.**
1. Identify the commits to squash — typically the last N on the current branch.
2. Get explicit approval.
3. Run `git rebase -i HEAD~N` — bare, not `rtk`, for the same interactive-editor reason — marking the older commits `squash` to keep their messages for editing, or `fixup` to discard them.
4. Compose the combined message when the rebase stops to ask. For a non-trivial combined message, follow the structure in `references/commit-template.md`.
## When a rebase halts on a conflict
Offer conflict resolution or `rtk git rebase --abort`. Do not resolve conflicts automatically without confirmation.
## Rebase the branch onto a new base
Replays this branch's commits on top of another branch's tip — bringing a feature branch up to
date without a merge commit.
1. Confirm nothing being replayed has been pushed anywhere someone else has based work on. A rebase
gives every replayed commit a new SHA, which breaks any clone that already has the old ones.
2. Get explicit approval — this rewrites history like every other flow on this page.
3. `rtk git fetch origin` first, so `<newbase>` is the real tip rather than a stale local copy.
4. `rtk git rebase <newbase>` — for example `rtk git rebase main`. Use
`rtk git rebase --onto <newbase> <upstream> <branch>` to replay only the commits after
`<upstream>`, which is how a branch started from the wrong base gets moved.
5. The branch has diverged from its remote. Push needs `--force-with-lease --force-if-includes`,
never a bare `--force` — and never on `main`/`master`; refuse that and explain.
## Move the branch pointer back (`git reset`)
`reset` moves the current branch to another commit. The mode decides what survives:
| Mode | Branch pointer | Index | Working tree |
|---|---|---|---|
| `--soft` | moves | untouched — the changes stay staged | untouched |
| `--mixed` (default) | moves | reset — the changes become unstaged | untouched |
| `--hard` | moves | reset | **overwritten; uncommitted work is destroyed** |
- "Undo my last commit but keep the changes" is `rtk git reset --soft HEAD~1`. That is the default
answer to the request; reach for anything else only when the caller asked for it.
- `rtk git reset --mixed HEAD~1` when the staging should be redone from scratch too.
- `rtk git reset --hard <ref>` is gated like a force-push: state exactly which uncommitted changes
will be discarded, get approval for that specific reset, and offer `rtk git stash push -u` first.
The commits it drops stay reachable through `git reflog`; the uncommitted edits never entered git
at all and nothing recovers them.
Reset does not rewrite the commits it leaves behind, so no force-push is needed unless the branch
was already pushed at the newer commit.

40
plugins/git/skills/git-commits/references/sources.md
View File

@@ -1,40 +0,0 @@
---
topic: commits
source_keys:
- conventional-commits-spec
- commitlint-config-conventional
- org-commit-conventions
- context7-git-htmldocs
---
# Research Sources for git-commits Skill
Sources extracted from the git plugin research phase. Only sources that directly informed this skill are listed; sibling skills (git-branches, git-history, git-remotes, etc.) have their own sources.md.
## conventional-commits-spec
- **Description:** Conventional Commits Specification (v1.0.0) — message format, types, breaking changes, footer rules
- **Research doc:** plugins/git/docs/research/docs/git/commits.md § "Conventional Commits Specification (v1.0.0)"
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md, references/create-commit.md
- **Status:** extracted
## commitlint-config-conventional
- **Description:** commitlint config-conventional preset — validation constraints (max 100 chars header, no trailing periods, lowercase type, 11-type set enforcement)
- **Research doc:** plugins/git/docs/research/docs/git/commits.md § "commitlint Constraints (`config-conventional`)"
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md, references/create-commit.md
- **Status:** extracted
## org-commit-conventions
- **Description:** Organization commit message body template and git conventions (atomic commits, no `--no-verify`, no force-push main/master, `rtk git` wrapper) — content fully embedded in this skill; the org's `core/instructions/git.md` and `core/instructions/commits.md` are provenance only and are not a live dependency
- **Research doc:** core/instructions/commits.md, core/instructions/git.md (org convention, not part of the plugin's research corpus)
- **Contributing files:** SKILL.md, references/commit-template.md, references/create-commit.md, references/rewrite-history.md
- **Status:** extracted
## context7-git-htmldocs
- **Description:** Official Git HTML documentation — `git commit --squash`/`--fixup`, `git rebase --autosquash`, and `git cherry-pick` range and abort semantics
- **Research doc:** plugins/git/docs/research/docs/git/cli-reference.md § "Committing", § "Rebasing", § "Cherry-picking"
- **Contributing files:** SKILL.md, references/rewrite-history.md, references/cherry-pick.md
- **Status:** extracted

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

@@ -1,66 +0,0 @@
---
name: git-history
description: >
Use when investigating git history — pickaxe (`-S`/`-G`) or `-L` line-range log
queries, tracing when a change landed, bisecting what broke something, or
locating a commit to revert or backport. Not authoring or rebasing commits ->
`git-commits`. Not a Gitea server's history -> `gitea-branches`.
metadata:
version: "1.0.2"
category: git
source_keys:
- git-scm-bisect-docs
- git-scm-log-docs
- git-scm-diff-docs
allowed-tools: Bash
---
## Gotchas
- `-S"string"` matches only where the string's *count* changed, so a line edited in place matches `-G"regex"` and not `-S`. Reach for `-G` whenever the string may have moved rather than appeared.
- `--follow` traces renames for exactly one path. Given several paths or a glob it fails instead of degrading, so run it once per file.
- Under `git bisect run`, exit `128` or above **aborts the session** rather than marking the commit bad, so a crashing test script ends the search silently.
- Bisect answering "cannot find exact culprit" beside skipped commits is a complete result: it is as precise as the skip range allows.
## Step 1 — Pick the entry procedure
| What is known | Procedure |
|---|---|
| Content, a file, or a line range to search for | Query the log — Step 2 |
| Nothing to search for — only that the behaviour changed between two points | Bisect — read `references/bisect.md` |
| The commit itself, already identified | Step 3 |
## Step 2 — Query the log
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.
- **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.
- **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)"`.
If you need the placeholder catalogue, format presets, `--diff-filter` letters, full `-L` syntax, ancestry filters, pickaxe binary-file behaviour, or `git diff` output-control flags such as `--stat`, `--word-diff` and the whitespace options, read `references/git-log-format.md`.
## Step 3 — Act on a located commit
Offer the operation and its consequence; run it only once the user has chosen.
- Backporting the commit to another branch is a cherry-pick, and cherry-pick is `git-commits`' — it owns the destination-branch check, the `rtk git` wrapper and the `--abort` path. Hand it the SHA; do not run `git cherry-pick` from here.
- `rtk git revert <commit>` adds a new commit undoing it — for un-applying merged work without rewriting history.
- `rtk git blame <file>` attributes each line to the commit that last touched it, when the question is which commit introduced one specific line.
For diff output control on the located commit, read `references/git-log-format.md`.
## Step 4 — Return the result
Report each located commit in this shape, so a calling agent can act on it without reparsing raw log output:
```text
<sha> — <subject>
<author> (<relative date>)
Recommendation: <action or "none">
```

68
plugins/git/skills/git-history/references/bisect.md
View File

@@ -1,68 +0,0 @@
---
topic: bisect
source_keys:
- git-scm-bisect-docs
---
# Finding a commit with `git bisect`
Read this when the question is *which commit changed the behaviour* and there is no string, file,
or line range to search the log for. Binary search reduces the trials from O(N) to O(log N).
## Manual flow
```bash
rtk git bisect start
rtk git bisect bad [HEAD] # mark current (or specified) as broken
rtk git bisect good <commit> # mark known-good baseline
# Git checks out the midpoint; test it
rtk git bisect good # test passes
rtk git bisect bad # test fails
# Repeat until git reports "X is the first bad commit"
rtk git bisect reset # return to the original HEAD
```
## Automated
With a test command available, use `rtk git bisect run <cmd>`. Git reads the exit code: `0` good,
`1`–`124` bad, `125` skip (build broken), `126`–`127` POSIX shell errors, treated as bad, and
`128` or above aborts the session outright rather than marking the commit bad.
## Untestable commits
`rtk git bisect skip` excludes a commit that cannot be built or tested without deciding good or bad
for it. When the first bad commit is adjacent to a skipped range, bisect reports that it cannot
pinpoint the culprit and lists the candidates — that is the precise answer the skip range allows,
not a failure.
## Undoing a wrong good/bad call
`rtk git bisect log` prints the session's decision history. Save it, edit out the mistaken entry, and
resume from the corrected log rather than restarting the search:
```bash
rtk git bisect log > bisect.log
# edit bisect.log, removing the wrong decision
rtk git bisect reset && rtk git bisect replay bisect.log
```
## Narrowing and speeding up
- `rtk git bisect start HEAD v1.2 -- src/` restricts bisection to a path, cutting the trial count.
- `--no-checkout` updates the `BISECT_HEAD` ref instead of checking out a working tree — useful
for tests that do not need one, and automatic in bare repos.
- `--first-parent` follows only first parents at merges, finding the integration commit that
introduced a regression while ignoring broken side branches.
## Inspecting the remaining candidates
`rtk git bisect visualize` (alias `view`) opens the suspects in gitk, falling back to `git log` when
no graphical display is detected. Add `--stat` or `-p` for a diffstat or full patches.
## Hunting a non-bug property change
`rtk git bisect start --term-new <new> --term-old <old>` searches for any property change — a
performance regression, say — instead of a bug. Use the custom terms in place of `good` and `bad`
for the rest of the session.
Once the first bad commit is identified, return to Step 3 to act on it and Step 4 to report it.

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

@@ -1,242 +0,0 @@
---
topic: git-log-format
source_keys:
- git-scm-log-docs
- git-scm-diff-docs
---
## Named Format Presets (`--format` / `--pretty`)
| Name | Output |
|---|---|
| `oneline` | `<hash> <title>` |
| `short` | hash, author, title |
| `medium` | hash, author, date, full message (default) |
| `full` | adds committer |
| `fuller` | separate author/committer dates |
| `reference` | `<abbrev> (<title>, <date>)` — for use in commit messages |
| `email` | RFC 2822 email format |
| `raw` | full object as stored in the object database |
| `format:<str>` | custom template with placeholders |
## Custom Format Placeholders
**Commit identity:**
| Placeholder | Meaning |
|---|---|
| `%H` | full commit hash |
| `%h` | abbreviated commit hash |
| `%T` | tree hash |
| `%t` | abbreviated tree hash |
| `%P` | full parent hashes |
| `%p` | abbreviated parent hashes |
**Author:**
| Placeholder | Meaning |
|---|---|
| `%an` | author name |
| `%aN` | author name (mailmap-resolved) |
| `%ae` | author email |
| `%aE` | author email (mailmap-resolved) |
| `%ad` | author date (respects `--date=`) |
| `%ar` | author date, relative |
| `%at` | author date, UNIX timestamp |
| `%ai` | author date, ISO 8601-like |
| `%aI` | author date, strict ISO 8601 |
| `%as` | author date, short (YYYY-MM-DD) |
**Committer:**
| Placeholder | Meaning |
|---|---|
| `%cn` | committer name |
| `%ce` | committer email |
| `%cd` | committer date (respects `--date=`) |
| `%cr` | committer date, relative |
| `%ct` | committer date, UNIX timestamp |
| `%ci` | committer date, ISO 8601-like |
| `%cs` | committer date, short |
**Message:**
| Placeholder | Meaning |
|---|---|
| `%s` | subject (first line) |
| `%f` | sanitized subject (filename-safe) |
| `%b` | body (everything after blank line following subject) |
| `%B` | raw body (subject + body) |
| `%N` | commit notes |
**Refs and decorations:**
| Placeholder | Meaning |
|---|---|
| `%d` | ref names (like `--decorate`) |
| `%D` | ref names without surrounding parentheses |
| `%S` | ref name by which commit was reached (requires `--source`) |
| `%(decorate[:opts])` | custom decorated refs; options: `prefix=`, `suffix=`, `separator=`, `pointer=`, `tag=` |
| `%(describe[:opts])` | like `git describe`; options: `tags=`, `abbrev=`, `match=`, `exclude=` |
**GPG signature:**
| Placeholder | Meaning |
|---|---|
| `%G?` | status: `G`=good, `B`=bad, `U`=unknown, `X`=expired, `R`=revoked, `N`=no signature |
| `%GS` | signer name |
| `%GK` | signing key ID |
**Trailers:**
```text
%(trailers[:key=<k>][,only][,separator=<s>][,unfold][,keyonly][,valueonly])
```
**Formatting / color:**
| Placeholder | Meaning |
|---|---|
| `%n` | newline |
| `%%` | literal `%` |
| `%Cred` / `%Cgreen` / `%Cblue` / `%Creset` | terminal colors |
| `%C(<spec>)` | color per git-config spec |
| `%<(<n>[,trunc])` | right-pad field to width n |
| `%>(<n>)` | left-pad to width |
**Reflog** (requires `-g` / `--walk-reflogs`):
| Placeholder | Meaning |
|---|---|
| `%gD` | reflog selector (e.g. `refs/stash@{1}`) |
| `%gd` | shortened reflog selector |
| `%gs` | reflog subject |
## Pickaxe Search: -S and -G
**`-S<string>`** — finds commits where the **count** of `<string>` changed (i.e. the string was added or removed net). Does not match commits where the string merely appears in a diff hunk without a count change.
```bash
rtk git log -S"my_function"
rtk git log -S"my_function" --pickaxe-regex # treat as POSIX ERE
rtk git log -S"my_function" --pickaxe-all # show all files in matching changesets
```
**`-G<regex>`** — finds commits where any added or removed **line** in the patch matches `<regex>`. Broader than `-S`: matches whenever the pattern appears in diff text regardless of count.
```bash
rtk git log -G"frotz\(nitfol"
```
**Critical distinction:** given a diff that removes one occurrence of `foo` and adds one occurrence of `foo` (net change = 0):
- `-S"foo"` — does **not** match (count unchanged)
- `-G"foo"` — **matches** (pattern appears in patch text)
Binary files are searched by `-S`; ignored by `-G` unless `--text` is supplied.
## --diff-filter (full table)
Selects commits (in `git log`) or files (in `git diff`) by change type:
| Letter | Meaning |
|---|---|
| `A` | Added |
| `C` | Copied |
| `D` | Deleted |
| `M` | Modified |
| `R` | Renamed |
| `T` | Type changed (regular file ↔ symlink ↔ submodule) |
| `U` | Unmerged (conflict) |
| `X` | Unknown (indicates a git bug) |
| `B` | Pairing broken |
Lowercase letters **exclude** that type:
```bash
rtk git log --diff-filter=ad # exclude added and deleted files
rtk git log --diff-filter=M # only show commits with modified files
```
`C` and `R` only appear when copy/rename detection is enabled (`-C`, `-M` flags or `diff.renames` config).
## -L — Line Range History (full syntax)
Traces the evolution of a specific range of lines or a named function through commits. Implies `--patch`.
Bare `git`, not `rtk git`, on every `-L` form below: rtk truncates each diff body
line at roughly 72 characters with an ellipsis, on the one query whose whole point
is showing line content.
```bash
git log -L 10,20:file.txt # bare (ADR-0023)
git log -L /start_pattern/,/end_pattern/:file.txt # bare (ADR-0023)
git log -L :myfunction:src/app.c # bare (ADR-0023)
git log -L /init/,+15:config.py # bare (ADR-0023); 15 lines after first /init/ match
```
Range formats:
| Format | Meaning |
|---|---|
| `<n>` | Absolute line number (1-based) |
| `/<regex>/` | First line matching regex from previous range end |
| `^/<regex>/` | First line matching regex from file start |
| `+<n>` / `-<n>` | Offset relative to `<start>` (end position only) |
Limitations: incompatible with `--raw`, `--numstat`, `--shortstat`, `--name-only`, `--name-status`, `--check`. Cannot use pathspec limiters alongside `-L`.
## Graph and Ancestry Filters
```bash
rtk git log --first-parent # at merges, follow only first parent (mainline evolution)
rtk git log --merges # only merge commits (≥2 parents); equivalent to --min-parents=2
rtk git log --no-merges # only non-merge commits; equivalent to --max-parents=1
rtk git log --ancestry-path D..M # only commits actually on the path from D to M
rtk git log --min-parents=<n> # include only commits with ≥ n parents
rtk git log --max-parents=<n> # include only commits with ≤ n parents
```
`--ancestry-path` is significant: without it, `D..M` includes all commits reachable from M but not D — including side branches that merged into the path. With it, only commits directly between D and M are shown.
## git diff — Output Control
### --stat
```bash
rtk git diff --stat # diffstat: file names + ± bar
rtk git diff --stat=<width>,<name-width>,<count>
rtk git diff --compact-summary # alongside --stat: shows new/gone, +x/-x (executable), +l (symlink)
rtk git diff --numstat # machine-readable: <added>\t<deleted>\t<path>; - for binary
```
### --name-only / --name-status
Bare `git`, not `rtk git`: rtk appends a blank line and a `Changes:` trailer, so
the output is no longer one record per line.
```bash
git diff --name-only # bare (ADR-0023); only filenames, one per line
git diff --name-status # bare (ADR-0023); status letter + filename per line
```
`--name-status` uses the same status letters as `--diff-filter`.
### --word-diff
Bare `git`, not `rtk git`: rtk replaces the word-diff with its own diffstat
renderer and emits none of the `[-removed-] {+added+}` markers.
```bash
git diff --word-diff # bare (ADR-0023); inline word-level diff, [-removed-] {+added+} markers
git diff --word-diff=color # bare (ADR-0023); color only, no markers
git diff --word-diff=porcelain # bare (ADR-0023); machine-readable: +/- prefixed lines, ~ for newlines
git diff --word-diff-regex=<re> # bare (ADR-0023); define what counts as a "word"
```
### Whitespace Flags
| Flag | Effect |
|---|---|
| `-b` / `--ignore-space-change` | Treat any run of whitespace as equivalent; ignore trailing whitespace |
| `-w` / `--ignore-all-space` | Ignore all whitespace completely |
| `--ignore-space-at-eol` | Ignore whitespace at end-of-line only |
| `--ignore-blank-lines` | Ignore changes consisting entirely of blank lines |
| `-I<regex>` / `--ignore-matching-lines=<re>` | Ignore changes where all changed lines match regex |

31
plugins/git/skills/git-history/references/sources.md
View File

@@ -1,31 +0,0 @@
---
topic: history-inspection
source_keys:
- git-scm-bisect-docs
- git-scm-log-docs
- git-scm-diff-docs
---
## git-scm-bisect-docs
Git bisect documentation covering binary search through commit history to find the commit that introduced a bug. Includes manual flow, automated mode with exit codes, skip patterns, and visualization options.
- **Research doc:** plugins/git/docs/research/docs/git/history-inspection.md
- **Doc heading:** `## git bisect`
- **Contributing files:** SKILL.md, references/bisect.md
## git-scm-log-docs
Git log documentation covering format presets, custom format placeholders (commit identity, author, committer, message, refs, GPG signature), pickaxe search (`-S` and `-G`), `--follow` for file renames, `--diff-filter`, and line-range history (`-L`).
- **Research doc:** plugins/git/docs/research/docs/git/history-inspection.md
- **Doc heading:** `## git log — Format and Filtering`
- **Contributing files:** SKILL.md, references/git-log-format.md
## git-scm-diff-docs
Git diff documentation covering output control (--stat, --name-only, --name-status, --word-diff) and whitespace handling flags.
- **Research doc:** plugins/git/docs/research/docs/git/history-inspection.md
- **Doc heading:** `## git diff — Output Control`
- **Contributing files:** SKILL.md, references/git-log-format.md

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

@@ -1,60 +0,0 @@
---
name: git-remotes
description: >
Use when a git operation — remote config, fetch, push, or pull — touches a
remote, even when the user does not name it.
Not local commits -> `git-commits`.
Not local branches -> `git-branches`.
Not log or bisect queries -> `git-history`.
Not submodule pointers -> `git-submodules`.
metadata:
version: "1.0.3"
category: git
source_keys:
- git-scm-remote-docs
- git-scm-fetch-docs
- git-scm-push-docs
- git-scm-pull-docs
- context7-git-htmldocs
---
## Gotchas
- **`--force-with-lease` alone is not safe** — background processes (IDE plugins, cron jobs) running `git fetch` silently defeat the protection. Combine it with `--force-if-includes`, or pin the explicit `--force-with-lease=<ref>:<sha>` form.
- **Prune does not touch tags by default** — `git fetch --prune` leaves orphaned tags behind. Use `--prune --prune-tags`, or set `fetch.pruneTags true`.
- **Set `pull.ff only` explicitly** — do not trust the installed default.
## Step 1 — Clear the force-push gate
`main`/`master` are a hard refusal: decline a force-push to either regardless of confirmation — no local approval restores what the remote loses. Elsewhere, `rtk git push --force`/`-f` run only after `confirm: true` for that specific push; for a human caller, prompt instead of failing.
## Step 2 — Dispatch
Read the row matching the operation, and only that row — each file is self-contained. A task spanning two operations reads both.
| Operation | Read |
|---|---|
| Add, remove, rename, inspect, or re-point a remote; tracking, mirror, and `set-url` config | `references/remote-config.md` |
| Fetch or prune remote-tracking refs; shallow or partial fetch | `references/fetch.md` |
| Push branches or tags; refspecs; force-push | `references/push.md` |
| Pull — integrate remote changes into the current branch | `references/pull.md` |
## Step 3 — Return format
For agent callers, return:
```json
{
"success": true,
"operation": "push",
"remote": "origin",
"branch": "main",
"output": "...",
"warnings": ["force-with-lease not confirmed"],
"recommendations": ["set `pull.ff only` so the default does not vary by Git version"]
}
```
On failure, set `success: false` and add an `error` field holding the root cause and a recovery suggestion.

31
plugins/git/skills/git-remotes/references/fetch.md
View File

@@ -1,31 +0,0 @@
---
topic: fetch
source_keys:
- git-scm-fetch-docs
- context7-git-htmldocs
---
# Fetching
Fetch **with no refspec** updates remote-tracking branches (`refs/remotes/<name>/*`) and leaves every local branch alone.
That safety comes from the default refspec, not from `fetch` itself. Give it an explicit one and it writes to local branches: verified on Git 2.39.5, `git fetch origin main:probe` fast-forwarded the local `probe` branch, and a `+` prefix force-updates the destination, discarding whatever commits it held. Treat any `fetch` carrying a `<src>:<dst>` refspec as a branch update, not a read.
- **One remote**: `rtk git fetch <remote>` — all branches
- **One branch**: `rtk git fetch <remote> <branch>` — the result lands in `FETCH_HEAD`, not a tracking ref
- **All remotes**: `rtk git fetch --all`
- **Prune properly**: `rtk git fetch --all --prune --prune-tags` cleans stale branches *and* tags
- **Auto-prune**: `rtk git config --global fetch.prune true` (or `remote.<name>.prune` to scope it to one remote), and `fetch.pruneTags true` for tags
## Shallow and partial fetch
```bash
rtk git fetch --depth=<n> # deepen history, or create a shallow clone
rtk git fetch --unshallow # convert a shallow clone to full history
rtk git fetch --update-shallow # allow the fetch to update the shallow boundary
rtk git fetch --refmap='' <remote> <branch> # fetch without updating any tracking ref (FETCH_HEAD only)
```
## Default fetch refspec
The default is `+refs/heads/*:refs/remotes/<name>/*`. The leading `+` forces the update — remote-tracking branches always mirror the remote exactly and offer no protection for local history.

43
plugins/git/skills/git-remotes/references/pull.md
View File

@@ -1,43 +0,0 @@
---
topic: pull
source_keys:
- git-scm-pull-docs
- context7-git-htmldocs
---
# Pulling
Default strategy: `--ff-only`. It fails on divergence, which forces a conscious choice instead of an accidental merge commit.
- **Fast-forward only**: `rtk git pull --ff-only` — the recommended default
- **Rebase**: `rtk git pull --rebase` replays your commits on top for linear history, but rewrites SHAs. Verify nothing being replayed has been pushed: rebasing published commits breaks everyone downstream.
- **Merge**: `rtk git pull --no-rebase` — three-way merge commit, preserves original commits, non-linear
- **Rebase preserving merges**: `rtk git pull --rebase=merges` keeps intentional local merge commits during the replay
- **Stage without committing**: `rtk git pull --squash` collapses incoming commits into staged changes; you write the message
- **Merge strategy**: Git 2.34+ defaults to `ort` (`recursive` is now an alias for it). Strategy options such as `-X ours`, `-X theirs`, `-X ignore-space-change` pass through unchanged.
- **Submodules**: `--recurse-submodules` only fetches submodules already checked out. Newly added ones are not initialized — use the `git-submodules` skill for those.
## On divergence
A pull that diverges with no strategy configured fails, and that failure is the useful outcome. Report the divergence and the three ways out — `--ff-only`, `--rebase`, `--no-rebase` — and let the caller choose. Auto-merging a diverged branch buries a decision that belongs to the human.
## Config precedence
`--ff-only` is not Git's default on an unset config, and never has been. Older versions silently
merged on divergence; current ones refuse outright — verified on Git 2.39.5, a divergent pull with
nothing configured prints the reconciliation hint and exits 128 with
`fatal: Need to specify how to reconcile divergent branches.` The behaviour therefore still varies
by installed version, and neither variant is the one you want. Set it explicitly.
Highest wins:
1. Command-line flag (`--ff-only` / `--rebase` / `--no-rebase`)
2. `pull.rebase` config (global or local)
3. `branch.<name>.rebase` (branch-specific override)
4. `branch.autoSetupRebase` (set automatically when the tracking branch was created)
```bash
rtk git config pull.ff only # deterministic default across Git versions
rtk git config --global pull.rebase true
rtk git config branch.develop.rebase false # develop always merges, regardless of the global default
```

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

@@ -1,69 +0,0 @@
---
topic: push
source_keys:
- git-scm-push-docs
- context7-git-htmldocs
---
# Pushing
Default: safe push to the same-named branch on the remote.
- **Force-push**: never bare `--force`. Use `rtk git push --force-with-lease --force-if-includes <remote> <branch>`, after the SKILL.md Step 1 gate.
- **Basic**: `rtk git push <remote> <branch>`
- **Set upstream**: `rtk git push -u <remote> <branch>` — push and configure tracking
- **Multi-remote**: push sequentially (`rtk git push origin develop`, `rtk git push staging develop`), or add a second push URL with `rtk git remote set-url --add <name> <url>` to reach both in one command
- **Delete a remote branch**: `rtk git push <remote> --delete <branch>` — clearer than the `:<branch>` form
- **Bulk**: `rtk git push --all` (all local branches), `rtk git push --tags` (all tags), `rtk git push origin <tag>` (one tag)
- **Delete remote branches with no local counterpart**: `rtk git push --prune origin 'refs/heads/*:refs/heads/*'`
- **Force only part of a multi-ref push**: prefix the one refspec that needs it with `+` — `rtk git push origin +release develop` forces `release` while safe-pushing `develop`. A `+` prefix is a force-push and passes the SKILL.md Step 1 gate like any other.
## Refspec syntax — `[+]<src>[:<dst>]`
| Pattern | Meaning |
|---|---|
| `<branch>` | Push to same-named remote branch |
| `<src>:<dst>` | Push `<src>` local ref to `<dst>` remote ref |
| `+<src>:<dst>` | Force this refspec (non-fast-forward allowed) — a force-push; passes the SKILL.md Step 1 gate |
| `:<branch>` | Delete remote `<branch>` |
| `refs/heads/*:refs/heads/*` | Glob: push all matching branches |
| `^refs/heads/dev-*` | Negative: exclude matching refs |
| `tag <name>` | Sugar for `refs/tags/<name>:refs/tags/<name>` |
## Force-push safety — full detail
`--force-with-lease` rejects the push if the remote ref moved since your last fetch. Three forms:
| Form | What it protects |
|---|---|
| `--force-with-lease` (bare) | All refs being pushed, checked against your remote-tracking branch |
| `--force-with-lease=<refname>` | Named ref only |
| `--force-with-lease=<refname>:<sha>` | Named ref must be at exact SHA — most stable |
**Caveat with the bare form:** any background process that runs `git fetch` (IDE plugin, cron job, editor auto-fetch) updates your remote-tracking branch, which can make the lease check pass even though someone else pushed in between. The protection is silently defeated.
Two mitigations:
```bash
# Option 1 — dedicated push-only remote: background tools fetch `origin`, you push
# through a separate remote that nothing else touches, so its tracking ref can't be
# poisoned by an unrelated fetch.
# The inner `git config` is bare: its stdout becomes a remote URL, so any
# output rewriting would poison the remote silently.
rtk git remote add origin-push $(git config remote.origin.url) # inner bare (ADR-0023)
rtk git push --force-with-lease origin-push
# Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state
rtk git fetch
rtk git tag base master
git rebase -i master # bare, not `rtk` (ADR-0023): interactive sequence editor
rtk git push --force-with-lease=master:base master:master
```
`--force-if-includes` adds a second check on top of bare `--force-with-lease`: it verifies the remote-tracking tip actually appears in your local branch's reflog, i.e. you genuinely integrated it before rewriting. It is a no-op without `--force-with-lease`, and has no effect with the `--force-with-lease=<ref>:<sha>` form, which already pins an exact SHA.
Safest combination: `rtk git push --force-with-lease --force-if-includes origin`.
## Server-side policy
`receive.denyDeletes`, `receive.denyDeleteCurrent` and `receive.denyNonFastForwards` are enforced on the remote regardless of any local flag — a hardened server rejects the push even with `--force`.

39
plugins/git/skills/git-remotes/references/remote-config.md
View File

@@ -1,39 +0,0 @@
---
topic: remote-config
source_keys:
- git-scm-remote-docs
- context7-git-htmldocs
---
# Remote configuration
Which remotes exist, where they point, and what they track.
`rtk git remote show <name>` needs network access — use `-n` for cached data offline, or `rtk git remote -v`, which lists URLs without querying.
## Add, remove, rename, inspect
- **Add**: `rtk git remote add <name> <url>`, or `-f` to fetch immediately
- **Remove**: `rtk git remote remove <name>` — deletes the remote, all its tracking refs, and its config
- **Rename**: `rtk git remote rename <old> <new>`
- **Inspect**: `rtk git remote -v` (URLs, offline) or `rtk git remote show <name>` (live tracking status)
- **Effective URLs**: `rtk git remote get-url <name>` shows the URL after `insteadOf` rewrites; `rtk git remote get-url --push --all <name>` lists every push URL
## Tracking, mirroring, housekeeping
- **Track one branch**: `rtk git remote add -t <branch> <name> <url>` (repeatable); `--no-tags` suppresses tag import entirely
- **Mirror**: `--mirror=fetch` mirrors all refs locally (bare repos only); `--mirror=push` makes every push behave like `--mirror`
- **Prune stale tracking refs without fetching**: `rtk git remote prune <name>`, with `--dry-run` to preview
- **Default branch pointer**: `rtk git remote set-head <name> -a` (auto-detect, needs a prior fetch), `... <branch>` (explicit), `... -d` (delete `refs/remotes/<name>/HEAD`)
## `set-url` — full form
```bash
rtk git remote set-url <name> <newurl> # replace the first fetch URL
rtk git remote set-url <name> <newurl> <oldurl-regex> # replace only the URL matching regex
rtk git remote set-url --push <name> <url> # change push URL only (must point at same repo)
rtk git remote set-url --add <name> <url> # add an extra push URL (push to multiple remotes)
rtk git remote set-url --delete <name> <regex> # remove URLs matching regex
```
`--push` changes only where pushes go — fetch and push URLs must still reference the same repository. For genuine fetch-from-A / push-to-B workflows, use two separate named remotes instead; `--push` cannot do this.

74
plugins/git/skills/git-remotes/references/sources.md
View File

@@ -1,74 +0,0 @@
---
# Research sources referenced by this skill
# Each entry documents where the skill's guidance came from.
---
## git-scm-remote-docs
**Description:** Git SCM official documentation for `git remote` command — remote configuration, add/remove/rename, URL management, inspection, and housekeeping.
**Source:** https://git-scm.com/docs/git-remote
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Remote Management (`git remote`)`
**Contributing files:**
- references/remote-config.md
---
## git-scm-fetch-docs
**Description:** Git SCM official documentation for `git fetch` command — fetching from remotes, tracking branch updates, pruning stale refs, shallow clones, and refspecs.
**Source:** https://git-scm.com/docs/git-fetch
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Fetching (`git fetch`)`
**Contributing files:**
- SKILL.md (Gotchas — prune does not touch tags)
- references/fetch.md
---
## git-scm-push-docs
**Description:** Git SCM official documentation for `git push` command — pushing branches, tags, force-push safety (--force-with-lease, --force-if-includes), refspecs, and multi-remote workflows.
**Source:** https://git-scm.com/docs/git-push
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Pushing (`git push`)`
**Contributing files:**
- SKILL.md (Gotchas — `--force-with-lease` caveat; Step 1 force-push gate)
- references/push.md
---
## git-scm-pull-docs
**Description:** Git SCM official documentation for `git pull` command — fetch + merge/rebase strategies, divergence resolution (--ff-only, --rebase, merge), config precedence, and pull-specific gotchas.
**Source:** https://git-scm.com/docs/git-pull
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Pulling (`git pull`)`
**Contributing files:**
- SKILL.md (Gotchas — pull default drift)
- references/pull.md (divergence rule; strategies; config precedence)
---
## context7-git-htmldocs
**Description:** Context7 MCP library providing current Git documentation and API reference — used for validation of modern Git syntax, behavior, and config semantics. This is a blanket cross-cutting reference and does not map to a single heading in the research doc; it informed terminology and syntax checks across all sections.
**Source:** Context7 MCP / Git library
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md (cross-cutting — no dedicated section)
**Contributing files:**
- SKILL.md (all sections)
- references/remote-config.md
- references/fetch.md
- references/push.md
- references/pull.md

66
plugins/git/skills/git-submodules/SKILL.md
View File

@@ -1,66 +0,0 @@
---
name: git-submodules
description: >
Use when managing Git submodules — the full lifecycle of a nested
repository inside a superproject — including phrasings that never say the
word, such as "add a dependency repo" or "vendor this repo inside ours".
Not multiple checkouts of one repo -> `git-worktrees`.
Not the superproject's own remotes -> `git-remotes`.
metadata:
version: "1.0.0"
category: git
source_keys:
- git-scm-submodule-docs
---
## Gotchas
- **`update` leaves the submodule in detached HEAD.** Branch inside the submodule before editing, or the work is unreachable once the pointer moves.
- **Push the submodule before the superproject.** The superproject stores only a SHA, and one missing from the submodule's remote breaks every collaborator's `update`.
- **`--recursive` is never the default.** Subcommands stop one level deep, so nested submodules go stale silently.
- **`git rm` leaves `.git/modules/<name>/` behind.** Nothing cleans it up, and it blocks re-adding a submodule there.
## Working rules
Run `rtk git` from the superproject root. Enter the submodule directory only for commits and pushes
that belong to the submodule's own history — the two repositories have independent histories, and
the same command from the wrong directory writes to the wrong one.
Before committing a superproject pointer, run `rtk git submodule status --recursive`. Prefixes: `-`
not initialized, `+` working tree differs from the recorded commit, `U` merge conflict. Add
`--cached` to read the SHAs the superproject index will record rather than the working-tree state.
A `-dirty` suffix means uncommitted changes inside the submodule, and committing the pointer over
them pins a state nobody else can reproduce.
To run one command across every submodule: `rtk git submodule foreach --recursive '<cmd>'`. Inside
`<cmd>`, Git sets `$name`, `$sm_path`, `$displaypath`, `$sha1` and `$toplevel`; append `|| :` to
continue past a failure instead of aborting the traversal. `$sm_path` and `$displaypath` name the
same directory from different vantage points — if which one you want is not obvious, read the
variable table in `references/setup-and-update.md` before writing the command.
## Dispatch
Read only the row that matches the request.
| Task | Reference |
|---|---|
| Clone a superproject with submodules; add, initialize, update or re-pin one; run a command across all of them with `foreach` | `references/setup-and-update.md` |
| Change where a submodule points — `sync`, `set-url`, `set-branch`, a local mirror override, `absorbgitdirs`, or any `.gitmodules` / `.git/config` key | `references/urls-and-config.md` |
| Remove a submodule, or `deinit` one without removing it | `references/removal.md` |
Removal and `deinit` are destructive: state what will be deleted and get confirmation before
executing.
## Output format
```yaml
operation: <clone|add|init|update|status|sync|set-url|set-branch|absorbgitdirs|deinit|remove>
status: <success|error|partial>
message: <one line; include git's own output on error>
details:
- <submodule-path>: <state>
conflicts: [<submodule-path>, ...]
next_step: <recovery action, when status is error or partial>
```

32
plugins/git/skills/git-submodules/references/removal.md
View File

@@ -1,32 +0,0 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Removing and deinitializing a submodule
Both operations are destructive. Confirm with the user before executing either.
## `deinit` is not removal
```bash
rtk git submodule deinit <path> # --all for every submodule, -f if locally modified
```
`deinit` clears the submodule's section from `.git/config` and empties its working tree. The
`.gitmodules` entry and the gitlink in the superproject's index are untouched, so the submodule is
still registered and a later `update --init` brings it straight back. Use it to reclaim disk space
or to reset a broken checkout, not to delete a dependency.
## Full removal, in order
```bash
rtk git submodule deinit -f <path> # unregister from .git/config
rtk git rm <path> # drop the .gitmodules entry and the gitlink from the index
rm -rf .git/modules/<name>/ # stale git dir: not tracked, not cleaned up by git
rtk git commit -m "chore: remove <name> submodule"
```
The third step is the one that gets skipped. `.git/modules/<name>/` survives `rtk git rm`, and while it
is present Git refuses to add a submodule at the same path again.

96
plugins/git/skills/git-submodules/references/setup-and-update.md
View File

@@ -1,96 +0,0 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Adding, initializing, updating and pinning submodules
## Clone a superproject that already has submodules
```bash
rtk git clone --recurse-submodules <url> # Git 2.13+, one step
# or, against an existing clone
rtk git submodule update --init --recursive
```
## Add a dependency as a submodule
```bash
rtk git submodule add <url> <path>
rtk git commit -m "chore: add <name> as submodule"
```
`add` stages a `.gitmodules` entry and a gitlink — the commit is still required. Flags:
| Flag | Meaning |
|---|---|
| `-b <branch>` | Track a branch (`submodule.<name>.branch`) instead of only a pinned commit |
| `--depth <n>` | Shallow clone |
| `-f` | Force past a gitignored path or a name conflict |
| `--name <name>` | Logical name differing from the path |
## Initialize without cloning
`rtk git submodule init [<path>...]` copies submodule URLs from `.gitmodules` into `.git/config` and
does nothing else. This is the point at which a local URL override can be edited before any fetch
happens. If a local mirror override is wanted, read `references/urls-and-config.md` before running
`update`. Use `update --init` to run both steps at once.
## Update
`rtk git submodule update --init --recursive` is the common case: it clones what is missing and checks
out the commit the superproject recorded, in detached HEAD.
| Flag | Meaning |
|---|---|
| `--init` | Run `init` first, avoiding a separate step |
| `--remote` | Use the submodule's remote branch tip instead of the superproject's recorded commit |
| `--checkout` | Detached HEAD at the recorded commit (default) |
| `--rebase` | Rebase the current branch onto the recorded commit |
| `--merge` | Merge the recorded commit into the current branch |
| `--recursive` | Operate on nested submodules |
| `--jobs <n>` | Parallel clone (defaults to `submodule.fetchJobs`) |
| `-N` / `--no-fetch` | Skip the remote fetch |
| `-f` | Discard local changes in the submodule working tree |
| `--depth <n>` | Shallow clone |
| `--filter <spec>` | Partial clone filter |
## Keep submodules pinned to the recorded commit
```bash
rtk git submodule update --recursive # after every rtk git pull
rtk git config submodule.recurse true # or do it automatically on pull/push/checkout
```
## Move the pin forward to the tracked branch tip
```bash
rtk git submodule update --remote --merge --recursive
rtk git commit -am "chore: update submodules to latest"
```
`--remote` uses `submodule.<name>.branch` when it is set; without it Git falls back to the remote's
default branch. Commit the superproject afterwards or the new pin is lost on the next `update`.
## Run one command across every submodule
```bash
rtk git submodule foreach --recursive '<command>'
rtk git submodule foreach 'git pull origin main || :' # || : continues past a failure
```
`<command>` runs inside each submodule's own working tree, so the git calls in it are the
submodule's own — that is the one place a bare `git` is correct. Append `|| :` to keep the
traversal going instead of aborting at the first failure.
Git exports five shell variables into `<command>`. `$sm_path` and `$displaypath` name the same
directory from different vantage points and are not interchangeable:
| Variable | Meaning |
|---|---|
| `$name` | Logical submodule name (the `.gitmodules` section name, which need not match the path) |
| `$sm_path` | Path relative to the superproject root |
| `$displaypath` | Path relative to the current working directory |
| `$sha1` | Commit SHA the superproject has recorded for this submodule |
| `$toplevel` | Absolute path of the superproject's root |

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

@@ -1,31 +0,0 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
## git-scm-submodule-docs
**Description:** Official git-scm.com reference for `git submodule` — all subcommands, flags, configuration keys, and behaviour details.
**Source:** https://git-scm.com/docs/git-submodule
- **Research doc:** plugins/git/docs/research/docs/git/submodules.md (whole-document reference — the research doc is organized by descriptive prose headings such as "Concept Overview" and "Key Commands" rather than a heading matching this slug; this key covers the entire doc, not a single section)
**Contributing files:**
- SKILL.md (all sections)
- references/setup-and-update.md (all sections)
- references/urls-and-config.md (all sections)
- references/removal.md (all sections)
---
Other source keys extracted during the git plugin research phase inform sibling skills in the git workflow suite, not this one:
- `context7-git-htmldocs` — git-branches, git-history, git-remotes
- `git-scm-docs` — no current skill; it backed a git-configuration skill that no longer exists and survives here as provenance only
- `git-scm-worktree-docs` — git-worktrees
- `nvie-gitflow-post`, `atlassian-gitflow-tutorial`, `gitflow-cheatsheet` — git-branches
- `conventional-commits-spec`, `commitlint-config-conventional` — git-commits
- `git-scm-push-docs`, `git-scm-fetch-docs`, `git-scm-pull-docs`, `git-scm-remote-docs` — git-remotes
- `git-scm-bisect-docs`, `git-scm-log-docs`, `git-scm-diff-docs` — git-history

79
plugins/git/skills/git-submodules/references/urls-and-config.md
View File

@@ -1,79 +0,0 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Where a submodule points, and how it is configured
## Two files, two audiences
- **`.gitmodules`** — version-controlled, shared with collaborators. Defines each submodule's
logical name, path, and canonical URL.
- **`.git/config`** — local only, populated by `rtk git submodule init`. Local URL overrides live here
and never propagate to another clone.
The submodule's own `.git` directory lives at `.git/modules/<name>/` in the superproject and is
linked to the submodule's working tree by a `.git` pointer file.
## `.gitmodules` keys
| Key | Purpose |
|---|---|
| `submodule.<name>.path` | Working tree path |
| `submodule.<name>.url` | Remote URL |
| `submodule.<name>.branch` | Branch used by `update --remote` |
| `submodule.<name>.update` | Default update procedure |
| `submodule.<name>.shallow` | Recommend a shallow clone |
## `.git/config` keys
| Key | Purpose |
|---|---|
| `submodule.<name>.url` | Local URL override |
| `submodule.<name>.update` | Local procedure override |
| `submodule.fetchJobs` | Default parallelism for `update --jobs` |
| `submodule.recurse` | Auto-recurse submodule updates on `pull`/`push`/etc. |
## Rebind a URL or branch
```bash
rtk git submodule sync --recursive # push .gitmodules URLs into .git/config
rtk git submodule set-url <path> <url> # change the canonical URL
rtk git submodule set-branch -b <branch> <path> # set the branch used by update --remote
```
Run `sync` after an upstream rename: existing clones keep the stale URL in `.git/config` until
they do.
## Override a URL locally (private mirror)
```bash
rtk git submodule init
# edit .git/config: submodule.<name>.url = <mirror-url>
rtk git submodule update
```
Local-only, invisible to collaborators, and overwritten by the next `sync`.
## Relative URLs
A `../foo.git` entry in `.gitmodules` resolves against the superproject's default remote URL, not
against the filesystem. It is portable across hosts that mirror the same layout and broken
everywhere else.
## Custom `update` commands are security-gated
A `.gitmodules` entry of `update = !some-command` is never copied into `.git/config` by
`rtk git submodule init`. That is deliberate: it stops a hostile clone from silently executing
arbitrary code. Setting it locally in `.git/config` is the only way to enable it.
## Relocate an embedded `.git` directory
```bash
rtk git submodule absorbgitdirs [<path>...]
```
Moves a submodule's own `.git` directory into `.git/modules/<name>/` and leaves a `.git` pointer
file behind. Needed when a nested repository was created or copied in without going through
`rtk git submodule add`.

80
plugins/git/skills/git-workflow/SKILL.md
View File

@@ -1,80 +0,0 @@
---
name: git-workflow
description: >
Use when a human's local git request is general or ambiguous — it routes to the owning
domain skill: `git-commits`, `git-branches`, `git-history`, `git-remotes`, `git-submodules`
or `git-worktrees`. An unambiguous request goes straight to its domain skill instead. Not an
agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`.
metadata:
version: "1.0.2"
category: git
source_keys:
- nvie-gitflow-post
- atlassian-gitflow-tutorial
- gitflow-cheatsheet
- context7-git-htmldocs
- org-git-conventions
---
## Gotchas
- Session context built during one multi-step request — branch names, the chosen base, the commit
strategy — persists for that request and then clears. Do not re-ask the user for a decision they
already gave you earlier in the same workflow.
- Run parent-repo commands through `rtk git <command>`, never bare `git <command>`. This is a
mandated org wrapper, not a style preference. Submodule-specific commands run from inside the
submodule's own directory instead.
## Domains
Route to the domain that owns the operation, and in sequence when a request spans two — a rebase
that ends in a force-push is `git-commits`, then `git-remotes`. An unambiguous request should have
gone straight to the domain skill; this one exists for the ones that did not.
| The request is about | Domain |
|---|---|
| Writing, amending, squashing, or cherry-picking a commit, and its message | `git-commits` |
| Rebasing onto a new base, or undoing a commit with `reset` | `git-commits` |
| Creating, switching, deleting, renaming, tracking, or merging a local branch | `git-branches` |
| Stashing work in progress to move between branches | `git-branches` |
| When a change landed, which commit broke something, what to revert or backport | `git-history` |
| Anything touching a remote — remote config, fetch, push, pull — even unnamed | `git-remotes` |
| A nested repository pinned inside this one by a recorded commit | `git-submodules` |
| Several branches checked out at once, in separate directories, without stashing | `git-worktrees` |
`git-orchestrate` executes whatever this resolves to (step 5); the table only decides which domain
owns the request.
## Workflow
1. **Parse intent** — extract the operation and, from the table above, the domain that owns it,
plus any options the user named.
2. **Check the hard rules** — if the request creates, amends, or rewrites a commit, pushes, or
touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule
before acting, not after.
3. **Read the repo** — current branch, working-tree state, and which branching model the repo
follows (`git-branches` infers this from branch names: Gitflow if `develop`/`release/*` exists,
GitHub Flow otherwise); the last of those decides which tips are worth offering.
4. **Gate destructive operations** — before force-push, branch deletion, rebase, or
force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user
declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not
confirmations — never offer "Proceed?" for a force-push of `main`/`master`.
5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or
inferred), `context` (step 3 plus the session context), and `confirm: true` only for a
destructive op the user approved in step 4.
6. **Clarify when the orchestrator asks for more** — put its question to the user in plain
language ("Which branch should this be based on?") and loop back to step 5 with the answer.
7. **Report the outcome** — on success, the result and what changed, in plain language; on
failure, the error reason and a recovery action.
## Interaction style
The caller is a human, so the interaction is the point. Explain each step and why it happens ("I'm
squashing your last 3 commits into one clean commit" beats "Squashing commits"), show progress as
you go, and prefer natural language to raw command lines.
Match tips to the repo's branching model rather than offering generic advice: on a Gitflow repo,
feature branches come off `develop` and `main` tracks only released code; on a trunk-based or
GitHub Flow repo, short-lived branches off `main` keep merges small and reviewable.

25
plugins/git/skills/git-workflow/references/hard-rules.md
View File

@@ -1,25 +0,0 @@
---
source_keys:
- org-git-conventions
---
# Org git hard rules
Non-negotiable regardless of what the user asks for. Surface the relevant one proactively rather
than waiting for the user to hit it — a human invoking this skill directly never sees the
orchestrator's copy of these rules, so raise them here.
- Never skip hooks with `--no-verify` — hooks are the automated QA gate, and bypassing them breaks
the pipeline for everyone downstream.
- Never force-push `main` or `master`.
- Keep commits atomic — each commit should represent one logical, independently reviewable and
reversible change.
- Every commit must leave the repository in a working state (buildable/testable where practical).
- Commit messages explain **why**, not **what** — the diff already documents what changed.
- Never commit secrets, credentials, or environment-specific config.
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
- Reference related issues, ADRs, or design documents using Git trailers when applicable.
If a user's request conflicts with one of these (e.g. "force-push main to fix this"), explain the
rule and propose a safe alternative instead of complying. Do not comply and note the rule
afterwards.

60
plugins/git/skills/git-workflow/references/sources.md
View File

@@ -1,60 +0,0 @@
---
# Research sources referenced by this skill
# Each entry documents where the skill's guidance came from.
---
## nvie-gitflow-post
**Description:** Original 2010 post by Vincent Driessen introducing the Gitflow branching model, including a 2020 reflection note recommending GitHub Flow for continuous delivery teams.
**Source:** https://nvie.com/posts/a-successful-git-branching-model/
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
**Contributing files:**
- SKILL.md (Interaction style — branching-model-aware tips)
## atlassian-gitflow-tutorial
**Description:** Atlassian's comprehensive Gitflow tutorial covering all five branch types, lifecycle steps, and CLI usage.
**Source:** https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
**Contributing files:**
- SKILL.md (Interaction style — branching-model-aware tips)
## gitflow-cheatsheet
**Description:** Visual cheatsheet for the git-flow CLI commands (git-flow-avh fork), covering all subcommands for feature, release, and hotfix branches.
**Source:** https://danielkummer.github.io/git-flow-cheatsheet/
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
**Contributing files:**
- SKILL.md (Interaction style — branching-model-aware tips)
## context7-git-htmldocs
**Description:** Official Git HTML documentation from the git/htmldocs repository — covers all commands, concepts, and internals.
**Source:** context7:/git/htmldocs
- **Research doc:** plugins/git/docs/research/docs/git/overview.md (whole-document reference)
**Contributing files:**
- SKILL.md (Workflow — general git operation vocabulary)
## org-git-conventions
**Description:** This org's internal git conventions (hard rules on hooks, force-push, atomic commits, secrets, Conventional Commits, trailers, and the `rtk git` wrapper requirement). Originally maintained as a standalone instruction file loaded into every agent's context; embedded directly into this skill because that central file has been removed from the repo, and skill content must stay self-contained after plugin installation.
**Source:** org-internal (formerly `core/instructions/git.md` in this repo, prior to its removal)
- **Research doc:** none — org convention, not part of the plugin's research corpus (no `plugins/git/docs/research/` topic file backs this entry)
**Contributing files:**
- references/hard-rules.md (whole file — the eight hard rules and the conflict-handling rule)
- SKILL.md (Gotchas — `rtk git` wrapper note)

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

@@ -1,68 +0,0 @@
---
name: git-worktrees
description: >
Use when working on several branches at once without stashing —
manages the full lifecycle of a git worktree.
Not ordinary branch switching or checkout -> `git-branches`.
Not interactive multi-step git guidance -> `git-workflow`.
metadata:
version: "1.0.2"
category: git
source_keys:
- git-scm-worktree-docs
---
## Gotchas
- **A branch can be checked out in only one worktree at a time.** `git worktree add` on an already-checked-out branch fails; `--force` is the only override, so use it only deliberately.
- **Never `rm -rf` a worktree directory.** That strands metadata in `$GIT_DIR/worktrees/`. Use `rtk git worktree remove`, or `rtk git worktree prune` afterwards.
- **Submodules break worktree support.** A worktree containing submodules cannot be moved at all, and needs `--force` to remove.
- **`extensions.worktreeConfig = true` is a one-way door.** Without it, `git config --worktree` errors; with it, that flag writes to the worktree's own `config.worktree` file, and `core.bare`/`core.worktree` are forced there too. It also breaks older Git. Leave it off unless per-worktree config is needed.
## Step 1 — Dispatch
| Operation | Run |
|---|---|
| Create on a branch that already exists locally | `rtk git worktree add <path> <branch>` |
| Create on a new branch | `rtk git worktree add -b <branch> <path>` |
| Create on the branch named after the path basename | `rtk git worktree add <path>` — checks that branch out if it exists, else creates it from HEAD |
| Create and reset an existing branch to HEAD — discards its commits | `rtk git worktree add -B <branch> <path>` |
| 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 |
| **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 (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>` |
| Move | `rtk git worktree move <from> <to>` |
| Remove | `rtk git worktree remove <path>` |
| Prune stale metadata | `rtk git worktree prune --dry-run`, then without the flag |
| Repair after a manual move | `rtk git worktree repair` — in the main worktree if *it* moved, or inside a linked worktree that moved. `rtk git worktree repair <path>...` — from any worktree, naming each moved linked worktree's new path |
If the operation needs anything the table does not carry — the full `add` flag
table, orphan branches, sparse-checkout, locking for removable media, remote
disambiguation across several remotes, how to name a worktree unambiguously,
worktree config keys, or the worked emergency-fix and PR-review patterns — read
`references/worktrees.md`.
Gates:
- **`move`, `remove` — the main worktree cannot be moved or removed.** Only linked worktrees, the ones `git worktree add` created, are candidates.
- **`add`, `move`, `remove` — escalate force flags one step at a time.** `-f` overrides a safeguard such as an unclean tree; `move` and `remove` need `-ff` on top of that when the worktree is locked. Confirm with the user before either — both discard state.
- **`add` — lock at creation, not after.** `rtk git worktree add --lock` is atomic, where add-then-`lock` leaves a window in which the worktree is unprotected.
## Step 2 — Report
```yaml
worktrees:
- path: <directory-path>
branch: <branch-name>
commit: <short-hash>
locked: <true/false>
lock_reason: <reason or empty>
```
Derive those fields from `git worktree list --porcelain -z` — bare, not `rtk`:
rtk drops both flags and never emits `locked`/`lock_reason`. For a single
operation, report its outcome instead — `created: true`, `moved: true`,
`removed: true`.

16
plugins/git/skills/git-worktrees/references/sources.md
View File

@@ -1,16 +0,0 @@
---
# Research sources referenced by this skill
# Each entry documents where the skill's guidance came from.
---
## git-scm-worktree-docs
**Description:** Git SCM official documentation for `git worktree` command — creating, listing, locking, moving, removing, pruning, and repairing linked worktrees; shared vs. per-worktree state; worktree-scoped config.
**Source:** https://git-scm.com/docs/git-worktree
- **Research doc:** plugins/git/docs/research/docs/git/worktrees.md (whole-document reference — covers `## Concept Overview`, `## Key Commands`, `## Workflow Patterns`, `## Common Gotchas`, `## Configuration`)
**Contributing files:**
- SKILL.md (Gotchas, Step 1 dispatch table and per-operation gates, Step 2 report format)
- references/worktrees.md (shared vs. per-worktree state, `add` command forms, full `add` flag table, orphan branches, sparse-checkout, removable media, remote disambiguation, `repair` invocation directory, configuration, workflow patterns)

178
plugins/git/skills/git-worktrees/references/worktrees.md
View File

@@ -1,178 +0,0 @@
---
topic: worktrees
source_keys:
- git-scm-worktree-docs
---
# Git worktrees
## Shared vs. per-worktree state
All worktrees share one object store, one config, and most refs under `refs/`. Each worktree keeps
its own `HEAD`, index, and per-worktree metadata (`ORIG_HEAD`, `MERGE_HEAD`, `refs/bisect/`,
`refs/worktree/`, `refs/rewritten/`) under `$GIT_DIR/worktrees/<name>/`. Exactly one **main
worktree** exists per repo — the one `git init` or `git clone` produced — and it cannot be removed
or moved. Every other worktree is a **linked worktree** created by `git worktree add`.
## Identifying a worktree
`lock`, `move`, `remove` and `repair` accept a full path, a unique basename, or a unique partial
path. An ambiguous name errors rather than picking one; `git worktree list` shows the identifiers
that are usable.
## `add` forms
```bash
rtk git worktree add <path> <branch> # <branch> exists locally: check it out — non-destructive
rtk git worktree add -b <branch> <path> # create a new branch; fails if it exists
rtk git worktree add <path> # branch named after $(basename <path>): checked out
# if it exists, else created from HEAD
rtk git worktree add -B <branch> <path> # create the branch, or reset an existing one to HEAD,
# discarding the commits it carried
rtk git worktree add --track -b <branch> <path> <remote>/<branch>
# new local branch tracking the remote — always works
rtk git worktree add <path> <branch> # <branch> absent locally and in exactly one remote:
# Git expands this to the --track -b form above
rtk git worktree add -d <path> # detached HEAD, no branch
```
The same `git worktree add <path> <branch>` spelling appears twice above and does two
different things: it checks out a local branch when one exists, and only otherwise falls
through to the remote-tracking shortcut. Read the local branch list before relying on either.
**Do not write `git worktree add <path> <remote>/<branch>`.** A remote-tracking ref resolves as a
commit-ish, so the tracking shortcut never fires and the worktree lands on a **detached HEAD with
no local branch and no upstream** — commits there go unreachable once HEAD moves or the worktree is
removed, and `git push` fails without an explicit refspec. That spelling is correct only as the
final argument of the `--track -b` form.
## Full `add` flag table
| Flag | Meaning |
|---|---|
| `-b <branch>` | Create and check out a new branch; fails if it exists |
| `-B <branch>` | Like `-b` but resets the branch if it already exists |
| `-d` / `--detach` | Detach HEAD; useful for throwaway experiments |
| `--orphan` | Create empty unborn branch — **Git 2.42+**; earlier versions exit 129 with `error: unknown option 'orphan'`. Fallback below |
| `--no-checkout` | Suppress initial checkout (for sparse-checkout setup) |
| `--guess-remote` | Look for a matching remote-tracking branch by path basename |
| `--lock [--reason <str>]` | Lock immediately on creation (atomic; avoids race vs. add-then-lock) |
| `-f` / `--force` | Allow when branch is already checked out elsewhere |
| `--relative-paths` | Link via relative paths (portable across moves) |
Using `-` as `<commit-ish>` is shorthand for `@{-1}` (the branch checked out before the current one), e.g. `git worktree add <path> -`.
## New unborn branch
```bash
rtk git worktree add --orphan -b <branch> <path>
```
Creates an empty branch with no commits. **`--orphan` needs Git 2.42 or later** — it was added
upstream in 2.42, and on 2.39.5 this fails with `error: unknown option 'orphan'` and exit 129.
Check `rtk git --version` before reaching for it.
Fallback on older Git, verified on 2.39.5 — detach first, then orphan the linked worktree in place,
which leaves the main worktree on its own branch throughout:
```bash
rtk git worktree add -d <path> # linked worktree, detached HEAD
cd <path>
rtk git switch --orphan <branch> # unborn branch: empty index, empty working tree
```
`git worktree list` then shows the new worktree at `0000000 [<branch>]` until its first commit.
Do not substitute `git switch --orphan` in the *main* worktree: it clears that checkout, which is
the disruption worktrees exist to avoid.
## Sparse-checkout worktree
Suppress the initial checkout to configure sparse-checkout first:
```bash
rtk git worktree add --no-checkout ../sparse main
cd ../sparse
rtk git sparse-checkout init --cone
rtk git sparse-checkout set src/
rtk git checkout main
```
## Worktree on removable media
```bash
rtk git worktree add --lock --reason "external SSD" <path> <branch>
rtk git worktree unlock <path> # when reconnected
```
## Remote-branch disambiguation
```bash
rtk git worktree add --track -b <branch> <path> <remote>/<branch> # explicit: no guessing at all
rtk git worktree add <path> <branch> # shortcut: needs one clear remote
```
**The bare-name shortcut needs exactly one remote.** It fires only when `<branch>` is not found
locally, none of `-b`/`-B`/`--detach` were given, and a tracking branch of that name exists in
exactly one remote. When several remotes carry the name, `checkout.defaultRemote` picks one for
disambiguation purposes; with no such setting the shortcut has no single remote to resolve against
and does not apply. When the remote is ambiguous or unknown, use the explicit `--track -b` form.
`--guess-remote` covers the *other* spelling — `git worktree add <path>` with no `<commit-ish>` at
all. It bases the new branch on the remote-tracking branch matching `$(basename <path>)` when
exactly one remote has it, and marks that branch as upstream. Its default comes from the
`worktree.guessRemote` config.
## Repair after a manual move
```bash
rtk git worktree repair # the MAIN worktree moved: run it there to reconnect every linked
# worktree back to the main worktree
rtk git worktree repair # a LINKED worktree moved: run it inside that recently-moved worktree
rtk git worktree repair <path>... # reconnect a specific linked worktree — runnable from any worktree,
# naming each moved tree's new path
```
Which form applies depends on what moved:
| What moved | Remedy |
|---|---|
| The main worktree (or bare repo) | `rtk git worktree repair` in the main worktree |
| One linked worktree | `rtk git worktree repair` inside that worktree |
| Several linked worktrees | `rtk git worktree repair <path>...` from any worktree, listing each new path |
| Both main and linked worktrees | `rtk git worktree repair <path>...` in the main worktree, naming each linked worktree's new path — this restores the connections in both directions |
Only the no-argument form is tied to the current directory. The `<path>...` form is not — it
reestablishes the connection to every path you name, run from any worktree.
## Configuration
| Key | Effect |
|---|---|
| `worktree.guessRemote` | Default for `--guess-remote` on `git worktree add` |
| `worktree.useRelativePaths` | Default for `--relative-paths` on `git worktree add` (link via relative paths — portable across moves) |
| `gc.worktreePruneExpire` | How long before stale worktree metadata is pruned by `git gc` |
| `extensions.worktreeConfig` | Enable per-worktree config scope (`config.worktree` file) — see Gotchas in SKILL.md |
| `checkout.defaultRemote` | Disambiguates which remote to use when a branch name matches multiple remotes during `worktree add` |
## Workflow patterns
**Emergency fix without disrupting current work** — nothing is stashed, and the main worktree is
untouched throughout:
```bash
rtk git worktree add -b emergency-fix ../temp main
cd ../temp
# fix, then commit
rtk git commit -a -m "fix: critical production bug"
cd -
rtk git worktree remove ../temp
```
**Review a PR branch alongside your own work** — both branches stay checked out, so there is no
context switch:
```bash
rtk git worktree add ../review-pr-123 origin/feature-xyz # detached HEAD — read-only review
rtk git worktree add --track -b feature-xyz ../review-pr-123 origin/feature-xyz # if you will commit
# open ../review-pr-123 in a second editor window or terminal
```
Pick the second form the moment you intend to push anything back: the first leaves no branch to
push and no upstream to push to.

38
plugins/git/skills/pc-author/SKILL.md
View File

@@ -1,38 +0,0 @@
---
name: pc-author
description: >
Use when the user wants to create or edit `.pre-commit-config.yaml` — add,
remove, or configure hooks — even when they name only the tool ("add
shellcheck"). Not running, installing, or updating hooks -> `pc-run`.
allowed-tools: Bash Read Write Edit
metadata:
version: "1.0.0"
category: devtools
source_keys:
- context7-pre-commit-com
- pre-commit-com
- context7-pre-commit-hooks
- pre-commit-hooks-github
---
## Gotchas
- `rev` must be an immutable tag or commit SHA, never a branch name. A branch looks like it works and then breaks `pre-commit autoupdate` silently.
- `pre-commit validate-config` checks YAML structure only — it never confirms a hook `id` exists upstream, so a config it accepts can still fail on first use.
## Route
| Condition | Flow | Read |
|---|---|---|
| No `.pre-commit-config.yaml` in the repo | Create | `references/create-config.md` |
| `.pre-commit-config.yaml` exists | Modify | `references/modify-config.md` |
Read only the file matching the resolved flow — each is self-contained.
The target is always `.pre-commit-config.yaml`, the config that consumes hooks. A request to publish hooks for other repos to consume means `.pre-commit-hooks.yaml`, a different file this skill does not author.
## Gates common to both flows
1. State the proposed config or edit in full and wait for confirmation before writing. Hook choices are opinions imposed on everyone else's commit loop, not defaults to assume.
2. Run `pre-commit validate-config` after every write. On a non-zero exit, show the error and resolve it before reporting done — never leave a config that cannot be parsed.
3. Never edit a `rev` value. Report staleness and hand the bump to `pc-run`, which runs `autoupdate` against the hook repos themselves.

31
plugins/git/skills/pc-author/references/create-config.md
View File

@@ -1,31 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Creating a `.pre-commit-config.yaml`
Reached from `SKILL.md`'s Route table when the repo has no config yet. Self-contained — the modify
flow's file is not needed here. `SKILL.md`'s three common gates still apply.
## Steps
1. Detect what languages are actually in the repo with a shallow extension scan, rather than
inferring them from the project's name or README:
```bash
rtk git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
```
2. Read `references/hooks-by-language.md` and map the detected extensions to recommended hooks.
Take the repo URL, `rev` and args from that file rather than from memory — a `rev` that does not
exist is the most common way a fresh config fails on its first run.
For a deliberately minimal starting point instead of a full recommendation set,
`pre-commit sample-config > .pre-commit-config.yaml` prints a small starter config to build on.
3. State the proposed config in full and wait for the user's confirmation.
4. Write `.pre-commit-config.yaml`, then run `pre-commit validate-config`. If it exits non-zero,
show the error, fix it in place, and re-validate.

92
plugins/git/skills/pc-author/references/hooks-by-language.md
View File

@@ -1,92 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
- context7-pre-commit-hooks
- pre-commit-hooks-github
---
# Hook Recommendations by Language / Context
Use this table when creating a config from scratch or recommending hooks to add.
Always check the existing config for duplicates before proposing.
Fixer hooks (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json` and the like) rewrite
files but do NOT re-stage them, so the commit is still blocked and the user has to stage and commit
again. Say so when proposing one — otherwise the first blocked commit reads as the hook being
broken.
## `pre-commit/pre-commit-hooks` (rev `v6.0.0`)
| Hook ID | Language / Context |
|---------|---------------------|
| `end-of-file-fixer` | Universal |
| `trailing-whitespace` | Universal |
| `check-merge-conflict` | Universal |
| `detect-private-key` | Universal |
| `check-added-large-files` | Universal |
| `check-case-conflict` | Universal |
| `mixed-line-ending` | Universal |
| `no-commit-to-branch` | Universal — defaults to blocking `main`+`master` with no args; add `args: [--branch, <name>]` only to protect additional branch names |
| `check-ast` | Python (`.py`) |
| `check-builtin-literals` | Python (`.py`) |
| `check-json` | JSON (`.json`) |
| `pretty-format-json` | JSON (`.json`) |
| `check-yaml` | YAML (`.yaml`, `.yml`) — for Kubernetes/Helm with custom tags add `args: ['--unsafe']` and `exclude: ^helm/templates/` |
| `check-toml` | TOML (`.toml`) |
Full repo URL: `https://github.com/pre-commit/pre-commit-hooks`. For Python formatting, check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them.
## Other repos
| Hook ID | Repo | Rev | Notes |
|---------|------|-----|-------|
| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | **Unverified — not in research corpus, verify upstream before use.** Recommended args: `args: [--severity=warning]` |
| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.30.1` | **Unverified — not in research corpus, verify upstream before use.** |
| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | Stage `commit-msg`; also add `default_install_hook_types: [pre-commit, commit-msg]` to the top-level config if not already present |
## Meta-validation (add last, after all other repos)
```yaml
- repo: meta
hooks:
- id: check-hooks-apply # catches hooks that match no files
- id: check-useless-excludes # catches exclude patterns that match no files
```
## Local hooks (repo: local)
Use for repo-specific scripts that don't belong in an external hook repo.
```yaml
- repo: local
hooks:
- id: run-tests
name: Run test suite
entry: bash tests/run-tests.sh
language: unsupported_script
pass_filenames: false
always_run: true
stages: [pre-push]
```
`language: system` and `language: script` are deprecated names for the first two below.
New local hooks use `unsupported` and `unsupported_script`.
Language choices for local hooks:
- `unsupported` — system PATH tool (pre-commit does not manage env)
- `unsupported_script` — script at a repo-relative path
- `fail` — always-fail guard; `entry` text becomes the error message
- `python` — isolated venv; use `additional_dependencies` for pip packages
- `node` — isolated node env; `additional_dependencies` are npm packages
- `ruby` — isolated gem env; `additional_dependencies` are gems
- `golang` — builds from source; `additional_dependencies` are Go module paths
- `rust` — Cargo build
- `docker` — Docker image built from `entry`; use when no other language fits
- `docker_image` — pulls a pre-built Docker image by `entry`
- `conda` — Conda environment; conda-native hooks
- `coursier` — Coursier (Scala/JVM) environment; JVM hooks
## Rev pin freshness
The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats these tables as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against these tables.

75
plugins/git/skills/pc-author/references/modify-config.md
View File

@@ -1,75 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Modifying an existing `.pre-commit-config.yaml`
Reached from `SKILL.md`'s Route table when the repo already has a config. Self-contained — the
create flow's file is not needed here. `SKILL.md`'s three common gates still apply.
Read the existing `.pre-commit-config.yaml` before editing. Note any stale `rev` values (see
**Rev staleness** below) but do not change them.
## Adding a hook
1. Run a shallow extension scan, so the addition is judged against the languages actually present:
```bash
rtk git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
```
2. Read `references/hooks-by-language.md` for the correct repo URL, `rev` and recommended args
before writing anything.
3. Check for duplicates. If the same hook ID, or an equivalent tool, is already configured, say so
and stop rather than adding a second one.
4. To sanity-check a hook against the repo's real files before committing to it, smoke-test it:
```bash
pre-commit try-repo <repo-url> <hook-id> --verbose
```
Use a local path in place of the URL for a hook under development. This runs the hook without
writing anything.
5. If the hook's source repo is already a block in the config, add the hook under that block.
Otherwise append a new repo block.
6. State the proposed addition, wait for confirmation, write, and run `pre-commit validate-config`.
On a non-zero exit, show the error, fix it, and re-validate.
## Removing a hook
1. Identify the hook entry and its parent repo block.
2. State what will be removed — the hook ID, and whether the parent repo block goes with it because
it would be left with zero hooks. Wait for confirmation.
3. Remove the hook entry. If the repo block now has no hooks left, remove the whole block: an empty
`hooks: []` fails `validate-config`.
4. Write, then run `pre-commit validate-config`. On a non-zero exit, **revert the edit**, show the
error, and stop. A removal is not safely fixable in place the way a malformed new hook block is,
so recovering the prior state beats patching forward.
## Configuring top-level keys
Only when the user explicitly asks. Valid keys: `fail_fast`, `default_stages`,
`default_language_version`, `minimum_pre_commit_version`, `exclude`, `files`,
`default_install_hook_types`.
State the proposed change and wait for confirmation before writing.
## Rev staleness
For each repo in the config that also appears in `references/hooks-by-language.md`, compare the
two `rev` values. Flag a mismatch as potentially outdated and tell the user to run `pc-run` to
autoupdate. Repos absent from the reference cannot be checked — skip them silently. Do not modify
any `rev` yourself.
The reference table's own pins go stale between updates, so treat a mismatch as a prompt to check
rather than proof of staleness. `pre-commit autoupdate`, via `pc-run`, is the authoritative answer
to what the current `rev` actually is.

33
plugins/git/skills/pc-author/references/sources.md
View File

@@ -1,33 +0,0 @@
# Sources
## context7-pre-commit-com
- **URL:** context7:/pre-commit/pre-commit.com
- **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting
- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
- **Status:** `extracted`
## pre-commit-com
- **URL:** https://pre-commit.com/
- **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration
- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
- **Status:** `extracted`
## context7-pre-commit-hooks
- **URL:** context7:/pre-commit/pre-commit-hooks
- **Description:** Official pre-commit-hooks collection — all available hook IDs with options and examples
- **Contributing files:** references/hooks-by-language.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/hooks-reference.md § pre-commit-hooks (official collection)
- **Status:** `extracted`
## pre-commit-hooks-github
- **URL:** https://raw.githubusercontent.com/pre-commit/pre-commit-hooks/main/README.md
- **Description:** Official pre-commit-hooks README — complete hook listing with all args, categories, deprecated hooks, and latest version (v6.0.0)
- **Contributing files:** references/hooks-by-language.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/hooks-reference.md § pre-commit-hooks (official collection), § Deprecated hooks
- **Status:** `extracted`

62
plugins/git/skills/pc-run/SKILL.md
View File

@@ -1,62 +0,0 @@
---
name: pc-run
description: >
Use when the user wants to run pre-commit hooks, wire them into git, bump hook
revs, maintain the cache, or diagnose why a hook fails or never fires. Not
creating or editing the pre-commit config -> `pc-author`.
compatibility: Requires pre-commit installed and available on PATH.
metadata:
version: "1.0.1"
category: devtools
source_keys:
- context7-pre-commit-com
- pre-commit-com
allowed-tools: Bash Read
---
## Gotchas
- The `SKIP` env var takes exact hook `id` values, comma-separated with no spaces: `SKIP=check-yaml,gitleaks rtk git commit -m "msg"`. A space after a comma silently skips nothing instead of erroring.
- Never bypass a failing hook with `git commit --no-verify` (or `-n`). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead.
- `- files were modified by this hook` is not a bug. A fixer hook rewrote a staged file, so the staged snapshot is stale and the commit is blocked on purpose. Re-stage and re-run the same commit: `rtk git add -u && rtk git commit`. Do NOT reach for `pre-commit install -f` here — it overwrites `.git/hooks/` and has nothing to do with re-staging.
## Gate — `pre-commit clean`
Confirm with the user before running `pre-commit clean`, on every path that reaches it — including when it turns up as the fix for a stale or broken environment. It wipes the whole cache at `~/.cache/pre-commit`, which is machine-wide and shared by every repo on the box, forcing every hook environment to be re-downloaded.
> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
`pre-commit gc` drops only unused environments and needs no confirmation — prefer it when the goal is just to reclaim disk.
## Route
Determine intent from the user's request, then execute the matching operation. Where the matching row names a `references/` file, read that one file and no other — each flow file is self-contained.
| User intent | Operation |
|---|---|
| "run", "check", "verify", "test hooks" | `pre-commit run --all-files` (default) |
| "staged", "simulate commit" | `pre-commit run` (staged files only) |
| "CI", "changed files only", "diff range" | `pre-commit run --from-ref <base> --to-ref <head>` — prefer this over `--all-files` on large repos |
| "install", "set up hooks", "wire into git" | `pre-commit install` — read `references/install.md` |
| "pre-create environments", "warm cache" | `pre-commit install-hooks` — builds every hook environment without running a hook |
| "remove hooks", "uninstall", "tear down" | `pre-commit uninstall` — removes pre-commit from `.git/hooks/` |
| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` — read `references/autoupdate.md` |
| "gc", "garbage collect" | `pre-commit gc` — drops unused cached environments only, safe at any time |
| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — read `references/clean.md` |
| "hooks aren't running", "hook never fires", "why did a hook fail", a hook failure whose cause is unclear | Diagnose — read `references/failure-patterns.md` |
If the intent is ambiguous, default to `pre-commit run --all-files` — do not stop to ask, and do
not fall through to a narrower row on a guess.
## Run
Default to `pre-commit run --all-files`; never silently narrow to staged files. Run `pre-commit run` (staged only) or `pre-commit run <hook-id>` (one named hook) when the user asks for it.
When hooks fail:
1. Name the hook and the specific cause. Be concrete — "gitleaks blocked `config.json` (high-entropy string on line 12)", not "gitleaks failed".
2. Suggest one concrete next step. Common causes and their concrete fixes are in `references/failure-patterns.md` — read it whenever the output does not already name the fix.
3. Do not auto-fix code files, and do not edit `.pre-commit-config.yaml` — those belong to the user or to `pc-author`.

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

@@ -1,17 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Bumping hook revs with `autoupdate`
Reached from `SKILL.md`'s Route table when the user asks to update hook versions or bump revs. Self-contained.
```bash
pre-commit autoupdate
```
This rewrites `.pre-commit-config.yaml` in place, so re-read the file afterwards and report which `rev` values changed. It is the one operation in this skill that writes that file, and the exception is deliberate: the rewrite is pre-commit's own, resolved against the hook repos, not a hand edit — which is why `pc-author` hands rev bumps here rather than making them itself.
Add `--freeze` when the user wants exact SHAs pinned for reproducibility.

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

@@ -1,17 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Wiping the pre-commit cache
Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. The confirmation gate on `pre-commit clean` stays in `SKILL.md`, because it must fire on every path that reaches this command, not only this one.
## Gate
`pre-commit clean` runs only after the confirmation gate in `SKILL.md` clears — that gate, its exact wording, and the `pre-commit gc` alternative live there and are not restated here.
```bash
pre-commit clean
```

109
plugins/git/skills/pc-run/references/failure-patterns.md
View File

@@ -1,109 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Hook Failure Patterns
Common hook failure causes and concrete next-step suggestions.
## Hook modified files — commit blocked
Cause: A fixer hook (e.g. `trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json`) modified staged files. The commit is blocked because the staged version is now stale.
Fix: Re-stage and recommit.
```bash
rtk git add -u
rtk git commit -m "same message"
```
Do NOT reach for `pre-commit install -f` here. That flag overwrites existing hook files in `.git/hooks/`; it has nothing to do with re-staging.
## Secret detected (gitleaks)
> Not sourced from the pre-commit research corpus (`context7-pre-commit-com`/`pre-commit-com` cover pre-commit itself, not gitleaks) — general tool knowledge, verify against gitleaks' own docs if precision matters.
Cause: gitleaks found a high-entropy string or known secret pattern in a staged file.
Suggestions:
- If it's a false positive: add a `# gitleaks:allow` inline comment, or add the path to `.gitleaksignore`.
- If it's a real secret: remove it from the file, rotate the credential, then commit.
## Shellcheck warning
> Not sourced from the pre-commit research corpus — general tool knowledge, verify against shellcheck's own docs if precision matters.
Cause: shellcheck found a shell script issue. The output includes the file path, line number, and SC-code.
Fix: Look up the SC-code on shellcheck.net or pass `--explain SCxxxx` to shellcheck for a detailed explanation.
## `check-hooks-apply` fails
Cause: A hook's `files`/`types` filter matches zero files in the repo — the hook is dead weight.
Fix: Broaden the filter, or remove the hook if it no longer applies to this repo.
## `check-useless-excludes` fails
Cause: An `exclude` pattern matches no files.
Fix: Remove or fix the pattern.
## `rev` is a branch name — `autoupdate` broke it
Cause: Branch refs are mutable and drift over time; pre-commit resolves them once at install time, so pinning to a branch name (instead of a tag or commit SHA) leads to silent version drift.
Fix:
```bash
pre-commit autoupdate # finds the latest tag and rewrites rev in place
```
## pretty-format-json fails but doesn't fix
Cause: `pretty-format-json` requires `args: [--autofix]` to modify files. Without it, the hook only fails.
Fix: The user (or `pc-author`) must add `args: [--autofix]` to the hook override in `.pre-commit-config.yaml`.
## Environment stale or broken
Cause: A hook's cached environment is corrupted or out of date.
Fix: `pre-commit clean` is gated. It wipes the machine-wide cache at `~/.cache/pre-commit`, shared by every repo on the box, so get explicit confirmation before running it — "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
```bash
pre-commit clean # gated — confirm with the user first
pre-commit install-hooks # rebuild everything
```
Or less destructively, needing no confirmation:
```bash
pre-commit gc # remove only unused environments
```
## Hooks don't run on `git commit`
Cause: `pre-commit install` was never run in this clone.
Fix: `pre-commit install`. Git hooks are per-clone — they are not committed to the repo.
## Hook runs but matches wrong files (or no files)
Cause: The `files:` pattern uses `re.search()` not full-string match. A pattern that looks correct may match unexpectedly.
Diagnosis: `identify-cli <filename>` shows the type tags for a file. Verify `types:` filters against these.
## stages mismatch — hook never fires
Cause: Hook is defined for a stage (e.g. `pre-push`) but `pre-commit install` was not run with `-t pre-push`.
Fix:
```bash
pre-commit install -t pre-commit -t pre-push -t commit-msg
```
Or add `default_install_hook_types` to `.pre-commit-config.yaml` and re-run `pre-commit install`.
## `validate-config` schema error
Common causes: missing `id` under a hook block, missing `rev` under a non-local repo block, a `repo: local` hook missing `language` or `entry`, or an indentation error (valid YAML but invalid pre-commit schema).

31
plugins/git/skills/pc-run/references/install.md
View File

@@ -1,31 +0,0 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Installing hooks into `.git/hooks/`
Reached from `SKILL.md`'s Route table when the user asks to install or set up hooks. Self-contained.
Only run this flow when the user explicitly asks for it. Installing rewrites their clone's `.git/hooks/`; it is never a side effect of another request.
## Gate — existing hook files
Check `ls .git/hooks/` first. With hook files already there, `pre-commit install` does not refuse — it silently enters migration mode and runs both. Only `-f` replaces them, and `pre-commit uninstall` cannot restore whatever `-f` overwrote.
So when hook files are present, put the choice to the user in these terms, including the irreversibility, and wait for an answer before passing `-f`:
> "Existing hook files found in `.git/hooks/`. Plain `pre-commit install` runs both; `-f` overwrites them permanently and `pre-commit uninstall` cannot restore them. Plain install, or overwrite?"
## Install
```bash
pre-commit install
```
Re-run with `-t` flags when `default_install_hook_types` changed, or when hooks in a non-default stage never fire — a hook whose stage was never installed cannot run:
```bash
pre-commit install -t pre-commit -t pre-push -t commit-msg
```

33
plugins/git/skills/pc-run/references/sources.md
View File

@@ -1,33 +0,0 @@
# Sources
## context7-pre-commit-com
- **URL:** context7:/pre-commit/pre-commit.com
- **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting
- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
- **Status:** `extracted`
## pre-commit-com
- **URL:** https://pre-commit.com/
- **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration
- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
- **Status:** `extracted`
## context7-pre-commit-hooks
- **URL:** context7:/pre-commit/pre-commit-hooks
- **Description:** Official pre-commit-hooks collection — all available hook IDs with options and examples
- **Contributing files:** (none)
- **Research doc:** plugins/git/docs/research/docs/pre-commit/hooks-reference.md § "pre-commit-hooks (official collection)"
- **Status:** `extracted`
## pre-commit-hooks-github
- **URL:** https://raw.githubusercontent.com/pre-commit/pre-commit-hooks/main/README.md
- **Description:** Official pre-commit-hooks README — complete hook listing with all args, categories, deprecated hooks, and latest version
- **Contributing files:** (none)
- **Research doc:** plugins/git/docs/research/docs/pre-commit/hooks-reference.md § "pre-commit-hooks (official collection)"
- **Status:** `extracted`

21
plugins/gitea/.claude-plugin/plugin.json
View File

@@ -1,21 +0,0 @@
{
"name": "gitea",
"version": "1.3.8",
"description": "Skills and agents for working with a Gitea forge through its HTTP API \u2014 the forge's own objects, as distinct from the local git clone.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"url": "https://git.dev.rkdr.net/Defame1297/"
},
"license": "MIT",
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/gitea",
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/gitea",
"keywords": [
"gitea",
"issues",
"prs",
"milestones",
"releases",
"branches"
]
}

21
plugins/gitea/.github/plugin/plugin.json vendored
View File

@@ -1,21 +0,0 @@
{
"name": "gitea",
"version": "1.3.8",
"description": "Skills and agents for working with a Gitea forge through its HTTP API \u2014 the forge's own objects, as distinct from the local git clone.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"url": "https://git.dev.rkdr.net/Defame1297/"
},
"license": "MIT",
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/gitea",
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/gitea",
"keywords": [
"gitea",
"issues",
"prs",
"milestones",
"releases",
"branches"
]
}

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