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

Compare commits

base: Defame1297:dd934d3b07b8a5d3550a4b65b5569383499e9b05
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:v1.0.0
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

83 Commits
dd934d3b07 ... v1.0.0

Author SHA1 Message Date
Defame1297
8f523da270 Merge pull request 'feat(lint): wire Vale as deterministic prefilter for skill-audit/agent-audit' (#85) from feat/84-vale-audit-prefilter into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/85
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-08-10 16:46:59 +00:00
Defame1297
cf5de2bd87 fix(lint): fail loudly on a nonexistent REPO_ROOT in check-vale-style-sync.sh 
A bad or stale REPO_ROOT argument fell through to the "neither copy
present" no-op guard and exited 0 — the exact "clean result can mean
nothing was checked" anti-pattern this PR spent multiple review rounds
eliminating elsewhere. That guard exists for a repo that legitimately has
no kyberforge plugin installed, not for a typo'd path.

Only the documented manual-invocation mode was affected: the shipped
pre-push hook always calls this script with zero args, which resolves via
`git rev-parse --show-toplevel` and is always valid inside a repo.

Added a regression test asserting a nonexistent REPO_ROOT exits non-zero.

Refs: #85
 2026-08-10 07:45:58 +00:00
Defame1297
76e0df6f5b chore(plugins): patch-bump gitea for shipped content changes 
gitea 1.3.2 -> 1.3.3. The round-1 Vale corpus fix (3324a73) changed
shipped skill content (gitea-issues, gitea-prs, gitea-releases SKILL.md)
without touching this plugin's manifests, so installed copies would keep
serving the old content from cache. Every other plugin whose content
changed in this PR got this bump (bin, kyberforge, lint, four times
total) — gitea was missed each time.

Marketplace entries carry no per-plugin version, so both marketplace.json
files are untouched, matching prior version-bump commits in this PR.

Refs: #85
 2026-08-10 07:38:09 +00:00
Defame1297
389a4f0f7a fix(lint): avoid bash 4 associative arrays in check-vale-style-sync.sh 
check-vale-style-sync.sh used `declare -A` for a per-skill regex cache.
Associative arrays are bash 4.0+; this script runs as an always-run
pre-push hook with `language: system`, so it inherits whatever bash is
first on the invoking user's PATH. On macOS's stock bash 3.2, `declare -A`
at top level aborts immediately under `set -euo pipefail` — every push
would hard-fail before the sync check ran anything.

Replaced with two parallel indexed arrays (HOOK_REGEX_CACHE_KEYS/_VALS),
linear-scanned by index — same caching behavior (avoids re-parsing both
pre-commit manifests when agent-audit is probed twice), but only ever
uses ${#arr[@]} and index access, never a bare ${arr[@]} expansion.

Extended test-vale-wrap.sh's existing bash-3.2 hazard sweep to scan this
file too, and added a check for `declare -A` itself — it previously only
caught unguarded ${arr[@]} expansions and mapfile/readarray, so this
exact regression had no test that would have caught it.

Refs: #85
 2026-08-10 07:37:55 +00:00
Defame1297
e62f68a1cc refactor(lint): cache manifest parsing, single-pass size check 
Two more efficiency findings from the same code-review pass:

- check-vale-style-sync.sh's hook_file_regexes() reparsed both
  pre-commit manifests from scratch on every call. The final
  validation loop calls it once per probe (3 probes: skill-audit once,
  agent-audit twice for its two file shapes), so agent-audit's regex
  set was being parsed twice for no reason. Now cached per skill in a
  lazily-populated associative array, with a separate "seen" map so an
  empty result isn't mistaken for "not yet computed."
- skill-size-check.sh read the target file twice (separate awk and
  wc -w calls) to get line and word counts; now a single awk pass
  returns both. Also documented, next to MAX_LINES/MAX_WORDS, why
  those constants are duplicated against skill-audit/scripts/
  validate.sh's Python implementation rather than unified — same
  cross-language/cross-context tradeoff as vale-wrap.sh's duplication,
  guarded by tests/test-skill-size-check.sh's drift check.

Verified: test-check-vale-style-sync.sh 20/20, test-skill-size-check.sh
9/9, full suite 12/12, pre-commit --all-files clean.
 2026-08-09 20:14:36 +00:00
Defame1297
680aa4f43c refactor(kyberforge): consolidate vale-wrap.sh's config parsing and subprocess spawns 
Two efficiency findings from a code-review pass:
- The separated (--config X) and joined (--config=X) argument branches
  duplicated ~20 lines of absolutize-if-relative path logic. Extracted
  into abs_config_value(), used by both branches; the redundant
  --config=/* special case falls out since the helper already passes
  absolute paths through unchanged.
- The common single-file path spawned python3 twice per file (once for
  abspath resolution, once for flatten()). flatten() now optionally
  takes a tmpdir arg and does both in one process. The per-file loop
  under a directory argument is unchanged — that path wasn't flagged.

agent-audit's copy is canonical; skill-audit's copy was regenerated via
scripts/sync-vale-styles.sh, not hand-edited, to guarantee byte parity.
No hardening (bash 3.2 compat, surrogateescape, symlink guards) touched.
Verified: tests/test-vale-wrap.sh 39/39, check-vale-style-sync.sh clean,
full suite 12/12.
 2026-08-09 20:14:23 +00:00
Defame1297
6910f1b5a5 fix(lint): reject checkpoint-suffixed tags as the release-gate baseline 
git describe --match is a shell glob, not a regex: the trailing `*`s
in 'v[0-9]*.[0-9]*.[0-9]*' match any suffix, so a tag like
v1.2.3-checkpoint or v1.2.3-rc1 satisfied the pattern and could be
picked as LAST_TAG instead of the true last release. That silently
shifts the diff baseline and can let a push skip a required release.
--exclude '*-*' rules out any tag carrying a hyphenated suffix.

Added a regression test that tags a release-relevant change with a
v1.0.1-checkpoint tag right after v1.0.0 and asserts the gate still
fires — confirmed it fails against the pre-fix script and passes
against the fix.
 2026-08-09 19:55:36 +00:00
Defame1297
050aec4c80 docs(kyberforge): document Vale-wiring files in skill-audit/agent-audit READMEs 
Both READMEs' file tables predate #85's Vale wiring and never picked
up scripts/vale-wrap.sh or the assets/vale/ style tree, so a reader
of either README had no way to find where the new Step 1 sub-check
actually lives. List the new files and note the Vale sub-check in
"What it does" for both skills.
 2026-08-09 19:55:27 +00:00
Defame1297
0a41b2c7d3 fix(kyberforge): restore skill-audit's action-verb opening check 
skill-audit's Description dimension implied Vale's DescriptionOpener
alert fully covers imperative-phrasing checks, but that rule only
matches the literal "This skill..." pattern. agent-audit kept its
equivalent manual "does the description open with a verb" fallback
bullet; skill-audit's got dropped when Vale wiring landed in #85,
leaving other non-imperative openers (gerunds, passive phrasing) to
sail through unflagged. Restore the parallel check.
 2026-08-09 19:55:19 +00:00
Defame1297
9a3f72b696 test(lint): stop the release-gate suite inheriting the caller's PRE_COMMIT refs 
run_check set PRE_COMMIT_REMOTE_BRANCH and, when asked, PRE_COMMIT_TO_REF, but
never cleared what was already in the environment. Standalone that is invisible
— nothing sets those vars. Under the pre-push hook this suite exists to guard,
pre-commit exports PRE_COMMIT_TO_REF and PRE_COMMIT_FROM_REF as shas of the
real repo; the fixtures inherited them, the script resolved a rev that does not
exist in the fixture, and 13 of 20 cases failed. The suite passed in every
context except the only one that matters.

The variables are now cleared in both branches, so a standalone run and a
pre-push run are the same test. Verified 20/20 with the vars unset and with
them set to real shas of this repo.

Found by the pre-push hook rejecting the push, not by any test — the same shape
as the --config regression: the local invocation exercised a different thing
than the shipped one, and the two were indistinguishable by reading the file.

Refs: #85
 2026-08-09 17:28:07 +00:00
Defame1297
7cf9a98509 docs(lessons): record two patterns from PR #85's round 6 
The aggregate-assertion failure joins the "a clean result can mean nothing ran"
family as its fifth instance: a total over N subjects is satisfiable by a
proper subset, so it proves nothing about any individual subject. Records the
reverse mutation sweep — neuter each assertion, confirm exactly one case fails
— as standing practice for checks whose failure mode is silence.

The second entry is about accepted residuals: the U+2019 rewrite survived
review because its justification was documented in the same breath as the
workaround, and the covering test asserted the residual's presence rather than
the behaviour it cost. Documentation records a belief; a belief adjacent to a
workaround is the one most worth attacking.

Refs: #85
 2026-08-09 17:24:08 +00:00
Defame1297
997f0df23b chore(plugins): patch-bump kyberforge and lint for shipped changes 
kyberforge 1.2.7 -> 1.2.8: both vale-wrap.sh copies, skill-audit's validate.sh
and its SKILL.md changed after the last bump. lint 1.1.4 -> 1.1.5: the Vale
research troubleshooting doc changed after its last bump.

Without the bump, installed copies keep serving the cached version. This is the
fourth time in this PR the bump was missed after shipped content changed —
check-manifests.sh validates parity between the two manifests but not that a
content change was accompanied by a bump, which is the gap that keeps letting
it through.

Refs: #85
 2026-08-09 17:24:08 +00:00
Defame1297
302f6d0c19 fix(lint): tighten the SKILL.md word ceiling to 2770 
MAX_WORDS=2900 was calibrated to the corpus median density and carried no
margin: at the densest observed 7.22 chars/word (~1.81 tokens/word) it permits
~5,240 tokens against the 5,000 it proxies for. 2770 holds the worst observed
density under the ceiling. The largest SKILL.md is 2,489 words, so the change
costs nothing today — 281 words of margin — and the header comment now argues
the new calibration rather than swapping the digits.

Both enforcement points move together, and a new test asserts they agree, since
a SKILL.md passing its own audit while the commit hook blocks it is the
disagreement this pair exists to prevent.

CONTEXT.md is deliberately left ungated: it is 2,816 words, and gating it would
block the build. Recorded here so the omission reads as a decision rather than
an oversight.

skill-audit's manual-fallback path listed only the line ceiling, so an agent
taking that path passed an oversized SKILL.md the hook then rejected. The word
ceiling is now named alongside it. agent-audit is deliberately unchanged: the
size hook scopes to SKILL.md only and agent-audit's validate.sh has no word
gate, so claiming it there would be false.

The Vale research doc still showed the MDX {/* vale off */} form under a
Markdown heading, contradicting CONTEXT.md and vale-run's troubleshooting
reference — that form suppresses nothing in plain .md. Fixed in both places it
appeared.

tests/run-tests.sh used mapfile (bash 4.0+) with unguarded array expansion,
though AGENTS.md tells contributors to run it and macOS ships bash 3.2. It now
collects via a while-read loop over process substitution and guards every
expansion. The newline-delimited find|sort pipeline is kept rather than -print0
with sort -z, whose BSD portability is the weaker link, and which matches
mapfile -t's previous behaviour exactly.

Refs: #85
ADR: 0013
 2026-08-09 17:23:51 +00:00
Defame1297
f6eb0d295e fix(lint): derive the release gate from the pushed ref, reject multi-token entries 
The gate hardcoded HEAD as its diff tip, but pre-commit exports
PRE_COMMIT_TO_REF for exactly this. Pushing "somebranch:main" from another
checkout diffed the wrong tip — a false negative when HEAD is older, a false
positive when newer. Fixing only the diff tip leaves a second bug: git describe
took the tag baseline from HEAD too, so a tag reachable only from HEAD becomes
a baseline the pushed ref never saw. Both now resolve from the pushed ref, and
an all-zeros ref (branch deletion) short-circuits before any rev resolution
rather than surfacing as "could not diff".

PRE_COMMIT_FROM_REF is deliberately not used: it is the remote's current tip,
so diffing from it would let an untagged release-relevant commit already on
main excuse the next push from cutting a tag — the drift this gate exists to
catch. The baseline must stay the last release tag.

collect_release_paths took tokens[0] as a path unconditionally. ADR-0014 makes
bare single-path entries a binding constraint, but nothing enforced it, and the
sibling .pre-commit-config.yaml already ships "entry: bash <script>". Under
that shape add_release_path takes "bash", git diff accepts the non-matching
pathspec silently, bundle_root becomes "." and is skipped — the hook's whole
surface leaves the gate with no error, the same shape as the --config
regression in LESSONS.md. Multi-token entries now fail loudly naming the hook
and the ADR, and tokens[0] must resolve at HEAD or at the tag (the union is
load-bearing: a per-scope check would reject the deletion cases).

Six mutations verified, each restored. One correction worth recording: the
first multi-token test passed with its guard removed, because the existence
guard caught "bash" and printed a similar message. It now requires the verbatim
entry text that only the multi-token diagnostic emits.

Refs: #85
ADR: 0014
 2026-08-09 17:23:36 +00:00
Defame1297
ad1e5aaa9b fix(kyberforge): carry apostrophes verbatim through a |- literal block 
The flattener's last-resort branch rewrote ASCII ' to U+2019, justified as the
one combination no YAML scalar can carry verbatim. That claim was false: a |-
literal block with a single indented content line carries ', ", \ and ": "
verbatim and keeps text.frontmatter.description matching — as the wrapper's own
docstring already said of literal blocks. The rewrite fired on 12 of 54
in-scope files, silently disabling every rule whose token contains an
apostrophe. Case 20 pinned only that the scope stayed alive, so it passed
either way.

The emission site now splits the emitted scalar on its first newline so a
carried-over trailing comment stays on the "description: |-" header line rather
than becoming part of the value, and pads by span_lines - 1 - newlines. The pad
stays non-negative because the branch is only reachable when the original span
is at least two lines. Verified across all 73 in-scope files: no line-count
changes, and exactly the 12 expected files take the new branch.

One reported position moves: an alert on a description that is itself flagged
shifts from the key line to the block's content line, both inside the original
span. YAML cannot put a literal block's content on the key's own line, so this
is unavoidable; no line at or after the end of any description span moves.

Also: --output no longer absolutises the built-in style names line, JSON and
CLI, which a same-named file or directory in cwd turned into a template path
(exit 2, E100 Runtime error). And case 19's empty-baseline guard no longer
lets five dependent comparisons print vacuous passes — while fixing it the
guard turned out to be unreachable, since under pipefail an alert-free report
aborted the script at the assignment.

Refs: #85
ADR: 0014
 2026-08-09 17:23:24 +00:00
Defame1297
d25355077f fix(lint): attribute Vale alerts per hook and cover .vale.ini in the sync check 
The external-consumer test asserted a combined alert count (>=2) across both
shipped Vale hooks, but the SKILL.md fixture alone raises two alerts — so one
working hook satisfied the threshold. Retargeting agent-audit's glob to match
nothing left the suite reporting "3 passed" under the message "both hooks
flatten and flag". The Skipped guard does not catch this: the hook still
matches the file, Vale lints nothing, reports 0 errors in 1 file and exits 0,
which pre-commit renders as Passed. An assertion aggregating over N subjects
proves nothing about any individual subject.

Each hook now runs individually and its alerts are attributed to the nearest
preceding path header, so an alert is checked by path rather than by presence
in the combined blob. The two fixtures carry distinct VagueWording tokens, so
one hook's alert cannot be credited to another.

Nothing in the repo read either .vale.ini — the sync check diffed only
vale-wrap.sh and styles/Kyberforge, so a one-line glob typo silently disabled
the prefilter for a whole file type. That was the enabling half of the same
defect. The check now asserts the shared lines both copies must carry
(StylesPath, a section naming Kyberforge as a whole word) without flagging
their intentional divergence, and probes each glob section by asking Vale
itself to lint a representative path. Regex-to-glob comparison was rejected as
it means reimplementing doublestar semantics in bash; a file-count dry-run was
rejected because a section whose glob matches but whose BasedOnStyles lost
Kyberforge reports "1 file" with no alerts and would pass it.

Every new assertion is bound to a failing case in both directions: breaking the
artifact fails the suite, and neutering the assertion fails exactly one case.
That reverse sweep exposed two assertions bound to no failing case at all, one
masked by a stronger check running first.

Refs: #85
 2026-08-09 17:23:10 +00:00
Defame1297
57654c4b02 docs(lint): correct the Vale scalar, size-ceiling and release-gate claims 
Four claims in shipped agent-facing docs did not match verified behaviour.
These are read as ground truth by agents in other repos, so each was
reproduced against vale 3.15.2 before rewriting:

- CONTEXT.md and `vale-config/SKILL.md` said both `>` and `|` block scalars
  break the description scope. `|` does not — it lints normally and fires every
  alert, while `>` yields zero. An agent following the old text would rewrite a
  working `|` description into a plain multi-line scalar, which genuinely does
  break, inverting the intended remediation. Both now name the forms that do
  break and state that `|` does not.
- CONTEXT.md and ADR-0013 described the size hook as failing only above 500
  lines, omitting the 2900-word gate it also enforces. Both now describe the
  pair and state that `validate.sh` checks the same two.
- ADR-0014 recorded an accepted residual — a wholesale `assets/` deletion going
  unflagged — that commit 14c2c91 closed. Left as the point-in-time record and
  amended with an update describing the union-with-tag-manifest mechanism,
  following the amendment precedent in ADR-0005.
- `vale-config/SKILL.md` asserted a fresh `.vale.ini` fails until `vale sync`
  runs, contradicting its own note that built-in styles need no download. The
  claim is now scoped to package styles; this repo's two configs declare no
  packages and lint clean with zero syncs.

Also repoints AGENTS.md at the seven `gitea:*` skills — the `bin:gitea` route
it named no longer exists.

Refs: #85
 2026-08-09 15:44:28 +00:00
Defame1297
4ae2429840 fix(kyberforge): align the audit word ceiling and drop the fragile --config 
Three divergences between what the audit skills claim and what the hooks
enforce, each of which fails silently rather than loudly:

- `skill-size-check.sh` blocked at 2900 words while `validate.sh` checked only
  the 500-line ceiling, so `/skill-audit` could report a skill ready to ship
  that the commit hook then rejected. `validate.sh` now checks the same pair on
  the same inclusive terms; the constants are duplicated with a comment naming
  the other file, because a plugin skill's scripts cannot read outside the
  plugin directory once installed to the cache.
- Both audit skills' Step 1 passed `--config assets/vale/.vale.ini`, which is
  redundant (the wrapper self-locates its sibling config) and fragile: an agent
  that resolves the script path against the skill directory but not the config
  path gets E100, exit 2, which the surrounding fallback clause misreads as
  "vale unavailable" and downgrades to full LLM judgment with no signal.
- The external-consumer test registered only the two Vale hooks, never the
  third shipped hook, so a lost executable bit would have broken every consumer
  while the local suite stayed green. Verified by mutation: `chmod 644` on the
  copied script now turns three passes into two failures.

Also corrects the size hook's calibration comment, which claimed ~5.7-6.5
characters per word against a corpus whose measured median is 6.79 — the stated
upper bound sat below the median, so the "calibrated with margin" claim was
inverted for prose-dense files. MAX_WORDS is unchanged pending a decision; the
comment is now explicit that the gate holds under 5,000 tokens for typical
prose density, not for any file.

Refs: #85
 2026-08-09 15:44:16 +00:00
Defame1297
aa8cc22695 fix(lint): flatten every multi-line description form in vale-wrap.sh 
Vale locates a frontmatter description by matching the parsed YAML value back
against the source text, so any scalar whose value is not spelled out verbatim
loses the `text.frontmatter.description` scope entirely. The wrapper only
flattened `>` folded scalars, so plain, double-quoted and single-quoted
multi-line descriptions silently reported zero alerts and exit 0 — a clean pass
indistinguishable from a real one, in a prefilter whose callers are instructed
not to re-derive its verdict by judgment.

Implementation notes:

- Classify the scalar kind after `^description:[ \t]*` and reuse one shared
  continuation-line generator for every form; `|` literal blocks keep their
  line breaks, stay verbatim-matchable, and are still left untouched.
- Emit the flattened value in whichever scalar form needs no escape at all
  (plain, then single-quoted, then double-quoted), because any escape breaks
  the verbatim match. The old blanket `'` -> U+2019 substitution silently made
  apostrophe-bearing rule tokens unmatchable across 63% of the corpus; it now
  survives only for the one combination no YAML scalar can carry verbatim.
- Terminate continuations at a line flush with the key, not only on a shallower
  indent — a `description:` followed by a flush-left line previously swallowed
  the rest of the frontmatter.
- Route vale's value-taking flags explicitly instead of inferring targets by
  file existence, and absolutize relative `--output`/`--path` values the way
  `--config` already was, since the run `cd`s into the scratch mirror.
- Fail loudly on a nonexistent path instead of inheriting bare vale's fallback
  to stdin, which rendered a typo'd path as `0 errors ... in stdin`, exit 0 —
  a form the callers' `0 files` NOT-RUN guard cannot match.
- Follow symlinks when walking a directory argument, matching bare vale.

Refs: #85
 2026-08-09 15:44:04 +00:00
Defame1297
afc2b7fdfd docs(lessons): record two patterns from PR #85's round 4 
A config's local mode can prove nothing about the mode that ships:
repo: local collapses the clone prefix, cwd and repo root into one
directory, so a byte-identical entry: string worked locally for a
reason that exists only locally, through three review rounds.

Deleting a token from a shared artifact breaks whatever parses it,
silently: dropping --config killed the loop that gave the bundled
Vale styles release coverage, shrinking a derived path list with no
error and no failing test.

Kept separate from the adjacent "clean linter result" and "one signal,
two consumers" entries, which describe different failure modes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:32:32 +00:00
Defame1297
16c038b178 fix(lint): guard empty array expansions in vale-wrap.sh for bash 3.2 
Under set -u, "${arr[@]}" on an empty array aborts on bash before 4.4,
which is what macOS ships as /bin/bash. Three expansion sites now use
${arr[@]+"${arr[@]}"} consistently.

The hazard is not currently reachable: verified on a bash 3.2.57 built
from source that all seven invocation shapes succeed against the
previous code, including zero args, flags-only and an empty directory.
vale_args is provably non-empty at every site because the default
--config branch always appends first. The guard is kept because that
invariant is non-local and untested, so an edit to the default-config
branch would reintroduce a macOS-only crash silently.

Test fidelity is deliberately mixed. Case 16 is static and is the only
one that fails against the previous code, since no bash 5 host can
reproduce the abort at runtime. Case 17 runs the emptiest invocations
under the oldest bash it can find and names that shell in its output
so it cannot overclaim. Case 18 guards against the tempting wrong fix
of dropping the quotes, which also silences the abort but word-splits
a path containing a space.

No other bash 4.x construct is present; swept for mapfile, declare -A,
case modification, negative indices, globstar, wait -n and namerefs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:32:30 +00:00
Defame1297
14c2c91521 fix(lint): flag release-relevant paths retired since the last tag 
Coverage was derived from the worktree alone, so the -d guard on a
hook's bundled assets/ tree meant deleting the whole tree removed it
from the pathspec instead of flagging it — the gate stayed silent
about a change that breaks every consumer at the next rev:.

The path set is now derived twice, from the worktree manifest and from
the manifest at $LAST_TAG, then unioned. A path the tag exposed but
HEAD no longer does is a removal pinned consumers must be told about;
a path only HEAD exposes is new contract surface. Both need flagging.

Fails closed on an unreadable tagged tree (shallow clone), and treats
a readable root tree with no manifest as "added since the tag".

tokens[0] needed no exit-code fix — it carries no existence guard, so
both deletion cases already exited non-zero. What was wrong was the
reporting: a fully retired hook could no longer be named in the
failure message. The tagged manifest fixes that.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:32:30 +00:00
Defame1297
cc5f366450 chore(plugins): patch-bump kyberforge and lint for shipped changes 
kyberforge 1.2.5 -> 1.2.6 for the self-locating vale-wrap.sh.
lint 1.1.3 -> 1.1.4 for the corrected Vale exit-code semantics: a
consumer cached at 1.1.3 holds docs that lead to building a gate which
passes everything.

Both provider manifests bumped in parity per ADR-0006. Marketplace
entries carry no per-plugin version, so neither file changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:06:53 +00:00
Defame1297
e9234f6d8a docs(lint): correct the Vale exit-code and glob-scoping claims 
cli-reference.md said vale exits non-zero for any alert at or above
MinAlertLevel. The exit code keys on error-level alerts alone;
MinAlertLevel filters display only. LESSONS.md records this exact
misconception as costing two review rounds, and this research doc is
the cited provenance source for the skills that state it correctly.

CONTEXT.md claimed a SKILL.md outside plugins/ matches no glob section.
[**/SKILL.md] matches any path ending in SKILL.md — the sentence is a
stale leftover from the path-scoped globs at cbc33d9, and contradicted
its own paragraph two sentences earlier. The NOT-RUN 0-files guard it
justifies is correct and is unchanged; only the rationale was wrong.
CONTEXT.md also cited the local files: regex as the scoping mechanism,
where the shipped manifest deliberately stays layout-agnostic.

ADR-0014 records the entry[0]-only prefixing constraint as the reason
the self-locating design is required, and that no entry may grow a
repo-internal path argument.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:06:52 +00:00
Defame1297
348dd9f665 fix(lint): restore release-gate coverage of bundled Vale assets 
The gate derived release-relevant paths from the dirname of each
entry's --config target. Dropping --config from .pre-commit-hooks.yaml
left that loop dead, silently removing both assets/vale/ trees from
coverage — a Vale rule change could land on main without demanding a
release tag, leaving consumers pinned to an old rev: with stale rules.

Coverage now derives from tokens[0] instead: double-dirname for the ..
normalization, guarded on the tree existing and on the bundle root not
resolving to "." so skill-size-check.sh cannot invent a bogus path.

The --config branch is removed rather than kept as dead code. Since
pre-commit rewrites only entry[0], no argument in any entry can ever
name a file this repo ships, so that shape is broken by design.

Known gap: deleting a hook's entire assets/ tree is not flagged, as the
candidate path stops existing. Deletions within a surviving tree are.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:06:37 +00:00
Defame1297
714e8a0c78 fix(lint): fail the style-sync check when one copy is missing 
The guard used `||`, so exactly one of the two audit skill directories
missing also exited 0, where the intended silent no-op is both absent.
A renamed skill-audit reported green instead of flagging that a
canonical style copy had lost its counterpart.

One-present now exits 1 naming the missing side and the remedy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:06:36 +00:00
Defame1297
8c570e9659 fix(lint): make the Vale prefilter work for external consumers 
pre-commit prefixes only entry[0] with the hook-repo clone path
(cmd = (prefix.path(cmd[0]), *cmd[1:])), so the --config argument in
.pre-commit-hooks.yaml resolved against the *consuming* repo's root
and hard-failed every external run with E100. Two of the three hooks
ADR-0014 promises were unusable.

vale-wrap.sh now self-locates its config from BASH_SOURCE when no
--config is supplied; an explicit --config still wins in all three
argv forms and stays cwd-relative. Both manifests drop the argument
and are kept byte-identical: the local repo: local config resolved
--config correctly only because the consuming repo *was* this repo,
and that divergence is why three review rounds missed the defect.

Also in the wrapper:
- replace GNU-only `realpath -m` with a portable abspath helper; -m is
  load-bearing (dest does not exist yet), so BSD realpath aborted the
  script under set -e on macOS
- walk directory arguments instead of passing them through unflattened,
  which reported a clean 0-error run for files that fail when named
  explicitly
- read/write with errors='surrogateescape' so one non-UTF-8 .md under a
  directory argument cannot abort the hook

New test-vale-hooks-consumer.sh builds the hook repo from the working
tree and points a file:// consumer at it, covering the manifest as a
hook repo for the first time.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:06:23 +00:00
Defame1297
acd2f1d422 fix(lint): harden check-release-needed.sh, script the vale-style sync 
A review of PR #85's last two commits (1164f3a, 4d018af) found the new
release-gate script fails open in four separate ways, and the new drift
check for the duplicated Vale styles only ever detects drift after a
human already hand-edited both copies out of sync.

check-release-needed.sh:
- The `-e` existence filter dropped a RELEASE_PATHS entry from the diff
  pathspec once it was deleted from the tree, so deleting a path exposed
  via .pre-commit-hooks.yaml since the last tag passed the gate clean —
  exactly the breakage the gate exists to catch. git diff reports
  deletions fine without an existence check; the filter is gone.
- `git diff ... 2>/dev/null || true` turned any git failure (a shallow
  clone missing the tag's objects, a corrupted ref) into an empty,
  falsely-clean diff. The diff result is no longer swallowed: a failure
  now hard-fails with the underlying git error visible.
- RELEASE_PATHS was a hand-maintained array duplicating
  .pre-commit-hooks.yaml's entry: paths with only a comment holding them
  in sync, and was already over-broad (it swept in validate.sh /
  validate-provenance.sh, which no hook entry references). It's now
  parsed straight from .pre-commit-hooks.yaml's entry: lines at
  runtime, so it can't drift from the manifest and only tracks what a
  hook actually exposes.
- `git describe --tags --abbrev=0` accepted any tag reachable from HEAD
  as the diff baseline, not just release tags. Added
  `--match 'v[0-9]*.[0-9]*.[0-9]*'` so an incidental checkpoint tag
  can't shift the baseline and mask a real release-relevant change.

check-vale-style-sync.sh still only detects drift between skill-audit's
and agent-audit's duplicated vale-wrap.sh/styles/Kyberforge copies
(both copies must exist independently per the plugin's no-cross-skill-
path packaging rule — a symlink would break at install time). Added
scripts/sync-vale-styles.sh to regenerate skill-audit's copy from
agent-audit's canonical one on demand, and pointed the sync check's
failure message at it, so fixing drift is one command instead of a
hand diff across two files.

Also recorded, rather than silently left unfixed: check-release-needed.sh
only fires on a local `git push` through pre-commit's pre-push hook — a
PR merged via Gitea's merge button, or CI invoking
`pre-commit run --hook-stage pre-push` directly, never sets
PRE_COMMIT_REMOTE_BRANCH and skips the gate entirely. Closing that needs
a server-side CI job this repo doesn't have yet; documented as a known
limitation in ADR-0014 rather than papered over.

Separately, LESSONS.md's "a clean check can mean nothing ran" entry was
marked **Graduated** without ever being promoted per the repo's own
graduation rule (3+ instances → a standing doc, marked
`[graduated → target file]`). Actually promoted it into
core/instructions/testing.md and fixed the marker.

tests/test-check-release-needed.sh gained 4 regression tests, one per
check-release-needed.sh fix above, each verified to fail against the
pre-fix script and pass against the current one.

Verification: bash tests/run-tests.sh (11 scripts + 125 bats, all
passing), pre-commit run --all-files, and
pre-commit run --all-files --hook-stage pre-push all clean.

ADR: 0014
 2026-08-09 11:20:55 +00:00
Defame1297
4d018af03c fix(lint): hard-fail on main when a release tag is needed 
.pre-commit-hooks.yaml now exposes hooks to external consumers pinning
rev: <tag>, but nothing enforced that a tag actually gets cut when the
files it references change — relying on memory is exactly what this
repo's governance rules say to avoid for a repeatable, deterministic
check.

scripts/check-release-needed.sh hard-fails at pre-push, but only when
PRE_COMMIT_REMOTE_BRANCH (set by pre-commit's hook-impl) is
refs/heads/main: it diffs .pre-commit-hooks.yaml's referenced paths
against the last tag reachable from HEAD, and fails if either no tag
exists yet or something changed since. It's a silent no-op on every
other branch — hard-failing on feature-branch pushes mid-review would
force a premature tag on a commit that might not survive a
squash-merge, the exact risk the repo: local (vs. pinned self-
reference) decision in ADR-0014 already avoids for this repo's own
dev-time gate.

Verified against the real git pre-push hook path (not just the script
in isolation): simulated stdin matching git's pre-push protocol through
.git/hooks/pre-push, confirmed it correctly fires and fails when
targeting main with no tag, and is silent otherwise.

ADR: 0014
Refs: #87
 2026-08-09 10:20:43 +00:00
Defame1297
1164f3abad fix(lint): make Vale prefilter portable via the plugin 
skill-audit/agent-audit's Step 1 resolved vale-wrap.sh/.vale.ini via
`git rev-parse --show-toplevel`, which returns whichever repo the skill
happens to run in. Inside ai-development that works; in any external repo
that installs kyberforge@holocron as a plugin, it resolves to that repo's
own root, which has no .vale.ini — the prefilter silently fell back to
full LLM judgment. ADR-0013 named this as a deliberately deferred gap.

Vale's config/styles/wrapper now ship inside the plugin itself: a
canonical copy in agent-audit/assets/vale/ (Kyberforge + KyberforgeCopilot,
the superset agent-audit needs) and a smaller duplicate in
skill-audit/assets/vale/ (Kyberforge only) — per the no-cross-skill-path
rule already established for plugin cache-installs. Both skills resolve
these relative to their own directory, same as scripts/validate.sh
already does.

A new root .pre-commit-hooks.yaml exposes both copies plus
skill-size-check so any external repo can enforce the same rules via
`repo: <this-repo-url>, rev: <tag>` in its own pre-commit config,
independent of Claude Code entirely — the same mechanism covers CI. This
repo's own pre-commit hook now consumes the identical plugin-bundled
copies via repo: local (not a third root copy, and not a pinned
self-reference, which would lint working-tree edits against the last
tagged release instead of the change being made). Split into
vale-audit-prefilter-skill/-agent hooks after confirming, by diffing the
full corpus against both old and new config before deleting the old
files, that one combined hook pointed at only one copy silently 0-file-
skips the other file type.

scripts/check-vale-style-sync.sh guards the two copies against drift,
wired at pre-push alongside check-manifests.

ADR: 0014
 2026-08-09 10:04:19 +00:00
Defame1297
864e7c689c docs(lessons): record three patterns from PR #85's review rounds 
Three rounds of review on the Vale prefilter surfaced patterns worth
keeping rather than just fixing.

The first has now recurred three times in a single PR — a check reporting
success because it had silently not run — so it is flagged as a
graduation candidate per LESSONS.md's own three-instance rule.

- A clean linter result can mean "nothing was checked": the frontmatter
  scope silently not matching, warning-level rules never affecting an
  exit code, and globs matching zero files all produced green results
  that were then cited as evidence of cleanliness.
- One signal, two consumers, no named distinction: Vale severities were
  tuned for the audit report while the commit gate silently inherited the
  resulting exit code, because CONTEXT.md described both as one mechanism.
- Measure a rule's false-positive rate at the severity you will ship it
  at: VagueQualifier was trialled at warning, where a false positive is
  free, and shipped at error, where it costs a blocked commit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:54:19 +00:00
Defame1297
aff5b6c4c8 chore(plugins): patch-bump bin, kyberforge and lint for shipped content changes 
The round-3 fixes changed shipped skill content in three plugins without
touching their manifests, so installed copies would keep serving the old
content from cache. plugin-author requires a patch bump for exactly this
reason: consumers use the version to detect changes.

It matters most for lint — anyone installed at 1.1.2 has a cached
vale-run/SKILL.md stating that Vale exits non-zero on warnings, which is
backwards and would lead them to build a gate that passes everything.

- bin        1.1.0 -> 1.1.1  (caveman: suppression comments removed)
- kyberforge 1.2.3 -> 1.2.4  (skill-audit/agent-audit: Vale step reworked)
- lint       1.1.2 -> 1.1.3  (vale-run: exit-code and suppression-syntax fixes)

Marketplace entries carry no per-plugin version, so both marketplace.json
files are unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:45:13 +00:00
Defame1297
149d564f6a fix(lint): make the Vale gate actually gate, drop VagueQualifier 
Round-3 review of PR #85 found the "enforcing" pre-commit hook enforced
nothing. Vale's exit code keys on error-level alerts alone: five of the
six rules were level: warning, so they exited 0, and pre-commit hides
output from a passing hook — the alerts were invisible and blocked
nothing. ADR-0013 rejected a report-only trial tier and then shipped one
by accident.

Flatten every rule to level: error. Vale's own exit code is then correct,
so the hook entry drops to a bare vale-wrap.sh call and the graded
error->FAIL / warning->SUGGESTION mapping disappears from both audit
skills: every alert is a FAIL, in the gate and the audit alike. No
ignorable tier, matching shellcheck, the test suite and
conventional-pre-commit.

Delete Kyberforge.VagueQualifier. Measured against the 41 skill/agent
files as they stood before the rule ever ran: 2 hits. One marginal
("very different" -> "fundamentally different"), one an unfixable false
positive — caveman/SKILL.md quotes "of course" as an example of filler,
a mention not a use — which forced the only Vale suppression comments in
the repo. Those four lines go with it; two of them were dead anyway,
suppressing a frontmatter-scoped rule on a body line. Held-out prose (273
files) fired 15 times, 9 inside out-of-scope research examples and the
rest one word in two idioms in a single doc. SentenceOpenerThereIs
survives: 22 held-out hits, both in-corpus hits clean rewrites, zero
suppressions.

Widen .vale.ini's globs to [**/SKILL.md], [**/agents/*.md] and
[**/*.agent.md]. The plugins/*/-prefixed globs scoped nothing — Vale's *
crosses /, so they already matched docs/research/examples/**/agents/*.md
and assets/templates/SKILL.md, the two paths CONTEXT.md claimed they
excluded. Scoping is and was the hook's files: regex. The old globs also
hid a silent false negative: a skill outside plugins/ matched no section,
so Vale reported 0 files and exited 0, which both audits read as clean.
They now treat a 0-file run as NOT RUN and fall back to full judgment.

Also:
- vale-wrap.sh resolves relative --config values and file arguments
  against the caller's cwd, as vale does, instead of the repo root, which
  hard-errored from a subdirectory and silently skipped flattening for
  file args that did not resolve from the root. Absolute paths inside the
  cwd are relativized so reports cite resolvable paths, not scratch ones.
- vale-run's exit-code model was documented backwards ("exits non-zero
  whenever it finds an alert at or above MinAlertLevel") and would have
  led anyone following it to build a gate that passes everything. Its
  Markdown suppression syntax was MDX-only and does not suppress in .md;
  corrected in the skill and its troubleshooting reference, with
  backtick/fence exemption documented as the first resort.
- skill-size-check.sh fails only above 500 lines, agreeing with
  skill-audit's validate.sh <= 500 pass.
- ADR-0013 and CONTEXT.md amended to match, recording why graded
  severities cannot gate.

Verified: 9 test scripts / 15 vale-wrap cases pass; vale-audit-prefilter,
skill-size-check and shellcheck pass --all-files; check-manifests and
claude plugin validate --strict clean. New tests fail against the old
script (3 of them) and pass against the new one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:42:15 +00:00
Defame1297
210b192613 docs(lint): add docs index for Vale research docs 
plugins/lint/docs/research/docs/vale/ had no top-level index pointing
into it, unlike plugins/kyberforge/docs/README.md which indexes its
own research directories. Add plugins/lint/docs/README.md mirroring
that convention: one line per file describing what it covers, plus a
provenance note tying the directory back to plugins/lint/sources.md
and the vale-config/vale-run skills that consume it.

Closes out a follow-up item from PR #85's review.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:21:21 +00:00
Defame1297
792d3e1852 fix(lint): resolve round-1 and round-2 review findings on the Vale prefilter 
Addresses PR #85's outstanding review items after grilling the open
questions against ADR-0013/CONTEXT.md/ADR-0010:

Blocking fixes:
- vale-wrap.sh: replace json.dumps() escaping (which silently defeated
  Vale's frontmatter scope on any description containing a quote,
  backslash, or non-ASCII char — ~58% of the corpus) with a single-quoted
  YAML scalar, substituting a Unicode right single quote for embedded
  apostrophes rather than '' doubling (Vale's frontmatter scanner isn't a
  full YAML parser and silently truncates on '' too).
- vale-wrap.sh: fix a blank-line-inside-a-folded-description truncation
  bug via indentation-based, blank-line-tolerant body capture; narrow
  flattening to `>`-style scalars only (`|` already works unflattened).
- skill-audit/agent-audit Step 1: make the vale-wrap.sh invocation
  cwd-independent via git rev-parse --show-toplevel, fixing a bug where
  no single cwd satisfied all three Step 1 commands.
- styles/Kyberforge/VagueQualifier.yml: prune 17 tokens verified
  false-positive-dominated on this repo's own voice via a real corpus
  sweep (obvious, clearly, usually, several, simple, easy, completely,
  simply, tiny, etc.), keep 13 with real or unattested noise. Revert the
  28 prose "fixes" those tokens drove across 14 skill files back to their
  original, correct wording, including a functional regression to
  caveman/SKILL.md's own filler-word list (a mention, not a use) — now
  guarded with vale-off comments against recurrence.

Gaps:
- --minAlertLevel=warning on the pre-commit hook and Step 1 invocation
  so warning-level rules actually surface, without collapsing the
  FAIL/SUGGESTION severity mapping skill-audit/agent-audit rely on.
- vale-wrap.sh: fix --config=<path> equals-form, absolute-path silent
  no-op, and a zero-file-argument stdin hang.
- Route vale-run and lint-runner through a documented wrapper script
  when a target repo has one, instead of unconditionally recommending
  bare `vale`.
- Wire Kyberforge.VagueQualifier/SentenceOpenerThereIs into skill-audit/
  agent-audit's dimension-mapping prose (Body discipline).
- Add plugins/lint/sources.md provenance for lint-runner (ADR-0010).
- Sync both marketplace.json lint-entry descriptions with plugin.json.
- Retune skill-size-check.sh's MAX_WORDS 5000->2900 (measured ~1.6-1.7
  tokens/word on this repo's corpus, the old value gated at ~8,500
  tokens against a stated 5,000 ceiling); fix the >/>= line-count
  boundary and wc -l undercount on files with no trailing newline.
- Document the vale binary as a Setup prerequisite in AGENTS.md.
- Fix SentenceOpenerThereIs's dead regex alternative and add a real
  sentence-start anchor/scope.
- Fix a stale docs/research/docs/vale/ index pointer in kyberforge's
  docs README (moved to plugins/lint/ in e1a5403).
- Rewrite ADR-0013's Consequences section past-tense to describe what
  actually landed, and record the styles-portability limitation
  (repo-root placement stays intentional; deferred to a separate
  session per this PR's review).

Test coverage: 9 new vale-wrap.sh fixtures (quotes, backslash/unicode,
blank-line paragraphs, --config= form, zero-arg/absolute-path handling,
literal-block no-regression) and boundary-pair tests for
skill-size-check.sh's line/word ceilings.

bash tests/run-tests.sh: 9 scripts + 125 bats assertions, all passing.
scripts/check-manifests.sh and claude plugin validate --strict: clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:21:21 +00:00
Defame1297
3324a73225 feat(lint): expand Vale audit prefilter into a broader plugin-content harness 
Deferred item from PR #85 review. Per ADR-0013: cherry-picks two low-noise
rules from trialing write-good/alex against the real corpus (VagueQualifier,
SentenceOpenerThereIs) into styles/Kyberforge rather than adopting either
package wholesale (both are tuned for blog prose and were noisy on this
repo's terse, imperative instruction files - see the ADR's rejected-rule
list). Adds a new skill-size-check pre-commit hook enforcing agentskills.io's
500-line/5,000-token SKILL.md ceiling, currently unenforced. Fixes the 28
resulting violations across 20 existing SKILL.md/agent files so the
enforcing pre-commit hook lands clean.

governance.md/CONTROLS.md were evaluated and excluded as rule sources -
they're org/CI-infrastructure controls, not prose patterns Vale can express.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QUDczvw1H3eEeMD29Q9Lbi
 2026-08-08 20:20:58 +00:00
Defame1297
544392be98 refactor(lint): genericize lint-runner dispatch and manifest wording 
lint-runner's description already promised other linters could be added
without changing its own contract, but Process hardcoded vale-config/
vale-run and .vale.ini by name. Switch to <linter>-config/<linter>-run
naming-convention dispatch so the promise holds. Drop the explicit
Vale callout from the plugin manifests' description/keywords to match.

Addresses a deferred item from PR #85 review.
 2026-08-08 20:20:58 +00:00
Defame1297
bbb0dcd21a fix(lint): flatten multi-line frontmatter descriptions before Vale runs 
Vale's text.frontmatter.description scope silently stops matching once
the description is a YAML block scalar spanning 2+ physical lines —
the style used by most skills/agents in this repo. scripts/vale-wrap.sh
flattens the description to one line in a scratch copy (preserving the
repo-relative path and total line count) before invoking real vale, and
both audit skills plus the pre-commit hook now call it instead of vale
directly. Also tightens the pre-commit hook's file glob to single path
segments so it can't cross into docs/research examples or asset
templates the way the audit skills' scoped invocations already avoid.

Addresses PR #85 review feedback.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297
8d56290414 feat(lint): wire Vale as commit-stage pre-commit hook 
Adds vale-audit-prefilter as a local pre-commit hook scoped to skill/agent
markdown files, matching the invocation pattern skill-audit/agent-audit
already use. Runs at commit-stage only since it's a fast deterministic
prefilter; push-stage already covers the full test suite and manifest checks.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297
cbc33d952e feat(kyberforge): wire Vale as deterministic prefilter for skill-audit/agent-audit 
Adds repo-root .vale.ini plus a custom Kyberforge style (description-opener,
vague-wording, and generic reference-pointer padding rules) and a
KyberforgeCopilot style scoped to .agent.md files (Use proactively check).
skill-audit and agent-audit Step 1 now run vale against the specific file(s)
being audited and defer the corresponding Description/Patterns/Body checks
to its output instead of re-deriving them by LLM judgment, per the split
proposed in issue #84.

Closes #84

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297
f326df4861 chore(lint): register lint plugin in marketplace and document scope 
Adds the lint plugin entry to both marketplace manifests and records
the resolved scope/structure decisions from grilling in CONTEXT.md:
standalone repo-agnostic plugin, split vale-config/vale-run skills,
report-only lint-runner agent, audit-pipeline wiring deferred.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297
57bdfa92e8 fix(lint): resolve audit findings on vale skills 
Merge duplicate gotcha in vale-config (Packages vs BasedOnStyles was
stated twice) and align vale-run's category field with vale-config's
(lint, not linting) so sibling skills in the plugin agree.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297
59ad2a3cbd feat(lint): add lint-runner agent 
Report-only agent that composes vale-config/vale-run to run a lint
sweep over a scope and return normalized findings — no Edit tool, it
flags issues rather than fixing them. Also lands the plugin manifest
scaffold (plugin.json, .claude-plugin/plugin.json) that the earlier
vale-config/vale-run skill commits assumed but didn't carry, bumped
to 1.1.0 for the new agent.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297
8b00728374 feat(lint): add vale-run skill 
Covers invoking the vale CLI and interpreting its output — output
formats, severity filtering, exit-code handling, and false-positive
triage — for an already-configured project.
 2026-08-08 20:20:58 +00:00
Defame1297
d1afdbeff7 feat(lint): add vale-config skill 
Covers Vale install and .vale.ini setup — StylesPath, built-in/
third-party/custom styles, BasedOnStyles activation. Setup half of
Vale support; vale-run (running/interpreting) is a separate skill.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297
5e22672189 docs(kyberforge): add vale.sh research docs 
Prep work for issue #84 - gathers Vale (vale.sh) config, styles/rules,
CLI, installation, and troubleshooting reference material into
plugins/kyberforge/docs/research/docs/vale/ alongside the existing
research topics.

Refs #84
 2026-08-08 20:20:58 +00:00
Defame1297
0ba8a95188 Merge pull request 'docs(agents-md): shrink AGENTS.md and prefer plugin skills over shell' (#86) from refactor/agents-md-prefer-plugin-skills into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/86
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-07-24 21:24:28 +00:00
Defame1297
533364029a docs(agents-md): shrink AGENTS.md and prefer plugin skills over shell 
AGENTS.md had grown to duplicate content owned elsewhere: behavioral
rules already active globally via ~/.agents/AGENTS.md, a VISION.md
read-on-demand entry CONTEXT.md already covers at session start, and
setup/testing/commit instructions that explained hook mechanics the
git plugin's pc-run/git-commits skills already own. It also gave no
explicit steer toward using installed plugin skills over raw shell
commands, so agents defaulted to shelling out to git directly.

- Added a "Prefer plugin skills over raw shell" section mapping
  operations (commits, branches, hooks, issues/PRs, linting, AGENTS.md
  itself) to the skill that owns them.
- Collapsed Setup/Testing/Commit-conventions into one section, keeping
  only the two genuinely non-obvious gotchas (missing
  default_install_hook_types, bats submodule auto-init).
- Removed the "Subagent orchestration" section: its content was mostly
  universal Agent/Task/worktree-tool facts, not specific to working in
  this repo, so it moves to core/instructions/subagent-orchestration.md
  (deployed globally via install.sh, referenced from core/AGENTS.md's
  content index) rather than staying repo-local.
- Removed agentsmd-author's "not this repo's own" scope exclusion in
  CONTEXT.md (ADR-0012 never mandated it) so this task could route
  through it, and folded the forge-routing rule it left behind into
  CONTEXT.md's existing Skill composition entry.

AGENTS.md: 50 -> 40 lines. Full test suite and manifest check pass.
 2026-07-24 21:19:17 +00:00
Defame1297
8cfef26491 Merge pull request 'chore(settings): enable gitea plugin' (#83) from chore/settings-enable-gitea-plugin into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/83
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-07-23 18:15:11 +00:00
Defame1297
b9249df1c1 chore(settings): enable gitea plugin 
Adds gitea@holocron to enabledPlugins now that the gitea skill/plugin has replaced the old flat skill.
 2026-07-23 18:14:00 +00:00
Defame1297
00cbe2b6c2 Merge pull request 'chore(gitea): remove old flat gitea skill, superseded by plugins/gitea' (#82) from chore/remove-old-gitea-skill into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/82
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-07-23 18:10:15 +00:00
Defame1297
1764781d10 chore(plugins): bump bin and gitea versions for skill relocation 
plugins/bin loses a whole skill (gitea removed) — minor bump (1.0.5 ->
1.1.0) to reflect the capability-surface change. plugins/gitea gains a
reference file and a README fix, no new capability — patch bump
(1.3.1 -> 1.3.2).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
 2026-07-23 18:08:46 +00:00
Defame1297
3a1305c438 chore(gitea): remove old flat gitea skill, superseded by plugins/gitea 
The deep-module split in plugins/gitea/ (ADR 0011) already covers every
domain the old plugins/bin/skills/gitea/ flat skill handled. Move its
token-access.md into plugins/gitea/references/ first, since it held
empirical scope-test results (Actions/CI, Wiki, Notifications, Packages,
User/Org) not reproduced anywhere in the new plugin, then drop the old
skill and fix a stale cross-reference pointing at it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
 2026-07-23 18:04:37 +00:00
Defame1297
638e60846b Merge pull request 'docs(agents): add setup, testing, and commit conventions' (#81) from docs/agentsmd-setup-testing-conventions into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/81
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-07-23 17:53:44 +00:00
Defame1297
f86f0b57bc docs(agents): add setup, testing, and commit conventions 
AGENTS.md had no Setup, Testing, or Commit/PR sections even though the
repo has verifiable, non-obvious conventions for all three: pre-commit
hooks span three stages with no default_install_hook_types set (a plain
`pre-commit install` silently skips commit-msg/pre-push), tests/run-tests.sh
runs the full suite, and conventional-pre-commit enforces Conventional
Commits. Agents working in this repo had no way to discover these without
reading the pre-commit config and scripts directly.
 2026-07-23 17:52:35 +00:00
Defame1297
8abb311cf4 Merge pull request 'feat(core): add AGENTS.md authoring/review tooling' (#80) from feat/79-agentsmd-tooling into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/80
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-07-23 17:46:08 +00:00
Defame1297
bb34aa0eb5 feat(core): add content-guide.md to agentsmd-author 
PR review feedback: Step 3 gave no concrete guidance on what good
AGENTS.md content looks like, and the skill had no substantive
references file (only provenance bookkeeping in sources.md), unlike
sibling kyberforge skills. Adds section-by-section content guidance,
the worked example, and monorepo precedence rules synthesized from
the agentsmd research corpus.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
 2026-07-23 17:40:27 +00:00
Defame1297
250c486ce1 docs(core): add plugin README 2026-07-23 17:31:14 +00:00
Defame1297
1fcee54c1e docs(context): fix stale ADR-0012 references to correct ADR-0002/0003 2026-07-23 17:31:04 +00:00
Defame1297
d6b0292da7 chore(core): bump version to 1.1.0 for new skill content 
core gained three skills for the first time (agentsmd-author,
agentsmd-audit, provider-adapter-author). Minor bump reflects new
capability rather than a fix. Also declares the missing `skills`
path in the Copilot manifest so Copilot CLI discovers them
(CC auto-discovers from the plugin root; Copilot requires explicit
declaration per ADR-0016 convention).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
 2026-07-23 17:29:02 +00:00
Defame1297
956ff7a54a feat(core): add agentsmd-author skill 
Creates/updates a target repo's AGENTS.md by exploring real repo
conventions, supports nested monorepo placement, closes out via
agentsmd-audit, and composes into provider-adapter-author for
provider-file reconciliation. Completes the three-skill trio from
ADR-0012.
 2026-07-23 17:25:43 +00:00
Defame1297
6fd6876264 feat(core): add provider-adapter-author skill 
Converts a target repo's provider-specific instruction file (CLAUDE.md,
.cursor/rules, copilot-instructions.md, etc.) into a thin adapter over
AGENTS.md, mirroring this repo's own two-tier CLAUDE.md pattern
(ADR-0002/0003). Self-validates via a bundled deterministic script
(scripts/validate-adapter.sh) rather than a separate paired audit skill.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
 2026-07-23 17:19:17 +00:00
Defame1297
04e7006f76 fix(core): list scripts/ and tests/ READMEs in agentsmd-audit file table 
Independent clean-context audit recheck flagged that README.md's file
table omitted scripts/README.md and tests/README.md despite both
existing on disk, inconsistent with sibling kyberforge skills.
 2026-07-23 17:12:17 +00:00
Defame1297
6c8ea8e8f0 feat(core): add agentsmd-audit skill files 
The previous commit only landed the research-folder rename — a multi-path
git add silently failed and left CONTEXT.md, ADR-0012, and the actual skill
files unstaged. This lands them: the agentsmd-audit skill itself (three
deterministic validators for secrets, structure, and drift against a target
repo's AGENTS.md), its bats test suite, provenance record, and the
CONTEXT.md/ADR entries documenting why this lives in core rather than
kyberforge.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
 2026-07-23 17:08:19 +00:00
Defame1297
40a045958f feat(core): add agentsmd-audit skill 
Audits a target repo's AGENTS.md file(s) for embedded secrets, structural
completeness against the agents.md common-sections checklist, and drift
(referenced commands/paths that no longer resolve). First active skill in
the core plugin — kyberforge is scoped to marketplace-factory meta-tooling,
not generic target-repo documentation (see ADR-0012). Moves the agentsmd
research corpus from plugins/kyberforge to plugins/core to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
 2026-07-23 17:06:48 +00:00
Claude Code AI - Gitea MCP
bc7b3ecdbf refactor(gitea): deep modules — split flat dispatch skill into 6 domain skills + orchestrator + agent (#67) 2026-07-05 19:53:26 +00:00
Claude Code AI - Gitea MCP
060771b481 fix(tests): auto-init submodules when bats binary is missing (#77) 2026-07-05 13:49:49 +00:00
Defame1297
3b4763ece9 Merge pull request 'docs(agents): document worktree/branch cleanup as part of PR close-out' (#76) from docs/75-worktree-branch-cleanup into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/76
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-07-05 13:37:21 +00:00
Defame1297
fcff7deb2c docs(agents): document worktree/branch cleanup as part of PR close-out 
Adds a bullet to the Subagent orchestration section in AGENTS.md so
coordinators treat merged-PR cleanup as one atomic step: verify the
merge, force-remove the worktree (double -f, since this repo's test
runs initialize submodules), and delete both the feature branch and
any Agent-tool-generated worktree-agent-<id> isolation branch.

Fixes #75

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
 2026-07-05 13:35:24 +00:00
Defame1297
c395acfa57 Merge pull request 'fix(kyberforge): require git-log commit verification and forbid self-spawned rechecks' (#74) from fix/69-71-factory-authoring-fixes into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/74
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-07-05 13:24:52 +00:00
Defame1297
c60ec5f2f7 chore(kyberforge): bump plugin version to 1.2.3 
skill-author and agent-author SKILL.md files received bug fixes (git-log
commit-hash verification before reporting completion, skill-author now
forbids self-spawning audit/recheck subagents during its authoring pass,
and agent-author closed checklist/coverage gaps). Patch bump to reflect
fixed behavior, not new capability.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
 2026-07-05 13:20:07 +00:00
Defame1297
f657123931 fix(kyberforge): fix checklist/action mixing and improve-flow source_keys gap in agent-author 
The Prerequisites checklist mixed items to confirm (preconditions) with an
action to perform (capturing git log), so the following "stop and ask if
missing" gate didn't logically apply to the git-log step. The improve flow
also had no reminder to update source_keys/sources.md when an edit touches
research-sourced content, unlike the create flow's explicit step for it.

Refs #69
 2026-07-05 13:20:07 +00:00
Defame1297
fe24f7d900 fix(kyberforge): close agent-author frontmatter-comment and audit-availability gaps 
Independent skill-audit found that agent-author's closing checklists never
verified template <!-- --> comments were stripped from frontmatter (produces
invalid YAML if left in), the Copilot field-exclusion checklist omitted two
fields present in the authoritative list, and the improve flow had no
agent-audit availability check unlike the create flow.
 2026-07-05 13:20:07 +00:00
Defame1297
b0903f190a fix(kyberforge): require commit-hash verification in agent-author 
Prior sessions had authoring subagents report completion after only
staging changes (git diff --stat showing output, but no git commit).
agent-author's create and improve flows now require capturing
git log --oneline -1 before and after the authoring pass and asserting
the hash actually changed via a real commit, matching the fix already
applied to skill-author.

Refs #69
 2026-07-05 13:20:07 +00:00
Defame1297
3eb216afa6 fix(kyberforge): use consistent slash-command form for forge reference 
Refs #69, #71
 2026-07-05 13:20:07 +00:00
Defame1297
fc79acfa05 fix(kyberforge): tighten skill-author checklist/phrasing/reference style 
Address round-2 independent-audit suggestions: single-item checklist
misuse in the improve flow, inaccurate "before Step 1" phrasing, and an
unbackticked cross-skill reference to kyberforge:forge.

Refs #69, #71
 2026-07-05 13:20:07 +00:00
Defame1297
8b92590dc9 fix(kyberforge): surface commit-hash checklist earlier, drop redundant scripts line in skill-author 
Independent /skill-audit recheck flagged the git-log-capture instructions
as discoverable only at close-out (Step 6/Step 5), long after the step
where the hash should actually be snapshotted. Adds the capture checklist
item to Prerequisites (create flow) and Step 1 (improve flow) instead of
leaving it as a retrospective-only note. Also drops a sentence in the
improve flow's Step 4 that duplicated the preceding one on editing
scripts/reference files directly.

Refs #69
 2026-07-05 13:20:07 +00:00
Defame1297
caebc42bad fix(kyberforge): require commit-hash verification and forbid self-spawned rechecks in skill-author 
Prior sessions had authoring subagents report completion after only
staging changes (git diff --stat showing output, but no git commit),
and one run self-spawned its own audit/recheck subagent instead of
leaving that to forge's outer loop, losing an uncommitted draft when
the stray subagent's worktree was torn down.

Refs #69, #71
 2026-07-05 13:20:07 +00:00
Defame1297
ccc34138a7 Merge pull request 'docs(agents): document fork task-scope and TaskList access constraints' (#73) from docs/68-70-subagent-orchestration-guidance into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/73
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-07-05 13:02:44 +00:00
Defame1297
3bab757f29 docs(agents): document fork task-scope and TaskList access constraints 
Adds a Subagent orchestration section to AGENTS.md so orchestrating
agents know upfront: forks must stop once their assigned task is done
rather than autonomously draining a shared TaskList, governance-gated
actions must not be exposed to forks without a fresh confirmation
round, and TaskGet/TaskUpdate/TaskList are fork-only so the coordinator
must own task-list bookkeeping for fresh subagents itself.

Refs #68, #70

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
 2026-07-05 13:00:05 +00:00
Defame1297
8b9989e200 Merge pull request 'fix(install): resolve git hooks dir via git plumbing, fix stale plugin manifests' (#72) from fix/plugin-manifest-and-worktree-hooks into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/72
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-07-05 12:59:19 +00:00
Defame1297
ba53e6544b fix(tests): isolate test-git-hooks-install.sh from inherited GIT_* env vars 
The test's own `git -C "$TEMP_REPO" init` silently re-targets an inherited
GIT_DIR instead of creating a repo in the temp dir when this test itself
runs inside a git hook (e.g. pre-push sets GIT_DIR to the invoking repo's
gitdir). Unset all GIT_* vars at the top of the script so the temp repo
fixture is actually isolated regardless of the calling context.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
 2026-07-05 12:52:52 +00:00
Defame1297
a43820725f fix(install): resolve git hooks dir via git plumbing, drop stale manifest fields 
scripts/install.sh hardcoded $REPO_ROOT/.git/hooks, which breaks under any
git worktree checkout (.git is a file there, not a directory) — this is
what blocks every worktree-based agent from pushing cleanly. Resolve the
hooks directory via `git rev-parse --git-path hooks` instead, normalizing
to an absolute path since git returns it relative to the queried repo root
for plain checkouts but absolute for worktrees.

Also drops `agents`/`skills` fields from plugins/bin, plugins/core, and
plugins/gitea plugin.json where the referenced directories don't exist on
main yet (bin never had an agents/ dir; core and gitea's real skill/agent
content is still pending merge from an in-flight branch) — these were
failing scripts/check-manifests.sh and blocking pushes for unrelated work.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
 2026-07-05 12:44:26 +00:00
151 changed files with 9093 additions and 241 deletions
Expand all files Collapse all files

7
.claude-plugin/marketplace.json
View File

@@ -38,7 +38,12 @@
"repo": "mattpocock/skills",
"source": "github"
}
},
{
"description": "Skills and agents for configuring and running linters.",
"name": "lint",
"source": "./plugins/lint"
}
],
"version": "0.2.0"
"version": "0.3.1"
}

1
.claude/settings.json
View File

@@ -3,6 +3,7 @@
"bin@holocron": true,
"core@holocron": true,
"git@holocron": true,
"gitea@holocron": true,
"kyberforge@holocron": true
},
"hooks": {

7
.github/plugin/marketplace.json vendored
View File

@@ -38,7 +38,12 @@
"repo": "mattpocock/skills",
"source": "github"
}
},
{
"description": "Skills and agents for configuring and running linters.",
"name": "lint",
"source": "./plugins/lint"
}
],
"version": "0.2.0"
"version": "0.3.1"
}

45
.pre-commit-config.yaml
View File

@@ -61,6 +61,24 @@ repos:
pass_filenames: false
always_run: true
- id: check-vale-style-sync
name: Check Vale style copies are in sync
description: Diff skill-audit's Vale copy against agent-audit's canonical copy
entry: bash scripts/check-vale-style-sync.sh
language: system
stages: [pre-push]
pass_filenames: false
always_run: true
- id: check-release-needed
name: Check a release tag covers .pre-commit-hooks.yaml's paths
description: On push to main only, fail if files exposed via .pre-commit-hooks.yaml changed since the last tag
entry: bash scripts/check-release-needed.sh
language: system
stages: [pre-push]
pass_filenames: false
always_run: true
- id: validate-plugins
name: Validate plugins
description: Run claude plugin validate --strict on every plugin directory
@@ -98,6 +116,33 @@ repos:
fi
done
- id: skill-size-check
stages: ['pre-commit']
name: SKILL.md size ceiling
description: Enforce agentskills.io's 500-line/5,000-token SKILL.md size ceiling
entry: scripts/skill-size-check.sh
language: script
files: '^plugins/[^/]+/skills/[^/]+/SKILL\.md$'
pass_filenames: true
- id: vale-audit-prefilter-skill
stages: ['pre-commit']
name: Vale audit prefilter (SKILL.md)
description: Run Vale against SKILL.md files as a deterministic prefilter for skill-audit, via skill-audit's own bundled copy
entry: plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
language: script
files: '^plugins/[^/]+/skills/[^/]+/SKILL\.md$'
pass_filenames: true
- id: vale-audit-prefilter-agent
stages: ['pre-commit']
name: Vale audit prefilter (agent files)
description: Run Vale against agent markdown files as a deterministic prefilter for agent-audit, via agent-audit's own bundled copy
entry: plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
language: script
files: '^plugins/[^/]+/agents/[^/]+\.md$'
pass_filenames: true
- repo: meta
hooks:
- id: check-hooks-apply

20
.pre-commit-hooks.yaml Normal file
View File

@@ -0,0 +1,20 @@
- id: kyberforge-vale-audit-skill
name: Kyberforge Vale prose audit (SKILL.md)
description: Deterministic prose-pattern prefilter for kyberforge's skill-audit, via its own bundled Vale config/styles
entry: plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
language: script
files: '(^|/)SKILL\.md$'
- id: kyberforge-vale-audit-agent
name: Kyberforge Vale prose audit (agent files)
description: Deterministic prose-pattern prefilter for kyberforge's agent-audit, via its own bundled Vale config/styles
entry: plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
language: script
files: '(^|/)agents/[^/]+\.md$|\.agent\.md$'
- id: kyberforge-skill-size-check
name: SKILL.md size ceiling
description: Enforce agentskills.io's 500-line/5,000-token SKILL.md size ceiling
entry: scripts/skill-size-check.sh
language: script
files: '(^|/)SKILL\.md$'

27
AGENTS.md
View File

@@ -1,26 +1,41 @@
# Working in this repo
This repo is the global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects.
This repo is the global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Built as a homelab tool intended to scale to professional environments.
## Structure
- `plugins/` — installable plugin units; each is self-contained (skills, agents, hooks, MCP servers, bundled assets); install separately via `claude plugin install <name>@holocron`
- `providers/claude-code/` — Claude Code adapter (deployed to `~/.claude/` via `install.sh`)
## Prefer plugin skills over raw shell
This repo dogfoods its own plugins. Before shelling out to git, gitea, or lint tooling directly, check whether an installed skill already owns the operation — it usually does:
- Commits, branches, history, worktrees, remotes → `git:git-commits`, `git:git-branches`, `git:git-history`, `git:git-worktrees`, `git:git-remotes`
- Pre-commit hook install/config/troubleshooting → `git:pc-run` / `git:pc-author`
- Issues, PRs, labels, milestones → `gitea:gitea-issues`, `gitea:gitea-prs`, `gitea:gitea-labels-milestones`; also `gitea:gitea-branches`, `gitea:gitea-files`, `gitea:gitea-releases`, or `gitea:gitea-workflow` when the domain is ambiguous
- Vale prose linting → `lint:vale-config` / `lint:vale-run`
- This repo's own AGENTS.md → `core:agentsmd-author` / `core:agentsmd-audit`
Fall back to raw shell only when no skill covers it.
## Setup and testing
- Install git hooks via `git:pc-run`, wiring all three stages — this repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits) and `pre-push` (tests, manifest check).
- Install the `vale` binary — required by the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, which run on every commit touching a `SKILL.md` or agent `.md` file. Without it the hooks fail with a bare "command not found" and no install pointer. `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or see https://vale.sh/docs/vale-cli/installation/. No `vale sync` needed — the `Kyberforge` styles are committed under `plugins/kyberforge/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded packages (see ADR-0014).
- Run `bash tests/run-tests.sh` before considering any change done — it runs every `test-*.sh` script in the repo plus the bats suite (`--bats-only` for just bats). First run auto-initializes the bats submodules; no manual `git submodule update` needed.
- Pushing re-runs the full suite plus `scripts/check-manifests.sh` via the pre-push hook — same commands, so run them locally first.
- Author commits with `git:git-commits` — it validates Conventional Commits (enforced at `commit-msg`) for you.
## Key documents
Read CONTEXT.md at the start of every session in this repo.
Read these on demand:
- `docs/VISION.md` — purpose, goals, and long-term Management Application vision
- `docs/spec/architecture.md` — current directory structure, install pipeline, provider model
- `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes
- `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification
- `docs/research/ai-coding-factory/ai-coding-factory-principles.md` — factory design rationale; read when implementing, auditing, or reviewing skills or factory structure
- `docs/notes/factory-integration-decisions.md` — decisions from the factory integration grill; read when making skill authoring or factory design decisions
- Governance rules are always in effect — `core/instructions/governance.md` (agent rules); `docs/research/governance_principles/CONTROLS.md`
## Working context
This repo is built by a junior developer as a homelab tool intended to scale to professional environments. Challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them.

22
CONTEXT.md
View File

@@ -8,7 +8,7 @@ description: Domain language and decisions for the global AI development config
## Principles
### CLAUDE.md index model
`AGENTS.md` is the source of always-on universal rules (provider-agnostic). `providers/claude-code/CLAUDE.md` is a thin adapter: it imports `~/.agents/AGENTS.md` via `@~/.agents/AGENTS.md` and appends Claude Code-specific additions (`@import` for governance.md, content index). Deployed to `~/.claude/CLAUDE.md` via `install.sh`. Context size is kept minimal — only what is needed every session is loaded upfront; detailed content is pulled on demand. See ADR-0012.
`AGENTS.md` is the source of always-on universal rules (provider-agnostic). `providers/claude-code/CLAUDE.md` is a thin adapter: it imports `~/.agents/AGENTS.md` via `@~/.agents/AGENTS.md` and appends Claude Code-specific additions (`@import` for governance.md, content index). Deployed to `~/.claude/CLAUDE.md` via `install.sh`. Context size is kept minimal — only what is needed every session is loaded upfront; detailed content is pulled on demand. See ADR-0003.
### Instruction file format
`core/instructions/<topic>.md` files are plain markdown — no frontmatter, no schema. The agent decides when to read each file based on task context and the content index label in `providers/claude-code/CLAUDE.md`. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice.
@@ -46,10 +46,10 @@ The provider-agnostic always-on instruction entry point. Two files:
- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules); imported by repo `CLAUDE.md` via `@AGENTS.md`.
- **Global `core/AGENTS.md`** — Communication and Behavior rules that apply across all projects; deployed to `~/.agents/AGENTS.md`; imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`.
Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0012.
Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0003.
### Skill composition
A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`.
A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). Reserve `forge` for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (`skill-author`, `plugin-author`, `agentsmd-author`, etc.); routing a known fix through `forge`'s grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`.
### Provider-agnostic issue tracker
Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0017). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it).
@@ -60,5 +60,21 @@ The three-stage traceability record linking a skill back to its research inputs:
### Bidirectional reference principle
Files that reference other files should declare those references explicitly. The referencing file carries the forward reference (e.g. content index in `CLAUDE.md`, `references:` in frontmatter). The referenced file carries a `when:` field describing when it is loaded. Both sides should agree — divergence signals staleness. The reverse map ("what files reference this file?") is derived by a reference scanner script, not maintained manually. This principle applies to instruction files, skills, and workflow documents.
### agentsmd-author / agentsmd-audit
A skill pair in the `core` plugin for writing, updating, and reviewing a repo's `AGENTS.md` file(s) — the generic open-standard file (see the `AGENTS.md` entry above), including this repo's own. `agentsmd-author` creates/updates AGENTS.md content, supports nested monorepo placement (per the standard's nearest-file-wins precedence), and closes out by invoking `agentsmd-audit` inline. `agentsmd-audit` runs a single combined pass checking three mandatory baselines: secrets/credentials (governance.md hard prohibition — AGENTS.md is committed content), structural completeness (common-sections checklist from the agents.md spec), and accuracy/drift (do referenced commands and paths actually resolve against the repo). `agentsmd-audit` never inspects provider adapter files (see `provider-adapter-author`) — its scope is AGENTS.md content only. Chosen over folding this into `kyberforge` because kyberforge's scope is meta-tooling for the holocron marketplace itself, not generic target-repo documentation; `core` is the intended home for cross-cutting, repo-agnostic utility skills.
### provider-adapter-author
A companion skill (`core` plugin) that detects a target repo's provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) and, where it duplicates content AGENTS.md should own, converts it into a thin adapter that imports AGENTS.md — mirroring this repo's own ADR-0002/ADR-0003 two-tier adapter pattern. Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`: checks for an import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — the check is mechanical, so a script suffices per governance.md's "prefer deterministic code for repeatable tasks." `agentsmd-author` calls this skill via skill composition when it detects an existing provider file with overlapping content.
### lint plugin
A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
### Vale audit prefilter (skill-audit / agent-audit)
Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it doesn't live in `plugins/lint/` — but per ADR-0014 it also doesn't live at the repo root anymore. Two copies live inside `plugins/kyberforge/`, one per skill, since a plugin's cache-install only copies each skill's own files (no cross-skill sharing): `plugins/kyberforge/skills/agent-audit/assets/vale/` is canonical (`.vale.ini` plus a custom `Kyberforge` style covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check), and `plugins/kyberforge/skills/skill-audit/assets/vale/` is a smaller duplicate (`Kyberforge` only, scoped to `SKILL.md`) kept in sync by `scripts/check-vale-style-sync.sh` (pre-push). A root-level `.pre-commit-hooks.yaml` exposes both copies (plus `skill-size-check`) so any external repo can enforce the same rules via `repo: <this-repo-url>, rev: <tag>` in its own `.pre-commit-config.yaml` — pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the `kyberforge` plugin is installed at all, and the same mechanism covers CI (`pre-commit run --all-files`). This repo's own `vale-audit-prefilter-skill`/`-agent` pre-commit hooks consume the identical plugin-bundled copies via `repo: local` (not a third root copy, and not a pinned self-reference — a pinned self-reference would lint working-tree edits against the last tagged release rather than the change being made). Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching on most — not all — multi-line descriptions. Verified by reproduction, not assumed: `>` folded scalars, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars all yield 0 alerts and exit 0 on a deliberately-bad fixture, while a `|` literal block spanning the same 2+ lines lints normally (alerts fire, exit 1). The wrapper flattens those three broken forms to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; `|` literal blocks and single-line descriptions pass through untouched, already linting correctly. The plain and quoted forms previously passed silently — unflattened and unmatched — so a bad description in either sailed through the prefilter. Handed no `--config` at all, the wrapper falls back to its own sibling `assets/vale/.vale.ini`, located from `${BASH_SOURCE[0]}` rather than from the cwd — which is why both manifests' `entry:` is now the bare script path with no argument after it. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: a `--config` in `.pre-commit-hooks.yaml` pointed at a path no consumer has and hard-failed every external run with `E100 [--config] Runtime error`. `.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical — the local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was* this repo, and that divergence is why three review rounds exercised a path no external consumer takes and missed the defect. An explicit `--config` still wins, in all three argv forms (`--config X`, `--config=/abs`, `--config=rel`), and a relative one still resolves against the caller's cwd, matching bare `vale`, not the repo root. Both audit skills' Step 1 now passes no `--config` either: it resolves the script relative to the skill's own directory so the call works from an installed plugin cache, but a relative `--config` alongside it would still resolve against the cwd, yielding `E100 Runtime error ... does not exist` and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades to full LLM judgment. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex and from the audit skills passing one explicit file per invocation. The two manifests scope differently on purpose: this repo's `.pre-commit-config.yaml` pins its own layout — `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/agents/[^/]+\.md$` for `-agent` — while the shipped `.pre-commit-hooks.yaml` stays layout-agnostic for external consumers whose skills live anywhere, using `(^|/)SKILL\.md$` and `(^|/)agents/[^/]+\.md$|\.agent\.md$`. Both manifests split the prefilter into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type. A `SKILL.md` outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted normally — the globs constrain filename shape, not location. Vale reports 0 files only when the path it is handed matches no glob section at all: a differently-named file, or a directory argument holding nothing that matches. That run prints `✔ 0 errors ... in 0 files.` and exits 0, indistinguishable from a clean pass, so both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the 41 skill/agent files, one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's `SKILL.md` ceiling as two blocking gates: `MAX_LINES=500` and `MAX_WORDS=2770` (a word-count proxy for the 5,000-token limit, calibrated to the densest prose measured in this repo — 1.81 tokens per word — so even a worst-case `SKILL.md` at the ceiling stays under 5,000 tokens). Both are inclusive, and `skill-audit/scripts/validate.sh` checks the same pair on the same terms, so a `SKILL.md` can no longer pass its own audit yet be blocked by the commit hook. Scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter-skill`, so it never lints `docs/research/examples/` reference skills. It's also exposed in the root-level `.pre-commit-hooks.yaml` as `kyberforge-skill-size-check` — it has no external asset dependency, so it needed no relocation, only exposure to external consumers. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
### LESSONS.md
Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.

36
LESSONS.md
View File

@@ -126,6 +126,42 @@ Two forks independently fixed `references/sources.md` with different approaches
When briefing an agent to implement a new skill, the instinct is to tell it to write the SKILL.md and supporting files directly. This bypasses Step 5 of the skill-author process (provenance), which requires reading all research `sources.md` files and recording every `extracted` slug in META.md. The `validate-provenance.sh` script catches the gap — but only after the commit, requiring a fix round. This pattern recurred twice in one session (plugin-author and marketplace-author initial implementation, then again in the first round of fix agents). Fix: briefs for implementation agents must explicitly say "invoke `/skill-author` (read and follow `plugins/kyberforge/skills/skill-author/SKILL.md`)" — not "write the skill files." Invoking the skill is the only reliable way to ensure all process gates, including provenance, run.
## 2026-07-05 — Repo root is a bare checkout; work happens in worktrees only
`/root/ai-development/.git` has `core.bare = true` — the root directory itself has no working tree. Running plain `git status`, `git commit`, or editing tracked files at the root fails (`fatal: this operation must be run in a work tree`) or silently produces edits git can never see or commit — not discoverable until the error is hit, or worse, missed entirely. All real work — including one-line docs fixes — requires `git worktree add <path> -b <branch> origin/main` first. Fresh worktrees also don't have submodules (`tests/bats`, `docs/wiki`, etc.) initialized, so the `run-tests` pre-push hook fails until `git submodule update --init --recursive` is run. Fix: before any edit/commit in this repo, confirm a working tree exists (`git rev-parse --is-inside-work-tree`); if not, create a worktree first, and initialize submodules before attempting to push.
## 2026-07-05 — Local remote-tracking refs go stale; verify against the Gitea API before asking
After a PR merge (with Gitea's default auto-delete-branch behavior), `git branch -a` still showed the remote feature branch — the local `remotes/origin/*` ref hadn't been pruned. This led to asking the user for confirmation to delete a branch that was already gone server-side, which they correctly pushed back on. Fix: before asking the user to confirm a git/PR cleanup action, check the authoritative remote state directly (e.g. `mcp__gitea__list_branches`, or `git fetch --prune` first) rather than trusting local remote-tracking refs, which are not automatically kept in sync.
## 2026-05-18 — Planning meta-commentary does not belong in deployed artifacts
During write-skill refactor, an "open thread" note (about a deferred research step) was written directly into the SKILL.md Process section. The user caught it. The rule it violated: a deployed artifact (SKILL.md, a runtime file loaded by agents) must not contain planning meta-commentary — deferred items, open threads, and implementation notes belong in the issue file, which is the planning artifact. The skill body should contain only content relevant to runtime execution. If a decision is deferred, record it in the issue and leave no trace in the skill. The distinction: issue = planning record; skill = executable instruction.
## 2026-08-08 — A clean linter result can mean "nothing was checked"
Three separate times in one PR (#85), a check reported success because it had silently not run. (1) Vale's `text.frontmatter.description` scope stops matching once the value is a multi-line YAML block scalar — the style most skills here use — so a repo-wide sweep returned 0 alerts across 49 files and was read as a clean repo. (2) Five of six rules were `level: warning`, but Vale's exit code keys on `error` alone and pre-commit hides output from passing hooks, so those rules were invisible and blocked nothing for two review rounds while the ADR described them as "enforcing immediately." (3) `.vale.ini`'s globs matched no file outside `plugins/`, so Vale printed "0 files" and exited 0, which both audit skills read as "no findings" and used to skip their own judgment passes. Each time the green result was worse than no check at all, because it was cited as positive evidence of cleanliness. Fix: for any new check, prove it fails before trusting that it passes — run it against a deliberately-bad fixture, confirm the failure, then run the real corpus. Where a check can scan zero inputs, assert on the input count, not just the exit code. **[graduated → core/instructions/testing.md]** (4th instance below, kept for audit trail).
**5th instance (2026-08-09, PR #85 round 6):** `tests/test-vale-hooks-consumer.sh` asserted `grep -c "VagueWording" >= 2` across the *combined* output of both shipped Vale hooks, and the SKILL.md fixture alone raised two alerts — so one working hook satisfied the threshold and the agent hook could be disabled entirely (glob retargeted to match nothing) while the suite still reported `3 passed` under the message "both hooks flatten and flag". The `Skipped` guard did not catch it: the hook still *matched* the file, Vale simply linted nothing, reported `0 errors in 1 file`, and exited 0, which pre-commit renders as `Passed`. The general shape: **an assertion that aggregates over N subjects proves nothing about any individual subject** — a total is satisfiable by a proper subset. Fix: attribute each signal to its source before asserting (alerts are now filed by path, with a distinct trigger token per fixture so one hook's alert cannot be credited to another), and assert per subject. Corollary technique, now standing practice for any check whose failure mode is silence: run the mutation sweep in *reverse* as well — neuter each assertion in turn and confirm exactly one test case fails. Applied to `check-vale-style-sync.sh` it exposed two assertions bound to no failing case at all, one of them masked by a stronger check that ran first.
**4th instance (2026-08-09, ADR-0014):** splitting the single root `.vale.ini` into two skill-scoped copies (skill-audit: `SKILL.md` only; agent-audit: agent files only) meant a single retargeted pre-commit hook pointed at agent-audit's copy alone would have silently scanned 0 `SKILL.md` files and exited 0 — caught only because the full corpus was dry-run against both the old and new config and the outputs diffed before the old config was deleted, not because any test asserted on file counts. Standing practice going forward: when a Vale (or any linter) config that serves multiple file-glob scopes is split or moved, dry-run the full corpus through both the old and new config and diff the outputs before removing the superseded source — a hook silently scanning 0 files looks identical to a clean pass.
## 2026-08-08 — One signal, two consumers, no named distinction
Vale's output fed two consumers with different contracts: the audit skills read severity *strings* to grade a report (`error`→FAIL, `warning`→SUGGESTION), while the pre-commit hook read the process *exit code* to allow or block a commit. Severities were tuned for the first consumer; the second silently inherited whatever exit code that produced, which was always 0. CONTEXT.md described both as a single mechanism under one heading, which is precisely why the divergence went unnoticed — there was no vocabulary in which "the gate" and "the prefilter" were different things that could disagree. Fix: when one output feeds two consumers, name them separately in the domain language and state each contract explicitly. If they cannot be given independent contracts, collapse them into one — which is what happened here: every rule became `level: error`, so the gate and the audit now share a single verdict with nothing to keep in sync.
## 2026-08-08 — Measure a rule's false-positive rate at the severity you will ship it at
`Kyberforge.VagueQualifier` was cherry-picked from `write-good` after being trialled as "low-noise against this repo's corpus" — but the trial ran at `level: warning`, where a false positive costs nothing because nobody ever sees it. Shipped at `error`, the same false positive costs a blocked commit and a permanent suppression comment. Re-measured at the severity it actually shipped at, the rule scored one marginal true positive and one unfixable false positive across 41 files (`caveman/SKILL.md` *quotes* filler words as its subject matter — a mention, not a use), and was deleted. Fix: trial conditions must match shipping conditions. A noise measurement taken where false positives are free does not transfer to a context where they are expensive, and "low-noise" is not a property of a rule alone — it is a property of the rule at a severity.
## 2026-08-09 — Exercising a config's "local" mode proves nothing about the mode that ships
The root `.pre-commit-hooks.yaml` shipped Vale hooks whose `entry:` carried a `--config <repo-relative-path>` argument. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: each external consumer hard-failed with `E100 [--config] Runtime error ... does not exist`, and two of the three hooks ADR-0014 promised were unusable. The defect survived three review rounds of PR #85 and a green `pre-commit run --all-files` every time, because this repo consumes the same hooks through `repo: local`, where the clone prefix, the cwd, and the repo root are one directory — the byte-identical `entry:` string worked locally for a reason that exists only locally. Nothing under `tests/` exercised the manifest as a hook repo at all. The sharp part: the local run was not weaker evidence of the same thing, it was evidence of a different thing, and the two were indistinguishable by reading either file. Fix: when a config has a local mode whose resolution semantics differ from the shipped mode, test the shipped mode against a real consumer — `tests/test-vale-hooks-consumer.sh` stands up a `file://` clone of this repo and runs the hooks from it — and then delete the divergence rather than living with it: `vale-wrap.sh` now self-locates its config from `${BASH_SOURCE[0]}`, and the local and shipped `entry:` lines are identical, so the local run no longer exercises a path no consumer takes.
## 2026-08-09 — Deleting a token from a shared artifact breaks whatever parses it, silently
Dropping the `--config` argument from `.pre-commit-hooks.yaml` was the right fix, but `scripts/check-release-needed.sh` derived its release-relevant path list by scanning those same `entry:` lines for `--config` and taking the target's `dirname` — that parse was the only thing giving the bundled `.vale.ini` and its sibling `styles/` tree release coverage. With the token gone the loop simply never fired: no error, no failing test, no warning, just a path list that shrank from six entries to four and lost both `assets/vale/` trees. Consequence: a change to a Vale *rule* could land on `main` without demanding a release tag, leaving external consumers pinned to an old `rev:` with stale rules — the exact drift the gate exists to prevent. It surfaced only because the agent making the change reported it as a suspected side effect of its own edit, and was confirmed by diffing the derived path list before and after. Fix: before removing a token from an artifact more than one script reads, grep for everything that *parses* the artifact, not just everything that consumes its documented purpose. The smell to watch for is a loop that builds a list, where an empty or short list is indistinguishable from a correct one — assert on the expected members, so a derivation whose input vanished fails loudly instead of quietly covering less.
## 2026-08-09 — A documented impossibility is a claim, not a constraint
`vale-wrap.sh` flattens multi-line YAML `description:` scalars so Vale's `text.frontmatter.description` scope keeps matching. Its last-resort branch rewrote ASCII `'` to U+2019, justified at the emission site and in review as "the single combination no YAML scalar can carry verbatim" — an accepted-by-design residual, documented and test-covered, which is exactly why nobody retested it. The claim was false: a `|-` literal block with one indented content line carries `'`, `"`, `\` and `: ` verbatim, keeps the scope alive, and the wrapper's own header docstring already said literal blocks were unaffected. The cost of the unexamined claim was a silent underlint on 12 of 54 in-scope files — any rule whose token contained an apostrophe simply never fired, and the covering test (case 20) pinned only "the scope stays alive", so it passed either way. Fix: when a residual is accepted because something is "impossible", write down the specific claim in a falsifiable form and test *that*, not the workaround built on top of it. The tell here was that the residual and its justification were documented in the same breath by the same author — documentation records a belief, and a belief adjacent to a workaround is the one most worth attacking. Related: an assertion written to cover an accepted residual tends to assert the residual's *presence* rather than the behaviour it costs; case 20b asserted the scope survived flattening, never that a rule matching the rewritten characters still fired.

1
core/AGENTS.md
View File

@@ -23,3 +23,4 @@ Read these files on demand:
- **Coding conventions** (`~/.claude/core/instructions/coding.md`) — when writing, editing, or reviewing code
- **Testing conventions** (`~/.claude/core/instructions/testing.md`) — when writing or running tests
- **Subagent orchestration** (`~/.claude/core/instructions/subagent-orchestration.md`) — when spawning or coordinating subagents/forks

6
core/instructions/subagent-orchestration.md Normal file
View File

@@ -0,0 +1,6 @@
# Subagent orchestration
- A fork stops when its assigned task is done. It inherits the coordinator's full context, including any shared TaskList — that visibility is not license to keep pulling further items after its assigned task is reported complete; doing so races the coordinator's own orchestration and can duplicate or conflict with separately-delegated work.
- Don't hand a fork a TaskList containing governance-gated actions (push, publish, merge) unless prepared for it to act on those without a fresh confirmation round. A fork acting on its own initiative is not party to any pending human confirmation the coordinator is mid-flow on.
- `TaskGet`/`TaskUpdate`/`TaskList` only work for forks. Fresh (non-fork) subagents cannot discover or call these tools — when delegating to a fresh subagent, the coordinator owns all task-list bookkeeping itself.
- `Agent(isolation: "worktree")` may fork from `main`, not the branch the coordinator was on. Verify and self-correct (`git merge --ff-only <target-branch>` or reset onto `origin/<target-branch>`) before editing. When removing such a worktree afterward, use `git worktree remove --force --force <path>` if the repo has submodules (double `-f` required), then `git branch -d` both the feature branch and the auto-created `worktree-agent-<id>` isolation branch.

1
core/instructions/testing.md
View File

@@ -4,3 +4,4 @@
- Automate everything automatable. Manual testing only for nuanced UI/UX or agent interaction behaviour requiring human judgment.
- Test observable end-state, not implementation internals. Tests must survive refactoring.
- No test is better than a wrong test. A passing mock that masks a real failure is actively harmful.
- A clean result can mean nothing ran. Before trusting a new check, prove it fails against a deliberately-bad fixture, then run it against the real target. Where a check can scan zero inputs, assert on the input count, not just the exit code — a zero-file run and a real clean pass look identical otherwise.

109
docs/adr/0011-gitea-skill-deep-modules.md Normal file
View File

@@ -0,0 +1,109 @@
# Gitea skill splits into deep modules under `plugins/gitea/`, replacing the flat `plugins/bin/skills/gitea/`
The gitea skill originated under kyberforge (`b9c73cc`), moved to `plugins/bin/skills/gitea/`
(`4f603cd`), and covers only 5 of gitea-mcp's ~15 tool domains (issues, labels, milestones, PRs,
branches) in one flat `SKILL.md` mixing routing logic with execution detail. Meanwhile
`plugins/gitea/` already existed as a plugin scaffold holding comprehensive research docs (all 55
MCP tool schemas, code-derived from gitea-mcp source, at
`plugins/gitea/docs/research/docs/gitea/`) but empty `skills/`, `agents/`, and `.mcp.json`. This
ADR records the decisions from a grill-with-docs session on issue #6 that splits the flat skill
into deep modules and relocates it to `plugins/gitea/`.
**Relocation.** The new deep-module skill structure is built in `plugins/gitea/`, not
`plugins/bin/`, making the gitea plugin self-contained — bundling its own skills, agents, and MCP
config — matching this repo's Plugin glossary definition (the deployable unit that bundles skills,
agents, hooks, and MCP servers into a single installable directory) and mirroring the existing
`plugins/git/` plugin's shape. The old flat skill stays at `plugins/bin/skills/gitea/` untouched
for now, kept as a reference/fallback — not deleted in this pass; removal is a future cleanup once
the new structure is validated in practice.
**Scope expansion.** Coverage expands beyond the original 5 domains to 3 new domains verified
working with the current token scope (`write:issue`, `write:repository`) per
`plugins/bin/skills/gitea/references/token-access.md`: Files (get/create/update/delete file, dir
contents, repo tree), Commits (list/get), and Releases & Tags (full CRUD). Domains not added:
repo/org listing, user identity, notifications, and packages are blocked by token scope
(`read:user`, `read:organization`, `read:notification`, `read:package`); Actions/CI (list_runs and
secrets return 403, writes untested) and Wiki (404 on this repo, writes untested) are partially
broken or unverified. All are deferred to future issues once scope is expanded or the domain is
verified safe elsewhere.
**Domain skill split.** The flat skill becomes 6 domain skills plus a workflow orchestrator and an
agent counterpart, composed per the Skill composition pattern:
- `gitea-issues` — issues only (list/read/write/search); closes out 4 enrichments deferred from
issue #6 comment #848 — milestone assignment on create, assignee on create (documented
workaround since `get_me`/`read:user` is blocked), dependency-linking convention ("Depends on
#N" in body, since gitea-mcp has no native dependency field) — and delegates label inference to
`gitea-labels-milestones`.
- `gitea-labels-milestones` — split out as its own shared skill since labels/milestones are
cross-cutting (apply to both issues and PRs), rather than bundled under `gitea-issues`; owns the
label inference guide (context-pattern → Kind/*/Priority/*/Status/* taxonomy mapping).
- `gitea-prs` — pull requests + reviews, composes `gitea-labels-milestones` for label/milestone
application.
- `gitea-branches` — branches + commits bundled together (commits are read-only history within
branches, a natural pairing).
- `gitea-files` — new domain.
- `gitea-releases` — releases + tags bundled together.
- `gitea-workflow` — thin human-facing orchestrator mirroring `git-workflow`
(`plugins/git/skills/git-workflow/`). Preserves the original flat skill's default no-args status
view (composes `gitea-issues` + `gitea-prs`) and routes ambiguous requests to the right domain
skill. Named `gitea-workflow`, not bare `gitea`, for naming consistency with the other 6 skills,
despite breaking the old `/gitea` invocation muscle memory — an explicit accepted tradeoff.
- `gitea-orchestrate` (agent, not skill) — agent-facing deterministic counterpart mirroring
`git-orchestrate`, for multi-step composition when the caller is an agent rather than a human.
**Reference-file signature sourcing.** Each new skill's `references/*.md` restates verified MCP
call signatures cross-checked live via `ToolSearch` at authoring time, not copied from
`api-reference.md`, which could drift from the deployed MCP server version. This resolves issue #6
comment #849's root-cause question about the original `type` parameter bug, which happened
because the skill was authored from Gitea REST API docs instead of the actual MCP tool schema.
This is applied manually during this authoring pass; the `kyberforge:skill-author` meta-skill
itself is not changed — comment #849's "option 2" process fix is considered and explicitly
deferred as out of scope for this PR.
**MCP config deferred.** `plugins/gitea/.mcp.json` is deliberately left as an empty `mcpServers`
block — the real gitea-mcp server config continues to live in the user's `~/.claude.json` rather
than being wired into the plugin manifest. This means the gitea plugin is not yet installable
standalone via `claude plugin install gitea@holocron` without manual MCP setup. A follow-up Gitea
issue tracks closing this gap.
**Research backfill.** The existing research docs
(`plugins/gitea/docs/research/docs/gitea/`) are 100% code-derived from gitea-mcp source with zero
external/best-practice content (the original docs.gitea.com fetch timed out and was never
retried). Context7 has `/websites/gitea` (official docs mirror) and `/git_gitea_com/gitea_tea` (Tea
CLI) available now — backfilled via a parallel research pass before skill-authoring, so the
Provenance chain (`source_keys` → `sources.md` → research doc) has real external sources for
workflow/convention guidance, not just API mechanics.
**Authoring route.** All 8 artifacts (7 skills + 1 agent) are authored via `kyberforge:forge`, not
direct `skill-author`/`agent-author` calls, even though `forge`'s own routing rule would normally
bypass itself here since the target artifact types are already known — chosen deliberately for
uniform audit/recheck coverage across every artifact.
## Considered options
**5-skill split, labels+milestones bundled under `gitea-issues` (rejected)** — simpler, one fewer
skill, but re-buries label/milestone logic inside an issues-specific skill even though PRs need it
equally, forcing `gitea-prs` to either duplicate the guide or reach into `gitea-issues`'
`references/` — breaking the self-contained skill boundary.
**8-skill split, one skill per raw API domain, no bundling (rejected)** — e.g. separate
`gitea-commits` and `gitea-tags` skills. Rejected as over-fragmentation: commits are read-only
history naturally scoped to branches, and tags are naturally scoped to releases, so bundling
avoids two near-empty skills each routing to a single tool family.
## Consequences
- `plugins/gitea/` gains `skills/gitea-issues/`, `skills/gitea-labels-milestones/`,
`skills/gitea-prs/`, `skills/gitea-branches/`, `skills/gitea-files/`, `skills/gitea-releases/`,
`skills/gitea-workflow/`, and `agents/gitea-orchestrate.md` (+ Copilot counterpart), each with
its own `references/` and provenance records.
- `plugins/gitea/.mcp.json` stays an empty `mcpServers` block until the follow-up issue wires in
the real gitea-mcp server config; the plugin is not standalone-installable until then.
- `plugins/bin/skills/gitea/` remains in place, unreferenced by new work, until a future cleanup
issue removes it once the new structure is validated in practice.
- Follow-up issues are needed for: the deferred domains (Actions/CI, Wiki, Notifications,
Packages, User/Org), the `.mcp.json` wiring gap, and the eventual removal of
`plugins/bin/skills/gitea/`.
- Future domain-plugin work in this repo can point to this ADR as the template for splitting an
MCP-wrapping skill into deep modules.

16
docs/adr/0012-agentsmd-tooling-in-core-plugin.md Normal file
View File

@@ -0,0 +1,16 @@
# AGENTS.md tooling lives in `core`, split into three skills
`kyberforge` is scoped to meta-tooling for building and maintaining the holocron marketplace itself (skills, agents, plugins, marketplace entries) — not to generic capabilities for an arbitrary target repo. Authoring and reviewing a target repo's `AGENTS.md` file is repo-agnostic documentation tooling, closer in kind to `bin:write-docs` or `bin:init` than to `skill-author`/`plugin-author`. Research for this topic was initially placed under `plugins/kyberforge/docs/research/docs/agentsmd/` but has moved to `plugins/core/docs/research/docs/agentsmd/` to keep the provenance chain consistent with the plugin the resulting skills live in.
## Decision
Three skills in the `core` plugin (`core`'s first active skills):
- **`agentsmd-author`** — creates/updates a target repo's `AGENTS.md`, including nested monorepo placement (nearest-file-wins). Closes out by invoking `agentsmd-audit` inline, mirroring the `skill-author`/`skill-audit` pattern. When it detects an existing provider-specific file (`CLAUDE.md`, etc.) with content that duplicates what AGENTS.md should own, it calls `provider-adapter-author` via skill composition.
- **`agentsmd-audit`** — a single combined pass checking three mandatory baselines against `AGENTS.md` only: secrets/credentials (governance.md hard prohibition), structural completeness (common-sections checklist from the agents.md spec), and accuracy/drift (do referenced commands/paths resolve against the repo). Never inspects provider adapter files.
- **`provider-adapter-author`** — detects and converts a provider-specific instruction file into a thin adapter that imports `AGENTS.md` (mirroring this repo's own two-tier `CLAUDE.md` pattern). Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`) rather than a separate paired audit skill, since the check (import present, no duplicated headings, size threshold) is mechanical.
## Consequences
- `core`'s plugin.json/README will list real skills for the first time.
- `plugins/kyberforge/docs/research/docs/agentsmd/` moves to `plugins/core/docs/research/docs/agentsmd/` before authoring begins.

121
docs/adr/0013-vale-harness-scope-and-rule-sources.md Normal file
View File

@@ -0,0 +1,121 @@
# Vale audit prefilter expands into a plugin-content harness, scoped to prose-pattern rules only
Issue #84 wired Vale as a deterministic prefilter for `skill-audit`/`agent-audit`, scoped to
exactly four pattern-matchable checks (imperative description opener, vague capability wording,
generic reference-pointer padding, Copilot's dead `Use proactively` phrasing), documented only in
CONTEXT.md's "Vale audit prefilter" section — never its own ADR — and explicitly excluding body
discipline, near-miss exclusion strength, and control calibration as non-goals. This ADR records a
deferred PR #85 review item to broaden that coverage, retroactively captures #84's own rationale
(since it was never recorded as a decision in its own right), and layers the expansion on top
without reversing or weakening the original four rules.
**File scope stays the same.** `SKILL.md` plus agent files (`**/agents/*.md`,
`**/*.agent.md`) only — matching the existing prefilter's globs. Skill-level
`README.md` files and `plugin.json` manifests are not added: README.md files are navigational, not
spec-governed content, and `plugin.json` is JSON, not prose Vale can meaningfully lint.
**Rule categories are prose-pattern-matchable only.** Structural, schema, and security concerns
stay out of this Vale-based harness because this repo already has dedicated tools for them:
`skill-frontmatter` (required frontmatter fields), `validate-plugins`/`validate-marketplace`
(`claude plugin validate --strict`, schema), and `gitleaks`/`detect-private-key` (secrets).
Duplicating those concerns as Vale rules would fight tools that already own them better.
**Governance docs are excluded as a rule source.** `docs/research/governance_principles/CONTROLS.md`
and `governance.md` were investigated and found to contribute nothing minable: CONTROLS.md is
org/CI-infrastructure controls (secret scanning, dependency/license scanning, agent permission
scoping, audit logging, human approval gates, periodic reviews) — none of it is a prose pattern
expressible as a Vale rule against SKILL.md/agent-file text, and what it does cover is either
already handled elsewhere (gitleaks) or genuinely out of scope for a plugin-content prose harness
(dependency/license scanning is a code-dependency concern, not skill authoring).
**Spec-derived custom rules stay mostly as-is.** Re-reading agentskills.io's
`optimizing-descriptions.md` and `skill-authoring.md`, plus `claude-code-plugins/agent-definition.md`
and `github-copilot-plugins/agent-definition.md`, found that the existing four Kyberforge rules
already cover the pattern-matchable surface those specs describe. The remaining spec guidance —
calibrating control vs. giving freedom, avoiding menus of options, coherent skill scope, moderate
detail level — is semantic judgment, already `skill-audit`'s job via LLM review, not new lintable
rules. One confirmation surfaced: Claude Code's `Use proactively` phrasing is meaningful for `.md`
agent files (it triggers auto-invocation), unlike Copilot's `.agent.md` files where it's dead
phrasing — so `KyberforgeCopilot/ProactivePhrase`'s existing `.agent.md`-only scope is correct and
must not be extended to `.md` files.
**`write-good`/`alex` are trialed, not adopted wholesale.** These built-in/third-party Vale
packages are tuned for general blog-style prose (passive voice, weasel words, wordy phrases) and
are expected to be noisy against this repo's terse, imperative instruction-file corpus. Only
individual rules proven low-noise against the existing corpus get cherry-picked into
`styles/Kyberforge`; the packages are never referenced wholesale in `BasedOnStyles`.
**A new non-Vale check closes a real gap.** `skill-authoring.md` states `SKILL.md` should stay
under 500 lines / 5,000 tokens — currently unenforced anywhere in this repo. This is a whole-file
length ceiling, not a text pattern, so it isn't a Vale rule — it becomes a new deterministic script
and pre-commit hook, sibling to the existing `skill-frontmatter` hook.
**Rules land directly in `styles/Kyberforge`, enforcing immediately.** No trial/report-only tier
is introduced (see Considered Options). "Enforcing immediately" holds only because every rule in
both styles is `level: error`: Vale's exit code keys on `error`-level alerts alone, so a
`warning`- or `suggestion`-level rule prints an alert and still exits 0, and pre-commit suppresses
output from hooks that pass — such a rule is invisible and blocks nothing. Every Vale alert is
therefore a FAIL, in the audit skills and in the blocking pre-commit hook alike, with no ignorable
tier; that matches every other gate in this repo (shellcheck, the test suite,
conventional-pre-commit). The implementation pass finalizes the cherry-picked
`write-good`/`alex` rules and any new spec-derived rule wording, runs the full set against the
existing SKILL.md/agent-file corpus, fixes any resulting violations across that corpus, and lands
the rule changes and the corpus fixes as one atomic commit — the same enforcement model as the
original four rules, never a partial or opt-in state.
## Considered options
**Phased rollout via a separate trial style + config (rejected).** A `styles/KyberforgeTrial/`
directory plus a parallel `.vale.trial.ini` (mirroring the root config's globs but with
`BasedOnStyles = Kyberforge, KyberforgeTrial`) would let new rules be swept report-only via
`lint-runner`/`vale-run` before promotion into the enforcing `styles/Kyberforge` + root
`.vale.ini`. This was considered because `BasedOnStyles = Kyberforge` activates every rule file
under that directory automatically — there's no partial/opt-in application within a style, so a
rule dropped straight into `styles/Kyberforge` goes live in the blocking pre-commit hook
immediately. Rejected in favor of finalizing rules directly and fixing violations via subagent
before committing: simpler, no new trial-config machinery to build or maintain — at the cost of no
standing report-only tier for future candidate rules. Note that the first implementation shipped
graded severities (`error`/`warning`/`suggestion`) and thereby recreated the rejected option by
accident: the five non-`error` rules never affected an exit code and never surfaced output through
a passing pre-commit hook, so they were a report-only tier that reported to nobody. Flattening
every rule to `level: error` is what actually implements this decision.
## Consequences
- `styles/Kyberforge/` gained one new rule file, cherry-picked from `write-good`/`alex` as
low-noise against this repo's corpus: `SentenceOpenerThereIs.yml` (22 hits across 273 held-out
markdown files; both in-corpus hits were clean rewrites, needing no suppression).
- A second candidate, `VagueQualifier.yml`, was cherry-picked and then dropped. Against the 41
skill/agent files it hit twice: one marginal real finding (`prototype/SKILL.md`, "very different"
→ "fundamentally different") and one false positive (`caveman/SKILL.md`, which *quotes* `of
course` as an example of filler — a mention, not a use) that no rewrite could clear, forcing the
repo's only Vale suppression comments. Of its 15 held-out hits, 9 were in `docs/research/examples/`
(out-of-scope upstream material) and the remaining 6 were the word "very" in two idioms in a
single research doc, each already adjacent to the hard number carrying the fact. One marginal
catch does not pay for a permanent suppression, so the rule is deleted and this ADR's
"cherry-picked rules" is one rule, not two.
- A new pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforces the
500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`. Both halves of that
ceiling are blocking gates, not just the line count: `MAX_LINES=500`, and `MAX_WORDS=2770` as a
word-count proxy for the 5,000-token limit (calibrated to the densest prose this repo measured,
1.81 tokens per word, so a worst-case `SKILL.md` at the ceiling still lands under 5,000 tokens —
`wc -w` is not BPE tokenization). Either one exceeded fails the hook. Both are
inclusive: a file at exactly 500 lines or exactly 2,770 words passes, and only one past a ceiling
fails. `skill-audit/scripts/validate.sh` enforces the same pair on the same inclusive terms, so
the audit and the commit hook cannot disagree about whether a given `SKILL.md` is over size.
- `styles/KyberforgeTrial/` and `.vale.trial.ini` were deliberately not created — noted here so a
future reader doesn't wonder if a trial tier was forgotten.
- The styles-portability question — whether `styles/` and `.vale.ini` should move into
`plugins/lint/` so the prefilter also works for repos that install `kyberforge@holocron` as an
external plugin, rather than living at this repo's root — was deliberately deferred, not fixed,
in this pass. This repo-root placement remains intentional: this ADR's "File scope stays the
same" framing is specific to Kyberforge's own authoring conventions in this repo, not a generic
`lint`-plugin feature. Portability is a known limitation, tracked for a separate future session,
not silently forgotten.
**What this ADR's implementation pass did:** synced and trialed `write-good`/`alex` against the
existing SKILL.md/agent-file corpus, cherry-picked the one low-noise rule above into
`styles/Kyberforge`, wrote `scripts/skill-size-check.sh` and its pre-commit hook, fixed the
resulting corpus violations, and landed the rule changes and corpus fixes as one atomic commit —
matching the enforcement model described above (no partial or opt-in state), with every rule at
`level: error` so that model is real rather than nominal.

188
docs/adr/0014-vale-prefilter-ships-from-the-plugin.md Normal file
View File

@@ -0,0 +1,188 @@
# Kyberforge's Vale prefilter ships from the plugin, with `.pre-commit-hooks.yaml` for external git-hook/CI enforcement
**Resolves:** ADR-0013's deferred "styles-portability" consequence — `.vale.ini`/`styles/` moving
out of the repo root was deliberately deferred there, not fixed. ADR-0013's other content
(rule scope, `level: error` model, `SentenceOpenerThereIs`/`VagueQualifier` trial outcomes) is
unaffected and remains in force.
`skill-audit`/`agent-audit`'s Step 1 called
`"$(git rev-parse --show-toplevel)/scripts/vale-wrap.sh" --config "$(git rev-parse --show-toplevel)/.vale.ini"`
— which resolves to whichever repo the skill happens to be running in. Inside `ai-development`
that's this repo; in any external repo that installs `kyberforge@holocron` as a plugin, it's that
repo's own root, which has no `.vale.ini` or `vale-wrap.sh`. The prefilter silently fell back to
full LLM judgment every time outside this repo — the exact gap ADR-0013 named and deferred.
## Decision
**Runtime (a live Claude Code session):** the Vale config, styles, and wrapper script move into
the plugin itself, following the no-cross-skill-path rule already established in
`skill-author/references/deployment-modes.md` (a plugin's cache-install only copies each skill's
own files; there is no plugin-level shared directory). `agent-audit` needs both `Kyberforge` and
`KyberforgeCopilot` (it lints `.agent.md` files), so `plugins/kyberforge/skills/agent-audit/assets/vale/`
is the canonical, superset copy. `skill-audit` needs a second, smaller copy
(`plugins/kyberforge/skills/skill-audit/assets/vale/`, `Kyberforge` only) since it cannot
reference agent-audit's copy across the skill boundary. Both skills' Step 1 now resolve
`scripts/vale-wrap.sh`/`assets/vale/.vale.ini` relative to their own directory, the same way
`scripts/validate.sh <skill-dir>` already does — no new resolution mechanism, just applying the
existing one consistently.
**git hooks / CI outside a Claude Code session** have no plugin cache and no
`${CLAUDE_PLUGIN_ROOT}` — a CI runner in particular is guaranteed not to have one. The mechanism
that works there for any consumer, with or without Claude Code installed, is pre-commit's own
hook-repo protocol: this repo now ships a root-level `.pre-commit-hooks.yaml` exposing
`kyberforge-vale-audit-skill`, `kyberforge-vale-audit-agent`, and `kyberforge-skill-size-check`.
Any external repo adds `repo: <this-repo-url>, rev: <tag>` to its own `.pre-commit-config.yaml`
and gets all three, fully decoupled from Claude Code. CI is the identical `pre-commit run
--all-files` call, so the same manifest covers "possibly CI" from the original ask.
**This repo's own dev-time gate** consumes the same plugin-bundled copies instead of a third
root-level copy — per explicit instruction, this repo should be set up like any other consumer
would be, not dogfood a special root-only path. The existing `repo: local` hook is retargeted
(not removed): `entry:` now points at `plugins/kyberforge/skills/{skill-audit,agent-audit}/scripts/vale-wrap.sh`.
`repo: local` is kept rather than switching to a pinned self-reference
(`repo: <own-url>, rev: <tag>`) — a pinned self-reference would lint working-tree edits against
the *last tagged release*, not the change actually being made, which is wrong for the repo that
*is* the source of the hook. This mirrors standard practice among hook-author repos (pre-commit's
own `pre-commit-hooks`, `shellcheck-py`): `repo: local` for self-consumption, `.pre-commit-hooks.yaml`
for everyone else, same underlying files and commands either way.
**One hook per file-scope, not one combined hook.** The old root `.vale.ini` had both the
`[**/SKILL.md]` and `[**/agents/*.md]`/`[**/*.agent.md]` glob sections in a single file, so one
pre-commit hook covered both. Splitting the config into two skill-scoped copies means a single
hook entry pointed at only one copy would silently 0-file-skip the other file type. Both the
local `.pre-commit-config.yaml` hooks and the external-facing `.pre-commit-hooks.yaml` therefore
define separate `-skill`/`-agent` hook IDs, each with a `files:` regex matching exactly what its
target copy's glob covers. (Confirmed empirically before deleting the root files: retargeting a
single hook at agent-audit's copy silently scanned 0 SKILL.md files.)
**The hook `entry:` is the wrapper alone; the wrapper self-locates its config.** pre-commit
prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`);
every later argument is handed to the process untouched and so resolves against the *consuming*
repo's root. A `--config plugins/kyberforge/skills/…/assets/vale/.vale.ini` in
`.pre-commit-hooks.yaml` therefore named a path no consumer has, and every external run died with
`E100 [--config] Runtime error`. The external-consumer contract this ADR exists to establish
cannot be expressed as a `--config` argument at all — the config path has to be derived inside
the process, from the script's own location. `vale-wrap.sh` accordingly defaults to its sibling
`assets/vale/.vale.ini`, resolved from `${BASH_SOURCE[0]}`, whenever no `--config` is supplied;
an explicit `--config` from any other caller still wins and still resolves against the caller's
cwd, so both audit skills' Step 1 (`--config assets/vale/.vale.ini`) is unaffected. Both
manifests now carry the identical argument-free `entry:`. Keeping them identical is part of the
decision: the local `repo: local` hook resolved its `--config` correctly only because the
consuming repo *was* this repo, and that one difference is why three review rounds exercised a
code path no external consumer ever takes.
**Vale's `StylesPath` resolves relative to the `.vale.ini` file's own location**, confirmed
against `docs.vale.sh/keys/stylespath` — so a config path into the plugin finds that ini's
sibling `styles/` regardless of the caller's cwd, whether it arrives as an explicit `--config` or
as the wrapper's self-located default. No extra path-juggling is needed beyond `vale-wrap.sh`'s
cwd-relative `--config`/path-argument handling and that fallback.
**A sync-check catches drift between the two copies.** `scripts/check-vale-style-sync.sh` diffs
`scripts/vale-wrap.sh` and `assets/vale/styles/Kyberforge/` between skill-audit and agent-audit
(not `.vale.ini` — those legitimately differ, scoped to different glob sections), wired at
`pre-push` alongside `check-manifests`. `.vale.ini` itself isn't diffed since divergence there is
by design.
**External `.pre-commit-hooks.yaml` consumers pin `rev:` to a tag, not a commit SHA.** This repo
had no tags before this change; going forward, a `vX.Y.Z` tag is cut whenever hook-relevant files
change, matching how every other `repo:` entry in this repo's own `.pre-commit-config.yaml`
already pins (`v2.4.0`, `v8.21.2`, ...).
## Considered options
**Keep a third root-level copy, dogfooded specially (rejected).** Simpler in that this repo's own
hook wouldn't need retargeting at all. Rejected on explicit instruction: this repo should consume
the same portability path an external repo would, not carve out a special root-only case that
never gets exercised the way external consumers exercise it.
**Publish styles as a hosted Vale package via `Packages = <zip-url>` (deferred, not rejected).**
Vale supports fetching a style from a direct `.zip` URL via `vale sync`, fully decoupled from
Claude Code and from pre-commit's hook-repo protocol — usable by any repo, even ones that never
install `kyberforge` at all. This is a larger, separate investment (a release/versioning pipeline
for the package itself) not required to satisfy the current ask; noted here so a future reader
doesn't wonder if it was overlooked.
## Consequences
- Root `.vale.ini`, `styles/`, `scripts/vale-wrap.sh` are deleted. Two copies remain:
`plugins/kyberforge/skills/agent-audit/assets/vale/` (canonical, superset) and
`plugins/kyberforge/skills/skill-audit/assets/vale/` (subset, `Kyberforge` only).
- `plugins/kyberforge`'s `plugin.json` and `.claude-plugin/plugin.json` both patch-bump for every
shipped content change (per ADR-0006's version-parity invariant): `1.2.5` for the relocation
itself, `1.2.6` for the self-locating `vale-wrap.sh` that followed.
- **`.pre-commit-hooks.yaml` entries are a bare script path and nothing else — a constraint, not a
house style, and it binds every future hook here, not just the Vale two.** Since pre-commit
rewrites only `entry[0]` into the hook-repo clone, no argument token in any entry can reference
a file this repo ships: a relative path resolves against the *consuming* repo and hard-fails,
and the absolute path is unknowable at author time. A hook that needs one of its own bundled
files must have the script self-locate it from `$0`/`${BASH_SOURCE[0]}`, exactly as
`vale-wrap.sh` now does for `.vale.ini`. Anything else rediscovers this as another `E100`.
`.pre-commit-config.yaml` stays byte-identical to the shipped manifest on those `entry:` lines
so the local gate keeps exercising the same resolution path a consumer does.
- `tests/test-vale-wrap.sh` now exercises skill-audit's copy specifically — its fixtures are all
`SKILL.md`-shaped, and only skill-audit's `.vale.ini` has the matching glob section.
- The first `vX.Y.Z` tag is cut once this change and its tests pass, giving external
`.pre-commit-hooks.yaml` consumers something to pin.
- **Cutting the tag is not left to memory.** `scripts/check-release-needed.sh`, wired at
`pre-push`, hard-fails — but only when `PRE_COMMIT_REMOTE_BRANCH` (set by pre-commit's
`hook-impl` for pre-push hooks) is `refs/heads/main` — if any path `.pre-commit-hooks.yaml`
exposes changed since the last tag reachable from `HEAD`. It is a silent no-op on every other
branch: hard-failing on feature-branch pushes mid-review would force a premature tag on a
commit that might not survive a squash-merge, the exact problem `repo: local` (above) already
avoids for this repo's own dev-time gate. A tag not existing at all is also a hard fail on
`main`, covering the very first release. This is deterministic tooling, not a standing
instruction to remember — consistent with `check-manifests.sh`/`check-vale-style-sync.sh`
already using the same pre-push, main-agnostic-elsewhere pattern.
- **Known limitation, not yet closed:** `check-release-needed.sh` only fires when a human runs
`git push` locally with pre-commit's hooks installed — `PRE_COMMIT_REMOTE_BRANCH` is set by
pre-commit's client-side `hook-impl` script parsing `git push`'s stdin protocol. A PR merged
through Gitea's merge button (server-side, no local push) or a CI runner invoking
`pre-commit run --hook-stage pre-push` directly never sets it, so the gate silently doesn't run
in either path. This repo has no CI workflow yet (`has_actions` is enabled but unused), so
closing this gap needs a server-side job re-running the same script on merge to `main` — deferred
as a separate piece of infrastructure, not fixed here. `RELEASE_PATHS` is derived from
`.pre-commit-hooks.yaml`'s own `entry:` lines rather than hand-maintained, so at least the set of
paths it checks can't drift from the manifest on its own.
- **Dropping `--config` moved the release gate's path derivation too.** `check-release-needed.sh`
used to reach each hook's bundled assets through the `dirname` of its `--config` target. With
no `--config` token left, that loop went dead and silently dropped both `assets/vale/` trees
from release coverage — a Vale *rule* change could then land on `main` without demanding a tag,
leaving consumers pinned to an old `rev:` running stale rules while the gate stayed green. The
script now derives the bundle's `assets/` tree from `tokens[0]` instead (double-`dirname`,
guarded on the candidate existing and on not resolving to `.`), which is the only derivation
compatible with the argument-free `entry:` contract above.
- **Accepted residual in the release gate (closed — see the update below):** deleting a hook's
*entire* `assets/` tree is not flagged — the derived candidate path stops existing, so the guard
drops it before it reaches the pathspec. Deleting individual files inside a surviving tree is
flagged, and tested.
**Update (commit `14c2c91`):** the accepted residual above no longer holds and is recorded here
only as the state at the time this ADR was written. `check-release-needed.sh` no longer derives
release-relevant paths from the worktree alone. It runs `collect_release_paths` twice — once over
the worktree's `.pre-commit-hooks.yaml`, once over the manifest read back from `$LAST_TAG` via
`git cat-file -p "$LAST_TAG:$HOOKS_MANIFEST"` — and unions the two path sets, so a path the tag
exposed stays in the pathspec even after the worktree's `-d` guard drops it. Wholesale deletion of
a hook's bundled `assets/` tree is therefore flagged, and `tests/test-check-release-needed.sh`
(case 12) asserts exit 1 for exactly that case. The union does not over-fire: any manifest edit
that makes the two disagree already touches `$HOOKS_MANIFEST`, itself a release-relevant path. An
unreadable tagged tree (shallow clone, truncated fetch) fails closed rather than silently degrading
to worktree-only derivation; a manifest simply absent at the tag — legitimate, it was added since —
does not.
**Update — the flattener rewrites no characters.** This ADR never recorded it as a decision, but
`vale-wrap.sh`'s flattener carried a lossy last-resort branch: when a description needed quoting
*and* held an ASCII apostrophe *and* held a double quote or backslash, it substituted U+2019 (`’`)
for every `'` before writing the scratch copy, on the stated rationale that no verbatim YAML scalar
could carry that combination. The rationale was wrong. A `|-` literal block with a single indented
content line carries `'`, `"`, `\` and `: ` byte for byte — a block scalar's body has no escape
syntax at all — and vale's `text.frontmatter.description` scope still matches and fires rules on it
(verified against vale 3.15.2; it is the same property that makes the `|` blocks in the wrapper's
header safe to leave unflattened). The branch fired on 12 of the 54 in-scope files in this repo,
silently disabling every rule whose token contains an apostrophe on each of them. The flattener now
emits that literal block instead, so its output is verbatim in all four forms and no Vale rule can
be silently disabled by the prefilter. The `|-` form is two physical lines where the three inline
forms are one, so the blank-line pad that preserves later line numbers drops by one — reachable
only when the original span is already two or more lines, so the pad count stays non-negative.
`tests/test-vale-wrap.sh` case 20 asserts an apostrophe-bearing token actually fires on a flattened
description in all three apostrophe-carrying branches, and case 20b pins the pad arithmetic against
a body line's true line number.

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

@@ -8,5 +8,5 @@
"keywords": [],
"license": "MIT",
"name": "bin",
"version": "1.0.5"
"version": "1.1.1"
}

3
plugins/bin/plugin.json
View File

@@ -1,5 +1,4 @@
{
"agents": "agents/",
"author": {
"email": "defame1297@rkdr.net",
"name": "Defame1297"
@@ -12,5 +11,5 @@
"skills": [
"skills/"
],
"version": "1.0.5"
"version": "1.1.1"
}

38
plugins/bin/skills/gitea/README.md
View File

@@ -1,38 +0,0 @@
# gitea
Dispatch skill for managing a Gitea repo — issues, PRs, milestones, labels, and branches — from within Claude Code.
## Files
| File | Purpose |
|---|---|
| `SKILL.md` | Skill definition — dispatch table, gotchas, execution steps |
| `references/token-access.md` | Token scope inventory — what works vs. what needs additional scopes |
## Usage
```
/gitea # status: open issues + open PRs
/gitea issue # create issue from conversation context
/gitea issue <N> # get issue details
/gitea issue close <N> # close issue
/gitea issue comment <N> # add comment from conversation context
/gitea label <N> Kind/Bug # apply labels by name (resolves IDs automatically)
/gitea milestone # list milestones
/gitea milestone create <title> # create milestone
/gitea pr # create PR from current branch → main
/gitea pr <N> # get PR status and diff summary
/gitea pr merge <N> # squash-merge PR, delete branch
/gitea branch # list branches
/gitea branch create <name> # create branch from current branch
```
## Requirements
- Gitea MCP server configured in `~/.claude.json` with `write:issue` and `write:repository` token scopes
- `git remote origin` pointing to the Gitea instance (used to derive owner/repo at runtime)
## Scope (v1)
In scope: issues, milestones, labels, PRs, branches, status.
Out of scope: releases, CI/Actions, wiki, file operations, notifications, packages, time tracking.

152
plugins/bin/skills/gitea/SKILL.md
View File

@@ -1,152 +0,0 @@
---
name: gitea
description: >
Use when the user wants to interact with Gitea — create or update issues,
open or merge pull requests, manage labels and milestones, list branches,
or check repo status. Always use this skill to interact with the GiteaMCP, never use GiteaMCP directly.
Triggers on: "create an issue", "open a PR", "what's
open", "label this issue", "create a milestone", "merge the PR", "list
branches", "close this issue" — even when the user doesn't say "Gitea"
explicitly. Owner and repo are derived automatically from the git remote;
no config required. Do not use for releases, CI/Actions, wiki, file
operations, notifications, or package management — those are out of scope.
compatibility: Requires Gitea MCP server configured in ~/.claude.json with write:issue and write:repository token scopes. Requires git remote "origin" pointing to the Gitea instance.
allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__issue_write mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp__gitea__pull_request_write mcp__gitea__list_branches mcp__gitea__create_branch
metadata:
category: integration
---
## Gotchas
- **Label writes take IDs, reads return names.** `issue_write` (add_labels, replace_labels) requires `labels: [3, 7]` (numeric IDs). Issue and PR responses return `labels: ["bug", "enhancement"]` (name strings). These are never interchangeable. Always call `label_read method: "list_repo_labels"` first and resolve names → IDs before any label write.
- **Issues and PRs share a number space.** `#5` might be an issue or a PR — there is only one counter per repo. `list_issues` returns issues only — it has no `type` parameter. Use `list_pull_requests` separately for PRs. Check `is_pull` on a single-item `issue_read` response to determine whether a number refers to an issue or PR.
- **Milestone write takes ID, not title.** `issue_write` takes `milestone: <numeric id>`. The title is not accepted. In `issue_read` responses the milestone is `{id, title}`, but in `pull_request_read` responses it's a bare title string — you cannot recover the ID from a PR response. Call `milestone_read method: "list"` and match by title if you need the ID from a PR context.
- **`get_me` is unavailable** with the current token (`write:issue, write:repository` only — `read:user` is missing). Owner and repo must always be derived from the git remote, never from `get_me` or `list_my_repos`.
- **Merging a PR does not itself close linked issues — but a commit message landing on the default branch can.** Gitea has no GitHub-style "merge triggers close" event. It does, however, parse closing keywords (`Fixes #N`, `Closes #N`) in commit messages pushed to the default branch. A regular (non-squash) merge preserves each original commit message, so if any of those commits says `Fixes #N`, the issue auto-closes at merge time — confirmed empirically (PR #64 auto-closed #63 this way, before any explicit `issue_write` call was made). This skill's own `pr merge` dispatch defaults to `merge_style: "squash"` (Step 3), which rewrites history into one commit — whether the keyword survives depends on what message that squash commit ends up with, so squash-merged PRs are the case most likely to still need an explicit close. Always call `issue_read method: "get"` to check current state before manually closing after a merge — closing an already-closed issue is a harmless no-op, but don't assume a manual close is always needed.
- **Pagination is manual.** List tools return one page at a time — no auto-pagination. When building complete datasets (e.g. all labels for name→ID mapping), iterate `page: 1, 2, ...` until result count < `per_page`.
- **`pull_request_read method: "get"` returns `review_scomments`, not `review_comments`.** This is a source-level typo in gitea-mcp v1.3.0. Do not access `review_comments` — it will always be undefined. Use `review_scomments`.
- **Cross-repo fork PRs require `head` as `"fork-owner:branch-name"`.** A bare branch name causes Gitea to search the base repo and return 422. The `pr create` dispatch assumes same-repo PRs (bare branch name). For fork-based PRs, pass `head` explicitly in the `owner:branch` format.
- **`draft: true` on PR create prepends `WIP:` to the title.** There is no first-class draft field — Gitea implements draft PRs via title prefix. To un-draft, call `pull_request_write method: "update"` and pass the title without the `WIP:` prefix. This differs from GitHub's draft PR model.
- **HTTP 404 may mean 403.** Gitea hides permission errors as not-found to avoid leaking resource existence. If a tool call returns 404 unexpectedly, check `references/token-access.md` before assuming the resource does not exist.
## Step 1 — Resolve owner and repo
Before any tool call, extract `owner` and `repo` from the git remote:
```bash
git remote get-url origin
```
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
## Step 2 — Dispatch
Route on the first argument:
| Invocation | Action |
|---|---|
| `/gitea` (no args) | **Status** — list open issues + open PRs |
| `/gitea issue` | Create issue from conversation context |
| `/gitea issue <N>` | Get issue details |
| `/gitea issue close <N>` | Close issue |
| `/gitea issue comment <N>` | Add comment from conversation context |
| `/gitea label <N> <names...>` | Apply named labels to issue/PR |
| `/gitea milestone` | List milestones |
| `/gitea milestone create <title>` | Create milestone |
| `/gitea pr` | Create PR from current branch → main |
| `/gitea pr <N>` | Get PR status and diff summary |
| `/gitea pr merge <N>` | Merge PR (squash, delete branch) |
| `/gitea branch` | List branches |
| `/gitea branch create <name>` | Create branch from current branch |
## Step 3 — Execute
### Status (default)
Call `list_issues state: "open"` and `list_pull_requests state: "open"` in parallel. `list_issues` does not accept a `type` parameter — it returns issues only. `list_pull_requests` returns PRs. Report as two sections.
### issue (create)
Extract title and body from conversation context. Use the most recent task, bug description, grill output, or explicit statement. If no body text is available from context, fall back to empty string. Fire immediately — no confirmation step.
**Label inference (do this before the create call):**
1. Call `label_read method: "list_repo_labels"` to get all available labels with their IDs.
2. From conversation context, infer which labels apply:
- Issue type → `Kind/*`: bug reports → `Kind/Bug`; new capabilities → `Kind/Feature`; improvements → `Kind/Enhancement`; docs → `Kind/Documentation`; security → `Kind/Security`
- Urgency signals → `Priority/*`: "blocking", "critical", "urgent" → `Priority/Critical`; "soon", "high priority" → `Priority/High`; default → `Priority/Medium`
- Explicit blocking → `Status/Blocked`
3. Resolve inferred label names to IDs from the label list. **Labels require numeric IDs — never pass name strings to `issue_write`.** If no labels can be confidently inferred, omit the `labels` parameter entirely rather than guessing.
Set `ref` to the current branch name (`git branch --show-current`) if a branch is already checked out for this work.
Call `issue_write method: "create" title: <extracted> body: <extracted or ""> labels: [<inferred IDs or omit>] ref: <current-branch-if-applicable>`.
### issue <N>
Call `issue_read method: "get" issue_number: <N>`. If the response includes `is_pull: true`, the number refers to a PR — report it as such and offer `pr <N>` for a full PR summary.
### issue close <N>
Call `issue_write method: "update" issue_number: <N> state: "closed"`. There is no `method: "close"` — using a non-existent method will error.
### issue comment <N>
Extract the comment body from conversation context (same sourcing as issue create). Call `issue_write method: "add_comment" issue_number: <N> body: <extracted>`.
### label <N> <names...>
1. Call `label_read method: "list_repo_labels"` — paginate until complete if > 30 labels.
2. Match each provided name (case-insensitive) against the label list → collect IDs.
3. Call `issue_write method: "add_labels" issue_number: <N> labels: [<matched IDs>]`.
4. Report applied labels and warn on any names that did not match, listing available labels.
Do not fail the operation because of unmatched names — apply what matches.
### milestone
Call `milestone_read method: "list"`. Report each milestone as: id, title, state (open/closed), open issue count, closed issue count.
### pr (create)
1. `git branch --show-current` → head branch.
2. Title: extract from conversation context; fall back to the last commit message (`git log -1 --pretty=%s`).
3. Body: extract from conversation; fall back to empty.
4. Call `pull_request_write method: "create" head: <branch> base: "main" title: <derived in step 2> body: <derived in step 3>`.
Note: this dispatch assumes a same-repo PR (bare branch name for `head`). For cross-repo fork PRs, `head` must be `"fork-owner:branch-name"` — see Gotchas.
### pr <N>
Call `pull_request_read method: "get"` and `pull_request_read method: "get_status"` in parallel (both take `pull_number: <N>`). Report: title, state, draft/merged flag, head → base, labels, CI status from get_status. Note: `milestone` in PR responses is a bare title string, not an object — you cannot extract a milestone ID from it.
### pr merge <N>
First call `pull_request_read method: "get_status" pull_number: <N>`. If CI status is failing, report it and warn the user — but do not block the merge unless they say to stop.
Then call `pull_request_write method: "merge" pull_number: <N> merge_style: "squash" delete_branch: true`. To use a different merge style, the user must specify it explicitly.
Squashing rewrites history into one commit — whether a linked issue's closing keyword survives depends on what message that squash commit ends up with. After merging, call `issue_read method: "get"` on any issue referenced by the PR to check whether it auto-closed before deciding whether to close it explicitly (see the auto-close gotcha above).
### milestone create <title>
Call `milestone_write method: "create" title: <title>`. Report the created milestone ID — it will be needed for assigning issues.
### branch
Call `list_branches`. Report each branch as: name, protected (bool).
### branch create <name>
Get the current local branch: `git branch --show-current`. Call `create_branch branch: <name> old_branch: <current-branch>`. This forks the new branch from where you are, not from the repo's default branch. If the user specifies a different base explicitly, use that instead.
## Step 4 — Report
For reads: display results as a compact table or numbered list — include number, title, labels, and milestone for issues/PRs.
For writes: confirm what was created/updated with the Gitea issue/PR number and URL if returned.
For errors: surface the HTTP code and message. 404 from some endpoints may actually mean insufficient token scope (Gitea hides 403 as 404 to avoid leaking resource existence).
If label resolution fails partially, always report which names were applied and which were skipped.
If token scope issues are suspected, read `references/token-access.md` for the full scope inventory.

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

@@ -14,7 +14,7 @@ Identify which question is being answered — from the user's prompt, the surrou
- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
The two branches produce fundamentally different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
## Rules that apply to both

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

@@ -14,5 +14,5 @@
],
"license": "MIT",
"name": "core",
"version": "1.0.0"
"version": "1.1.0"
}

47
plugins/core/README.md Normal file
View File

@@ -0,0 +1,47 @@
# core
Cross-cutting utility skills for everyday AI-assisted coding — triage, diagnosis, architecture review, and session navigation.
## Install
**Claude Code:**
```bash
claude plugin marketplace add <owner>/<repo>
claude plugin install core@<marketplace-name>
```
**GitHub Copilot CLI:**
```bash
copilot plugin marketplace add <owner>/<repo>
copilot plugin install core
```
**Local (development):**
```bash
# Claude Code
claude --plugin-dir ./plugins/core
# GitHub Copilot CLI
copilot plugin install ./plugins/core
```
## Contents
| Component | Path | Description |
|---|---|---|
| Skills | `skills/` | Slash commands available after install |
## Skills
| Skill | Description |
|---|---|
| `agentsmd-author` | Create or update a repo's AGENTS.md by exploring real build/test/lint conventions; supports nested monorepo placement and hands off to agentsmd-audit and provider-adapter-author |
| `agentsmd-audit` | Audit a repo's AGENTS.md for embedded secrets, structural completeness, and drift; produces a findings report |
| `provider-adapter-author` | Convert a provider-specific instruction file (CLAUDE.md, `.cursor/rules/*.mdc`, copilot-instructions.md, etc.) into a thin adapter that defers to AGENTS.md |
## Author
Defame1297

0
plugins/kyberforge/docs/research/docs/agentsmd/configuration.md → plugins/core/docs/research/docs/agentsmd/configuration.md
View File

0
plugins/kyberforge/docs/research/docs/agentsmd/examples.md → plugins/core/docs/research/docs/agentsmd/examples.md
View File

0
plugins/kyberforge/docs/research/docs/agentsmd/overview.md → plugins/core/docs/research/docs/agentsmd/overview.md
View File

0
plugins/kyberforge/docs/research/docs/agentsmd/sources.md → plugins/core/docs/research/docs/agentsmd/sources.md
View File

3
plugins/core/plugin.json
View File

@@ -1,5 +1,4 @@
{
"agents": "agents/",
"author": {
"email": "defame1297@rkdr.net",
"name": "Defame1297"
@@ -19,5 +18,5 @@
"skills": [
"skills/"
],
"version": "1.0.0"
"version": "1.1.0"
}

30
plugins/core/skills/agentsmd-audit/README.md Normal file
View File

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

68
plugins/core/skills/agentsmd-audit/SKILL.md Normal file
View File

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

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

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

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

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

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

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

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

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

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

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

30
plugins/core/skills/agentsmd-audit/tests/README.md Normal file
View File

@@ -0,0 +1,30 @@
# tests/
Test files for scripts bundled with this skill.
## Dependencies
Tests require [bats-support](https://github.com/bats-core/bats-support) and
[bats-assert](https://github.com/bats-core/bats-assert). The test files load
helpers from the repo root's `tests/test_helper/`.
From the repo root:
```bash
git clone https://github.com/bats-core/bats-support tests/test_helper/bats-support
git clone https://github.com/bats-core/bats-assert tests/test_helper/bats-assert
```
Run all tests for this skill (from the repo root):
```bash
bats plugins/core/skills/agentsmd-audit/tests/
```
## Files
| File | Purpose |
|------|---------|
| `validate-secrets.bats` | Bats test suite for `scripts/validate-secrets.sh` |
| `validate-structure.bats` | Bats test suite for `scripts/validate-structure.sh` |
| `validate-drift.bats` | Bats test suite for `scripts/validate-drift.sh` |

105
plugins/core/skills/agentsmd-audit/tests/validate-drift.bats Normal file
View File

@@ -0,0 +1,105 @@
#!/usr/bin/env bats
setup() {
REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../" && pwd)"
load "$REPO_ROOT/tests/test_helper/bats-support/load"
load "$REPO_ROOT/tests/test_helper/bats-assert/load"
SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate-drift.sh"
TMPDIR="$(mktemp -d)"
}
teardown() {
rm -rf "$TMPDIR"
}
@test "fails when AGENTS.md references a stale npm script" {
cat > "$TMPDIR/package.json" <<'EOF'
{
"scripts": {
"test": "jest"
}
}
EOF
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Testing
- Run `pnpm run e2e` before committing.
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_failure
assert_output --partial "e2e"
}
@test "passes when the referenced npm script exists" {
cat > "$TMPDIR/package.json" <<'EOF'
{
"scripts": {
"test": "jest"
}
}
EOF
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Testing
- Run `npm run test` before committing.
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_success
}
@test "fails when AGENTS.md references a stale make target" {
cat > "$TMPDIR/Makefile" <<'EOF'
build:
echo building
EOF
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup
Run `make deploy` to ship.
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_failure
assert_output --partial "deploy"
}
@test "emits INFO instead of FAIL when there is no package.json to verify an npm script against" {
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Testing
Run `pnpm run e2e` before committing.
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_success
assert_output --partial "INFO"
assert_output --partial "e2e"
}
@test "fails when a referenced file path does not exist" {
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup
See `scripts/bootstrap.sh` for environment setup.
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_failure
assert_output --partial "scripts/bootstrap.sh"
}
@test "passes when the referenced file path exists" {
mkdir -p "$TMPDIR/scripts"
: > "$TMPDIR/scripts/bootstrap.sh"
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup
See `scripts/bootstrap.sh` for environment setup.
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_success
}

68
plugins/core/skills/agentsmd-audit/tests/validate-secrets.bats Normal file
View File

@@ -0,0 +1,68 @@
#!/usr/bin/env bats
setup() {
REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../" && pwd)"
load "$REPO_ROOT/tests/test_helper/bats-support/load"
load "$REPO_ROOT/tests/test_helper/bats-assert/load"
SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate-secrets.sh"
TMPDIR="$(mktemp -d)"
}
teardown() {
rm -rf "$TMPDIR"
}
@test "passes on AGENTS.md with no secrets, only placeholders" {
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup
- Set `export API_KEY=$API_KEY`
- Token: <your-token-here>
- DB: postgres://user:changeme@localhost/db
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_success
assert_output ""
}
@test "fails on a real-looking AWS access key" {
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup
- AWS_ACCESS_KEY_ID=AKIAABCDEFGHIJKLMNOP # gitleaks:allow (synthetic fixture — this test verifies validate-secrets.sh catches exactly this pattern)
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_failure
assert_output --partial "AWS access key ID"
assert_output --partial "AGENTS.md:4"
}
@test "fails on a credential-bearing connection string" {
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup
- DB: postgres://svc_user:h8x2Klm9pQrT@db.internal:5432/prod
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_failure
assert_output --partial "connection string"
}
@test "detects secrets in a nested AGENTS.md, not just root" {
mkdir -p "$TMPDIR/packages/api"
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
Clean root file.
EOF
cat > "$TMPDIR/packages/api/AGENTS.md" <<'EOF'
# API package
- token: ghp_1234567890abcdefghijklmnopqrstuvwxyz01 # gitleaks:allow (synthetic fixture)
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_failure
assert_output --partial "packages/api/AGENTS.md"
}

76
plugins/core/skills/agentsmd-audit/tests/validate-structure.bats Normal file
View File

@@ -0,0 +1,76 @@
#!/usr/bin/env bats
setup() {
REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../" && pwd)"
load "$REPO_ROOT/tests/test_helper/bats-support/load"
load "$REPO_ROOT/tests/test_helper/bats-assert/load"
SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate-structure.sh"
TMPDIR="$(mktemp -d)"
}
teardown() {
rm -rf "$TMPDIR"
}
@test "fails on an empty AGENTS.md" {
: > "$TMPDIR/AGENTS.md"
run bash "$SCRIPT" "$TMPDIR"
assert_failure
assert_output --partial "empty"
}
@test "fails on an unfilled placeholder AGENTS.md" {
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup
FILL IN: describe setup commands here.
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_failure
assert_output --partial "placeholder"
}
@test "passes with INFO on real content missing an optional section" {
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Run tests: `pnpm test`
## Code style
- TypeScript strict mode, single quotes, no semicolons.
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_success
assert_output --partial "INFO"
assert_output --partial "security"
}
@test "suggests trimming a nested AGENTS.md that duplicates the root file" {
mkdir -p "$TMPDIR/packages/api"
cat > "$TMPDIR/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Run tests: `pnpm test`
- Lint: `pnpm lint`
- Build: `pnpm build`
EOF
cat > "$TMPDIR/packages/api/AGENTS.md" <<'EOF'
# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Run tests: `pnpm test`
- Lint: `pnpm lint`
- Build: `pnpm build`
EOF
run bash "$SCRIPT" "$TMPDIR"
assert_success
assert_output --partial "SUGGESTION"
assert_output --partial "packages/api/AGENTS.md"
}

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

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

56
plugins/core/skills/agentsmd-author/SKILL.md Normal file
View File

@@ -0,0 +1,56 @@
---
name: agentsmd-author
description: >
Use when the user wants to create or update a repo's AGENTS.md file
("write an AGENTS.md for this repo", "add setup/test instructions for
agents", "update AGENTS.md", "give this package its own AGENTS.md") — even
if they don't name the file explicitly, e.g. "document this for AI coding
tools" or "make sure agents know how to run tests here". Writes/updates
AGENTS.md by exploring the target repo for real build, test, lint, and
style conventions — never invents commands. Supports nested monorepo
placement (a subdirectory can get its own AGENTS.md following
nearest-file-wins precedence). Closes every run by invoking agentsmd-audit
inline, and calls provider-adapter-author when an existing provider file
(CLAUDE.md, etc.) now duplicates what AGENTS.md owns. Do not use to review
an existing AGENTS.md without changing it — use agentsmd-audit instead. Do
not use to convert CLAUDE.md/.cursor/rules into a thin adapter — use
provider-adapter-author instead.
allowed-tools: Bash Read Write Edit
metadata:
category: docs
source_keys:
- agents-md-official
- context7-websites-agents-md
- context7-agentsmd-agents-md
version: "0.1.1"
---
## Gotchas
- Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (`package.json` scripts, a `Makefile` target, a CI workflow step, a README). If you can't verify a command, don't include it.
- AGENTS.md has no required schema — don't force every common-sections-checklist heading into every repo. Include only sections that reflect something real about this repo; a thin, accurate file beats a padded, generic one.
- Nested placement is for genuinely different conventions, not convenience. Only create a subdirectory AGENTS.md when that subtree has its own build tool, stack, or conventions distinct from the root — otherwise you're duplicating content the root already covers, which the nearest-file-wins rule doesn't merge back together.
- This skill never touches CLAUDE.md, `.cursor/rules/*.mdc`, `copilot-instructions.md`, or similar provider files directly — that's `provider-adapter-author`'s job. Detect and hand off; don't reconcile it yourself.
- This skill never audits on its own judgment — the closing `agentsmd-audit` invocation is mandatory, not optional, even when the change looks trivial.
## Step 1 — Explore the target repo
Before writing anything, gather real facts: package manager and scripts (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.), a `Makefile` or task runner, CI config (`.github/workflows/`, etc.) for the commands it actually runs, linter/formatter config files, and any existing docs (`README.md`, existing `AGENTS.md`) describing conventions. Note whether any subdirectory looks like its own package with a different stack.
## Step 2 — Decide placement
- No `AGENTS.md` at the repo root yet → create one there first, covering whole-repo conventions.
- A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested `AGENTS.md` there, scoped to what's different. Don't repeat root-level content — the nearest-file-wins rule means the nested file is read alone, not merged with the root.
- Otherwise → update the existing file(s) in place.
## Step 3 — Write or update
Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
## Step 4 — Check for an existing provider file
Look for `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, or similar in the target repo. If one exists and now duplicates content the AGENTS.md you just wrote/updated already owns, invoke the `provider-adapter-author` skill on it to reconcile — don't rewrite it yourself.
## Step 5 — Audit and report
Invoke the `agentsmd-audit` skill directly on the AGENTS.md file(s) you just wrote or updated. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.

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

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

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

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

30
plugins/core/skills/provider-adapter-author/README.md Normal file
View File

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

54
plugins/core/skills/provider-adapter-author/SKILL.md Normal file
View File

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

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

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

9
plugins/core/skills/provider-adapter-author/scripts/README.md Normal file
View File

@@ -0,0 +1,9 @@
# scripts/
Deterministic self-check this skill shells out to instead of relying on LLM judgment for a mechanical check.
| File | Purpose |
|------|---------|
| `validate-adapter.sh` | Checks a rewritten provider file (CLAUDE.md, etc.) has a reference to AGENTS.md, doesn't duplicate its content, and stays under a thin-file line threshold |
Takes `<adapter-file> <agents-md-file>`, with optional `--no-import-syntax` and `--max-lines N` flags. Prints `FAIL` findings to stdout and exits non-zero on any failure.

141
plugins/core/skills/provider-adapter-author/scripts/validate-adapter.sh Executable file
View File

@@ -0,0 +1,141 @@
#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<EOF
Usage: validate-adapter.sh [--no-import-syntax] [--max-lines N] <adapter-file> <agents-md-file>
Self-check gate for provider-adapter-author. Checks that a rewritten
provider-specific instruction file (CLAUDE.md, .cursor/rules/*.mdc,
copilot-instructions.md, etc.) is actually a thin adapter over AGENTS.md,
not a duplicate copy of it.
Arguments:
adapter-file Path to the provider-specific file to check.
agents-md-file Path to the AGENTS.md file it should defer to.
Options:
--no-import-syntax The target provider has no native cross-file import
mechanism. Accept a plain-text pointer mention of
"AGENTS.md" instead of requiring an @import-style line.
--max-lines N Max non-blank lines allowed in the adapter file before
it's considered no longer "thin". Default: 60.
--help, -h Show this help and exit 0.
Exit codes:
0 Adapter file passes all checks
1 One or more checks failed (empty file, no reference to AGENTS.md,
excessive duplication, or file too long)
EOF
}
NO_IMPORT_SYNTAX=0
MAX_LINES=60
ARGS=()
while [[ $# -gt 0 ]]; do
case "$1" in
--help|-h)
usage
exit 0
;;
--no-import-syntax)
NO_IMPORT_SYNTAX=1
shift
;;
--max-lines)
MAX_LINES="${2:-}"
shift 2
;;
*)
ARGS+=("$1")
shift
;;
esac
done
if [[ ${#ARGS[@]} -lt 2 ]]; then
echo "Error: adapter-file and agents-md-file are required." >&2
echo "" >&2
usage >&2
exit 1
fi
python3 -u - "${ARGS[0]}" "${ARGS[1]}" "$NO_IMPORT_SYNTAX" "$MAX_LINES" <<'PYTHON'
import sys
import os
import re
adapter_path, agents_md_path, no_import_syntax, max_lines = sys.argv[1:5]
no_import_syntax = no_import_syntax == "1"
max_lines = int(max_lines)
if not os.path.isfile(adapter_path):
print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr)
sys.exit(1)
if not os.path.isfile(agents_md_path):
print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr)
sys.exit(1)
with open(adapter_path, encoding="utf-8", errors="replace") as f:
adapter_content = f.read()
with open(agents_md_path, encoding="utf-8", errors="replace") as f:
agents_md_content = f.read()
has_fail = False
if not adapter_content.strip():
print(f"FAIL Adapter file is empty — {adapter_path}")
print(" Why: An empty adapter carries no reference to AGENTS.md and no provider-specific content.")
print(" Fix: Add at least an import (or text pointer) to AGENTS.md.")
print()
sys.exit(1)
IMPORT_RE = re.compile(r'(?m)^\s*@\S*AGENTS\.md\s*$')
lines = adapter_content.splitlines()
import_lines = [ln for ln in lines if IMPORT_RE.match(ln)]
if no_import_syntax:
has_reference = "AGENTS.md" in adapter_content
else:
has_reference = bool(import_lines) or "AGENTS.md" in adapter_content
if not has_reference:
has_fail = True
print(f"FAIL Adapter has no reference to AGENTS.md — {adapter_path}")
if no_import_syntax:
print(" Why: This provider has no import syntax, so the adapter must at least mention AGENTS.md as a text pointer.")
print(" Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\"")
else:
print(" Why: A thin adapter must import AGENTS.md (e.g. `@AGENTS.md`) rather than silently omitting it.")
print(" Fix: Add an `@AGENTS.md` (or equivalent relative path) import line.")
print()
# --- Duplication check ---
non_import_lines = [ln for ln in lines if not IMPORT_RE.match(ln)]
adapter_lines = [ln.strip() for ln in non_import_lines if ln.strip()]
agents_lines = {ln.strip() for ln in agents_md_content.splitlines() if ln.strip()}
if adapter_lines:
overlap = sum(1 for ln in adapter_lines if ln in agents_lines)
ratio = overlap / len(adapter_lines)
if ratio > 0.3:
has_fail = True
print(f"FAIL Adapter duplicates AGENTS.md content — {adapter_path}")
print(f" Why: {ratio:.0%} of the adapter's non-import lines already appear verbatim in AGENTS.md. A thin adapter should import shared content, not restate it.")
print(" Fix: Remove the duplicated lines and rely on the AGENTS.md import (or pointer) instead.")
print()
# --- Size check ---
non_blank_count = len([ln for ln in lines if ln.strip()])
if non_blank_count > max_lines:
has_fail = True
print(f"FAIL Adapter is not thin — {adapter_path}")
print(f" Why: {non_blank_count} non-blank lines exceeds the {max_lines}-line threshold for a thin adapter.")
print(" Fix: Move provider-agnostic content into AGENTS.md; keep only genuinely provider-specific additions here.")
print()
if has_fail:
sys.exit(1)
sys.exit(0)
PYTHON

28
plugins/core/skills/provider-adapter-author/tests/README.md Normal file
View File

@@ -0,0 +1,28 @@
# tests/
Test files for scripts bundled with this skill.
## Dependencies
Tests require [bats-support](https://github.com/bats-core/bats-support) and
[bats-assert](https://github.com/bats-core/bats-assert). The test files load
helpers from the repo root's `tests/test_helper/`.
From the repo root:
```bash
git clone https://github.com/bats-core/bats-support tests/test_helper/bats-support
git clone https://github.com/bats-core/bats-assert tests/test_helper/bats-assert
```
Run all tests for this skill (from the repo root):
```bash
bats plugins/core/skills/provider-adapter-author/tests/
```
## Files
| File | Purpose |
|------|---------|
| `validate-adapter.bats` | Bats test suite for `scripts/validate-adapter.sh` |

128
plugins/core/skills/provider-adapter-author/tests/validate-adapter.bats Normal file
View File

@@ -0,0 +1,128 @@
#!/usr/bin/env bats
setup() {
REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../" && pwd)"
load "$REPO_ROOT/tests/test_helper/bats-support/load"
load "$REPO_ROOT/tests/test_helper/bats-assert/load"
SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate-adapter.sh"
TMPDIR="$(mktemp -d)"
AGENTS_MD="$TMPDIR/AGENTS.md"
cat > "$AGENTS_MD" <<'EOF'
# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Run tests: `pnpm test`
## Code style
- TypeScript strict mode, single quotes, no semicolons.
EOF
}
teardown() {
rm -rf "$TMPDIR"
}
@test "fails when the adapter file is empty" {
ADAPTER="$TMPDIR/CLAUDE.md"
: > "$ADAPTER"
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_failure
assert_output --partial "empty"
}
@test "fails when the adapter has no reference to AGENTS.md" {
ADAPTER="$TMPDIR/CLAUDE.md"
cat > "$ADAPTER" <<'EOF'
# Claude-specific notes
Use the internal linter before committing.
EOF
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_failure
assert_output --partial "no reference"
}
@test "passes a thin adapter with an @import line and provider-specific additions" {
ADAPTER="$TMPDIR/CLAUDE.md"
cat > "$ADAPTER" <<'EOF'
@AGENTS.md
@core/instructions/governance.md
EOF
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_success
}
@test "fails when the adapter duplicates most of AGENTS.md's content" {
ADAPTER="$TMPDIR/CLAUDE.md"
cat > "$ADAPTER" <<'EOF'
@AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Run tests: `pnpm test`
## Code style
- TypeScript strict mode, single quotes, no semicolons.
EOF
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_failure
assert_output --partial "duplicat"
}
@test "fails when the adapter exceeds the max line threshold" {
ADAPTER="$TMPDIR/CLAUDE.md"
{
echo "@AGENTS.md"
for i in $(seq 1 80); do echo "Provider-specific line $i unrelated to AGENTS.md content."; done
} > "$ADAPTER"
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_failure
assert_output --partial "thin"
}
@test "allows a custom --max-lines threshold" {
ADAPTER="$TMPDIR/CLAUDE.md"
{
echo "@AGENTS.md"
for i in $(seq 1 10); do echo "Provider-specific line $i unrelated to AGENTS.md content."; done
} > "$ADAPTER"
run bash "$SCRIPT" --max-lines 5 "$ADAPTER" "$AGENTS_MD"
assert_failure
assert_output --partial "thin"
}
@test "with --no-import-syntax, a text pointer to AGENTS.md is accepted instead of an @import line" {
ADAPTER="$TMPDIR/copilot-instructions.md"
cat > "$ADAPTER" <<'EOF'
See AGENTS.md at the repo root for setup, style, and testing conventions.
## Copilot-specific
Prefer inline suggestions over chat for one-line edits.
EOF
run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
assert_success
}
@test "with --no-import-syntax, still fails if there is no mention of AGENTS.md at all" {
ADAPTER="$TMPDIR/copilot-instructions.md"
cat > "$ADAPTER" <<'EOF'
## Copilot-specific
Prefer inline suggestions over chat for one-line edits.
EOF
run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
assert_failure
assert_output --partial "no reference"
}
@test "--help exits 0 and documents usage" {
run bash "$SCRIPT" --help
assert_success
assert_output --partial "Usage:"
}
@test "fails with a clear error when the adapter file argument is missing" {
run bash "$SCRIPT"
assert_failure
assert_output --partial "required"
}

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

@@ -10,9 +10,10 @@
"issues",
"prs",
"milestones",
"releases"
"releases",
"branches"
],
"license": "MIT",
"name": "gitea",
"version": "1.0.0"
"version": "1.3.3"
}

79
plugins/gitea/agents/gitea-orchestrate.agent.md Normal file
View File

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

95
plugins/gitea/agents/gitea-orchestrate.md Normal file
View File

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

14
plugins/gitea/docs/research/docs/gitea/sources.md
View File

@@ -20,3 +20,17 @@
- **Description:** Gitea REST API swagger documentation covering underlying endpoints for issues, PRs, labels, milestones, and branches
- **Contributing files:** (see notes below)
- **Status:** `no content extracted` — source fetch timed out; all reference content derived from gitea-mcp source files which are authoritative for MCP tool usage
## context7-websites-gitea
- **URL:** context7:/websites/gitea
- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — scoped/exclusive label conventions, branch protection and PR review/merge rules, release and webhook semantics, issue/PR automatic cross-reference linking, protected-branch signed-commit safeguards, reverse-proxy request size limits, and repository upload limits. Backfills the external/best-practice gap left by the original docs.gitea.com fetch timeout.
- **Contributing files:** workflow-conventions.md, troubleshooting.md
- **Status:** `extracted`
## context7-gitea-tea-cli
- **URL:** context7:/git_gitea_com/gitea_tea
- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner command patterns for issues, PRs, and releases, including semver tag/release conventions, draft/prerelease flags, and release-notes-from-file conventions.
- **Contributing files:** workflow-conventions.md
- **Status:** `extracted`

9
plugins/gitea/docs/research/docs/gitea/troubleshooting.md
View File

@@ -3,6 +3,7 @@ topic: troubleshooting
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
- context7-websites-gitea
---
# Gitea MCP — Troubleshooting
@@ -86,6 +87,14 @@ The MCP server surfaces HTTP error codes from the Gitea REST API:
The `milestones` parameter on `list_issues` accepts milestone names or IDs as an array. Using IDs is more reliable — milestone names are mutable. Always prefer filtering by milestone ID when programmatically filtering.
## Signed-commit branch protection can silently block file writes
A protected branch can require signed commits as a safeguard (`docs.gitea.com/usage/access-control/protected-branches`). `create_or_update_file` and `delete_file` both create commits server-side via a bare API token call with no 2FA/PGP context — if the target branch's protection rule requires signed commits, Gitea rejects the push outright. The MCP tool surfaces this as a generic write failure (typically 403 or 422), not a message naming "signed commit required" — `get_file_contents` (read) keeps succeeding right up until the write. When a file write fails without a 409 (missing/stale SHA) or 404 (bad path) explanation, check whether the target branch's protection rule requires signed commits before assuming the SHA is wrong.
## Large file content can hit a reverse-proxy 413, not a Gitea limit
`create_or_update_file` sends `content` base64-encoded, which inflates the payload ~33% over the raw file size. A `413 Request Entity Too Large` response is commonly a reverse-proxy body-size limit in front of the Gitea instance (e.g. nginx `client_max_body_size`), not a Gitea-side rejection (`docs.gitea.com/administration/reverse-proxies`, `docs.gitea.com/help/faq`) — Gitea's own configured upload limit is a separate, unrelated setting (50MB per file by default, for the web upload feature). A 413 on a file-write call is an infrastructure-layer symptom that cannot be fixed by changing the request (a different SHA, path, or branch won't help) — it requires the reverse-proxy config to be raised, which is outside the skill's or the calling agent's control. Surface this distinction to the user rather than retrying the same call.
## `per_page` defaults vary
Not all endpoints share the same default `per_page`:

88
plugins/gitea/docs/research/docs/gitea/workflow-conventions.md Normal file
View File

@@ -0,0 +1,88 @@
---
topic: workflow-conventions
source_keys:
- context7-websites-gitea
- context7-gitea-tea-cli
---
# Gitea Workflow Conventions
Practitioner conventions and platform behavior that inform *how* to use the mechanics already
documented in `api-reference.md` — not additional tool schemas.
## Scoped, exclusive labels
Gitea labels support a scoped-label convention: a `/` delimiter in the label name (e.g.
`Priority/High`) plus an `exclusive: true` flag means only one label from that scope can be applied
to an issue or PR at a time — applying a new `Priority/*` label automatically replaces the previous
one. This is exactly the `Kind/*` / `Priority/*` / `Status/*` taxonomy already used in this repo's
own label set, confirming the taxonomy follows Gitea's native scoped-label convention rather than an
ad hoc naming scheme. When defining or inferring labels, a scope prefix implies mutual exclusivity —
label inference logic should replace, not add to, existing labels in the same scope.
Repositories can also seed a predefined label set at creation time from a YAML label file
(`name`, `color`, `description`, `exclusive`), which is where the base `Kind/Priority/Status` sets
typically originate.
## Milestone and label state as first-class transitions
Both issues and PRs treat labeling and milestoning as discrete state-transition events
(`label_updated`/`label_cleared`, `milestoned`/`demilestoned`), not passive metadata fields. This
reinforces treating `gitea-labels-milestones` as a shared skill: the same transition semantics apply
whether the target is an issue or a PR.
## Automatic cross-reference linking
Gitea auto-renders issue/PR references in body text without any API call: `#1234` and `!1234` both
resolve to issue/PR 1234 in the same repo (issues and PRs share one number space, consistent with
`data-model.md`); cross-repo references use `owner/repo#1234` (issue) or `owner/repo!1234` (PR). This
directly validates the dependency-linking convention decided for `gitea-issues` (issue #6, comment
#848): writing `Depends on #N` in an issue body is not just a text convention — Gitea renders it as
a real clickable cross-reference automatically, with no separate API call required. For
external-issue-tracker repos, the same syntax renders as an external link instead, so the skill
should assume same-repo internal linking unless told otherwise.
## Pull request review workflow
The reviewer flow is: comment, request changes, or approve; the author pushes updates to the same
branch, which the PR auto-tracks; maintainers merge once approved. Protected branches can layer
additional constraints on top of this base flow:
- An allowlist of users/teams may be required to approve before merge is possible.
- A minimum approval count can be enforced.
- Stale approvals (approvals given before new commits were pushed) can be auto-dismissed or ignored.
- Merge can be blocked if any review requests changes, if requested reviewers haven't reviewed yet,
or if the branch is outdated relative to its base.
- Repository admins are not exempt from these rules by default — an explicit
"administrators must follow branch protection rules" setting is what removes their force-merge
bypass.
A skill that merges PRs should treat "CI passing" and "reviews satisfied" as two independently
checkable gates — `get_status` covers CI, but review/approval state and branch-protection
constraints are a separate check the merge call itself will enforce server-side and return as an
error if unmet.
## Release and tag conventions
Releases are conceptually separate from tags but always tied to one: a release wraps a tag with a
title, notes, and optional binary assets. Practitioner convention (per the `tea` CLI, the reference
Gitea client) is:
- Tag names are semver-style, typically `v`-prefixed (`v1.2.0`, `v2.0.0-beta.1`).
- Release notes are commonly sourced from a changelog file rather than typed inline.
- Draft and prerelease are separate boolean flags, not states inferred from the tag name — a
prerelease is anything with a `-beta`/`-rc` style suffix by convention, but Gitea does not enforce
this; the skill should treat `draft`/`prerelease` as flags the caller sets explicitly rather than
something to infer from the tag string.
- Deleting a release does not delete its tag by default — the two are separate destructive
operations (confirmed by `delete_release` taking a numeric release ID per `troubleshooting.md`,
distinct from `delete_tag`).
## File editing: direct commit vs. PR
Gitea's own UI defaults to prompting for a target branch when creating/editing a file directly
through the web interface, and supports pre-filling a new file's path and content via query
parameters — reflecting that direct-commit file edits are a first-class, expected workflow (not just
an API escape hatch). This supports `create_or_update_file`/`delete_file` being used directly against
a working branch as a normal editing action, with the SHA-currency requirement (`troubleshooting.md`)
being the main gotcha rather than direct-commit being an anti-pattern to avoid.

5
plugins/gitea/plugin.json
View File

@@ -11,7 +11,8 @@
"issues",
"prs",
"milestones",
"releases"
"releases",
"branches"
],
"license": "MIT",
"mcpServers": ".mcp.json",
@@ -19,5 +20,5 @@
"skills": [
"skills/"
],
"version": "1.0.0"
"version": "1.3.3"
}

0
plugins/bin/skills/gitea/references/token-access.md → plugins/gitea/references/token-access.md
View File

37
plugins/gitea/skills/gitea-branches/README.md Normal file
View File

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

66
plugins/gitea/skills/gitea-branches/SKILL.md Normal file
View File

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

81
plugins/gitea/skills/gitea-branches/references/branches.md Normal file
View File

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

73
plugins/gitea/skills/gitea-branches/references/commits.md Normal file
View File

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

41
plugins/gitea/skills/gitea-branches/references/sources.md Normal file
View File

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

23
plugins/gitea/skills/gitea-files/README.md Normal file
View File

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

56
plugins/gitea/skills/gitea-files/SKILL.md Normal file
View File

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

65
plugins/gitea/skills/gitea-files/references/examples.md Normal file
View File

@@ -0,0 +1,65 @@
---
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# Canonical call sequences
## Push a file to a new branch, then open a PR
```
1. get_repository_tree or get_file_contents on the base branch — only needed if the
new file is actually replacing an existing one; skip for a brand-new path.
2. create_or_update_file
owner, repo
path: "docs/example.md"
content: "<base64-encoded content>"
message: "docs: add example"
branch_name: "main"
new_branch_name: "feat/add-example" ← branches off before the commit lands
(sha omitted — this is a new file)
3. Hand off to gitea-prs to open a PR from "feat/add-example" into "main".
```
`new_branch_name` on `create_or_update_file` replaces a separate branch-creation call — the branch is created and the commit lands on it in one step.
## Update a file when you don't already have its SHA
SHA is mandatory for updates. If it wasn't captured earlier in the conversation:
```
1. get_file_contents
owner, repo
ref: "main"
path: "docs/example.md"
→ read the top-level `sha` field (not content.sha)
2. create_or_update_file
owner, repo
path: "docs/example.md"
content: "<new base64-encoded content>"
message: "docs: update example"
branch_name: "main"
sha: "<sha from step 1>"
```
Do not guess or omit the SHA — the write either fails (409 on create-path fallback) or is rejected outright.
## Delete a file
Same SHA-first pattern, no fallback path:
```
1. get_file_contents owner, repo, ref: "main", path: "docs/old-example.md"
→ read the top-level `sha` field
2. delete_file
owner, repo
path: "docs/old-example.md"
message: "docs: remove old example"
branch_name: "main"
sha: "<sha from step 1>"
```

46
plugins/gitea/skills/gitea-files/references/sources.md Normal file
View File

@@ -0,0 +1,46 @@
# Sources
## gitea-mcp-repo
**Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags.
**Source:** https://gitea.com/gitea/gitea-mcp
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
**Contributing files:**
- SKILL.md (Gotchas, Reading, Writing — tool parameters and SHA/concurrency behavior, cross-checked live against the deployed MCP tool schemas via ToolSearch)
- references/examples.md (canonical call sequences)
## gitea-mcp-slim-go
**Description:** Slim response shape structs from gitea-mcp source; defines exactly which fields the MCP server returns for files (top-level `sha`, no nested `content.sha`) and directory/tree entries.
**Source:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/repo/slim.go
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
**Contributing files:**
- SKILL.md (Gotchas — top-level `sha` field location, `get_dir_contents`/`get_repository_tree` not being usable SHA sources for a file write)
- references/examples.md (SHA-first update/delete sequences)
## context7-websites-gitea
**Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — confirms direct-commit file editing through the web UI is a first-class, expected workflow rather than an API-only escape hatch.
**Source:** context7:/websites/gitea
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
**Contributing files:**
- SKILL.md (Gotchas — "Direct commits to a branch are a first-class action, not a workaround")
## context7-gitea-tea-cli
**Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner command patterns for issues, PRs, and releases, including semver tag/release conventions, draft/prerelease flags, and release-notes-from-file conventions. Consulted alongside `context7-websites-gitea` while researching `workflow-conventions.md` (both sources contribute to that research doc, backing `gitea-workflow`); its file-command patterns did not end up informing any gitea-files content.
**Source:** context7:/git_gitea_com/gitea_tea
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
**Contributing files:** (none)

42
plugins/gitea/skills/gitea-issues/README.md Normal file
View File

@@ -0,0 +1,42 @@
# gitea-issues
Read and write Gitea issues — list, get, create, comment, close, and search — via the Gitea MCP server.
## What it does
This skill handles the issue lifecycle (`list_issues`, `issue_read`, `issue_write`, `search_issues`):
listing repo issues, reading a single issue's details/comments/labels, creating an issue, updating
its state, adding/editing comments, applying labels, and searching issues/PRs across repositories.
The create flow closes out four enrichments deferred from issue #6 comment #848: label inference
and milestone assignment (both by composing `gitea-labels-milestones`), an assignee workaround for
the blocked `get_me` scope, and the "Depends on #N" dependency-linking convention. It supersedes the
`issue`/`issue <N>`/`issue close <N>`/`issue comment <N>` dispatch in the old flat
`plugins/bin/skills/gitea/SKILL.md`, removed per
`docs/adr/0011-gitea-skill-deep-modules.md`.
## Before you start
Requires a Gitea MCP server configured with a token holding `write:issue` + `write:repository`.
Requires a git remote named `origin` pointing at the Gitea instance, unless an orchestrating caller
(e.g. `gitea-workflow`) already resolved `owner`/`repo` for you. Label and milestone management
(creating/editing a label, creating/closing a milestone) is out of scope here — that's
`gitea-labels-milestones`, which this skill composes rather than duplicates.
## Usage
```
/gitea-issues
```
Describe your task: list issues, create one, get/comment/close a specific issue number, or search
across repos. See `SKILL.md`'s dispatch table for the full set of recognized invocations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — dispatch table, Gotchas |
| `references/issues.md` | Verified call signatures and mechanics for `list_issues`/`issue_read`/`issue_write` |
| `references/search.md` | Verified call signature and mechanics for `search_issues` |
| `references/enrichments.md` | Create-flow enrichments — label inference, milestone assignment, assignee workaround, dependency-linking convention |
| `references/sources.md` | Research sources backing the issue guidance |

105
plugins/gitea/skills/gitea-issues/SKILL.md Normal file
View File

@@ -0,0 +1,105 @@
---
name: gitea-issues
description: >
Use when reading or writing Gitea issues: listing repo issues, getting a single issue's details/
comments/labels, creating an issue, updating its state, adding or editing comments, applying
labels via issue_write, or searching issues/PRs across repositories. Triggers on "create an
issue", "what issues are open", "get issue #N", "close issue #N", "comment on issue #N", "search
issues for X" — even when the user doesn't say "Gitea" explicitly. Composes gitea-labels-
milestones for all label inference/resolution and milestone lookup — do not use this skill to
manage label or milestone definitions themselves (create/edit/delete a label, create/close a
milestone), that's gitea-labels-milestones directly. Do not use for pull requests (use gitea-prs)
or for local git branch/commit work (use gitea-branches or git-branches).
compatibility: Requires Gitea MCP server configured with write:issue and write:repository token
scopes. Requires git remote "origin" pointing to the Gitea instance for owner/repo resolution
when invoked directly by a human; an orchestrating caller (e.g. gitea-workflow) may pass
owner/repo already resolved.
metadata:
category: integration
version: "0.1.0"
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
- context7-websites-gitea
- context7-gitea-tea-cli
allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__issue_write mcp__gitea__search_issues
---
## Gotchas
- **`list_issues` has no `type` or `milestones` parameter — despite `api-reference.md` documenting both.** The live MCP schema (re-verified via `ToolSearch` at authoring time — see `references/sources.md`) only accepts `owner`, `repo` (required), `state` (default `"all"`), `labels` (array of label *names*), `since`, `before` (ISO 8601), `page`, `per_page` (default 30). This tool provides no way to filter issues-vs-PRs or by milestone. Since issues and PRs share one number space, `list_issues` results can include PR entries with no client-side filter to exclude them. If you need to know whether a specific number is a PR, call `issue_read method: "get"` and check `is_pull` — that field only appears on the single-item response, never in a list item. This exact drift (a prior skill trusted the research doc's `type` param and broke) is why this skill's reference files were re-verified live rather than copied from `api-reference.md`.
- **`search_issues` does have a working `type` filter** (`"issues"` | `"pulls"`) — unlike `list_issues`. Its `labels` parameter is also shaped differently: a comma-separated string, not an array of names.
- **Labels are numeric IDs on write, name strings on read.** `issue_write`'s `labels` parameter (used by `add_labels`/`replace_labels`) takes IDs. `list_issues`/`issue_read` return names. Never resolve this yourself — compose `gitea-labels-milestones` (see `references/enrichments.md`) to get IDs.
- **Milestone on `issue_read` is `{id, title}`** — an object, not a bare string. This skill only ever needs the `id`. (The bare-title-string case only happens on the PR side, which is `gitea-prs`' problem, not this skill's.)
- **Closing-keyword auto-close behavior is plausible but unconfirmed in our research docs.** Our research docs confirm Gitea does NOT auto-close an issue on a plain PR merge (unlike GitHub) — closing keywords like `Fixes #N`/`Closes #N` in a commit message are not documented one way or the other. After a PR merges (a `gitea-prs` operation), always re-check the issue's state here via `issue_read method: "get"` before deciding whether to close it manually — closing an already-closed issue is a harmless no-op, but don't assume a manual close is always needed.
- **Pagination is manual.** `list_issues` and `search_issues` return one page at a time. Iterate `page: 1, 2, ...` until the returned count is less than `per_page`.
- **HTTP 404 may actually mean 403.** Gitea hides permission errors as not-found. If a call 404s unexpectedly, verify the token holds `write:issue` scope (see `references/issues.md`'s Token scope note) before concluding the issue doesn't exist.
## Step 1 — Resolve owner and repo
Before any tool call, extract `owner` and `repo` from the git remote (skip this if an orchestrating caller already passed them in):
```bash
git remote get-url origin
```
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
## Step 2 — Dispatch
| Invocation | Action |
|---|---|
| `/gitea-issues` or `/gitea-issues list` | List issues (optional state filter) |
| `/gitea-issues create` | Create an issue from conversation context — infers labels, checks milestone fit, applies a configured default assignee if set |
| `/gitea-issues <N>` | Get issue details (flag it as a PR if `is_pull: true`) |
| `/gitea-issues <N> comments` | Get an issue's comments |
| `/gitea-issues close <N>` | Close an issue |
| `/gitea-issues comment <N>` | Add a comment from conversation context |
| `/gitea-issues search <query>` | Cross-repo search via `search_issues` |
For full parameter detail on `list_issues`/`issue_read`/`issue_write`, read `references/issues.md`. For `search_issues`, read `references/search.md`. For the create-flow enrichments (label inference, milestone assignment, assignee workaround, dependency-linking), read `references/enrichments.md`.
## Step 3 — Execute
### list (default)
Call `list_issues owner: <owner> repo: <repo> state: <"open"|"closed"|"all", default "all">`. Remember: results may include PR entries (see Gotchas) — if the caller needs issues only, this tool cannot filter that server-side; note the limitation rather than silently mislabeling PR entries as issues.
### create
1. Extract `title` and `body` from conversation context (the most recent task, bug description, or explicit statement). Fall back to an empty body if nothing is available.
2. Run the enrichment sequence in `references/enrichments.md`: infer labels (composing `gitea-labels-milestones`), check for a clearly-fitting open milestone (composing the same skill), and check for a configured default assignee.
3. Call `issue_write method: "create" owner: <owner> repo: <repo> title: <title> body: <body> labels: [<resolved IDs, or omit>] milestone: <resolved ID, or omit> assignees: [<default login, or omit>]`.
4. Fire immediately — no confirmation step for the create itself.
### `<N>` (get)
Call `issue_read method: "get" owner: <owner> repo: <repo> issue_number: <N>`. If `is_pull: true`, report that this number is actually a PR and suggest `gitea-prs` for full detail.
### `<N> comments`
Call `issue_read method: "get_comments" owner: <owner> repo: <repo> issue_number: <N>`.
### close `<N>`
Call `issue_write method: "update" owner: <owner> repo: <repo> issue_number: <N> state: "closed"`. No `method: "close"` exists.
### comment `<N>`
Extract the comment body from conversation context (same sourcing as create). Call `issue_write method: "add_comment" owner: <owner> repo: <repo> issue_number: <N> body: <body>`.
### search `<query>`
Call `search_issues query: <query>`, adding `owner`, `state`, `type`, or `labels` filters if the request narrows scope (e.g. "search open PRs for X" → `type: "pulls" state: "open"`).
## Step 4 — Report
For reads: a compact table or numbered list — number, title, state, labels, milestone.
For writes: confirm what was created/updated with the issue number and URL if returned.
For errors: surface the HTTP code and message; check token scope per the Gotchas if a 404 looks wrong.

92
plugins/gitea/skills/gitea-issues/references/enrichments.md Normal file
View File

@@ -0,0 +1,92 @@
---
topic: enrichments
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
- context7-websites-gitea
---
# Create-flow enrichments
Closes out the four enrichments deferred from issue #6 comment #848. Run in this order before the
`issue_write method: "create"` call in SKILL.md's create dispatch: **labels → milestone →
assignee → dependency link**. Each step is independent and skippable on its own — a missing
milestone fit doesn't block label inference, and so on — but this is the order that lets later
steps use context established earlier (e.g. the inferred `Kind/*` label can inform which milestone
plausibly fits).
**Cross-skill composition note:** none of the steps below read `gitea-labels-milestones`'s
reference files directly by path. A plugin install copies each skill's directory into an isolated
cache — any file path that leaves this skill's own directory breaks post-install. Instead, compose
`gitea-labels-milestones` as a skill: describe the task to it (its own `SKILL.md` and description
trigger it) and consume the resolved IDs it returns. This mirrors how `gitea-labels-milestones`'s
own description already frames the relationship ("`gitea-issues` and `gitea-prs` both compose it").
## 1. Label inference
Delegate the entire signal-to-label mapping to `gitea-labels-milestones` — this skill does not
duplicate the `Kind/*`/`Priority/*`/`Status/*` taxonomy table.
1. Compose `gitea-labels-milestones` to resolve labels for the issue being created: give it the
draft title/body and ask it to infer and resolve applicable labels (it calls
`label_read method: "list_repo_labels"` internally and runs its own inference procedure).
2. Take back the resolved label IDs (and which scope groups, if any, need replacing — not relevant
yet on a brand-new issue, since there's nothing to replace).
3. If `gitea-labels-milestones` reports low confidence and omits a `Kind/*` label, pass no `Kind/*`
ID rather than guessing one yourself. `Priority/Medium` is the one label its own inference
procedure defaults to when no urgency signal is present — that's expected, not a gap.
4. Pass the resulting label IDs to `issue_write`'s `labels` parameter (omit the parameter entirely
if the resolved list is empty).
## 2. Milestone assignment on create
1. Compose `gitea-labels-milestones` to list open milestones (it calls
`milestone_read method: "list" state: "open"` internally).
2. Compare the issue's inferred scope (title, body, and any `Kind/*` label from step 1) against
each open milestone's title/description. Assign a milestone only when the fit is clear — a
milestone literally named for the feature area, or one whose description explicitly covers this
kind of work. A milestone that's merely "the current one" without a clear scope match is not a
confident fit.
3. If a milestone clearly fits, pass its **numeric ID** (never the title) as `issue_write`'s
`milestone` parameter. `issue_write`'s `milestone` field only accepts the ID — see
`references/issues.md`.
4. If no milestone clearly fits, omit `milestone` entirely. Guessing a milestone assignment is worse
than leaving it unset — an issue can always be milestoned later, but a wrong milestone
assignment pollutes that milestone's issue count and scope.
## 3. Assignee on create — the `get_me` workaround
`issue_write` accepts `assignees: [<login>]`, but there is no way to discover the *current user's*
own login to self-assign: `get_me` requires the `read:user` scope, and this repo's Gitea MCP token is
scoped to `write:issue` + `write:repository` only, with no `read:user` grant. This is a hard
capability gap, not something to work around with a guess.
**Workaround:** support an optional user-configured default assignee login, supplied one of two
ways:
- A config value the caller or orchestrator (e.g. `gitea-workflow`) already resolved and passes in
when invoking this skill.
- A login explicitly stated in the conversation ("assign this to alice") — use that login directly,
no lookup needed, since Gitea accepts a login string without requiring you to resolve an ID first.
**If neither is available, omit `assignees` entirely.** Do not guess a login, do not fail the create
over a missing assignee, and do not attempt `get_me`/`search_users` as a fallback — both are blocked
by the same scope gap and will only produce a confusing secondary error.
## 4. Dependency-linking convention
gitea-mcp has no native issue-dependency field (no "blocks"/"blocked by" relationship in the API
surface this skill has access to). The convention is to write **"Depends on #N"** as a line in the
issue body.
This is not just a text convention with no effect — Gitea auto-renders `#N` (and `!N` for PRs) as a
real clickable cross-reference with no separate API call, a documented platform behavior (see
`references/sources.md` for the backing research). This works because issues and PRs share one
repo-scoped number space. Use the bare `#N` form for same-repo dependencies; use `owner/repo#N` for
a dependency in a different repo.
When creating an issue that depends on another, append a line like:
```
Depends on #42
```
to the body before calling `issue_write method: "create"`. There is no separate field or follow-up
call — the rendering happens automatically once the body is saved.

123
plugins/gitea/skills/gitea-issues/references/issues.md Normal file
View File

@@ -0,0 +1,123 @@
---
topic: issues
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# Issue operations
Call signatures below were verified live against the deployed `gitea-mcp` server via `ToolSearch`
at authoring time, not copied from `api-reference.md` — this is deliberate: research docs are
generated from source at a point in time and can drift from the server actually deployed (see the
`list_issues` gotcha below, which is the exact drift this policy exists to catch). Re-verify against
the live schema if these tools appear to behave differently than documented here.
## `list_issues`
**Parameters (live schema):**
- `owner` (string, required)
- `repo` (string, required)
- `state` (string, optional, default `"all"`) — conventional values `"open"`/`"closed"`/`"all"`, not
schema-enforced as an enum
- `labels` (array of strings, optional) — filter by label *name* (not ID)
- `since` (string, optional) — ISO 8601, issues updated after this time
- `before` (string, optional) — ISO 8601, issues updated before this time
- `page` (number, optional, default `1`)
- `per_page` (number, optional, default `30`)
**There is no `type` parameter and no `milestones` parameter**, despite both appearing in
`api-reference.md`. This tool cannot filter issues-vs-PRs or by milestone — see the Gotchas section
of SKILL.md for the consequence (PR entries can appear in results with no way to exclude them here).
**Call:**
```
list_issues owner: <owner> repo: <repo> state: "open"
```
**Response (list item):** `number`, `title`, `state`, `html_url`, `user`, `comments`, `created_at`,
`updated_at`, and optionally `labels` (`[]string`), `milestone` (`{id, title}`), `ref`, `deadline`.
Body and `closed_at` are omitted from list responses — call `issue_read method: "get"` for those.
Paginate with `page`/`per_page` until the returned count is less than `per_page`.
## `issue_read`
**Parameters (live schema, matches `api-reference.md`):**
- `method` (string, required, enum) — `"get"` | `"get_comments"` | `"get_labels"`
- `owner` (string, required)
- `repo` (string, required)
- `issue_number` (number, required)
**`get`** — full issue: `number`, `title`, `body`, `state`, `html_url`, `user`, `labels`
(`[]string`), `comments`, `created_at`, `updated_at`, `closed_at`, and optionally `assignees`
(`[]string`), `milestone` (`{id, title}`), `ref`, `deadline`, `is_pull` (present only when this
number is backed by a pull request — absent, not `false`, on true issues).
**`get_comments`** — array of `{id, body, user, html_url, created_at, updated_at}`.
**`get_labels`** — array of full label objects (`id`, `name`, `color`, `description` — not slimmed
to name strings, unlike the labels array on `get`).
**Call:**
```
issue_read method: "get" owner: <owner> repo: <repo> issue_number: <N>
```
Always check `is_pull` before treating a number as a plain issue — see the shared number-space
gotcha in SKILL.md.
## `issue_write`
**Parameters (live schema, matches `api-reference.md`):**
- `method` (string, required, enum) — `"create"` | `"update"` | `"add_comment"` | `"edit_comment"` |
`"add_labels"` | `"remove_label"` | `"replace_labels"` | `"clear_labels"`
- `owner` (string, required)
- `repo` (string, required)
- `issue_number` (number, required for every method except `"create"`)
- `title` (string, required for `"create"`)
- `body` (string, required for `"create"`, `"add_comment"`, `"edit_comment"`)
- `assignees` (array of strings, optional) — login names (see `references/enrichments.md` for why
this is usually omitted)
- `milestone` (number, optional) — milestone ID, never a title
- `state` (string, enum `"open"`/`"closed"`/`"all"`, optional) — for `"update"`
- `commentID` (number, optional, required for `"edit_comment"`)
- `labels` (array of numbers, optional) — label IDs, never names — for `add_labels`/`replace_labels`
- `label_id` (number, optional, required for `"remove_label"`) — singular, not the array form
- `ref` (string, optional) — branch association, informational only
- `deadline` (string, optional) — ISO 8601
- `remove_deadline` (boolean, optional)
**Create:**
```
issue_write method: "create"
owner: <owner> repo: <repo>
title: <title> body: <body>
labels: [<resolved IDs>] ← omit if none confidently inferred
milestone: <resolved ID> ← omit if none clearly fits
assignees: ["<login>"] ← omit if no default configured
```
**Close:**
```
issue_write method: "update" owner: <owner> repo: <repo> issue_number: <N> state: "closed"
```
There is no `method: "close"` — using one will error.
**Comment:**
```
issue_write method: "add_comment" owner: <owner> repo: <repo> issue_number: <N> body: <text>
```
**Apply resolved label IDs directly** (bypassing `references/enrichments.md`'s inference step, e.g.
when the caller already named exact labels):
```
issue_write method: "add_labels" owner: <owner> repo: <repo> issue_number: <N> labels: [<IDs>]
```
To replace all labels atomically instead of adding: `method: "replace_labels"`.
To remove one: `method: "remove_label" label_id: <single ID>`.
## Token scope
All of `list_issues`, `issue_read`, and `issue_write` are verified working under a token holding
`write:issue` + `write:repository`.

39
plugins/gitea/skills/gitea-issues/references/search.md Normal file
View File

@@ -0,0 +1,39 @@
---
topic: search
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# `search_issues`
Call signature verified live against the deployed `gitea-mcp` server via `ToolSearch` at authoring
time (see `references/sources.md`) — confirmed to match `api-reference.md`.
**Parameters:**
- `query` (string, required) — the only hard-required parameter
- `state` (string, enum `"open"` | `"closed"` | `"all"`, optional)
- `type` (string, enum `"issues"` | `"pulls"`, optional) — **this tool has a working type filter**,
unlike `list_issues` (see `references/issues.md`)
- `labels` (string, optional) — comma-separated label **names** — a plain string, not the array form
`list_issues` uses
- `owner` (string, optional) — restrict results to one owner
- `page` (number, optional, default `1`)
- `per_page` (number, optional, default `30`)
**Call:**
```
search_issues query: <text>
```
**Narrowing the search:**
```
search_issues query: <text> owner: <owner> state: "open" type: "pulls" labels: "bug,urgent"
```
This is a cross-repository search (unlike `list_issues`, which is scoped to one `owner`/`repo`) —
useful when the caller doesn't know which repo an issue lives in, or wants results across an
organization. Pass `owner` to narrow scope if the caller does know it.
Paginate the same way as `list_issues`: iterate `page` until the returned count is less than
`per_page`.

41
plugins/gitea/skills/gitea-issues/references/sources.md Normal file
View File

@@ -0,0 +1,41 @@
# Sources
**Note on call signatures:** per `docs/adr/0011-gitea-skill-deep-modules.md`, the tool parameter
signatures in `references/issues.md` and `references/search.md` were re-verified live via
`ToolSearch` against the deployed `gitea-mcp` server at authoring time — they are not copied
verbatim from `api-reference.md`. This resolves issue #6 comment #849's root-cause finding that a
prior skill was authored from API docs that had drifted from the actual MCP tool schema; the live
check caught exactly this drift on `list_issues` (see SKILL.md Gotchas — the research doc documents
a `type` and a `milestones` parameter that do not exist on the deployed server).
## gitea-mcp-repo
- **URL:** https://gitea.com/gitea/gitea-mcp
- **Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/issues.md, references/search.md, references/enrichments.md
- **Status:** `extracted`
## gitea-mcp-slim-go
- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/issue/slim.go
- **Description:** Slim response shape structs from gitea-mcp source; defines exactly which fields the MCP server returns for issues (label name-vs-ID slimming, milestone object-vs-string shape, `is_pull` presence on single-item reads only).
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/issues.md
- **Status:** `extracted`
## context7-websites-gitea
- **URL:** context7:/websites/gitea
- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — backs the automatic cross-reference rendering (`#N`/`!N`) that validates the "Depends on #N" dependency-linking convention.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** references/enrichments.md
- **Status:** `extracted`
## context7-gitea-tea-cli
- **URL:** context7:/git_gitea_com/gitea_tea
- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner command patterns for issues, PRs, and releases. Consulted alongside context7-websites-gitea while researching `workflow-conventions.md`'s cross-reference-linking section (both sources contribute to that research doc); its issue-specific command patterns did not end up informing any gitea-issues content beyond what context7-websites-gitea already backs.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** (none)
- **Status:** `extracted`

25
plugins/gitea/skills/gitea-labels-milestones/README.md Normal file
View File

@@ -0,0 +1,25 @@
# gitea-labels-milestones
Read and write Gitea labels and milestones, and resolve label/milestone identity for the skills that apply them to issues and PRs.
## What it does
This skill handles label and milestone CRUD (`label_read`/`label_write`, `milestone_read`/`milestone_write`) — listing repo or org labels, creating/editing/deleting a label, resolving a label name to the numeric ID required for any write, and listing/creating/updating/closing/deleting a milestone. It also owns label inference: mapping conversation context (bug report, feature request, urgency language) to this repo's `Kind/*`/`Priority/*`/`Status/*` taxonomy. It is a cross-cutting shared skill composed by `gitea-issues` and `gitea-prs`, which call into it for label/milestone resolution before their own `issue_write`/`pull_request_write` calls apply the resolved IDs.
## Usage
```
/gitea-labels-milestones
```
Describe the label or milestone task: list labels, resolve a name to an ID, create/edit/delete a label, or list/create/update/close/delete a milestone. For applying already-resolved labels or a milestone to a specific issue or PR, use `gitea-issues` or `gitea-prs` instead.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — dispatch table and Gotchas |
| `references/labels.md` | Execution detail for `label_read`/`label_write` |
| `references/milestones.md` | Execution detail for `milestone_read`/`milestone_write` |
| `references/label-inference.md` | Context-pattern → `Kind/*`/`Priority/*`/`Status/*` label inference guide |
| `references/sources.md` | Research sources backing the label/milestone guidance |

68
plugins/gitea/skills/gitea-labels-milestones/SKILL.md Normal file
View File

@@ -0,0 +1,68 @@
---
name: gitea-labels-milestones
description: >
Use when reading or writing Gitea labels or milestones — listing repo/org labels, creating,
editing, or deleting a label, resolving label names to the numeric IDs required for applying
them to an issue or PR, or listing, creating, updating, closing, or deleting a milestone. This is
a cross-cutting shared skill: `gitea-issues` and `gitea-prs` both compose it whenever they need to
apply labels or assign a milestone, rather than duplicating label/milestone logic. Also use for
label inference — mapping a bug report, feature request, or urgency signal in conversation
context to the repo's `Kind/*`/`Priority/*`/`Status/*` label taxonomy. Do not use for applying
already-resolved label IDs or milestone IDs to a specific issue or PR — that write goes through
`issue_write`/`pull_request_write` in `gitea-issues`/`gitea-prs`, not here.
compatibility: Requires Gitea MCP server configured with write:issue and write:repository token scopes.
metadata:
category: integration
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
- context7-websites-gitea
- context7-gitea-tea-cli
version: "0.1.1"
allowed-tools: Bash mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write
---
## Gotchas
- **Label writes take IDs, reads return names.** `label_read` is the only tool that returns full label objects (`id`, `name`, `color`, `description`). Issue/PR responses slim labels down to name strings. Before any label is applied to an issue or PR (in `gitea-issues`/`gitea-prs`), resolve names → IDs here via `label_read method: "list_repo_labels"` — never pass a name string where an ID is expected.
- **Milestones are referenced by ID everywhere, never by title.** `milestone_write` update/delete take `id`. The one place titles show up as the sole handle is the `pull_request_read` response (see next gotcha).
- **Milestone representation differs between issues and PRs.** `issue_read` returns `milestone: {id, title}` — an object. `pull_request_read` returns `milestone: "title string"` — title only, no ID. You cannot recover a milestone ID from a PR response directly; call `milestone_read method: "list"` and match by title instead.
- **Repo labels and org labels are separate pools, never mixed in one call.** `label_read`/`label_write` take either `owner`+`repo` (repo-scoped methods) or `org` (org-scoped methods) — passing both or neither for a given method is a caller error, not something the schema enforces for you. Repo and org labels can both apply to the same issue, but you list/create/edit them through different method values.
- **`milestone_write` accepts `"update"` and `"edit"` as the same operation.** Both method values map to the identical update call. Prefer `"update"` for consistency with `issue_write`/`pull_request_write`.
- **`exclusive` is documented as an org-labels-only flag — it isn't what enforces exclusivity here.** Gitea's docs scope the settable/server-enforced `exclusive` flag to org labels only, and the live `label_write` schema for `create_repo_label`/`edit_repo_label` doesn't document accepting it at all. This repo's `Kind/*`, `Priority/*`, `Status/*` groups still behave as one-label-per-scope, but that's a manually-enforced convention this skill implements client-side, not a guaranteed server behavior for repo labels: applying a new label within a scope (e.g. `Priority/High`) must replace any existing label in that same scope, not add alongside it, and nothing on the server enforces that for you. Label inference (see `references/label-inference.md`) must respect this — replace, don't stack.
- **Pagination is manual on every list call.** `label_read` and `milestone_read` both default to `per_page: 30`. Iterate `page: 1, 2, ...` until the result count is less than `per_page` — there is no cursor or auto-pagination.
- **Schema requiredness differs between the two tool families.** `milestone_read`/`milestone_write` have `owner` and `repo` as hard-required parameters (the call fails validation without them). `label_read`/`label_write` only hard-require `method` — `owner`/`repo`/`org` are functionally required per method but not schema-enforced, so passing none produces a runtime error from Gitea, not a client-side validation error.
## Step 1 — Resolve owner and repo
Before any tool call, extract `owner` and `repo` from the git remote (skip this if an orchestrating caller already passed them in):
```bash
git remote get-url origin
```
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
## Step 2 — Dispatch
| Task | Tool | method |
|---|---|---|
| List repo labels | `label_read` | `"list_repo_labels"` |
| Get one repo label by ID | `label_read` | `"get_repo_label"` |
| List org labels | `label_read` | `"list_org_labels"` |
| Create a repo/org label | `label_write` | `"create_repo_label"` / `"create_org_label"` |
| Edit a repo/org label | `label_write` | `"edit_repo_label"` / `"edit_org_label"` |
| Delete a repo/org label | `label_write` | `"delete_repo_label"` / `"delete_org_label"` |
| List milestones | `milestone_read` | `"list"` |
| Get one milestone by ID | `milestone_read` | `"get"` |
| Create a milestone | `milestone_write` | `"create"` |
| Update / close a milestone | `milestone_write` | `"update"` |
| Delete a milestone | `milestone_write` | `"delete"` |
For full parameter detail and step-by-step call sequences, read `references/labels.md` (label operations) or `references/milestones.md` (milestone operations). For mapping conversation context to a label to apply, read `references/label-inference.md`.
Applying resolved label IDs or a milestone ID to a specific issue or PR is out of scope here — that's `issue_write`/`pull_request_write` in the composing skill (`gitea-issues`/`gitea-prs`).

68
plugins/gitea/skills/gitea-labels-milestones/references/label-inference.md Normal file
View File

@@ -0,0 +1,68 @@
---
topic: label-inference
source_keys:
- context7-websites-gitea
- gitea-mcp-repo
---
# Label inference guide
Maps context-pattern signals from conversation content (an issue being drafted, a bug report, a PR
description) to this repo's `Kind/*` / `Priority/*` / `Status/*` label taxonomy. Used by
`gitea-issues` and `gitea-prs` before creating or updating an issue/PR, and directly when the user
asks to label something without naming exact labels.
## Scoped labels are mutually exclusive — replace, don't stack
Each of `Kind/*`, `Priority/*`, `Status/*` is treated as a scoped-label group by convention (the `/`
delimiter naming pattern). Gitea's `exclusive` flag — the mechanism that would let the server itself
enforce one-label-per-scope — is documented as an org-labels-only setting, and the repo-level
`label_write` methods used here don't accept it at all. So exclusivity within these scopes is a
convention this skill enforces client-side, not something the server guarantees: applying a new
label within a scope is expected to replace any existing label in that same scope on the target
issue/PR, not add alongside it. When inference
selects a `Priority/High` label and the issue already carries `Priority/Medium`, the write should
result in only `Priority/High` remaining — use `replace_labels` scoped to that group's labels, or at
minimum remove the superseded label before adding the new one. Never leave two labels from the same
scope applied at once.
## Signal → label mapping
**`Kind/*`** (what kind of work this is):
| Signal in context | Label |
|---|---|
| Bug report, error, crash, unexpected behavior, "broken", "doesn't work" | `Kind/Bug` |
| New capability, "add support for", net-new functionality | `Kind/Feature` |
| Improvement to existing behavior, "make X better", refactor with behavior change | `Kind/Enhancement` |
| Docs-only change, README/comment/guide updates | `Kind/Documentation` |
| Vulnerability, credential exposure, injection risk, auth bypass | `Kind/Security` |
**`Priority/*`** (urgency):
| Signal in context | Label |
|---|---|
| "blocking", "critical", "urgent", production-down | `Priority/Critical` |
| "soon", "high priority", "should do this sprint" | `Priority/High` |
| No urgency signal present | `Priority/Medium` (default) |
**`Status/*`** (workflow state):
| Signal in context | Label |
|---|---|
| Explicit statement that the work is blocked on something else | `Status/Blocked` |
## Procedure
1. Read the conversation context (issue/PR title, body, or the triggering discussion) for the
signals above.
2. Call `label_read method: "list_repo_labels"` (see `references/labels.md`) to get the current
label set with IDs — inference must never guess an ID, only a name, then resolve it.
3. Match inferred label names against the resolved list (case-insensitive). If a scope group
already has a different label applied on the target and a new one is inferred for that same
scope, plan to replace rather than add (see above).
4. **Low-confidence inference omits the label.** If no signal confidently maps to a `Kind/*` value,
do not guess — omit `Kind/*` entirely rather than default to one. `Priority/Medium` is the one
exception: it's the explicit default when no urgency signal is present, not a guess.
5. Hand the resolved IDs (plus which scopes to replace) to the caller's `issue_write`/
`pull_request_write` call — this skill does not apply labels to an issue or PR itself.

97
plugins/gitea/skills/gitea-labels-milestones/references/labels.md Normal file
View File

@@ -0,0 +1,97 @@
---
topic: labels
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# Label operations
Execution detail for `label_read` and `label_write`. Both tools operate on either **repo-scoped**
or **org-scoped** labels — never both in one call. Pick the method family (`*_repo_label*` vs.
`*_org_label*`) that matches the target, and pass `owner`+`repo` or `org` accordingly.
## Verified live schemas
`label_read` — required: `method`.
| Param | Type | Notes |
|---|---|---|
| `method` | string (enum) | `"list_repo_labels"` \| `"get_repo_label"` \| `"list_org_labels"` |
| `owner` | string | for repo methods |
| `repo` | string | for repo methods |
| `org` | string | for org methods |
| `id` | number | label ID, required for `"get_repo_label"` |
| `page` | number | default `1` |
| `per_page` | number | default `30` |
`label_write` — required: `method`.
| Param | Type | Notes |
|---|---|---|
| `method` | string (enum) | `"create_repo_label"` \| `"edit_repo_label"` \| `"delete_repo_label"` \| `"create_org_label"` \| `"edit_org_label"` \| `"delete_org_label"` |
| `owner` | string | for repo methods |
| `repo` | string | for repo methods |
| `org` | string | for org methods |
| `id` | number | for edit/delete |
| `name` | string | required for create |
| `color` | string | hex `#RRGGBB`, required for create |
| `description` | string | optional |
| `exclusive` | boolean | org labels only |
| `is_archived` | boolean | repo labels only |
Note: unlike `milestone_read`/`milestone_write`, `owner`/`repo`/`org` are **not** schema-required on
either label tool — only `method` is. Passing none for a repo/org method still fails, just as a
runtime error from Gitea rather than a client-side validation error.
## List repo labels
```
label_read method: "list_repo_labels" owner: <owner> repo: <repo> per_page: 50
```
Paginate (`page: 1, 2, ...`) until the returned count is less than `per_page`. This is the only way
to build a complete name → ID map — there is no lookup-by-name endpoint.
## Get one label
```
label_read method: "get_repo_label" owner: <owner> repo: <repo> id: <id>
```
## Resolve a name to an ID
There is no direct name lookup. List all repo labels (paginating if needed), scan for a
case-insensitive name match, and extract `id`. This is the required first step before any label
application on an issue or PR — the actual `add_labels`/`replace_labels`/`remove_label` call lives
in `gitea-issues`/`gitea-prs` via `issue_write`/`pull_request_write`, which take numeric IDs only.
## Create a label
```
label_write method: "create_repo_label"
owner: <owner> repo: <repo>
name: "Kind/Bug"
color: "#d73a4a"
description: "Confirmed bug"
```
For an org label, use `method: "create_org_label"` with `org:` instead of `owner`/`repo`, and
`exclusive: true` if the label belongs to a mutually-exclusive scope group.
## Edit a label
```
label_write method: "edit_repo_label" owner: <owner> repo: <repo> id: <id> color: "#ff0000"
```
Only pass the fields being changed — `id` plus any of `name`/`color`/`description`/`is_archived`.
## Delete a label
```
label_write method: "delete_repo_label" owner: <owner> repo: <repo> id: <id>
```
Deleting a label does not remove it from historical issue/PR timeline events — it disappears only
from current label lists.

98
plugins/gitea/skills/gitea-labels-milestones/references/milestones.md Normal file
View File

@@ -0,0 +1,98 @@
---
topic: milestones
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# Milestone operations
Execution detail for `milestone_read` and `milestone_write`. Milestones are always repo-scoped —
there is no org-level milestone concept, unlike labels.
## Verified live schemas
`milestone_read` — required: `method`, `owner`, `repo`.
| Param | Type | Notes |
|---|---|---|
| `method` | string (enum) | `"get"` \| `"list"` |
| `owner` | string | required |
| `repo` | string | required |
| `id` | number | milestone ID, required for `"get"` |
| `name` | string | title filter, for `"list"` |
| `state` | string | default `"all"` — conventional values `"open"`/`"closed"`/`"all"`, but **not enforced by an enum in the live schema** (plain string). Any other value is passed through to Gitea rather than rejected client-side. |
| `page` | number | default `1` |
| `per_page` | number | default `30` |
`milestone_write` — required: `method`, `owner`, `repo`.
| Param | Type | Notes |
|---|---|---|
| `method` | string (enum) | `"create"` \| `"update"` \| `"edit"` \| `"delete"` — `"update"`/`"edit"` are aliases for the same operation; prefer `"update"` |
| `owner` | string | required |
| `repo` | string | required |
| `id` | number | required for update/delete |
| `title` | string | required for create |
| `description` | string | optional |
| `due_on` | string | due date — the live tool schema only describes this as an opaque "due date" string with no enforced format; ISO 8601 (e.g. `"2025-03-01T00:00:00Z"`) is the conventional value Gitea's REST API accepts, not something confirmed by the live MCP schema itself |
| `state` | string (enum) | `"open"` \| `"closed"` — **this one is schema-enforced**, unlike `milestone_read`'s `state` |
Note: unlike `label_read`/`label_write`, both milestone tools hard-require `owner` and `repo` at the
schema level — there's no scope variant to omit them for.
## List milestones
```
milestone_read method: "list" owner: <owner> repo: <repo> state: "open"
```
Report each as: id, title, state, due date, open/closed issue counts.
## Get one milestone
```
milestone_read method: "get" owner: <owner> repo: <repo> id: <id>
```
## Resolve a milestone ID from a title
Needed whenever the only handle available is a title — e.g. a `pull_request_read` response, which
returns `milestone` as a bare title string rather than `{id, title}`. Call:
```
milestone_read method: "list" owner: <owner> repo: <repo> name: <title>
```
and take the `id` of the matching result. If `name` filtering returns no match (e.g. due to a
title typo or case mismatch), fall back to listing without the filter and matching manually.
## Create a milestone
```
milestone_write method: "create"
owner: <owner> repo: <repo>
title: "v1.0"
description: "First stable release"
due_on: "2025-03-01T00:00:00Z"
```
Report the returned ID — the caller (`gitea-issues`/`gitea-prs`) needs it to assign issues/PRs to
this milestone via `issue_write`/`pull_request_write`.
## Update or close a milestone
```
milestone_write method: "update" owner: <owner> repo: <repo> id: <id> state: "closed"
```
Only pass the fields being changed — `id` plus any of `title`/`description`/`due_on`/`state`.
## Delete a milestone
```
milestone_write method: "delete" owner: <owner> repo: <repo> id: <id>
```
Deleting a milestone does not delete or unassign the issues/PRs that referenced it — they simply
lose the milestone reference.

33
plugins/gitea/skills/gitea-labels-milestones/references/sources.md Normal file
View File

@@ -0,0 +1,33 @@
# Sources
## gitea-mcp-repo
- **URL:** https://gitea.com/gitea/gitea-mcp
- **Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/labels.md, references/milestones.md, references/label-inference.md
- **Status:** `extracted`
## gitea-mcp-slim-go
- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/issue/slim.go, https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/pull/slim.go, https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/repo/slim.go
- **Description:** Slim response shape structs from gitea-mcp source; defines exactly which fields the MCP server returns for issues, PRs, branches, commits, tags, releases, and files — including the label name-vs-ID and milestone object-vs-string representation quirks this skill's Gotchas document
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/labels.md, references/milestones.md
- **Status:** `extracted`
## context7-websites-gitea
- **URL:** context7:/websites/gitea
- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — scoped/exclusive label conventions and milestone/label state-transition semantics
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/label-inference.md
- **Status:** `extracted`
## context7-gitea-tea-cli
- **URL:** context7:/git_gitea_com/gitea_tea
- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner command patterns for labels and milestones
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md
- **Status:** `extracted`

25
plugins/gitea/skills/gitea-prs/README.md Normal file
View File

@@ -0,0 +1,25 @@
# gitea-prs
List, read, create, update, merge, and review Gitea pull requests.
## What it does
This skill handles the pull request lifecycle within the Gitea integration suite — listing and reading PRs (details, diff, changed files, CI status, reviews), creating and updating them (title, body, reviewers, labels, milestone), closing/reopening, merging with a chosen strategy and post-merge branch cleanup, and the full code-review flow (create a review with inline comments, submit it, dismiss or delete it). It composes `gitea-labels-milestones` for label/milestone ID resolution rather than duplicating that logic, and defers to `gitea-issues` for anything that turns out to be an issue rather than a PR (they share one number space) and to `gitea-branches`/`gitea-files` for the underlying branch/file operations behind a PR.
## Usage
```
/gitea-prs
```
Describe the PR or review task: list PRs, get a PR's status/diff/reviews, create or update a PR, merge one, or create/submit/dismiss a code review. The skill will determine owner/repo from context and resolve any label or milestone names via `gitea-labels-milestones` before writing them.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — Gotchas, composition with `gitea-labels-milestones`, and the dispatch table |
| `references/pull-requests.md` | Execution detail for `list_pull_requests`, `pull_request_read` (get/get_diff/get_files/get_status), and `pull_request_write` (create/update/close/reopen/update_branch/add_reviewers/remove_reviewers) |
| `references/reviews.md` | Execution detail for `pull_request_review_write` (create/submit/delete/dismiss) and the review-related `pull_request_read` methods |
| `references/merging.md` | The merge workflow — CI vs. review/branch-protection gates, merge styles, branch cleanup, and the post-merge issue-close check |
| `references/sources.md` | Research sources backing the PR/review guidance |

68
plugins/gitea/skills/gitea-prs/SKILL.md Normal file
View File

@@ -0,0 +1,68 @@
---
name: gitea-prs
description: >
Use when listing, reading, creating, updating, merging, or reviewing Gitea pull requests —
getting PR status/diff/changed files/CI status, opening a PR, updating title/body/reviewers,
closing/reopening, merging with a chosen strategy, or submitting/dismissing a code review with
inline comments. Composes `gitea-labels-milestones` to resolve label names or milestone titles
to the numeric IDs `pull_request_write` requires, rather than duplicating that resolution logic.
Do not use for issues (`gitea-issues`) or branch/commit operations (`gitea-branches`) — a number
the user mentions may refer to either an issue or a PR since they share one number space, so
confirm which domain applies before dispatching.
compatibility: Requires Gitea MCP server configured with write:issue and write:repository token scopes.
metadata:
category: integration
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
- context7-websites-gitea
- context7-gitea-tea-cli
version: "0.1.1"
allowed-tools: mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp__gitea__pull_request_write mcp__gitea__pull_request_review_write
---
## Gotchas
- **Issues and PRs share one number space.** A number the user mentions (`#42`) might be an issue, not a PR — there is only one counter per repo. If you're not certain, call `pull_request_read method: "get"` and treat a 404 as "this number is an issue, not a PR" (or check `is_pull` on an `issue_read` response first if you already have one).
- **`pull_request_read method: "get"` returns `review_scomments`, not `review_comments`.** Source-level typo in gitea-mcp v1.3.0. Never reference `review_comments` — it will always be undefined.
- **`draft: true` on create prepends `"WIP:"` to the title.** Gitea has no first-class draft field — it implements draft PRs via title prefix. To un-draft, call `update` and pass the title without the `WIP:` prefix.
- **Cross-repo fork PRs require `head` as `"fork-owner:branch-name"`.** A bare branch name causes Gitea to search the base repo for it and return 422. Same-repo PRs use a bare branch name.
- **PR `milestone` is a bare title string, not `{id, title}`.** Unlike issues, you cannot recover a milestone's ID from a PR response. If you need the ID (e.g. to filter or to pass to another write), call into `gitea-labels-milestones` and match by title via `milestone_read method: "list"`.
- **CI status and review/approval state are independent merge gates.** `get_status` only reports CI. Branch-protection rules (required approvals, requested-reviewer coverage, stale-approval handling) are enforced server-side by the merge call itself and will error if unmet — passing CI does not mean the merge will succeed.
- **Reviews move through a state machine, not a single write.** `create` opens a review in `PENDING` state with inline comments attached; `submit` finalizes it with a terminal `state` (`APPROVED`/`REQUEST_CHANGES`/`COMMENT`). A submitted review can be `dismiss`ed afterward, but never deleted — `delete` only removes a review that was never submitted.
- **Merging a PR does not auto-close linked issues.** Unlike GitHub, Gitea has no merge-triggers-close event. It does parse closing keywords (`Fixes #N`, `Closes #N`) in commit messages landing on the default branch, so a non-squash merge that preserves those commit messages may auto-close the issue — but a squash merge rewrites history into one commit, so survival of the keyword depends on the squash commit's message. Always call `issue_read method: "get"` on any referenced issue after merging to check whether it already closed before deciding to close it explicitly.
## Composing `gitea-labels-milestones`
Before any `pull_request_write` call that includes a `labels` or `milestone` parameter, resolve names/titles to numeric IDs via `gitea-labels-milestones` — `label_read method: "list_repo_labels"` for label name → ID, `milestone_read method: "list"` for milestone title → ID. Never pass a label name string or milestone title string directly to `pull_request_write`; both parameters take numeric IDs only. This skill does not duplicate that lookup logic — it composes the shared skill.
## Dispatch
| Task | Tool | method |
|---|---|---|
| List PRs | `list_pull_requests` | — |
| Get PR details | `pull_request_read` | `"get"` |
| Get PR diff | `pull_request_read` | `"get_diff"` |
| Get PR changed files | `pull_request_read` | `"get_files"` |
| Get PR CI status | `pull_request_read` | `"get_status"` |
| Get PR reviews | `pull_request_read` | `"get_reviews"` |
| Get one review | `pull_request_read` | `"get_review"` |
| Get review inline comments | `pull_request_read` | `"get_review_comments"` |
| Create a PR | `pull_request_write` | `"create"` |
| Update a PR | `pull_request_write` | `"update"` |
| Close a PR | `pull_request_write` | `"close"` |
| Reopen a PR | `pull_request_write` | `"reopen"` |
| Merge a PR | `pull_request_write` | `"merge"` |
| Update branch from base | `pull_request_write` | `"update_branch"` |
| Add reviewers | `pull_request_write` | `"add_reviewers"` |
| Remove reviewers | `pull_request_write` | `"remove_reviewers"` |
| Create a review | `pull_request_review_write` | `"create"` |
| Submit a review | `pull_request_review_write` | `"submit"` |
| Delete a review | `pull_request_review_write` | `"delete"` |
| Dismiss a review | `pull_request_review_write` | `"dismiss"` |
For full parameter detail on listing/reading/creating/updating/closing PRs, read `references/pull-requests.md`. For review-specific detail (create/submit/delete/dismiss, inline comment shape), read `references/reviews.md`. For the merge workflow specifically (CI gate, merge styles, branch cleanup, post-merge issue check), read `references/merging.md`.

41
plugins/gitea/skills/gitea-prs/references/merging.md Normal file
View File

@@ -0,0 +1,41 @@
---
topic: merging
source_keys:
- gitea-mcp-repo
- context7-websites-gitea
- context7-gitea-tea-cli
---
# Merge workflow
## Two independent gates
Before merging, two things can each independently block the merge, and only one of them is visible from `get_status`:
1. **CI status** — `pull_request_read method: "get_status"` returns the combined commit status for the PR's head commit. This reflects CI/build checks only.
2. **Review and branch-protection state** — required approval counts, an allowlist of required approvers/teams, whether requested reviewers have reviewed, and stale-approval handling (an approval given before new commits were pushed may be auto-dismissed or ignored, depending on repo settings). None of this is exposed via `get_status` — it is enforced server-side by the merge call itself, and repository admins are not exempt from it by default (an explicit "administrators must follow branch protection" setting is what removes that bypass).
A green `get_status` does not mean the merge will succeed. Treat both gates as independently checkable, and expect `pull_request_write method: "merge"` to return an error if branch-protection requirements aren't met even when CI is passing.
## `pull_request_write method: "merge"`
**Parameters** (in addition to `owner`, `repo`, `pull_number` — see `references/pull-requests.md` for the full parameter list):
- `merge_style` (string, optional, default `"merge"`) — `"merge"` | `"rebase"` | `"rebase-merge"` | `"squash"` | `"fast-forward-only"`
- `title` (string, optional) — override the merge/squash commit's title
- `message` (string, optional) — merge commit message (for squash, this becomes the squash commit's message — see the auto-close gotcha below)
- `delete_branch` (boolean, optional) — delete the head branch after a successful merge
- `force_merge` (boolean, optional) — merge even if checks are failing; use only when the user explicitly asks to override a failing CI status
- `merge_when_checks_succeed` (boolean, optional) — queue the merge to happen automatically once checks pass, instead of merging immediately
- `head_commit_id` (string, optional) — expected head SHA; supplying it lets the server detect if the branch moved since you last read it (conflict detection) rather than merging a stale diff
## Recommended sequence
1. Call `pull_request_read method: "get_status"` first. Report CI status to the user. Do not block the merge attempt solely because CI is failing unless the user asks you to stop — but do surface it before proceeding.
2. Call `pull_request_write method: "merge"` with the chosen `merge_style` (ask the user if unspecified; do not default to squash silently, since squash has the closing-keyword implication below) and `delete_branch: true` unless told otherwise.
3. If branch-protection requirements block the merge, the call itself will return the error — report it verbatim rather than retrying with `force_merge` unless the user explicitly asks to override.
## Merging does not auto-close linked issues
Gitea has no GitHub-style "merge triggers close" event. It does parse closing keywords (`Fixes #N`, `Closes #N`) in commit messages that land on the default branch — so a regular (non-squash) merge, which preserves each original commit message, can auto-close an issue this way if one of those commits used a closing keyword. A squash merge rewrites history into a single commit, so whether the keyword survives depends entirely on what `message` (or the default squash message) ends up being.
After any merge, call `issue_read method: "get"` (in `gitea-issues`) on any issue the PR references before deciding whether to close it explicitly. Closing an already-closed issue is a harmless no-op, but don't assume a manual close is always needed, and don't assume it never is.

75
plugins/gitea/skills/gitea-prs/references/pull-requests.md Normal file
View File

@@ -0,0 +1,75 @@
---
topic: pull-requests
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# Pull request read/write execution detail
Parameter signatures below are cross-checked live against the deployed gitea-mcp server tool schemas at authoring time — not copied verbatim from the plugin's research doc for this domain, which has a known history of drifting from the deployed server (e.g. a prior `type` parameter that no longer exists on `list_issues`, and the `review_scomments` typo covered in `references/reviews.md`). Re-verify via `ToolSearch` before trusting this file if the gitea-mcp version changes.
## `list_pull_requests`
**Parameters:**
- `owner` (string, required)
- `repo` (string, required)
- `state` (string, optional, default `"all"`) — `"open"` | `"closed"` | `"all"`
- `sort` (string, optional, default `"recentupdate"`) — `"oldest"` | `"recentupdate"` | `"leastupdate"` | `"mostcomment"` | `"leastcomment"` | `"priority"`
- `milestone` (number, optional) — milestone ID filter, not a title
- `page` (number, optional, default 1)
- `per_page` (number, optional, default 30)
List responses trim PRs down to summary fields — `head`/`base` are bare ref strings and `milestone` does not appear as an object. Don't rely on this call to resolve a milestone's ID; see the Gotcha below.
## `pull_request_read`
**Parameters:**
- `method` (string, required) — `"get"` | `"get_diff"` | `"get_files"` | `"get_status"` | `"get_reviews"` | `"get_review"` | `"get_review_comments"`
- `owner` (string, required)
- `repo` (string, required)
- `pull_number` (number, required)
- `review_id` (number, optional) — required for `"get_review"` and `"get_review_comments"`; see `references/reviews.md`
- `binary` (boolean, optional) — include binary diff content for `"get_diff"`
- `page` (number, optional, default 1)
- `per_page` (number, optional, default 30)
`"get"`, `"get_diff"`, `"get_files"`, and `"get_status"` are covered here. `"get_reviews"`, `"get_review"`, and `"get_review_comments"` are covered in `references/reviews.md`.
- `"get"` returns the full PR object: state, draft, merged, mergeable flags; `head`/`base` as full objects (`{ref, sha, repo?}`); `milestone` as a bare title string (not `{id, title}`); `review_scomments` (typo, see `references/reviews.md`).
- `"get_diff"` returns raw diff text.
- `"get_files"` returns the list of changed file objects.
- `"get_status"` returns the combined commit status for the PR's head commit — CI result only, not review/approval state (see `references/merging.md`).
**Milestone gotcha:** because `pull_request_read` only ever returns a milestone title, never an ID, resolving "which milestone ID does this PR belong to" requires calling into `gitea-labels-milestones`' `milestone_read method: "list"` and matching by title. Do not attempt to infer or guess the ID.
## `pull_request_write`
**Parameters:**
- `method` (string, required) — `"create"` | `"update"` | `"close"` | `"reopen"` | `"merge"` | `"update_branch"` | `"add_reviewers"` | `"remove_reviewers"`
- `owner` (string, required)
- `repo` (string, required)
- `pull_number` (number, required for every method except `"create"` — this is enforced by convention, not by the tool's schema, so passing it incorrectly produces a runtime error rather than a client-side validation error)
- `title` (string, required for `"create"`; optional for `"update"`)
- `body` (string, required for `"create"`; optional for `"update"`)
- `head` (string, required for `"create"`) — source branch; same-repo PRs use a bare branch name, cross-repo fork PRs use `"fork-owner:branch-name"` (see Gotcha)
- `base` (string, required for `"create"`) — target branch
- `assignee` (string, optional) — single login
- `assignees` (array of strings, optional) — login names
- `milestone` (number, optional) — milestone ID, never a title; settable on both `"create"` and `"update"`
- `state` (string, optional, for `"update"`) — `"open"` | `"closed"` (no `"all"` — unlike issue state filters)
- `allow_maintainer_edit` (boolean, optional, for `"update"`)
- `labels` (array of numbers, optional) — label IDs, never names — resolve via `gitea-labels-milestones` first
- `deadline` (string, optional) — ISO 8601
- `remove_deadline` (boolean, optional)
- `reviewers` (array of strings, optional) — login names; settable directly on `"create"`, or use `"add_reviewers"`/`"remove_reviewers"` to adjust reviewers on an already-open PR
- `team_reviewers` (array of strings, optional) — same as `reviewers`: settable on `"create"`, or via `"add_reviewers"`/`"remove_reviewers"` post-creation
- `draft` (boolean, optional, for `"create"`) — prepends `"WIP:"` to the title (see Gotcha)
Merge-specific parameters (`merge_style`, `delete_branch`, `force_merge`, `merge_when_checks_succeed`, `head_commit_id`, `message` as merge commit message) are covered in `references/merging.md`.
**Cross-repo head format:** `head` must be `"fork-owner:branch-name"` for a PR originating from a fork of the base repo. Passing a bare branch name causes Gitea to search for that branch in the base repo instead, and returns 422 when it isn't found there.
**Draft/WIP behavior:** `draft: true` on `"create"` is implemented by prepending `"WIP:"` to the title — there is no first-class draft boolean stored separately from the title. The title returned by subsequent reads will include the prefix. To un-draft, call `"update"` with `title` set to the same text minus the `"WIP:"` prefix; there is no dedicated undraft method.
**`update_branch`:** takes only `owner`, `repo`, `pull_number` — no other parameters. It merges the current base branch into the PR's head branch server-side, resolving a PR that Gitea reports as behind its base (analogous to GitHub's "Update branch" button). Use it when a PR shows `mergeable: false` or an out-of-date status due to base-branch drift rather than an actual conflict; if the head and base have truly diverged with conflicting changes, this call fails and the conflict must be resolved by pushing a merge/rebase to the head branch directly, outside this skill's scope.

43
plugins/gitea/skills/gitea-prs/references/reviews.md Normal file
View File

@@ -0,0 +1,43 @@
---
topic: reviews
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# PR review execution detail
Parameter signatures below are cross-checked live against the deployed gitea-mcp server tool schema, not copied from the plugin's research doc verbatim — same sourcing discipline as `references/pull-requests.md`.
## Review state machine
A review is not a single write. It moves through states:
1. **`create`** — opens a review in `"PENDING"` state, optionally attaching inline comments. Nothing is visible to other users yet.
2. **`submit`** — finalizes the pending review with a terminal `state`: `"APPROVED"`, `"REQUEST_CHANGES"`, or `"COMMENT"`. This is the point at which the review becomes visible and counts toward merge-gate requirements (see `references/merging.md`).
3. **`dismiss`** — invalidates an already-submitted review (e.g. an approval that's no longer valid after force-push), with an optional `message` giving the reason. Dismissal does not delete the review record — it stays visible but marked dismissed.
4. **`delete`** — removes a review outright. Use only for a review that was never submitted (e.g. abandoning a `PENDING` draft); do not use `delete` to retract a submitted review — use `dismiss` instead.
## `pull_request_review_write`
**Parameters:**
- `method` (string, required) — `"create"` | `"submit"` | `"delete"` | `"dismiss"`
- `owner` (string, required)
- `repo` (string, required)
- `pull_number` (number, required)
- `review_id` (number, required for every method except `"create"`, which returns the ID to use for the follow-up `submit`/`delete`/`dismiss` call)
- `state` (string, optional) — `"APPROVED"` | `"REQUEST_CHANGES"` | `"COMMENT"` | `"PENDING"` — set on `"create"` (typically `"PENDING"`, or a terminal state to create-and-submit in one call if the server supports it) or `"submit"` (terminal state)
- `body` (string, optional) — overall review comment text
- `commit_id` (string, optional, for `"create"`) — anchors inline comments to a specific commit SHA (typically the PR's current head SHA from `pull_request_read method: "get"`)
- `message` (string, optional, for `"dismiss"`) — dismissal reason
- `comments` (array of objects, optional, for `"create"`) — inline comments, each: `{path, body, old_line_num, new_line_num}` — `path` is the file path, `body` is the comment text, `new_line_num` anchors to a line in the new (added) side of the diff, `old_line_num` anchors to a line in the old (removed) side; use whichever side the comment applies to, not both
## Reading reviews (`pull_request_read`)
- `method: "get_reviews"` — array of review summaries: `id`, `state`, `body`, `user` (login), `comments_count`, `submitted_at`, `html_url`, `stale` (bool — the PR was pushed to after this review was submitted, meaning it may be outdated), `official` (bool), `dismissed` (bool).
- `method: "get_review"` (requires `review_id`) — single review detail.
- `method: "get_review_comments"` (requires `review_id`) — array of inline comments: `id`, `body`, `path`, `position`, `old_position`, `diff_hunk`, `user`, `html_url`, `created_at`, `updated_at`.
**`review_scomments` typo:** the full PR object returned by `pull_request_read method: "get"` includes a field named `review_scomments` (a count), not `review_comments` — a source-level misspelling in gitea-mcp v1.3.0's `slim.go`. Do not write code or instructions that reference `review_comments` on that response; it will always be `undefined`. This is distinct from the `get_review_comments` method above, which is spelled correctly and returns the actual comment objects.
**Inline-comment field names differ between write and read.** The `comments` array on `pull_request_review_write method: "create"` uses `old_line_num`/`new_line_num`. The `get_review_comments` read response uses different field names for the same concept — `position` (new-side line) and `old_position` (old-side line). Do not assume the same key names apply on both sides of the round trip.

33
plugins/gitea/skills/gitea-prs/references/sources.md Normal file
View File

@@ -0,0 +1,33 @@
# Sources
## gitea-mcp-repo
- **URL:** https://gitea.com/gitea/gitea-mcp
- **Description:** Official gitea-mcp repository (v1.3.0) — `operation/*.go` source files documenting all 55 MCP tools, their parameters, and CLI flags. Live tool schemas (`list_pull_requests`, `pull_request_read`, `pull_request_write`, `pull_request_review_write`) were verified directly against the deployed MCP server via `ToolSearch` at authoring time, per this repo's process for resolving schema-vs-docs drift, rather than copied from the derived research doc.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/pull-requests.md, references/reviews.md, references/merging.md
- **Status:** `extracted`
## gitea-mcp-slim-go
- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/pull/slim.go
- **Description:** Slim response shape structs from gitea-mcp source — defines exactly which fields the MCP server returns for PRs and reviews, including the `review_scomments` typo and the PR-response milestone-as-title-string quirk.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/pull-requests.md, references/reviews.md
- **Status:** `extracted`
## context7-websites-gitea
- **URL:** context7:/websites/gitea
- **Description:** Official Gitea docs mirror on Context7 — branch protection rules, PR review/merge gating behavior, and automatic issue/PR cross-reference linking. Backfills the external/best-practice gap left by the original docs.gitea.com fetch timeout.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/merging.md
- **Status:** `extracted`
## context7-gitea-tea-cli
- **URL:** context7:/git_gitea_com/gitea_tea
- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner command patterns for PR review workflows.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** references/merging.md
- **Status:** `extracted`

24
plugins/gitea/skills/gitea-releases/README.md Normal file
View File

@@ -0,0 +1,24 @@
# gitea-releases
Manage Gitea releases and tags — list, create, and delete releases (with draft/prerelease flags and notes) and their underlying tags.
## What it does
This skill handles release and tag operations for a Gitea repository. It creates releases from a tag/target commitish with title, notes, and draft/prerelease flags; lists and paginates releases and tags; retrieves the latest release; and deletes releases and tags as separate, independent destructive operations. It resolves the numeric release id required for deletion instead of assuming a tag name will work.
## Usage
```
/gitea-releases
```
Describe your release/tag task: list releases, get the latest release, create a release (with a tag, target, and title), or delete a release or tag. The skill handles resolving the numeric release id where required and keeps release/tag deletion as distinct operations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/call-signatures.md` | Tool parameters and response shapes derived from gitea-mcp source (see `references/sources.md`); input params for 3 of the 9 tools additionally live-cross-checked |
| `references/conventions.md` | Semver/draft/prerelease practitioner conventions and pagination behavior |
| `references/sources.md` | Research sources backing the call signatures and conventions |

52
plugins/gitea/skills/gitea-releases/SKILL.md Normal file
View File

@@ -0,0 +1,52 @@
---
name: gitea-releases
description: >
Use when managing Gitea releases and tags for a repository: listing, creating, or deleting
releases (with draft/prerelease flags and release notes), and listing, creating, or deleting the
underlying git tags. Use even if the user doesn't say "release" explicitly — "cut a v1.2.0",
"publish a prerelease", "tag this commit", or "what's the latest release" all apply. Do not use
for git branch or commit history operations (use gitea-branches) or for issue/PR management (use
gitea-issues / gitea-prs).
metadata:
category: gitea
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
- context7-websites-gitea
- context7-gitea-tea-cli
---
## Gotchas
- **`delete_release` takes a numeric `id`, never a tag name.** `delete_tag` is the mirror opposite — it takes the `tag_name` string, never a numeric id. These two tools are asymmetric on purpose; passing a tag name to `delete_release` or a numeric id to `delete_tag` fails. Always resolve the numeric release id via `list_releases` or `get_release` first if you only have a tag name in hand.
- **Deleting a release does not delete its tag.** They are separate destructive operations against separate resources — a release is a wrapper (title, notes, draft/prerelease flags, assets) around a tag, not the tag itself. If the intent is to remove both, call `delete_release` and `delete_tag` separately.
- **`list_releases`/`list_tags` default to `per_page: 20`**, unlike most other gitea-mcp tools which default to 30. The MCP layer does no auto-pagination — to get a complete result set, loop `page` upward until a page returns fewer than `per_page` results.
- **`is_draft`/`is_pre_release` are explicit booleans the caller sets on `create_release` — never inferred from `tag_name`.** Note the input param is `is_draft`, which maps to the `draft` field on the *response* object (see Dispatch table below and `references/call-signatures.md`) — `draft` is never a valid input key. Practitioner convention (per the `tea` CLI) uses `-beta`/`-rc` suffixes for prereleases (e.g. `v2.0.0-beta.1`), but Gitea does not enforce or infer this from the tag string. If the user names a tag that looks like a prerelease, set `is_pre_release: true` explicitly rather than assuming the flag is redundant with the name.
- **Tag names are conventionally semver, `v`-prefixed** (`v1.2.0`, `v2.0.0-beta.1`), but this is a practitioner convention, not a Gitea constraint — don't reject or rewrite a caller-supplied tag name that doesn't follow it.
## Dispatch table
| Action | Tool | Required params | Optional params |
|---|---|---|---|
| List releases | `list_releases` | `owner`, `repo` | `is_draft`, `is_pre_release`, `page` (default 1), `per_page` (default 20) |
| Get one release | `get_release` | `owner`, `repo`, `id` (number) | — |
| Get latest release | `get_latest_release` | `owner`, `repo` | — |
| Create release | `create_release` | `owner`, `repo`, `tag_name`, `target`, `title` | `body`, `is_draft`, `is_pre_release` |
| Delete release | `delete_release` | `owner`, `repo`, `id` (number) | — |
| List tags | `list_tags` | `owner`, `repo` | `page` (default 1), `per_page` (default 20) |
| Get one tag | `get_tag` | `owner`, `repo`, `tag_name` | — |
| Create tag | `create_tag` | `owner`, `repo`, `tag_name` | `target`, `message` |
| Delete tag | `delete_tag` | `owner`, `repo`, `tag_name` | — |
`target` (on `create_release`/`create_tag`) is a commitish — a branch name, existing tag, or commit SHA — the point the new tag is cut from. See `references/call-signatures.md` for response shapes.
## Workflow
- [ ] **Creating a release:** Call `create_release` directly with `tag_name` + `target` + `title` — Gitea is assumed to create the underlying tag automatically if `tag_name` doesn't already exist (this is plausible behavior inferred from the API shape, not directly confirmed in the research docs), so a separate `create_tag` call is only needed when you want to tag a commit without wrapping it in a release yet. Verify the tag exists afterward if this matters to the caller. Set `is_pre_release`/`is_draft` explicitly per the Gotchas above; don't leave them to default inference.
- [ ] **Deleting a release safely:** Resolve the numeric id first — call `list_releases` (paginate if needed, see Gotchas) or `get_release` if the id is already known, find the entry matching the target `tag_name`, then call `delete_release` with that `id`. Never pass `tag_name` to `delete_release`.
- [ ] **Deleting a tag along with its release:** Delete the release first (frees the id lookup), then call `delete_tag` with the `tag_name` separately — confirm both are intended before proceeding, since each is an independent irreversible operation.
- [ ] **Listing every page:** If the caller needs all releases or tags (not just the first page), loop `page: 1, 2, 3...` until a response has fewer than `per_page` entries.
If exact response field shapes or additional conventions are needed, read `references/call-signatures.md` and `references/conventions.md`.

75
plugins/gitea/skills/gitea-releases/references/call-signatures.md Normal file
View File

@@ -0,0 +1,75 @@
---
topic: call-signatures
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# Release and tag call signatures
Signatures and response shapes are derived from gitea-mcp source (`operation/*.go` and `slim.go`,
see `references/sources.md`) rather than copied from upstream API docs, which can drift from the
deployed gitea-mcp version — but this is a source-code extraction, not a live MCP tool call.
Input parameter schemas for 3 of the 9 tools here — `create_release`, `delete_tag`, and
`get_latest_release` — were additionally cross-checked live via `ToolSearch` against the deployed
`mcp__gitea__*` tools in session 2026-07-05, and confirmed to match exactly (required/optional
params and names). That check covered only input params for those 3 tools, not response shapes,
and not the other 6 tools — treat the rest of this document as source-derived, not live-verified.
`owner` and `repo` are required strings on every tool below and are omitted from the per-tool lists
for brevity.
## Releases
**`list_releases`**
- Optional: `is_draft` (boolean), `is_pre_release` (boolean), `page` (number, default 1), `per_page` (number, default 20)
- Returns an array of release objects (shape below), one page at a time.
**`get_release`**
- Required: `id` (number) — the release's numeric id, not its tag name.
- Returns a single release object.
**`get_latest_release`**
- No parameters beyond `owner`/`repo`.
- Returns a single release object for the most recently published release. It is assumed (by analogy with typical "latest release" semantics) that this excludes drafts and prereleases, but that exclusion is not directly confirmed by any of the research docs — verify with `list_releases` if the caller depends on this.
**`create_release`**
- Required: `tag_name` (string), `target` (string — branch, tag, or commit SHA to cut the tag from), `title` (string)
- Optional: `body` (string — release notes), `is_draft` (boolean), `is_pre_release` (boolean)
- Assumed (not confirmed by the research docs) that if `tag_name` doesn't already exist as a tag, Gitea creates it against `target` as part of this call. Verify with `get_tag`/`list_tags` afterward if the caller needs certainty.
**`delete_release`**
- Required: `id` (number) — same numeric id as `get_release`. Does not accept `tag_name`.
- Does not delete the underlying tag.
**Release object shape** (returned by list/get/create/latest):
```
id, tag_name, target, title, body, draft, prerelease, html_url, author, created_at, published_at
```
`author` is the creator's login. `body` holds the release notes.
## Tags
**`list_tags`**
- Optional: `page` (number, default 1), `per_page` (number, default 20)
- Returns an array of `{ name, commit_sha }` — no `message` field on list responses.
**`get_tag`**
- Required: `tag_name` (string)
- Returns `{ name, message, commit_sha }` — the only tag call that returns `message`.
**`create_tag`**
- Required: `tag_name` (string)
- Optional: `target` (string — commitish to tag; if omitted, Gitea tags the default branch tip), `message` (string — annotated tag message)
**`delete_tag`**
- Required: `tag_name` (string). Does not accept a numeric id.
- Assumed by symmetry with `delete_release` (documented above as not deleting the underlying tag) to also not delete any release wrapping the tag — but this reverse direction is not independently confirmed by the research docs, and is the more dangerous direction to get wrong: an agent might skip an explicit `delete_release` call assuming the release survives. Verify with `list_releases`/`get_release` after calling `delete_tag` rather than assume.
## Pagination
None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then
`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and
`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list
tools, so a caller assuming 30 will under-count pages needed for a fixed total.

44
plugins/gitea/skills/gitea-releases/references/conventions.md Normal file
View File

@@ -0,0 +1,44 @@
---
topic: conventions
source_keys:
- context7-websites-gitea
- context7-gitea-tea-cli
---
# Release and tag conventions
Practitioner conventions that inform *how* to use the mechanics in `call-signatures.md` — not
additional tool schemas.
## Release wraps a tag, not the reverse
A release is a title, body (notes), and draft/prerelease flags layered on top of an existing or
newly-created tag. The tag is the git-level object (a name pointing at a commit); the release is a
Gitea-level metadata wrapper around it. This is why `delete_release` and `delete_tag` are separate
calls with separate identifiers (numeric id vs. tag name) — removing the wrapper never implies
removing the underlying pointer, and vice versa.
## Semver tag naming
Per the `tea` CLI (the reference Gitea client), tag names conventionally follow semver with a `v`
prefix: `v1.2.0`, `v2.0.0-beta.1`. This is a convention observed by tooling and humans, not a
Gitea-enforced constraint — the API accepts any string as `tag_name`. Don't validate or rewrite a
caller-supplied tag name against semver; just pass it through.
## Draft and prerelease are explicit flags
`is_draft` and `is_pre_release` are booleans the caller sets directly on `create_release` — Gitea
does not infer either from the tag name, even though the `-beta`/`-rc` suffix convention above is
commonly used to signal a prerelease to humans. When a user asks to "cut a beta" or "publish a
release candidate," set `is_pre_release: true` explicitly in the same call rather than relying on
the tag string to carry that meaning.
Note the input/output naming mismatch: the input param is `is_draft`, but the release object
returned by the API uses `draft` (and `prerelease`) as the field names. `draft` is never a valid
input key — passing `draft: true` to `create_release` is silently ignored rather than erroring.
## Release notes sourcing
Practitioner convention (per `tea`) is to source release notes (`body`) from a changelog file
rather than typing them inline for each release — useful context when a caller asks to "generate"
or "use the changelog for" release notes rather than write them from scratch.

48
plugins/gitea/skills/gitea-releases/references/sources.md Normal file
View File

@@ -0,0 +1,48 @@
# Sources
## gitea-mcp-repo
- **URL:** https://gitea.com/gitea/gitea-mcp
- **Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/api-reference.md (Releases and Tags section); plugins/gitea/docs/research/docs/gitea/troubleshooting.md (`delete_release` numeric-id gotcha, `per_page` defaults)
**Contributing files:**
- SKILL.md (Dispatch table, Gotchas)
- references/call-signatures.md
**Status:** `extracted`
## gitea-mcp-slim-go
- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/repo/slim.go
- **Description:** Slim response shape structs from gitea-mcp source; defines exactly which fields the MCP server returns for tags and releases.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/api-reference.md (Releases and Tags response shapes)
**Contributing files:**
- references/call-signatures.md (release/tag object shapes)
**Status:** `extracted`
## context7-websites-gitea
- **URL:** context7:/websites/gitea
- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — release and tag semantics, draft/prerelease behavior.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/workflow-conventions.md (Release and tag conventions section)
**Contributing files:**
- SKILL.md (Gotchas — draft/prerelease as explicit flags)
- references/conventions.md
**Status:** `extracted`
## context7-gitea-tea-cli
- **URL:** context7:/git_gitea_com/gitea_tea
- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner release/tag command patterns, semver tag conventions, draft/prerelease flags, release-notes-from-file conventions.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/workflow-conventions.md (Release and tag conventions section)
**Contributing files:**
- SKILL.md (Gotchas — semver tag naming)
- references/conventions.md
**Status:** `extracted`

22
plugins/gitea/skills/gitea-workflow/README.md Normal file
View File

@@ -0,0 +1,22 @@
# gitea-workflow
Human-facing entry point and router for the Gitea integration.
## What it does
This skill is the conversational front door to the Gitea suite — it replaces the old flat `/gitea` skill. On its own it never calls a Gitea MCP tool; it composes the six domain skills (`gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-branches`, `gitea-files`, `gitea-releases`). It handles the no-args status check-in (open issues + open PRs), resolves ambiguous issue-or-PR numbers before dispatching (issues and PRs share one number space), and points a user or agent to the right domain skill when it's unclear which one applies.
## Usage
```
/gitea-workflow
```
Invoke with no arguments for a status check-in, with a bare number to resolve and show issue or PR detail, or with a general request to be routed to the right domain skill.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — Gotchas, status view, ambiguous-number resolution, and the domain-skill index |
| `references/sources.md` | Research sources backing the routing/status guidance |

74
plugins/gitea/skills/gitea-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,74 @@
---
name: gitea-workflow
description: >
Use when a human wants a general or ambiguous Gitea status check or isn't sure which Gitea
domain skill applies — a no-args check-in ("what's going on in the repo", "any updates?"),
a bare-numbered reference that could be an issue or a PR ("what's the status of #42", "what's
happening with #17"), or a request to discover which Gitea capability handles a task. This is
the human-facing entry point and router for the Gitea integration — it replaces the old flat
`/gitea` invocation (now `/gitea-workflow`) and composes the six domain skills
(`gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-branches`, `gitea-files`,
`gitea-releases`) rather than calling any Gitea MCP tool directly. Do not use this skill when
the domain is already known and unambiguous — invoke the matching domain skill directly instead
(e.g. "create an issue" → `gitea-issues`, "merge PR #10" → `gitea-prs`, "cut a release" →
`gitea-releases`). Do not use for local git operations with no Gitea component (use
`git-workflow`).
compatibility: Requires Gitea MCP server configured with a token; delegates all calls to the six
domain skills, which in turn require write:issue and write:repository scopes at minimum.
metadata:
category: integration
version: "0.1.0"
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
- context7-websites-gitea
---
## Gotchas
- **This skill never calls a Gitea MCP tool itself.** Every read or write goes through one of the six domain skills. If a request needs a raw `mcp__gitea__*` call that no domain skill exposes, that's a gap in a domain skill, not something to patch here.
- **Issues and PRs share one number space** — a bare number like `#42` could be either. Never guess from context clues alone; resolve it with a real call (see Step 2) before dispatching.
- **A 404 on the resolution call doesn't necessarily mean the number doesn't exist.** Gitea hides permission errors as not-found (documented in `gitea-issues`' Gotchas). If resolution 404s unexpectedly, say so and suggest checking token scope rather than reporting "no such issue or PR."
## Step 1 — Default status view (no args)
When invoked with no specific request, give a status check-in:
1. Invoke `gitea-issues` to list open issues (`state: "open"`).
2. Invoke `gitea-prs` to list open PRs (`state: "open"`).
3. Run both in parallel — they're independent reads.
4. Report as two sections, "Open Issues" and "Open Pull Requests", each as a compact list (number, title). This preserves the original flat `/gitea` skill's default behavior.
## Step 2 — Resolve an ambiguous number
When the user references a bare number without saying "issue" or "PR" (e.g. "what's going on with #42"):
1. Invoke `gitea-issues` to run `issue_read method: "get"` on that number.
2. Check the response's `is_pull` field:
- `true` → it's a PR. Invoke `gitea-prs` for full PR detail (status, diff, reviews as appropriate to the request) and present that instead.
- `false` or absent → it's an issue. Present the issue detail already retrieved.
3. If the resolution call 404s, don't conclude the number doesn't exist — report the 404 and suggest verifying token scope (`write:issue`) per `gitea-issues`' Gotchas, since permission errors are hidden as not-found in Gitea.
Never dispatch to `gitea-issues` or `gitea-prs` based on guessing from phrasing alone ("that sounds like a bug" is not evidence) — always resolve first.
## Step 3 — Route explicit but domain-unclear requests
For requests that name a capability but not obviously which skill owns it, use this index:
| Skill | Covers |
|---|---|
| `gitea-issues` | List/read/create/update issues, comments, search across issues and PRs. Composes `gitea-labels-milestones` for label/milestone resolution. |
| `gitea-labels-milestones` | Label and milestone CRUD, label inference from conversation context, resolving names/titles to the numeric IDs writes require. Cross-cutting — used by both `gitea-issues` and `gitea-prs`. |
| `gitea-prs` | List/read/create/update/merge PRs, code reviews. Composes `gitea-labels-milestones` the same way `gitea-issues` does. |
| `gitea-branches` | Branch list/create/delete, plus commit history (list commits, get a single commit by SHA). |
| `gitea-files` | Read/write/delete individual files, list a directory, walk the full repo tree. |
| `gitea-releases` | Release and tag CRUD — draft/prerelease flags, release notes, semver tags. |
If a request clearly names one of these (e.g. "create a milestone" → `gitea-labels-milestones`, "read this file from the repo" → `gitea-files`), invoke that skill directly rather than routing through here. Use this table only when the user or an upstream agent is unsure which skill applies.
## Step 4 — Report
Present results in plain language. For the status view, two labeled sections. For a resolved ambiguous number, say which domain it turned out to be before showing detail ("That's a pull request:" / "That's an issue:"). For routing, name the skill and hand off — don't duplicate its output format, let it report.

33
plugins/gitea/skills/gitea-workflow/references/sources.md Normal file
View File

@@ -0,0 +1,33 @@
# Sources
## gitea-mcp-repo
- **URL:** https://gitea.com/gitea/gitea-mcp
- **Description:** Official gitea-mcp repository (v1.3.0) — `operation/*.go` source files documenting all 55 MCP tools. This skill's status view relies on `list_issues`/`list_pull_requests` semantics (via `gitea-issues`/`gitea-prs`), and its ambiguous-number resolution relies on `issue_read`'s `is_pull` field, both verified against this source at authoring time.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md
- **Status:** `extracted`
## gitea-mcp-slim-go
- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/issue/slim.go
- **Description:** Slim response shape structs from gitea-mcp source — confirms `is_pull` is present on a single-item `issue_read` response, the field this skill's resolution step depends on to distinguish an issue from a PR sharing the same number.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md
- **Status:** `extracted`
## context7-websites-gitea
- **URL:** context7:/websites/gitea
- **Description:** Official Gitea docs mirror on Context7 — confirms issues and pull requests share a single per-repository number sequence, and that Gitea returns 404 for permission failures rather than a distinct 403, both facts this skill's resolution and error-handling steps depend on.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md
- **Status:** `extracted`
## context7-gitea-tea-cli
- **URL:** context7:/git_gitea_com/gitea_tea
- **Description:** Official `tea` CLI docs on Context7 — practitioner conventions for issues, PRs, and releases. Consulted as part of the shared research pass but its content is domain-specific (PR/release workflow patterns), out of scope for pure status/routing behavior — no content from it was used in this skill.
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** (none)
- **Status:** `extracted`

33
plugins/gitea/sources.md Normal file
View File

@@ -0,0 +1,33 @@
# Sources
## gitea-mcp-repo
- **URL:** https://gitea.com/gitea/gitea-mcp
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags — informs the orchestrator's operation index and its `delete_release`/`delete_tag` id-vs-name and pagination-default hard rules.
- **Contributing files:** agents/gitea-orchestrate.md, agents/gitea-orchestrate.agent.md
- **Status:** `extracted`
## gitea-mcp-slim-go
- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/issue/slim.go, https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/pull/slim.go, https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/repo/slim.go
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Description:** Slim response shape structs from gitea-mcp source; defines the `is_pull` field the orchestrator's Number resolution routine checks to disambiguate issue vs. PR numbers.
- **Contributing files:** agents/gitea-orchestrate.md, agents/gitea-orchestrate.agent.md
- **Status:** `extracted`
## context7-websites-gitea
- **URL:** context7:/websites/gitea
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Description:** Official Gitea docs mirror on Context7 — informs the default-branch protection hard rule and permission-errors-as-404 behavior the orchestrator surfaces via `not_found_or_forbidden`.
- **Contributing files:** agents/gitea-orchestrate.md, agents/gitea-orchestrate.agent.md
- **Status:** `extracted`
## context7-gitea-tea-cli
- **URL:** context7:/git_gitea_com/gitea_tea
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Description:** Official `tea` CLI docs on Context7 — practitioner conventions for release/tag semver naming and merge strategy choices that inform the orchestrator's destructive-operation gating around `merge-pr` and `delete-release`/`delete-tag`.
- **Contributing files:** agents/gitea-orchestrate.md, agents/gitea-orchestrate.agent.md
- **Status:** `extracted`

2
plugins/kyberforge/.claude-plugin/plugin.json
View File

@@ -8,5 +8,5 @@
"keywords": [],
"license": "MIT",
"name": "kyberforge",
"version": "1.2.2"
"version": "1.2.8"
}

2
plugins/kyberforge/plugin.json
View File

@@ -13,5 +13,5 @@
"skills": [
"skills/"
],
"version": "1.2.2"
"version": "1.2.8"
}

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

@@ -4,7 +4,7 @@ Audits a Claude Code and Copilot agent definition file pair for correctness and
## What it does
Accepts either file in a CC `.md` / Copilot `.agent.md` pair, derives the counterpart automatically, and validates both. Runs structural checks via `validate.sh` (required fields, kebab-case name, no placeholders, no CC-only fields in the Copilot file, silently-ignored fields at plugin scope), provenance chain validation via `validate-provenance.sh` (checks `source_keys` against `sources.md` at the plugin root), then qualitative checks on description phrasing and system prompt quality. Produces a compact findings report in the same format as `skill-audit`.
Accepts either file in a CC `.md` / Copilot `.agent.md` pair, derives the counterpart automatically, and validates both. Runs structural checks via `validate.sh` (required fields, kebab-case name, no placeholders, no CC-only fields in the Copilot file, silently-ignored fields at plugin scope), provenance chain validation via `validate-provenance.sh` (checks `source_keys` against `sources.md` at the plugin root), then qualitative checks on description phrasing and system prompt quality. Step 1 also runs a Vale-based prose sub-check via `vale-wrap.sh` against both files of the pair, using the `Kyberforge` style (both files) and `KyberforgeCopilot` style (Copilot file only) — every alert is a `FAIL`, cited by rule ID — falling back to Step 2 judgment when the `vale` binary is unavailable or reports `0 files` scanned. Produces a compact findings report in the same format as `skill-audit`.
## Usage
@@ -19,6 +19,12 @@ Pass the path to either agent file as the argument.
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `assets/vale/.vale.ini` | Vale config: scopes `Kyberforge` to `**/agents/*.md`, `Kyberforge`+`KyberforgeCopilot` to `**/*.agent.md` |
| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Flags descriptions opening with "This skill/agent" instead of an imperative "Use when..." |
| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Flags generic "see references/ for info" pointers instead of specific file references |
| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Flags sentences opening with "There is/are" instead of naming the subject directly |
| `assets/vale/styles/Kyberforge/VagueWording.yml` | Flags vague capability wording ("helps with", "utilize", "assists with", "used for") in descriptions |
| `assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml` | Flags CC-specific "Use proactively" phrasing with no effect in Copilot descriptions |
| `references/README.md` | Directory documentation for references/ |
| `references/description-quality.md` | Qualitative guide for borderline description findings |
| `references/field-inventory.md` | Authoritative list of valid CC and Copilot agent fields |
@@ -26,6 +32,7 @@ Pass the path to either agent file as the argument.
| `scripts/README.md` | Directory documentation for scripts/ |
| `scripts/validate.sh` | Structural validation script for agent file pairs |
| `scripts/validate-provenance.sh` | Provenance chain validation script for agent pairs against `sources.md` (plugin root) |
| `scripts/vale-wrap.sh` | Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation |
| `tests/README.md` | Bats test dependency and run instructions |
| `tests/validate.bats` | Bats tests for validate.sh |
| `tests/validate-provenance.bats` | Bats tests for validate-provenance.sh |

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

@@ -36,10 +36,13 @@ metadata:
```bash
bash scripts/validate.sh <path-to-agent-file>
bash scripts/validate-provenance.sh <path-to-agent-file>
scripts/vale-wrap.sh <path-to-cc-file> <path-to-copilot-file>
```
The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, plugin-silently-ignored fields, body length, or subagent-unavailable tools → `### Provider safety`. A missing counterpart file → `### Pair consistency`.
`vale-wrap.sh` ships inside this skill's own `scripts/` — resolve it relative to this skill's directory the same way `scripts/validate.sh` is resolved above, so the invocation works whether this skill is running from this repo or from an installed plugin cache. Pass no `--config`: handed none, the wrapper loads its own sibling `assets/vale/.vale.ini`, located from the script's path rather than from the cwd. Adding an explicit relative `--config` breaks exactly the case the self-location covers — a resolved script path plus an unresolved config path yields `E100 Runtime error ... does not exist`, exit 2, which the fallback below then misreads as "vale unavailable". Run it against both files of the pair (not just the one passed in). `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one in the `### Description` / `### Body` dimensions citing its rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if the `vale` binary is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 2 judgment for the dimensions it would have covered.
`validate-provenance.sh` validates the provenance chain between the agent pair's `source_keys` and the plugin-scoped `sources.md` (plugin root — see ADR-0010). It exits 0 silently for non-plugin-scope agents and when no provenance data exists. Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
If the scripts cannot run (Bash denied, python3 unavailable), perform checks manually: counterpart file exists, required fields present (`name`, `description`, non-empty body), `name` is kebab-case, Copilot CLI `.agent.md` `name` must match filename stem (CC files are exempt — the CC platform does not require name to match filename), no `FILL IN:` placeholders, no CC-only fields in Copilot file, no Copilot-only fields in CC file (read `references/field-inventory.md` for the authoritative field lists).
@@ -49,15 +52,17 @@ If the scripts cannot run (Bash denied, python3 unavailable), perform checks man
Read both agent files. Work through each dimension internally. Collect findings only; report in Step 3.
**Description (both files):**
- Action-verb opening: description starts with a verb ("Reviews...", "Analyzes...", "Generates...") — FAIL if absent
- Specificity: is the trigger condition stated precisely? — SUGGESTION if vague
- `Use proactively` in a Copilot description: CC-specific phrasing, has no effect in Copilot — SUGGESTION to remove
- Action-verb opening: description starts with a verb ("Reviews...", "Analyzes...", "Generates...") — FAIL if absent. Vale's `Kyberforge.DescriptionOpener` alert flags the specific known-bad "This agent..." opener directly; verifying an arbitrary opening word is genuinely a strong verb still requires judgment.
- Specificity: is the trigger condition stated precisely? — SUGGESTION if vague. Vale's `Kyberforge.VagueWording` alert covers known filler ("helps with", "utilize", ...) directly; report those as FAILs without re-deriving by judgment.
- `Use proactively` in a Copilot description: Vale's `KyberforgeCopilot.ProactivePhrase` alert (Copilot file only) flags this directly — report it without re-deriving by judgment.
If a description finding is borderline, read `references/description-quality.md`.
**Body:**
- Direct role instruction: system prompt opens with `You are a [role]. When invoked, [action].` — SUGGESTION if absent
- One job per agent: system prompt describes a single bounded task — SUGGESTION if scope appears unbounded
- Generic, non-specific reference pointers to the `references/` directory: Vale's `Kyberforge.PaddingPhrase` alert flags this directly — report it without re-deriving by judgment
- Sentences that open with "There is"/"There are": Vale's `Kyberforge.SentenceOpenerThereIs` alert flags this directly — report it without re-deriving by judgment
**Body/Frontmatter comments:**
- Inspect each comment block in the YAML frontmatter. For each comment, apply: *"Would the agent get this wrong without this comment?"* Flag any that answer "no" as padding.

7
plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini Normal file
View File

@@ -0,0 +1,7 @@
StylesPath = styles
[**/agents/*.md]
BasedOnStyles = Kyberforge
[**/*.agent.md]
BasedOnStyles = Kyberforge, KyberforgeCopilot

7
plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml Normal file
View File

@@ -0,0 +1,7 @@
extends: existence
message: "Description opens with '%s' — use an imperative 'Use when...' opener instead"
level: error
scope: text.frontmatter.description
ignorecase: true
raw:
- '^This (skill|agent)\b'

7
plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml Normal file
View File

@@ -0,0 +1,7 @@
extends: existence
message: "Generic reference pointer: '%s' — use the specific 'If X, read `references/file.md`' form instead"
level: error
scope: text
ignorecase: true
raw:
- 'see references?/? for (more )?(info|information|details)\b'

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