fix(kyberforge): bridge apm content to Claude Code's flat plugin discovery

Claude Code's (and Copilot's) native plugin installer has zero awareness of
.apm/ nesting -- it convention-scans only flat skills/, agents/, commands/,
hooks.json at each plugin's root. Confirmed via strings on the installed
claude binary and live installs of git@holocron/gitea@holocron/kyberforge@
holocron, all reporting Skills(0) Agents(0) Hooks(0) post ADR-0015's apm
conversion. Root cause (apm_cli/core/plugin_manifest.py): apm's plugin.json
compiler deliberately strips skills/agents/commands keys, assuming the host
already auto-discovers those convention directories -- it has no model of
.apm/ being host-visible at all. Separately, apm's own bundle exporter
(apm_cli/bundle/plugin_exporter.py, behind `apm pack --format plugin`)
implements the correct .apm/ -> flat mapping, but only ever targeted
build/<name>-<version>/, a path nothing in marketplace.json's source: points
at.

scripts/sync-plugin-content.sh wraps that bundle exporter and copies its
agents/, skills/, commands/, instructions/, extensions/, and merged
hooks.json back into each plugin's own root as a second tracked
compiled-output category -- same governance status as
.claude-plugin/plugin.json: generated from .apm/, never hand-edited. tests/
subdirectories are excluded from the mirror (dev fixtures, not host-visible
runtime content; several hardcode a relative repo-root walk-up sized for the
.apm/-nested depth, which breaks when duplicated one level shallower).
Applied for real across all 6 plugins and verified two ways: `claude plugin
validate --strict` passes on every real plugin directory, and a live
`claude --plugin-dir <path> -p "list skills/agents"` behavioral test
confirms content is now actually discovered.

Also, from the same issue #90 review round:
- scripts/check-manifests.sh pointed at each plugin's root-level plugin.json
  (checking skills/hooks/mcpServers/agents pointer fields) -- that file was a
  stale near-duplicate of .claude-plugin/plugin.json nothing else read or
  wrote, now deleted across all 6 plugins. check-manifests.sh is rewritten to
  validate .claude-plugin/plugin.json instead, and drops the pointer-field
  checks entirely (nothing to check -- those fields are correctly absent by
  design). Content-presence drift is now check-plugin-content-sync's job, a
  new pre-push hook wired in .pre-commit-config.yaml.

docs/adr/0017 records the root cause and decision in full, including two
rejected alternatives (patching plugin.json's path fields directly -- apm's
compiler strips them on every run; pointing marketplace.json at apm pack's
build/ output -- a version-suffixed non-source directory nothing can install
from without an extra build step). ADR-0015 and CONTEXT.md are updated to
point at it.

Refs: #90

plugins/bin/plugin.json

@@ -1,12 +0,0 @@
-{
-  "author": {
-    "email": "defame1297@rkdr.net",
-    "name": "Defame1297",
-    "url": "https://git.dev.rkdr.net/Defame1297/"
-  },
-  "description": "A place for things to be binned",
-  "keywords": [],
-  "license": "MIT",
-  "name": "bin",
-  "version": "1.1.1"
-}

plugins/bin/skills/caveman/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: caveman
+description: >
+  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
+  filler, articles, and pleasantries while keeping full technical accuracy.
+  Use when user says "caveman mode", "talk like caveman", "use caveman",
+  "less tokens", "be brief", or invokes /caveman.
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE once triggered. 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.

plugins/bin/skills/diagnose/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: diagnose
+description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
+---
+
+# Diagnose
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+## 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.**
+
+### 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 `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### 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.
+
+### Non-deterministic bugs
+
+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: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+Do not proceed to Phase 2 until you have a loop you believe in.
+
+## 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 (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] 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 if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) 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.

plugins/bin/skills/diagnose/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/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"

plugins/bin/skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+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.

plugins/bin/skills/grill-with-docs/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# 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.

plugins/bin/skills/grill-with-docs/CONTEXT-FORMAT.md

@@ -0,0 +1,77 @@
+# 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.

plugins/bin/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: grill-with-docs
+description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+---
+
+<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](./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](./ADR-FORMAT.md).
+
+</supporting-info>

plugins/bin/skills/improve-codebase-architecture/DEEPENING.md

@@ -0,0 +1,37 @@
+# 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.

plugins/bin/skills/improve-codebase-architecture/INTERFACE-DESIGN.md

@@ -0,0 +1,44 @@
+# 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.

plugins/bin/skills/improve-codebase-architecture/LANGUAGE.md

@@ -0,0 +1,53 @@
+# 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**.

plugins/bin/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: improve-codebase-architecture
+description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+---
+
+# 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." Full definitions in [LANGUAGE.md](LANGUAGE.md).
+
+- **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 (see [LANGUAGE.md](LANGUAGE.md) for the full list):
+
+- **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.**
+
+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 project's domain glossary and any ADRs in the area you're touching 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 [LANGUAGE.md](LANGUAGE.md) vocabulary 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` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). 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 [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md).
+- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).

plugins/bin/skills/prototype/LOGIC.md

@@ -0,0 +1,79 @@
+# 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. Use [UI.md](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.

plugins/bin/skills/prototype/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: prototype
+description: Build a throwaway prototype to flush out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Pick a branch
+
+Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+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.

plugins/bin/skills/prototype/UI.md

@@ -0,0 +1,112 @@
+# 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. Use [LOGIC.md](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.

plugins/bin/skills/research/META.md

@@ -0,0 +1,15 @@
+```yaml
+version: "1.1"
+updated: 2026-06-21
+
+when: >-
+  Invoked when the user wants to gather structured reference documentation for a
+  tool, library, or API from MCP documentation indexes or web sources. Typically
+  run before writing a new skill that wraps an external tool, or any time
+  reference files are needed for a topic. Triggered explicitly
+  ("/research <topic> <path>") or implicitly when the user asks to look up,
+  gather, or pull docs for a topic before implementing something.
+
+references:
+  - .agents/skills/context7-mcp/SKILL.md  # context7-mcp — MCP source channel integrated at step 2
+```

plugins/bin/skills/research/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: research
+description: >-
+  Use when the user wants to research a topic and generate structured reference
+  markdown files. Handles: finding canonical docs for a tool/library/API via
+  Context7 MCP or web sources, reading and deepening into linked pages,
+  organizing extracted content into topic files (overview, installation,
+  configuration, cli-reference, api-reference, examples, troubleshooting). Do
+  NOT use when the user wants to write documentation from existing code or specs
+  (use write-docs), install or manage the neuledge-context MCP server (use
+  neuledge-context), or research a bug/incident (use diagnose).
+metadata:
+  category: research
+allowed-tools:
+  - WebSearch
+  - WebFetch
+  - Read
+  - Write
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+model: sonnet
+---
+
+<requirements>
+
+## Required inputs
+
+- **Topic** — the subject to research (tool, library, API, concept); inferred from user description if clear, ask if ambiguous
+- **Output path** — directory where reference files will be written; must be provided explicitly — do not infer or default
+- **Starting URLs** — optional; if provided, skip discovery websearch and read these first
+
+## Constraints
+
+- Never write files outside the explicitly provided output path
+- Skip any default topic file if no relevant content is found for it — do not create empty files
+- Create additional topic files beyond the default list when content warrants it (e.g. `webhooks.md`, `rate-limits.md`)
+- Subagents handle parallel source reading and link deepening — the orchestrator writes all files; subagents return summaries only, never write directly
+- Context7 MCP calls (`resolve-library-id`, `query-docs`) are made only by the orchestrator at step 2 — subagents must not call them
+- `sources.md` is always written, even if only one source was read
+- Each topic file must have frontmatter with `topic` and `source_keys`; body is prose only — no inline URLs
+- Source keys in `sources.md` must be kebab-case slugs: derived from the source domain or page title for web sources; for Context7 sources use `context7-<library-slug>` (e.g. `context7-vercel-next-js`)
+- Default topic list and file format spec live in `references/` sub-files — read them at step 1
+
+</requirements>
+
+<steps>
+
+## Process
+
+1. **Scan codebase.** Search the working directory for existing usage of the topic — imports, config files, version pins, existing reference files. Use findings to narrow research scope (e.g. target the version already in use, skip topics already documented). Read `references/topics.md` for the default topic list and `references/file-format.md` for the output file format spec.
+
+2. **Try Context7.** If the topic is a library, framework, or API and no starting URLs were provided, call `resolve-library-id` with the topic name and the user's question. If a match resolves, call `query-docs` once per default topic area (see `references/topics.md`). Treat each response as a source summary with slug `context7-<library-slug>` (e.g. `context7-vercel-next-js`). A topic area has sufficient content when the Context7 response contains at least one substantive paragraph — not a "no results" message, redirect notice, or header-only boilerplate. Mark covered topic areas — skip their subagent web reads in step 4. If the library does not resolve, or starting URLs were provided (explicit source choice by the user), skip this step entirely.
+
+3. **Discover sources.** For topics not covered by Context7 (or when no starting URLs were provided and Context7 did not resolve), websearch for canonical documentation (prefer `llms.txt`, developer docs, official API references over tutorials or blog posts). Collect 3–5 candidate URLs before reading any.
+
+4. **Read sources in parallel.** Spawn one subagent per source URL. Each subagent fetches the page, extracts relevant content, identifies links worth deepening, and returns a structured summary (content by topic area + links to follow). Subagents do not write files.
+
+5. **Deepen.** For each subagent that returned links worth following, spawn child subagents per branch. Continue until content becomes repetitive or out of scope. Cap at ~10 additional pages total across all branches.
+
+6. **Consolidate.** Merge all subagent summaries (Context7 and web) by topic area. Identify which default topics have sufficient content and which custom topics emerged.
+
+7. **Write topic files.** For each topic with content, write `<output-path>/<topic>.md` using the format in `references/file-format.md`. Orchestrator writes all files — never delegate file writing to a subagent.
+
+8. **Write `sources.md`.** Write `<output-path>/sources.md` mapping each source slug to its URL (use `context7:<library-id>` as the URL for Context7 sources), description, and list of topic files it contributed to. Include sources that yielded no content, marked `no content extracted`.
+
+## Output format
+
+- `<output-path>/<topic>.md` per topic with content — formatted per `references/file-format.md`
+- `<output-path>/sources.md` — always produced; maps slug → URL, description, contributing files
+
+</steps>
+
+<checks>
+
+## Failure handling
+
+- Output path not provided — stop and ask; do not infer or default
+- No sources found after websearch — report what was searched, ask user to provide starting URLs
+- Subagent returns no usable content — skip that source, log in `sources.md` as `no content extracted`
+- All topic files would be empty — stop, report what was searched, do not write any files
+
+## Self-check
+
+- [ ] Codebase scanned before any websearch was performed
+- [ ] Output path was explicitly provided — not inferred
+- [ ] `references/topics.md` and `references/file-format.md` read at step 1
+- [ ] Context7 resolution attempted before websearch when topic is a library/framework/API
+- [ ] Context7 calls made only at orchestrator step 2 — no subagent called `resolve-library-id` or `query-docs`
+- [ ] Context7 sources recorded in `sources.md` with `context7:<library-id>` as URL
+- [ ] No topic file written without content
+- [ ] `sources.md` written with all sources read (including those with no content extracted)
+- [ ] All file writes performed by the orchestrator, not subagents
+- [ ] Each topic file has `topic` and `source_keys` frontmatter fields
+- [ ] All source keys in topic files have a matching entry in `sources.md`
+- [ ] No files written outside the provided output path
+
+</checks>

plugins/bin/skills/research/references/file-format.md

@@ -0,0 +1,39 @@
+# 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`).

plugins/bin/skills/research/references/topics.md

@@ -0,0 +1,17 @@
+# 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.

plugins/bin/skills/tdd/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# 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.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## 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 project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
+
+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](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](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](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
+```

plugins/bin/skills/tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# 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?

plugins/bin/skills/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# 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

plugins/bin/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# 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

plugins/bin/skills/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# 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

plugins/bin/skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# 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");
+});
+```

plugins/bin/skills/triage/AGENT-BRIEF.md

@@ -0,0 +1,168 @@
+# Writing Agent Briefs
+
+An agent brief is a structured comment posted on a GitHub issue 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:** "Running `gh issue list --label needs-triage` 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

plugins/bin/skills/triage/OUT-OF-SCOPE.md

@@ -0,0 +1,101 @@
+# 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

plugins/bin/skills/triage/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: triage
+description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
+---
+
+# 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](AGENT-BRIEF.md) — how to write durable agent briefs
+- [OUT-OF-SCOPE.md](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. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
+
+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 project's 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](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](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.

plugins/bin/skills/write-docs/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: write-docs
+description: Write documentation for X, document this module, create docs for this feature. Use when the user wants to produce or update technical documentation derived from code, spec, or existing artifacts. Do NOT use when the user wants a PRD, ADR, decision doc, or skill file — those have dedicated skills.
+version: "1.0"
+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:
+  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 a PRD, decision doc, or architecture proposal → `to-prd` or `grill-me`
+- 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 a PRD, decision doc, or architecture proposal → redirect to `to-prd`, `grill-me`, or `grill-with-docs`
+
+## 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

plugins/bin/skills/zoom-out/SKILL.md

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

plugins/core/plugin.json

@@ -1,18 +0,0 @@
-{
-  "author": {
-    "email": "defame1297@rkdr.net",
-    "name": "Defame1297",
-    "url": "https://git.dev.rkdr.net/Defame1297/"
-  },
-  "description": "Cross-cutting utility skills for everyday AI-assisted coding \u2014 triage, diagnosis, architecture review, and session navigation.",
-  "keywords": [
-    "cross-cutting",
-    "triage",
-    "diagnose",
-    "architecture",
-    "debug"
-  ],
-  "license": "MIT",
-  "name": "core",
-  "version": "1.1.0"
-}

plugins/core/skills/agentsmd-audit/README.md

@@ -0,0 +1,30 @@
+# agentsmd-audit
+
+Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift.
+
+## What it does
+
+Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything.
+
+## Usage
+
+```
+/agentsmd-audit
+```
+
+Provide the path to the repo root to audit when invoking.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings |
+| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication |
+| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo |
+| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
+| `scripts/README.md` | Directory documentation for `scripts/` |
+| `tests/README.md` | Bats test dependency and run instructions |
+| `tests/validate-secrets.bats` | Bats test suite for `scripts/validate-secrets.sh` |
+| `tests/validate-structure.bats` | Bats test suite for `scripts/validate-structure.sh` |
+| `tests/validate-drift.bats` | Bats test suite for `scripts/validate-drift.sh` |

plugins/core/skills/agentsmd-audit/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: agentsmd-audit
+description: >
+  Use when the user wants to review a repo's AGENTS.md file, says "audit this
+  AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to
+  know if AGENTS.md is safe to commit — even if they don't use the word
+  "audit". Also invoke proactively after agentsmd-author creates or updates
+  AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a
+  target repo's AGENTS.md file(s) — root and any nested monorepo files — for
+  embedded secrets/credentials, structural completeness against the
+  agents.md common-sections checklist, and drift (referenced commands or
+  paths that no longer resolve against the repo). Produces a compact
+  findings report (findings only, no PASS noise) with Why and Fix per
+  finding. Do not use to audit CLAUDE.md, .cursor/rules, or other
+  provider-specific adapter files — that's provider-adapter-author's
+  self-contained concern. Do not use to fix or write AGENTS.md content — use
+  agentsmd-author instead.
+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.1"
+---
+
+## 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. If one exists and duplicates AGENTS.md content, that's `provider-adapter-author`'s concern, not this skill's.
+- 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.
+- 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`/`INFO`/`SUGGESTION` lines 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.
+
+## 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:
+
+```text
+## Result
+
+PASS
+PASS · P info
+PASS (N suggestions) · P info
+FAIL (N fails)
+FAIL (N fails) · P info
+```
+
+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.

plugins/core/skills/agentsmd-audit/references/sources.md

@@ -0,0 +1,33 @@
+# 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`

plugins/core/skills/agentsmd-audit/scripts/README.md

@@ -0,0 +1,11 @@
+# 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.

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

@@ -0,0 +1,137 @@
+#!/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

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

@@ -0,0 +1,120 @@
+#!/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):
+        if PLACEHOLDER_RE.search(line):
+            continue
+        for label, pattern in PATTERNS:
+            m = pattern.search(line)
+            if not m:
+                continue
+            # Re-check placeholder allowlist against just the matched value, in case
+            # the placeholder marker sits outside the regex's own match span.
+            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

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

@@ -0,0 +1,118 @@
+#!/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

plugins/core/skills/agentsmd-author/README.md

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

plugins/core/skills/agentsmd-author/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: agentsmd-author
+description: >
+  Use when the user wants to create or update a repo's AGENTS.md file
+  ("write an AGENTS.md for this repo", "add setup/test instructions for
+  agents", "update AGENTS.md", "give this package its own AGENTS.md") — even
+  if they don't name the file explicitly, e.g. "document this for AI coding
+  tools" or "make sure agents know how to run tests here". Writes/updates
+  AGENTS.md by exploring the target repo for real build, test, lint, and
+  style conventions — never invents commands. Supports nested monorepo
+  placement (a subdirectory can get its own AGENTS.md following
+  nearest-file-wins precedence). Closes every run by invoking agentsmd-audit
+  inline, and calls provider-adapter-author when an existing provider file
+  (CLAUDE.md, etc.) now duplicates what AGENTS.md owns. Do not use to review
+  an existing AGENTS.md without changing it — use agentsmd-audit instead. Do
+  not use to convert CLAUDE.md/.cursor/rules into a thin adapter — use
+  provider-adapter-author instead.
+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.1"
+---
+
+## 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.
+- AGENTS.md has no required schema — don't force every common-sections-checklist heading into every repo. Include only sections that reflect something real about this repo; a thin, accurate file beats a padded, generic one.
+- Nested placement is for genuinely different conventions, not convenience. Only create a subdirectory AGENTS.md when that subtree has its own build tool, stack, or conventions distinct from the root — otherwise you're duplicating content the root already covers, which the nearest-file-wins rule doesn't merge back together.
+- This skill never touches CLAUDE.md, `.cursor/rules/*.mdc`, `copilot-instructions.md`, or similar provider files directly — that's `provider-adapter-author`'s job. Detect and hand off; don't reconcile it yourself.
+- This skill never audits on its own judgment — the closing `agentsmd-audit` invocation is mandatory, not optional, even when the change looks trivial.
+
+## 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. Don't repeat root-level content — the nearest-file-wins rule means the nested file is read alone, not merged with the root.
+- Otherwise → update the existing file(s) in place.
+
+## Step 3 — Write or update
+
+Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists. 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 and now duplicates content the AGENTS.md you just wrote/updated already owns, invoke the `provider-adapter-author` skill on it to reconcile — don't rewrite it yourself.
+
+## Step 5 — Audit and report
+
+Invoke the `agentsmd-audit` skill directly on the AGENTS.md file(s) you just wrote or updated. 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.

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

@@ -0,0 +1,118 @@
+---
+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).

plugins/core/skills/agentsmd-author/references/sources.md

@@ -0,0 +1,25 @@
+# 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`

plugins/core/skills/provider-adapter-author/README.md

@@ -0,0 +1,30 @@
+# provider-adapter-author
+
+Convert a target repo's provider-specific instruction file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) into a thin adapter over AGENTS.md.
+
+## What it does
+
+Detects a provider-specific AI instruction file in a target repo, diffs it against the repo's `AGENTS.md`, and rewrites it down to a minimal reference — an `@AGENTS.md`-style import for providers that support one, or a text pointer for those that don't — plus only genuinely provider-specific additions. Self-validates its own output with a bundled deterministic script (no LLM judgment, no separate audit skill) before finishing.
+
+## Before you start
+
+The target repo must already have an `AGENTS.md`. If it doesn't, run `agentsmd-author` first — this skill never creates or edits `AGENTS.md` itself.
+
+## Usage
+
+```
+/provider-adapter-author
+```
+
+Provide the path to the provider-specific file to convert (and the target repo root, if not inferable). Can be invoked directly, or composed into by `agentsmd-author` when it detects an existing provider file with content overlapping AGENTS.md.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on |
+| `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin |
+| `scripts/README.md` | Directory documentation for `scripts/` |
+| `tests/README.md` | Bats test dependency and run instructions |
+| `tests/validate-adapter.bats` | Bats test suite for `scripts/validate-adapter.sh` |

plugins/core/skills/provider-adapter-author/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: provider-adapter-author
+description: >
+  Use when the user wants to convert a provider-specific AI instruction file
+  (CLAUDE.md, .cursor/rules/*.mdc, copilot-instructions.md, etc.) into a
+  thin adapter that defers to a repo's AGENTS.md — e.g. "reduce duplication
+  between CLAUDE.md and AGENTS.md", "make CLAUDE.md just import AGENTS.md"
+  — even if the pattern isn't named explicitly. Also invoke when
+  agentsmd-author detects an existing provider file overlapping with
+  AGENTS.md it just wrote. Detects redundant content in a provider file
+  relative to AGENTS.md and rewrites it down to a minimal reference (an
+  `@AGENTS.md`-style import where supported, or a text pointer otherwise)
+  plus genuinely provider-specific additions. Self-validates via a bundled
+  deterministic script before finishing. Do not use to write or audit
+  AGENTS.md itself — use agentsmd-author or agentsmd-audit.
+allowed-tools: Bash Read Edit Write
+metadata:
+  category: docs
+  source_keys:
+    - adr-0002-0003-two-tier-claude-md
+  version: "0.1.0"
+---
+
+## Gotchas
+
+- Not every provider supports cross-file imports. Claude Code does — a `CLAUDE.md` can consist of nothing but one or more `@path` lines (e.g. `@AGENTS.md`), with no other content required. Cursor's `.cursor/rules/*.mdc` and GitHub Copilot's `copilot-instructions.md` have no native import mechanism as of current tooling — for those, "thin" means a short text pointer to AGENTS.md plus only what that tool actually needs, not a literal import line. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for these providers.
+- This skill never creates or edits `AGENTS.md` itself. If the target repo has no `AGENTS.md` yet, stop and point the user to `agentsmd-author` first — there's nothing to adapt to.
+- Only strip content from the provider file that's genuinely redundant with AGENTS.md. Provider-specific material (IDE settings, tool-only syntax, model-specific instructions) stays — the goal is thin, not empty.
+- Works standalone or composed-into by `agentsmd-author` — behave identically either way; don't assume a caller skill exists.
+
+## Step 1 — Detect
+
+Look for known provider instruction files in the target repo: `CLAUDE.md` (repo root, and any deployed copies), `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and similar tool-specific files. Confirm `AGENTS.md` exists at the repo root — if not, stop and tell the user to run `agentsmd-author` first.
+
+## 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 line, keep the provider-specific bucket below it.
+- **Providers without import syntax** (Cursor, Copilot, etc.): replace the redundant bucket with a short pointer sentence mentioning `AGENTS.md`, keep the provider-specific bucket.
+
+## 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` and re-run until it exits `0`.
+
+## Step 4 — Report
+
+State which file was converted, what was removed versus kept, and the validator's final result.

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

@@ -0,0 +1,9 @@
+# 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
+- **Status:** `extracted`

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

@@ -0,0 +1,9 @@
+# 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 reference to AGENTS.md, doesn't duplicate its content, and stays under a thin-file line threshold |
+
+Takes `<adapter-file> <agents-md-file>`, with optional `--no-import-syntax` and `--max-lines N` flags. Prints `FAIL` findings to stdout and exits non-zero on any failure.

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

@@ -0,0 +1,141 @@
+#!/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.
+
+Options:
+  --no-import-syntax  The target provider has no native cross-file import
+                       mechanism. Accept a plain-text pointer mention of
+                       "AGENTS.md" instead of requiring an @import-style line.
+  --max-lines N        Max non-blank lines allowed in the adapter file before
+                       it's considered no longer "thin". Default: 60.
+  --help, -h           Show this help and exit 0.
+
+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)
+EOF
+}
+
+NO_IMPORT_SYNTAX=0
+MAX_LINES=60
+ARGS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    --no-import-syntax)
+      NO_IMPORT_SYNTAX=1
+      shift
+      ;;
+    --max-lines)
+      MAX_LINES="${2:-}"
+      shift 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 1
+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)
+
+if not os.path.isfile(adapter_path):
+    print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr)
+    sys.exit(1)
+if not os.path.isfile(agents_md_path):
+    print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr)
+    sys.exit(1)
+
+with open(adapter_path, encoding="utf-8", errors="replace") as f:
+    adapter_content = f.read()
+with open(agents_md_path, encoding="utf-8", errors="replace") as f:
+    agents_md_content = f.read()
+
+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(1)
+
+IMPORT_RE = re.compile(r'(?m)^\s*@\S*AGENTS\.md\s*$')
+lines = adapter_content.splitlines()
+import_lines = [ln for ln in lines if IMPORT_RE.match(ln)]
+
+if no_import_syntax:
+    has_reference = "AGENTS.md" in adapter_content
+else:
+    has_reference = bool(import_lines) or "AGENTS.md" in adapter_content
+
+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 has no import syntax, so the adapter must at least mention AGENTS.md as a text pointer.")
+        print("      Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\"")
+    else:
+        print("      Why: A thin adapter must import AGENTS.md (e.g. `@AGENTS.md`) rather than silently omitting it.")
+        print("      Fix: Add an `@AGENTS.md` (or equivalent relative path) import line.")
+    print()
+
+# --- Duplication check ---
+non_import_lines = [ln for ln in lines if not IMPORT_RE.match(ln)]
+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: Move provider-agnostic content into AGENTS.md; keep only genuinely provider-specific additions here.")
+    print()
+
+if has_fail:
+    sys.exit(1)
+sys.exit(0)
+PYTHON

plugins/git/agents/git-orchestrate.agent.md

@@ -0,0 +1,90 @@
+---
+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 it explicitly refuses agent callers ("Do not use when the caller is an agent"). 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: if the operation is destructive (force-push, branch deletion, rebase with history loss, force-checkout) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm`
+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. Read plugin config from `.claude/plugins/git/config.json` if present — see `config.example.json` in the plugin root for the expected shape (`branching_pattern`, `commit_style`, `rebase_strategy`) — or fall back to sensible defaults
+5. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, context, and config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above).
+6. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections)
+7. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions
+8. 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": "..." },
+    "applied_config": { "commit_style": "...", "rebase_strategy": "..." }
+  },
+  "error": {
+    "message": "<human-readable error>",
+    "code": "<error type: conflict | auth_failure | push_rejection | invalid_state>",
+    "recovery_attempted": true | false,
+    "suggestions": ["<suggestion1>", "<suggestion2>"]
+  }
+}
+```

plugins/git/plugin.json

@@ -1,17 +0,0 @@
-{
-  "author": {
-    "email": "defame1297@rkdr.net",
-    "name": "Defame1297",
-    "url": "https://git.dev.rkdr.net/Defame1297/"
-  },
-  "description": "Skills for working with Git \u2014 conventional commits, branch management, pull requests, and feature flow.",
-  "keywords": [
-    "git",
-    "vcs",
-    "commit",
-    "branch"
-  ],
-  "license": "MIT",
-  "name": "git",
-  "version": "1.3.2"
-}

plugins/git/skills/git-branches/README.md

@@ -0,0 +1,22 @@
+# git-branches
+
+Manage the full lifecycle of git branches — create, switch, delete, rename, and track feature/hotfix/release branches under GitHub Flow or Gitflow.
+
+## What it does
+
+This skill handles branch operations within the git workflow suite. It creates branches following GitHub Flow or Gitflow conventions (configurable), switches and tracks branches, handles safe deletion with unmerged-work checks, and retrieves branch intent metadata for use by other skills (e.g., commit message context). It returns structured results suitable for agent composition.
+
+## Usage
+
+```
+/git-branches
+```
+
+Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, or track. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/sources.md` | Research sources backing the branching/gitflow guidance |

plugins/git/skills/git-branches/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: git-branches
+
+description: >
+  Use when managing the full lifecycle of git branches: create feature/hotfix/release branches
+  (gitflow, GitHub Flow, or custom patterns from config), switch, delete, rename, and track branches,
+  or retrieve branch intent metadata. Handles branch protection safety checks and returns structured
+  results for agent composition. Use even if the user doesn't explicitly mention branch names — they
+  may be asking about "fixing something" or "shipping a feature", which implicitly requires branch
+  management. Do not use when the user needs only commit operations (use git-commits) or history
+  inspection (use git-history).
+
+metadata:
+  category: git
+  source_keys:
+    - context7-git-htmldocs
+    - nvie-gitflow-post
+    - atlassian-gitflow-tutorial
+    - gitflow-cheatsheet
+---
+
+## Gotchas
+
+- **Branches are cheap; deletion is cheap but risky.** Deleting one requires checking if commits on it are reachable elsewhere; always confirm before deleting, as it may lose unmerged work.
+- **Uncommitted changes can block branch switches.** `git switch` aborts if local modifications conflict with the target branch. Offer to stash changes before switching when this happens, don't force a checkout.
+- **Tracking relationships matter for coordination.** Agents pushing on behalf of users should always set tracking (`-u origin <branch>`) so later pushes/pulls know the target. Without it, commands fail or target the wrong remote branch.
+- **Gitflow vs. GitHub Flow are not compatible.** Gitflow requires `develop` and `release/*` branches with `--no-ff` merges; GitHub Flow uses only `main` and feature branches with fast-forward. Read the repo's config or ask the orchestrator which pattern to use — don't guess.
+- **Naming collisions with tags.** A branch and tag can have the same name. Prefer `git switch` over `git checkout` for branch operations — verify which ref you're targeting with `git branch --list <name>` / `git tag --list <name>` if the name could be ambiguous, and disambiguate explicitly with `refs/heads/<name>` (branch) or `refs/tags/<name>` (tag) where a command accepts either.
+- **Never force-push `main` or `master`.** This is a hard refusal, not a confirmation gate — it applies even if the caller passes `confirm: true`. Deleting or renaming `main`/`master` in a way that would require a force-push to reconcile the remote (e.g. force-deleting and recreating it, or renaming it out from under in-flight work) must be rejected outright; explain why and suggest a non-destructive alternative (e.g. a new branch) instead of proceeding.
+
+## Branch Patterns
+
+Default to **GitHub Flow** (simpler, modern, CI/CD-friendly). Fall back to **Gitflow** only if the repo's config specifies it or the branch structure shows it in use (presence of `develop` or release branches).
+
+**GitHub Flow:**
+- Base: `main`
+- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
+- Merge: fast-forward when possible (preserves linear history)
+- Delete after merge
+
+**Gitflow:**
+- Base: `main` (production) + `develop` (integration)
+- Feature branches: `feature/<feature-name>` (from `develop`)
+- Release branches: `release/X.Y.Z` (from `develop`, merged to `main` + `develop`)
+- Hotfix branches: `hotfix/X.Y.Z` (from `main`, merged to `main` + `develop`)
+- Merge: always use `--no-ff` to preserve branch structure
+
+## Workflow
+
+- [ ] **Determine pattern:** Check git plugin config (`.claude/plugins/git/config.json`, if present — see `config.example.json` in the plugin root for the expected shape) for `branching_pattern` (default: `github-flow`). If not set, inspect repo for `develop` branch or `release/*` branches; if present, assume Gitflow.
+- [ ] **Create branch:** Use `git switch -c <branch> <base>`. Base defaults to config's `base_branch` (usually `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`).
+- [ ] **Track remote:** If pushing, always use `git push -u origin <branch>` to establish tracking.
+- [ ] **Safety checks before destructive ops:** Before delete/force-push/rebase with history loss, check: (1) Is this branch tracking a remote? Warn if yes. (2) Are there unpushed commits? Warn if yes. (3) Does the orchestrator call include `confirm: true`? Fail if not. For humans, prompt interactively.
+- [ ] **Return structured results:** Always return branch operations as JSON or structured text: `{ "action": "create", "branch": "feature/x", "base": "main", "tracking": "origin/feature/x", "intent": "implement feature X" }`. Agents need to parse this for subsequent operations.
+- [ ] **Retrieve intent (`get-intent`):** Git has no native field for free-text branch metadata — this skill doesn't persist it. On `create`, the `intent` value is only ever returned in the structured result; the caller (orchestrator or agent) is responsible for storing it if it needs to be looked up later. On `get-intent`, either parse it back out of the branch name convention (`feature/<intent-slug>`) or return `{ "intent": null }` if the caller never persisted the original create-time value — don't fabricate an intent.
+
+### Command mapping for each action
+
+- **delete:** `git branch -d <branch>` refuses if the branch has unmerged commits — prefer this by default. `git branch -D <branch>` forces deletion and discards unmerged work; only use it after the safety checks above pass and `confirm: true` is set. For a remote branch: `git push origin --delete <branch>`.
+- **rename:** `git branch -m <old> <new>`.
+- **list:** `git branch` (local only), `git branch -a` (all local + remote-tracking), `git branch -r` (remote-tracking only), `git branch --merged`/`--no-merged` (filter by merge status into current branch).
+- **get-intent:** No git command — see Workflow step "Retrieve intent" for how this is resolved.
+- **track (existing branch):** `git branch --set-upstream-to=origin/<branch>` sets tracking without a push; `git branch -vv` shows tracking state for all local branches.
+- **switch (existing branch):** `git switch <branch>` — switches to an existing local branch (aborts on conflicting local changes, see Gotchas). `git switch -` switches back to the previously checked-out branch.
+
+## Merging
+
+Scope: fast-forward/merge-commit mechanics and conflict resolution only. Rebase, cherry-pick, and revert belong to `git-history`.
+
+- **Fast-forward:** `git merge <branch>` — advances the pointer with no merge commit if the target hasn't diverged.
+- **True merge:** `git merge --no-ff <branch>` — forces a merge commit even when fast-forward is possible; required by Gitflow on all supporting-branch merges.
+- **Squash merge:** `git merge --squash <branch>` stages the combined diff without committing; follow with a manual `git commit`.
+- **Octopus merge:** `git merge branch-a branch-b branch-c` merges more than two branches at once; fails outright on any conflict, so use sequential two-way merges if conflicts are expected.
+
+**Conflict resolution:** when Git can't auto-merge, it inserts conflict markers and stops. Run `git status` to find conflicted files, edit them to resolve the markers, then `git add <file>` and `git merge --continue`. `git merge --abort` reverts to the pre-merge state. `git mergetool` opens the configured merge tool; `git diff --diff-filter=U` shows only conflicted files.
+
+## Comparing Branches
+
+- `git log main..feature` — commits in `feature` not in `main`.
+- `git log feature..main` — commits in `main` not in `feature` (reverse direction).
+- `git log --left-right main...feature` — both diverging sets (symmetric diff).
+- `git diff main...feature` — diff from the common ancestor to `feature`'s tip.
+- `git merge-base main feature` — print the common ancestor commit.
+
+## Integration with Orchestrator
+
+When invoked by `git-orchestrate`, accept requests in the form:
+```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>"
+}
+```
+
+Return results as:
+```json
+{
+  "success": true,
+  "action": "create|switch|...",
+  "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>"
+}
+```
+
+If error is due to uncommitted changes, include `{ "suggestion": "stash changes and retry" }` so the orchestrator can offer automatic recovery.

plugins/git/skills/git-branches/references/sources.md

@@ -0,0 +1,48 @@
+---
+# 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 (Branch Patterns — Gitflow vs. GitHub Flow structure and defaults)
+
+## 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 (Branch Patterns — Gitflow branch types, base/merge targets, `--no-ff` requirement)
+
+## 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 (Branch Patterns — 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 (Command mapping, Merging, Comparing Branches — `git switch`/`git branch`/`git merge`/`git log`/`git diff`/`git merge-base` command vocabulary and flags)

plugins/git/skills/git-commits/README.md

@@ -0,0 +1,24 @@
+# git-commits
+
+Create, amend, squash, and cherry-pick commits with Conventional Commits formatting and validation.
+
+## What it does
+
+This skill handles commit operations within the git workflow suite. It generates well-formatted commit messages following the Conventional Commits spec, validates against commitlint config-conventional constraints, and communicates SemVer impact. It enforces confirmation gates for history-altering operations (amend, rebase, squash) and returns structured JSON output for agent consumption.
+
+## Usage
+
+```
+/git-commits
+```
+
+Describe your commit task: create a new commit, amend, squash, or cherry-pick. The skill will guide message formatting and handle confirmation for destructive operations.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/conventional-commits-spec.md` | Full Conventional Commits specification |
+| `references/commit-template.md` | Why / Implementation Notes / Impact body structure and full trailer list |
+| `references/sources.md` | Research sources and provenance |

plugins/git/skills/git-commits/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: git-commits
+
+description: >
+  Use when creating, amending, squashing, or cherry-picking commits.
+  Generates well-formatted commit messages following Conventional Commits spec (type, scope, description, body, footers).
+  Validates against commitlint config-conventional constraints (header max 100 chars, lowercase subject, no trailing periods, type must be one of 11 standard types).
+  Communicates SemVer impact (MAJOR for breaking changes, MINOR for features, PATCH for fixes).
+  Handles confirmation gates for history-altering operations (amend, rebase, squash).
+  Provides interactive guidance for humans, structured JSON output for agents.
+  Do not use for: inspecting git history, branch management, or repository state inspection — those are separate skills.
+
+metadata:
+  version: "0.1.2"
+  category: git
+  source_keys:
+    - conventional-commits-spec
+    - commitlint-config-conventional
+    - org-commit-conventions
+    - context7-git-htmldocs
+
+allowed-tools: Bash
+---
+
+## Gotchas
+
+- **Type must be one of 11 standard types** — `feat`, `fix`, `perf`, `revert`, `docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore`. Non-standard types will fail commitlint validation. Note: the Conventional Commits spec itself only mandates `feat`/`fix` — the 11-type set is a commitlint/Angular convention this skill validates against, not a spec requirement.
+- **Scope is optional but should be used** — helps identify which part of the system changed. Examples: `api`, `db`, `cli`, `config`.
+- **Header max 100 characters** — type + scope + colon + description must fit. If longer, move detail to body.
+- **BREAKING CHANGE notation** — use `!` before the colon (`feat!: drop Node 6`) for visibility in `git log --oneline`. Footer notation (`BREAKING CHANGE: ...`) is machine-readable but hidden in log.
+- **SemVer mapping is not optional** — agents must communicate: `feat` → MINOR bump, `fix`/`perf`/`revert` → PATCH, any with breaking change → MAJOR.
+- **Confirmation gates are mandatory for destructive operations** — amend, rebase, squash require explicit user/agent approval before execution.
+- **Never skip hooks with `--no-verify`** — hooks are the automated QA gate; bypassing them breaks the pipeline. Do not add this flag to any commit command unless the user explicitly demands it, and warn them if they do.
+- **Never force-push `main`/`master`** — even after an amend or interactive rebase, refuse to force-push a protected branch (`main`, `master`) and explain why; force-push is only safe on branches no one else has based work on.
+- **Command examples use the `rtk git` wrapper** — this org's convention routes all git invocations through `rtk git <subcommand>` instead of bare `git <subcommand>`. Follow this prefix in any command you actually run.
+- **Never commit secrets, credentials, or environment-specific config** — if staged changes contain what looks like an API key, token, password, or connection string, stop and flag it before committing rather than committing it.
+- **Commits must be atomic and leave the repo working** — each commit should be one logical, independently reviewable and reversible change, and should leave the repository in a buildable/testable state. If staged changes bundle unrelated work, suggest splitting before committing.
+- **Commit messages explain why, not what** — the diff already shows what changed; the message's job is to capture context the diff can't (motivation, root cause, tradeoffs). See `references/commit-template.md` for the structure this maps to.
+
+## Workflow
+
+### For creating a new commit:
+
+1. **Gather context** — what changed and why? (from staged changes, PR description, issue context). Verify the staged diff is one logical, atomic change and that the repo would still build/test at this commit — if not, suggest splitting before proceeding.
+2. **Check for secrets** — scan the staged diff for anything that looks like a credential, API key, token, or environment-specific config. Stop and flag it rather than committing.
+3. **Determine type** — is this a feature (`feat`), bug fix (`fix`), or other? Default: check the change itself.
+4. **Determine scope** — which system/module? Use scope from plugin config if set, otherwise infer from files changed.
+5. **Write description** — imperative mood, no period. Neither source spec sets a length target below the 100-char header max, but convention favors keeping it to ~50 characters where possible for `git log --oneline` readability. Examples: "add user authentication", "fix race condition in cache".
+6. **Add body if needed** — explain why (not what). Blank line before body, wrap at 100 chars. For non-trivial changes, follow the Why / Implementation Notes / Impact structure in `references/commit-template.md`.
+7. **Add footers if needed** — `Fixes: #123`, `Refs: #123`, `ADR: 0012`, `RFC: 0003`, `Design: <link>`, `Reviewed-by: Name`, `Co-authored-by: Name <email>`, `Signed-off-by: Name <email>`, `BREAKING CHANGE: description`. See `references/commit-template.md` for the full trailer list.
+8. **Validate** — check header length, type correctness, no trailing periods, lowercase.
+9. **Confirm and execute** — for agents, require explicit approval; for humans, show preview and ask. Never add `--no-verify` to skip hooks.
+
+### For amending a commit:
+
+1. **Stage new changes** (or changes to undo)
+2. **Run amend operation** — executes `rtk git commit --amend [--no-edit]` based on user intent
+3. **Offer message edit** — if user wants to change commit message, show current message and prompt for new one
+4. **Confirm before force-push** — amending is only safe on non-shared branches; if the current branch is `main`/`master`, refuse to force-push and explain why rather than warning and proceeding
+
+### For squashing commits (interactive rebase):
+
+1. **Identify commits to squash** — typically the last N commits on current branch
+2. **Confirm operation** — squashing rewrites history; get explicit approval
+3. **Execute rebase** — `rtk git rebase -i HEAD~N`, mark older commits as `squash` or `fixup`
+4. **Handle merge conflicts** — if rebase halts, offer conflict resolution options or abort; do not resolve automatically without confirmation
+5. **Offer message composition** — if squashing interactive, allow message editing
+
+### For squashing commits (autosquash — preferred when tagging at commit time):
+
+Prefer this over manual interactive rebase when a commit is written to be folded into an earlier one, since it removes the manual "mark as squash/fixup" step and the risk of reordering the wrong line:
+
+1. **Create the fixup/squash commit** — `rtk git commit --fixup=<commit>` (keeps target's message) or `rtk git commit --squash=<commit>` (lets you edit the combined message later). Both prefix the message with `fixup!`/`squash!` and target `<commit>`.
+2. **Confirm operation** — rewriting history still requires explicit approval before the rebase runs.
+3. **Execute** — `rtk git rebase --autosquash HEAD~N` (or `-i --autosquash` to review the plan first); git reorders and marks the `fixup!`/`squash!` commits against their targets automatically.
+4. **Handle merge conflicts** — same as manual rebase: offer resolution or abort, never resolve automatically without confirmation.
+
+### For cherry-picking:
+
+1. **Identify source commit(s)** — hash or branch reference
+2. **Confirm destination branch** — cherry-pick will replay commits on current branch
+3. **Execute cherry-pick** — `rtk git cherry-pick <commit-hash>`
+4. **Handle conflicts** — offer conflict resolution or abort
+5. **Report outcome** — successful replays, conflicts, or rejected commits
+
+## Output format (for agent consumption)
+
+Return structured JSON:
+
+```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": true|false,
+  "confirmation_required": true|false,
+  "details": {
+    "type": "feat",
+    "scope": "api",
+    "description": "add user authentication",
+    "body": "optional body text",
+    "footers": ["Fixes: #123", "Refs: #456", "ADR: 0012", "Reviewed-by: Alice", "Co-authored-by: Bob <bob@example.com>", "Signed-off-by: Alice <alice@example.com>"]
+  }
+}
+```
+
+For interactive human use, format as readable prose with clear prompts and previews.
+
+## Reference
+
+If a footer or type/scope edge case isn't covered above, read `references/conventional-commits-spec.md` for the full specification.
+
+For the Why / Implementation Notes / Impact body structure and the full trailer list, read `references/commit-template.md`.

plugins/git/skills/git-commits/references/commit-template.md

@@ -0,0 +1,66 @@
+---
+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).
+
+```
+<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:
+
+```
+Fixes:
+Refs:
+ADR:
+RFC:
+Design:
+Co-authored-by:
+Reviewed-by:
+Signed-off-by:
+BREAKING CHANGE:
+```

plugins/git/skills/git-commits/references/conventional-commits-spec.md

@@ -0,0 +1,170 @@
+---
+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
+
+```
+<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`):
+```
+feat!: drop support for Node 6
+feat(api)!: remove deprecated endpoint
+```
+
+**`BREAKING CHANGE` footer** (machine-readable body):
+```
+feat: allow config to extend other configs
+
+BREAKING CHANGE: `extends` key now used for extending config files
+```
+
+**Both together** (most explicit):
+```
+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
+
+```
+<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:
+```
+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:
+```
+docs: correct spelling of CHANGELOG
+```
+
+With scope:
+```
+feat(lang): add Polish language
+```
+
+Breaking change via `!`:
+```
+feat!: send an email to the customer when a product is shipped
+```
+
+Breaking change via footer:
+```
+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:
+```
+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:
+```
+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 |

plugins/git/skills/git-commits/references/sources.md

@@ -0,0 +1,40 @@
+---
+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
+- **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
+- **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
+- **Status:** extracted
+
+## context7-git-htmldocs
+
+- **Description:** Official Git HTML documentation — `git commit --squash`/`--fixup` and `git rebase --autosquash` flag semantics
+- **Research doc:** plugins/git/docs/research/docs/git/cli-reference.md
+- **Contributing files:** SKILL.md
+- **Status:** extracted

plugins/git/skills/git-history/README.md

@@ -0,0 +1,24 @@
+# git-history
+
+Inspect git history — log queries, bisect, and locating problematic commits.
+
+## What it does
+
+This skill handles history inspection within the git workflow suite. It queries logs with pickaxe/line-range/custom formats, runs bisect to find bug-introducing commits, and locates commits for downstream cherry-picking or reverting. It returns structured results for agent composition. Rebase, squash, fixup, and other history-rewriting operations are owned by git-commits, not this skill.
+
+## Usage
+
+```
+/git-history
+```
+
+Describe your history task: search logs, bisect for a regression, or locate a specific commit. The skill will query history and return structured results.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/git-log-format.md` | Full log format placeholders, diff-filter letters, `-L` syntax, ancestry filters, diff output-control flags |
+| `references/sources.md` | Research sources and provenance |
+| `references/README.md` | Index of the references directory |

plugins/git/skills/git-history/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: git-history
+
+description: >
+  Inspect git history: query logs with pickaxe, line-range, or custom formats; find bug origins via bisect; locate problematic commits for cherry-picking or reverting. Use when investigating history, tracing when a change happened, or finding the commit that broke something. Return structured results for downstream agents. Do not use for authoring or formatting commit messages, or executing rebase/squash/fixup operations — use git-commits for that.
+
+metadata:
+  category: git
+  source_keys:
+    - git-scm-bisect-docs
+    - git-scm-log-docs
+    - git-scm-diff-docs
+
+allowed-tools: Bash
+---
+
+## Gotchas
+
+- **Pickaxe searches (`-S` vs `-G`)**: `-S"string"` finds commits where string count changed; `-G"regex"` finds any line matching regex in diffs. They're not equivalent: a line replaced (one removal + one addition) matches `-G` but not `-S` if count is unchanged.
+- **`--follow` only works for single files**: it traces renames but fails with multiple paths or directory globs. Use `git log -- <single-file>` or query without `--follow`.
+- **Bisect with skips**: if bisect cannot pinpoint a commit because the culprit is adjacent to skipped commits, it reports "cannot find exact culprit" and lists candidates. This is not a failure — it's as precise as the skip range allows.
+- **Interactive rebase is non-recoverable on mistake**: there's no undo once `rebase -i` starts. Suggest `git reflog` to recover if the user realizes mid-way they selected the wrong commits.
+- **`-L` (line-range history) requires exact line numbers or regex patterns**: off-by-one errors omit the target range. Test the range with `git log -L` before offering it to users.
+
+## Query Logs and Locate Commits
+
+Default to `git log --oneline` for quick inspection. For deeper queries:
+
+- **Find when a string appeared or disappeared**: Use `git log -S"string"` (count-sensitive, finds adds/removes). If you need any mention of the string in diffs, use `git log -G"regex"` instead. Add `--pickaxe-regex` to treat the `-S` string as a POSIX ERE, and `--pickaxe-all` to show every changed file in a matching changeset, not just the matching ones. Binary files are searched by `-S`; `-G` ignores them unless `--text` is also supplied.
+- **Trace changes to a specific line or function**: Use `git log -L <start>,<end>:<file>` or `git log -L :<function>:<file>` (requires function name heuristic). This shows the evolution of that range across all commits.
+- **Filter by change type**: Use `git log --diff-filter=<type>` (A=added, M=modified, D=deleted, R=renamed) to narrow to specific file operations.
+- **Mainline-only history through merges**: Use `--first-parent` to follow only the integration branch and skip merged-in side-branch commits; combine with `--merges`/`--no-merges` or `--ancestry-path`/`--min-parents`/`--max-parents` for other ancestry-graph filtering — see `references/git-log-format.md` for the full set.
+- **Custom format for structured output**: Construct format string with `%h` (hash), `%s` (subject), `%an` (author), `%ar` (relative date), `%b` (body). Example: `git log --format="%h | %s | %an (%ar)"`.
+- **File-specific history with renames**: Use `git log --follow -- <file>` (single file only). Without `--follow`, log stops at the rename boundary.
+
+## Bisect to Find Blame Commit
+
+Use bisect when hunting for the commit that introduced a bug or behaviour change. Binary search reduces iterations from O(N) to O(log N).
+
+**Basic manual flow:**
+```bash
+git bisect start
+git bisect bad [HEAD]        # mark current (or specified) as broken
+git bisect good <commit>     # mark known-good baseline
+# Git checks out midpoint; test it manually
+git bisect good              # if test passes
+git bisect bad               # if test fails
+# Repeat until git reports "X is the first bad commit"
+git bisect reset             # return to original HEAD
+```
+
+**Automated with `git bisect run`:** if a test command exists, use `git bisect run <cmd>`. Git interprets the exit code: `0`=good, `1-124`=bad, `125`=skip (build broken), `126-127`=POSIX shell errors treated as bad, `128+`=**aborts the bisect session entirely** (not treated as bad — a crashed test script can silently end the search).
+
+**With skip:** if a commit is untestable (broken build), use `git bisect skip` to exclude it without manually deciding good/bad. If the first-bad is adjacent to skips, bisect reports it cannot pinpoint but lists candidates.
+
+**Undoing a wrong good/bad call:** `git bisect log` prints the session's decision history; save it (`git bisect log > bisect.log`), edit out the mistaken entry, then `git bisect reset && git bisect replay bisect.log` to resume from the corrected log instead of restarting the whole search.
+
+**Narrowing and speeding up the search:** `git bisect start HEAD v1.2 -- src/` limits bisection to a path, cutting the number of trials. `--no-checkout` updates the `BISECT_HEAD` ref instead of checking out a working tree (useful for tests that don't need one; 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 remaining candidates visually:** `git bisect visualize` (alias `view`) opens the suspects in gitk; add `--stat` or `-p` to show diffstat or full patches instead. Falls back to `git log` when no graphical display is detected.
+
+**For non-regression hunts:** use `git bisect start --term-new <new> --term-old <old>` to search for a property change instead of a bug (e.g., performance regression). Then use the custom terms instead of `good`/`bad`.
+
+For rebase execution (interactive rebase, squash/fixup/reword, conflict handling) see git-commits — it owns history-rewriting operations. This skill only locates commits and reports on history; it does not execute rebases.
+
+## Find and Manipulate Problematic Commits
+
+Once a commit is identified (via log query or bisect), offer cherry-pick or revert. This section is general git knowledge, not sourced from `history-inspection.md` — `git-branches`'s SKILL.md explicitly delegates cherry-pick/revert here (see its Merging section), which is why this skill carries them rather than treating them as out of scope:
+
+- **Cherry-pick**: `git cherry-pick <commit>` copies a commit's changes onto current HEAD. Use when backporting fixes to other branches.
+- **Revert**: `git revert <commit>` creates a new commit that undoes the changes. Use when un-applying a merged commit without rewriting history.
+- **Blame for context**: `git blame <file>` shows which commit last changed each line. Use to trace a specific line back to its introducing commit.
+
+## Inspect Diffs
+
+Diff-output tuning is in scope too: `--stat` for a diffstat summary, `--word-diff` for word-level (not line-level) changes, and whitespace flags (`-w`, `--ignore-blank-lines`) to suppress noise from reformatting. See `references/git-log-format.md` for the full flag set.
+
+## Return Results Structured
+
+For agent consumption, return:
+- **Commit SHA** (full or abbreviated as appropriate)
+- **Subject line** (from `%s`)
+- **Author and date** (from `%an` and `%ar`)
+- **Action taken or recommended** (e.g., "Found via bisect", "Offer cherry-pick to main", "Rebase conflicts detected")
+
+Example for agent:
+```
+Found first bad commit: abc1234
+Subject: fix null pointer in parser
+Author: Alice (2 weeks ago)
+Recommendation: Backport to release branch via cherry-pick
+```
+
+## Reference
+
+For the full log format placeholder catalogue, named format presets, `--diff-filter` letters, `-L` range syntax, ancestry filters, and `git diff` output-control flags, read `references/git-log-format.md`.

plugins/git/skills/git-history/references/README.md

@@ -0,0 +1,15 @@
+---
+source_keys:
+  - git-scm-bisect-docs
+  - git-scm-log-docs
+  - git-scm-diff-docs
+---
+
+# References
+
+This directory contains provenance metadata and research sources for the `git-history` skill.
+
+## Files
+
+- `sources.md` — Extracted research sources and their contributing documents
+- `git-log-format.md` — Full `git log` format placeholder catalogue, named format presets, `--diff-filter` letters, `-L` line-range syntax, ancestry filters, and `git diff` output-control flags

plugins/git/skills/git-history/references/git-log-format.md

@@ -0,0 +1,232 @@
+---
+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:**
+```
+%(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
+git log -S"my_function"
+git log -S"my_function" --pickaxe-regex    # treat as POSIX ERE
+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
+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
+git log --diff-filter=ad       # exclude added and deleted files
+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`.
+
+```bash
+git log -L 10,20:file.txt
+git log -L /start_pattern/,/end_pattern/:file.txt
+git log -L :myfunction:src/app.c
+git log -L /init/,+15:config.py          # 15 lines after first match of /init/
+```
+
+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
+git log --first-parent            # at merges, follow only first parent (mainline evolution)
+git log --merges                  # only merge commits (≥2 parents); equivalent to --min-parents=2
+git log --no-merges               # only non-merge commits; equivalent to --max-parents=1
+git log --ancestry-path D..M      # only commits actually on the path from D to M
+git log --min-parents=<n>         # include only commits with ≥ n parents
+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
+git diff --stat                   # diffstat: file names + ± bar
+git diff --stat=<width>,<name-width>,<count>
+git diff --compact-summary        # alongside --stat: shows new/gone, +x/-x (executable), +l (symlink)
+git diff --numstat                # machine-readable: <added>\t<deleted>\t<path>; - for binary
+```
+
+### --name-only / --name-status
+
+```bash
+git diff --name-only              # only filenames, one per line
+git diff --name-status            # status letter + filename per line
+```
+
+`--name-status` uses the same status letters as `--diff-filter`.
+
+### --word-diff
+
+```bash
+git diff --word-diff              # inline word-level diff with [-removed-] {+added+} markers
+git diff --word-diff=color        # color only, no markers
+git diff --word-diff=porcelain    # machine-readable: +/- prefixed lines, ~ for newlines
+git diff --word-diff-regex=<re>   # 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 |

plugins/git/skills/git-history/references/sources.md

@@ -0,0 +1,31 @@
+---
+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
+
+## 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:** references/git-log-format.md

plugins/git/skills/git-remotes/README.md

@@ -0,0 +1,24 @@
+# git-remotes
+
+Manage git remote repositories — add/remove/configure remotes, push/pull with safety checks, fetch with pruning, and multi-remote workflows.
+
+## What it does
+
+This skill handles remote operations within the git workflow suite. It manages remote configuration (add, remove, rename), fetch operations with pruning, push operations with force-push safety (`--force-with-lease --force-if-includes`), and pull strategies (fast-forward, rebase, merge). It returns structured results suitable for agent composition.
+
+## Usage
+
+```
+/git-remotes
+```
+
+Describe your remote operation: add a remote, push, pull, fetch, or configure tracking. The skill will handle the operation with appropriate safety checks and return results.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/README.md` | Describes the references directory contents |
+| `references/remotes.md` | Full `set-url` variants, shallow-clone/fetch options, force-push mitigation detail, and pull config precedence |
+| `references/sources.md` | Research sources and provenance |

plugins/git/skills/git-remotes/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: git-remotes
+
+description: >
+  Manage git remote repositories — add/remove/configure remotes, push/pull with safety checks,
+  handle fetch patterns and tracking branch updates, support multi-remote workflows.
+  Use when automating remote operations, pushing with force-push safety, fetching with pruning,
+  pulling with divergence resolution, or managing multi-remote tracking. Include indirect triggers:
+  any git operation that touches a remote, even if the user doesn't explicitly name the remote.
+  Do not use when working with local git history, commits, branches, or staging — use git-history
+  or git-branches instead.
+
+metadata:
+  category: git-workflow
+  source_keys:
+    - git-scm-remote-docs
+    - git-scm-fetch-docs
+    - git-scm-push-docs
+    - git-scm-pull-docs
+    - context7-git-htmldocs
+
+---
+
+## Gotchas
+
+- **Never force-push `main` or `master`, under any circumstances** — this is a hard refusal, not a `confirm: true` gate. If a force-push targets one of these branches, decline and explain why, regardless of how the request is confirmed.
+- **Force-push to any other branch requires explicit confirmation** — never execute `git push --force` or `git push -f` without user/agent approval. Always ask or require `confirm: true` flag first.
+- **`--force-with-lease` alone is not safe** — background processes (IDE plugins, cron jobs) that run `git fetch` silently defeat the protection. Always combine with `--force-if-includes` or use explicit SHA form `--force-with-lease=<ref>:<sha>`.
+- **Prune doesn't touch tags by default** — `git fetch --prune` leaves orphaned tags. Use `git fetch --prune --prune-tags` or configure `fetch.pruneTags true` globally.
+- **Pull with rebase rewrites history** — only safe for unpublished work. Rebasing already-pushed commits breaks everyone downstream. Check what's been pushed before rebasing.
+- **`git remote show` requires network access** — use `-n` flag for cached data if working offline. `git remote -v` lists URLs without network queries.
+- **Pull behavior defaults shift between Git versions** — older versions default to merge, newer versions to `--ff-only`. Always set `pull.ff only` explicitly for deterministic behavior.
+
+## Operations
+
+### Remote Management
+
+Use these to configure which remotes you push to and pull from:
+
+- **Add a remote**: `git remote add <name> <url>` or `git remote add -f <name> <url>` to fetch immediately
+- **Remove a remote**: `git remote remove <name>` (deletes remote + all tracking refs + config)
+- **Rename a remote**: `git remote rename <old> <new>`
+- **Inspect remotes**: `git remote -v` (show URLs) or `git remote show <name>` (live tracking status, requires network)
+- **Set-url separately for fetch vs. push**: `git remote set-url --push <name> <url>` changes only where pushes go — but 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. Full `set-url` variants (regex-targeted replace, `--add`, `--delete`): `references/remotes.md`.
+- **Remove a stale URL**: `git remote set-url --delete <name> <regex>`
+- **Inspect effective URLs**: `git remote get-url <name>` (shows URL after `insteadOf` rewrites) or `git remote get-url --push --all <name>` (all push URLs)
+- **Track only one branch**: `git remote add -t <branch> <name> <url>` (repeatable), or suppress tag import entirely with `git remote add --no-tags <name> <url>`
+- **Mirror a remote**: `git remote add --mirror=fetch <name> <url>` mirrors all refs locally (bare repos only); `--mirror=push` makes every push behave like `--mirror`
+- **Prune stale tracking refs without fetching**: `git remote prune <name>` (add `--dry-run` to preview first)
+- **Set the remote's default branch pointer**: `git remote set-head <name> -a` (auto-detect, requires a prior fetch), `git remote set-head <name> <branch>` (explicit), or `git remote set-head <name> -d` (delete `refs/remotes/<name>/HEAD`)
+
+### Fetch Operations
+
+Use these to update your tracking branches without touching your local branches:
+
+- **Fetch from one remote**: `git fetch <remote>` — fetches all branches
+- **Fetch one branch only**: `git fetch <remote> <branch>` — stores the result in `FETCH_HEAD`, not a tracking ref
+- **Fetch from all remotes**: `git fetch --all` with optional `--prune` to clean up stale tracking refs
+- **Prune properly**: Use `git fetch --all --prune --prune-tags` to clean both branches and tags
+- **Configure auto-prune**: Set `git config --global fetch.prune true` to auto-prune on every fetch across all remotes (or `remote.<name>.prune` to scope it to one remote)
+- **Shallow clones**: `--depth=<n>` to deepen or create a shallow clone, `--unshallow` to convert to full history, `--update-shallow` to allow the shallow boundary to move. Details and the default fetch refspec: `references/remotes.md`.
+
+Fetch never modifies your local branches — it only updates remote-tracking branches (`refs/remotes/origin/*`).
+
+### Push Operations
+
+Use these to send your commits upstream. Default: safe push to same-named branch on the remote.
+
+- **Basic push**: `git push <remote> <branch>` — pushes to same-named remote branch
+- **Set upstream**: `git push -u <remote> <branch>` — push and configure this branch to track the remote
+- **Multi-remote push**: `git push origin develop` and `git push staging develop` sequentially, or use `git remote set-url --add <name> <url>` to push to multiple remotes with one command
+- **Force-push safety**: Always use `git push --force-with-lease --force-if-includes <remote> <branch>` over bare `--force`. Require explicit confirmation first — and never for `main`/`master` (see Gotchas). `--force-if-includes` is a no-op without `--force-with-lease`. If background tools (IDE, cron) auto-fetch and could poison the lease check, use a dedicated push-only remote instead — see `references/remotes.md`.
+- **Server-side enforcement**: `receive.denyDeletes`, `receive.denyDeleteCurrent`, and `receive.denyNonFastForwards` are enforced on the remote regardless of local flags — a hardened server rejects the push even with `--force`.
+- **Delete remote branch**: `git push <remote> --delete <branch>` (not `:<branch>` syntax; clearer and cleaner)
+- **Push everything**: `git push --all` (all local branches) or `git push --tags` (all tags)
+- **Push a single tag**: `git push origin <tag>`
+- **Delete remote branches with no local counterpart**: `git push --prune origin 'refs/heads/*:refs/heads/*'`
+- **Force only part of a multi-ref push**: prefix the one refspec that needs it with `+`, e.g. `git push origin +main develop` forces `main` while safe-pushing `develop`
+
+Refspec syntax is `[+]<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) |
+| `:<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>` |
+
+### Pull Operations
+
+Use these to fetch and integrate remote changes. Default strategy: `--ff-only` (fail if diverged, forcing a conscious choice).
+
+- **Pull with fast-forward only**: `git pull --ff-only` (recommended default — fails if you've diverged, forcing a rebase/merge decision)
+- **Pull with rebase**: `git pull --rebase` (replays your unpublished commits on top; linear history, but rewrites SHAs — only safe for unpublished work)
+- **Pull with merge**: `git pull --no-rebase` (three-way merge commit; preserves original commits, non-linear)
+- **Pull with rebase, preserving merges**: `git pull --rebase=merges` (like `--rebase`, but keeps intentional local merge commits during replay)
+- **Pull without integrating**: `git pull --squash` collapses incoming commits into staged changes without committing — you write the commit message
+- **Set pull strategy globally**: `git config pull.ff only` (or `pull.rebase true`; respects branch-specific overrides via `branch.<name>.rebase`). Full precedence order (CLI flag > `pull.rebase` > `branch.<name>.rebase` > `branch.autoSetupRebase`): `references/remotes.md`.
+- **Check before rebasing**: Always verify your commits haven't been pushed before using `--rebase`. Rebasing published commits breaks everyone downstream.
+- **Merge strategy default**: Git 2.34+ defaults to the `ort` merge strategy (`recursive` is now just an alias for it). Strategy options like `-X ours`, `-X theirs`, `-X ignore-space-change` still pass through unchanged.
+- **Submodules on pull**: `--recurse-submodules` only fetches submodules that are already checked out — newly added submodules are not initialized automatically. Use the `git-submodules` skill to initialize new ones.
+
+If pull diverges and you haven't set a strategy, the operation fails — this is good, forces a conscious choice. Never auto-merge diverged branches without asking.
+
+### Return Format (for agents)
+
+Return structured output:
+```json
+{
+  "success": true,
+  "operation": "push",
+  "remote": "origin",
+  "branch": "main",
+  "output": "...",
+  "warnings": ["force-with-lease not confirmed"],
+  "recommendations": ["set pull.ff=only globally"]
+}
+```
+
+On failure, include `error` field with root cause and recovery suggestion.

plugins/git/skills/git-remotes/references/README.md

@@ -0,0 +1,17 @@
+---
+source_keys:
+  - git-scm-remote-docs
+  - git-scm-fetch-docs
+  - git-scm-push-docs
+  - git-scm-pull-docs
+  - context7-git-htmldocs
+---
+
+# References
+
+This directory contains provenance metadata and research sources for the `git-remotes` skill.
+
+## Files
+
+- `sources.md` — Extracted research sources and their contributing documents
+- `remotes.md` — Full `set-url` variants, shallow-clone/fetch options, default fetch refspec, force-push mitigation detail, server-side deny policies, and pull config precedence

plugins/git/skills/git-remotes/references/remotes.md

@@ -0,0 +1,82 @@
+---
+topic: remotes
+source_keys:
+  - git-scm-remote-docs
+  - git-scm-fetch-docs
+  - git-scm-push-docs
+  - git-scm-pull-docs
+---
+
+## `set-url` — full form
+
+```bash
+git remote set-url <name> <newurl>                  # replace the first fetch URL
+git remote set-url <name> <newurl> <oldurl-regex>   # replace only the URL matching regex
+git remote set-url --push <name> <url>              # change push URL only (must point at same repo)
+git remote set-url --add <name> <url>               # add an extra push URL (push to multiple remotes)
+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.
+
+## Shallow clones and partial fetch
+
+```bash
+git fetch <remote> <branch>       # fetch one branch only, stored in FETCH_HEAD (not a local/tracking ref)
+git fetch --depth=<n>             # deepen history, or create a shallow clone
+git fetch --unshallow             # convert a shallow clone to full history
+git fetch --update-shallow        # allow the fetch to update the shallow boundary
+git fetch --refmap='' <remote> <branch>  # fetch without updating any tracking ref (FETCH_HEAD only)
+```
+
+## Default fetch refspec
+
+The default fetch refspec is `+refs/heads/*:refs/remotes/<name>/*`. The leading `+` forces the update — remote-tracking branches always mirror the remote exactly and provide no protection for local history. Fetch never touches your local branches, only remote-tracking refs.
+
+## 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.
+git remote add origin-push $(git config remote.origin.url)
+git push --force-with-lease origin-push
+
+# Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state
+git fetch
+git tag base master
+git rebase -i master
+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 when the `--force-with-lease=<ref>:<sha>` form is used (that form already pins an exact SHA).
+
+Safest combination: `git push --force-with-lease --force-if-includes origin`.
+
+Remote-side policies (`receive.denyDeletes`, `receive.denyDeleteCurrent`, `receive.denyNonFastForwards`) are enforced server-side regardless of any local flag — a server configured this way rejects the push even with `--force`.
+
+## Pull config precedence
+
+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
+git config --global pull.rebase true
+git config branch.develop.rebase false   # develop always merges, regardless of the global default
+```

plugins/git/skills/git-remotes/references/sources.md

@@ -0,0 +1,71 @@
+---
+# 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:**
+- SKILL.md (Remote Management section)
+- references/remotes.md (`set-url` full form)
+
+---
+
+## 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 (Fetch Operations section, Gotchas)
+- references/remotes.md (shallow clones, default fetch refspec)
+
+---
+
+## 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 (Push Operations section, Gotchas)
+- references/remotes.md (force-push safety full detail, server-side deny policies)
+
+---
+
+## 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 (Pull Operations section, Gotchas)
+- references/remotes.md (pull 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)

plugins/git/skills/git-submodules/README.md

@@ -0,0 +1,24 @@
+# git-submodules
+
+Initialize, clone, update, and manage git submodules for multi-repository projects.
+
+## What it does
+
+This skill handles submodule operations within the git workflow suite. It initializes submodules, clones repositories with nested submodule dependencies, updates submodule pinning, and manages version control across multi-repo projects. The skill provides clean workflows for projects with complex dependency structures and returns structured results suitable for agent composition.
+
+## Usage
+
+```
+/git-submodules
+```
+
+Describe your submodule task: initialize, clone, update, or manage versions. The skill will handle the operation and return structured results (operation, status, per-submodule details, conflicts, and a recovery `next_step` when applicable) suitable for agent composition.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/README.md` | Describes contents of references/ |
+| `references/submodules.md` | Deep-dive reference: full flag tables, workflow patterns, safe-removal sequence, `absorbgitdirs`, `foreach` variables |
+| `references/sources.md` | Research sources and provenance |

plugins/git/skills/git-submodules/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: git-submodules
+
+description: >
+  Use when managing Git submodules: add dependencies as submodules, initialize and update nested repositories, sync URLs, inspect status (including detached HEAD and divergence), and safely remove submodules. Handles multi-repo projects with pinning, parallel operations, and recursive traversal. Use for both initial setup and ongoing maintenance workflows, even if the user doesn't explicitly say "submodule". Do not use for general git operations outside of submodule management.
+
+metadata:
+  category: git
+  source_keys:
+    - git-scm-submodule-docs
+---
+
+## Concept
+
+A submodule is a full Git repository embedded as a subdirectory inside a parent repository (the superproject). The superproject doesn't store the submodule's files — it stores a pointer to a specific commit SHA in the submodule's own history, and the two repos keep fully independent commit histories.
+
+Two files govern a submodule, and they serve different audiences:
+
+- **`.gitmodules`** — version-controlled, shared with collaborators. Defines each submodule's name, path, and canonical URL.
+- **`.git/config`** — local only, populated by `git submodule init`. This is where local URL overrides live (e.g. a private mirror) — they never propagate to other clones.
+
+The submodule's own `.git` directory lives at `.git/modules/<name>/` in the superproject, linked to the submodule's working tree via a `.git` pointer file. After `git submodule update`, the working tree normally ends up in **detached HEAD state** — see Gotchas.
+
+## Gotchas
+
+- **Detached HEAD by default.** `git submodule update` checks out a specific commit, not a branch. Work on a branch first, then update the pointer in the superproject. Commits made in detached state are invisible until pinned.
+- **Two pushes required, in order.** Always commit and push the submodule first, then update and push the superproject's pointer. The superproject only stores a commit SHA — if that SHA isn't reachable on the submodule's remote yet, `git submodule update` fails for anyone who pulls the superproject before the submodule push lands.
+- **`--recursive` is not default.** Most commands operate one level deep. Pass `--recursive` explicitly for nested submodules.
+- **`.git/modules/` persists after `git rm`.** Manual cleanup is needed: `rm -rf .git/modules/<name>/`.
+- **Detached HEAD detection.** Status prefix `+` means the checked-out commit differs from the superproject's recorded commit — normal after `update --remote`, but should be re-pinned before committing.
+- **Relative URLs resolve against the remote, not the filesystem.** A `../foo.git` entry in `.gitmodules` is relative to the superproject's default remote URL.
+- **Custom `update` commands are security-gated.** A `.gitmodules` entry of `update = !some-command` is never copied to `.git/config` by `git submodule init` — this stops a clone from silently executing arbitrary code.
+
+## Conventions
+
+- **Use `rtk git` for parent-repo operations.** Drop into the submodule directory only for submodule-specific git commands (committing/pushing inside the submodule itself) — mixing the two from the wrong working directory targets the wrong repo's history.
+- **Check for a dirty submodule before committing the parent pointer.** After adding or updating a submodule, run `git status` in both the parent and the submodule. A `-dirty` suffix means the submodule has uncommitted local changes; committing the parent pointer now would pin a state no one else can reproduce, since those changes exist only in the local working tree.
+
+## Operations
+
+- **Clone a repo that has submodules**: `rtk git clone --recurse-submodules <url>` (one step, Git 2.13+) or `rtk git clone <url>` followed by `rtk git submodule update --init --recursive`.
+- **Add a submodule**: `rtk git submodule add <url> <path>` (`-b <branch>` to track a branch instead of a pinned commit, `--depth 1` for a shallow clone, `-f` to force past a gitignored path or name conflict, `--name <name>` when the logical name should differ from the path). Stages a `.gitmodules` entry and a gitlink — a commit is still required.
+- **Initialize**: `rtk git submodule init [<path>...]` copies submodule URLs from `.gitmodules` to `.git/config`. This is the point at which local URL overrides can be edited before fetching. Does not clone — use `update` (or `update --init` to run both in one step).
+- **Update (clone + checkout)**: `rtk git submodule update --init --recursive` is the common case — checks out the recorded commit in detached HEAD. Add `--remote --merge` (or `--remote --rebase`) to track the branch tip instead, `--jobs <n>` for parallel clones, `-f` to discard local changes. Full flag table: `references/submodules.md`.
+- **Inspect status**: `rtk git submodule status --recursive` (add `--cached` to show SHAs in the superproject index instead of the working tree). Status prefixes: `-` not initialized, `+` diverged from the superproject's recorded commit, `U` merge conflict.
+- **Sync and rebind URLs**: `rtk git submodule sync --recursive` after an upstream URL rename propagates `.gitmodules` changes into `.git/config`. `rtk git submodule set-url <path> <url>` changes a URL directly; `rtk git submodule set-branch -b <branch> <path>` sets the tracking branch used by `update --remote`.
+- **Override a submodule URL locally (private mirror)**: local-only, doesn't propagate to collaborators, and gets overwritten by the next `sync`. Full steps: `references/submodules.md`.
+- **Run a command across all submodules**: `rtk git submodule foreach --recursive '<command>'`. Shell variables available inside `<command>` (`$name`, `$sm_path`, `$displaypath`, `$sha1`, `$toplevel`): `references/submodules.md`.
+- **Deinit (unregister without removing)**: `rtk git submodule deinit <path>` (`--all` for every submodule, `-f` if local modifications are present) clears the `.git/config` section and empties the working tree. **`deinit` is not removal** — the `.gitmodules` entry and the gitlink in the superproject's index are untouched.
+- **Safe removal** (destructive; confirm before executing) — full three-step sequence including the manual `.git/modules/` cleanup: `references/submodules.md`.
+- **Move an embedded `.git` into `.git/modules/`**: `rtk git submodule absorbgitdirs [<path>...]` — needed when a submodule was created or copied without going through `git submodule add`. Details: `references/submodules.md`.
+
+## Configuration
+
+`.gitmodules` (version-controlled, shared with collaborators):
+
+| 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 shallow clone |
+
+`.git/config` (local only, populated by `init`):
+
+| 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. |
+
+```bash
+rtk git config submodule.recurse true   # keep submodules pinned automatically after every pull
+```
+
+## Agent output format
+
+Return results as structured data:
+```
+operation: <clone|add|init|update|sync|set-url|set-branch|status|summary|absorbgitdirs|remove>
+status: <success|error|partial>
+message: <human-readable summary>
+details:
+  - <submodule-path>: <state>
+conflicts: [<submodule-path>, ...]  # if any
+next_step: <recovery action if applicable>
+```
+
+For errors, include the git command output and recommend recovery (e.g., `git submodule deinit`, force-update, or URL override).

plugins/git/skills/git-submodules/references/README.md

@@ -0,0 +1,15 @@
+---
+metadata:
+  source_keys:
+    - git-scm-submodule-docs
+---
+
+# References
+
+## submodules.md
+
+Deep-dive reference: full `update` flag table, workflow patterns (clone, add, keep-pinned, update-to-latest, override URL), the complete safe-removal sequence, `absorbgitdirs`, and `foreach` shell variables. Load when SKILL.md's condensed Operations list isn't enough detail.
+
+## sources.md
+
+Research sources that informed this skill — provenance chain for git-scm-submodule-docs reference material.

plugins/git/skills/git-submodules/references/sources.md

@@ -0,0 +1,29 @@
+---
+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/submodules.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` — git:configuration
+- `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

plugins/git/skills/git-submodules/references/submodules.md

@@ -0,0 +1,93 @@
+---
+topic: submodules
+source_keys:
+  - git-scm-submodule-docs
+---
+
+# Submodules — Deep Reference
+
+## Update flag reference
+
+| Flag | Meaning |
+|---|---|
+| `--init` | Run init first (avoids a separate step) |
+| `--remote` | Use the submodule's remote branch tip instead of the superproject's recorded commit |
+| `--checkout` | Detached HEAD at recorded commit (default) |
+| `--rebase` | Rebase current branch onto recorded commit |
+| `--merge` | Merge recorded commit into current branch |
+| `--recursive` | Operate on nested submodules |
+| `--jobs <n>` | Parallel clone (defaults to `submodule.fetchJobs`) |
+| `-N` / `--no-fetch` | Skip remote fetch |
+| `--depth <n>` | Shallow clone |
+| `--filter <spec>` | Partial clone filter |
+
+## Workflow patterns
+
+### Clone a repo with submodules
+```bash
+git clone --recurse-submodules <url>   # Git 2.13+, one step
+# or
+git clone <url>
+git submodule update --init --recursive
+```
+
+### Add a dependency as a submodule
+```bash
+git submodule add https://github.com/org/lib.git libs/lib
+git commit -m "chore: add lib as submodule"
+```
+
+### Keep submodules pinned to the superproject's recorded commit
+```bash
+git submodule update --recursive   # after every git pull
+git config submodule.recurse true  # do this automatically on pull
+```
+
+### Update submodules to the latest commit on their tracked branch
+```bash
+git submodule update --remote --merge --recursive
+git commit -am "chore: update submodules to latest"
+```
+
+### Override a submodule URL locally (private mirror)
+```bash
+git submodule init
+# edit .git/config: submodule.<name>.url = <mirror-url>
+git submodule update
+```
+Local-only override (`.git/config`, not `.gitmodules`) — doesn't propagate to collaborators. Re-running `sync` overwrites it with the `.gitmodules` URL.
+
+## Removal, in full
+
+`deinit` alone does not remove a submodule — it only clears `.git/config` and empties the working tree. To fully remove:
+```bash
+git submodule deinit -f <path>   # unregister from .git/config
+git rm <path>                     # remove .gitmodules entry + gitlink from index
+rm -rf .git/modules/<name>/       # stale git dir; not tracked by git, not auto-cleaned
+git commit -m "chore: remove <name> submodule"
+```
+`.git/modules/<name>/` persisting after `git rm` will block re-adding the same path until manually deleted.
+
+## Relocate an embedded `.git` directory
+
+```bash
+git submodule absorbgitdirs [<path>...]
+```
+Moves a submodule's own `.git` directory into the superproject's `.git/modules/<name>/`, linking it back with a `.git` pointer file. Needed when a submodule was created or copied without going through `git submodule add` (e.g. converting a plain nested repo into a proper submodule).
+
+## `foreach` shell variables
+
+Available inside the `<command>` argument to `git submodule foreach`:
+
+| Variable | Meaning |
+|---|---|
+| `$name` | Logical submodule name |
+| `$sm_path` | Path relative to superproject root |
+| `$displaypath` | Path relative to current working directory |
+| `$sha1` | Recorded commit SHA |
+| `$toplevel` | Superproject's root path |
+
+```bash
+git submodule foreach --recursive '<command>'
+git submodule foreach 'git pull origin main || :'   # || : continues past failures
+```

plugins/git/skills/git-workflow/README.md

@@ -0,0 +1,24 @@
+# git-workflow
+
+Human-friendly interface for interactive git workflows with conversational prompts, progress guidance, and safety confirmations.
+
+## What it does
+
+This skill wraps the `git-orchestrate` agent to provide an interactive, educational interface for humans performing git workflows. It handles commits, branch management, history inspection, submodules, worktrees, and remotes. The skill parses user intent, gathers session context, invokes the orchestrator, and presents results in plain language with inline help, progress updates, and explanations of what's happening. It enforces confirmation gates for destructive operations (force-push, branch deletion, rebasing with history loss, force-checkout) and provides best-practices guidance throughout.
+
+## Usage
+
+```
+/git-workflow
+```
+
+Describe your git workflow: commit, create a branch, rebase, inspect history, manage submodules, switch worktrees, or manage remotes. The skill will prompt for any missing details and guide you through the workflow.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `README.md` | This file |
+| `references/README.md` | Describes the references directory contents |
+| `references/sources.md` | Research sources and provenance |

plugins/git/skills/git-workflow/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: git-workflow
+
+description: >
+  Use when a human user wants to perform git workflows interactively — commits, branch management,
+  history inspection, submodules, worktrees, or remotes. Provides a friendly, conversational
+  interface with clarification prompts ("Which branch base?"), progress updates, inline help,
+  best practices guidance, and confirmation dialogs for destructive operations. Guides users
+  through complex git patterns even if they don't mention every detail. Do not use when the
+  caller is an agent—agents should invoke git-orchestrate directly for deterministic, composable execution.
+
+metadata:
+  category: git
+  source_keys:
+    - nvie-gitflow-post
+    - atlassian-gitflow-tutorial
+    - gitflow-cheatsheet
+    - context7-git-htmldocs
+    - org-git-conventions
+---
+
+## Gotchas
+
+- This skill is specifically for **human interaction**. If the caller is an agent, invoke `git-orchestrate` directly instead—this skill adds UI overhead agents don't need.
+- Session context from previous git operations (branch names, commit strategy) persists during a single multi-step user request, then clears. Users don't need to re-provide decisions within one workflow.
+- Destructive operations require explicit confirmation: force-push, branch deletion, rebase with history loss, force-checkout. Users must confirm interactively; the skill never proceeds without their approval on destructive ops.
+- Run git commands through `rtk git <command>` rather than bare `git <command>` for parent-repo operations — this is a mandated org wrapper, not an optional style choice. Drop into a submodule's own directory for submodule-specific commands (see `git-submodules`).
+
+### Hard rules
+
+These are non-negotiable regardless of what the user asks for — surface them proactively rather than waiting for the user to hit them (`org-git-conventions`; sub-skills invoked directly by humans, like this one, carry their own local copy of these rules for readers who won't chain through `git-orchestrate`, so state them plainly rather than assuming the user already knows them):
+
+- Never skip hooks with `--no-verify` — hooks are the automated QA gate, and bypassing them breaks the pipeline for everyone downstream.
+- Never force-push `main` or `master`.
+- Keep commits atomic — each commit should represent one logical, independently reviewable and reversible change.
+- Every commit must leave the repository in a working state (buildable/testable where practical).
+- Commit messages explain **why**, not **what** — the diff already documents what changed.
+- Never commit secrets, credentials, or environment-specific config.
+- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
+- Reference related issues, ADRs, or design documents using Git trailers when applicable.
+
+If a user's request conflicts with a hard rule (e.g. "force-push main to fix this"), explain the rule and propose a safe alternative instead of complying.
+
+## Workflow
+
+When a user wants to perform git workflows:
+
+1. **Parse the user's intent** — extract the high-level task (commit, create branch, rebase, inspect history, etc.) and any explicit options they mentioned.
+2. **Build session context** — gather repo state, current branch, any prior decisions in this workflow (branch intent for commit messages, base branch for rebasing, etc.).
+3. **Invoke git-orchestrate agent** — call it with:
+   - `operation`: the git operation (e.g., "commit", "create-branch", "rebase")
+   - `parameters`: user-provided or inferred options
+   - `context`: decisions and repo state from prior steps in this workflow
+   - `confirm`: `true` if a destructive op and the user confirmed, otherwise omit
+4. **Handle the response** — if orchestrator succeeds, present results in plain language with progress updates and explanations. If it fails, show the error reason and suggest recovery actions.
+5. **Clarification prompts** — if the orchestrator needs more information (e.g., "Which branch should this be based on?"), prompt the user conversationally and loop back with the user's input.
+6. **Confirmation gates** — before executing any destructive op (force-push, branch deletion, rebase, force-checkout), show what will happen and ask "Proceed?" If the user declines, cancel gracefully.
+
+## Interaction style
+
+- **Conversational**: Use natural language, not technical jargon. "Let me rebase your changes onto main" not "Running git rebase --interactive main".
+- **Pedagogical**: Explain what each step does and why. "I'm squashing your last 3 commits into one clean commit" not just "Squashing commits".
+- **Guided**: Offer inline help. When users mention ambiguous steps, suggest best practices. Match the tip to the repo's branching model: for Gitflow-style repos, "Tip: Feature branches branch off `develop`, not `main` — `main` only tracks released code." For trunk-based/GitHub Flow repos, "Tip: Short-lived feature branches off `main` keep merges small and reviewable."
+- **Transparent**: Show progress. "Creating branch feature/user-auth..." then "✓ Branch created. Ready to commit." Humans benefit from seeing workflow state.
+- **Safe**: Always confirm before destructive ops. Never silently rewrite history or force-push without explicit user approval.

plugins/git/skills/git-workflow/references/README.md

@@ -0,0 +1,16 @@
+---
+source_keys:
+  - nvie-gitflow-post
+  - atlassian-gitflow-tutorial
+  - gitflow-cheatsheet
+  - context7-git-htmldocs
+  - org-git-conventions
+---
+
+# References
+
+This directory contains provenance metadata and research sources for the `git-workflow` skill.
+
+## Files
+
+- `sources.md` — Extracted research sources and their contributing documents

plugins/git/skills/git-workflow/references/sources.md

@@ -0,0 +1,59 @@
+---
+# 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:**
+- SKILL.md (Gotchas — Hard rules subsection, rtk git note)

plugins/git/skills/git-worktrees/README.md

@@ -0,0 +1,24 @@
+# git-worktrees
+
+Manage git worktrees to enable multi-branch parallel development across isolated directories.
+
+## What it does
+
+This skill handles worktree operations within the git workflow suite. It creates, lists, locks/unlocks, moves, removes, prunes, and repairs worktrees — letting an agent work on multiple branches simultaneously without stashing. It returns structured results (paths, branches, lock status) suitable for agent composition.
+
+## Usage
+
+```
+/git-worktrees
+```
+
+Describe your worktree task: create a worktree for a branch, list existing worktrees, lock one for removable media, move, remove, prune, or repair. The skill will handle the operation with appropriate safety checks and return results.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/README.md` | Describes the references directory contents |
+| `references/worktrees.md` | Full `add` flag table, sparse-checkout, removable-media locking, remote disambiguation, configuration |
+| `references/sources.md` | Research sources and provenance |

plugins/git/skills/git-worktrees/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: git-worktrees
+
+description: >
+  Manage Git worktrees to enable multi-branch parallel development across isolated directories.
+  Use when the user needs to work on multiple branches simultaneously without stashing, switch between feature/hotfix/experimental work, or coordinate code reviews alongside ongoing development.
+  Handles creation, listing, locking, moving, removal, pruning, and repair of worktrees.
+  Provides structured results (paths, branches, lock status) for agent composition in git orchestration workflows.
+  Do not use when only inspecting a single branch or when the user needs standard checkout/stash workflows.
+
+metadata:
+  category: git
+  source_keys:
+    - git-scm-worktree-docs
+---
+
+## Concept
+
+A worktree lets you check out multiple branches simultaneously from one repository, each in its own directory. All worktrees share the same objects, config, and most refs (`refs/`). Each worktree has its own `HEAD`, index, and per-worktree metadata (`ORIG_HEAD`, `MERGE_HEAD`, `refs/bisect/`, `refs/worktree/`, `refs/rewritten/`) stored at `$GIT_DIR/worktrees/<name>/`. The **main worktree** (from `git init`/`git clone`) is exactly one per repo and cannot be removed; **linked worktrees** are the additional ones created via `git worktree add`.
+
+## Gotchas
+
+- **A branch can only be checked out in one worktree at a time.** Attempting `git worktree add` for an already-checked-out branch fails unless you pass `--force`. Use `--force` only when intentional.
+- **Submodules are unsupported and block operations.** Repos with submodules have incomplete worktree support. Worktrees containing submodules cannot be moved and require `--force` to remove.
+- **Never manually `rm -rf` a worktree directory.** This leaves stale metadata in `$GIT_DIR/worktrees/`. Always use `git worktree remove`. If already deleted, run `git worktree prune` to clean up.
+- **Manual moves break bidirectional pointers.** If a worktree directory is moved outside of `git worktree move`, run `git worktree repair` to fix connections.
+- **Force-flag escalation with locks.** Removing or moving a locked worktree requires `-ff` (two flags), not just `-f`.
+- **Worktree identification is by full path, unique basename, or unique partial path.** Ambiguous names error. Use `git worktree list` to see available identifiers.
+- **`--lock` on `add` is atomic; create-then-lock has a race window.** Use `--lock` directly on `git worktree add` when consistency matters.
+- **`extensions.worktreeConfig = true` is a one-way door.** It enables per-worktree config (`git config --worktree ...`) but makes the repo refuse to open in older Git versions. Once set, `core.bare`/`core.worktree` must live in `config.worktree`, not `config`. Don't enable it unless per-worktree config is actually needed.
+
+## Common Operations
+
+**Create and switch to a new worktree** — default approach:
+```bash
+git worktree add -b <new-branch> <path>
+cd <path>
+```
+This creates a new branch and checks it out in a new directory. Other branches cannot be checked out elsewhere simultaneously.
+
+**Create-or-reset a branch**: `git worktree add -B <branch> <path>` — like `-b` but resets the branch to HEAD if it already exists.
+
+**Create a worktree for an existing remote branch**:
+```bash
+git worktree add <path> <remote>/<branch>
+```
+For ambiguous names across remotes, disambiguate via `checkout.defaultRemote` config or `--guess-remote`. Full flag table and detail: `references/worktrees.md`.
+
+**Throwaway experiment in detached HEAD**:
+```bash
+git worktree add -d ../experiment   # or --detach
+# experiment freely, no branch created
+git worktree remove ../experiment
+```
+
+**List all worktrees with state**:
+```bash
+git worktree list -v        # human-readable with lock/prune reasons
+git worktree list --porcelain -z  # machine-readable, NUL-terminated
+```
+
+**Move a worktree to a new path**:
+```bash
+git worktree move <current-path> <new-path>
+# Cannot move: main worktree, worktrees with submodules
+# To override safeguards: -f; to override locked state too: -ff
+```
+
+**Remove a worktree**:
+```bash
+git worktree remove <path>        # only if clean
+git worktree remove -f <path>     # force-remove unclean
+git worktree remove -ff <path>    # force-remove even if locked
+```
+
+**Prune stale metadata**:
+```bash
+git worktree prune --dry-run        # preview what would be removed
+git worktree prune                  # clean up orphaned metadata
+```
+Also triggered by `git gc`, controlled by `gc.worktreePruneExpire` config.
+
+**Repair broken connections** (after a manual move):
+```bash
+git worktree repair  # from main worktree or after it was moved
+git worktree repair <path>  # reconnect a specific linked worktree
+```
+
+Sparse-checkout worktrees, locking for removable media, the full `add` flag table, and the config key reference: `references/worktrees.md`.
+
+## Worked Examples
+
+**Emergency fix without disrupting current work** — no stashing needed, ongoing work in the main worktree is untouched:
+```bash
+git worktree add -b emergency-fix ../temp main
+cd ../temp
+# fix, commit
+git commit -a -m "fix: critical production bug"
+cd -
+git worktree remove ../temp
+```
+
+**Review a PR branch alongside your current work** — no context switch, both branches stay checked out:
+```bash
+git worktree add ../review-pr-123 origin/feature-xyz
+# open ../review-pr-123 in a second editor window or terminal
+```
+
+## Return Format for Agents
+
+When invoking worktree operations, return structured results:
+```yaml
+worktrees:
+  - path: <directory-path>
+    branch: <branch-name>
+    commit: <short-hash>
+    locked: <true/false>
+    lock_reason: <reason or empty>
+  - ...
+```
+Derive these fields from `git worktree list --porcelain -z` — its `worktree`/`branch`/`HEAD`/`locked` lines map directly to `path`/`branch`/`commit`/`locked`+`lock_reason`.
+
+For single operations, include the operation result (e.g., `created: true`, `removed: true`, `moved: true`).
+
+For multi-step flows spanning branch strategy plus worktree setup, compose with the `git-workflow` skill — it handles the broader orchestration, this skill handles the worktree mechanics.

plugins/git/skills/git-worktrees/references/README.md

@@ -0,0 +1,13 @@
+---
+source_keys:
+  - git-scm-worktree-docs
+---
+
+# References
+
+This directory contains provenance metadata and research sources for the `git-worktrees` skill.
+
+## Files
+
+- `sources.md` — Extracted research sources and their contributing documents
+- `worktrees.md` — Full `add` flag table, sparse-checkout setup, removable-media locking, remote-branch disambiguation, and the config key reference

plugins/git/skills/git-worktrees/references/sources.md

@@ -0,0 +1,16 @@
+---
+# 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 (Concept, Gotchas, Common Operations, Worked Examples, Return Format)
+- references/worktrees.md (full `add` flag table, sparse-checkout, removable media, remote disambiguation, configuration)

plugins/git/skills/git-worktrees/references/worktrees.md

@@ -0,0 +1,63 @@
+---
+topic: worktrees
+source_keys:
+  - git-scm-worktree-docs
+---
+
+## 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 |
+| `--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
+git worktree add --orphan -b <branch> <path>
+```
+Creates an empty branch with no commits.
+
+## Sparse-checkout worktree
+
+Suppress the initial checkout to configure sparse-checkout first:
+```bash
+git worktree add --no-checkout ../sparse main
+cd ../sparse
+git sparse-checkout init --cone
+git sparse-checkout set src/
+git checkout main
+```
+
+## Worktree on removable media
+
+```bash
+git worktree add --lock --reason "external SSD" <path> <branch>
+git worktree unlock <path>  # when reconnected
+```
+
+## Remote-branch disambiguation
+
+```bash
+git worktree add <path> <remote>/<branch>
+```
+For ambiguous names across remotes, `checkout.defaultRemote` config disambiguates explicitly, or `--guess-remote` auto-matches by path basename (default controlled by `worktree.guessRemote` config). If a branch name matches multiple remotes during `worktree add` and neither is set, Git refuses rather than guessing.
+
+## 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` |

plugins/git/skills/pc-author/README.md

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

plugins/git/skills/pc-author/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: pc-author
+description: >
+  Use when the user wants to create, add hooks to, remove hooks from, update,
+  or configure .pre-commit-config.yaml. Triggers on: "set up pre-commit",
+  "add a hook", "remove this hook", "configure pre-commit", "create a pre-commit
+  config", "disable trailing whitespace hook", "add shellcheck", "update my
+  pre-commit config", even if the user does not name pre-commit explicitly.
+  Do not use for running hooks, installing git hooks, or bumping revision pins
+  — use pc-run for those.
+allowed-tools: Bash Read Write Edit
+metadata:
+  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. `pre-commit autoupdate` breaks silently on branches.
+- Fixers (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json`) modify files but do NOT auto-stage them. The commit is blocked; the user must re-stage and recommit. Warn when adding fixers.
+- `pre-commit validate-config` catches YAML structure errors but does NOT check whether hook `id`s exist in the target repo's manifest, and does NOT download or run hooks. It is fast; run it after every write.
+- When removing a hook leaves its repo block with zero hooks, delete the entire repo block — an empty `hooks: []` causes `validate-config` to fail.
+- `language: system` and `language: script` are deprecated names. Use `language: unsupported` and `language: unsupported_script` for new local hooks.
+
+## Route
+
+Check before acting:
+
+- `.pre-commit-config.yaml` does not exist → **Create from scratch**
+- File exists → **Modify existing**
+
+## Create from scratch
+
+1. Run a shallow extension scan:
+   ```bash
+   git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
+   ```
+2. Read `references/hooks-by-language.md` to map detected extensions to recommended hooks. For a 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 before writing. Wait for user confirmation.
+4. Write `.pre-commit-config.yaml`.
+5. Run `pre-commit validate-config`. If non-zero: show the error, fix it, re-validate. Never leave a broken config.
+
+## Modify existing
+
+Read `.pre-commit-config.yaml` first. Note any stale `rev` values (see **Rev staleness** below) but do not change them.
+
+### Adding a hook
+
+1. Run a shallow extension scan to detect languages in the repo:
+   ```bash
+   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 for any hook before writing.
+3. Check for duplicates — if the same hook ID or equivalent tool already exists in the config, say so and stop.
+4. To sanity-check a hook against the repo's actual files before committing to it in config, smoke-test it with `pre-commit try-repo <repo-url> <hook-id> --verbose` (or a local path for hooks under development). This runs the hook without writing anything.
+5. If the hook's source repo already exists in the config, add the hook under that repo block. Otherwise append a new repo block.
+6. State the proposed addition. Wait for confirmation.
+7. Write. Run `pre-commit validate-config`. If non-zero: show error, fix, re-validate.
+
+### Removing a hook
+
+1. Identify the hook entry and its repo block.
+2. State what will be removed: hook ID, and whether the parent repo block will also be deleted (if it would have zero hooks remaining). Wait for confirmation.
+3. Remove the hook entry. If the repo block now has zero hooks remaining, remove the entire repo block.
+4. Write. Run `pre-commit validate-config`. If non-zero: revert the edit, show the error, and stop — do not leave a broken config (removal edits are not safely auto-fixable, unlike a bad new hook block, which can usually be corrected in place).
+
+### 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
+
+When reading the config, for each repo listed in `references/hooks-by-language.md`, compare its `rev` in the user's config against the rev in that file. Flag any mismatch as potentially outdated and tell the user to run `pc-run` to autoupdate. Repos not in the reference cannot be checked — skip them silently. Do not modify `rev` values yourself.
+
+The reference table's pins can themselves go stale between updates — treat a mismatch as a prompt to check, not a certainty. `pre-commit autoupdate` (via `pc-run`) is the authoritative source for what the current rev actually is.
+
+## Scope boundary
+
+This skill manages `.pre-commit-config.yaml` only. It does not:
+- Author `.pre-commit-hooks.yaml` (publishing hooks for external consumers)
+- Run `pre-commit install`
+- Execute hooks or run the test suite
+- Bump `rev` values
+
+For those operations, use `pc-run`.

plugins/git/skills/pc-author/references/README.md

@@ -0,0 +1,14 @@
+---
+source_keys:
+  - context7-pre-commit-com
+  - pre-commit-com
+  - context7-pre-commit-hooks
+  - pre-commit-hooks-github
+---
+
+# references/
+
+| File | Purpose |
+|---|---|
+| `hooks-by-language.md` | Hook recommendations by language/context — repo, rev, and rationale for adding hooks |
+| `sources.md` | Provenance: research sources that informed this skill |

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

@@ -0,0 +1,120 @@
+---
+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.
+
+## Universal (recommend for every repo)
+
+| Hook ID | Repo | Rev | Rationale |
+|---------|------|-----|-----------|
+| `end-of-file-fixer` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Ensures files end with a newline — prevents spurious diffs |
+| `trailing-whitespace` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Strips trailing whitespace — prevents invisible diff noise |
+| `check-merge-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches unresolved merge markers before commit |
+| `detect-private-key` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks PEM private key material |
+| `check-added-large-files` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks accidentally committing large binary files |
+| `check-case-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches filenames that would collide on case-insensitive filesystems |
+| `mixed-line-ending` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Normalizes line endings |
+| `no-commit-to-branch` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks direct commits to protected branches — defaults to blocking `main`+`master` with no args; add `args: [--branch, <name>]` only to protect additional branch names |
+
+## Shell (`.sh`)
+
+| Hook ID | Repo | Rev | Rationale |
+|---------|------|-----|-----------|
+| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | **Unverified — not in research corpus, verify upstream before use.** Static analysis for shell scripts; catches common errors |
+
+Recommended args: `args: [--severity=warning]`
+
+## Python (`.py`)
+
+| Hook ID | Repo | Rev | Rationale |
+|---------|------|-----|-----------|
+| `check-ast` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates Python files parse as valid AST |
+| `check-builtin-literals` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Enforces literal syntax for `dict()`, `list()` |
+
+For formatting: check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them.
+
+## JSON (`.json`)
+
+| Hook ID | Repo | Rev | Rationale |
+|---------|------|-----|-----------|
+| `check-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates JSON parses correctly |
+| `pretty-format-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Auto-formats JSON (fixer — warns user to re-stage after commit) |
+
+## YAML (`.yaml`, `.yml`)
+
+| Hook ID | Repo | Rev | Rationale |
+|---------|------|-----|-----------|
+| `check-yaml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates YAML parses correctly |
+
+For Kubernetes/Helm YAML with custom tags, add `args: ['--unsafe']` and `exclude: ^helm/templates/`.
+
+## TOML (`.toml`)
+
+| Hook ID | Repo | Rev | Rationale |
+|---------|------|-----|-----------|
+| `check-toml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates TOML parses correctly |
+
+## Secrets / security
+
+| Hook ID | Repo | Rev | Rationale |
+|---------|------|-----|-----------|
+| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.30.1` | **Unverified — not in research corpus, verify upstream before use.** Scans for secrets and high-entropy strings |
+
+## Commit message
+
+| Hook ID | Repo | Rev | Stage | Rationale |
+|---------|------|-----|-------|-----------|
+| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | `commit-msg` | Enforces Conventional Commits format |
+
+When adding commit-msg hooks, 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 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 `pc-author`'s "Rev staleness" check treats this table 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 this table.

plugins/git/skills/pc-author/references/sources.md

@@ -0,0 +1,33 @@
+# 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/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/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`

plugins/git/skills/pc-run/README.md

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

plugins/git/skills/pc-run/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: pc-run
+description: >
+  Use when the user wants to run pre-commit hooks, install git hooks, update
+  hook versions, or maintain the pre-commit cache. Triggers on: "run
+  pre-commit", "run all hooks", "check everything passes", "install hooks",
+  "wire hooks into git", "update hook versions", "autoupdate", "bump revs",
+  "clean the cache", "rebuild environments", "gc", "why is my hook failing",
+  "hooks aren't running". Do not use for creating or editing
+  `.pre-commit-config.yaml` — use `pc-author` for that.
+
+compatibility: Requires pre-commit installed and available on PATH.
+
+metadata:
+  category: devtools
+  source_keys:
+    - context7-pre-commit-com
+    - pre-commit-com
+
+allowed-tools: Bash Read
+---
+
+## Gotchas
+
+- Hooks not running on `git commit` almost always means `pre-commit install` was never run in this clone. Git hooks are per-clone — they are not committed to the repo.
+- When a hook modifies files (e.g. `trailing-whitespace`, `end-of-file-fixer`), the commit is blocked intentionally — the staged version is stale. The fix is `git add -u && git commit`. Do NOT call `pre-commit install -f` here; that is for overwriting existing hooks, not re-staging.
+- `pre-commit autoupdate` modifies `.pre-commit-config.yaml` in-place. Re-read the file after calling it to show the user the updated `rev` values.
+- The `SKIP` env var requires exact hook `id` values, comma-separated, no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after the comma silently skips nothing.
+- Never use `git commit --no-verify` (or `-n`) to bypass a failing hook. Hooks are the automated QA gate; bypassing them breaks the pipeline. Diagnose and fix the failure instead — see the hook-specific guidance below and in `references/failure-patterns.md`.
+- A stages mismatch — hook stage not installed — means the hook was added to the config but `pre-commit install` was not re-run with the correct `-t` flags. Hooks in stages not listed under `default_install_hook_types` will never fire.
+
+## Route
+
+Determine intent from the user's request, then execute the matching operation:
+
+| 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` — see Install |
+| "pre-create environments", "install-hooks", "warm cache" | `pre-commit install-hooks` — see Install |
+| "remove hooks", "uninstall", "tear down pre-commit" | `pre-commit uninstall` |
+| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` |
+| "gc", "garbage collect" | `pre-commit gc` |
+| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — see Clean |
+
+If the intent is ambiguous, default to `pre-commit run --all-files`.
+
+## Run
+
+Default: `pre-commit run --all-files`. Never silently run staged-only.
+
+```bash
+pre-commit run --all-files
+```
+
+**When hooks fail**, read the output and:
+1. Identify which hook failed and the specific cause. Be concrete: "gitleaks blocked `config.json` (high-entropy string on line 12)", not just "gitleaks failed".
+2. Suggest a concrete next step. Common patterns are in `references/failure-patterns.md`.
+3. Do NOT auto-fix code files. Do NOT modify `.pre-commit-config.yaml`. Those are the user's or `pc-author`'s responsibility.
+
+If the user asks to run only staged files: `pre-commit run` (no `--all-files`).
+If the user names a specific hook: `pre-commit run <hook-id>`.
+
+## Install
+
+Only run when the user explicitly asks to install or set up hooks.
+
+Before running, check for existing hook files:
+
+```bash
+ls .git/hooks/
+```
+
+If any hook files exist (e.g. a hand-written `pre-commit`), `pre-commit install` does NOT refuse or error — it defaults to migration mode, which runs the existing hook and pre-commit's hooks both. Only `-f` replaces the existing hook file outright, and that replacement is not reversible via `pre-commit uninstall` — uninstall only removes pre-commit from `.git/hooks/`, it does not restore whatever hand-written hook `-f` overwrote. If files are present, tell the user: "Existing hook files found at `.git/hooks/<names>`. Plain `pre-commit install` will run both; `pre-commit install -f` will overwrite them permanently instead. Proceed with plain install, or overwrite?" Wait for confirmation before using `-f`.
+
+```bash
+pre-commit install
+```
+
+Re-run with `-t` flags when `default_install_hook_types` was changed or when hooks in non-default stages aren't firing:
+
+```bash
+pre-commit install -t pre-commit -t pre-push -t commit-msg
+```
+
+To pre-create all hook environments without running hooks (useful for CI warm-up or first-time setup):
+
+```bash
+pre-commit install-hooks
+```
+
+To remove pre-commit from `.git/hooks/` entirely:
+
+```bash
+pre-commit uninstall
+```
+
+## Autoupdate
+
+```bash
+pre-commit autoupdate
+```
+
+After it completes, read `.pre-commit-config.yaml` and report which `rev` values changed. If the user wants to pin to exact SHAs (for reproducibility): `pre-commit autoupdate --freeze`.
+
+## Clean and GC
+
+**`gc`** — removes only unused cached environments. Safe to run at any time:
+```bash
+pre-commit gc
+```
+
+**`clean`** — wipes the entire cache at `~/.cache/pre-commit`. All hook environments will be re-downloaded on next run. Require explicit confirmation before running:
+
+> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
+
+Wait for the user to say yes before executing:
+
+```bash
+pre-commit clean
+```

plugins/git/skills/pc-run/references/README.md

@@ -0,0 +1,14 @@
+---
+source_keys:
+  - context7-pre-commit-com
+  - pre-commit-com
+  - context7-pre-commit-hooks
+  - pre-commit-hooks-github
+---
+
+# references/
+
+| File | Purpose |
+|---|---|
+| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when hooks fail |
+| `sources.md` | Provenance: research sources that informed this skill |

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

@@ -0,0 +1,130 @@
+---
+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
+git add -u
+git commit -m "same message"
+```
+
+## 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. The most common fixes:
+- SC2086 (unquoted variable): wrap in double quotes.
+- SC2046 (unquoted command substitution): wrap in double quotes.
+- SC2181 (check exit code of `$?`): use `if command; then` directly.
+
+## `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.
+
+## SSH cloning fails in CI
+
+Cause: The CI environment lacks SSH credentials to clone hook repos over SSH.
+
+Fix: Export `SSH_AUTH_SOCK` in the CI environment, or switch hook repo URLs to HTTPS.
+
+## HTTP proxy needed
+
+Cause: The CI/sandbox network requires a proxy to reach hook repos.
+
+Fix:
+```bash
+export http_proxy=http://proxy.example.com:3128
+export https_proxy=http://proxy.example.com:3128
+export no_proxy=localhost,127.0.0.1
+```
+
+## `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:
+```bash
+pre-commit clean          # wipe all environments
+pre-commit install-hooks  # rebuild everything
+```
+
+Or less destructively:
+```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
+- `repo: local` hook missing `language` or `entry`
+- Indentation error (valid YAML but invalid pre-commit schema)

plugins/git/skills/pc-run/references/sources.md

@@ -0,0 +1,33 @@
+# 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/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/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`

plugins/gitea/agents/gitea-orchestrate.agent.md

@@ -0,0 +1,93 @@
+---
+name: gitea-orchestrate
+
+description: Orchestrates Gitea operations for other agents. Invoke when a caller needs a multi-step or destructive Gitea operation (merge a PR, delete a branch/release/tag/label/milestone, delete a file) coordinated across domain skills with safety gates, session context, and structured results.
+
+source_keys:
+  - gitea-mcp-repo
+  - gitea-mcp-slim-go
+  - context7-websites-gitea
+  - context7-gitea-tea-cli
+
+---
+
+You are the orchestrator for the gitea plugin — a composable workflow dispatcher designed for other agents to invoke multi-step Gitea operations reliably. Your one job is routing and safety-gating: you do not call `mcp__gitea__*` tools yourself, you delegate to domain skills and enforce confirmation on destructive operations.
+
+You resolve `owner`/`repo` once per session (via `git remote -v` on `origin`) and carry that forward as session context to every domain skill you dispatch to, rather than making each skill re-resolve it.
+
+**Scope:** this orchestrator routes Gitea-object operations across the six domain skills only: `gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-branches`, `gitea-files`, `gitea-releases`. `gitea-workflow` is also not routed here, but for a different reason than a missing domain: it is a human-facing conversational wrapper that gives status check-ins and resolves ambiguous bare numbers ("what's going on with #42") by reasoning about phrasing and context, and it composes the same six domain skills directly rather than calling this orchestrator. It is not a peer to invoke instead of this dispatcher — agent callers route Gitea-object operations here directly with an explicit `operation` field; direct human users to `gitea-workflow` when they want guided, conversational help. Never invoke `gitea-workflow` as an agent caller — resolve ambiguous issue/PR numbers yourself (see Number resolution below) instead of relying on its conversational disambiguation.
+
+## Hard rules
+
+These are non-negotiable regardless of `confirm` or any skill-local override:
+- Never delete the repository's default branch (typically `main` or `master`) — refused outright, independent of `confirm`.
+- `delete_release` takes a numeric `id`; `delete_tag` takes a `tag_name` string. These are asymmetric and never interchangeable — resolve the correct identifier via `list_releases`/`get_release` before calling either, and never guess one from the other.
+- Deleting a release does not delete its tag, and vice versa — if the caller's intent is to remove both, dispatch both operations explicitly rather than assuming one implies the other.
+- A 404 from any domain skill does not necessarily mean the target doesn't exist — Gitea hides permission errors as not-found. Surface this ambiguity in the error `code` (`not_found_or_forbidden`) rather than reporting a hard "does not exist."
+- Label and milestone IDs must be resolved via `gitea-labels-milestones` before being applied to an issue or PR — never pass a label/milestone name directly to `gitea-issues`/`gitea-prs`, they require numeric IDs.
+- Issues and PRs share one number space. Before dispatching an operation keyed on a bare number, resolve whether it's an issue or a PR yourself (see Number resolution) — never infer the domain from operation phrasing alone.
+- `list_releases`/`list_tags` default to `per_page: 20` (other domains default to 30) with no server-side auto-pagination — when a caller needs a complete result set, loop `page` upward until a page returns fewer than `per_page` results before returning.
+- Never commit secrets, credentials, or environment-specific config into any file written via `gitea-files`.
+
+### Number resolution
+
+When an operation targets a bare issue/PR number and the caller hasn't specified which domain it is:
+1. Dispatch to `gitea-issues` with `issue_read method: "get"` on that number.
+2. Check the response's `is_pull` field: `true` → re-dispatch to `gitea-prs` for the actual operation; `false`/absent → it's an issue, proceed with `gitea-issues`.
+3. Cache the resolution in session context for the remainder of the request so repeated references to the same number don't re-resolve.
+4. If the resolution call 404s, do not conclude the number doesn't exist — return `not_found_or_forbidden` and suggest verifying token scope (`write:issue`).
+
+Sub-skills carry their own local copies of relevant gotchas 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: if the operation is destructive (delete-branch, delete-release, delete-tag, delete-label, delete-milestone, delete-file, merge-pr) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; deleting the default branch is refused outright regardless of `confirm`
+3. Route to the appropriate domain skill: `gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-branches`, `gitea-files`, `gitea-releases`
+4. Manage session context: resolve and carry forward `owner`/`repo` and any cached number-space resolutions, passing them explicitly to each skill
+5. Handle error recovery: for recoverable failures (rate limiting, transient 5xx, pagination gaps) retry or complete the operation; for ambiguous 404s, attempt the permission-vs-not-found disambiguation before failing
+6. Aggregate results and return structured JSON output suitable for agent chaining
+
+## Inputs
+
+- **operation:** string, one of:
+  - issues: list-issues, get-issue, create-issue, update-issue, comment-issue, search-issues
+  - labels/milestones: list-labels, create-label, update-label, delete-label, list-milestones, create-milestone, update-milestone, close-milestone, delete-milestone, resolve-labels
+  - prs: list-prs, get-pr, create-pr, update-pr, close-pr, reopen-pr, merge-pr, review-pr
+  - branches/commits: list-branches, create-branch, delete-branch, list-commits, get-commit
+  - files: get-file, get-dir, get-tree, write-file, delete-file
+  - releases/tags: list-releases, get-release, create-release, delete-release, list-tags, create-tag, delete-tag
+- **parameters:** object, operation-specific arguments (issue/PR number, title, body, label names, tag name, file path, etc.)
+- **context:** object (optional), session state to carry forward (`owner`, `repo`, cached number-space resolutions)
+- **confirm:** boolean (optional), explicit confirmation for destructive operations (required if not set for delete-branch, delete-release, delete-tag, delete-label, delete-milestone, delete-file, merge-pr)
+
+## Process
+
+1. Validate the request structure and check if `operation` is known
+2. Check the request against the Hard rules above (default-branch deletion, release/tag id-vs-name asymmetry, label/milestone ID resolution, number-space ambiguity, pagination) — refuse outright on violation, independent of `confirm`
+3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error
+4. Resolve `owner`/`repo` via `git remote -v` on `origin` if not already present in `context`, and reuse the resolution for the remainder of the request
+5. If the operation targets a bare number and the domain isn't specified, run Number resolution above before dispatch
+6. Invoke the appropriate domain skill via `Skill` with the operation, parameters, and resolved context (`owner`, `repo`)
+7. Catch and handle Gitea errors: disambiguate 404s (not-found vs. permission-hidden), retry transient failures, loop pagination for `list_releases`/`list_tags` until exhausted
+8. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions
+9. Aggregate all outputs and return as structured JSON
+
+## Output
+
+```json
+{
+  "status": "success" | "error",
+  "operation": "<operation_name>",
+  "result": {
+    "output": "<domain skill output or result>",
+    "context": { "owner": "...", "repo": "...", "resolved_number_type": "issue" | "pull" | null },
+    "applied_config": { "confirm_required": true | false }
+  },
+  "error": {
+    "message": "<human-readable error>",
+    "code": "<error type: not_found_or_forbidden | conflict | auth_failure | invalid_state | pagination_incomplete>",
+    "recovery_attempted": true | false,
+    "suggestions": ["<suggestion1>", "<suggestion2>"]
+  }
+}
+```

plugins/gitea/plugin.json

@@ -1,19 +0,0 @@
-{
-  "author": {
-    "email": "defame1297@rkdr.net",
-    "name": "Defame1297",
-    "url": "https://git.dev.rkdr.net/Defame1297/"
-  },
-  "description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.",
-  "keywords": [
-    "gitea",
-    "issues",
-    "prs",
-    "milestones",
-    "releases",
-    "branches"
-  ],
-  "license": "MIT",
-  "name": "gitea",
-  "version": "1.3.3"
-}

plugins/gitea/skills/gitea-branches/README.md

@@ -0,0 +1,37 @@
+# gitea-branches
+
+Manage Gitea repository branches and inspect commit history via the Gitea MCP server.
+
+## What it does
+
+This skill handles branch lifecycle operations (list, create, delete) and read-only commit
+history (list commits, get a single commit's full detail) against a Gitea repository. It resolves
+`owner`/`repo` from the git remote, dispatches to the right MCP tool, and applies safety and
+pagination conventions specific to Gitea's API (e.g. refusing to delete a protected branch without
+explicit confirmation, and treating unexpected 404s as possible masked 403s).
+
+## Before you start
+
+Requires a Gitea MCP server configured with a token that has `write:repository` scope. This is
+confirmed for `list_branches`, `create_branch`, and `delete_branch` (Gitea gates reads behind write
+scope for repo-scoped operations); `list_commits` and `get_commit` are inferred to need the same
+scope by analogy, not explicitly confirmed — see `references/commits.md`. Requires a git remote
+named `origin` pointing at the Gitea instance.
+
+## Usage
+
+```
+/gitea-branches
+```
+
+Describe your task: list/create/delete a branch, or list/inspect commits. See `SKILL.md`'s
+dispatch table for the full set of recognized invocations.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents — dispatch table, gotchas |
+| `references/branches.md` | Verified call signatures and mechanics for list/create/delete branch |
+| `references/commits.md` | Verified call signatures and mechanics for list/get commit |
+| `references/sources.md` | Research sources backing the branch/commit guidance |

plugins/gitea/skills/gitea-branches/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: gitea-branches
+
+description: >
+  Use when managing Gitea repository branches — listing, creating, or deleting
+  branches — or inspecting commit history within a Gitea repo: listing commits
+  (optionally filtered by branch or file path) or getting full detail for a
+  single commit by SHA. Triggers on "list branches", "create a branch",
+  "delete a branch", "what commits are on this branch", "show commit <sha>",
+  "what changed in that commit" — even if the user doesn't say "Gitea"
+  explicitly, as long as the repo's remote is a Gitea instance. Do not use for
+  local git branch/commit operations on your working copy (use git-branches or
+  git-history) or for PR-side branch references like cross-repo fork PR heads
+  (use gitea-prs).
+
+compatibility: Requires Gitea MCP server configured with a token with write:repository scope; this is confirmed to gate list_branches, create_branch, and delete_branch (Gitea gates reads behind write scope for repo-scoped operations), and is inferred by analogy (not explicitly confirmed by source docs) to also gate list_commits and get_commit. Requires git remote "origin" pointing to the Gitea instance.
+
+metadata:
+  category: integration
+  version: "0.1.1"
+  source_keys:
+    - gitea-mcp-repo
+    - gitea-mcp-slim-go
+    - context7-websites-gitea
+
+allowed-tools: Bash mcp__gitea__list_branches mcp__gitea__create_branch mcp__gitea__delete_branch mcp__gitea__list_commits mcp__gitea__get_commit
+---
+
+## Gotchas
+
+- **Never delete a protected branch (`main`/`master` by name, or `protected: true` from `list_branches`) without explicit confirmation.** `delete_branch` is a direct API call, not a local `git push` — there is no client-side force-push guard protecting it. Name-matching `main`/`master` is a convenient default but not authoritative — a repo can protect a differently-named default branch. When in doubt, call `list_branches` first and check `protected` on the target; treat deletion of any protected branch as a hard refusal unless the user explicitly confirms in the conversation.
+- **404 may actually mean 403.** Gitea hides permission errors as not-found to avoid leaking resource existence. If any of these five tools returns 404 unexpectedly, check token scope (see `references/branches.md` / `references/commits.md`) before concluding the branch or commit doesn't exist.
+- **Pagination is manual.** `list_branches` and `list_commits` return one page at a time — no auto-pagination in the MCP layer. When you need a complete list, iterate `page: 1, 2, ...` until the returned count is less than `per_page`.
+- **Owner/repo always come from the git remote, never from `get_me`.** Resolve them via `git remote get-url origin` (Step 1 below). `get_me`/`list_my_repos` are blocked under the token scopes this skill assumes.
+- **`create_branch`'s source is `old_branch`, not "wherever gitea-mcp feels like."** Omitting `old_branch` forks from the repo's server-side default branch — not necessarily the branch you're currently working on locally. If you want to branch from your current checkout, pass `old_branch` explicitly.
+
+## Step 1 — Resolve owner and repo
+
+Before any tool call, extract `owner` and `repo` from the git remote:
+
+```bash
+git remote get-url origin
+```
+
+If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
+
+## Step 2 — Dispatch
+
+| Invocation | Action |
+|---|---|
+| `/gitea-branches` or `/gitea-branches list` | List branches |
+| `/gitea-branches create <name> [from <base>]` | Create branch |
+| `/gitea-branches delete <name>` | Delete branch |
+| `/gitea-branches commits [on <branch>] [touching <path>]` | List commit history |
+| `/gitea-branches commit <sha>` | Get full detail for one commit |
+
+For branch operations (list/create/delete), read `references/branches.md`.
+For commit operations (list/get), read `references/commits.md`.
+
+## Step 3 — Report
+
+For reads: display branches as name + protected flag; display commits as SHA (short), message summary, author, date.
+
+For writes (create/delete): confirm the action taken, the branch name, and (for create) the base it forked from.
+
+For errors: surface the HTTP code and message. If a 404 is unexpected, re-check token scope per the Gotchas above before reporting "not found" to the user.

plugins/gitea/skills/gitea-branches/references/branches.md

@@ -0,0 +1,81 @@
+---
+topic: branches
+source_keys:
+  - gitea-mcp-repo
+  - gitea-mcp-slim-go
+---
+
+# Branch operations
+
+Call signatures below were verified live against the deployed `gitea-mcp` server via `ToolSearch`
+at authoring time, not copied from research docs — this is deliberate: research docs are generated
+from source code at a point in time and can drift from the server actually deployed. Re-verify
+against the live schema if these tools appear to behave differently than documented here.
+
+## `list_branches`
+
+**Parameters:**
+- `owner` (string, required)
+- `repo` (string, required)
+- `page` (number, optional, default: `1`)
+- `per_page` (number, optional, default: `30`)
+
+**Call:**
+```
+list_branches owner: <owner> repo: <repo>
+```
+
+**Response:** one object per branch: `name`, `protected` (bool), `commit_sha` (present when the
+underlying commit data is available).
+
+Paginate if you need the full list (see Gotchas in SKILL.md) — iterate `page` until the returned
+count is less than `per_page`.
+
+## `create_branch`
+
+**Parameters:**
+- `owner` (string, required)
+- `repo` (string, required)
+- `branch` (string, required) — new branch name
+- `old_branch` (string, optional) — source branch; if omitted, defaults to the repo's default
+  branch server-side (not necessarily your current local checkout)
+
+**Call:**
+```
+create_branch owner: <owner> repo: <repo> branch: <new-name> old_branch: <source-branch>
+```
+
+Default dispatch: if the user gives a base ("branch off of X", "from X"), pass it as `old_branch`.
+If they don't specify a base and you're mid-task on a local branch, pass your current branch
+(`git branch --show-current`) as `old_branch` so the new branch forks from where you're actually
+working, rather than silently falling back to the repo default. If neither applies (e.g. a fresh
+top-level request with no working branch context), omit `old_branch` and let it default server-side.
+
+A branch name collision returns `409 Conflict`.
+
+## `delete_branch`
+
+**Parameters:**
+- `owner` (string, required)
+- `repo` (string, required)
+- `branch` (string, required)
+
+**Call:**
+```
+delete_branch owner: <owner> repo: <repo> branch: <name>
+```
+
+Before calling this, see the hard-refusal Gotcha in SKILL.md. If the target branch's name isn't
+obviously a scratch/feature branch, call `list_branches` first and check `protected` on the
+matching entry — name-matching `main`/`master` alone isn't authoritative, since a repo can protect
+a differently-named default branch. Confirm explicitly with the user before deleting anything
+protected, every time, regardless of how the request is phrased.
+
+## Token scope
+
+All three — `list_branches`, `create_branch`, `delete_branch` — require `write:repository`. Gitea
+gates reads behind write scope for repo-scoped operations, so `list_branches` needs the same scope
+as the write operations, not `write:issue` alone. An earlier version of this doc claimed
+`write:issue` alone was sufficient for `list_branches`, based on empirical testing under a token
+that held both `write:issue` and `write:repository` simultaneously — that test didn't isolate the
+variable, so it couldn't actually establish `write:issue` alone as sufficient.

plugins/gitea/skills/gitea-branches/references/commits.md

@@ -0,0 +1,73 @@
+---
+topic: commits
+source_keys:
+  - gitea-mcp-repo
+  - gitea-mcp-slim-go
+---
+
+# Commit operations
+
+Read-only commit history, scoped to a repo (optionally to one branch or one path). Call signatures
+below were verified live against the deployed `gitea-mcp` server via `ToolSearch` at authoring time,
+not copied from research docs, for the same drift-avoidance reason noted in `references/branches.md`.
+
+This domain has no prior skill precedent — it's new coverage added alongside branches because commit
+history is naturally scoped to a branch (a "what happened on this branch" question), not because it
+shares any tool family with branch create/delete.
+
+## `list_commits`
+
+**Parameters:**
+- `owner` (string, required)
+- `repo` (string, required)
+- `sha` (string, optional) — starting SHA or branch name; if omitted, gitea-mcp uses the repo's
+  default branch
+- `path` (string, optional) — restrict results to commits that touched this file/path
+- `page` (number, optional, default: `1`, minimum: `1`)
+- `per_page` (number, optional, default: `30`, minimum: `1`)
+
+**Call:**
+```
+list_commits owner: <owner> repo: <repo> sha: <branch-or-sha> path: <optional-path>
+```
+
+Dispatch defaults:
+- "commits on `<branch>`" → pass `<branch>` as `sha`.
+- "commits touching `<path>`" (no branch mentioned) → pass `path` alone, `sha` omitted (defaults to
+  the repo's default branch).
+- Both given → pass both; the result is history for that path, walked from that branch/SHA.
+- Neither given → omit both; this returns default-branch history, which is a reasonable default for
+  an open-ended "what's the recent history here" question.
+
+**Response:** one object per commit: `sha`, `html_url`, `created`, `message` (when available),
+`author` (`{name, email, date}`, when available).
+
+Paginate per the manual-pagination Gotcha in SKILL.md if you need more than one page of history.
+
+## `get_commit`
+
+**Parameters:**
+- `owner` (string, required)
+- `repo` (string, required)
+- `sha` (string, required)
+
+**Call:**
+```
+get_commit owner: <owner> repo: <repo> sha: <commit-sha>
+```
+
+**Response:** same shape as a `list_commits` entry, but always fully populated (`message` and
+`author` are guaranteed present, not conditional). Use this when the user asks about one specific
+commit by SHA rather than browsing history — `list_commits` entries may omit `message`/`author` in
+edge cases, `get_commit` will not.
+
+## Token scope
+
+Both tools are believed to require `write:repository`, even though they're read-only — inferred by
+analogy with the scope-gating principle in `overview.md` (Gitea gates reads behind write scope for
+repo-scoped operations), not a claim `overview.md` makes for commits by name: its explicit
+`write:repository` enumeration lists PR, branch, file, release, and tag operations, but doesn't
+mention commits. An earlier version of this doc claimed `write:issue` alone worked, based on
+empirical testing under a token that held both `write:issue` and `write:repository`
+simultaneously — that test didn't isolate the variable either. Treat this as unverified until
+tested under a token scoped to `write:issue` only (no `write:repository`).

plugins/gitea/skills/gitea-branches/references/sources.md

@@ -0,0 +1,41 @@
+# Sources
+
+**Note on call signatures:** per `docs/adr/0011-gitea-skill-deep-modules.md`, the tool parameter
+signatures in `references/branches.md` and `references/commits.md` were re-verified live via
+`ToolSearch` against the deployed `gitea-mcp` server at authoring time — they are not copied
+verbatim from `api-reference.md` below. This resolves issue #6 comment #849's root-cause finding
+that a prior skill was authored from API docs that had drifted from the actual MCP tool schema.
+The research docs cited here informed gotchas, response shapes, and workflow context, not the
+parameter lists themselves.
+
+## gitea-mcp-repo
+
+- **URL:** https://gitea.com/gitea/gitea-mcp
+- **Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags. Informed the dispatch table and pagination / 404-may-mean-403 gotchas in SKILL.md, and the list/create/delete branch and list/get commit mechanics (including 409 conflict and default-branch fallback behavior) in references/branches.md and references/commits.md.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
+- **Contributing files:** SKILL.md, references/branches.md, references/commits.md
+- **Status:** `extracted`
+
+## gitea-mcp-slim-go
+
+- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/repo/slim.go
+- **Description:** Slim response shape structs from gitea-mcp source; defines exactly which fields the MCP server returns for branches (name, protected, commit_sha) and commits (sha, html_url, created, message, author), and informed get_commit's always-populated guarantee vs. list_commits' conditional fields.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
+- **Contributing files:** references/branches.md, references/commits.md
+- **Status:** `extracted`
+
+## context7-websites-gitea
+
+- **URL:** context7:/websites/gitea
+- **Description:** Official Gitea docs mirror on Context7 — informed the protected-branch gotcha in SKILL.md (protected branches can block server-side operations regardless of client-side checks; admins aren't exempt by default).
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
+
+## context7-gitea-tea-cli
+
+- **URL:** context7:/git_gitea_com/gitea_tea
+- **Description:** Official `tea` CLI docs on Context7 — practitioner conventions for issues, PRs, and releases (semver tags, draft/prerelease flags). Consulted as part of the shared research pass but its content is scoped to releases/tags, out of scope for branches/commits — no content from it was used in this skill.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
+- **Contributing files:** (none)
+- **Status:** `extracted`

plugins/gitea/skills/gitea-files/README.md

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

plugins/gitea/skills/gitea-files/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: gitea-files
+
+description: >
+  Use when reading or writing individual files or directory trees in a Gitea repository via the
+  Gitea MCP server: reading a file's contents, listing a directory, walking a full repository
+  tree, creating a new file, updating an existing file, or deleting a file. Triggers on "read this
+  file from the repo", "what's in this directory", "show me the repo tree", "create/update a file
+  in Gitea", "commit this file to the branch", "delete this file from the repo" — even when the
+  user doesn't say "Gitea" explicitly, as long as the target is a Gitea-hosted repository. Do not
+  use for local filesystem file operations (use Read/Write/Edit), for branch or commit history
+  (use gitea-branches), or for opening a pull request around a file change (use gitea-prs after
+  the file write completes here).
+
+compatibility: Requires the Gitea MCP server configured with a token scoped to at least
+  write:repository. Tested with a token holding write:issue + write:repository; write:issue
+  is not actually required for any of this domain's five tools.
+
+metadata:
+  category: gitea
+  source_keys:
+    - gitea-mcp-repo
+    - gitea-mcp-slim-go
+    - context7-websites-gitea
+
+allowed-tools: mcp__gitea__get_file_contents mcp__gitea__get_dir_contents mcp__gitea__get_repository_tree mcp__gitea__create_or_update_file mcp__gitea__delete_file
+---
+
+## Gotchas
+
+- **A 404 from any read call may actually be a 403 in disguise.** `get_file_contents`, `get_dir_contents`, and `get_repository_tree` all gate on `write:repository` scope, not just read access — some Gitea endpoints return 404 instead of 403 when the token's scope is insufficient, to avoid leaking whether the resource exists. If a read fails with 404 on a path you're confident is correct, check the token's configured scopes before concluding the file or directory doesn't exist.
+- **SHA is the concurrency token for every write — and it lives at the top level of `get_file_contents`'s response, not nested under `content`.** `create_or_update_file` without `sha` is always treated as a *create*: if the path already exists, Gitea returns HTTP 409. `delete_file` has no optional path at all — omitting `sha` returns HTTP 422. The safe sequence for any update or delete is always: call `get_file_contents` first, read the top-level `sha` field, then pass that exact value to the write call. Never guess or reuse a stale SHA — a mismatched SHA is rejected the same as a missing one.
+- **A write can also fail because the branch requires signed commits — a separate failure mode from a bad SHA.** `create_or_update_file` and `delete_file` create commits server-side via a bare API token call with no 2FA/PGP context. If the target branch's protection rule requires signed commits, Gitea rejects the write outright — surfaced as a generic 403 or 422, not an error naming "signed commit required," and reads against that same branch keep succeeding right up until you try to write. When a write fails without a clean 409 (missing/stale SHA) or 404 (bad path) explanation, check whether the branch's protection rule requires signed commits before assuming the SHA is wrong and retrying.
+- **A large `create_or_update_file` payload can hit a reverse-proxy 413 that has nothing to do with Gitea.** `content` is base64-encoded, which inflates the payload ~33% over the raw file size; a 413 is commonly a reverse-proxy body-size limit in front of the Gitea instance, not a Gitea-side rejection. No amount of retrying, or changing the SHA, path, or branch, will fix it — it needs the proxy's config raised, which is outside this skill's or the calling agent's control. Surface that distinction to the user instead of retrying the same call.
+- **`get_dir_contents` and `get_repository_tree` are not SHA sources for a specific file's write.** `get_dir_contents` entries carry no `sha` at all. `get_repository_tree` entries do carry a `sha` (a blob/tree hash), but fetching it means an extra round trip with no content — `get_file_contents` is the canonical path since it returns the decoded content and the write-ready `sha` in one call.
+- **`owner` and `repo` are always caller-supplied inputs, never resolved here.** This skill doesn't infer them from a git remote. If invoked directly by a human, ask for them if not stated. If invoked by `gitea-workflow` or an orchestrating agent, expect them to already be resolved and passed in.
+- **Direct commits to a branch are a first-class action, not a workaround.** Gitea's own web UI defaults to editing files directly against a branch — `create_or_update_file`/`delete_file` used that way is normal, not an API escape hatch to avoid. The SHA-currency requirement above is the actual risk to manage, not the act of committing directly.
+- **`ref` (reads) vs. `branch_name` (writes) are different parameters for the same concept.** `get_file_contents`, `get_dir_contents`, and `get_repository_tree` (as `tree_sha`) all accept a branch name, tag, or commit SHA to select what to read. `create_or_update_file` and `delete_file` instead take `branch_name` — the branch the commit lands on. Don't conflate the two when chaining a read into a write.
+- **Content is base64.** `create_or_update_file`'s `content` parameter is base64-encoded file content, not raw text — encode before calling. `get_file_contents`'s response content is likewise base64-encoded (decode after reading), unless `withLines: true` is passed for a numbered-line view.
+
+## Reading
+
+- **Single file:** `get_file_contents(owner, repo, ref, path)`. Pass `withLines: true` only when you need line numbers for referencing specific lines (e.g. quoting a snippet back to the user); omit it for a normal content fetch.
+- **One directory level:** `get_dir_contents(owner, repo, ref, path)` — returns immediate entries only (name, path, type, size), no recursion, no SHA, no content.
+- **Whole tree:** `get_repository_tree(owner, repo, tree_sha, recursive)` — `tree_sha` accepts a SHA, branch, or tag name despite the name. Set `recursive: true` to walk subdirectories in one call. Response includes `truncated: true` when a page doesn't hold every entry — page through with `page`/`per_page` (default `page: 1`, `per_page: 30`) until you get fewer results than `per_page`.
+
+## Writing
+
+- **Creating a new file:** call `create_or_update_file(owner, repo, path, content, message, branch_name)` with `sha` omitted entirely.
+- **Updating an existing file:** call `get_file_contents(owner, repo, ref: branch_name, path)` first, take the top-level `sha`, then call `create_or_update_file(..., sha: <that value>)`.
+- **Deleting a file:** call `get_file_contents` first the same way, then `delete_file(owner, repo, path, message, branch_name, sha: <that value>)` — `sha` is required, no create-style fallback exists.
+- **Creating a new branch as part of the write:** pass `new_branch_name` on `create_or_update_file` to branch off before the commit lands, instead of calling a separate branch-creation step.
+
+If the change needs review before merging, or targets a protected branch, hand off to `gitea-prs` after the write lands here to open the pull request — this skill's scope ends at the commit.
+
+If you need the full multi-call sequence rather than the single-call summary above — e.g. branching off as part of a file push ahead of opening a PR, or recovering a SHA you didn't capture earlier — read `references/examples.md`.