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

Compare commits

base: Defame1297:feat/66-wire-gitea-mcp-config
Branches Tags
Defame1297:main Defame1297:docs/onedev-migration-plan Defame1297:feat/66-wire-gitea-mcp-config
Defame1297:v2.0.1 Defame1297:v2.0.0 Defame1297:v1.0.0
...
compare: Defame1297:4aab9d327c4457bed53b24144483473aacd068da
Branches Tags
Defame1297:main Defame1297:docs/onedev-migration-plan Defame1297:feat/66-wire-gitea-mcp-config
Defame1297:v2.0.1 Defame1297:v2.0.0 Defame1297:v1.0.0

37 Commits
feat/66-wi ... 4aab9d327c

Author SHA1 Message Date
Defame1297
4aab9d327c refactor(kyberforge): retrofit forge to the ADR-0020 contract 
Description 648 -> 387 chars, body 1093 -> 541 words. This was the last
body FAIL in the 39-skill corpus.

The body was not trimmed to fit. forge routes four artifact types that a
single invocation classifies between, so the contract requires a dispatch
table plus the gates common to every route, with each route self-contained
in references/. Adds references/author-routes.md (skill and agent),
references/apm-routes.md (plugin and marketplace entry) and
references/version-bump.md. Skill and agent share one file: they differ on
one axis only, which audit skill verifies the result.

Fixes three defects the first pass introduced or relocated:

- references/apm-routes.md claimed `apm audit` "already runs inside
  apm-workflow's own flow" and told the agent to confirm it ran clean.
  apm-workflow dispatches audit as its own row; the configure and
  marketplace rows never reach it. That was the only completion check
  these routes had, and it could never be satisfied. Replaced with a
  manual read-back the agent performs itself.
- "Read only the reference file" forbade the multi-artifact case the same
  body documents two lines later, and ADR-0011 records eight artifacts
  authored in one pass.
- The announce gate became a closing gate, reachable only after the
  invocation it was meant to precede. Moved to the end of Step 2.

Also restores the artifact enumeration to the plugin row, normalises to
bare unnamespaced skill names per AGENTS.md, adds a dispatch fallback for
artifacts matching no row, and corrects three provenance entries -- one
asserted a contribution that did not happen.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
 2026-08-30 16:31:23 +00:00
Defame1297
1e4aab53a7 refactor(kyberforge): retrofit apm-workflow to the ADR-0020 contract 
Description 817 -> 324 chars, body 421 -> 237 words, Gotchas 6 -> 2.

The five capability clauses, the second trigger register and the prose
boundary form go; one trigger clause, the indirect trigger and one
boundary clause remain. Four of six Gotchas move into the flow file that
every branch needing them already loads.

Two stay in the always-loaded body because a dispatch body must carry the
gates common to every branch, not just the dispatch table: the MCP secret
indirection rule, and the `apm experimental enable registries`
precondition. The first pass moved registries into references/configure.md
alone, which stranded it -- references/compile.md documents publishing to a
registry and references/install.md resolves dependencies through one, and
neither points at configure.md. Declaring a registry without the
precondition is a silent no-op, so the failure had no signal.

Also drops an unsourced claim the compression pass introduced (that apm
checks `type:` going forward -- no source supports it), corrects the MCP
rationale to install *or* runtime per configuration.md:98, and repoints
two apm-orchestrate back-references that pointed at body Gotchas which had
moved.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
 2026-08-30 16:31:11 +00:00
Defame1297
915eb09ae2 docs(scripts): record that the bare-arrow carve-out is now unexercised 
The comment justified the ADR-0020 compressed-form gate with diagnose's
process chain 'fix -> regression-test', which without the gate read as a
route to a non-existent regression-test skill. Issue #99 cut that chain
when it retrofitted the description, so the gate now produces an
identical verdict corpus-wide whether it is applied or not.

Keeping the branch. It guards against prose no one has written yet, any
new process chain re-arms it, and the bare-arrow rule it sits on is the
sole extractor for three real targets in kyberforge's audit skills, all
written unbackticked. Unexercised is not the same as unnecessary — the
comment just needed to stop citing evidence that no longer exists.

Refs #99
 2026-08-30 15:51:43 +00:00
Defame1297
d8dfba958c docs(agents): correct the ADR-0020 gate counts after wave 3 
Three skills still exceed a FAIL tier, all in kyberforge, down from ten
descriptions and two bodies. No routing target dangles any more, and the
test suite now pins that set as empty rather than tracking a backlog.

Refs #99
 2026-08-30 15:07:17 +00:00
Defame1297
7e80c09b13 fix(kyberforge): a dispatch table satisfies the reference-wiring rule 
body-discipline.md required every reference load to use the literal
'If X, read references/file.md' form and called anything else a generic
pointer. ADR-0020's own cited dispatch exemplar, apm-workflow, uses a
bare table plus one closing line, so an author could not satisfy both --
and the rule reliably produced duplication in exactly the bodies the
contract exists to keep short.

Resolves #109 with its option 1: a table row already pairs a condition
with a target, so where a body dispatches, the table is the wiring. The
literal form is what a body needs when it loads a reference without a
table.

Two corrections to the issue as filed. There is no Vale conflict --
PaddingPhrase.yml only matches 'see references/ for more info' and never
fired on the exemplar, so this is a one-file prose fix and no rule
changes. And gitea-workflow carried the predicted duplication: a
three-row table restated underneath as three conditionals. Removed, body
227 -> 148 words.

Closes #109
 2026-08-30 15:07:16 +00:00
Defame1297
ff187ef9fc refactor(lint): retrofit vale-run to the ADR-0020 context contract 
Description 654 -> 294 chars, Gotchas 36% -> 19%. Body 698 -> 642 words:
up from the first pass, because a clean-context audit found four defects
whose fixes are net-additive text.

The suppression-markup warning covered only one of the two paths that
write it -- the list is case-based, so a recurring false positive goes
straight to step 3 and never read step 2's warning. Hoisted above both.

The CI-failure trigger, which the description advertises, had no path to
the file holding its answer: the negative diagnosis 'if the alerts are
warnings, Vale is not what failed the build' survived only in
troubleshooting.md, which no CI-entered invocation loads. An agent would
confidently prescribe --no-exit for a failure Vale never caused.

The description had lost every prose-domain word -- no 'prose', no
'linter' -- while vale-config kept all of them, so 'check prose style'
routed to the wrong skill of the pair.

Accepts two soft SUGGESTIONs rather than dropping restored content;
neither fails the gate.

Refs #99
 2026-08-30 15:07:16 +00:00
Defame1297
45cd26045a refactor(lint): retrofit vale-config to the ADR-0020 context contract 
Description 657 -> 244 chars, body 504 -> 342 words, Gotchas 50% -> 24%.
The 50% was the worst ratio in the corpus and a real inverted body, not
the denominator artefact the ratio usually flags: half the body was a
Gotchas section doing duty as reference material.

A clean-context audit caught the split leaving a false statement behind.
Gotcha 1's kernel lost the qualifier that only package styles need
fetching, so it asserted that any style vale sync has not fetched fails
-- contradicting the same file twice, since the built-in Vale style and
any committed custom style are never fetched. An agent adding a custom
style would have added a spurious Packages entry and broken vale sync
outright. The qualifier is restored in the body rather than behind a
fourth reference pointer.

Also corrects the moved fixture's framing, which tabulated a control row
under a heading claiming it came from a multi-line fixture.

Refs #99
 2026-08-30 15:07:15 +00:00
Defame1297
c59e4bf0c5 refactor(core): retrofit provider-adapter-author to the ADR-0020 contract 
Description 833 -> 239 chars, body 370 -> 387 words, Gotchas 41% -> 20%.
The file-type enumeration moves to a new references/provider-matrix.md;
the composition note was already in README.md.

Three defects a clean-context audit found, all fixed:

The 'never edits AGENTS.md' prohibition had become a justification clause
on the false branch of a conditional, so the common path never read a
sentence binding it. That matters because the bundled validator's own
remediation text tells the agent to move content into AGENTS.md, so a
size FAIL actively invited the prohibited edit. Restored as a standing
imperative, plus a counter at the step where the trap fires.

A Gotcha asserted that validate-adapter.sh fails without
--no-import-syntax. The flag is a no-op -- both branches reduce to the
same expression. Reverted to an instruction; the script defect is #115.

The boundary clauses used pronouns to dodge the #110 regex, and 'Not
auditing it' resolved to CLAUDE.md as readily as to AGENTS.md -- routing
'audit my CLAUDE.md' to a skill whose own description declines it.

Refs #99
 2026-08-30 15:06:50 +00:00
Defame1297
f0526b310d refactor(core): retrofit agentsmd-audit to the ADR-0020 context contract 
Description 944 -> 322 chars, Gotchas 36% -> 22%. The composition note
moves to README.md.

Restores the hand-edit trigger, which a clean-context audit found had no
other caller: agentsmd-author owns the post-authoring invocation, but a
hand-edit has no author skill in the loop, so nothing invoked the audit
at all. It survived only in README.md, which neither the router nor the
invoked agent loads. That is the path on which a human pastes a
credential into AGENTS.md.

The first pass dropped it against a measured budget of '~9 spare chars'.
The real cost was ~49, and 250 is the SUGGESTION tier, not a ceiling --
the gate fails at 400. Ships at 322 with one advisory line.

Names the three audit dimensions in the capability clause, recovering
routing for 'does my AGENTS.md leak credentials', and qualifies the
'is this AGENTS.md safe to commit' phrasing, whose pronoun had no
antecedent inside the quoted string.

Refs #99
 2026-08-30 15:06:49 +00:00
Defame1297
e42c055294 refactor(core): retrofit agentsmd-author to the ADR-0020 context contract 
Description 960 -> 244 chars, body 470 -> 452 words, Gotchas 36% -> 22%.
Both composition notes move to README.md, which already carried them.

Four of five Gotchas were paraphrases of the step below them and were
deleted with their force folded back into that step. A clean-context
audit overturned the fifth deletion: the provider-file prohibition was
strictly broader than Step 4, so it was never a paraphrase, and Step 4's
'don't rewrite it yourself' is attached to the if-duplicates branch. With
Write and Edit granted, a provider file that was merely stale had nothing
forbidding an edit. Restored as an unconditional Gotcha, read before any
step writes.

Also restores a concrete indirect trigger. The retrofit had replaced two
with the meta-statement 'even when they don't name the file', which
claims an indirect trigger exists rather than being one -- and users
asking to document a repo for AI tools have no reason to know the
filename.

Refs #99
 2026-08-30 15:06:48 +00:00
Defame1297
00c1e6b305 refactor(bin): retrofit diagnose to the ADR-0020 context contract 
Body 1126 -> 808 words, clearing the FAIL tier, and description 290 ->
220 chars. Phase 1's depth moves to references/feedback-loops.md; the
six-phase spine stays in the body, since a linear procedure is not a
dispatch case.

The description rewrite was not originally in scope, which was an error:
adding a mandatory boundary clause to a 290-char description cannot land
under 400. The dropped capability chain was also inaccurate -- it named
'minimise' as a phase that does not exist while omitting the one phase
the body calls 'This is the skill'.

A clean-context audit found no text lost but three reachability defects,
all fixed: content stranded behind an inverted trigger, Phase 2's
reproduction-rate threshold defined only in a file that path never
loaded, and a script path that did not resolve from the file carrying it.
The two reference files are merged into one, since the split is what
created the first two.

Refs #99
 2026-08-30 15:06:26 +00:00
Defame1297
f03bfa8d24 refactor(bin): retrofit prototype to the ADR-0020 context contract 
Description 426 -> 286 chars, with a boundary clause added. The body was
already compliant at 467 words and is untouched.

A clean-context audit caught the first pass trading away the LOGIC
branch's routing vocabulary for characters it did not need to save: both
'data model' and 'business logic' had gone, though LOGIC.md defines its
own scope with exactly those words. Restored, so 'does this data model
feel right?' routes here again.

Accepts 286 over the 250 target -- the hard tier is 400, and the
alternative was leaving half the dispatch reachable by one phrase.

Leaves LOGIC.md and UI.md at the skill root; moving them into references/
is tracked as #114.

Refs #99
 2026-08-30 15:06:25 +00:00
Defame1297
ee6b04061a refactor(bin): retrofit research to the ADR-0020 context contract 
Description 583 -> 231 chars and body 854 -> 519 words. Deletes the
neuledge-context boundary clause outright: commit 6146120 deleted that
skill and no skill has owned MCP-server installation since. That was the
last dangling routing target in the corpus.

Removes META.md, which file-structure.md:20 forbids at a skill root. Its
when: field duplicated the description and its references: entry pointed
at .agents/skills/context7-mcp/SKILL.md, which does not exist.

Restores two rules a clean-context audit found had lost their force: the
starting-URLs branch in step 3, which the retrofit had reduced to a
condition with no behaviour, and the references/file-format.md pointer at
step 6. The second matters downstream -- validate-provenance.sh parses
sources.md with anchored regexes and check 8 short-circuits silently when
the Status field is absent, so a sources.md written from step 6 alone
broke the provenance chain with no error anywhere.

Rewrites steps 4-5 as serial WebFetch reads. They mandated spawning
subagents that allowed-tools never granted; no tool was added because the
name differs across the three compile targets. Tracked as #116.

Updates the two test pins and the eval case that asserted the dead route.

Refs #99
 2026-08-30 15:06:23 +00:00
Defame1297
a2ebdafc5e fix(skill-audit): pin the stale worked example and state its reachability precondition 
The body-discipline rubric cited git-commits as it stood before the ADR-0020
retrofit -- twelve Gotchas, 387/1102 words, line numbers :31-:52. Every
figure was correct for that version and none survives in the current file,
so the example is now anchored to commit 5e23250 and marked not to be
refreshed against HEAD.

More than staleness: row four called the secrets Gotcha a paraphrase FAIL
because step 2 restated it. Wave 2 followed that reasoning, deleted the
always-loaded copy, and left the amend branch able to commit a credential
unchecked -- dispatch loads exactly one flow file. The paraphrase rule now
carries its missing precondition: delete a restating Gotcha only when the
surviving copy is reachable from every branch that needs it, and relocate
a multi-branch safety gate into the body rather than dropping it.
 2026-08-30 13:22:55 +00:00
Defame1297
afbeaff56b docs(agents): correct the ADR-0020 gate counts after the git retrofit 
Descriptions over the FAIL tier 19 -> 10, bodies 7 -> 2. This line is
always-loaded context, so a stale count misleads every session.
 2026-08-30 13:14:00 +00:00
Defame1297
3cd3f33706 refactor(pc-author): retrofit to the ADR-0020 context contract 
Description 475 -> 213 chars, body 680 -> 212 words. Create and modify
become self-contained flow files behind a dispatch table, since the two are
mutually exclusive on whether the config already exists.

Passed its clean-context audit with no must-fix findings.
 2026-08-30 13:10:53 +00:00
Defame1297
15ff7417b9 refactor(pc-run): retrofit to the ADR-0020 context contract 
Description 477 -> 211 chars, body 736 -> 367 words. Install, autoupdate,
and clean become flow files behind the Route table.

The audit found no route for 'hooks aren't running': the only pointer to
failure-patterns.md sat inside the failure path, but when hooks never fire
the manual run succeeds, so the request fell to the ambiguity default and
was masked. Restores the disclosure that install -f is not reversible by
uninstall.
 2026-08-30 13:10:53 +00:00
Defame1297
7cb8e95379 refactor(git-history): retrofit to the ADR-0020 context contract 
Description 450 -> 266 chars, body 1044 -> 462 words. The bisect procedure
moves to references/bisect.md.

The boundary clause read 'not writing or rewriting commits', which
disclaimed the cherry-pick and revert this skill's own Step 3 executes; it
now excludes authoring and rebasing only. Adds 'backport' so cherry-pick is
reachable by natural language at all, accepting 266 chars against a 250
soft target and a 400 ceiling.
 2026-08-30 13:10:53 +00:00
Defame1297
261e5b5491 refactor(git-submodules): retrofit to the ADR-0020 context contract 
Description 480 -> 248 chars, body 1011 -> 347 words. The single
submodules.md splits into setup-and-update, urls-and-config, and removal.

Restores three regressions the first pass introduced: 'repointing' as the
trigger for the URL branch, which had none while the boundary clause
steered those queries to git-remotes; clone and absorbgitdirs in the output
enum, which dispatch still routed to; and status --cached, the flag that
makes the pre-commit pointer gate verifiable.
 2026-08-30 13:10:53 +00:00
Defame1297
3c74beb280 refactor(git-workflow): retrofit to the ADR-0020 context contract 
Description 566 -> 249 chars, body 644 -> 398 words, Gotchas 12 -> 2. The
eight organisational hard rules move to references/hard-rules.md.

Its load trigger enumerates operations rather than rule topics: the first
draft keyed on 'commit message form', which left the atomicity and
working-state rules unreachable when a caller supplied a conventional
message. Also promotes the destructive-op confirmation ahead of the
orchestrator invocation, which it previously followed.
 2026-08-30 13:10:53 +00:00
Defame1297
38eb0745b7 refactor(git-remotes): retrofit to the ADR-0020 context contract 
Description 582 -> 237 chars, body 1217 -> 290 words. The single remotes.md
splits into config, fetch, push, and pull flow files.

Restores the confirm: true token to the force-push gate -- it is the git
plugin's cross-skill contract, gated on by git-orchestrate and git-branches.
Moves push.md's worked example off main, which the skill's own Step 1
refuses, and restores the never-bare---force directive.
 2026-08-30 13:10:53 +00:00
Defame1297
3dd5387671 refactor(git-worktrees): retrofit to the ADR-0020 context contract 
Description 592 -> 248 chars, body 756 -> 515 words, Gotchas 8 -> 4.

The audit found the dispatch table had no row for a worktree on an
existing local branch, so that request fell to the adjacent -B row, which
resets the branch to HEAD and discards its commits. Non-destructive create
is now the first row and -B names its own destructiveness. Adds the missing
lock/unlock row and repair's run-from constraint.
 2026-08-30 13:10:53 +00:00
Defame1297
0fde892f20 refactor(git-branches): retrofit to the ADR-0020 context contract 
Description 612 -> 273 chars, body 1124 -> 457 words. Branch patterns,
operations, merging, comparison, and the orchestrator contract move to
references/.

Corrects rebase routing in four places: this skill sent rebase to
git-history, which carries no rebase content and disclaims it. Rebase is
git-commits'; cherry-pick and revert stay git-history's. Drops a Step 3
gate on a rebase flow this skill does not have.
 2026-08-30 13:10:53 +00:00
Defame1297
f3b4860e14 refactor(git-commits): retrofit to the ADR-0020 context contract 
Description 724 -> 214 chars, body 1102 -> 343 words, Gotchas 12 -> 3.
Create, rewrite, and cherry-pick flows move to self-contained references/
files behind a dispatch table.

The audit caught that moving the secret scan into the create flow left the
amend/squash path with no check in its loaded context; it is now a gate
common to every flow. Also re-homes the interactive-rebase reflog warning
git-history dropped, since this skill owns rebase.
 2026-08-30 13:10:53 +00:00
Defame1297
bbc73008a3 chore(gitea): regenerate the flat content mirror after the ADR-0020 retrofit 
Generated output, not authored content: scripts/sync-plugin-content.sh --all.
Claude Code has no .apm/ awareness, so this compiled mirror must track .apm/ or
the check-plugin-content-sync pre-push hook reports drift.

Deferred to a single commit at the end of the wave on purpose. sync_dir runs
rm -rf before every copy, so running it while seven agents were editing the
same plugin would have raced them; agents were told not to sync for that reason.

Refs #99
 2026-08-30 12:42:20 +00:00
Defame1297
bedbd1d872 refactor(gitea-workflow): retrofit to the ADR-0020 context contract 
Description 1012 -> 347 chars, body 582 -> 170 words, Gotchas 3 entries -> 1 at
22.9% of body. Clears the description FAIL and all four Vale CompositionNote
errors -- the last carriers in the corpus, so that rule now fires nowhere.

Cut the 'human-facing entry point and router' architecture note, the /gitea
migration history and the six-skill composition list; all were already in the
README or the routing table.

Split three mutually exclusive flows into a dispatch table keyed on invocation
shape, each branch self-contained in references/: status-checkin.md,
number-resolution.md, skill-index.md. Report stays in the body as the gate
common to every branch; each branch's own format moved to its file. The old
Step 1-4 numbering presented three alternatives as a sequence.

The description grew from an intermediate 283 chars on purpose: that draft had
dropped flow 3's trigger entirely, leaving the domain-routing index -- a third
of the skill -- reachable only through a tail clause whose grammatical subject
was the request rather than the skill. Both gates were green over that.

Boundary clauses are one arrow per target, so both resolve (#107: the resolver
extracts only the first target per clause and reports 1 of 1 on a clause naming
two). The local-git exclusion keeps its wording but drops the route to
git-workflow, which would not resolve in a gitea-only install.

Known residual: the dispatch conditions are stated twice, as a table and as
literal conditionals. That is #109 -- body-discipline.md mandates the literal
form while the ADR's cited exemplar, apm-workflow, uses a bare table plus one
summary line. Fixing it here would settle that contradiction in a skill rather
than in the spec, so it rides with #109.

Refs #99, #107, #109
 2026-08-30 12:42:04 +00:00
Defame1297
b8c36c36f6 docs(agents): correct the ADR-0020 gate counts to measured state 
The bullet is always-loaded context, and all three of its numbers had gone
stale as the issue #99 retrofit landed. Measured now: 19 of 39 descriptions and
7 of 39 bodies over their FAIL tier, down from 26 and 9; one dangling routing
target left (research -> neuledge-context), down from two.

Kyberforge.CompositionNote fired 10 errors across four gitea-* skills and now
fires nowhere -- those four were the only carriers and all four have been
retrofitted. The 'check both gates' advice stays: skill-size-check still does
not cover the Vale half, and any new description can reintroduce the rule.

Refs #99
 2026-08-30 12:35:48 +00:00
Defame1297
23b843a311 test: drop the gitea-labels pin now the retrofit removed that target 
tests/test-adr0020-targets.sh pinned the corpus dangling set as exactly
{gitea-labels, neuledge-context} and tests/test-skill-size-check.sh probed both
individually. The gitea-issues retrofit cut the composition sentence whose
'>'-folded scalar produced 'gitea-labels- milestones', so that target no longer
exists and both suites went red.

EXPECTED_DANGLING is now {neuledge-context} and the gitea-issues probe is
removed rather than skipped, per the rule the probe file states about itself: a
probe whose fixture has been retrofitted is a pin that needs updating, not an
assertion-free pass counted in the totals.

The exact-set assertion stays. An empty expected set is still valid and still
pins that no new dangling target appeared -- which is what it becomes once
research is retrofitted. Both loops carry a shellcheck SC2043 waiver for the
same reason: one entry is the expected steady state, not bad quoting.

Refs #99
 2026-08-30 12:34:24 +00:00
Defame1297
37382cb72a refactor(gitea-labels-milestones): retrofit to the ADR-0020 context contract 
Description 835 -> 214 chars, body 669 -> 426 words, Gotchas 8 entries/63% of
body -> 3/20.4%. Clears the description FAIL, all three Vale CompositionNote
errors and both Gotchas suggestions. 63% was the worst Gotchas ratio in the
corpus.

Cut the composition sentence to README -- it changes no routing decision and an
agent picks this skill because the user asked about labels, not because two
other skills call it. Cut the capability enumeration; 'list, create, edit,
delete' decompose 'reading or writing' and add no trigger.

Boundary clauses are now one arrow per target. The resolver extracts only the
first name per arrow clause, so the previous '-> gitea-issues / gitea-prs' left
gitea-prs neither dangling nor checked while validate.sh reported 1 of 1. Now
2 of 2.

Makes org-scoped label resolution executable. The org label pool was reachable
in principle -- four *_org_label* methods, and a claim to own name-to-ID
resolution -- but list_org_labels takes org, and Step 1 derived only owner and
repo, so both resolution procedures stalled at the fallback. Fixed once at the
identity step rather than per-procedure. get_user_orgs is outside allowed-tools,
so the failing call is the discriminator: a failure means the owner is a user
account with no org pool, which is an answer, not an error.

Corrects a Gotcha that was false for create_repo_label/create_org_label and
collided with the literal tool name label_write. Same false claim removed from
README.

Refs #99
 2026-08-30 12:29:18 +00:00
Defame1297
78015893d4 refactor(gitea-issues): retrofit to the ADR-0020 context contract 
Description 827 -> 182 chars, body 902 -> 584 words, Gotchas 7 entries/43% of
body -> 4/23.1%. Clears both size FAILs, the dangling-target FAIL and the Vale
CompositionNote error.

The dangling 'gitea-labels' target is gone with the composition sentence that
carried it -- a YAML fold artifact, not a typo: the '>'-folded scalar joined
'gitea-labels-' and 'milestones' across a line break, leaving the name terminal
and danglable. Both boundary names now sit whole on one source line each, and
both resolve.

Cut the second trigger register, the seven-verb capability enumeration, the
issue_write implementation detail and a gitea-branches boundary that defended
nothing. Two Gotchas deleted as spec restatement carried in references/, one as
a paraphrase of the step below it.

Closes a capability hole rather than papering over it: gitea-labels-milestones
routes label application here and has no issue_write, but no dispatch row
existed for add/replace/remove/clear_labels or get_labels. Both rows added.
The label ID/name Gotcha is now stated per method -- issue_write takes IDs,
list_issues and search_issues filter by name, issue_read 'get' returns names
but 'get_labels' returns full objects with IDs.

Drops a stale quotation of gitea-labels-milestones' description from
references/enrichments.md; that string went with its composition note.

Refs #99
 2026-08-30 12:28:54 +00:00
Defame1297
0079f3508c fix(gitea-prs): correct reference drift against gitea-mcp v1.7.0 
The reference files were last verified against v1.3.0 -- references/sources.md
still said so. PR #106 re-verified the write side only, so three defects had
accumulated on the read/review side. All three reproduced against the deployed
server before being fixed; get_gitea_mcp_server_version reports v1.7.0.

- reviews.md forbade review_comments on the "get" response and directed callers
  to review_scomments, which does not exist. The upstream slim.go typo was
  corrected; a live pull_request_read on PR #106 returns "review_comments":1 and
  no review_scomments key. review_comments is an integer count, not comment
  objects -- distinct from the get_review_comments method. Also fixed in
  pull-requests.md's response-shape list.
- pull_request_review_write grants seven methods; only four were documented.
  reply_comment, resolve_thread, unresolve_thread and the comment_id parameter
  had zero mentions anywhere in the skill. Documented from the schema, in a
  Comment threads section kept outside the numbered review state machine --
  they are not lifecycle states.
- review_id was documented as required for get_review_comments. It is optional;
  omitting it lists every inline comment on the PR. Confirmed behaviourally:
  get_review without it errors, get_review_comments without it returns [].

sources.md now records v1.7.0 as the last-verified version, so the next reader
knows what these files were checked against.

Refs #99
 2026-08-30 12:21:11 +00:00
Defame1297
d578d6b2f2 refactor(gitea-prs): retrofit to the ADR-0020 context contract 
Description 709 -> 161 chars, body 683 -> 353 words, Gotchas 8 entries/56% of
body -> 2/24.9%. Clears the description FAIL and both Vale CompositionNote
errors.

Fixes the three stale claims recorded on issue #99, all re-verified against the
deployed gitea-mcp schema during review:

- The description no longer advertises 'reviewers' as an update capability.
  editPullRequestFn never reads reviewers or team_reviewers; only
  add_reviewers/remove_reviewers do.
- milestone is now marked honoured on "update" only, in the Gotcha, the body
  and the dispatch table's create row. On "create" the server discards it and
  omits the key from the response, so the drop is indistinguishable from never
  passing it -- and labels DOES apply on create, so labels landing is no
  evidence the milestone did. The old text told callers to resolve a milestone
  before any write, wasting the lookup on create.
- The superseded un-draft workaround is gone. "update" with draft:false and no
  title makes the server strip the prefix itself, including [WIP],
  case-insensitively -- carried by references/pull-requests.md, corrected in
  PR #106.

The 22-row tool/method table becomes a 5-row dispatch table; all 20 operations
it named remain reachable, including update_branch and the reviewer methods.

Refs #99
 2026-08-30 12:10:21 +00:00
Defame1297
d5954d3d99 refactor(gitea-files): retrofit to the ADR-0020 context contract 
Description 787 -> 263 chars, body 922 -> 302 words, Gotchas 9 entries/69% of
body -> 3/24.8%. Clears both size FAILs and both Gotchas suggestions.

Deleted the second trigger register outright -- ~300 chars re-quoting the same
six verbs as user phrasings, which ADR-0020 names this skill for specifically.

Split the body on the read/write boundary: one invocation cannot both read and
write, so a dispatch table is mandatory. Six operations collapse into two flow
files rather than six -- create/update/delete share one tool pair and one
SHA-first lifecycle whose preamble would otherwise be triplicated, and the three
read tools share ref selection plus a 'neither listing is a SHA source'
comparison that only exists between them.

references/examples.md removed; all eight of its content blocks and all nine
named parameters carry into references/writing.md, verified against git HEAD.
Two deltas are corrections: the repo tree is now ruled out as a SHA source, and
reusing a SHA captured earlier in the conversation is now forbidden.

Four Gotchas relocated to the flow file that needs them; two promoted to gates
(SHA-as-concurrency-token opens writing.md; owner/repo became ## Inputs).

Refs #99
 2026-08-30 12:09:52 +00:00
Defame1297
ee812699a4 refactor(gitea-branches): retrofit to the ADR-0020 context contract 
Description 688 -> 282 chars, body 435 -> 293 words, Gotchas 5 entries/54% of
body -> 3/23.5%. Clears the description FAIL and the Gotchas suggestion.

Cut the second trigger register (six re-quoted user phrasings) and the capability
enumeration; both moved to a new Boundaries section in the skill's own README.
Kept all three boundary clauses -- git-branches, git-history and gitea-prs each
defend a real activation steal, and gitea-prs is now the only guard on the
branch/PR collision in either direction since gitea-prs's own retrofit narrowed
its boundary to issues. Written as one arrow per target: the resolver extracts
only the first name per arrow clause, so conjoined targets go unchecked.

Two Gotchas deleted -- one paraphrased the step below it (its non-obvious half,
the get_me/list_my_repos token-scope block, was folded into that step), the other
is carried in full by references/branches.md:40-52.

Repoint two reference pointers the rename broke: branches.md and commits.md named
Gotchas by titles this retrofit changed. Now named by stable descriptors.

Refs #99
 2026-08-30 12:08:38 +00:00
Defame1297
dfacf051a8 refactor(gitea-releases): retrofit to the ADR-0020 context contract 
Description 500 -> 211 chars, body 676 -> 462 words, Gotchas 5 entries/41% of
body -> 3/21%. Clears the description FAIL and both Gotchas suggestions.

Cut the second trigger register (the re-quoted user phrasings), the doubled
capability enumeration across releases and tags, and the gitea-issues/gitea-prs
boundary, which defended against nothing -- neither was going to win a release
request. Kept the indirect trigger and the one real near-miss, gitea-branches.

Releases and tags are one flow, not two: 'delete the release and its tag' is a
single invocation that takes both branches, which disqualifies mutual
exclusivity, so no dispatch split. Two Gotchas moved to references/ behind
explicit triggers; one deleted as a paraphrase of the step below it.

Refs #99
 2026-08-30 12:06:37 +00:00
Defame1297
ef3e981eac docs(context): record that hand-invocation blocks skill-to-skill routing 
The Hand-invoked skill entry covered listing visibility and preload tax but not
invocability. Measured: disable-model-invocation: true hard-blocks the Skill
tool, not just the model-visible listing, so a `Call `x`` step in another
skill's body stops working the moment x takes the flag.

ADR-0020's 'Invocation as a design axis' verified only the visibility and slash
directions. Without this half, marking grill-with-docs hand-invoked -- one of
issue #99's four named candidates -- would silently break forge Step 1, which
calls it, plus three other inbound routes.

Refs #99
 2026-08-30 11:54:26 +00:00
Defame1297
5f984ce34a chore(apm): refresh lock after SessionStart update 
The SessionStart hook found six packages behind the remote default branch and
ran apm update. Committing the resulting lock separately so it does not sit in
the ADR-0020 retrofit diff.
 2026-08-30 11:54:18 +00:00
261 changed files with 4396 additions and 3271 deletions
Expand all files Collapse all files

2
AGENTS.md
View File

@@ -36,7 +36,7 @@ Fall back to raw shell only when no skill covers it.
- **Do not add repo-owned keys to `.claude/settings.json`.** apm treats it as its own deployed artifact and `apm audit --ci` replays the install and diffs, so anything apm would not have written is permanent drift that fails the `apm-audit-ci` pre-push hook. A hook you want here is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written into that file. The `SessionStart` entry already in it is exactly that: kyberforge authors it in `plugins/kyberforge/.apm/hooks/hooks.json` and apm merges it in, so it is apm's own output, it is what the replay expects, and it belongs in the commit — do not strip it (ADR-0019). Machine-specific settings go in the gitignored `.claude/settings.local.json`; shared enforcement goes in `.pre-commit-config.yaml`.
- **`apm.lock.yaml` turning up modified is expected, not a bug.** kyberforge's `SessionStart` hook runs `apm outdated` at startup and `apm update --yes` when something is behind, which rewrites the lock. Commit or discard it deliberately.
- **A `.apm/` edit is not live in this session until it is pushed.** The six dependencies resolve from the holocron remote, unpinned against the default branch. `apm install` deploys from the lock; `apm update` is what re-resolves refs.
- **The ADR-0020 skill gates ship hot, with no baseline.** 26 of 39 descriptions and 9 of 39 bodies exceed their FAIL tier, and the `Kyberforge.CompositionNote` Vale rule fires 10 errors across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`. Editing any of those skills *for any reason* means retrofitting it to the contract first — a one-line fix cannot be committed until the skill complies. Deliberate; tracked as Gitea issue #99. `skill-size-check` will not warn you about the Vale half, so check both: `pre-commit run --all-files`.
- **The ADR-0020 skill gates ship hot, with no baseline.** Three skills still exceed a FAIL tier, all in `kyberforge`: `apm-workflow` (817-char description), `forge` (648 chars, 1,093-word body) and `apm-install` (514 chars). Editing any of those three *for any reason* means retrofitting it to the contract first — a one-line fix cannot be committed until the skill complies. Deliberate; tracked as Gitea issue #99, which is retrofitting the corpus plugin by plugin and has `kyberforge` left. **No routing target dangles any more**, and `tests/test-adr0020-targets.sh` now pins that set as empty, so a new boundary clause naming a non-existent skill fails the suite rather than joining a backlog. The `Kyberforge.CompositionNote` Vale rule fires nowhere, but `skill-size-check` does not cover the Vale half and any new description can reintroduce it, so check both: `pre-commit run --all-files`.
- **Run `bash tests/run-tests.sh --strict` before considering any change done.** Keep the flag: without it a suite whose dependency is missing exits 77 and is counted SKIPPED rather than failed, so the run goes green having verified less than it claims.
- **Before pushing, rehearse the gate locally:** `pre-commit run --hook-stage pre-push --all-files`. It runs the 14 pre-push hooks this repo authors itself plus pre-commit's 2 `meta` hooks, so it prints 16; `check-release-needed` passes without checking anything, because it needs a real push to `main`. `docs/spec/gates.md` reconciles both.
- **Pushing without a network** needs `SKIP=apm-marketplace-check,apm-pack-check-clean git push` — those two resolve a remote marketplace entry via `git ls-remote`. Skip only those two; the rest are real local checks, and adding one to `SKIP` disarms it silently.

4
CONTEXT.md
View File

@@ -35,7 +35,9 @@ _Avoid_: router body, thin body
**Hand-invoked skill**:
A skill reached only by typing its slash command, declared `disable-model-invocation: true`. The host
withholds it from the model-visible listing entirely, so it pays no preload tax and its description
becomes human-facing text. Exemplar: `zoom-out`.
becomes human-facing text. The flag also hard-blocks the Skill tool, so **no other skill can route to
a hand-invoked skill** — a `Call \`x\`` step in another skill's body stops working the moment `x`
takes the flag. Check inbound routes before declaring one. Exemplar: `zoom-out`.
_Avoid_: manual skill, disabled skill
**Delegation discipline**:

34
apm.lock.yaml
View File

@@ -1,12 +1,12 @@
lockfile_version: '1'
generated_at: '2026-08-17T06:44:18.931217+00:00'
generated_at: '2026-08-30T11:38:46.419301+00:00'
apm_version: 0.28.0
dependencies:
- repo_url: Defame1297/holocron
name: bin
host: git.dev.rkdr.net
resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
version: 1.1.3
resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.1.5
virtual_path: plugins/bin
is_virtual: true
package_type: marketplace_plugin
@@ -81,13 +81,13 @@ dependencies:
.claude/skills/triage/SKILL.md: sha256:b819f0285e4e5814ac6472d0217f07dc9f23d2fdae3ebb0dd31d98360d8ac029
.claude/skills/write-docs/SKILL.md: sha256:0d06d0f6836a67532497ea61bd5a1294a8d80f529bf1ffb5c4b1fdc72e9cb51a
.claude/skills/zoom-out/SKILL.md: sha256:2a6894c7f9b1c9c55f451c625a834c4f377e217b623a85280e55db5fe9cacf48
content_hash: sha256:7acfaa806ae8379fe6351441ce8f973ac3ff8a02deb4a5e145968203d1176ef8
content_hash: sha256:d7cca4972651b241a5450679289fdb6f0e3a37aef9dff0498cb4b3340b048781
declared_license: MIT
exec_status: gated_pending_approval
- repo_url: Defame1297/holocron
name: core
host: git.dev.rkdr.net
resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.1.1
virtual_path: plugins/core
is_virtual: true
@@ -134,8 +134,8 @@ dependencies:
- repo_url: Defame1297/holocron
name: git
host: git.dev.rkdr.net
resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
version: 1.3.3
resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.3.5
virtual_path: plugins/git
is_virtual: true
package_type: marketplace_plugin
@@ -236,13 +236,13 @@ dependencies:
.claude/skills/pc-run/references/README.md: sha256:ad42b9013dbd44b8c4515c15317c5e9e6b235bc656ad5a03e037eb4bc6f8782c
.claude/skills/pc-run/references/failure-patterns.md: sha256:59d913c001483c3770d269fdf5e83cf1d7578e0ae879928a1404bf93bb395994
.claude/skills/pc-run/references/sources.md: sha256:7ca8b7106e7ee5c2c7d1fbd3dc9e0d2a89c18eba79145cbab55bc8e39eef9087
content_hash: sha256:6d0c8fcec32d8fb8321b539cc567c4241342cfa33e5d0b6f66697d2f8b784fdd
content_hash: sha256:8c47bd35572c331f1a1b61a8be159d9690a1bf286958a85826fde01939e3007b
declared_license: MIT
- repo_url: Defame1297/holocron
name: gitea
host: git.dev.rkdr.net
resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
version: 1.3.4
resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.3.6
virtual_path: plugins/gitea
is_virtual: true
package_type: marketplace_plugin
@@ -313,10 +313,10 @@ dependencies:
.claude/skills/gitea-labels-milestones/references/labels.md: sha256:be8ff5ce4dbfb31dd2bdcc425a769dca94887c5c8acd47c78e1e21ccfc24dcba
.claude/skills/gitea-labels-milestones/references/milestones.md: sha256:ff1f1b0c8ecb6967c940d1ca8bebf2a2c7995414936f8ac7f5ff23d1dc01ac3f
.claude/skills/gitea-labels-milestones/references/sources.md: sha256:a1a1d3381dfb0dc8f331be0b3ab49f28e94b992fb4809ca09be91ce33047dd1e
.claude/skills/gitea-prs/README.md: sha256:0346388f642641c56cef82ba1ee576a187d048eee66fab839a17417c81122cbc
.claude/skills/gitea-prs/README.md: sha256:31b6ad46379feee8ac7d837030f93ec04be20b7d11021b295dc6d27b4340a05b
.claude/skills/gitea-prs/SKILL.md: sha256:bf70832f3d97064c9816d680390da84c256a971d7804317e1814b4ee6a622b4d
.claude/skills/gitea-prs/references/merging.md: sha256:5f8b55b1a729f122ee265fb5da69369fc27434a13dd02fc112801f945d2c9d19
.claude/skills/gitea-prs/references/pull-requests.md: sha256:631874a7cddfcf678a2beffa5578fa7848bcef36be1251fa13fb0ccc543bcaf7
.claude/skills/gitea-prs/references/pull-requests.md: sha256:d6cefd0cf270f8d844536311e67bfa45cd07f024aa0a649de1938af306ae7109
.claude/skills/gitea-prs/references/reviews.md: sha256:1089cf45a75a562bbb29de6538848c4f4bd627d5a7e36bf9b2ab6496f45f962b
.claude/skills/gitea-prs/references/sources.md: sha256:ac48a3018443b56acb5c3d55d6c04e62103f5bac71b8185e2bd085fb7e165431
.claude/skills/gitea-releases/README.md: sha256:102625066c34c7b5a16e25b7506a87f876e9b123b334f5ffba73ab1523a57ed7
@@ -327,12 +327,12 @@ dependencies:
.claude/skills/gitea-workflow/README.md: sha256:338f79d0b3c25741848fce841a5094ef27cbc7e4a6228404557b2d9594df68fa
.claude/skills/gitea-workflow/SKILL.md: sha256:a8266ceb335c56eb68cc09b3f81690c52c4dada9f25b48c3a46ac46b0ad3b761
.claude/skills/gitea-workflow/references/sources.md: sha256:171d3a5a36cb9d637302516501a1e9fc7a4bd058968dc9244412c335aa2de68b
content_hash: sha256:8149467df78678963dbb140aa254f606a53491f3cb7e5d97a1211be426e7892e
content_hash: sha256:16d5b4462c3f4a506c1c74172d4d67bf0dacc4218676de4e8dfe551b2f31a3f8
declared_license: MIT
- repo_url: Defame1297/holocron
name: kyberforge
host: git.dev.rkdr.net
resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.6.0
virtual_path: plugins/kyberforge
is_virtual: true
@@ -530,7 +530,7 @@ dependencies:
- repo_url: Defame1297/holocron
name: lint
host: git.dev.rkdr.net
resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.1.6
virtual_path: plugins/lint
is_virtual: true
@@ -1873,7 +1873,7 @@ deployments:
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
content_hash: sha256:0346388f642641c56cef82ba1ee576a187d048eee66fab839a17417c81122cbc
content_hash: sha256:31b6ad46379feee8ac7d837030f93ec04be20b7d11021b295dc6d27b4340a05b
- kind: project-relative
target: claude
value: .claude/skills/gitea-prs/SKILL.md
@@ -1900,7 +1900,7 @@ deployments:
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
content_hash: sha256:631874a7cddfcf678a2beffa5578fa7848bcef36be1251fa13fb0ccc543bcaf7
content_hash: sha256:d6cefd0cf270f8d844536311e67bfa45cd07f024aa0a649de1938af306ae7109
- kind: project-relative
target: claude
value: .claude/skills/gitea-prs/references/reviews.md

46
plugins/bin/.apm/skills/diagnose/SKILL.md
View File

@@ -1,6 +1,9 @@
---
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.
description: >
Use when the user says "diagnose this" or "debug this", reports something
broken, throwing, or failing, or says something got slow. Not filing or
triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`.
---
# Diagnose
@@ -15,40 +18,9 @@ When exploring the codebase, use the project's domain glossary to get a clear me
Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
### Ways to construct one — try them in roughly this order
Read `references/feedback-loops.md` — even if you already have a signal. Ten ways to build a loop ordered by cost, how to sharpen the one you have, and what to do when the bug resists reproduction. An unsharpened loop is usually not good enough yet.
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.
Do not proceed to Phase 2 until you have a loop you believe in. If you cannot build one, stop and say so explicitly, listing what you tried — never hypothesise without a signal.
## Phase 2 — Reproduce
@@ -57,7 +29,7 @@ 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).
- [ ] The failure is reproducible across multiple runs. If it is intermittent, `references/feedback-loops.md` defines the rate high enough to debug against — go back to Phase 1 and raise it.
- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
Do not proceed until you reproduce the bug.
@@ -98,11 +70,11 @@ A correct seam is one where the test exercises the **real bug pattern** as it oc
If a correct seam exists:
1. Turn the minimised repro into a failing test at that seam.
1. Turn the Phase 1 loop into a failing test at that seam, narrowed to the symptom captured in Phase 2.
2. Watch it fail.
3. Apply the fix.
4. Watch it pass.
5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
5. Re-run the Phase 1 feedback loop against the original, un-narrowed scenario.
## Phase 6 — Cleanup + post-mortem

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

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

6
plugins/bin/.apm/skills/prototype/SKILL.md
View File

@@ -1,6 +1,10 @@
---
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".
description: >
Use when the user wants a throwaway prototype to answer a design question about
a data model, state machine or business logic, or to mock up a UI in several
variations, as in "try a few designs". Not production code -> `tdd`. Not
talking a design through without building -> `grill-me`.
---
# Prototype

15
plugins/bin/.apm/skills/research/META.md
View File

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

91
plugins/bin/.apm/skills/research/SKILL.md
View File

@@ -1,14 +1,10 @@
---
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).
Use when the user wants a tool, library, or API researched from canonical
documentation into structured per-topic reference markdown files. Not
documentation written from existing code or specs -> `write-docs`. Not a bug
or incident -> `diagnose`.
metadata:
category: research
allowed-tools:
@@ -21,77 +17,48 @@ allowed-tools:
model: sonnet
---
<requirements>
## Gotchas
## Required inputs
- Never infer the output path. A run writes a directory's worth of files, and a guessed destination scatters them through someone's source tree. If the user named no path, stop and ask.
- Write nothing outside the given output path. A file placed beside the agreed directory is one the user never asked for and will not think to look for.
- Never write an empty topic file. A stub `troubleshooting.md` reads downstream as researched and closed.
- A Context7 response that is a "no results" message, a redirect notice, or header-only boilerplate is not coverage. A topic area counts as covered only when the response carries at least one substantive paragraph.
- **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
## Step 1 — Scope against the working directory
## Constraints
Search for existing use of the topic — imports, config files, version pins, reference files already written — and narrow the research to what is missing: the version actually in use, the topics not yet documented.
- 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
Read `references/topics.md` before narrowing, for the default topic list.
</requirements>
## Step 2 — Resolve against Context7
<steps>
If the topic is a library, framework, or API and the user gave no starting URLs, call `resolve-library-id` with the topic name and the user's full question — match quality depends on the question, not the bare name — then `query-docs` once per default topic area. Record each response as a source with slug `context7-<library-slug>`, and mark which topic areas it covered — those skip the web reads at step 4.
## Process
If the library does not resolve, or the user gave starting URLs, go to step 3. Explicit URLs are a source choice; do not second-guess them with a resolution attempt.
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.
## Step 3 — Discover sources
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.
If the user gave starting URLs, skip discovery: those URLs are the source list and go straight to step 4.
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.
Otherwise, for every topic area Context7 did not cover, websearch for canonical documentation — `llms.txt`, official developer docs, and API references ahead of tutorials or blog posts. Collect three to five candidate URLs before reading any of them.
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.
If nothing usable comes back, stop and report what was searched, then ask for starting URLs rather than settling for tutorials.
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.
## Step 4 — Read the sources
6. **Consolidate.** Merge all subagent summaries (Context7 and web) by topic area. Identify which default topics have sufficient content and which custom topics emerged.
`WebFetch` each URL in turn. No subagent tool is granted here, so the reads are serial and every fetched page lands in this context: reduce each page to notes by topic area, plus the links worth deepening, before fetching the next one.
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.
## Step 5 — Deepen
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`.
`WebFetch` the links worth following, still one at a time and still reducing each page to notes. Stop a branch once its content turns repetitive or leaves the topic, and cap the whole step at roughly ten additional pages — serial reads make that cap a real budget, not a formality.
## Output format
## Step 6 — Write
- `<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
Merge every set of notes, Context7 and web alike, by topic area. Read `references/file-format.md`, then write, in the output path:
</steps>
- `<topic>.md` for each topic area that has content, default or custom
- `sources.md`, always, one section per source in the schema that file gives — URL, description, contributing files, and status — including sources that yielded nothing, marked `no content extracted`
<checks>
Spell the `sources.md` field names exactly as `references/file-format.md` gives them. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing.
## 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>
If no topic area has content, write nothing at all, `sources.md` included, and report what was searched. A directory of empty files is worse than an honest miss.

5
plugins/bin/evals/research/research/eval.yaml
View File

@@ -26,11 +26,6 @@ trigger_tests:
query: "Research why these integration tests are failing"
should_trigger: false
- id: negative-neuledge
name: "Negative — MCP server setup goes to neuledge-context"
query: "Install the neuledge context server and set it up"
should_trigger: false
- id: negative-context7-direct-question
name: "Negative — direct doc question goes to context7-mcp, not research"
query: "What are the Next.js middleware options?"

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

@@ -1,6 +1,9 @@
---
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.
description: >
Use when the user says "diagnose this" or "debug this", reports something
broken, throwing, or failing, or says something got slow. Not filing or
triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`.
---
# Diagnose
@@ -15,40 +18,9 @@ When exploring the codebase, use the project's domain glossary to get a clear me
Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
### Ways to construct one — try them in roughly this order
Read `references/feedback-loops.md` — even if you already have a signal. Ten ways to build a loop ordered by cost, how to sharpen the one you have, and what to do when the bug resists reproduction. An unsharpened loop is usually not good enough yet.
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.
Do not proceed to Phase 2 until you have a loop you believe in. If you cannot build one, stop and say so explicitly, listing what you tried — never hypothesise without a signal.
## Phase 2 — Reproduce
@@ -57,7 +29,7 @@ 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).
- [ ] The failure is reproducible across multiple runs. If it is intermittent, `references/feedback-loops.md` defines the rate high enough to debug against — go back to Phase 1 and raise it.
- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
Do not proceed until you reproduce the bug.
@@ -98,11 +70,11 @@ A correct seam is one where the test exercises the **real bug pattern** as it oc
If a correct seam exists:
1. Turn the minimised repro into a failing test at that seam.
1. Turn the Phase 1 loop into a failing test at that seam, narrowed to the symptom captured in Phase 2.
2. Watch it fail.
3. Apply the fix.
4. Watch it pass.
5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
5. Re-run the Phase 1 feedback loop against the original, un-narrowed scenario.
## Phase 6 — Cleanup + post-mortem

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

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

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

@@ -1,6 +1,10 @@
---
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".
description: >
Use when the user wants a throwaway prototype to answer a design question about
a data model, state machine or business logic, or to mock up a UI in several
variations, as in "try a few designs". Not production code -> `tdd`. Not
talking a design through without building -> `grill-me`.
---
# Prototype

15
plugins/bin/skills/research/META.md
View File

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

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

@@ -1,14 +1,10 @@
---
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).
Use when the user wants a tool, library, or API researched from canonical
documentation into structured per-topic reference markdown files. Not
documentation written from existing code or specs -> `write-docs`. Not a bug
or incident -> `diagnose`.
metadata:
category: research
allowed-tools:
@@ -21,77 +17,48 @@ allowed-tools:
model: sonnet
---
<requirements>
## Gotchas
## Required inputs
- Never infer the output path. A run writes a directory's worth of files, and a guessed destination scatters them through someone's source tree. If the user named no path, stop and ask.
- Write nothing outside the given output path. A file placed beside the agreed directory is one the user never asked for and will not think to look for.
- Never write an empty topic file. A stub `troubleshooting.md` reads downstream as researched and closed.
- A Context7 response that is a "no results" message, a redirect notice, or header-only boilerplate is not coverage. A topic area counts as covered only when the response carries at least one substantive paragraph.
- **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
## Step 1 — Scope against the working directory
## Constraints
Search for existing use of the topic — imports, config files, version pins, reference files already written — and narrow the research to what is missing: the version actually in use, the topics not yet documented.
- 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
Read `references/topics.md` before narrowing, for the default topic list.
</requirements>
## Step 2 — Resolve against Context7
<steps>
If the topic is a library, framework, or API and the user gave no starting URLs, call `resolve-library-id` with the topic name and the user's full question — match quality depends on the question, not the bare name — then `query-docs` once per default topic area. Record each response as a source with slug `context7-<library-slug>`, and mark which topic areas it covered — those skip the web reads at step 4.
## Process
If the library does not resolve, or the user gave starting URLs, go to step 3. Explicit URLs are a source choice; do not second-guess them with a resolution attempt.
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.
## Step 3 — Discover sources
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.
If the user gave starting URLs, skip discovery: those URLs are the source list and go straight to step 4.
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.
Otherwise, for every topic area Context7 did not cover, websearch for canonical documentation — `llms.txt`, official developer docs, and API references ahead of tutorials or blog posts. Collect three to five candidate URLs before reading any of them.
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.
If nothing usable comes back, stop and report what was searched, then ask for starting URLs rather than settling for tutorials.
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.
## Step 4 — Read the sources
6. **Consolidate.** Merge all subagent summaries (Context7 and web) by topic area. Identify which default topics have sufficient content and which custom topics emerged.
`WebFetch` each URL in turn. No subagent tool is granted here, so the reads are serial and every fetched page lands in this context: reduce each page to notes by topic area, plus the links worth deepening, before fetching the next one.
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.
## Step 5 — Deepen
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`.
`WebFetch` the links worth following, still one at a time and still reducing each page to notes. Stop a branch once its content turns repetitive or leaves the topic, and cap the whole step at roughly ten additional pages — serial reads make that cap a real budget, not a formality.
## Output format
## Step 6 — Write
- `<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
Merge every set of notes, Context7 and web alike, by topic area. Read `references/file-format.md`, then write, in the output path:
</steps>
- `<topic>.md` for each topic area that has content, default or custom
- `sources.md`, always, one section per source in the schema that file gives — URL, description, contributing files, and status — including sources that yielded nothing, marked `no content extracted`
<checks>
Spell the `sources.md` field names exactly as `references/file-format.md` gives them. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing.
## 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>
If no topic area has content, write nothing at all, `sources.md` included, and report what was searched. A directory of empty files is worse than an honest miss.

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

@@ -14,6 +14,9 @@ Runs a single combined pass across every AGENTS.md file in a repo (root and any
Provide the path to the repo root to audit when invoking.
Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a
hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit.
## Files
| File | Purpose |

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

@@ -1,20 +1,11 @@
---
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.
Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md",
"is this AGENTS.md safe to commit" — or after a hand-edit outside
`agentsmd-author`. Reports secrets, structure and drift; never edits.
Not for CLAUDE.md or provider files -> `provider-adapter-author`.
Not writing AGENTS.md -> `agentsmd-author`.
allowed-tools: Bash Read
metadata:
category: docs
@@ -23,14 +14,13 @@ metadata:
- context7-websites-agents-md
- context7-agentsmd-agents-md
- governance-secrets-hard-prohibition
version: "0.1.1"
version: "0.1.2"
---
## Gotchas
- Always run all three checks — this skill does a single combined pass, not staged/gated passes. Don't skip structure or drift checks just because a secrets FAIL was found.
- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. 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.
- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope.
- Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report.
## Step 1 — Run the validators
@@ -41,7 +31,7 @@ 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.
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. Grade a manual finding the way the scripts grade theirs: a missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference.
## Step 2 — Report

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

@@ -1,20 +1,10 @@
---
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.
Use when the user wants a repo's AGENTS.md written or updated, root or
nested, including "document this for AI coding tools". Writes only verified
conventions. Not review-only -> `agentsmd-audit`. Not for CLAUDE.md ->
`provider-adapter-author`.
allowed-tools: Bash Read Write Edit
metadata:
category: docs
@@ -22,16 +12,13 @@ metadata:
- agents-md-official
- context7-websites-agents-md
- context7-agentsmd-agents-md
version: "0.1.1"
version: "0.1.2"
---
## Gotchas
- Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (`package.json` scripts, a `Makefile` target, a CI workflow step, a README). If you can't verify a command, don't include it.
- 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.
- Never write to a provider file yourself, in any circumstance: `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md` and their equivalents are `provider-adapter-author`'s to own. That holds even when the user asks for one in the same breath as AGENTS.md, and even when the file is merely stale or missing a pointer rather than duplicating anything. Detect it and hand off.
## Step 1 — Explore the target repo
@@ -40,17 +27,17 @@ Before writing anything, gather real facts: package manager and scripts (`packag
## 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.
- A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested `AGENTS.md` there, scoped to what's different. Convenience is not a reason to create one — without a distinct stack you are duplicating content the root already covers. **Don't repeat root-level content** in a nested file: the nearest-file-wins rule means it is read alone, never merged back with the root.
- Otherwise → update the existing file(s) in place.
## Step 3 — Write or update
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.
AGENTS.md has no required schema. Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists, because a thin accurate file beats a padded generic one. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
## Step 4 — Check for an existing provider file
Look for `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, or similar in the target repo. If one exists 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.
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.
## 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.
Invoke the `agentsmd-audit` skill directly on the AGENTS.md file(s) you just wrote or updated. This closeout is mandatory, not optional, even when the change looks trivial — never sign the work off on your own judgment. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.

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

@@ -23,6 +23,7 @@ Provide the path to the provider-specific file to convert (and the target repo r
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, and the validator flag each needs |
| `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/` |

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

@@ -1,36 +1,28 @@
---
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.
Use when a provider file (CLAUDE.md, .cursor rules, copilot-instructions)
duplicating the repo's AGENTS.md should be cut to a thin adapter.
Not writing the AGENTS file -> `agentsmd-author`.
Not auditing the AGENTS file -> `agentsmd-audit`.
allowed-tools: Bash Read Edit Write
metadata:
category: docs
source_keys:
- adr-0002-0003-two-tier-claude-md
version: "0.1.0"
version: "0.1.1"
---
## 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.
- Assume a provider has no cross-file import mechanism until you have confirmed it has one. Claude Code is the exception, not the rule: a `CLAUDE.md` may consist of nothing but `@path` lines, while the same `@AGENTS.md` line in a Cursor rule or a Copilot instructions file is inert text no tool resolves. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for those providers.
- Works standalone or composed-into by `agentsmd-author` — behave identically either way; 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.
Find the provider instruction file to convert. Before searching, read `references/provider-matrix.md` — skip it only when the target is already a known root `CLAUDE.md`, which is the common case.
Then confirm `AGENTS.md` exists at the repo root. If it does not, stop and tell the user to run `agentsmd-author` first — there is nothing to adapt to.
## Step 2 — Diff and rewrite
@@ -39,6 +31,10 @@ Read the provider file and `AGENTS.md` side by side. Separate 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.
The provider file is the only file this skill ever writes. Never create or edit `AGENTS.md` — not in this step, not in any step, whatever the payoff looks like.
Strip only what is genuinely redundant. Provider-specific material stays even when it is short — the goal is thin, not empty.
## Step 3 — Self-validate
Run the bundled check before finishing — this is the skill's own closeout gate; there is no separate paired audit skill for this concern:
@@ -47,7 +43,7 @@ Run the bundled check before finishing — this is the skill's own closeout gate
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`.
Fix any `FAIL` by editing the provider file, and re-run until it exits `0`. The size `FAIL` advises moving provider-agnostic content into `AGENTS.md`; disregard that half of its wording and delete the redundant lines instead.
## Step 4 — Report

23
plugins/core/.apm/skills/provider-adapter-author/references/provider-matrix.md Normal file
View File

@@ -0,0 +1,23 @@
---
source_keys:
- adr-0002-0003-two-tier-claude-md
---
# Known provider instruction files
Which files to look for when detecting a provider-specific instruction file, whether each provider
resolves a cross-file import, and what a thin adapter therefore looks like for it.
| Provider | File(s) | Import syntax | Thin adapter shape | Validator flag |
|---|---|---|---|---|
| Claude Code | `CLAUDE.md` at the repo root, plus any deployed copies | Yes — `@path` lines, e.g. `@AGENTS.md` | One or more `@` import lines; no other content is required | none |
| Cursor | `.cursor/rules/*.mdc` | No | A short sentence pointing at `AGENTS.md`, plus the rule's own frontmatter and provider-specific body | `--no-import-syntax` |
| GitHub Copilot | `.github/copilot-instructions.md` | No | A short sentence pointing at `AGENTS.md`, plus Copilot-only instructions | `--no-import-syntax` |
| Anything else | tool-specific instruction file at whatever path the tool documents | Assume no | Text pointer, as above | `--no-import-syntax` |
A provider not listed here is not evidence it has an import mechanism. Confirm against that tool's
own documentation before emitting an `@`-style line; an unresolved import reads as literal text and
silently drops every rule the adapter was supposed to defer to.
Detection is a search, not a lookup: a repo may hold more than one of these, and each one converts
independently against the same `AGENTS.md`.

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

@@ -5,5 +5,5 @@
- **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
- **Contributing files:** SKILL.md, references/provider-matrix.md
- **Status:** `extracted`

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

@@ -14,6 +14,9 @@ Runs a single combined pass across every AGENTS.md file in a repo (root and any
Provide the path to the repo root to audit when invoking.
Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a
hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit.
## Files
| File | Purpose |

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

@@ -1,20 +1,11 @@
---
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.
Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md",
"is this AGENTS.md safe to commit" — or after a hand-edit outside
`agentsmd-author`. Reports secrets, structure and drift; never edits.
Not for CLAUDE.md or provider files -> `provider-adapter-author`.
Not writing AGENTS.md -> `agentsmd-author`.
allowed-tools: Bash Read
metadata:
category: docs
@@ -23,14 +14,13 @@ metadata:
- context7-websites-agents-md
- context7-agentsmd-agents-md
- governance-secrets-hard-prohibition
version: "0.1.1"
version: "0.1.2"
---
## Gotchas
- Always run all three checks — this skill does a single combined pass, not staged/gated passes. Don't skip structure or drift checks just because a secrets FAIL was found.
- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. 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.
- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope.
- Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report.
## Step 1 — Run the validators
@@ -41,7 +31,7 @@ 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.
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. Grade a manual finding the way the scripts grade theirs: a missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference.
## Step 2 — Report

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

@@ -1,20 +1,10 @@
---
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.
Use when the user wants a repo's AGENTS.md written or updated, root or
nested, including "document this for AI coding tools". Writes only verified
conventions. Not review-only -> `agentsmd-audit`. Not for CLAUDE.md ->
`provider-adapter-author`.
allowed-tools: Bash Read Write Edit
metadata:
category: docs
@@ -22,16 +12,13 @@ metadata:
- agents-md-official
- context7-websites-agents-md
- context7-agentsmd-agents-md
version: "0.1.1"
version: "0.1.2"
---
## Gotchas
- Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (`package.json` scripts, a `Makefile` target, a CI workflow step, a README). If you can't verify a command, don't include it.
- 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.
- Never write to a provider file yourself, in any circumstance: `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md` and their equivalents are `provider-adapter-author`'s to own. That holds even when the user asks for one in the same breath as AGENTS.md, and even when the file is merely stale or missing a pointer rather than duplicating anything. Detect it and hand off.
## Step 1 — Explore the target repo
@@ -40,17 +27,17 @@ Before writing anything, gather real facts: package manager and scripts (`packag
## 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.
- A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested `AGENTS.md` there, scoped to what's different. Convenience is not a reason to create one — without a distinct stack you are duplicating content the root already covers. **Don't repeat root-level content** in a nested file: the nearest-file-wins rule means it is read alone, never merged back with the root.
- Otherwise → update the existing file(s) in place.
## Step 3 — Write or update
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.
AGENTS.md has no required schema. Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists, because a thin accurate file beats a padded generic one. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
## Step 4 — Check for an existing provider file
Look for `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, or similar in the target repo. If one exists 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.
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.
## 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.
Invoke the `agentsmd-audit` skill directly on the AGENTS.md file(s) you just wrote or updated. This closeout is mandatory, not optional, even when the change looks trivial — never sign the work off on your own judgment. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.

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

@@ -23,6 +23,7 @@ Provide the path to the provider-specific file to convert (and the target repo r
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, and the validator flag each needs |
| `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/` |

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

@@ -1,36 +1,28 @@
---
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.
Use when a provider file (CLAUDE.md, .cursor rules, copilot-instructions)
duplicating the repo's AGENTS.md should be cut to a thin adapter.
Not writing the AGENTS file -> `agentsmd-author`.
Not auditing the AGENTS file -> `agentsmd-audit`.
allowed-tools: Bash Read Edit Write
metadata:
category: docs
source_keys:
- adr-0002-0003-two-tier-claude-md
version: "0.1.0"
version: "0.1.1"
---
## 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.
- Assume a provider has no cross-file import mechanism until you have confirmed it has one. Claude Code is the exception, not the rule: a `CLAUDE.md` may consist of nothing but `@path` lines, while the same `@AGENTS.md` line in a Cursor rule or a Copilot instructions file is inert text no tool resolves. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for those providers.
- Works standalone or composed-into by `agentsmd-author` — behave identically either way; 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.
Find the provider instruction file to convert. Before searching, read `references/provider-matrix.md` — skip it only when the target is already a known root `CLAUDE.md`, which is the common case.
Then confirm `AGENTS.md` exists at the repo root. If it does not, stop and tell the user to run `agentsmd-author` first — there is nothing to adapt to.
## Step 2 — Diff and rewrite
@@ -39,6 +31,10 @@ Read the provider file and `AGENTS.md` side by side. Separate 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.
The provider file is the only file this skill ever writes. Never create or edit `AGENTS.md` — not in this step, not in any step, whatever the payoff looks like.
Strip only what is genuinely redundant. Provider-specific material stays even when it is short — the goal is thin, not empty.
## Step 3 — Self-validate
Run the bundled check before finishing — this is the skill's own closeout gate; there is no separate paired audit skill for this concern:
@@ -47,7 +43,7 @@ Run the bundled check before finishing — this is the skill's own closeout gate
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`.
Fix any `FAIL` by editing the provider file, and re-run until it exits `0`. The size `FAIL` advises moving provider-agnostic content into `AGENTS.md`; disregard that half of its wording and delete the redundant lines instead.
## Step 4 — Report

23
plugins/core/skills/provider-adapter-author/references/provider-matrix.md Normal file
View File

@@ -0,0 +1,23 @@
---
source_keys:
- adr-0002-0003-two-tier-claude-md
---
# Known provider instruction files
Which files to look for when detecting a provider-specific instruction file, whether each provider
resolves a cross-file import, and what a thin adapter therefore looks like for it.
| Provider | File(s) | Import syntax | Thin adapter shape | Validator flag |
|---|---|---|---|---|
| Claude Code | `CLAUDE.md` at the repo root, plus any deployed copies | Yes — `@path` lines, e.g. `@AGENTS.md` | One or more `@` import lines; no other content is required | none |
| Cursor | `.cursor/rules/*.mdc` | No | A short sentence pointing at `AGENTS.md`, plus the rule's own frontmatter and provider-specific body | `--no-import-syntax` |
| GitHub Copilot | `.github/copilot-instructions.md` | No | A short sentence pointing at `AGENTS.md`, plus Copilot-only instructions | `--no-import-syntax` |
| Anything else | tool-specific instruction file at whatever path the tool documents | Assume no | Text pointer, as above | `--no-import-syntax` |
A provider not listed here is not evidence it has an import mechanism. Confirm against that tool's
own documentation before emitting an `@`-style line; an unresolved import reads as literal text and
silently drops every rule the adapter was supposed to defer to.
Detection is a search, not a lookup: a repo may hold more than one of these, and each one converts
independently against the same `AGENTS.md`.

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

@@ -5,5 +5,5 @@
- **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
- **Contributing files:** SKILL.md, references/provider-matrix.md
- **Status:** `extracted`

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

@@ -1,6 +1,6 @@
# git-branches
Manage the full lifecycle of git branches — create, switch, delete, rename, and track feature/hotfix/release branches under GitHub Flow or Gitflow.
Manage the full lifecycle of git branches — create, switch, delete, rename, track, merge, and compare feature/hotfix/release branches under GitHub Flow or Gitflow.
## What it does
@@ -12,11 +12,22 @@ This skill handles branch operations within the git workflow suite. It creates b
/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.
Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, track, merge, or compare two branches. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/branch-patterns.md` | Loaded when a branch's base, name prefix, or merge rule depends on GitHub Flow vs. Gitflow |
| `references/branch-operations.md` | Loaded when running a create/switch/delete/rename/track/list action, or resolving `get-intent` |
| `references/merging.md` | Loaded when merging one branch into another or resolving merge conflicts |
| `references/comparing-branches.md` | Loaded when comparing two branches or finding where they diverged |
| `references/orchestrator-contract.md` | Loaded when `git-orchestrate` or another calling agent supplies a structured request rather than prose |
| `references/sources.md` | Research sources backing the branching/gitflow guidance |
## Composition
`git-orchestrate` calls this skill for the branch step of a multi-step workflow and parses its
structured result. Cherry-pick and revert are `git-history`'s; commit authoring and rebase are
`git-commits`'; branch operations against a Gitea-hosted remote are `gitea-branches`'.

103
plugins/git/.apm/skills/git-branches/SKILL.md
View File

@@ -2,13 +2,11 @@
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).
Use when creating, switching, deleting, renaming, tracking, merging, or comparing
local git branches under GitHub Flow or Gitflow.
Not writing or rewriting commits -> `git-commits`.
Not history inspection -> `git-history`.
Not a Gitea remote's branches -> `gitea-branches`.
metadata:
category: git
@@ -21,92 +19,57 @@ metadata:
## 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.
- **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears.
- **A branch and a tag can carry the same name.** Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/<name>` or `refs/tags/<name>`.
- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead.
## Branch Patterns
## Step 1 — Determine the branching pattern
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).
Read `branching_pattern` from the git plugin config (`.claude/plugins/git/config.json`; the plugin root's `config.example.json` shows the shape). Default: `github-flow`. With no config, infer Gitflow from the presence of a `develop` or `release/*` branch, and GitHub Flow otherwise.
**GitHub Flow:**
- Base: `main`
- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
- Merge: fast-forward when possible (preserves linear history)
- Delete after merge
The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`.
**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
## Step 2 — Dispatch on the action
## Workflow
| Action | Reference |
|---|---|
| create, switch, delete, rename, track, list, get-intent | `references/branch-operations.md` |
| merge a branch, resolve merge conflicts | `references/merging.md` |
| compare two branches, find their divergence | `references/comparing-branches.md` |
- [ ] **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.
Load only the file the action needs. A destructive action still passes Step 3 first.
### Command mapping for each action
## Step 3 — Gate destructive operations
- **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.
Before any delete or force-delete that loses history:
## Merging
- [ ] Does the branch track a remote? Warn if so.
- [ ] Are there unpushed commits on it? Warn if so.
- [ ] Did the caller pass `confirm: true`? Fail if not — for a human caller, prompt interactively instead of failing.
Scope: fast-forward/merge-commit mechanics and conflict resolution only. Rebase, cherry-pick, and revert belong to `git-history`.
These gates are passable. The `main`/`master` refusal in Gotchas is not.
- **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.
## Step 4 — Set tracking
**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.
When pushing a branch for the first time, always `git push -u origin <branch>`. Without an upstream, later pushes and pulls either fail or silently target the wrong remote branch, and the caller has no way to tell which happened.
## Comparing Branches
## Step 5 — Return a structured result
- `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.
Return every operation in this shape rather than prose, including failures — a calling agent chains its next operation on the result and cannot parse a sentence.
## 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|...",
"action": "create|switch|delete|rename|track|list|get-intent",
"branch": "<name>",
"message": "descriptive message",
"intent": "<intent if tracked>",
"tracking": "origin/<branch (if set)>",
"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.
When the failure is uncommitted local changes, set `"suggestion": "stash changes and retry"` so the caller can offer recovery rather than surfacing a dead end.
When a calling agent supplies a structured request rather than prose, read `references/orchestrator-contract.md` for the request schema.

34
plugins/git/.apm/skills/git-branches/references/branch-operations.md Normal file
View File

@@ -0,0 +1,34 @@
---
source_keys:
- context7-git-htmldocs
---
# Per-action command mapping
One command per action. Where two forms exist, the first is the default and the second the escape
hatch.
- **create** — `git switch -c <branch> <base>`. Base comes from the config's `base_branch`
(`main` under GitHub Flow, usually `develop` under Gitflow).
- **switch** — `git switch <branch>` moves to an existing local branch; it aborts rather than
clobbering conflicting local changes. `git switch -` returns to the previous branch.
- **delete (local)** — `git branch -d <branch>` refuses when the branch holds unmerged commits,
which is why it is the default. `git branch -D <branch>` forces the deletion and discards that
work — only after the destructive-operation gates pass and `confirm: true` is set.
- **delete (remote)** — `git push origin --delete <branch>`.
- **rename** — `git branch -m <old> <new>`.
- **list** — `git branch` (local), `-a` (local plus remote-tracking), `-r` (remote-tracking only),
`--merged` / `--no-merged` (filter by merge status into the current branch).
- **track** — `git branch --set-upstream-to=origin/<branch>` sets an upstream without pushing.
`git branch -vv` shows the tracking state of every local branch.
## get-intent
Git has no native field for free-text branch metadata, and this skill does not persist any. On
`create`, the `intent` value is only returned in the structured result — the caller decides
whether to store it.
On `get-intent`, either parse the intent back out of the branch-name convention
(`feature/<intent-slug>`) or return `{ "intent": null }` when the caller never persisted the
create-time value. Never fabricate an intent: a downstream commit message built on a guessed
intent is worse than one built on none.

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

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

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

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

29
plugins/git/.apm/skills/git-branches/references/merging.md Normal file
View File

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

16
plugins/git/.apm/skills/git-branches/references/orchestrator-contract.md Normal file
View File

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

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

@@ -12,7 +12,8 @@
- **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)
- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
- references/branch-patterns.md (Gitflow vs. GitHub Flow structure, defaults, and why the two are not mixable)
## atlassian-gitflow-tutorial
@@ -23,7 +24,9 @@
- **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)
- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
- references/branch-patterns.md (Gitflow branch types, base/merge targets, `--no-ff` requirement)
- references/merging.md (`--no-ff` requirement on Gitflow supporting-branch merges)
## gitflow-cheatsheet
@@ -34,7 +37,7 @@
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
**Contributing files:**
- SKILL.md (Branch Patterns — feature/release/hotfix naming conventions)
- references/branch-patterns.md (feature/release/hotfix naming conventions)
## context7-git-htmldocs
@@ -45,4 +48,7 @@
- **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)
- SKILL.md (Gotchas — `git switch` abort-on-conflict behaviour, branch/tag name ambiguity)
- references/branch-operations.md (`git switch`/`git branch` command vocabulary and flags)
- references/merging.md (`git merge` strategies and conflict-resolution commands)
- references/comparing-branches.md (`git log`/`git diff`/`git merge-base` range syntax)

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

@@ -16,9 +16,16 @@ Describe your commit task: create a new commit, amend, squash, or cherry-pick. T
## 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 |
| File | Loaded when |
|------|-------------|
| `SKILL.md` | Always — gotchas, the flow dispatch table, the gates common to every flow, and the output shape |
| `references/create-commit.md` | Composing a new commit from staged changes |
| `references/rewrite-history.md` | Amending, squashing, or folding a `fixup!`/`squash!` commit into an earlier one |
| `references/cherry-pick.md` | Replaying an existing commit onto the current branch |
| `references/conventional-commits-spec.md` | A type, footer, or breaking-change edge case is not obvious — full spec, 11-type set, commitlint constraint table |
| `references/commit-template.md` | Writing a body for a non-trivial commit — Why / Implementation Notes / Impact structure and the full trailer list |
| `references/sources.md` | Research sources and provenance |
## Composition
Part of the git plugin's domain suite. This skill owns commit authoring and history-rewriting operations only; `git-history` inspects history, `git-branches` owns branch lifecycle, and `git-workflow` is the conversational entry point that routes between them.

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

@@ -2,16 +2,13 @@
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.
Use when creating, amending, squashing, or cherry-picking commits, including
writing and validating the Conventional Commits message.
Not history inspection -> `git-history`.
Not branch lifecycle -> `git-branches`.
metadata:
version: "0.1.2"
version: "0.1.3"
category: git
source_keys:
- conventional-commits-spec
@@ -24,92 +21,45 @@ 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.
- **Run git as `rtk git <subcommand>`, never bare `git`** — org convention, in `&&` chains too.
- **Refuse to force-push `main`/`master`** — a rewrite leaves the branch diverged and the reflex is to force it back; safe only where nobody else has based work on it.
- **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning.
## Workflow
## Dispatch
### For creating a new commit:
Read exactly one flow file. Each is self-contained.
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.
| Condition | Flow | Read |
|---|---|---|
| Composing a new commit from staged changes | create | `references/create-commit.md` |
| Amending, squashing, or folding a fixup into an earlier commit | rewrite | `references/rewrite-history.md` |
| Replaying an existing commit onto the current branch | cherry-pick | `references/cherry-pick.md` |
### For amending a commit:
## Gates on every flow
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
1. **Confirmation.** No history rewrite executes without explicit approval from the user or the calling agent. Cherry-pick needs the destination branch confirmed first.
2. **Secrets.** Before any commit or amend, scan the staged diff for anything resembling an API key,
token, password, connection string, or environment-specific config. Stop and flag it rather than
committing it.
3. **Validation.** Check the message against commitlint `config-conventional` before committing. If a type, footer, or breaking-change edge case is not obvious, read `references/conventional-commits-spec.md` — it carries the constraint table, the 11-type set, and the footer token rules.
4. **SemVer impact.** Report the bump the commit implies: `feat` → MINOR, `fix`/`perf`/`revert` → PATCH, any breaking change → MAJOR, everything else → none. Callers decide releases from this, so never omit it.
5. **Conflicts.** If a rebase or cherry-pick halts, offer resolution or an abort. Do not resolve automatically without confirmation.
### For squashing commits (interactive rebase):
## Output
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:
For an agent caller, return:
```json
{
"operation": "create|amend|squash|cherry-pick",
"status": "success|conflict|rejected",
"message": "Commit message or error description",
"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>"]
}
"breaking_change": false,
"confirmation_required": false,
"details": { "type": "feat", "scope": "api", "description": "add user authentication" }
}
```
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`.
For a human caller, show the same fields as a prose preview with a confirmation prompt.

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

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

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

@@ -7,7 +7,7 @@ source_keys:
Use this structure for the body/footer of any non-trivial commit (skip sections that don't apply — do not leave placeholders in the actual commit).
```
```text
<type>(<scope>): <concise summary>
```
The header is required. Describe the intended outcome, not the implementation.
@@ -53,7 +53,7 @@ Omit if there are no noteworthy impacts.
Structured metadata for traceability and tooling. Use only the trailers that apply:
```
```text
Fixes:
Refs:
ADR:

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

@@ -10,7 +10,7 @@ Conventional Commits is a lightweight convention on top of commit messages that
## Message Format
```
```text
<type>[optional scope]: <description>
[optional body]
@@ -58,20 +58,20 @@ A `BREAKING CHANGE` footer or `!` on **any** type always triggers a MAJOR bump.
Two equivalent notations:
**`!` in header** (preferred — visible in `git log --oneline`):
```
```text
feat!: drop support for Node 6
feat(api)!: remove deprecated endpoint
```
**`BREAKING CHANGE` footer** (machine-readable body):
```
```text
feat: allow config to extend other configs
BREAKING CHANGE: `extends` key now used for extending config files
```
**Both together** (most explicit):
```
```text
feat!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
@@ -85,7 +85,7 @@ Rules:
## Footer Token Rules
```
```text
<token>: <value>
<token> #<value> # for issue references
```
@@ -96,7 +96,7 @@ Rules:
- Blank line required before the footer block.
Valid footer examples:
```
```text
Reviewed-by: Z
Refs: #123
Co-authored-by: Alice <alice@example.com>
@@ -106,29 +106,29 @@ BREAKING CHANGE: the `--format` flag now requires a value
## Examples
Minimal — no body, no footer:
```
```text
docs: correct spelling of CHANGELOG
```
With scope:
```
```text
feat(lang): add Polish language
```
Breaking change via `!`:
```
```text
feat!: send an email to the customer when a product is shipped
```
Breaking change via footer:
```
```text
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
```
Multi-paragraph body with multiple footers:
```
```text
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
@@ -142,7 +142,7 @@ Refs: #123
```
Revert:
```
```text
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868

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

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

37
plugins/git/.apm/skills/git-commits/references/rewrite-history.md Normal file
View File

@@ -0,0 +1,37 @@
---
source_keys:
- org-commit-conventions
- context7-git-htmldocs
---
# Rewriting existing commits
Every flow on this page rewrites history. None of them runs before the caller has explicitly approved it, and none is followed by a force-push to `main`/`master` — refuse that and explain why instead.
## Amend the last commit
1. Stage the new changes, or the changes that undo something.
2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is.
3. If the message should change, show the current one and prompt for the replacement.
4. The branch has now diverged from its remote. Amending is safe only on a branch nobody else has based work on; on `main`/`master`, refuse the force-push and explain, rather than warning and proceeding.
## Fold a commit into an earlier one (autosquash — preferred)
Prefer this whenever a commit is written to be folded, because git does the marking:
1. `rtk git commit --fixup=<commit>` keeps the target's message; `rtk git commit --squash=<commit>` lets you edit the combined message later. Both prefix the message with `fixup!`/`squash!` and name the target commit.
2. Get explicit approval — the rebase still rewrites history.
3. Run `rtk git rebase --autosquash HEAD~N`, or `-i --autosquash` to review the plan first. Git reorders the tagged commits against their targets automatically.
## Squash by hand (interactive rebase)
Use this when the commits were not tagged at commit time. **Interactive rebase has no undo once `rebase -i` starts — `git reflog` is the recovery path.**
1. Identify the commits to squash — typically the last N on the current branch.
2. Get explicit approval.
3. Run `rtk git rebase -i HEAD~N`, marking the older commits `squash` to keep their messages for editing, or `fixup` to discard them.
4. Compose the combined message when the rebase stops to ask. For a non-trivial combined message, follow the structure in `references/commit-template.md`.
## When a rebase halts on a conflict
Offer conflict resolution or `rtk git rebase --abort`. Do not resolve conflicts automatically without confirmation.

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

@@ -7,34 +7,34 @@ source_keys:
- context7-git-htmldocs
---
# Research Sources for git:commits Skill
# 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.
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
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md, references/create-commit.md
- **Status:** extracted
## commitlint-config-conventional
- **Description:** commitlint config-conventional preset — validation constraints (max 100 chars header, no trailing periods, lowercase type, 11-type set enforcement)
- **Research doc:** plugins/git/docs/research/docs/git/commits.md § "commitlint Constraints (`config-conventional`)"
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md, references/create-commit.md
- **Status:** extracted
## org-commit-conventions
- **Description:** Organization commit message body template and git conventions (atomic commits, no `--no-verify`, no force-push main/master, `rtk git` wrapper) — content fully embedded in this skill; the org's `core/instructions/git.md` and `core/instructions/commits.md` are provenance only and are not a live dependency
- **Research doc:** core/instructions/commits.md, core/instructions/git.md (org convention, not part of the plugin's research corpus)
- **Contributing files:** SKILL.md, references/commit-template.md
- **Contributing files:** SKILL.md, references/commit-template.md, references/create-commit.md, references/rewrite-history.md
- **Status:** extracted
## context7-git-htmldocs
- **Description:** Official Git HTML documentation — `git commit --squash`/`--fixup` and `git rebase --autosquash` flag semantics
- **Research doc:** plugins/git/docs/research/docs/git/cli-reference.md
- **Contributing files:** SKILL.md
- **Description:** Official Git HTML documentation — `git commit --squash`/`--fixup`, `git rebase --autosquash`, and `git cherry-pick` range and abort semantics
- **Research doc:** plugins/git/docs/research/docs/git/cli-reference.md § "Committing", § "Rebasing", § "Cherry-picking"
- **Contributing files:** SKILL.md, references/rewrite-history.md, references/cherry-pick.md
- **Status:** extracted

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

@@ -6,6 +6,10 @@ Inspect git history — log queries, bisect, and locating problematic commits.
This skill handles history inspection within the git workflow suite. It queries logs with pickaxe/line-range/custom formats, runs bisect to find bug-introducing commits, and locates commits for downstream cherry-picking or reverting. It returns structured results for agent composition. Rebase, squash, fixup, and other history-rewriting operations are owned by git-commits, not this skill.
## Composition
`git-branches` delegates cherry-pick and revert here (see `git-branches`'s `references/merging.md`), which is why this skill carries those two operations rather than treating them as out of scope. They are general git knowledge, not drawn from the `history-inspection.md` research corpus. Server-side commit history on a Gitea-hosted repository belongs to `gitea-branches`; this skill reads the local working copy.
## Usage
```
@@ -19,6 +23,7 @@ Describe your history task: search logs, bisect for a regression, or locate a sp
| 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/bisect.md` | Loaded when the entry procedure is bisect: manual and automated flows, exit codes, skip, replay, narrowing, custom terms |
| `references/git-log-format.md` | Loaded when a log or diff flag needs looking up: format placeholders, presets, diff-filter letters, `-L` syntax, ancestry filters, pickaxe binary-file behaviour, diff output-control flags |
| `references/sources.md` | Research sources and provenance |
| `references/README.md` | Index of the references directory |

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

@@ -2,7 +2,10 @@
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.
Use when investigating git history — querying logs, tracing when a change
landed, bisecting the commit that broke something, or locating one to
revert or backport. Not authoring or rebasing commits -> `git-commits`.
Not history on a Gitea server -> `gitea-branches`.
metadata:
category: git
@@ -16,81 +19,47 @@ 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.
- `-S"string"` matches only where the string's *count* changed, so a line edited in place matches `-G"regex"` and not `-S`. Reach for `-G` whenever the string may have moved rather than appeared.
- `--follow` traces renames for exactly one path. Given several paths or a glob it fails instead of degrading, so run it once per file.
- Under `git bisect run`, exit `128` or above **aborts the session** rather than marking the commit bad, so a crashing test script ends the search silently.
- Bisect answering "cannot find exact culprit" beside skipped commits is a complete result: it is as precise as the skip range allows.
## Query Logs and Locate Commits
## Step 1 — Pick the entry procedure
Default to `git log --oneline` for quick inspection. For deeper queries:
| What is known | Procedure |
|---|---|
| Content, a file, or a line range to search for | Query the log — Step 2 |
| Nothing to search for — only that the behaviour changed between two points | Bisect — read `references/bisect.md` |
| The commit itself, already identified | Step 3 |
- **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.
## Step 2 — Query the log
## Bisect to Find Blame Commit
Default to `git log --oneline`, then narrow by whatever is known:
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).
- **Content**: `git log -S"string"`, or `-G"regex"` to match any diff line. `--pickaxe-regex` makes the `-S` argument a POSIX ERE; `--pickaxe-all` shows every file in a matching changeset.
- **A line or function**: `git log -L <start>,<end>:<file>` or `git log -L :<function>:<file>`. Confirm the range resolves before reporting on it — an off-by-one silently omits the target.
- **A file across renames**: `git log --follow -- <file>`. Without `--follow` the history stops at the rename boundary.
- **Mainline only**: `--first-parent` follows the integration branch and skips commits merged in from side branches.
- **Structured output**: `git log --format="%h | %s | %an (%ar)"`.
**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
If you need the placeholder catalogue, format presets, `--diff-filter` letters, full `-L` syntax, ancestry filters, pickaxe binary-file behaviour, or `git diff` output-control flags such as `--stat`, `--word-diff` and the whitespace options, read `references/git-log-format.md`.
## Step 3 — Act on a located commit
Offer the operation and its consequence; run it only once the user has chosen.
- `git cherry-pick <commit>` copies the commit's changes onto the current HEAD — for backporting a fix to another branch.
- `git revert <commit>` adds a new commit undoing it — for un-applying merged work without rewriting history.
- `git blame <file>` attributes each line to the commit that last touched it, when the question is which commit introduced one specific line.
For diff output control on the located commit, read `references/git-log-format.md`.
## Step 4 — Return the result
Report each located commit in this shape, so a calling agent can act on it without reparsing raw log output:
```text
<sha> — <subject>
<author> (<relative date>)
Recommendation: <action or "none">
```
**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`.

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

@@ -12,4 +12,5 @@ This directory contains provenance metadata and research sources for the `git-hi
## 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
- `bisect.md` — The full `git bisect` procedure: manual and automated flows, exit-code semantics, skip and replay, narrowing options, and custom good/bad terms
- `git-log-format.md` — Full `git log` format placeholder catalogue, named format presets, `--diff-filter` letters, `-L` line-range syntax, ancestry filters, pickaxe binary-file behaviour, and `git diff` output-control flags

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

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

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

@@ -88,7 +88,7 @@ source_keys:
| `%GK` | signing key ID |
**Trailers:**
```
```text
%(trailers[:key=<k>][,only][,separator=<s>][,unfold][,keyonly][,valueonly])
```

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

@@ -12,7 +12,7 @@ Git bisect documentation covering binary search through commit history to find t
- **Research doc:** plugins/git/docs/research/docs/git/history-inspection.md
- **Doc heading:** `## git bisect`
- **Contributing files:** SKILL.md
- **Contributing files:** SKILL.md, references/bisect.md
## git-scm-log-docs
@@ -28,4 +28,4 @@ Git diff documentation covering output control (--stat, --name-only, --name-stat
- **Research doc:** plugins/git/docs/research/docs/git/history-inspection.md
- **Doc heading:** `## git diff — Output Control`
- **Contributing files:** references/git-log-format.md
- **Contributing files:** SKILL.md, references/git-log-format.md

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

@@ -18,7 +18,17 @@ Describe your remote operation: add a remote, push, pull, fetch, or configure tr
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `SKILL.md` | Skill instructions for agents — force-push gate, dispatch table, return format |
| `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/remote-config.md` | Read when adding, removing, renaming, inspecting or re-pointing a remote, or configuring tracking, mirroring, or `set-url` |
| `references/fetch.md` | Read when fetching or pruning remote-tracking refs, or doing a shallow or partial fetch |
| `references/push.md` | Read when pushing branches or tags, writing refspecs, or force-pushing |
| `references/pull.md` | Read when integrating remote changes into the current branch, including the divergence rule |
| `references/sources.md` | Research sources and provenance |
## Composition
Callers that need submodule initialization after a `--recurse-submodules` pull hand off to
`git-submodules`; local-only work (commits, branches, history) belongs to `git-commits`,
`git-branches`, and `git-history`. The `git-workflow` skill routes humans here for any
remote-touching request.

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

@@ -2,13 +2,11 @@
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.
Use when a git operation — remote config, fetch, push, or pull — touches a
remote, even when the user does not name it.
Not local commits -> `git-commits`.
Not local branches -> `git-branches`.
Not submodule pointers -> `git-submodules`.
metadata:
category: git-workflow
@@ -23,91 +21,29 @@ metadata:
## 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.
- **`--force-with-lease` alone is not safe** — background processes (IDE plugins, cron jobs) running `git fetch` silently defeat the protection. Combine it with `--force-if-includes`, or pin the explicit `--force-with-lease=<ref>:<sha>` form.
- **Prune does not touch tags by default** — `git fetch --prune` leaves orphaned tags behind. Use `--prune --prune-tags`, or set `fetch.pruneTags true`.
- **Pull defaults shift between Git versions** — older ones default to merge, newer to `--ff-only`. Set `pull.ff only` explicitly rather than trusting the installed default.
## Operations
## Step 1 — Clear the force-push gate
### Remote Management
`main` and `master` are a hard refusal: decline a force-push targeting either, whatever confirmation accompanies it, because no local approval can restore what the remote loses. On any other branch, `git push --force` and `-f` run only after the caller passes `confirm: true` for that specific push — for a human caller, prompt instead of failing.
Use these to configure which remotes you push to and pull from:
## Step 2 — Dispatch
- **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`)
Read the row matching the operation, and only that row — each file is self-contained. A task spanning two operations reads both.
### 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 |
| Operation | Read |
|---|---|
| `<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>` |
| Add, remove, rename, inspect, or re-point a remote; tracking, mirror, and `set-url` config | `references/remote-config.md` |
| Fetch or prune remote-tracking refs; shallow or partial fetch | `references/fetch.md` |
| Push branches or tags; refspecs; force-push | `references/push.md` |
| Pull — integrate remote changes into the current branch | `references/pull.md` |
### Pull Operations
## Step 3 — Return format
Use these to fetch and integrate remote changes. Default strategy: `--ff-only` (fail if diverged, forcing a conscious choice).
For agent callers, return:
- **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,
@@ -116,8 +52,8 @@ Return structured output:
"branch": "main",
"output": "...",
"warnings": ["force-with-lease not confirmed"],
"recommendations": ["set pull.ff=only globally"]
"recommendations": ["set `pull.ff only` so the default does not vary by Git version"]
}
```
On failure, include `error` field with root cause and recovery suggestion.
On failure, set `success: false` and add an `error` field holding the root cause and a recovery suggestion.

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

@@ -14,4 +14,7 @@ This directory contains provenance metadata and research sources for the `git-re
## 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
- `remote-config.md` — Remote add/remove/rename/inspect, tracking and mirror options, housekeeping, and the full `set-url` form
- `fetch.md` — Fetch and prune options, shallow and partial fetch, the default fetch refspec
- `push.md` — Push options, refspec syntax, force-push safety in full, server-side deny policies
- `pull.md` — Pull strategies, submodule caveat, the divergence rule, and pull config precedence

29
plugins/git/.apm/skills/git-remotes/references/fetch.md Normal file
View File

@@ -0,0 +1,29 @@
---
topic: fetch
source_keys:
- git-scm-fetch-docs
- context7-git-htmldocs
---
# Fetching
Fetch updates remote-tracking branches (`refs/remotes/<name>/*`) and never modifies a local branch, so it is always safe to run.
- **One remote**: `git fetch <remote>` — all branches
- **One branch**: `git fetch <remote> <branch>` — the result lands in `FETCH_HEAD`, not a tracking ref
- **All remotes**: `git fetch --all`
- **Prune properly**: `git fetch --all --prune --prune-tags` cleans stale branches *and* tags
- **Auto-prune**: `git config --global fetch.prune true` (or `remote.<name>.prune` to scope it to one remote), and `fetch.pruneTags true` for tags
## Shallow and partial fetch
```bash
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 is `+refs/heads/*:refs/remotes/<name>/*`. The leading `+` forces the update — remote-tracking branches always mirror the remote exactly and offer no protection for local history.

37
plugins/git/.apm/skills/git-remotes/references/pull.md Normal file
View File

@@ -0,0 +1,37 @@
---
topic: pull
source_keys:
- git-scm-pull-docs
- context7-git-htmldocs
---
# Pulling
Default strategy: `--ff-only`. It fails on divergence, which forces a conscious choice instead of an accidental merge commit.
- **Fast-forward only**: `git pull --ff-only` — the recommended default
- **Rebase**: `git pull --rebase` replays your commits on top for linear history, but rewrites SHAs. Verify nothing being replayed has been pushed: rebasing published commits breaks everyone downstream.
- **Merge**: `git pull --no-rebase` — three-way merge commit, preserves original commits, non-linear
- **Rebase preserving merges**: `git pull --rebase=merges` keeps intentional local merge commits during the replay
- **Stage without committing**: `git pull --squash` collapses incoming commits into staged changes; you write the message
- **Merge strategy**: Git 2.34+ defaults to `ort` (`recursive` is now an alias for it). Strategy options such as `-X ours`, `-X theirs`, `-X ignore-space-change` pass through unchanged.
- **Submodules**: `--recurse-submodules` only fetches submodules already checked out. Newly added ones are not initialized — use the `git-submodules` skill for those.
## On divergence
A pull that diverges with no strategy configured fails, and that failure is the useful outcome. Report the divergence and the three ways out — `--ff-only`, `--rebase`, `--no-rebase` — and let the caller choose. Auto-merging a diverged branch buries a decision that belongs to the human.
## Config precedence
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 pull.ff only # deterministic default across Git versions
git config --global pull.rebase true
git config branch.develop.rebase false # develop always merges, regardless of the global default
```

67
plugins/git/.apm/skills/git-remotes/references/push.md Normal file
View File

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

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

@@ -0,0 +1,39 @@
---
topic: remote-config
source_keys:
- git-scm-remote-docs
- context7-git-htmldocs
---
# Remote configuration
Which remotes exist, where they point, and what they track.
`git remote show <name>` needs network access — use `-n` for cached data offline, or `git remote -v`, which lists URLs without querying.
## Add, remove, rename, inspect
- **Add**: `git remote add <name> <url>`, or `-f` to fetch immediately
- **Remove**: `git remote remove <name>` — deletes the remote, all its tracking refs, and its config
- **Rename**: `git remote rename <old> <new>`
- **Inspect**: `git remote -v` (URLs, offline) or `git remote show <name>` (live tracking status)
- **Effective URLs**: `git remote get-url <name>` shows the URL after `insteadOf` rewrites; `git remote get-url --push --all <name>` lists every push URL
## Tracking, mirroring, housekeeping
- **Track one branch**: `git remote add -t <branch> <name> <url>` (repeatable); `--no-tags` suppresses tag import entirely
- **Mirror**: `--mirror=fetch` mirrors all refs locally (bare repos only); `--mirror=push` makes every push behave like `--mirror`
- **Prune stale tracking refs without fetching**: `git remote prune <name>`, with `--dry-run` to preview
- **Default branch pointer**: `git remote set-head <name> -a` (auto-detect, needs a prior fetch), `... <branch>` (explicit), `... -d` (delete `refs/remotes/<name>/HEAD`)
## `set-url` — full form
```bash
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; `--push` cannot do this.

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

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

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

@@ -12,8 +12,7 @@
- **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)
- references/remote-config.md
---
@@ -26,8 +25,8 @@
- **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)
- SKILL.md (Gotchas — prune does not touch tags)
- references/fetch.md
---
@@ -40,8 +39,8 @@
- **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)
- SKILL.md (Gotchas — `--force-with-lease` caveat; Step 1 force-push gate)
- references/push.md
---
@@ -54,8 +53,8 @@
- **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)
- SKILL.md (Gotchas — pull default drift)
- references/pull.md (divergence rule; strategies; config precedence)
---
@@ -69,3 +68,7 @@
**Contributing files:**
- SKILL.md (all sections)
- references/remote-config.md
- references/fetch.md
- references/push.md
- references/pull.md

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

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

95
plugins/git/.apm/skills/git-submodules/SKILL.md
View File

@@ -2,7 +2,10 @@
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.
Use when managing Git submodules — adding, updating, pinning, inspecting,
repointing, or removing a nested repository inside a superproject.
Not multiple checkouts of one repo -> `git-worktrees`.
Not the superproject's own remotes -> `git-remotes`.
metadata:
category: git
@@ -10,82 +13,50 @@ metadata:
- 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.
- **`update` leaves the submodule in detached HEAD.** Branch inside the submodule before editing, or the work is unreachable once the pointer moves.
- **Push the submodule before the superproject.** The superproject stores only a SHA, and one missing from the submodule's remote breaks every collaborator's `update`.
- **`--recursive` is never the default.** Subcommands stop one level deep, so nested submodules go stale silently.
- **`git rm` leaves `.git/modules/<name>/` behind.** Nothing cleans it up, and it blocks re-adding a submodule there.
## Conventions
## Working rules
- **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.
Run `rtk git` from the superproject root. Enter the submodule directory only for commits and pushes
that belong to the submodule's own history — the two repositories have independent histories, and
the same command from the wrong directory writes to the wrong one.
## Operations
Before committing a superproject pointer, run `rtk git submodule status --recursive`. Prefixes: `-`
not initialized, `+` working tree differs from the recorded commit, `U` merge conflict. Add
`--cached` to read the SHAs the superproject index will record rather than the working-tree state.
A `-dirty` suffix means uncommitted changes inside the submodule, and committing the pointer over
them pins a state nobody else can reproduce.
- **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`.
To run one command across every submodule: `rtk git submodule foreach --recursive '<cmd>'`. Inside
`<cmd>`, Git sets `$name`, `$sm_path`, `$displaypath`, `$sha1` and `$toplevel`; append `|| :` to
continue past a failure instead of aborting the traversal.
## Configuration
## Dispatch
`.gitmodules` (version-controlled, shared with collaborators):
Read only the row that matches the request.
| Key | Purpose |
| Task | Reference |
|---|---|
| `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 |
| Clone a superproject with submodules, or add, initialize, update or re-pin one | `references/setup-and-update.md` |
| Change where a submodule points — `sync`, `set-url`, `set-branch`, a local mirror override, `absorbgitdirs`, or any `.gitmodules` / `.git/config` key | `references/urls-and-config.md` |
| Remove a submodule, or `deinit` one without removing it | `references/removal.md` |
`.git/config` (local only, populated by `init`):
Removal and `deinit` are destructive: state what will be deleted and get confirmation before
executing.
| 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. |
## Output format
```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>
operation: <clone|add|init|update|status|sync|set-url|set-branch|absorbgitdirs|deinit|remove>
status: <success|error|partial>
message: <human-readable summary>
message: <one line; include git's own output on error>
details:
- <submodule-path>: <state>
conflicts: [<submodule-path>, ...] # if any
next_step: <recovery action if applicable>
conflicts: [<submodule-path>, ...]
next_step: <recovery action, when status is error or partial>
```
For errors, include the git command output and recommend recovery (e.g., `git submodule deinit`, force-update, or URL override).

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

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

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

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

74
plugins/git/.apm/skills/git-submodules/references/setup-and-update.md Normal file
View File

@@ -0,0 +1,74 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Adding, initializing, updating and pinning submodules
## Clone a superproject that already has submodules
```bash
git clone --recurse-submodules <url> # Git 2.13+, one step
# or, against an existing clone
git submodule update --init --recursive
```
## Add a dependency as a submodule
```bash
git submodule add <url> <path>
git commit -m "chore: add <name> as submodule"
```
`add` stages a `.gitmodules` entry and a gitlink — the commit is still required. Flags:
| Flag | Meaning |
|---|---|
| `-b <branch>` | Track a branch (`submodule.<name>.branch`) instead of only a pinned commit |
| `--depth <n>` | Shallow clone |
| `-f` | Force past a gitignored path or a name conflict |
| `--name <name>` | Logical name differing from the path |
## Initialize without cloning
`git submodule init [<path>...]` copies submodule URLs from `.gitmodules` into `.git/config` and
does nothing else. This is the point at which a local URL override can be edited before any fetch
happens. If a local mirror override is wanted, read `references/urls-and-config.md` before running
`update`. Use `update --init` to run both steps at once.
## Update
`git submodule update --init --recursive` is the common case: it clones what is missing and checks
out the commit the superproject recorded, in detached HEAD.
| Flag | Meaning |
|---|---|
| `--init` | Run `init` first, avoiding a separate step |
| `--remote` | Use the submodule's remote branch tip instead of the superproject's recorded commit |
| `--checkout` | Detached HEAD at the recorded commit (default) |
| `--rebase` | Rebase the current branch onto the recorded commit |
| `--merge` | Merge the recorded commit into the current branch |
| `--recursive` | Operate on nested submodules |
| `--jobs <n>` | Parallel clone (defaults to `submodule.fetchJobs`) |
| `-N` / `--no-fetch` | Skip the remote fetch |
| `-f` | Discard local changes in the submodule working tree |
| `--depth <n>` | Shallow clone |
| `--filter <spec>` | Partial clone filter |
## Keep submodules pinned to the recorded commit
```bash
git submodule update --recursive # after every git pull
git config submodule.recurse true # or do it automatically on pull/push/checkout
```
## Move the pin forward to the tracked branch tip
```bash
git submodule update --remote --merge --recursive
git commit -am "chore: update submodules to latest"
```
`--remote` requires `submodule.<name>.branch`; without it Git falls back to the remote's default
branch. Commit the superproject afterwards or the new pin is lost on the next `update`.

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

@@ -14,7 +14,9 @@ source_keys:
**Contributing files:**
- SKILL.md (all sections)
- references/submodules.md (all sections)
- references/setup-and-update.md (all sections)
- references/urls-and-config.md (all sections)
- references/removal.md (all sections)
---

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

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

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

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

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

@@ -4,7 +4,7 @@ Human-friendly interface for interactive git workflows with conversational promp
## 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.
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. The org's non-negotiable git rules live in `references/hard-rules.md` and are loaded only when a request could conflict with one.
## Usage
@@ -20,5 +20,6 @@ Describe your git workflow: commit, create a branch, rebase, inspect history, ma
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `README.md` | This file |
| `references/hard-rules.md` | The org's non-negotiable git rules; read when a request creates, amends, or rewrites a commit, pushes, or touches hooks, config, or credentials |
| `references/README.md` | Describes the references directory contents |
| `references/sources.md` | Research sources and provenance |

77
plugins/git/.apm/skills/git-workflow/SKILL.md
View File

@@ -2,12 +2,9 @@
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.
Use when a human wants to work through local git interactively — commits, branches, history,
submodules, worktrees, or remotes. Not an agent caller needing deterministic execution ->
`git-orchestrate`. Not server-side Gitea work -> `gitea-workflow`.
metadata:
category: git
@@ -21,45 +18,41 @@ metadata:
## 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.
- Session context built during one multi-step request — branch names, the chosen base, the commit
strategy — persists for that request and then clears. Do not re-ask the user for a decision they
already gave you earlier in the same workflow.
- Run parent-repo commands through `rtk git <command>`, never bare `git <command>`. This is a
mandated org wrapper, not a style preference. Submodule-specific commands run from inside the
submodule's own directory instead.
## 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.
1. **Parse intent** — extract the operation (commit, create branch, rebase, inspect history, …)
and any options the user named.
2. **Check the hard rules** — if the request creates, amends, or rewrites a commit, pushes, or
touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule
before acting, not after.
3. **Read the repo** — current branch, working-tree state, and which branching model the repo
follows (the orchestrator reads `branching_pattern` from plugin config; infer from branch names
if absent); the last of those decides which tips are worth offering.
4. **Gate destructive operations** — before force-push, branch deletion, rebase, or
force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user
declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not
confirmations: never offer "Proceed?" for a force-push of `main` or `master`.
5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or
inferred), `context` (step 3 plus the session context), and `confirm: true` only for a
destructive op the user approved in step 4.
6. **Clarify when the orchestrator asks for more** — put its question to the user in plain
language ("Which branch should this be based on?") and loop back to step 5 with the answer.
7. **Report the outcome** — on success, the result and what changed, in plain language; on
failure, the error reason and a recovery action.
## Interaction style
- **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.
The caller is a human, so the interaction is the point. Explain each step and why it happens ("I'm
squashing your last 3 commits into one clean commit" beats "Squashing commits"), show progress as
you go, and prefer natural language to raw command lines.
Match tips to the repo's branching model rather than offering generic advice: on a Gitflow repo,
feature branches come off `develop` and `main` tracks only released code; on a trunk-based or
GitHub Flow repo, short-lived branches off `main` keep merges small and reviewable.

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

@@ -9,8 +9,11 @@ source_keys:
# References
This directory contains provenance metadata and research sources for the `git-workflow` skill.
This directory contains the org git rules and the provenance metadata for the `git-workflow`
skill.
## Files
- `hard-rules.md` — The org's non-negotiable git rules, loaded when a request creates, amends, or
rewrites a commit, pushes, or touches hooks, config, or credentials
- `sources.md` — Extracted research sources and their contributing documents

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

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

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

@@ -56,4 +56,5 @@
- **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)
- references/hard-rules.md (whole file — the eight hard rules and the conflict-handling rule)
- SKILL.md (Gotchas — `rtk git` wrapper note)

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

@@ -4,7 +4,7 @@ Manage git worktrees to enable multi-branch parallel development across isolated
## 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.
This skill handles worktree operations within the git workflow suite. It creates, lists, locks/unlocks, moves, removes, prunes, and repairs worktrees — letting an agent work on multiple branches simultaneously without stashing. It returns structured results (paths, branches, lock status) suitable for agent composition. For multi-step flows spanning branch strategy plus worktree setup, `git-workflow` handles the broader orchestration and delegates the worktree mechanics here.
## Usage
@@ -18,7 +18,7 @@ Describe your worktree task: create a worktree for a branch, list existing workt
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `SKILL.md` | Dispatch table, per-operation gates, and the report format |
| `references/README.md` | Describes the references directory contents |
| `references/worktrees.md` | Full `add` flag table, sparse-checkout, removable-media locking, remote disambiguation, configuration |
| `references/worktrees.md` | Read when an operation needs more than the dispatch table: shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout, removable-media locking, remote disambiguation, where to run `repair` from, config keys, and the emergency-fix and PR-review patterns |
| `references/sources.md` | Research sources and provenance |

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

@@ -2,11 +2,10 @@
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.
Use when working on several branches at once without stashing.
Create, list, lock, move, remove, prune, or repair git worktrees.
Not ordinary branch switching or checkout -> `git-branches`.
Not interactive multi-step git guidance -> `git-workflow`.
metadata:
category: git
@@ -14,101 +13,44 @@ metadata:
- 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.
- **A branch can be checked out in only one worktree at a time.** `git worktree add` on an already-checked-out branch fails; `--force` is the only override, so use it only deliberately.
- **Never `rm -rf` a worktree directory.** That strands metadata in `$GIT_DIR/worktrees/`. Use `git worktree remove`, or `git worktree prune` afterwards.
- **Submodules break worktree support.** A worktree containing submodules cannot be moved at all, and needs `--force` to remove.
- **`extensions.worktreeConfig = true` is a one-way door.** It costs compatibility with older Git and forces `core.bare`/`core.worktree` into `config.worktree`. Leave it off unless per-worktree config is needed.
## Common Operations
## Step 1 — Dispatch
**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.
| Operation | Run |
|---|---|
| Create on an existing branch | `git worktree add <path> <branch>` |
| Create on a new branch | `git worktree add -b <branch> <path>` |
| Create on the branch named after the path basename | `git worktree add <path>` — checks that branch out if it exists, else creates it from HEAD |
| Create and reset an existing branch to HEAD — discards its commits | `git worktree add -B <branch> <path>` |
| Create tracking a remote branch | `git worktree add <path> <remote>/<branch>` |
| Throwaway experiment, no branch | `git worktree add -d <path>` |
| List | `git worktree list -v`, or `--porcelain -z` to parse |
| Lock or unlock | `git worktree lock [--reason <str>] <path>` / `git worktree unlock <path>` |
| Move | `git worktree move <from> <to>` |
| Remove | `git worktree remove <path>` |
| Prune stale metadata | `git worktree prune --dry-run`, then without the flag |
| Repair after a manual move | `git worktree repair [<path>]` — from the main worktree to fix all links, or from the moved worktree itself |
**Create-or-reset a branch**: `git worktree add -B <branch> <path>` — like `-b` but resets the branch to HEAD if it already exists.
If the operation needs anything the table does not carry — the full `add` flag
table, orphan branches, sparse-checkout, locking for removable media, remote
disambiguation across several remotes, worktree config keys, or the worked
emergency-fix and PR-review patterns — read `references/worktrees.md`.
**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`.
Gates:
**Throwaway experiment in detached HEAD**:
```bash
git worktree add -d ../experiment # or --detach
# experiment freely, no branch created
git worktree remove ../experiment
```
- **`move`, `remove` — the main worktree cannot be moved or removed.** Only linked worktrees, the ones `git worktree add` created, are candidates.
- **`add`, `move`, `remove` — escalate force flags one step at a time.** `-f` overrides a safeguard such as an unclean tree; `move` and `remove` need `-ff` on top of that when the worktree is locked. Confirm with the user before either — both discard state.
- **`lock`, `move`, `remove`, `repair` — identify a worktree by full path, unique basename, or unique partial path.** An ambiguous name errors rather than picking; `git worktree list` shows the usable identifiers.
- **`add` — lock at creation, not after.** `git worktree add --lock` is atomic, where add-then-`lock` leaves a window in which the worktree is unprotected.
**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
```
## Step 2 — Report
**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>
@@ -116,10 +58,8 @@ worktrees:
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.
Derive those fields from `git worktree list --porcelain -z`. For a single
operation, report its outcome instead — `created: true`, `moved: true`,
`removed: true`.

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

@@ -10,4 +10,4 @@ This directory contains provenance metadata and research sources for the `git-wo
## 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
- `worktrees.md` — Shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout setup, removable-media locking, remote-branch disambiguation, where to run `repair` from, the config key reference, and the emergency-fix and PR-review workflow patterns

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

@@ -12,5 +12,5 @@
- **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)
- SKILL.md (Gotchas, Step 1 dispatch table and per-operation gates, Step 2 report format)
- references/worktrees.md (shared vs. per-worktree state, `add` command forms, full `add` flag table, orphan branches, sparse-checkout, removable media, remote disambiguation, `repair` invocation directory, configuration, workflow patterns)

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

@@ -4,6 +4,27 @@ source_keys:
- git-scm-worktree-docs
---
## Shared vs. per-worktree state
All worktrees share one object store, one config, and most refs under `refs/`. Each worktree keeps
its own `HEAD`, index, and per-worktree metadata (`ORIG_HEAD`, `MERGE_HEAD`, `refs/bisect/`,
`refs/worktree/`, `refs/rewritten/`) under `$GIT_DIR/worktrees/<name>/`. Exactly one **main
worktree** exists per repo — the one `git init` or `git clone` produced — and it cannot be removed
or moved. Every other worktree is a **linked worktree** created by `git worktree add`.
## `add` forms
```bash
git worktree add <path> <branch> # check out an existing branch — non-destructive
git worktree add -b <branch> <path> # create a new branch; fails if it exists
git worktree add <path> # branch named after $(basename <path>): checked out
# if it exists, else created from HEAD
git worktree add -B <branch> <path> # create the branch, or reset an existing one to HEAD,
# discarding the commits it carried
git worktree add <path> <remote>/<branch> # track a remote branch
git worktree add -d <path> # detached HEAD, no branch
```
## Full `add` flag table
| Flag | Meaning |
@@ -52,6 +73,16 @@ 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.
## Repair after a manual move
```bash
git worktree repair # run from the main worktree: fixes the links to every linked worktree
git worktree repair <path> # run from a moved linked worktree: fixes its own pointer back to main
```
`repair` reestablishes the bidirectional pointers a manual move breaks, but only for the side it is
run from. Run it from the wrong directory and it reports nothing and fixes nothing.
## Configuration
| Key | Effect |
@@ -61,3 +92,25 @@ For ambiguous names across remotes, `checkout.defaultRemote` config disambiguate
| `gc.worktreePruneExpire` | How long before stale worktree metadata is pruned by `git gc` |
| `extensions.worktreeConfig` | Enable per-worktree config scope (`config.worktree` file) — see Gotchas in SKILL.md |
| `checkout.defaultRemote` | Disambiguates which remote to use when a branch name matches multiple remotes during `worktree add` |
## Workflow patterns
**Emergency fix without disrupting current work** — nothing is stashed, and the main worktree is
untouched throughout:
```bash
git worktree add -b emergency-fix ../temp main
cd ../temp
# fix, then commit
git commit -a -m "fix: critical production bug"
cd -
git worktree remove ../temp
```
**Review a PR branch alongside your own work** — both branches stay checked out, so there is no
context switch:
```bash
git worktree add ../review-pr-123 origin/feature-xyz
# open ../review-pr-123 in a second editor window or terminal
```

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

@@ -19,6 +19,8 @@ Invoke with no arguments. The skill determines from context whether to create a
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/create-config.md` | Loaded when the repo has no `.pre-commit-config.yaml` — the create-from-scratch flow |
| `references/modify-config.md` | Loaded when a `.pre-commit-config.yaml` already exists — add, remove, top-level keys, rev staleness |
| `references/hooks-by-language.md` | Hook recommendations by detected language/extension |
| `references/README.md` | Index of files in references/ |
| `references/sources.md` | Provenance — research sources that informed this skill |

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

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

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

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

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

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

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

@@ -11,6 +11,11 @@ source_keys:
Use this table when creating a config from scratch or recommending hooks to add.
Always check the existing config for duplicates before proposing.
Fixer hooks (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json` and the like) rewrite
files but do NOT re-stage them, so the commit is still blocked and the user has to stage and commit
again. Say so when proposing one — otherwise the first blocked commit reads as the hook being
broken.
## Universal (recommend for every repo)
| Hook ID | Repo | Rev | Rationale |
@@ -101,6 +106,9 @@ Use for repo-specific scripts that don't belong in an external hook repo.
stages: [pre-push]
```
`language: system` and `language: script` are deprecated names for the first two below.
New local hooks use `unsupported` and `unsupported_script`.
Language choices for local hooks:
- `unsupported` — system PATH tool (pre-commit does not manage env)
- `unsupported_script` — script at a repo-relative path
@@ -117,4 +125,4 @@ Language choices for local 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.
The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats 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.

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

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

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

@@ -4,7 +4,7 @@
- **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
- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
- **Status:** `extracted`
@@ -12,7 +12,7 @@
- **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
- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
- **Status:** `extracted`

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

@@ -24,6 +24,9 @@ Common invocations:
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions |
| `references/install.md` | The install flow — loaded when the user asks to install or set up hooks |
| `references/autoupdate.md` | The autoupdate flow — loaded when the user asks to bump hook revs |
| `references/clean.md` | The clean flow — loaded when the user asks to wipe the cache or rebuild environments |
| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when a hook fails or never fires |
| `references/sources.md` | Provenance: research sources that informed this skill |
| `references/README.md` | Directory index for references/ |

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

@@ -1,13 +1,9 @@
---
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.
Use when the user wants to run pre-commit hooks, wire them into git, bump hook
revs, maintain the cache, or diagnose why a hook fails or never fires. Not
creating or editing the pre-commit config -> `pc-author`.
compatibility: Requires pre-commit installed and available on PATH.
@@ -22,102 +18,34 @@ 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.
- The `SKIP` env var takes exact hook `id` values, comma-separated with no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after a comma silently skips nothing instead of erroring.
- Never bypass a failing hook with `git commit --no-verify` (or `-n`). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead.
## Route
Determine intent from the user's request, then execute the matching operation:
Determine intent from the user's request, then execute the matching operation. Where the matching row names a `references/` file, read that one file and no other — each flow file is self-contained.
| User intent | Operation |
|---|---|
| "run", "check", "verify", "test hooks" | `pre-commit run --all-files` (default) |
| "staged", "simulate commit" | `pre-commit run` (staged files only) |
| "CI", "changed files only", "diff range" | `pre-commit run --from-ref <base> --to-ref <head>` — prefer this over `--all-files` on large repos |
| "install", "set up hooks", "wire into git" | `pre-commit install` — 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 |
| "install", "set up hooks", "wire into git" | `pre-commit install` — read `references/install.md` |
| "pre-create environments", "warm cache" | `pre-commit install-hooks` — builds every hook environment without running a hook |
| "remove hooks", "uninstall", "tear down" | `pre-commit uninstall` — removes pre-commit from `.git/hooks/` |
| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` — read `references/autoupdate.md` |
| "gc", "garbage collect" | `pre-commit gc` — drops unused cached environments only, safe at any time |
| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — read `references/clean.md` |
| "hooks aren't running", "hook never fires", "why did a hook fail" | Diagnose — read `references/failure-patterns.md` |
If the intent is ambiguous, default to `pre-commit run --all-files`.
## Run
Default: `pre-commit run --all-files`. Never silently run staged-only.
Default to `pre-commit run --all-files`; never silently narrow to staged files. Run `pre-commit run` (staged only) or `pre-commit run <hook-id>` (one named hook) when the user asks for it.
```bash
pre-commit run --all-files
```
When hooks fail:
**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
```
1. Name the hook and the specific cause. Be concrete — "gitleaks blocked `config.json` (high-entropy string on line 12)", not "gitleaks failed".
2. Suggest one concrete next step. If the cause is not obvious from the output, read `references/failure-patterns.md`.
3. Do not auto-fix code files, and do not edit `.pre-commit-config.yaml` — those belong to the user or to `pc-author`.

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

@@ -10,5 +10,8 @@ source_keys:
| File | Purpose |
|---|---|
| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when hooks fail |
| `install.md` | The install flow — read when the user asks to install or set up hooks |
| `autoupdate.md` | The autoupdate flow — read when the user asks to bump hook revs |
| `clean.md` | The clean flow — read when the user asks to wipe the cache or rebuild environments |
| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — read when a hook fails or never fires |
| `sources.md` | Provenance: research sources that informed this skill |

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

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

21
plugins/git/.apm/skills/pc-run/references/clean.md Normal file
View File

@@ -0,0 +1,21 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Wiping the pre-commit cache
Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. Self-contained.
## Gate — confirm first
`pre-commit clean` wipes the whole cache at `~/.cache/pre-commit`, forcing every hook environment to be re-downloaded on the next run. Require explicit confirmation before executing it:
> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
```bash
pre-commit clean
```
Prefer `pre-commit gc` when the goal is only to reclaim disk — it drops unused environments and leaves the ones in use intact, so it needs no confirmation.

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

@@ -18,6 +18,8 @@ git add -u
git commit -m "same message"
```
Do NOT reach for `pre-commit install -f` here. That flag overwrites existing hook files in `.git/hooks/`; it has nothing to do with re-staging.
## Secret detected (gitleaks)
> Not sourced from the pre-commit research corpus (`context7-pre-commit-com`/`pre-commit-com` cover pre-commit itself, not gitleaks) — general tool knowledge, verify against gitleaks' own docs if precision matters.

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

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

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

@@ -4,7 +4,7 @@
- **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
- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
- **Status:** `extracted`
@@ -12,7 +12,7 @@
- **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
- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
- **Status:** `extracted`

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

@@ -1,6 +1,6 @@
# git-branches
Manage the full lifecycle of git branches — create, switch, delete, rename, and track feature/hotfix/release branches under GitHub Flow or Gitflow.
Manage the full lifecycle of git branches — create, switch, delete, rename, track, merge, and compare feature/hotfix/release branches under GitHub Flow or Gitflow.
## What it does
@@ -12,11 +12,22 @@ This skill handles branch operations within the git workflow suite. It creates b
/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.
Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, track, merge, or compare two branches. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/branch-patterns.md` | Loaded when a branch's base, name prefix, or merge rule depends on GitHub Flow vs. Gitflow |
| `references/branch-operations.md` | Loaded when running a create/switch/delete/rename/track/list action, or resolving `get-intent` |
| `references/merging.md` | Loaded when merging one branch into another or resolving merge conflicts |
| `references/comparing-branches.md` | Loaded when comparing two branches or finding where they diverged |
| `references/orchestrator-contract.md` | Loaded when `git-orchestrate` or another calling agent supplies a structured request rather than prose |
| `references/sources.md` | Research sources backing the branching/gitflow guidance |
## Composition
`git-orchestrate` calls this skill for the branch step of a multi-step workflow and parses its
structured result. Cherry-pick and revert are `git-history`'s; commit authoring and rebase are
`git-commits`'; branch operations against a Gitea-hosted remote are `gitea-branches`'.

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

@@ -2,13 +2,11 @@
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).
Use when creating, switching, deleting, renaming, tracking, merging, or comparing
local git branches under GitHub Flow or Gitflow.
Not writing or rewriting commits -> `git-commits`.
Not history inspection -> `git-history`.
Not a Gitea remote's branches -> `gitea-branches`.
metadata:
category: git
@@ -21,92 +19,57 @@ metadata:
## 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.
- **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears.
- **A branch and a tag can carry the same name.** Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/<name>` or `refs/tags/<name>`.
- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead.
## Branch Patterns
## Step 1 — Determine the branching pattern
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).
Read `branching_pattern` from the git plugin config (`.claude/plugins/git/config.json`; the plugin root's `config.example.json` shows the shape). Default: `github-flow`. With no config, infer Gitflow from the presence of a `develop` or `release/*` branch, and GitHub Flow otherwise.
**GitHub Flow:**
- Base: `main`
- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
- Merge: fast-forward when possible (preserves linear history)
- Delete after merge
The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`.
**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
## Step 2 — Dispatch on the action
## Workflow
| Action | Reference |
|---|---|
| create, switch, delete, rename, track, list, get-intent | `references/branch-operations.md` |
| merge a branch, resolve merge conflicts | `references/merging.md` |
| compare two branches, find their divergence | `references/comparing-branches.md` |
- [ ] **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.
Load only the file the action needs. A destructive action still passes Step 3 first.
### Command mapping for each action
## Step 3 — Gate destructive operations
- **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.
Before any delete or force-delete that loses history:
## Merging
- [ ] Does the branch track a remote? Warn if so.
- [ ] Are there unpushed commits on it? Warn if so.
- [ ] Did the caller pass `confirm: true`? Fail if not — for a human caller, prompt interactively instead of failing.
Scope: fast-forward/merge-commit mechanics and conflict resolution only. Rebase, cherry-pick, and revert belong to `git-history`.
These gates are passable. The `main`/`master` refusal in Gotchas is not.
- **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.
## Step 4 — Set tracking
**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.
When pushing a branch for the first time, always `git push -u origin <branch>`. Without an upstream, later pushes and pulls either fail or silently target the wrong remote branch, and the caller has no way to tell which happened.
## Comparing Branches
## Step 5 — Return a structured result
- `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.
Return every operation in this shape rather than prose, including failures — a calling agent chains its next operation on the result and cannot parse a sentence.
## 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|...",
"action": "create|switch|delete|rename|track|list|get-intent",
"branch": "<name>",
"message": "descriptive message",
"intent": "<intent if tracked>",
"tracking": "origin/<branch (if set)>",
"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.
When the failure is uncommitted local changes, set `"suggestion": "stash changes and retry"` so the caller can offer recovery rather than surfacing a dead end.
When a calling agent supplies a structured request rather than prose, read `references/orchestrator-contract.md` for the request schema.

34
plugins/git/skills/git-branches/references/branch-operations.md Normal file
View File

@@ -0,0 +1,34 @@
---
source_keys:
- context7-git-htmldocs
---
# Per-action command mapping
One command per action. Where two forms exist, the first is the default and the second the escape
hatch.
- **create** — `git switch -c <branch> <base>`. Base comes from the config's `base_branch`
(`main` under GitHub Flow, usually `develop` under Gitflow).
- **switch** — `git switch <branch>` moves to an existing local branch; it aborts rather than
clobbering conflicting local changes. `git switch -` returns to the previous branch.
- **delete (local)** — `git branch -d <branch>` refuses when the branch holds unmerged commits,
which is why it is the default. `git branch -D <branch>` forces the deletion and discards that
work — only after the destructive-operation gates pass and `confirm: true` is set.
- **delete (remote)** — `git push origin --delete <branch>`.
- **rename** — `git branch -m <old> <new>`.
- **list** — `git branch` (local), `-a` (local plus remote-tracking), `-r` (remote-tracking only),
`--merged` / `--no-merged` (filter by merge status into the current branch).
- **track** — `git branch --set-upstream-to=origin/<branch>` sets an upstream without pushing.
`git branch -vv` shows the tracking state of every local branch.
## get-intent
Git has no native field for free-text branch metadata, and this skill does not persist any. On
`create`, the `intent` value is only returned in the structured result — the caller decides
whether to store it.
On `get-intent`, either parse the intent back out of the branch-name convention
(`feature/<intent-slug>`) or return `{ "intent": null }` when the caller never persisted the
create-time value. Never fabricate an intent: a downstream commit message built on a guessed
intent is worse than one built on none.

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

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

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

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

29
plugins/git/skills/git-branches/references/merging.md Normal file
View File

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

16
plugins/git/skills/git-branches/references/orchestrator-contract.md Normal file
View File

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

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

@@ -12,7 +12,8 @@
- **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)
- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
- references/branch-patterns.md (Gitflow vs. GitHub Flow structure, defaults, and why the two are not mixable)
## atlassian-gitflow-tutorial
@@ -23,7 +24,9 @@
- **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)
- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
- references/branch-patterns.md (Gitflow branch types, base/merge targets, `--no-ff` requirement)
- references/merging.md (`--no-ff` requirement on Gitflow supporting-branch merges)
## gitflow-cheatsheet
@@ -34,7 +37,7 @@
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
**Contributing files:**
- SKILL.md (Branch Patterns — feature/release/hotfix naming conventions)
- references/branch-patterns.md (feature/release/hotfix naming conventions)
## context7-git-htmldocs
@@ -45,4 +48,7 @@
- **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)
- SKILL.md (Gotchas — `git switch` abort-on-conflict behaviour, branch/tag name ambiguity)
- references/branch-operations.md (`git switch`/`git branch` command vocabulary and flags)
- references/merging.md (`git merge` strategies and conflict-resolution commands)
- references/comparing-branches.md (`git log`/`git diff`/`git merge-base` range syntax)

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