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

Compare commits

base: Defame1297/holocron:01f6171347d4bed045aba0b42dd7beda9696f7aa
Defame1297/holocron:main Defame1297/holocron:docs/onedev-migration-plan Defame1297/holocron:feat/66-wire-gitea-mcp-config
Defame1297/holocron:v2.0.1 Defame1297/holocron:v2.0.0 Defame1297/holocron:v1.0.0
..
compare: Defame1297/holocron:v1.0.0
Defame1297/holocron:main Defame1297/holocron:docs/onedev-migration-plan Defame1297/holocron:feat/66-wire-gitea-mcp-config
Defame1297/holocron:v2.0.1 Defame1297/holocron:v2.0.0 Defame1297/holocron:v1.0.0
115 Commits
01f6171347 .. 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 <[email protected]>
 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
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:32:32 +00:00
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:32:30 +00:00
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:32:30 +00:00
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:06:53 +00:00
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:06:52 +00:00
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:06:37 +00:00
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-09 13:06:36 +00:00
Defame1297andClaude Opus 5 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 <[email protected]>
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
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:54:19 +00:00
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:45:13 +00:00
Defame1297andClaude Opus 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:42:15 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:21:21 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
 2026-08-08 20:21:21 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
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
Defame1297andClaude Sonnet 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
 2026-08-08 20:20:58 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
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
Defame1297andClaude Sonnet 5 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 <[email protected]>
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 <[email protected]>
 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 <[email protected]>
 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 <[email protected]>
 2026-07-23 18:10:15 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
 2026-07-23 18:08:46 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
 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 <[email protected]>
 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 <[email protected]>
 2026-07-23 17:46:08 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
 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
Defame1297andClaude Sonnet 5 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 <[email protected]>
 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
Defame1297andClaude Sonnet 5 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 <[email protected]>
 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
Defame1297andClaude Sonnet 5 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 <[email protected]>
 2026-07-23 17:08:19 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
 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 <[email protected]>
 2026-07-05 13:37:21 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
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 <[email protected]>
 2026-07-05 13:24:52 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
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 <[email protected]>
 2026-07-05 13:02:44 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
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 <[email protected]>
 2026-07-05 12:59:19 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
 2026-07-05 12:52:52 +00:00
Defame1297andClaude Sonnet 5 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
 2026-07-05 12:44:26 +00:00
Defame1297 828e79535f Merge pull request 'fix(factory): embed lessons from #63 into gitea and kyberforge skills' (#65) from chore/factory-lessons-from-63 into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/65
Reviewed-by: Defame1297 <[email protected]>
 2026-07-05 09:38:48 +00:00
Defame1297andClaude Sonnet 5 642e4fd142 fix(kyberforge): broaden audit self-triggers, plug factory gaps 
skill-audit/agent-audit now proactively trigger after a skill/agent
file is hand-edited outside skill-author/agent-author, not just on
explicit request — closing a gap from this session where a fork's
direct edits to agent-author/agent-audit shipped without their own
inline audit until forge was invoked to check afterward.

Also: plugin-author gains a gotcha on claude plugin validate --strict
auto-discovering every .md under agents/ regardless of manifest
declarations (ADR-0010); agent-audit's dimension count and
validate-provenance.sh's --help now match actual behavior.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
 2026-07-05 09:34:59 +00:00
Defame1297andClaude Sonnet 5 f21a1427f5 fix(gitea): correct issue auto-close gotcha, drop unused tool 
The gotcha claimed Gitea never auto-closes issues on merge. Confirmed
empirically (issue #63 / PR #64) that a regular merge preserving an
original commit's closing keyword does auto-close — only squash merges
(this skill's default) are unreliable. Also drops search_issues from
allowed-tools since no dispatch route calls it.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
 2026-07-05 09:34:47 +00:00
Defame1297 acc0ae00bf Merge pull request 'fix(agents): relocate provenance sources.md outside agents/ dir' (#64) from fix/63-relocate-agent-sources-provenance into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/64
Reviewed-by: Defame1297 <[email protected]>
 2026-07-05 09:15:21 +00:00
Defame1297andClaude Sonnet 5 d8e242eb5b docs(agent-audit): map counterpart-missing failure to Pair consistency 
Independent skill-audit clean-check surfaced that the dimension-mapping
list and manual-fallback checklist both skipped the counterpart-missing
case, which validate.sh already treats as a hard FAIL.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
 2026-07-05 09:10:31 +00:00
Defame1297andClaude Sonnet 5 996d9be428 fix(agents): relocate provenance sources.md outside agents/ dir 
`claude plugin validate --strict` auto-discovers every .md under a
plugin's agents/ directory as an agent requiring frontmatter, so the
provenance file there always needs fake agent frontmatter to pass
validation. Confirmed empirically that an explicit `agents` manifest
array can't suppress this discovery. Move the file to <plugin-root>/
sources.md instead, and update agent-author/agent-audit accordingly.

Adds ADR-0010, partially superseding ADR-0005's `agents/sources.md`
convention. Fixes #63.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
 2026-07-05 09:01:06 +00:00
Defame1297 5deed07a95 chore: add plugins settings + remove git instructions 2026-07-04 19:03:17 +00:00
Defame1297andClaude Sonnet 5 0239b00944 feat(git-plugin): add complete git workflow automation suite 
## Why
The git plugin only covered a partial slice of common git workflows.
This adds the remaining skill set (branches, commits, history, remotes,
submodules, workflow, worktrees) plus a git-orchestrate agent so the
plugin can handle end-to-end git automation instead of a handful of
commands.

## Implementation Notes
Each new skill was validated against its research docs and org
conventions after initial authoring, which surfaced hallucinated
version pins, factual errors, and completeness gaps that were
corrected in the same pass rather than left for follow-up.

## Impact
Bumps the git plugin to 1.3.0.

Co-authored-by: Claude Sonnet 5 <[email protected]>
 2026-07-04 18:46:02 +00:00
Defame1297 05bb9d6e9f docs(adr): triage, rewrite, and renumber ADRs for clean slate 
Complete ADR refactoring for issue #15:

## Changes

1. **Triage archival** — deleted chunk-era ADRs (0001–0003, 0006–0011, 0013); kept active decisions (0004, 0005, 0012, 0014+)
2. **ADR-0004 rewrite** — now reflects plugin-based skill distribution (`plugins/<name>/skills/` + `claude plugin install`) instead of monolithic `.agents/skills/` deployment
3. **Renumber to 0001–0009** — sequential clean slate after archival; all cross-references updated
4. **Content audit** — verified all 9 remaining ADRs for alignment with plugin model, removed stale chunk/deployment language

Kept ADRs: 0001–0009
- 0001: Skills distributed via plugins
- 0002: Two-tier CLAUDE.md (always-on + on-demand)
- 0003: AGENTS.md as provider-agnostic entry point
- 0004: INFO finding level in skill-audit
- 0005: agent-author dual provider scaffold
- 0006: Plugin version parity (version in both manifests)
- 0007: Gitea as exclusive issue tracker
- 0008: agent-audit single-file invocation
- 0009: agent-audit field inventory reference

All decisions are active and aligned with current repository state (marketplace/plugin model).

Closes #15 (ADR section of acceptance criteria)
Co-Authored-By: Claude Haiku 4.5 <[email protected]>
 2026-07-04 17:18:04 +00:00
Defame1297andClaude Haiku 4.5 9f662807a1 feat(forge): add version-bump orchestration via plugin-author subagent 
Step 4 ensures that after creating/updating artifacts in a plugin, forge invokes plugin-author (clean-context subagent) to bump the plugin version if not already done by other skills. Prevents missed version updates when artifacts are added to plugins.

Co-Authored-By: Claude Haiku 4.5 <[email protected]>
 2026-07-04 16:53:18 +00:00
Defame1297andClaude Haiku 4.5 69218ae224 feat(plugins): bump kyberforge to 1.2.0, git to 1.1.0 
kyberforge gains new forge skill for factory artifact routing; git gains pc-author and pc-run skills moved from kyberforge. Includes version parity fixes in CC manifests (ADR-0016).

Co-Authored-By: Claude Haiku 4.5 <[email protected]>
 2026-07-04 16:53:16 +00:00
Defame1297andClaude Sonnet 5 7e3cb90359 feat(kyberforge): add forge routing skill for factory artifact classification 
Grills intent, classifies target artifact type (skill/agent/plugin/marketplace
entry) against a fully descriptive table, then routes to the matching author
skill via fork subagent (falling back to inline when fork is unavailable or
the flow needs live interaction). Adds an independent clean-context audit
recheck after each skill/agent route, looping author-then-audit until the
recheck comes back clean, since the author skill's own inline audit shares
context with the work it verifies. Updates CONTEXT.md's Skill composition
entry to describe this recheck loop and adds forge's provenance chain
(references/sources.md).

Refs Defame1297/holocron#61

Co-Authored-By: Claude Sonnet 5 <[email protected]>
 2026-07-04 16:45:50 +00:00
Defame1297 b521083335 chore(settings): enable core and git plugins 2026-07-04 15:41:04 +00:00
Defame1297 e41afd8db1 docs(kyberforge): add skill-vs-agent decision criteria for Claude Code and Copilot 
Fills a gap needed for the planned forge orchestrator skill: neither doc set
previously stated when to build a skill vs a subagent/custom agent. Sourced
via context7 against the same libraries already recorded in each sources.md.
Also confirms agentskills.io's spec is runtime-agnostic and defines no agent
concept, so it has no bearing on this decision by design.
 2026-07-04 15:40:36 +00:00
Defame1297andClaude Haiku 4.5 19f7fde5e1 refactor(factory): align agent-author and agent-audit with skill-author pattern 
- agent-author: convert template comments from YAML (#) to HTML (<!-- -->)
  - Easier to spot and distinguish from functional comments
  - Add explicit "Delete template comments before shipping" reminders
  - Update SKILL.md Steps 2-3 with removal instruction

- agent-audit: add comment-discipline check
  - Flag excessive frontmatter documentation comments as padding
  - Mirrors skill-audit's body-discipline principle
  - Update coverage line to include comment-discipline dimension

This ensures agents follow the same comment-cleanup discipline as skills,
preventing template documentation from shipping with agent definitions.

Co-Authored-By: Claude Haiku 4.5 <[email protected]>
 2026-07-04 15:23:04 +00:00
Defame1297 77dedc3735 chore(git): move pc skills from kyberforge to git plugin 2026-07-04 12:23:28 +00:00
Defame1297 31e11e7969 chore(docs): cleanup + restructuring 2026-07-04 11:41:11 +00:00
Defame1297andClaude Sonnet 4.6 e58234eaf9 fix(kyberforge): address agent-audit audit findings in validate-provenance.sh 
## Why

Two issues were found in `validate-provenance.sh` by `/skill-audit`:

1. `find_plugin_root` only walked up looking for bare `plugin.json`, missing
   the `.claude-plugin/plugin.json` layout used by kyberforge plugins — matching
   the logic already present in `validate.sh`.

2. Check numbers in `--help` and inline comments had a gap (0,1,2,4,5,6) from
   a previously removed check, making the numbering confusing to readers.

## Implementation Notes

Check numbers renumbered sequentially 0–5 in both the `--help` output block
and the inline `# --- Check N:` comments. The `find_plugin_root` condition now
mirrors the `detect_scope` function in `validate.sh`.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 11:33:03 +00:00
Defame1297andClaude Sonnet 4.6 fe34daeed7 fix(kyberforge): resolve agent-author audit findings 
Corrects three FAIL findings from the skill-audit run:
- Scope detection table in SKILL.md and references/scripts.md now lists all
  four plugin-marker variants the script actually checks (plugin.json,
  .claude-plugin/plugin.json, .plugin/plugin.json, .github/plugin/plugin.json)
- assets/README.md copilot.agent.md description was wrong about field set;
  replaced with accurate CLI-format description noting excluded cloud/IDE fields
  and the Copilot tool aliases actually used.

Also applies the SUGGESTION: moves the conditional reference
(`If the destination is a plugin directory, read references/deployment-modes.md`)
out of the ## Gotchas section body and into ## Route as a standalone line,
immediately after ## Gotchas closes.

INFO findings (source_keys frontmatter) were already present in both
references/README.md and references/scripts.md — no change needed.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 11:29:20 +00:00
Defame1297andClaude Sonnet 4.6 1eb28da207 fix(kyberforge): remove internal mechanics sentence from skill-author description 
## Why

The description sentence "Handles both the full create flow (scaffold → fill →
validate) and the improve flow (signals → root cause → edit → audit)." describes
internal mechanics rather than user intent. The surrounding trigger phrases already
cover both create and improve intents, so this sentence adds no triggering value
and violates the description principle of focusing on what the user is trying to
achieve.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 11:24:05 +00:00
Defame1297andClaude Sonnet 4.6 fb4bfc1ae7 fix(kyberforge): apply audit findings to agent-audit skill 
Remove phantom cross-file name-match claim from SKILL.md manual fallback
list (validate.sh has no such check). Fix broken bats stem-mismatch test
to overwrite the Copilot file instead of the CC file, exercising the
actual Copilot stem check.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 11:23:05 +00:00
Defame1297andClaude Sonnet 4.6 4ea9e21ead fix(kyberforge): apply audit findings to agent-author skill 
- Fix Copilot format conflation: split CLI vs cloud/IDE in Step 3,
  clean copilot template to CLI-only fields, add body length limit (30k)
- Add missing CC fields to Step 2: disallowedTools, skills, color,
  initialPrompt, background
- Fix Gotchas: add WaitForMcpServers to unavailable tools list,
  add ExitPlanMode plan-mode carve-out
- Make 'Use proactively' conditional (was unconditional directive)
- Clarify audit invocation to 'Invoke kyberforge:agent-audit skill directly'
- Add 'Would the agent get this wrong?' heuristic to Improve Step 4
- Add agent-audit co-install prerequisite check
- Add pre-audit manual checklist to validate/close step
- Add references/scripts.md for new-agent.sh conventions
- Fix sources.md: remove template/script files from Contributing files
  (templates can't carry YAML provenance without leaking into user files),
  add 3 missing research slugs with (none) contributing files
- Add context7-github-en-copilot to deployment-modes.md source_keys
- Update README.md and references/README.md with new scripts.md entry

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 11:11:11 +00:00
Defame1297andClaude Sonnet 4.6 8463c87dfc feat(kyberforge): improve agent-audit skill with platform-accurate checks and description quality reference 
- Fix validate.sh: remove incorrect name==stem check for CC files (CC docs say filename need not match name field); keep check for Copilot CLI only
- Fix validate.sh: plugin scope detection now checks both plugin.json and .claude-plugin/plugin.json
- Fix validate.sh: Copilot cloud/IDE agents (.github/copilot/agents/) have name as optional; path-based guard added
- Add validate.sh checks: Copilot body length >30,000 chars (SUGGESTION), Copilot-only fields in CC files (FAIL), subagent-unavailable tools in tools field (SUGGESTION)
- Add references/description-quality.md as conditional escape hatch for borderline description findings
- SKILL.md: name five audit dimensions in description; sharpen indirect-trigger phrasing
- SKILL.md: label pair-mandate as kyberforge project convention, not platform requirement
- SKILL.md: scope redundant name-match/body-empty checks to manual fallback only
- SKILL.md: add conditional reference to description-quality.md; update provider-safety description for new check categories; fix plugin scope gotcha to mention .claude-plugin/plugin.json
- SKILL.md: add INFO tier to result block template
- Add source_keys frontmatter to references/README.md; update sources.md to add description-quality.md to contributing files

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 11:10:32 +00:00
Defame1297andClaude Sonnet 4.6 f9b22322a1 feat(kyberforge): improve skill-author — duality description, source_keys guidance, pre-audit checklists, version bump conventions 
- references/sources.md: add YAML frontmatter with source_keys to fix provenance chain break
- SKILL.md description: make create/improve duality explicit ("Handles both the full create flow ... and the improve flow ...")
- SKILL.md Step 2: add inline metadata.source_keys instruction — fill early, not deferred to Step 5
- SKILL.md Step 6 (create) / Step 5 (improve): add pre-audit manual checklists and version bump conventions (minor for create, patch for improve)
- README.md: correct false claim that the skill bumps plugin manifests; it bumps metadata.version only

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 11:06:02 +00:00
Defame1297andClaude Sonnet 4.6 1333d2c1b1 feat(kyberforge): add agent-audit provenance chain validation (closes #60) 
## Why

agent-author produces agents/sources.md at plugin scope to record which
research sources informed which agent files. agent-audit had no way to
validate this chain, leaving stale or missing provenance undetected.

## Implementation Notes

Validation is per-pair (the given agent file + its counterpart) rather
than plugin-wide, keeping the scope consistent with validate.sh. The
script exits 0 silently for non-plugin-scope agents.

source_keys is top-level in both CC .md and Copilot .agent.md files
(not under metadata:) to avoid conflict with Copilot's own metadata
field semantics. Checks 0, 1, 2, 4, 5, 6 mirror the skill provenance
set; upstream research-doc cross-reference checks (7, 8) are deferred.

agent-author Steps 2, 3, and 4 updated to formally specify the
agents/sources.md format and instruct authors to add source_keys to
both files when research sources are in context.

Refs: #60

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 10:37:44 +00:00
Defame1297andClaude Sonnet 4.6 a4235d197d feat(kyberforge): wire agent-audit into agent-author close steps 
## Why

The last acceptance criterion from #11: agent-author's close step should
reference agent-audit so authors are prompted to validate the pair before
shipping, matching the pattern skill-author uses with skill-audit.

Refs: #11
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 10:07:39 +00:00
Defame1297andClaude Sonnet 4.6 92c13b997f feat(kyberforge): add agent-audit skill (closes #11) 
## Why

agent-author produces paired agent definition files (Claude Code .md +
Copilot .agent.md) but had no companion audit skill to validate them.
agent-audit fills that gap, giving the same structured PASS/FAIL report
that skill-audit provides for SKILL.md files.

## Implementation Notes

- validate.sh uses scope detection (walk up for plugin.json / .git) to
  locate the counterpart file and determine whether plugin-silently-ignored
  fields (hooks, mcpServers, permissionMode) should be flagged
- CC-only and silently-ignored field lists are read from
  references/field-inventory.md at runtime rather than hardcoded —
  provenance back to the research corpus; see ADR-0019
- Single-file invocation (pass either file, counterpart derived) chosen
  over directory or name+root — see ADR-0018
- 12 bats tests cover provider detection, scope detection, all FAIL paths,
  and clean-pair pass

## Impact

- kyberforge bumped to v1.1.2
- agent-author close step should be updated to reference agent-audit (#11)
- Provenance/sources chain check deferred to #60

ADR: docs/adr/0018-agent-audit-single-file-invocation.md
ADR: docs/adr/0019-agent-audit-field-inventory-reference.md
Refs: #11
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-07-04 10:06:37 +00:00
Defame1297andClaude Sonnet 4.6 e3e43502db docs(kyberforge): add component-selection research closing the when-to-use gap 
## Why

The existing kyberforge research covered skills vs agents (ADR-0010),
Copilot track selection, and agent scope hierarchy — but had no documented
basis for three practical decisions: when to use MCP servers vs skills vs
agents, when hooks are the right tool vs skills, and when bin/ is
appropriate vs scripts/ inside a skill directory. Without this, the
plugin-author and agent-author skills have no research backing for those
choices.

## Implementation Notes

Sourced from official Claude Code plugin docs (code.claude.com), official
GitHub Copilot CLI docs (docs.github.com), and the Copilot
customization-cheat-sheet and comparing-cli-features pages — the latter
containing the only official "putting it together" decision table across
components. Context7 MCP was the primary retrieval mechanism; web reads
deepened the hooks and bin/ content.

Three files produced:
- overview.md — mental model, component roles, cross-provider portability
- decision-guide.md — explicit decision tables for all three gaps,
  including anti-patterns and Copilot surface support matrix
- hooks.md — full lifecycle event reference, stdin/stdout schema,
  hookSpecificOutput per event, plugin scope restriction

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-06-28 20:49:05 +00:00
Defame1297andClaude Sonnet 4.6 e1e85284d1 docs(git): add research reference corpus for git plugin 
11 topic files covering the full git surface area needed for skill and
agent authoring: overview, installation, configuration, cli-reference,
commits (Conventional Commits v1.0.0), branching-merging, submodules,
worktrees, gitflow, remotes (push/pull/fetch/force-with-lease), and
history-inspection (bisect, log --format, pickaxe, --diff-filter).
Includes sources.md mapping all 13 source documents.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
 2026-06-28 20:34:42 +00:00
Defame1297andClaude Sonnet 4.6 69f395f0f6 chore: remove stale chunk/skills references from vision, scripts, and tests 
## Why
The repo moved from a chunk-based delivery model with `.agents/skills/`
as the canonical skill source to a plugin model. Several files retained
references to the old model that were either dead code or misleading
framing.

## Impact
- `tests/test-install.sh`: dead `.agents/skills/` test blocks removed;
  suite now tests only what `install.sh` actually deploys
- `scripts/deploy-manifest.sh`: `DEPLOY_SKILLS_SRC` variable and stale
  `sync.sh (Chunk 6)` comment removed
- `tests/test-git-hooks-install.sh`: fixture stub no longer declares
  the removed `DEPLOY_SKILLS_SRC` variable
- `docs/VISION.md`: chunk delivery framing replaced with plugin model
  language throughout; manual test plan date updated
- `tests/test-instructions-and-docs.sh`: stale test plan date flagged
  as pre-refactor so readers know a re-run is needed

Refs: #15

Co-authored-by: Claude Sonnet 4.6 <[email protected]>
 2026-06-28 20:04:45 +00:00
Defame1297 3b5b1b5199 docs(spec): remove overview.md, rewrite architecture.md for plugin model 
## Why
overview.md described the chunk-based delivery model, which is superseded
by the marketplace/plugin pivot. architecture.md was equally stale: it
described .agents/skills/ as the canonical skills source (directory does not
exist), a provider-manifest.sh symlink mechanism (never built), and sync.sh /
init-project.sh as existing scripts (Chunk 6, not yet built).

## Implementation Notes
- overview.md deleted; all cross-references scrubbed from AGENTS.md, CONTEXT.md,
  and three notes/research files
- architecture.md fully rewritten: content deployment model reflects actual
  install.sh behaviour (DEPLOY_FILES / DEPLOY_EXECUTABLES / DEPLOY_DIRS);
  plugin model section added listing all 5 plugins; directory structure section
  removed (was describing a layout that no longer exists)
- "Chunk 6" phase label → "planned"; "chunk workflow" removed from AGENTS.md
  description
- Fixed broken path docs/HUMANS.md → docs/wiki/HUMANS.md in governance layer
  and core/instructions/governance.md

Refs: #15
 2026-06-28 19:53:19 +00:00
Defame1297andClaude Sonnet 4.6 7a00368683 docs: remove ROADMAP.md and scrub all references 
## Why

ROADMAP.md was a static file that duplicated tracking information now
owned by Gitea milestones and issues. Keeping it created a maintenance
burden — references drifted out of sync with the actual state of work,
and agents were directed to read it when the source of truth had moved.

## Implementation Notes

All inbound references replaced with either the relevant Gitea milestone
("Skills & Agents") or removed where the context made them redundant.
Test assertions that verified ROADMAP.md content removed; test output
strings updated to drop the ROADMAP cross-reference instruction.

## Impact

Agents no longer read docs/ROADMAP.md at session start. Gitea milestones
and issues are the canonical source for roadmap and open-question tracking.

---

Co-authored-by: Claude Sonnet 4.6 <[email protected]>
 2026-06-28 19:37:43 +00:00
289 changed files with 15680 additions and 944 deletions
Expand all files Collapse all files

No files matched your search

.claude-plugin/marketplace.json
+6 -1
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"
}
.claude/settings.json
+3
View File
@@ -1,6 +1,9 @@
{
"enabledPlugins": {
"bin@holocron": true,
"core@holocron": true,
"git@holocron": true,
"gitea@holocron": true,
"kyberforge@holocron": true
},
"hooks": {
.github/plugin/marketplace.json
+6 -1
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"
}
.pre-commit-config.yaml
+45
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
.pre-commit-hooks.yaml
+20
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$'
AGENTS.md
+21 -8
View File
@@ -1,28 +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/overview.md` — current deployed state; what works today
- `docs/spec/architecture.md` — current directory structure, install pipeline, provider model
- `docs/ROADMAP.md` — chunk status table and open questions; read this to orient on where work stands
- `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.
CONTEXT.md
+20 -4
View File
@@ -8,13 +8,13 @@ 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.
### Repo/gitea as source of truth
All project state, decisions, context, and working conventions live in this repo or Gitea. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read `CLAUDE.md`, `CONTEXT.md`, `docs/VISION.md`, and `docs/spec/overview.md`. Everything needed to orient is here.
All project state, decisions, context, and working conventions live in this repo or Gitea. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read `CLAUDE.md`, `CONTEXT.md`, and `docs/VISION.md`. Everything needed to orient is here.
Before answering any design or architecture question, check for existing decisions: `docs/adr/` (hard architectural decisions).
@@ -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.
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.
LESSONS.md
+37 -1
View File
@@ -24,7 +24,7 @@ Issue files frequently referenced "the workflow defined in `docs/notes/skill-imp
## 2026-05-17 — "Read at session start" is a behavioral hope, not a guarantee
The repo CLAUDE.md instructs agents to read CONTEXT.md and ROADMAP.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context. ROADMAP stays on-demand.
The repo CLAUDE.md instructs agents to read CONTEXT.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context.
## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity
@@ -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.
core/AGENTS.md
+1 -2
View File
@@ -22,6 +22,5 @@
Read these files on demand:
- **Coding conventions** (`~/.claude/core/instructions/coding.md`) — when writing, editing, or reviewing code
- **Git conventions** (`~/.claude/core/instructions/git.md`) — when doing git operations
- **Testing conventions** (`~/.claude/core/instructions/testing.md`) — when writing or running tests
- **Git Commit conventions** (`~/.claude/core/instructions/commits.md`) — when committing changes
- **Subagent orchestration** (`~/.claude/core/instructions/subagent-orchestration.md`) — when spawning or coordinating subagents/forks
core/instructions/commits.md
-78
View File
@@ -1,78 +0,0 @@
<!--
<type>(<scope>): <concise summary>
Required.
Purpose:
- Quickly communicates the intent when scanning `git log`.
- Follow Conventional Commits for consistency and tooling.
- Describe the intended outcome, not the implementation.
Examples:
feat(auth): support OAuth device flow
fix(cache): prevent stale session reuse
refactor(api): simplify request validation
-->
## Why
<!--
Explain why this change exists.
This is the most valuable part of the commit because the code diff
already shows WHAT changed. Future maintainers (human or AI) often
need to understand WHY the change was made.
Include, where applicable:
- Problem being solved
- User or business need
- Bug or root cause
- Important context that is not visible in the code
Omit if the reason is immediately obvious.
-->
## Implementation Notes
<!--
Capture decisions that are difficult to infer from the code.
Useful information includes:
- Why this approach was chosen
- Important assumptions or invariants
- Constraints imposed by external systems
- Tradeoffs or intentional compromises
- Non-obvious implementation details
- Workarounds or temporary solutions
Do NOT describe the diff ("renamed X", "added Y", etc.).
The code already documents that.
Omit if there is nothing worth preserving.
-->
## Impact
<!--
Document effects that future developers should know.
Examples:
- Behavior changes
- Breaking changes
- Performance implications
- Security considerations
- Migration or deployment requirements
- Compatibility concerns
- Follow-up work or known limitations
Omit if there are no noteworthy impacts.
-->
---
# References
<!-- Git Trailers: Structured metadata for traceability and tooling. Use only the trailers that apply. -->
Fixes:
Refs:
ADR:
RFC:
Design:
Co-authored-by:
Reviewed-by:
Signed-off-by:
BREAKING CHANGE:
core/instructions/git.md
-16
View File
@@ -1,16 +0,0 @@
# Git conventions
- Never skip hooks with `--no-verify`. Hooks are the automated QA gate; bypassing them breaks the pipeline.
- Never force-push `main` or `master`.
- Keep commits atomic. Each commit should represent one logical, independently reviewable and reversible change.
- Ensure every commit leaves the repository in a working state (buildable/testable where practical).
- Commit messages explain **why**, not **what**. The diff already documents what changed.
- Never commit secrets, credentials, or environment-specific config.
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
- Reference related issues, ADRs or design documents using Git trailers when applicable.
## Submodules
- When working with submodules: commit and push the submodule first, then update and push the parent repo. Pushing the parent while the submodule commit doesn't exist on the remote breaks `git submodule update` for anyone who pulls.
- Always use `rtk git` for parent repo operations; drop into the submodule directory for submodule-specific git commands.
- After adding a submodule, check `git status` in both the parent and the submodule — a `-dirty` flag means the submodule has uncommitted local changes that need to be committed before the parent pointer is updated.
core/instructions/governance.md
+1 -1
View File
@@ -70,7 +70,7 @@ When asked to perform a well-defined, repeatable task — file processing, deplo
## What This File Does Not Govern
Human process decisions are outside agent scope: oversight checkpoints, human approval gates, post-mortems, regulatory notifications, IP licence scanning, and sustainability measurement. These are defined in `docs/ai-constitution.md` and executed by humans following `docs/HUMANS.md`.
Human process decisions are outside agent scope: oversight checkpoints, human approval gates, post-mortems, regulatory notifications, IP licence scanning, and sustainability measurement. These are defined in `docs/ai-constitution.md` and executed by humans following `docs/wiki/HUMANS.md`.
The deterministic enforcement layer — pre-commit hooks, CI gates, scanner configuration, audit logging infrastructure, and AI agent permission scoping — is specified in `docs/research/governance_principles/CONTROLS.md` and implemented by humans. Agent instructions alone cannot enforce what deterministic tooling must enforce.
core/instructions/subagent-orchestration.md
+6
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.
core/instructions/testing.md
+1
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.
docs/ROADMAP.md
-138
View File
@@ -1,138 +0,0 @@
# Roadmap
## Chunk conventions
Content chunks (2–5) run in two phases, treated as separate sessions:
1. **Architecture + thin drafts** — define the format, schema, and loading model; populate every category with a minimal first draft. Mark speculative entries with `<!-- draft -->` so future sessions know what to trust. Architecture decisions must be stable before phase 2.
2. **Focused refinement** — work through each category properly, one at a time. Treated as ongoing rather than a hard deadline; refinement is triggered by real friction, not a schedule.
Phase 1 is the planned chunk. Phase 2 is ongoing.
Chunk 6 (tooling) is exempt — it is implementation-driven, not content-driven.
## Plugin marketplace workstream
A parallel workstream (not a numbered chunk) establishing the plugin distribution layer. Runs alongside the chunk sequence.
**Phase 1 — marketplace scaffold and kyberforge plugin** ✅ complete (2026-06-20)
- `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json` — dual-path marketplace manifest (Claude Code + Copilot CLI)
- `plugins/kyberforge/` — marketplace management toolkit: `create-plugin`, `marketplace-architect`, `write-skill`, `write-eval`, `plugin-author`, `marketplace-author` skills, bundled template (`assets/plugin-template/`), reference docs, scripts, and evals
- `templates/plugin/` removed — bundled into `kyberforge` plugin; `docs/research/plugin-marketplace-architecture.md` moved into `plugins/kyberforge/docs/`
- Skills `write-eval`, `write-skill`, `create-plugin`, `marketplace-architect` removed from `.agents/skills/` — now only available via `kyberforge` plugin install
**Phase 2 — remaining skills migrated into plugins** (deferred — no chunk assigned)
- Remaining `.agents/skills/` skills grouped into outcome-based plugins per the ~10–20 plugin target
- Run `/marketplace-architect` to audit and recommend plugin boundaries when ready
## Governance workstream
A parallel workstream (not a numbered chunk) that runs alongside the chunk sequence. Cross-cutting concern — governance rules apply to all chunks.
**Phase 1 — instruction and documentation layer** ✅ complete (before Chunk 3)
- `core/instructions/governance.md` — agent instruction file loaded via `@import` at every session start
- `docs/ai-constitution.md` — full evidence base and governance principles (human-facing)
- `docs/HUMANS.md` — practitioner checklist (human-facing)
- `CONTEXT.md` — extended with governance domain language (HITL, HOTL, sycophancy, data classification tiers, symbolic oversight)
- `docs/VISION.md`, `CLAUDE.md`, `docs/ROADMAP.md` — updated to reflect governance layer existence
- `tests/test-governance-layer.sh` — manual test plan verifying governance rules take effect in a fresh session
**Phase 2 — deterministic enforcement layer** (Chunk 6)
- Pre-commit hooks, CI gates, secret scanning, licence scanning, audit logging infrastructure, human approval gates in CI/CD
- Specification: `docs/research/governance_principles/CONTROLS.md`
**Pre-Chunk 6 test suite work** (no CI required — can be done now; see Gitea issue #2 for full context):
- Fix U1 first: add gitleaks.toml allowlist entry for `docs/research/ai-coding-factory/ai-coding-factory-session.md:90` (`Token routing: Haiku/Sonnet/Opus` triggers `generic-api-key` false positive; pre-commit hook blocks commits on all machines with gitleaks installed)
- `tests/test-plugin-validate.sh` — run `claude plugin validate --strict` on all plugins and marketplace manifests; add the same check to the pre-push hook alongside `check-manifests.sh`
- `tests/test-pre-commit-installed.sh` — verify `.pre-commit-config.yaml` is present and hooks run successfully; validate pre-commit framework integration
- `tests/test-inventory-crossrefs.sh` — run `inventory.sh` against the live repo; assert zero `../` cross-reference warnings in post-refactor skills; triage the 11 current warnings (U4: determine which are in Chunk 3 rebuild targets vs. post-refactor skills that should be self-contained)
- `tests/run-all-tests.sh` — single entry point that runs every test in `tests/`; needed for both developer use and future CI integration
- Extend `test-governance-layer.sh` — add structural checks that CONTROLS.md-required controls are in place (.pre-commit-config.yaml present with gitleaks hook, pre-commit framework installed, plugin validation passes strict mode); current checks verify governance files exist but not that controls are enforced
**Chunk 6 CI gaps** (require CI pipeline; implement during Chunk 6 grill):
- Secret scanning in CI — CONTROLS.md: "Pre-commit hooks can be bypassed; CI cannot. Both layers are required."
- Dependency/security scanning in CI pipeline
- Licence scanning in CI pipeline (must cover code content, not just declared deps — relevant for AI-generated/adopted code)
- Human approval gate in CI/CD for any pipeline applying production changes
- Audit logging for agentic workflows (every state-modifying workflow must produce a tamper-evident log per CONTROLS.md)
## Chunk table
| Chunk | Scope | Why this order |
|---|---|---|
| ✅ 1 | Repo skeleton + `install.sh` — structure in place, Claude Code wired up | Nothing else can be built without the structure and install working |
| ✅ 2 | Core instructions — `coding.md`, `git.md` (incl. conventional commits), `testing.md`; communication rules in `providers/claude-code/CLAUDE.md` always-on section; retire `global.md`; migrate `docs/` to subdirectory-by-type naming | Instructions are the foundation everything else references; commit convention and doc naming must be in place before history accumulates |
| ⏳ 3 | Skills library rebuild — the 12 existing skills are first-draft placeholders that predate the factory research; all are rebuilt or replaced. **Target library:** `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` is the canonical build reference — use it directly for each skill's trigger description, constraints, and category. Core categories: roles (6), design (3), factory (7 meta-skills — entirely new, high priority), implement (4 incl. tdd multi-file), test (3), review (4), deploy (4), operate (4), cross-cutting (4). Global optional: IaC (7) and Gitea (3) — scope defined in Chunk 3 PRD. **Naming convention:** the skills-index uses `category/skill-name` notation (e.g., `design/grill-me`) for identification only; actual paths are flat per ADR-0009 (`grill-me/SKILL.md`), category expressed in SKILL.md frontmatter. **Authoring standard:** see `SKILL-TEMPLATE.md` in `.agents/skills/write-skill/` (authoritative). Frontmatter: `name`, `description`, `metadata.category` only — provenance fields (`version`, `updated`, `when`, `source`, `references`) live in `META.md` per `META-TEMPLATE.md`. Body: 6 sections (Required inputs, Constraints, Process, Output format, Failure handling, Self-check) — Role and When/When not dropped per agentskills.io spec. **Process per skill:** check skills-index for trigger description and constraints → check implementation guidance Section 4–5 for framework sourcing → research/inspect open-source implementations → implement. Delete `ai-coding-factory-skills-index.md` when all skills exist. **Infrastructure complete**: 12 skills deployed to `~/.agents/skills/` via `install.sh`; provider adapter pattern in place. | Skills are the most immediately useful output; the rebuild is necessary because existing skills predate the authoring standard and the factory research |
| 4 | Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns. **Prerequisite:** WorkflowContext schema (what each skill in a chain receives and returns) must be designed before any workflow skill is written; `docs/spec/` must exist (implement-feature constraint: update spec in same PR as behavior change) | Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting |
| 5 | Agents — role skills (Architect, Developer, Reviewer, Security, QA, Ops) in `.agents/skills/` with `category: roles`; `core/agents/` for provider-agnostic subagent definitions needing isolated execution context (`context: fork`), translated to `.claude/agents/` by adapter; cross-project orchestration agents as use case | Role skills benefit from workflow patterns being established first; subagent definitions require the skills library to be stable |
| 6 | Sync + project init tooling — `sync.sh` and `init-project.sh` | Tooling only makes sense once there is content worth syncing and scaffolding |
| 7 | Copilot provider — adapter for GitHub Copilot. **Provider adapter pattern established**: `install.sh` auto-discovers `providers/*/provider-manifest.sh`; Copilot adapter is a new `providers/copilot/provider-manifest.sh` declaring a symlink if needed | Second provider comes after the first is fully proven |
## Development workflow
Every workstream follows this shape. Pick a kick-off type, grill it, then run the implementation loop per issue.
```
Kick-off (pick type)
├── Feature → /grill-with-docs → PRD → /to-issues
├── Bug → /grill-with-docs → Bug Brief → /to-issues → /diagnose
├── Architecture → /grill-with-docs → ARD (+ ADR later) → /to-issues
├── Improvement → /grill-with-docs → PRD or ARD → /to-issues
├── Feedback → /triage → PRD or Bug Brief → /to-issues
└── Ideation → /grill-me → Exploration Note → /to-issues (optional)
Per issue
└── /tdd → implement → automated QA → commit (conventional)
Manual QA — only for nuanced UI/UX or agent interaction behavior
/improve-codebase-architecture — ad hoc or at chunk/PR boundaries, not per issue
Ongoing (ad hoc, within any workstream)
├── /diagnose (unexpected breakage)
├── /prototype (design uncertainty)
└── /zoom-out (orientation)
Finalize (per workstream)
└── update docs → commit
```
This workflow is defined at convention level in Chunk 2. Chunk 4 formalizes it as a composable skill/workflow.
## Open questions / deferred decisions
Items consciously not resolved — to be addressed in the relevant chunk PRD or grill.
| Question | Deferred to |
|---|---|
| How project-level overrides are structured and what they can override | Chunk 6 PRD |
| ~~Deployment manifest seam — `install.sh` embeds source→target mappings implicitly; `sync.sh` will need the same mapping.~~ | ✅ Resolved in Chunk 2 architecture review — extracted to `scripts/deploy-manifest.sh`; `sync.sh` sources the same file in Chunk 6 |
| Feedback intake workflow — where does feedback arrive (GitHub issues, Slack, email)? | Grill before Chunk 4 (workflows) |
| QA agent design — what does automated agent testing look like in practice? | Grill before Chunk 5 (agents) |
| Automated deployment pipeline — CI/CD beyond gitops convention | Chunk 6 grill |
| Formal CI gate for `/improve-codebase-architecture` | Chunk 6 grill |
| ~~Changelog tooling — which generator (git-cliff, conventional-changelog, etc.) and where it runs~~ | ✅ Resolved — Chunk 3 grill. **git-cliff** selected (Rust binary, no runtime deps, Gitea-compatible). `cliff.toml` config in Chunk 3; CI integration in Chunk 6. `review/changelog-entry` skill handles prose release notes where commit messages are insufficient. |
| Content index frontmatter — bidirectional reference convention: files referencing others should carry a `when:` field in frontmatter; the referencing file (e.g. CLAUDE.md content index) and the referenced file should both document the relationship. `.claude/rules/` path-scoped rules resolve the path-based case natively. Reference scanner (reverse map: "what files point to X?") deferred to Chunk 6 tooling. Full `when:` field resolution deferred to Chunk 4+. | Chunk 4+ / Chunk 6 tooling |
| ~~Skill taxonomy — flat vs nested paths, category organisation~~ | ✅ Resolved — factory integration grill. Flat paths (Claude Code + agentskills.io standard enforce one-level-deep discovery). Categories via `metadata: category:` in SKILL.md frontmatter. See ADR-0009. |
| ~~Factory boundary — which factory features belong here vs project repos~~ | ✅ Resolved — factory integration grill. This repo is a provider (ADR-0008). LESSONS.md and docs/spec/ are exceptions: added here because this repo also develops itself. IaC and Gitea skills are global optional. Role skills in .agents/skills/; core/agents/ for subagent definitions (ADR-0010). |
| ~~IaC and Gitea skill scope — which specific skills to include in the global optional set, and in what order~~ | ✅ Resolved — Chunk 3 PRD. IaC in Chunk 3: `write-docker-compose` + `iac-security-review`. Deferred: Ansible, Molecule, Terraform, K8s, Proxmox. Gitea skills moved to `providers/gitea/` provider adapter — not part of the core library. |
| Agent behavior confirmation model — writes/edits/git currently require stating intent + approval before acting. Loosen to autonomy-first once skills and workflows are proven and automated agents replace direct interaction. | Phase 2 refinement (post Chunk 4) |
| ~~CLAUDE.md always-on refinement — security floor (no credentials/auth URLs), scope discipline (no over-engineering), tool preference (Read/Edit over Bash); **plus instruction quality**: current rules are thin one-liners observed in practice to lose to RLHF-trained defaults (verbose responses, validating user positions); fix is specificity, counter-examples, and boundary framing — not accepting violations as expected. Needs its own grill session → PRD before implementation.~~ | ✅ Resolved — Governance workstream Phase 1. `core/instructions/governance.md` loaded via `@import` covers hard prohibitions, data classification, HITL, sycophancy resistance, and deterministic execution preference. Instruction quality principle documented in `CONTEXT.md`. |
## Housekeeping reminders
- **AI coding factory integration** — grill complete. Decision record: `docs/notes/factory-integration-decisions.md`. ADRs: 0008 (factory boundary), 0009 (flat taxonomy), 0010 (role skills vs subagents). Follow-on issues: ~~0013 (LESSONS.md)~~ ✅, ~~0014 (docs/spec/ + VISION.md refactor)~~ ✅. Chunk 3 scope substantially expanded — skills rebuild, new skills, IaC/Gitea skills. See updated chunk table above.
- **`.gitkeep` files** — placeholder files exist in `core/agents/`, `core/workflows/`, `core/prompts/`. Remove each when the first real file is added to that directory. Each `.gitkeep` names the chunk that will populate it. (`docs/notes/.gitkeep` already removed — directory has real content. `docs/ard/.gitkeep` and `docs/bug/.gitkeep` removed 2026-06-21, commit `34c93d9` — directories pending first real ARD and Bug Brief.)
- **Skills pipeline verified** — `install.sh` deploys 13 skills directly to `~/.agents/skills/` and creates `~/.claude/skills/ → ~/.agents/skills/` symlink adapter. Tested idempotent. `skills-lock.json` removed (was a manual artifact). 6 additional skills (`write-eval`, `write-skill`, `create-plugin`, `marketplace-architect`, `plugin-author`, `marketplace-author`) are in the `kyberforge` plugin — install separately via `claude plugin install kyberforge@holocron`. If `~/.claude/skills/` exists as a real directory on a machine being migrated, remove it manually and re-run install.
- **Chunk 2 behavioral tests** — run and fully resolved 2026-05-17. 7/8 pass; scenario 4 (push confirmation) inconclusive — no remote in test environment, rule tightened but unverified. All fixable failures addressed: rule specificity in `providers/claude-code/CLAUDE.md`; context-loading guarantee via `@import CONTEXT.md` in repo CLAUDE.md; standing rule in CONTEXT.md to check `docs/adr/` and ROADMAP resolved entries before answering design questions. Chunk 2 ✅ complete.
- **Governance Phase 1 behavioral tests** — run 2026-05-17. 3/4 testable scenarios pass. Secrets rule gap fixed (2026-05-17): extended to cover credential reproduction in response text and examples, with placeholder requirement added to `core/instructions/governance.md`. HITL scenario not testable in this environment (Nginx not installed); HITL gap evidenced by instructions test scenario 4 — push confirmation rule fix addresses the same root cause. Governance Phase 1 ✅ complete.
- **AI ethics/security workstream** — `docs/notes/ai-ethics-security-principles.md` exploration note is superseded. Governance Phase 1 (`core/instructions/governance.md`) covers all planned scope: credentials, data classification, HITL, scope discipline, agent autonomy, transparency, and security code review. Tier-placement architectural question resolved by the `@import` always-on model. No separate workstream needed.
- **Chunk 3 grill complete** — 2026-05-17. PRD at `docs/prd/chunk-3-skills-library.md`. Key decisions: 42-skill target library, AGENTS.md refactor as prerequisite issue (both CLAUDE.md files become thin adapters), git-cliff for changelog, provider-agnostic issue tracker abstraction, grill-me/grill-lean design phase split, factory bootstrap order (write-eval → write-skill → write-docs phase 2 → write-adr → remaining factory → design → parallel category groups). ADRs written: 0011 (provider-agnostic issue tracker), 0012 (AGENTS.md governance entry point, partially supersedes ADR-0005). Upstream review cadence: per-skill + quarterly post-roadmap (per-chunk-start changed to per-skill by issue 0016 grill). **Issues created 0015–0028** — all HITL; ~~0015 (AGENTS.md refactor, prerequisite)~~ ✅, ~~0016 (skill workflow grill, produces conventions for 0017–0028)~~ ✅, ~~0017 (bootstrap skill: write-eval)~~ ✅ HITL complete (HOTL 2026-05-26), ~~0018 phase 1 (write-skill)~~ ✅ HITL complete (HOTL 2026-05-26), ~~0018 phase 2 (write-docs — first factory-authored skill)~~ ✅ HITL complete (HOTL 2026-05-26), **0018 phase 3** (doc convention — open, do before 0019), 0019 (remaining factory skills), 0020–0027 (design/implement/test/review/deploy/operate/iac/cross-cutting), 0028 (chunk closure). ~~Acceptance criteria for 0017–0028 to be refined after 0016 grill session.~~ ✅ Refined 2026-05-17 — see `docs/notes/skill-implementation-workflow.md`.
- **Test suite audit (2026-06-21)** — full automated check run via 6 parallel subagents. All 77 existing test cases pass. Three fixes applied and committed (`ce7dd15`, `247bd4a`, `a3ff72c`): shellcheck `-x` flag + `source=` path correction in `install.sh` (SC2115 + SC1091 pre-hook blocker), kyberforge plugin version field, `agents/README.md` moved to `docs/adding-agents.md`. One additional gap found and fixed during commit flow: `setup-hooks.sh` was calling `shellcheck` without `-x`. Four untracked issues remain (U1–U4) and seven test-suite structural gaps identified against `docs/research/governance_principles/CONTROLS.md` — none blocking Chunk 3 work. Full details in Gitea issue #2. Pre-Chunk 6 test work itemised in the Governance workstream section above.
- **Pre-0019 cleanup (do before starting 0019):** Three items from 0018 open threads that must be resolved before the remaining factory skills are built with `write-skill`:
1. **0018 phase 3** — `/grill-me` → `docs/notes/doc-convention.md` → update `write-docs` output format → `CONTEXT.md` if convention becomes a standing principle. Tracked in `docs/issues/0018-factory-write-skill.md` acceptance criteria.
2. **write-eval refactor** — bring `write-eval` to the 6-section / META.md standard (currently follows the old 8-section format with provenance fields in SKILL.md frontmatter). Now lives at `plugins/kyberforge/skills/write-eval/SKILL.md`. Open thread from 0018 handoff note #4. Use `write-skill` (also in `kyberforge` plugin) to author the refactored version.
3. **Eval updates** — after write-eval refactor settles, run `write-eval` against `write-skill` and `write-eval` themselves to extend coverage. Evals now at `plugins/kyberforge/tests/evals/write-skill/eval.yaml` and `plugins/kyberforge/tests/evals/write-eval/eval.yaml`.
- Note: `write-docs` standard conformance (no META.md, old section structure) is deferred to 0028 (chunk closure) per open thread #5 in 0018 handoff.
docs/VISION.md
+5 -5
View File
@@ -19,8 +19,8 @@ Designed to start as a personal homelab tool and grow into something shareable w
- Automatic push-based sync to projects
- Runtime dependency from projects back to this repo
- Bootstrapping new projects (`init-project.sh` comes in chunk 6)
- GitHub Copilot support (chunk 7)
- Bootstrapping new projects (`init-project.sh` — not yet built)
- GitHub Copilot support (not yet built)
## Current architecture
@@ -30,9 +30,9 @@ See `docs/spec/architecture.md` for the deployed directory structure, content de
V1 is "ready to develop" — not a finished product. It means this repo is structured, Claude Code is wired up to it, and there is enough initial content to start building incrementally.
**V1 = Chunk 1 complete — ✅ done.**
**V1 = core install pipeline complete — ✅ done.**
Everything from chunk 2 onward is content and tooling built on top of that foundation.
All content and tooling is built incrementally on top of that foundation via plugins.
## Long-term: Management Application
@@ -56,7 +56,7 @@ Browse, edit, and configure AI development config through a proper product UI.
- Hosting: self-hosted first, cloud-hosted option later
- Users: solo-first, multi-user-ready data model from day one
**Start trigger:** after Chunk 6 of this repo (`sync.sh` + `init-project.sh`). Full content model and sync tooling must be stable before building a UI over them.
**Start trigger:** when the plugin content model and sync tooling are stable. Full content model must be stable before building a UI over it.
**Mobile/desktop (Phase 3):** React → React Native for mobile; Tauri to wrap the web app for desktop.
docs/adr/0001-pull-distribution-model.md
-3
View File
@@ -1,3 +0,0 @@
# Pull distribution model
Projects pull config updates from this repo consciously rather than receiving automatic pushes. We chose pull because it keeps projects in control of when they take updates — a silent push could break a project mid-sprint with no warning. Pull also scales cleanly from solo homelab to open source: anyone can fork this repo and projects remain decoupled from the origin. The trade-off is that stale projects are invisible until they pull; push would make fleet drift detectable earlier, which is why fleet sync tooling (Phase 2) revisits this at the network layer, not at the file distribution layer.
docs/adr/0001-skills-in-agents-dir.md
+15
View File
@@ -0,0 +1,15 @@
# Skills are distributed via plugins, not monolithic repo deployment
Skills (slash commands) are authored and distributed as part of **plugins** — each plugin contains its own `skills/` directory alongside agents and other artifacts. Plugins are installed via `claude plugin install <name>@holocron` rather than deployed from the repo's local tree. This decision decouples skill authoring cadence from core provider deployments and allows independent versioning per plugin.
## Context
Initially, skills were stored in a single `.agents/skills/` directory and deployed universally via `install.sh`. This created a coupling problem: shipping a new skill required shipping an entire repo release, and skill updates were pinned to provider version releases. As the skill library grew, independent skill shipping became essential.
## Consequences
- Skills are now co-located with their associated agents and infrastructure in `plugins/<name>/`. Logically related skills ship together; independent skills can ship on independent cadences.
- `claude plugin install` handles installation, versioning, and updates — no need for shell deployment logic in `install.sh`.
- Repositories that use skills from this project declare plugin dependencies in their `claude.plugin.json` manifest or install via the CLI.
- Providers that do not natively understand `claude plugin install` (hypothetically) would need a custom adapter to fetch from the Holocron marketplace — deferred concern, not yet needed.
- A skill in one plugin does not block a breaking change in another plugin.
docs/adr/0002-copy-not-symlink.md
-3
View File
@@ -1,3 +0,0 @@
# Copy files, not symlinks or submodules
Content is deployed by copying files, not symlinking or using git submodules. Symlinks break if this repo moves or is renamed; submodules require git tooling everywhere a project runs — including on machines where this repo may not be cloned at all. Copying means a deployed project works in complete isolation from this repo's location or existence. The cost is that updates are opt-in (consistent with ADR-0001) and no automatic change detection exists. This is intentional: silent changes are a worse failure mode than stale configs.
docs/adr/0005-two-tier-claude-md.md → docs/adr/0002-two-tier-claude-md.md
View File
File renamed without changes.
docs/adr/0012-agents-md-provider-agnostic-entry-point.md → docs/adr/0003-agents-md-provider-agnostic-entry-point.md
+3 -3
View File
@@ -4,8 +4,8 @@
Claude Code reads `CLAUDE.md` natively, not `AGENTS.md`. The Anthropic documentation explicitly recommends the import pattern for repos that use `AGENTS.md` for other tools: `CLAUDE.md` contains `@AGENTS.md` and appends Claude Code-specific content below. This means `CLAUDE.md` continues to exist as the Claude Code entry point but carries no original content — it is purely an adapter.
`AGENTS.md` must be self-contained: no `@import` syntax (which is Claude Code-specific and would make the file provider-specific). On-demand instruction loading via `@import` stays in the Claude Code adapter (`CLAUDE.md`), pointing to `core/instructions/` as today. The `core/` deployment path (`~/.claude/core/`) is unchanged in this chunk; migration to `~/.agents/` is deferred to Chunk 7 when a second provider (Copilot) provides evidence of what that provider needs.
`AGENTS.md` must be self-contained: no `@import` syntax (which is Claude Code-specific and would make the file provider-specific). On-demand instruction loading via `@import` stays in the Claude Code adapter (`CLAUDE.md`), pointing to `core/instructions/` as today. The `core/` deployment path (`~/.claude/core/`) reflects the current provider deployment model.
This partially supersedes ADR-0005 (two-tier CLAUDE.md model). ADR-0005 established the always-on / on-demand split and remains correct as a structural pattern. What changes is where the always-on content lives: previously in `providers/claude-code/CLAUDE.md`, now in `AGENTS.md`. The adapter layer ADR-0005 described still exists; `CLAUDE.md` is now the adapter rather than the source.
This partially supersedes ADR-0002 (two-tier CLAUDE.md model). ADR-0002 established the always-on / on-demand split and remains correct as a structural pattern. What changes is where the always-on content lives: previously in `providers/claude-code/CLAUDE.md`, now in `AGENTS.md`. The adapter layer ADR-0002 described still exists; `CLAUDE.md` is now the adapter rather than the source.
The alternative — keeping always-on content in `providers/claude-code/CLAUDE.md` — was rejected because it violates ADR-0003 (provider-agnostic core). Content that applies to all agents regardless of provider has no business living in a provider-specific file. When Copilot arrives in Chunk 7, duplicating that content into a Copilot adapter or maintaining two sources of the same rules is exactly the drift ADR-0003 was written to prevent.
The alternative — keeping always-on content in `providers/claude-code/CLAUDE.md` — was rejected because it violates the provider-agnostic principle: content that applies to all agents regardless of provider has no business living in a provider-specific file. When multiple providers exist, duplicating that content into a separate adapter or maintaining two sources of the same rules creates drift and inconsistency.
docs/adr/0003-provider-agnostic-core.md
-3
View File
@@ -1,3 +0,0 @@
# Provider-agnostic core with thin adapters
`core/` uses plain imperative markdown — no tool names, provider APIs, or format assumptions. Provider-specific translations live in `providers/<name>/`. The alternative was provider-specific content everywhere, which means adding a second provider (Copilot, Cursor) requires rewriting all content from scratch rather than writing a thin adapter. The cost is a translation layer: content must be kept abstract enough to survive adaptation, which sometimes means less tool-specific precision in the core. Where precision matters more than portability, it belongs in `providers/`, not `core/`.
docs/adr/0014-skill-audit-info-finding-level.md → docs/adr/0004-skill-audit-info-finding-level.md
View File
File renamed without changes.
docs/adr/0004-skills-in-agents-dir.md
-5
View File
@@ -1,5 +0,0 @@
# Skills live in .agents/skills/, not .claude/skills/
Skills (slash commands) are stored in `.agents/skills/` following the [Agent Skills open standard](https://agentskills.io), not in `.claude/skills/` which is a Claude Code-specific location. Putting skills in `.claude/skills/` would make them Claude Code-only and contradict ADR-0003 (provider-agnostic where possible). Skills are the strongest shared primitive across providers — they should live at the most portable location available.
`install.sh` deploys skills to `~/.agents/skills/` as the single canonical location. Providers that do not read `~/.agents/skills/` natively declare a symlink adapter in `providers/<name>/provider-manifest.sh`; `install.sh` discovers and creates these automatically. Claude Code is one such provider — it reads `~/.claude/skills/` natively, so it gets a `~/.claude/skills/ → ~/.agents/skills/` symlink. See ADR-0007 for the rationale behind using symlinks for provider adapters.
docs/adr/0015-agent-author-dual-provider-scaffold.md → docs/adr/0005-agent-author-dual-provider-scaffold.md
+5
View File
@@ -39,3 +39,8 @@ separate single-provider skill, adding complexity with no benefit.
- The file-by-file no-op in the script (skip existing files rather than
overwriting) means partial state — one provider file exists, the other does not —
is handled by routing in the skill body, not in the script.
**Update (ADR-0010):** the `agents/sources.md` path above is superseded. The provenance
file now lives at `<plugin-root>/sources.md`, outside the `agents/` directory, because
`claude plugin validate --strict` auto-discovers every `.md` under `agents/` as an agent
requiring frontmatter. See ADR-0010 for the empirical finding and rationale.
docs/adr/0006-install-always-overwrites.md
-5
View File
@@ -1,5 +0,0 @@
# install.sh always overwrites deployed files
`install.sh` overwrites `~/.claude/` and `~/.claude/core/` unconditionally on every run. It does not merge, diff, or ask. The rationale: the source of truth is this repo. Editing deployed files directly is a usage error — `sync.sh` would overwrite those edits on the next pull anyway. Offering a merge path would imply that editing `~/.claude/CLAUDE.md` directly is a supported workflow, which it is not. If a local customisation is needed it belongs in a project-level override file, not in the deployed global config.
**Exception — skills**: `~/.agents/skills/` uses a merge-per-skill strategy. Each skill directory from `.agents/skills/` is replaced individually; the parent directory is never wiped. This preserves user-installed skills from other sources alongside the skills managed by this repo. The overwrite-always principle still holds for each individual managed skill — the per-skill replace is unconditional.
docs/adr/0016-plugin-version-parity.md → docs/adr/0006-plugin-version-parity.md
View File
File renamed without changes.
docs/adr/0017-gitea-canonical-issue-tracker.md → docs/adr/0007-gitea-canonical-issue-tracker.md
+2
View File
@@ -1,5 +1,7 @@
# Gitea is the exclusive issue tracker — file-based fallback removed
**Supersedes:** ADR-0011 (provider-agnostic issue tracker with file-based default — archived during refactoring)
ADR-0011 established a provider-agnostic model with `docs/issues/NNNN-<slug>.md` as the file-based default, switching to Gitea MCP at runtime when available. The interim model was justified because Gitea would not be configured until after Chunk 3, and the repo needed to work before then.
Gitea is now configured and in active use. The condition in ADR-0011 has been met. This ADR supersedes it.
docs/adr/0007-provider-adapters-as-symlinks.md
-9
View File
@@ -1,9 +0,0 @@
# Provider skill adapters are symlinks, not copies
Provider skill adapters — the mechanism that makes `~/.agents/skills/` visible to a provider that reads a different path — are implemented as symlinks, not file copies. This is a deliberate exception to ADR-0002 (copy-not-symlink), which applies to content files. Adapters are infrastructure, not content.
**Why symlinks here:** a provider adapter has no content of its own — it is purely a pointer to the canonical location. Copying would create a second source of truth and require install.sh to keep two directories in sync; any drift between them would be a silent bug. A symlink makes the relationship explicit and eliminates the sync problem entirely.
**Why ADR-0002 still holds for content:** ADR-0002's concern is that symlinks break if this repo moves. Provider adapters point to `~/.agents/skills/`, not into this repo — they survive repo relocation without modification.
Each provider that cannot read `~/.agents/skills/` natively declares its adapter path in `providers/<name>/provider-manifest.sh`. `install.sh` discovers all provider manifests and creates the symlinks. A provider that reads `~/.agents/skills/` natively needs no entry. If the adapter target already exists as a real directory, install.sh emits a warning and leaves it intact rather than destroying user data.
docs/adr/0008-agent-audit-single-file-invocation.md
+16
View File
@@ -0,0 +1,16 @@
# agent-audit takes a single file path and derives the counterpart by scope detection
`agent-audit` validates agent definition file pairs (Claude Code `.md` + Copilot `.agent.md`). The skill accepts a path to either file and derives the counterpart using scope detection rather than requiring the caller to name both files or supply a root directory.
## Considered options
**Directory input (rejected)** — analogous to `skill-audit <skill-dir>`. Rejected because agents have no per-agent directory. At plugin scope both files are flat in `agents/`; at project scope they are in completely different directories (`.claude/agents/` and `.github/agents/`). No single directory contains both files across all scopes.
**`<name> <root>` signature (rejected)** — mirrors `new-agent.sh <name> <root>`. Rejected because it requires the caller to supply two pieces of information when one (the file path) is sufficient. The file path already implies the agent name (filename stem) and the root (found by walking up). Forcing the caller to re-supply what the script can infer is the kind of convention knowledge the script exists to encapsulate.
## Consequences
- The unit of validation is the pair. A missing counterpart is always a FAIL — an orphan file is incomplete by definition.
- Scope detection walks up from the input file: first directory containing `plugin.json` → plugin scope; first directory containing `.git` without `plugin.json` → project scope; path under `~` with neither → user scope.
- At user scope the derivation crosses filesystem locations (`~/.claude/agents/` ↔ `~/.copilot/agents/`); the script must handle the home directory case explicitly.
- The invocation signature is the public contract. Changing it is a breaking change to any caller — treat it as such.
docs/adr/0008-factory-boundary.md
-7
View File
@@ -1,7 +0,0 @@
# This repo is a provider of factory tooling, not a factory instance
This repo ships skills, governance, and conventions to project repos — it does not itself adopt the full factory structure (LESSONS.md, docs/spec/, eval infrastructure, references/) as if it were a software project using the factory. Conflating the two layers would mix config-delivery concerns with application concerns, make the repo harder to upgrade (changes to the factory shape would break all consumers simultaneously), and obscure what is a global primitive vs. what is project-specific.
Exception: artefacts also needed while building *this repo itself* are added here in addition to being scaffolded for project repos. LESSONS.md and docs/spec/ qualify — this repo undergoes active development and benefits from the same feedback and spec hygiene it ships to others. This exception is bounded: it applies only when the artefact genuinely serves the repo's own development, not to import the full factory shape by default.
Orchestration agents (cross-project automation) are a natural future extension at Chunk 5, not a reason to change the provider boundary now.
docs/adr/0009-agent-audit-field-inventory-reference.md
+30
View File
@@ -0,0 +1,30 @@
# agent-audit reads field lists from a reference file, not hardcoded script arrays
`agent-audit`'s `validate.sh` checks for Claude Code-only fields in Copilot files and
silently-ignored fields in plugin agents. Rather than hardcoding those field lists in the
script, the script reads `references/field-inventory.md` at runtime. This keeps field list
maintenance decoupled from script logic and preserves a provenance chain back to the
research corpus that sourced the lists.
## Considered options
**Hardcode in validate.sh (rejected)** — field lists live as literal arrays in the
bash/python script. Rejected because: (1) the lists came from research docs
(`claude-code-plugins/agent-definition.md` and `github-copilot-plugins/agent-definition.md`)
and should maintain a provenance chain back to those sources via `source_keys` frontmatter;
(2) both provider APIs evolve — updating a structured markdown file is lower friction than
editing a script and less likely to introduce bugs; (3) it breaks the bidirectional reference
principle already established for this repo, where research-derived content carries explicit
source attribution.
## Consequences
- `validate.sh` must parse `references/field-inventory.md` to extract field lists — the
file format must be machine-parseable (section headings the script can grep, or a simple
list structure).
- `field-inventory.md` carries `source_keys` frontmatter referencing
`claude-code-plugins-docs` and `github-custom-agents-configuration` slugs.
- The script exits with a clear error if `references/field-inventory.md` is not found —
fail-fast, not silent.
- Field list updates (new provider field, deprecated field) require only editing
`field-inventory.md`; no script change needed.
docs/adr/0009-flat-skill-taxonomy.md
-7
View File
@@ -1,7 +0,0 @@
# Flat skill directories with category metadata, not nested paths
Skills are stored as flat directories directly under `.agents/skills/` (`grill-me/SKILL.md`, not `design/grill-me/SKILL.md`). Category organisation is expressed via `metadata: category:` in each SKILL.md frontmatter rather than directory nesting.
Nested paths were evaluated and rejected for three reasons. First, Claude Code discovers skills exactly one level deep under `~/.claude/skills/` — a skill at `~/.claude/skills/design/grill-me/SKILL.md` is invisible to the tool. Second, the agentskills.io open standard specifies that the `name` field must match the parent directory name, implying a flat structure at the skills root; no nested discovery is defined in the spec. Third, `install.sh` iterates `for skill_dir in .agents/skills/*/` — one level only; nested paths would require a traversal rewrite before a single nested skill could be deployed.
Category metadata achieves the same organisational goals: the Management App can group skills by category, a generated README can cluster them, and the category is machine-readable for tooling — all without path changes, pipeline changes, or deviation from the open standard. If Claude Code adds nested discovery in a future release, paths can be restructured then with evidence rather than speculatively now.
docs/adr/0010-agent-sources-relocated-outside-agents-dir.md
+58
View File
@@ -0,0 +1,58 @@
# Plugin-scope agent provenance file moves to `<plugin-root>/sources.md`
**Partially supersedes:** ADR-0005 (agent-author dual-provider scaffold) — specifically the
claim that "both files share a single `agents/sources.md` for provenance." The rest of
ADR-0005 (dual-provider generation, scope detection, single-root script interface) is
unaffected and remains in force.
`claude plugin validate --strict` auto-discovers every `.md` file directly under a plugin's
`agents/` directory and treats it as an agent definition requiring YAML frontmatter (`name`,
`description`, etc.). A flat provenance file at `agents/sources.md` — no frontmatter, by
design, since it is not an agent — fails validation with a missing-frontmatter warning that
`--strict` promotes to an error.
This was first hit in `plugins/git/agents/sources.md` (added by the git-plugin skill suite).
It failed the `validate-plugins` pre-push hook. The stopgap in commit `0239b00` added
throwaway agent frontmatter to unblock the push:
```yaml
---
name: git-agents-sources
description: Provenance record for the git plugin's agents, not an invokable agent. Do not invoke.
tools: none
---
```
That workaround is now reverted — the file no longer lives where it needs to impersonate an
agent to pass validation.
## Considered options
**Exclude via an explicit `agents` manifest array (rejected)** — `plugin.json` supports
`"agents": ["./agents/reviewer.md"]` as an alternative to `"agents": "agents/"`. The
hypothesis was that listing only real agent files would stop the validator from also
discovering `sources.md` in the same directory. Tested empirically on a scratch copy of the
git plugin: `claude plugin validate --strict` still auto-discovered and failed on the
unlisted `sources.md`, regardless of the explicit array. The manifest field controls what
Claude Code loads as agents at runtime; it does not control what the validator scans on
disk. There is no manifest-level or CLI-flag mechanism to exclude a file from `agents/`
auto-discovery.
**Keep the frontmatter workaround permanently (rejected)** — cheapest fix, already applied,
but semantically wrong: it makes a plain provenance record indistinguishable from a real
invokable agent to any tooling or UI that lists available agents (e.g. it could appear as a
callable agent in the `/agents` picker), which is confusing and incorrect.
## Consequences
- The provenance file moves to `<plugin-root>/sources.md` — a flat file, plugin-root
relative, sitting outside any directory that Claude Code or its validator auto-scans. No
frontmatter is needed or added.
- `agent-author`'s `new-agent.sh` now writes `<root>/sources.md` instead of
`<root>/agents/sources.md` at plugin scope.
- `agent-audit`'s `validate-provenance.sh` now looks for `<plugin-root>/sources.md` when
checking `source_keys` provenance chains.
- All doc and template references to `agents/sources.md` (agent-author `SKILL.md`,
agent-audit `SKILL.md`/`README.md`, both provider templates) are updated to `sources.md`.
- `plugins/git/agents/sources.md` is relocated to `plugins/git/sources.md` and the
`0239b00` frontmatter workaround is removed.
docs/adr/0010-role-skills-vs-subagents.md
-7
View File
@@ -1,7 +0,0 @@
# Role skills in .agents/skills/, core/agents/ reserved for subagent definitions
Role skills (Architect, Developer, Reviewer, Security, QA, Ops) live in `.agents/skills/` with `category: roles`. They are ordinary skills that activate a cognitive mode in the current conversation — loaded on trigger, follow the standard SKILL.md authoring format, and use the same deployment pipeline as every other skill. Placing them in a separate `core/agents/` directory would require a distinct deployment path, a distinct provider adapter, and a distinct discovery mechanism for no functional gain.
`core/agents/` is reserved for a distinct content type: provider-agnostic subagent definitions that run in isolated execution contexts (`context: fork` in Claude Code terms). These are skills or agents that need a fresh context window, a dedicated system prompt, and no access to the parent conversation history. The Claude Code adapter translates `core/agents/` definitions to `.claude/agents/`. This is structurally different from a role skill that loads inline — the isolation boundary is the defining characteristic, not the cognitive mode.
The factory research conflates these two into a single `roles/` skill category. The distinction matters here because Claude Code's subagent execution model is meaningfully different from skill activation, and the provider adapter pattern requires them to be in separate source locations to translate correctly.
docs/adr/0011-gitea-skill-deep-modules.md
+109
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.
docs/adr/0011-provider-agnostic-issue-tracker.md
-11
View File
@@ -1,11 +0,0 @@
# Provider-agnostic issue tracker with file-based default and provider adapters
Skills and workflows reference a "linked issue" generically rather than coupling to a specific issue tracker. In the file-based phase, an issue is a `docs/issues/NNNN-<slug>.md` file. When a provider MCP (e.g. Gitea MCP) is configured, skills detect it at runtime and use it instead. The active backend is determined by MCP availability — no config flag required. "Issue" is the canonical cross-provider term; GitHub, GitLab, and Gitea all use it natively.
Gitea-specific skills (`setup-gitea-mcp`, `post-pr-review`, `create-issue`) are a provider adapter at `providers/gitea/` — structurally identical to how `providers/claude-code/` adapts core content for Claude Code. They are not part of the core skill library.
Two alternatives were rejected. Gitea-specific skills in the core library would block use before Gitea is configured and embed a provider assumption into skills that are otherwise provider-neutral. Per-provider skill variants (e.g. `implement-feature` + `implement-feature-gitea`) create maintenance overhead with no functional gain — the only difference is the issue lookup mechanism, not the skill logic.
The file-based default was chosen because this repo must work before Gitea is set up. File-based issues are already the working convention (`docs/issues/`), established in Chunk 1. Gitea is the first concrete provider and will be configured after Chunk 3; existing file-based issues will be migrated at that point.
This decision makes the skills library usable on any machine without external service dependencies, while keeping Gitea integration as a first-class path once available. The provider adapter pattern (`providers/gitea/`) is consistent with ADR-0007 (provider adapters as symlinks) and ADR-0008 (factory boundary).
docs/adr/0012-agentsmd-tooling-in-core-plugin.md
+16
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.
docs/adr/0013-skill-author-merge.md
-16
View File
@@ -1,16 +0,0 @@
# Merge skill-write and skill-improve into skill-author
The kyberforge plugin shipped a factory trio: `skill-write` (create), `skill-improve` (apply signals), `skill-audit` (review). Write and improve both embed authoring quality guidance inline. As standards evolve — agentskills.io spec updates, shared scripts, future governance rules — each change requires updating both skills. Plugin cache isolation makes shared reference files unworkable: `../` paths break when a plugin is copied to its install cache, and the spec explicitly prohibits cross-skill file sharing. We therefore merge `skill-write` and `skill-improve` into a single `skill-author` skill.
## Considered options
**Mirror shared files (rejected)** — duplicate `references/body-discipline.md` and any shared scripts into both skill directories with a mirror comment, relying on convention to keep them in sync. Rejected because it compounds as standards grow: every new governance rule, every spec change, requires updating two files with no enforcement mechanism. The maintenance surface is small today but was judged unacceptable as a permanent pattern.
**Status quo (rejected)** — accept that the two skills embed divergent authoring guidance. Rejected because the divergence is already observable: audit/improve loops oscillate (improve applies criteria slightly different from audit's, producing new findings on re-audit). Adding governance rules to both skills independently would worsen this.
## Consequences
- `skill-write` and `skill-improve` are deleted; invocations of `/skill-write` and `/skill-improve` break — users must switch to `/skill-author`.
- `skill-audit`'s report footer references `/skill-improve`; that reference is now stale. Update deferred to a follow-on issue.
- `skill-author` uses auto-detect routing: no existing directory → create flow; existing directory + improvement signals → improve flow; existing directory but no signals → ask.
- Shared scripts (`scripts/new-skill.sh`), reference files, templates, and tests live in one directory. Future governance rules and spec updates have a single target.
docs/adr/0013-vale-harness-scope-and-rule-sources.md
+121
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.
docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
+188
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.
docs/notes/factory-integration-decisions.md
+1 -2
View File
@@ -92,7 +92,6 @@ Evals require a runner to be meaningful. Chunk 3 ships skills without evals; the
Both this repo and project repos get `docs/spec/`. The distinction from VISION.md:
- `docs/VISION.md` — goals, intent, long-term roadmap (stable)
- `docs/spec/overview.md` — current deployed state, what works today (updated with each chunk)
- `docs/spec/architecture.md` — current directory structure, install behavior, provider model as-deployed
VISION.md is refactored in issue 0014 to goals/intent only; architecture content moves to `docs/spec/`. The `implement-feature` skill constraint: update `docs/spec/` in the same PR as any behavior change.
@@ -147,7 +146,7 @@ IaC skills (category: `iac`) and Gitea integration skills (category: `gitea`) li
| Chunk | Change |
|---|---|
| **2 follow-on** | Add issues 0013 (LESSONS.md) and 0014 (docs/spec/ + VISION.md refactor) |
| **3** | Scope substantially expanded — see ROADMAP.md |
| **3** | Scope substantially expanded — see Gitea milestone "Skills & Agents" |
| **4** | WorkflowContext schema is a design prerequisite; docs/spec/ must exist before workflows reference it |
| **5** | Role skills in `.agents/skills/` (category: roles); `core/agents/` for subagent definitions |
| **6** | Eval runner, backfill, project LESSONS.md template, project docs/spec/ template, references/ template |
docs/notes/factory-research-gaps-conflicts.md
+1 -1
View File
@@ -49,7 +49,7 @@ Factory treats `LESSONS.md` as a required committed file — the mechanism for l
### 3.2 `docs/spec/` living spec layer
Factory requires `docs/spec/overview.md` and `docs/spec/architecture.md` — a spec that is updated in the same PR as any behaviour change. The current docs structure has no equivalent layer; workflow artifacts go in `docs/prd/`, `docs/ard/`, etc. Adding `docs/spec/` is additive (not conflicting), but it changes the docs convention and needs to be decided before Chunk 4 (workflows) defines workflow artifacts.
Factory requires `docs/spec/architecture.md` — a spec that is updated in the same PR as any behaviour change. The current docs structure has no equivalent layer; workflow artifacts go in `docs/prd/`, `docs/ard/`, etc. Adding `docs/spec/` is additive (not conflicting), but it changes the docs convention and needs to be decided before Chunk 4 (workflows) defines workflow artifacts.
### 3.3 Session handoff skill (impacts Chunk 3)
docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md
+1 -1
View File
@@ -419,7 +419,7 @@ Goal: A working factory skeleton that a real task can be run through end-to-end.
1. Commit `AGENTS.md` — merge existing governance content; validate against principles doc
2. Generate `CONTEXT.md` — manually populate shared vocabulary (10–15 domain terms to start)
3. Create `docs/spec/overview.md` and `docs/spec/architecture.md` — initial living spec, even if sparse
3. Create `docs/spec/architecture.md` — initial living spec, even if sparse
4. Create `docs/adr/` with an `adr-template.md`
5. Implement Phase 1 skill set (7 files):
- `roles/architect`, `roles/developer`, `roles/reviewer`
docs/spec/architecture.md
+14 -50
View File
@@ -1,79 +1,45 @@
# Architecture
Current deployed architecture. Updated in the same PR as any structural change.
## Layered model
```
this repo (global defaults)
├── install.sh → ~/.agents/skills/ (canonical skills location)
├── install.sh → ~/.claude/skills/ (symlink → ~/.agents/skills/, Claude Code adapter)
└── install.sh → ~/.claude/ (Claude Code config + content)
└── scripts/install.sh → ~/.claude/ (Claude Code config + content)
project repo (local overrides)
└── .claude/settings.json, CLAUDE.md (overrides global)
```
Projects consume from this repo by pulling updates via `sync.sh` (Chunk 6). Until then, install is a one-time manual step.
## Directory structure
```
ai-development/
├── AGENTS.md # Provider-agnostic always-on rules for this repo; imported by repo CLAUDE.md
├── CONTEXT.md # Domain language, principles, glossary; auto-loaded at session start
├── docs/ # Workflow artifacts and issues (prd/, ard/, bug/, notes/, adr/, issues/, spec/) + research/ (raw research audit trail)
├── .agents/ # Agent Skills standard location (provider-agnostic)
│ ├── skills/ # SKILL.md files — canonical source, deployed to ~/.agents/skills/
│ └── evals/ # eval.yaml files for skills not yet in a plugin (cross-cutting/, implement/)
├── .claude-plugin/ # Marketplace manifest (both Claude Code and Copilot CLI read here)
│ └── marketplace.json # Declares all installable plugins in this repo
├── .github/plugin/
│ └── marketplace.json # Mirror of .claude-plugin/marketplace.json for Copilot CLI canonical path
├── plugins/ # Installable plugin units (each is a self-contained deployable)
│ └── kyberforge/ # Marketplace management toolkit (create-plugin, marketplace-architect, write-skill, write-eval)
├── core/ # Provider-agnostic source of truth
│ ├── AGENTS.md # Global always-on rules (Communication + Behavior); deployed to ~/.agents/AGENTS.md
│ ├── instructions/ # AI behavior definitions (plain markdown)
│ ├── agents/ # Agent role definitions
│ ├── workflows/ # Workflow definitions
│ └── prompts/ # Reusable prompt templates
├── providers/ # Provider-specific adapters
│ ├── claude-code/ # CLAUDE.md (thin adapter), settings.json, provider-manifest.sh
│ └── copilot/ # copilot-instructions.md, hooks, agents adapter
└── scripts/
├── deploy-manifest.sh # Source→target mappings; sourced by install.sh and sync.sh
├── install.sh # Deploys to ~/.agents/skills/, ~/.claude/, etc.
├── sync.sh # Pulls updates into an existing project
└── init-project.sh # Bootstraps a new or existing project
```
## Content deployment model
`install.sh` is a **deployer**, not a composer. It does not concatenate content into a single file. Instead:
`scripts/install.sh` is a **deployer**, not a composer. It sources `scripts/deploy-manifest.sh` and deploys three categories:
- `.agents/skills/` → `~/.agents/skills/` — canonical skills location; each skill dir is replaced individually (parent not wiped, user-added skills preserved)
- `core/AGENTS.md` → `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`
- Provider adapters declared in `providers/*/provider-manifest.sh` — symlinks from the provider's skill path to `~/.agents/skills/`; e.g. Claude Code gets `~/.claude/skills/ → ~/.agents/skills/` because it reads `~/.claude/skills/` natively. Providers that read `~/.agents/skills/` directly need no adapter.
- `core/` → `~/.claude/core/` — workflows, prompts, agent definitions; agent reads on demand
- `providers/claude-code/settings.json` → `~/.claude/settings.json`
- `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md` — thin adapter: imports `~/.agents/AGENTS.md` and `governance.md`; no original content
- **Files** (`DEPLOY_FILES`): `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md`; `providers/claude-code/settings.json` → `~/.claude/settings.json`; `core/AGENTS.md` → `~/.agents/AGENTS.md`
- **Executables** (`DEPLOY_EXECUTABLES`): `providers/claude-code/statusline-command.sh` → `~/.claude/statusline-command.sh` (with `+x`)
- **Directories** (`DEPLOY_DIRS`): `core/` → `~/.claude/core/` (destination fully replaced on each deploy)
Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately via `claude plugin install <name>@holocron`.
`~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance), then lists the content index. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication.
## Plugin model
Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`. Each plugin has a `plugin.json` manifest and is installed independently via `claude plugin install`.
## Governance layer
`core/instructions/governance.md` is the always-on governance instruction file. Unlike the on-demand instruction files in the content index, governance.md is loaded into every Claude session via `@import` in `providers/claude-code/CLAUDE.md`. This is a technical guarantee, not a behavioural instruction — `@import` causes Claude Code to expand and load the file at launch, before any interaction begins.
The governance layer has two phases:
- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
- **Phase 2** (Chunk 6): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
- **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
## AGENTS.md pattern
This repo uses two `AGENTS.md` files as the provider-agnostic source of always-on rules (ADR-0012):
- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules, chunk workflow). Imported by repo `CLAUDE.md` via `@AGENTS.md`.
- **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`.
Both `CLAUDE.md` files are thin adapters: they import from their respective `AGENTS.md` and add only Claude Code-specific syntax (`@import`, content index paths). They carry no original always-on content.
@@ -84,8 +50,6 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for
`core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers/<name>/` that translates core content into the tool's expected format and location. The core content itself does not change.
Skills are the strongest shared primitive — the `SKILL.md` format and [Agent Skills open standard](https://agentskills.io) are cross-provider. Providers that don't read `~/.agents/skills/` natively declare a symlink adapter in `providers/<name>/provider-manifest.sh`; `install.sh` discovers and wires these up automatically.
## Architectural decisions
Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. See the index there for rationale on choices like the pull distribution model, copy-not-symlink coupling, and the two-tier CLAUDE.md structure.
docs/spec/overview.md
-71
View File
@@ -1,71 +0,0 @@
# Overview
Current deployed state of this repo — what you get if you run `install.sh` today. Updated at the close of each chunk and in the same PR as any behavior change.
*Last updated: 2026-06-27 (kyberforge plugin — agent-author skill)*
## What is deployed
### Plugins
1 plugin registered in the marketplace (`holocron` marketplace, `.claude-plugin/marketplace.json`):
- **`kyberforge`** — marketplace management toolkit and skill/agent factory. Contains `skill-author` (create/improve SKILL.md files), `skill-audit` (validate skills against agentskills.io spec), and `agent-author` (create/improve Claude Code + Copilot CLI agent definition files at plugin, project, or user scope) skills. Install: `claude plugin install kyberforge@holocron`. Source: `plugins/kyberforge/`. Research doc: `plugins/kyberforge/docs/plugin-marketplace-architecture.md`.
### Skills
13 skills deployed directly to `~/.agents/skills/` via `install.sh`. Available as slash commands in Claude Code via `~/.claude/skills/ → ~/.agents/skills/` symlink. Factory and marketplace skills (`write-eval`, `write-skill`, `create-plugin`, `marketplace-architect`) have moved to the `kyberforge` plugin and are only available after plugin install.
**Factory bootstrap (now in kyberforge plugin):**
- `write-eval` — produces `eval.yaml` test files for skills. Hand-written (bootstrap). Eval at `plugins/kyberforge/tests/evals/write-eval/eval.yaml`.
- `write-skill` — authors new SKILL.md files and converts placeholders to canonical format. Hand-written (bootstrap). Eval at `plugins/kyberforge/tests/evals/write-skill/eval.yaml`. Invokes `write-eval` as part of its own process.
- `write-docs` — produces technical documentation derived from code and spec; never invents behaviour. **First factory-authored skill** (SKILL.md produced via `write-skill`, eval via `write-eval`). Eval at `.agents/evals/implement/write-docs/eval.yaml`. Sources: anthropics/skills `doc-coauthoring`, mattpocock/skills `write-a-skill`, bmad-code-org/BMAD-METHOD `bmad-advanced-elicitation`.
Current skills (direct): `caveman`, `diagnose`, `gitleaks`, `grill-me`, `grill-with-docs`, `improve-codebase-architecture`, `prototype`, `tdd`, `to-issues`, `to-prd`, `triage`, `write-docs`, `zoom-out`.
**Chunk 3 target:** 42 skills across 9 categories. PRD: `docs/prd/chunk-3-skills-library.md`. Canonical build reference: `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` (delete once all skills exist). Skills stored flat (`skill-name/SKILL.md`) per ADR-0009; category in `metadata.category` frontmatter. Categories: design, factory, implement, test, review, deploy, operate, cross-cutting, iac (2 skills only — docker-compose + iac-security-review). Role skills (6) deferred to Chunk 5. Gitea skills moved to `providers/gitea/` provider adapter.
**Skill implementation workflow:** each skill follows the per-skill process in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016). Sub-agents handle source discovery, source review, and conflict checking; synthesis grill and HITL test are human steps. Bootstrap: write-eval (hand-written) → write-skill (hand-written) → write-docs (first factory-authored) → all others via factory.
### Claude Code configuration
- `~/.claude/CLAUDE.md` — thin adapter; imports `~/.agents/AGENTS.md` (Communication + Behavior) and `governance.md`; content index pointers only
- `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); provider-agnostic source of truth
- `~/.claude/core/instructions/` — coding, git, testing, governance instruction files
- `~/.claude/settings.json` — Claude Code settings
### Governance layer
`core/instructions/governance.md` loads into every Claude Code session via `@import` in `~/.claude/CLAUDE.md`. Covers: hard prohibitions on secrets and data, data classification tiers, HITL requirements, sycophancy resistance, deterministic execution preference.
## What works end-to-end
- `install.sh` runs idempotently — safe to re-run after changes
- Provider adapter pattern: `providers/*/provider-manifest.sh` auto-discovered by `install.sh`
- Governance rules take effect at session start without any manual loading step
- Skills available as slash commands immediately after install
## What is not yet deployed
- `sync.sh` — pulls updates into existing projects (Chunk 6)
- `init-project.sh` — bootstraps a new project (Chunk 6)
- Copilot provider adapter (Chunk 7)
- Formal CI/pre-commit enforcement of governance rules (Chunk 6)
- `init-project.sh` scaffolding (Chunk 6) — will seed `.pre-commit-config.yaml` for new projects
For chunk planning and open questions, see `docs/ROADMAP.md`.
## Recent changes
- 2026-06-27 — `agent-author` skill added to kyberforge plugin. Creates and improves agent definition files for both Claude Code (`.md`) and GitHub Copilot CLI (`.agent.md`) from a single root directory input via `new-agent.sh`. Supports plugin, project, and user scope — scope auto-detected from root (`plugin.json` presence). File-by-file no-op scaffold; routing on file existence (neither → create, any exists → improve). `agents/sources.md` for provenance at plugin scope. No companion `agent-audit` skill (deferred, tracked in issue #11). ADR-0015 documents the dual-provider single-root scaffold decision.
- 2026-06-20 — kyberforge plugin created and registered in `holocron` marketplace. Consolidates `create-plugin`, `marketplace-architect`, `write-skill`, and `write-eval` skills (previously in `.agents/skills/`) plus their evals, bundled scripts, references, and the plugin-marketplace-architecture research doc into a single installable plugin at `plugins/kyberforge/`. Plugin template (`templates/plugin/`) bundled into `plugins/kyberforge/skills/create-plugin/assets/plugin-template/` and removed from repo root. Evals moved from `.agents/evals/marketplace/` and `.agents/evals/factory/write-eval/` into `plugins/kyberforge/tests/evals/`. These four skills are no longer available as standalone slash commands — install the plugin to use them.
- 2026-06-20 — Gitleaks secret scanning added via pre-commit framework. `.gitleaks.toml` in repo root is the base config extending gitleaks defaults and adds path allowlist for `docs/research/` (high-entropy terminal captures). `gitleaks` skill added (`cross-cutting`) covering full lifecycle: install, update, tune allowlist, scan modes, resolve real findings. Supports both modern repos (pre-commit-based) and legacy repos (shell hook-based setup). Key lesson: v8.24.2 uses `[allowlist]` (singular); v8.25.0+ uses `[[allowlists]]` — wrong syntax silently does nothing.
- 2026-05-18 — Issue 0018 phase 1 refactor complete: `write-skill` redesigned from scratch. New files added to skill directory: `SKILL-TEMPLATE.md` (authoritative 6-section template with XML blocks, human-usable), `META-TEMPLATE.md` (provenance schema with inline-commented YAML), `CATEGORIES.md` (self-contained category table), `META.md` (write-skill's own provenance). SKILL.md rewritten: 6 sections replacing 8 (Role and When/When not dropped — not in agentskills.io spec); frontmatter reduced to 3 fields (`name`, `description`, `metadata.category`); provenance fields (`version`, `updated`, `when`, `source`, `references`) moved to META.md (progressive disclosure — not loaded at startup). `docs/notes/skill-implementation-workflow.md` updated to reference SKILL-TEMPLATE.md as the authoritative template.
- 2026-05-17 — Issue 0018 phase 2 complete: `write-docs` skill written and deployed. First skill produced end-to-end by the factory (SKILL.md via `write-skill`, eval via `write-eval`). Category: implement. Key decisions: file-approval gate before reading (user names files or approves proposals); gap check before drafting (user fills what code doesn't explain); stage skipping allowed with logged reason; full revised section shown before confirmation gate; surgical edits only with per-round delta summary; Reader Testing via scoped sub-agent (doc + questions only, no source files); summary/overview sections written last. Sources: anthropics/skills doc-coauthoring (Reader Testing stage, surgical-edit constraint), mattpocock/skills write-a-skill (trigger pattern), bmad-code-org/BMAD-METHOD bmad-advanced-elicitation (confirmation gate). Open follow-up: documentation convention (file/folder/content structure, global vs repo-specific) — not yet defined.
- 2026-05-17 — Issue 0018 phase 1 complete: `write-skill` bootstrap skill written and deployed. Hand-written (factory bootstrap). Self-authored — no upstream content adopted; agentskills.io best-practices and optimizing-descriptions docs cited as references. Speckit excluded (AGPL-3.0). Key decisions: new-skill + placeholder-conversion scope only (upgrades → `upgrade-skill`); trigger description tested against 3 cases before body written; `write-eval` invoked as step 7 in process; HITL prompt as step 8. Eval at `.agents/evals/factory/write-skill/eval.yaml`.
- 2026-05-17 — Issue 0017 complete: `write-eval` bootstrap skill written and deployed. Two sections schema (`trigger_tests` + `output_tests`), provider-agnostic string assertions, show-plan-then-merge-on-rerun behaviour, conflict flagging (B model). Sources: agentskills/agentskills, darkrishabh/agent-skills-eval, bmad-code-org/BMAD-METHOD, mattpocock/skills. Hand-written eval at `.agents/evals/factory/write-eval/eval.yaml`.
- 2026-05-17 — Issue 0016 complete: skill implementation workflow grill completed. `docs/notes/skill-implementation-workflow.md` written. All issues 0017–0028 updated with specific acceptance criteria. Key conventions: sub-agents prescribed at each research/writing step; conflict check against constitution + factory principles before synthesis grill; `when:` and `references:` fields added to authoring standard; write-docs moved to issue 0018 phase 2 (first factory-authored skill).
- 2026-05-17 — Issue 0015 complete: AGENTS.md refactor implemented. Two AGENTS.md files created (`AGENTS.md` at repo root, `core/AGENTS.md` deployed to `~/.agents/AGENTS.md`). Both CLAUDE.md files slimmed to thin adapters. `deploy-manifest.sh` updated. `docs/spec/architecture.md` updated with new structure. ADR-0012 in effect.
- 2026-05-17 — Chunk 3 issues created (0015–0028): AGENTS.md refactor prerequisite, skill workflow grill, bootstrap skills (write-eval, write-skill), factory/design/implement/test/review/deploy/operate/IaC/cross-cutting skill groups, chunk closure; all HITL; acceptance criteria for 0017–0028 to be refined after issue 0016 grill session
- 2026-05-17 — behavioral tests fully resolved: `CONTEXT.md` now always-loaded via `@import` in repo `CLAUDE.md`; standing rule added to check `docs/adr/` and ROADMAP resolved entries before answering design questions; communication/behavior and secrets rules tightened; Chunk 2 and Governance Phase 1 ✅ complete
- 2026-05-17 — added `LESSONS.md` (issue 0013) and `docs/spec/` (issue 0014); refactored `docs/VISION.md` to goals/intent only
plugins/bin/.claude-plugin/plugin.json
+1 -1
View File
@@ -8,5 +8,5 @@
"keywords": [],
"license": "MIT",
"name": "bin",
"version": "1.0.4"
"version": "1.1.1"
}
plugins/bin/plugin.json
+1 -2
View File
@@ -1,5 +1,4 @@
{
"agents": "agents/",
"author": {
"email": "[email protected]",
"name": "Defame1297"
@@ -12,5 +11,5 @@
"skills": [
"skills/"
],
"version": "1.0.4"
"version": "1.1.1"
}
plugins/bin/skills/gitea/README.md
-38
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.
plugins/bin/skills/gitea/SKILL.md
-150
View File
@@ -1,150 +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__search_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`.
- **Issues are not auto-closed when a PR merges.** Unlike GitHub, Gitea does not close linked issues on merge. Close explicitly with `issue_write method: "update" state: "closed"` after merging.
- **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.
### 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.
plugins/bin/skills/prototype/SKILL.md
+1 -1
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
plugins/core/.claude-plugin/plugin.json
+1 -1
View File
@@ -14,5 +14,5 @@
],
"license": "MIT",
"name": "core",
"version": "1.0.0"
"version": "1.1.0"
}
plugins/core/README.md
+47
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
plugins/kyberforge/docs/research/docs/agentsmd/configuration.md → plugins/core/docs/research/docs/agentsmd/configuration.md
View File
File renamed without changes.
plugins/kyberforge/docs/research/docs/agentsmd/examples.md → plugins/core/docs/research/docs/agentsmd/examples.md
View File
File renamed without changes.
plugins/kyberforge/docs/research/docs/agentsmd/overview.md → plugins/core/docs/research/docs/agentsmd/overview.md
View File
File renamed without changes.
plugins/kyberforge/docs/research/docs/agentsmd/sources.md → plugins/core/docs/research/docs/agentsmd/sources.md
View File
File renamed without changes.
plugins/core/plugin.json
+1 -2
View File
@@ -1,5 +1,4 @@
{
"agents": "agents/",
"author": {
"email": "[email protected]",
"name": "Defame1297"
@@ -19,5 +18,5 @@
"skills": [
"skills/"
],
"version": "1.0.0"
"version": "1.1.0"
}
plugins/core/skills/agentsmd-audit/README.md
+30
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` |
plugins/core/skills/agentsmd-audit/SKILL.md
+68
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.
plugins/core/skills/agentsmd-audit/references/sources.md
+33
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`
plugins/core/skills/agentsmd-audit/scripts/README.md
+11
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.
plugins/core/skills/agentsmd-audit/scripts/validate-drift.sh
Executable
+137
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
plugins/core/skills/agentsmd-audit/scripts/validate-secrets.sh
Executable
+120
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
plugins/core/skills/agentsmd-audit/scripts/validate-structure.sh
Executable
+118
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
plugins/core/skills/agentsmd-audit/tests/README.md
+30
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` |
plugins/core/skills/agentsmd-audit/tests/validate-drift.bats
+105
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
}
plugins/core/skills/agentsmd-audit/tests/validate-secrets.bats
+68
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:[email protected]: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"
}
plugins/core/skills/agentsmd-audit/tests/validate-structure.bats
+76
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"
}
plugins/core/skills/agentsmd-author/README.md
+27
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 |
plugins/core/skills/agentsmd-author/SKILL.md
+56
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.
plugins/core/skills/agentsmd-author/references/content-guide.md
+118
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).
plugins/core/skills/agentsmd-author/references/sources.md
+25
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`
plugins/core/skills/provider-adapter-author/README.md
+30
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` |
plugins/core/skills/provider-adapter-author/SKILL.md
+54
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.
plugins/core/skills/provider-adapter-author/references/sources.md
+9
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`
plugins/core/skills/provider-adapter-author/scripts/README.md
+9
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.
plugins/core/skills/provider-adapter-author/scripts/validate-adapter.sh
Executable
+141
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
plugins/core/skills/provider-adapter-author/tests/README.md
+28
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` |
plugins/core/skills/provider-adapter-author/tests/validate-adapter.bats
+128
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"
}
plugins/git/.claude-plugin/plugin.json
+1 -1
View File
@@ -13,5 +13,5 @@
],
"license": "MIT",
"name": "git",
"version": "1.0.0"
"version": "1.3.2"
}
plugins/git/agents/git-orchestrate.agent.md
+77
View File
@@ -0,0 +1,77 @@
---
name: git-orchestrate
description: Orchestrates git workflow operations for other agents. Invoke when a caller needs a multi-step or destructive git operation (rebase, force-push, branch deletion) coordinated across domain skills with safety gates, session context, and structured results.
tools: ["execute", "read", "edit"]
source_keys:
- context7-git-htmldocs
- git-scm-docs
- git-scm-worktree-docs
- git-scm-submodule-docs
- git-scm-remote-docs
- conventional-commits-spec
---
You are the orchestrator for the git plugin—a composable workflow dispatcher designed for other agents to invoke multi-step git operations reliably. Your one job is routing and safety-gating: you do not execute git logic yourself, you delegate to domain skills and enforce confirmation on destructive operations.
You act on the caller's real branch and session context (you explicitly carry forward `current_branch`), not a disposable copy — you do not run in an isolated worktree.
**Scope:** this orchestrator routes git-object operations only (commits, branches, worktrees, remotes, submodules, history). `pc-author` and `pc-run` (pre-commit config authoring and hook execution) are intentionally not routed here — they operate on `.pre-commit-config.yaml` and hook installation, not git objects. `git-workflow` is also not routed here, but for a different reason than `pc-author`/`pc-run`: it is a human-facing conversational wrapper for all git operation types (commits, branches, history, submodules, worktrees, remotes), and it itself calls this orchestrator internally as its execution backend — its own workflow explicitly invokes the `git-orchestrate` agent as its final step. It is not a peer to invoke instead of this dispatcher, and it explicitly refuses agent callers ("Do not use when the caller is an agent"). Agent callers route git-object operations here directly; direct human users to `git-workflow` when they want guided, conversational git help — it will call back into this orchestrator itself. Invoke `pc-author`/`pc-run` directly rather than through this dispatcher; do not invoke `git-workflow` as an agent caller under any circumstance.
## Hard rules
These are non-negotiable regardless of `confirm` or any skill-local override:
- Never skip hooks with `--no-verify`. Hooks are the automated QA gate; bypassing them breaks the pipeline.
- Never force-push `main` or `master`.
- Keep commits atomic — one logical, independently reviewable and reversible change per commit.
- Every commit must leave the repository in a working state (buildable/testable where practical).
- Commit messages explain **why**, not **what** — the diff already documents what changed.
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
- Never commit secrets, credentials, or environment-specific config.
- Reference related issues, ADRs, or design documents using git trailers (`Fixes:`, `Refs:`, `ADR:`, `RFC:`, `Design:`) when applicable.
### Submodule ordering
- Commit and push the submodule first, then update and push the parent repo. Pushing the parent before the submodule commit exists on the remote breaks `git submodule update` for anyone who pulls.
- Always use `rtk git` for parent-repo operations; drop into the submodule directory and use bare `git` for submodule-specific commands.
- After adding or updating a submodule, check `git status` in both the parent and the submodule — a `-dirty` flag means the submodule has uncommitted local changes that must be committed before the parent pointer updates.
Sub-skills carry their own local copies of these rules for humans who invoke them directly, bypassing this orchestrator. When a caller routes through you, this section is the enforcement backstop: check every routed operation against it before dispatch, not just the destructive-operation confirm gate below.
When invoked, you:
1. Parse the incoming workflow request (operation type, parameters, context overrides)
2. Check safety gates: if the operation is destructive (force-push, branch deletion, rebase with history loss, force-checkout) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm`
3. Route to the appropriate domain skill: git-commits, git-branches, git-history, git-submodules, git-worktrees, git-remotes
4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill
5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics
6. Aggregate results and return structured JSON output suitable for agent chaining
## Inputs
- **operation:** string, one of:
- commits/history: commit, amend, cherry-pick, rebase, squash, blame, log
- branches: create-branch, switch-branch, delete-branch, rename-branch, track-branch, list-branches
- worktrees: create-worktree, list-worktrees, lock-worktree, unlock-worktree, move-worktree, remove-worktree, prune-worktree, repair-worktree
- remotes: add-remote, remove-remote, rename-remote, set-remote-url, push, pull, fetch
- submodules: add-submodule, init-submodule, update-submodule, sync-submodule, remove-submodule, submodule-status
- **parameters:** object, operation-specific arguments (branch name, commit message, etc.)
- **context:** object (optional), workflow state to carry forward (current_branch, branch_intent, user_config_overrides)
- **confirm:** boolean (optional), explicit confirmation for destructive operations (required if not set for force-push, branch deletion, rebase with history loss, force-checkout)
## Process
1. Validate the request structure and check if operation is known
2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm`
3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error
4. Read plugin config from `.claude/plugins/git/config.json` if present — see `config.example.json` in the plugin root for the expected shape (`branching_pattern`, `commit_style`, `rebase_strategy`) — or fall back to sensible defaults
5. Invoke the appropriate skill with the operation, parameters, context, and config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above).
6. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections)
7. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions
8. Aggregate all outputs and return as structured JSON
## Output
Returns structured JSON with operation status, result (output, context, applied config), and optional error details with recovery suggestions.
plugins/git/agents/git-orchestrate.md
+93
View File
@@ -0,0 +1,93 @@
---
name: git-orchestrate
description: Orchestrates git workflow operations for other agents. Invoke when a caller needs a multi-step or destructive git operation (rebase, force-push, branch deletion) coordinated across domain skills with safety gates, session context, and structured results.
tools: Bash, Read, Edit
source_keys:
- context7-git-htmldocs
- git-scm-docs
- git-scm-worktree-docs
- git-scm-submodule-docs
- git-scm-remote-docs
- conventional-commits-spec
---
You are the orchestrator for the git plugin—a composable workflow dispatcher designed for other agents to invoke multi-step git operations reliably. Your one job is routing and safety-gating: you do not execute git logic yourself, you delegate to domain skills and enforce confirmation on destructive operations.
You act on the caller's real branch and session context (you explicitly carry forward `current_branch`), not a disposable copy — you do not run in an isolated worktree.
**Scope:** this orchestrator routes git-object operations only (commits, branches, worktrees, remotes, submodules, history). `pc-author` and `pc-run` (pre-commit config authoring and hook execution) are intentionally not routed here — they operate on `.pre-commit-config.yaml` and hook installation, not git objects. `git-workflow` is also not routed here, but for a different reason than `pc-author`/`pc-run`: it is a human-facing conversational wrapper for all git operation types (commits, branches, history, submodules, worktrees, remotes), and it itself calls this orchestrator internally as its execution backend — its own workflow explicitly invokes the `git-orchestrate` agent as its final step. It is not a peer to invoke instead of this dispatcher, and it explicitly refuses agent callers ("Do not use when the caller is an agent"). Agent callers route git-object operations here directly; direct human users to `git-workflow` when they want guided, conversational git help — it will call back into this orchestrator itself. Invoke `pc-author`/`pc-run` directly rather than through this dispatcher; do not invoke `git-workflow` as an agent caller under any circumstance.
## Hard rules
These are non-negotiable regardless of `confirm` or any skill-local override:
- Never skip hooks with `--no-verify`. Hooks are the automated QA gate; bypassing them breaks the pipeline.
- Never force-push `main` or `master`.
- Keep commits atomic — one logical, independently reviewable and reversible change per commit.
- Every commit must leave the repository in a working state (buildable/testable where practical).
- Commit messages explain **why**, not **what** — the diff already documents what changed.
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
- Never commit secrets, credentials, or environment-specific config.
- Reference related issues, ADRs, or design documents using git trailers (`Fixes:`, `Refs:`, `ADR:`, `RFC:`, `Design:`) when applicable.
### Submodule ordering
- Commit and push the submodule first, then update and push the parent repo. Pushing the parent before the submodule commit exists on the remote breaks `git submodule update` for anyone who pulls.
- Always use `rtk git` for parent-repo operations; drop into the submodule directory and use bare `git` for submodule-specific commands.
- After adding or updating a submodule, check `git status` in both the parent and the submodule — a `-dirty` flag means the submodule has uncommitted local changes that must be committed before the parent pointer updates.
Sub-skills carry their own local copies of these rules for humans who invoke them directly, bypassing this orchestrator. When a caller routes through you, this section is the enforcement backstop: check every routed operation against it before dispatch, not just the destructive-operation confirm gate below.
When invoked, you:
1. Parse the incoming workflow request (operation type, parameters, context overrides)
2. Check safety gates: if the operation is destructive (force-push, branch deletion, rebase with history loss, force-checkout) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm`
3. Route to the appropriate domain skill: `git-commits`, `git-branches`, `git-history`, `git-submodules`, `git-worktrees`, `git-remotes`
4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill
5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics
6. Aggregate results and return structured JSON output suitable for agent chaining
## Inputs
- **operation:** string, one of:
- commits/history: commit, amend, cherry-pick, rebase, squash, blame, log
- branches: create-branch, switch-branch, delete-branch, rename-branch, track-branch, list-branches
- worktrees: create-worktree, list-worktrees, lock-worktree, unlock-worktree, move-worktree, remove-worktree, prune-worktree, repair-worktree
- remotes: add-remote, remove-remote, rename-remote, set-remote-url, push, pull, fetch
- submodules: add-submodule, init-submodule, update-submodule, sync-submodule, remove-submodule, submodule-status
- **parameters:** object, operation-specific arguments (branch name, commit message, etc.)
- **context:** object (optional), workflow state to carry forward (current_branch, branch_intent, user_config_overrides)
- **confirm:** boolean (optional), explicit confirmation for destructive operations (required if not set for force-push, branch deletion, rebase with history loss, force-checkout)
## Process
1. Validate the request structure and check if operation is known
2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm`
3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error
4. Read plugin config from `.claude/plugins/git/config.json` if present — see `config.example.json` in the plugin root for the expected shape (`branching_pattern`, `commit_style`, `rebase_strategy`) — or fall back to sensible defaults
5. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, context, and config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above).
6. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections)
7. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions
8. Aggregate all outputs and return as structured JSON
## Output
```json
{
"status": "success" | "error",
"operation": "<operation_name>",
"result": {
"output": "<command output or result>",
"context": { "current_branch": "...", "workflow_intent": "..." },
"applied_config": { "commit_style": "...", "rebase_strategy": "..." }
},
"error": {
"message": "<human-readable error>",
"code": "<error type: conflict | auth_failure | push_rejection | invalid_state>",
"recovery_attempted": true | false,
"suggestions": ["<suggestion1>", "<suggestion2>"]
}
}
```
plugins/git/config.example.json
+5
View File
@@ -0,0 +1,5 @@
{
"branching_pattern": "github-flow",
"commit_style": "conventional",
"rebase_strategy": "interactive"
}
plugins/git/docs/research/docs/git/branching-merging.md
+180
View File
@@ -0,0 +1,180 @@
---
topic: branching-merging
source_keys:
- context7-git-htmldocs
---
## Branching Model
Git branches are cheap: each is just a ref file (41 bytes) pointing to a commit. Creating, switching, and deleting branches is a sub-millisecond operation regardless of repo size.
The canonical branching workflow is:
1. Create a branch from a stable point (usually `main` or `develop`).
2. Commit work on the branch.
3. Integrate back via merge or rebase.
4. Delete the branch.
## Creating and Switching Branches
```bash
git switch -c <branch> # create and switch (preferred, Git 2.23+)
git switch -c <branch> <start> # from a specific commit or remote branch
git switch <existing-branch> # switch to existing
git switch - # switch back to previous branch
# Legacy equivalents
git checkout -b <branch>
git checkout <branch>
```
When switching, Git updates `HEAD`, the index, and the working tree. Uncommitted changes that conflict with the target branch will block the switch (Git refuses to overwrite them).
## Merge Strategies
### Fast-forward merge
If the target branch has not diverged from the source, Git simply advances the branch pointer — no merge commit is created. History remains linear.
```bash
git merge <branch> # fast-forward if possible
```
### True merge (--no-ff)
Forces a merge commit even when a fast-forward is possible. Preserves the fact that a group of commits came from a branch. Required by Gitflow on all supporting-branch merges.
```bash
git merge --no-ff <branch>
git merge --no-ff -m "Merge feature/X" <branch>
```
### Squash merge
Collapses all commits from the source branch into a single staged change, which you then commit manually. Keeps the target branch history clean; discards individual commit granularity.
```bash
git merge --squash <branch>
git commit -m "feat: add X" # separate commit step required
```
### Octopus merge
Merging more than two branches simultaneously. Git uses this by default when you pass multiple branch names. Fails on conflicts — use sequential two-way merges when conflicts are expected.
```bash
git merge branch-a branch-b branch-c
```
## Conflict Resolution
When Git cannot auto-merge, it inserts conflict markers into the affected files and stops:
```
<<<<<<< HEAD
current branch content
=======
incoming branch content
>>>>>>> feature/x
```
Resolution workflow:
```bash
# 1. Find conflicted files
git status
# 2. Edit each file to resolve markers, then stage
git add <resolved-file>
# 3. Continue
git merge --continue # or git commit if --continue is unavailable
# Alternatively: abort and reset
git merge --abort
```
Tools:
```bash
git mergetool # open configured merge.tool (meld, vimdiff, etc.)
git diff --diff-filter=U # show only conflicted files
```
## Rebase
Rebase replays a sequence of commits on top of a new base, rewriting SHAs in the process. The result is a linear history with no merge commits.
```bash
git rebase main # rebase current branch onto main
git rebase --onto <newbase> <upstream> <branch> # transplant a range
```
**Interactive rebase** — rewrites local history:
```bash
git rebase -i HEAD~5 # edit last 5 commits
```
Interactive commands:
| Command | Effect |
|---|---|
| `pick` | Keep commit as-is |
| `reword` | Keep commit but edit message |
| `edit` | Pause for amending |
| `squash` | Fold into previous commit (keep message) |
| `fixup` | Fold into previous commit (discard message) |
| `drop` | Remove commit entirely |
| `exec` | Run a shell command |
**Golden rule of rebasing:** Never rebase commits that have been pushed to a shared branch. Rebase rewrites history; force-pushing to shared branches breaks other people's local copies.
## Conflict Resolution During Rebase
```bash
# Resolve each conflicting commit, then:
git add <file>
git rebase --continue
# Skip a problematic commit:
git rebase --skip
# Abort and return to pre-rebase state:
git rebase --abort
```
## Cherry-picking
Applies the diff introduced by a specific commit onto the current branch as a new commit.
```bash
git cherry-pick <sha> # apply one commit
git cherry-pick <sha-a>^..<sha-b> # apply a range (inclusive)
git cherry-pick -n <sha> # stage without committing (for editing)
```
Cherry-picking does not maintain a history link between branches. For sharing code between branches, prefer merge or rebase unless you specifically need to apply an isolated patch.
## Tracking Branches
A tracking relationship lets `git pull` and `git push` know which remote branch to target.
```bash
git push -u origin <branch> # push and set upstream
git branch --set-upstream-to=origin/<branch> # set tracking on existing branch
git branch -vv # show tracking info for all branches
```
`@{upstream}` (or `@{u}`) is shorthand for the tracked remote branch:
```bash
git log @{u}..HEAD # commits not yet pushed
git diff @{u} # diff against upstream
```
## Comparing Branches
```bash
git log main..feature # commits in feature not in main
git log feature..main # commits in main not in feature
git log --left-right main...feature # both diverging sets (symmetric diff)
git diff main...feature # diff from common ancestor to feature tip
git merge-base main feature # print the common ancestor commit
```
plugins/git/docs/research/docs/git/cli-reference.md
+212
View File
@@ -0,0 +1,212 @@
---
topic: cli-reference
source_keys:
- context7-git-htmldocs
- git-scm-docs
---
## Setup and Init
```bash
git init [<directory>] # initialise new repo (or reinit existing)
git init --bare # bare repo (no working tree; used as remote)
git clone <url> [<directory>] # clone a remote repo
git clone --recurse-submodules # clone including all submodules
git clone --depth <n> # shallow clone (only last n commits)
git clone --filter=blob:none # blobless partial clone
```
## Staging and Status
```bash
git status # show working tree and staging area state
git status -s # short format
git add <file> # stage a file
git add -p # interactively stage hunks
git add -A # stage all changes including deletions
git rm <file> # remove file from index and working tree
git rm --cached <file> # unstage (remove from index only)
git mv <old> <new> # rename/move a file
git diff # unstaged changes
git diff --cached # staged changes (what will be committed)
git diff HEAD # all uncommitted changes
git restore <file> # discard working tree changes (Git 2.23+)
git restore --staged <file> # unstage (Git 2.23+)
```
## Committing
```bash
git commit -m "<message>" # commit with inline message
git commit # open editor for message
git commit -a # stage tracked changes and commit in one step
git commit --amend # rewrite the most recent commit (local only)
git commit --amend --no-edit # amend without changing the message
git commit --allow-empty # commit with no changes (useful for triggers)
```
### Key `git commit` Flags
| Flag | Meaning |
|---|---|
| `-m <msg>` | Inline message; multiple `-m` flags become separate paragraphs |
| `-F <file>` | Read message from file; `-` reads from stdin |
| `-a` | Auto-stage modified tracked files |
| `-n` / `--no-verify` | Skip pre-commit and commit-msg hooks |
| `--author "<Name> <email>"` | Override author |
| `--date <date>` | Override author date |
| `--squash=<commit>` | Prefix message with "squash!" for use with `rebase --autosquash` |
| `--fixup=<commit>` | Prefix message with "fixup!" for `rebase --autosquash` |
| `--reset-author` | Reassign authorship to the committer (use with `--amend`) |
| `--trailer <token>:<value>` | Append a footer trailer to the message |
| `--cleanup=<mode>` | Control message whitespace handling: `strip`, `whitespace`, `verbatim`, `scissors` |
## Branching
```bash
git branch # list local branches
git branch -a # list local and remote branches
git branch -vv # show tracking info and last commit
git branch <name> # create branch at current HEAD
git branch <name> <start> # create branch at specific commit
git branch -d <name> # delete (safe — refuses if unmerged)
git branch -D <name> # delete (force)
git branch -m <old> <new> # rename branch
git branch --set-upstream-to=origin/<branch> # set tracking
git switch <branch> # switch to branch (Git 2.23+)
git switch -c <branch> # create and switch (Git 2.23+)
git checkout <branch> # switch (legacy)
git checkout -b <branch> # create and switch (legacy)
```
## Merging
```bash
git merge <branch> # merge branch into current branch
git merge --no-ff <branch> # always create a merge commit
git merge --squash <branch> # squash into a single staged change
git merge --abort # cancel an in-progress merge
git merge --continue # continue after conflict resolution
git merge -m "<msg>" <branch> # custom merge commit message
git merge --into-name <branch> # override branch name in default message
```
## Rebasing
```bash
git rebase <base> # rebase current branch onto base
git rebase -i HEAD~<n> # interactive rebase of last n commits
git rebase -i <commit> # interactive rebase from commit onwards
git rebase --onto <newbase> <upstream> <branch> # transplant branch
git rebase --continue # continue after conflict resolution
git rebase --abort # restore pre-rebase state
git rebase --skip # skip the conflicting commit
git rebase --quit # abort but keep HEAD position
git rebase --autosquash # auto-apply fixup!/squash! commits
```
Interactive rebase `pick` commands: `pick`, `reword`, `edit`, `squash`, `fixup`, `drop`, `exec`, `break`, `label`, `reset`, `merge`.
## Cherry-picking
```bash
git cherry-pick <commit> # apply a commit onto current branch
git cherry-pick <a>..<b> # apply a range (exclusive of a)
git cherry-pick <a>^..<b> # apply a range (inclusive of a)
git cherry-pick -n <commit> # apply without committing (stage only)
git cherry-pick --abort
git cherry-pick --continue
```
## History and Inspection
```bash
git log # full log
git log --oneline # compact one-line per commit
git log --graph --oneline --all # branch graph
git log --stat # show file change counts
git log -p # show patch diff for each commit
git log --author="<name>"
git log --grep="<pattern>"
git log --since="2 weeks ago"
git log <file> # history of a specific file
git log <branch>..<branch> # commits in second not in first
git show <commit> # show commit details and diff
git diff <commit1> <commit2> # diff between two commits
git blame <file> # annotate each line with last commit
git bisect start # start binary search for bug
git bisect good <commit>
git bisect bad <commit>
git bisect reset
```
## Remote Operations
```bash
git remote -v # list remotes
git remote add <name> <url> # add a remote
git remote remove <name>
git remote rename <old> <new>
git fetch <remote> # download objects and refs
git fetch --all # fetch all remotes
git fetch --prune # remove stale remote-tracking refs
git pull # fetch + merge (or rebase if configured)
git push <remote> <branch> # push branch to remote
git push -u origin <branch> # push and set upstream
git push --force-with-lease # safe force push (checks remote tip)
git push --tags # push tags
git push origin :<branch> # delete remote branch
```
## Stashing
```bash
git stash # stash working tree and index
git stash push -m "<msg>" # stash with description
git stash push -u # include untracked files
git stash list # show all stashes
git stash pop # apply most recent and remove from list
git stash apply stash@{n} # apply without removing
git stash drop stash@{n} # delete a stash
git stash clear # delete all stashes
git stash branch <branch> # create branch from stash
```
## Tags
```bash
git tag # list tags
git tag <name> # lightweight tag at HEAD
git tag -a <name> -m "<msg>" # annotated tag
git tag <name> <commit> # tag a specific commit
git tag -d <name> # delete local tag
git push origin <tag> # push tag
git push origin --tags # push all tags
git push origin :refs/tags/<name> # delete remote tag
```
## Undoing
```bash
git reset HEAD~1 # undo last commit, keep changes staged
git reset --soft HEAD~1 # undo last commit, keep changes staged
git reset --mixed HEAD~1 # undo last commit, unstage changes
git reset --hard HEAD~1 # undo last commit, discard changes
git revert <commit> # create new commit that undoes a past commit
git revert -n <commit> # stage the revert without committing
git clean -fd # delete untracked files and directories
git clean -n # dry run (show what would be deleted)
```
## Plumbing (scripting-safe)
```bash
git rev-parse HEAD # print full SHA of HEAD
git rev-parse --short HEAD # print short SHA
git rev-parse --show-toplevel # print repo root path
git symbolic-ref HEAD # print the ref HEAD points to
git cat-file -t <sha> # print object type
git cat-file -p <sha> # print object contents
git update-ref refs/heads/<b> <sha> # set a ref to a commit
git for-each-ref refs/heads/ # list refs with metadata
```
plugins/git/docs/research/docs/git/commits.md
+169
View File
@@ -0,0 +1,169 @@
---
topic: commits
source_keys:
- conventional-commits-spec
- commitlint-config-conventional
---
## Conventional Commits Specification (v1.0.0)
Conventional Commits is a lightweight convention on top of commit messages that provides a set of rules for creating an explicit commit history. It enables automated tooling (CHANGELOG generation, semantic version bumping) and structured filtering.
## Message Format
```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
Each section is separated by a blank line. The header is the only required part.
## Rules
| Element | Rule |
|---|---|
| `type` | Required. Lowercase noun. |
| `scope` | Optional. Noun in parentheses directly after type: `feat(api):`. |
| `description` | Required. Immediately follows `type/scope: `. Imperative mood, no trailing period. |
| `body` | Optional. Begins one blank line after description. Free-form prose, multiple paragraphs allowed. |
| `footer(s)` | Optional. Begins one blank line after body (or description). `<token>: <value>` format. |
| `BREAKING CHANGE` | Must be uppercase. Either a footer token or signalled by `!` before the colon. |
## Standard Types
The spec mandates only `feat` and `fix`. The following 11 types are the de-facto standard from `@commitlint/config-conventional` (Angular commit message guidelines):
| Type | Meaning | SemVer impact | Appears in CHANGELOG |
|---|---|---|---|
| `feat` | New user-visible feature | MINOR | Yes |
| `fix` | Bug fix | PATCH | Yes |
| `perf` | Performance improvement, no API change | PATCH | Yes |
| `revert` | Reverts a previous commit | PATCH | Yes |
| `docs` | Documentation only | none | No |
| `style` | Formatting, whitespace — no logic change | none | No |
| `refactor` | Code restructuring — no feature or fix | none | No |
| `test` | Adding or fixing tests | none | No |
| `build` | Build system or external dependency changes | none | No |
| `ci` | CI configuration and scripts | none | No |
| `chore` | Anything not fitting above | none | No |
A `BREAKING CHANGE` footer or `!` on **any** type always triggers a MAJOR bump.
## Breaking Changes
Two equivalent notations:
**`!` in header** (preferred — visible in `git log --oneline`):
```
feat!: drop support for Node 6
feat(api)!: remove deprecated endpoint
```
**`BREAKING CHANGE` footer** (machine-readable body):
```
feat: allow config to extend other configs
BREAKING CHANGE: `extends` key now used for extending config files
```
**Both together** (most explicit):
```
feat!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
```
Rules:
- `BREAKING CHANGE` must be all caps.
- `BREAKING-CHANGE` (hyphenated) is an accepted synonym.
- Any type can carry a breaking change, not just `feat`.
- The footer value must describe what broke.
## Footer Token Rules
```
<token>: <value>
<token> #<value> # for issue references
```
- Tokens use hyphens for word separation: `Reviewed-by`, `Co-authored-by`, `Refs`.
- Exception: `BREAKING CHANGE` (space allowed, uppercase).
- Multiple footers allowed, one per line.
- Blank line required before the footer block.
Valid footer examples:
```
Reviewed-by: Z
Refs: #123
Co-authored-by: Alice <alice@example.com>
BREAKING CHANGE: the `--format` flag now requires a value
```
## Examples
Minimal — no body, no footer:
```
docs: correct spelling of CHANGELOG
```
With scope:
```
feat(lang): add Polish language
```
Breaking change via `!`:
```
feat!: send an email to the customer when a product is shipped
```
Breaking change via footer:
```
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
```
Multi-paragraph body with multiple footers:
```
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Reviewed-by: Z
Refs: #123
```
Revert:
```
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868
```
## commitlint Constraints (`config-conventional`)
| Constraint | Value |
|---|---|
| Header max length | 100 characters |
| Subject must not end with `.` | enforced |
| Subject must be lowercase | enforced (not sentence-case or UPPER-CASE) |
| Body / footer line max length | 100 characters |
| Type must be one of the 11 standard types | error if not |
| Blank line before body | warning |
| Blank line before footer | warning |
## SemVer Mapping Summary
| Condition | SemVer bump |
|---|---|
| `fix`, `perf`, `revert` | PATCH |
| `feat` | MINOR |
| Any type with `BREAKING CHANGE` or `!` | MAJOR |
| All other types (`docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore`) | none |
plugins/git/docs/research/docs/git/configuration.md
+147
View File
@@ -0,0 +1,147 @@
---
topic: configuration
source_keys:
- git-scm-docs
---
## Config Scopes
Git reads configuration from three scopes in order: system → global → local. The last value wins. A fourth `worktree` scope exists when `extensions.worktreeConfig` is enabled.
| Scope | Flag | File (Linux/macOS) | File (Windows) |
|---|---|---|---|
| system | `--system` | `$(prefix)/etc/gitconfig` | `$(prefix)\etc\gitconfig` |
| global | `--global` | `~/.gitconfig` or `$XDG_CONFIG_HOME/git/config` | `%USERPROFILE%\.gitconfig` |
| local | `--local` (default) | `.git/config` | `.git/config` |
| worktree | `--worktree` | `.git/config.worktree` | `.git/config.worktree` |
Writes default to local scope. Pass `--global` to write user-wide settings.
## Inspecting Config
```bash
git config --list # merged view of all scopes
git config --global --list # global scope only
git config --global --edit # open in $EDITOR
git config --get user.email # read a single key
git config --unset core.editor # remove a key
```
## Essential Variables
### Identity (required — no defaults)
```bash
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
```
These are stamped on every commit. There is no system default — omitting them causes `git commit` to fail.
### Editor
```bash
git config --global core.editor "code --wait" # VS Code
git config --global core.editor "vim"
git config --global core.editor "nano"
```
Used for commit messages, rebase TODO lists, `git notes edit`, etc. Falls back to `$VISUAL` / `$EDITOR` env vars if unset.
### Default Branch Name
```bash
git config --global init.defaultBranch main
```
Controls the name of the initial branch created by `git init`. Defaults to `master` on most installations; set to `main` to match current convention.
### Pull Behaviour
```bash
git config --global pull.rebase true # rebase instead of merge on pull
```
| Value | Behaviour |
|---|---|
| `false` | Merge (creates a merge commit) |
| `true` | Rebase (rewrites local commits on top of fetched) |
| `merges` | Rebase, preserving merge commits |
| `interactive` | Interactive rebase on pull |
Leaving this unset causes a warning on every `git pull` in Git ≥ 2.27. Setting `pull.rebase true` is the cleaner-history choice for most workflows.
### Push Behaviour
```bash
git config --global push.default simple
```
| Value | Behaviour |
|---|---|
| `simple` (default) | Push current branch to its upstream; refuse if names differ |
| `current` | Push current branch to same-named remote branch |
| `upstream` | Push to the branch's configured upstream, regardless of name |
| `matching` | Push all matching local/remote branch pairs |
| `nothing` | Refuse all pushes unless an explicit refspec is given |
### Line Endings
```bash
# Windows
git config --global core.autocrlf true
# Linux / macOS
git config --global core.autocrlf input
```
`true` converts CRLF→LF on check-in and LF→CRLF on check-out (Windows). `input` converts CRLF→LF on check-in only.
### Credential Storage
```bash
git config --global credential.helper cache # in-memory, expires
git config --global credential.helper osxkeychain # macOS Keychain
git config --global credential.helper manager-core # Windows Credential Manager
```
### Global Ignore File
```bash
git config --global core.excludesFile ~/.gitignore_global
```
Patterns in this file are ignored across all repos without touching `.gitignore`.
### Merge and Diff Tools
```bash
git config --global merge.tool meld # or vimdiff, kdiff3, etc.
git config --global diff.tool vimdiff
```
### Aliases
Defined under `[alias]` in the config file:
```ini
[alias]
st = status
co = checkout
br = branch -vv
last = log -1 HEAD
lg = log --graph --oneline --decorate --all
undo = reset --soft HEAD~1
```
## Minimal First-Time Setup
```bash
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global core.editor "vim"
git config --global init.defaultBranch main
git config --global pull.rebase true
git config --global push.default simple
git config --global credential.helper cache
git config --global core.excludesFile ~/.gitignore_global
```
plugins/git/docs/research/docs/git/gitflow.md
+158
View File
@@ -0,0 +1,158 @@
---
topic: gitflow
source_keys:
- nvie-gitflow-post
- atlassian-gitflow-tutorial
- gitflow-cheatsheet
---
## Core Philosophy
Gitflow is a branching model that treats branching and merging as routine operations, not exceptional ones. It defines a strict structure where every branch has a fixed purpose, a fixed origin point, and a fixed merge target. This predictability enables automated tooling and makes the history of any project self-documenting.
The central invariant: `main` always reflects production-ready code; `develop` always reflects the latest integrated development state. All other branches are temporary scaffolding.
The model was designed for software with **explicit versioned releases**. Vincent Driessen (the original author) noted in 2020 that teams doing continuous delivery should prefer GitHub Flow instead.
## The Five Branch Types
### 1. `main` (permanent)
HEAD always reflects a production-ready, releasable state. Every commit is tagged with a version. Automated deployment pipelines trigger off this branch.
**Receives merges from:** `release/*` and `hotfix/*` only. Never committed to directly.
### 2. `develop` (permanent)
Integration branch for all completed features. HEAD reflects the latest delivered development changes for the next release. When `develop` is feature-complete for a release, a release branch forks from it.
**Receives merges from:** `feature/*`, `release/*`, `hotfix/*`.
### 3. Feature branches (short-lived)
| Property | Value |
|---|---|
| Branch from | `develop` |
| Merge back to | `develop` |
| Naming | `feature/<name>` or `feature/TICKET-123-description` |
Isolate development of a single feature. Live primarily in developer local repos; pushed to `origin` only when collaboration is needed. No direct relationship with `main`.
Lifecycle:
1. Branch from `develop`.
2. Develop in isolation.
3. Merge back to `develop` with `--no-ff`.
4. Delete the branch.
### 4. Release branches (short-lived)
| Property | Value |
|---|---|
| Branch from | `develop` |
| Merge back to | both `main` AND `develop` |
| Naming | `release/<version>` (e.g. `release/1.2.0`) |
Purpose: prepare a production release. Once branched, no new features — only bug fixes, version bumping, and release metadata. This frees `develop` to receive features for the *next* release immediately.
Lifecycle:
1. Branch from `develop` when it has reached the desired state.
2. Bump the version number as the first commit.
3. Fix last-minute bugs directly on the release branch.
4. Merge into `main` with `--no-ff`; tag the merge commit with the version.
5. Merge back into `develop` with `--no-ff` (to carry bug fixes forward).
6. Delete the branch.
### 5. Hotfix branches (short-lived)
| Property | Value |
|---|---|
| Branch from | `main` (from the tagged production commit) |
| Merge back to | both `main` AND `develop` (or active release branch) |
| Naming | `hotfix/<version>` (e.g. `hotfix/1.2.1`) |
Purpose: emergency patches for production bugs. Allows fixing critical issues without interrupting feature development on `develop`.
Lifecycle:
1. Branch from `main`.
2. Bump the patch version.
3. Fix the bug.
4. Merge into `main` with `--no-ff`; tag with new version.
5. Merge into `develop` with `--no-ff` — or into the active release branch if one is open (it will carry the fix into `develop` at close).
6. Delete the branch.
## Naming Conventions
| Branch type | Convention | Examples |
|---|---|---|
| Permanent | exact name | `main`, `develop` |
| Feature | `feature/<name>` | `feature/login-oauth`, `feature/JIRA-42-cart` |
| Release | `release/<version>` | `release/2.1.0` |
| Hotfix | `hotfix/<version>` | `hotfix/2.1.1` |
Versions follow semantic versioning: `MAJOR.MINOR.PATCH`.
## The `--no-ff` Rule
All merges of supporting branches (feature, release, hotfix) into permanent branches use `--no-ff`:
```bash
git merge --no-ff <branch>
```
This forces a merge commit even when a fast-forward is possible, preserving the branch history in the DAG. Without it, the commit group collapses into a linear history and you lose the ability to identify which commits belonged to a given feature or to revert a feature atomically by reverting the merge commit.
## Hard Invariants
1. `main` only receives merges from `release/*` and `hotfix/*`.
2. `develop` only receives merges from `feature/*`, `release/*`, and `hotfix/*`.
3. All merges into permanent branches use `--no-ff`.
4. Release branches are created from `develop`; hotfix branches are created from `main`.
5. Both release and hotfix branches merge into **both** `main` and `develop` at close.
6. Version tags are applied to the merge commit on `main`.
## git-flow CLI
The `git-flow` CLI wraps the manual operations. The `git-flow-avh` fork is the most maintained.
**Setup:**
```bash
git flow init # interactive prompt for branch naming
git flow init -d # use defaults without prompting
```
**Feature branches:**
```bash
git flow feature start <name> # branch feature/<name> from develop
git flow feature finish <name> # merge into develop (--no-ff), delete
git flow feature publish <name> # push to origin
git flow feature track <name> # track a remote feature branch
```
**Release branches:**
```bash
git flow release start <version> # branch release/<version> from develop
git flow release publish <version> # push for collaboration
git flow release finish <version> # merge into main (tagged) + develop, delete
```
**Hotfix branches:**
```bash
git flow hotfix start <version> # branch hotfix/<version> from main
git flow hotfix finish <version> # merge into main (tagged) + develop, delete
```
## When to Use Gitflow
**Good fit:**
- Software with explicit versioned releases: libraries, desktop apps, mobile apps, versioned APIs.
- Projects that must maintain and patch multiple concurrent production versions.
- Larger teams with parallel feature development and release preparation happening simultaneously.
- Workflows where release preparation (docs, QA, sign-off) takes meaningful calendar time.
**Poor fit / when not to use:**
- Continuously deployed web applications (SaaS, internal tools, websites) — release branches add ceremony with no benefit when deploys happen multiple times per day.
- Teams practising trunk-based development where the trunk is always deployable — GitHub Flow (short-lived feature branches off `main`, fast merges, immediate deploy) is simpler and better matched.
- Small teams or solo projects where branching overhead exceeds the benefit.
- Projects without versioned releases.
Driessen's own 2020 note: "If your team is doing continuous delivery of software, I would suggest to adopt a much simpler workflow (like GitHub Flow) instead of trying to shoehorn git-flow into your team."
plugins/git/docs/research/docs/git/history-inspection.md
+359
View File
@@ -0,0 +1,359 @@
---
topic: history-inspection
source_keys:
- git-scm-bisect-docs
- git-scm-log-docs
- git-scm-diff-docs
- context7-git-htmldocs
---
## git bisect
Binary search through commit history to find the commit that introduced a bug or behaviour change. Requires O(log2 N) test steps.
### Core Workflow
```bash
git bisect start
git bisect bad # current HEAD is broken
git bisect good <commit> # known-good baseline
# Git checks out midpoint. Test, then:
git bisect good # test passed
git bisect bad # test failed
# Repeat until Git prints "X is the first bad commit"
git bisect reset # return to original HEAD
git bisect reset <commit> # return to a specific commit
git bisect reset bisect/bad # check out the bad commit itself
```
Compact start form:
```bash
git bisect start HEAD v1.2 -- # HEAD=bad, v1.2=good; -- separates paths
git bisect start HEAD v1.2 -- src/ # limit bisection to src/ directory
```
### bisect run — Automated Mode
```bash
git bisect run <cmd> [<arg>...]
```
Runs `<cmd>` on each candidate commit. Git interprets the exit code:
| Exit code | Meaning |
|---|---|
| `0` | Good (test passed) |
| `1–124` | Bad (test failed) |
| `125` | Skip this commit (cannot test — e.g. build broken) |
| `126–127` | POSIX shell errors — treated as bad |
| `128+` | Aborts the bisect session |
The 125 build-failure skip pattern:
```bash
#!/bin/sh
make || exit 125 # skip if build is broken
./check_test_case.sh # 0=good, nonzero=bad
```
Keep test scripts outside the repository so checkout does not clobber them.
### bisect skip
```bash
git bisect skip # skip current commit
git bisect skip v2.5..v2.6 # skip a range (v2.5 exclusive, v2.6 inclusive)
git bisect skip v2.5 v2.5..v2.6 # skip point commit + range
```
If the first bad commit is adjacent to a skipped commit, bisect reports it cannot pinpoint the exact culprit but prints the likely candidates.
### bisect log / bisect replay
```bash
git bisect log # print session history (good/bad/skip decisions)
git bisect log > bisect.log # save to file
# edit bisect.log to remove a wrong decision
git bisect reset && git bisect replay bisect.log # replay from edited log
```
Use `log` + `replay` to undo mistakes without restarting from scratch.
### bisect visualize / view
```bash
git bisect visualize # open remaining suspects in gitk
git bisect view # alias for visualize
git bisect visualize --stat # show stat instead of full diff
git bisect visualize -p # show patches
```
Falls back to `git log` when no graphical display is detected (checks `DISPLAY`, `SESSIONNAME`, `MSYSTEM`, `SECURITYSESSIONID`).
### Non-Bug Hunts: new / old / custom terms
Use `new`/`old` when searching for a property change rather than a regression:
```bash
git bisect start
git bisect new HEAD # has the property
git bisect old HEAD~10 # does not have the property
```
Custom terms:
```bash
git bisect start --term-new slow --term-old fast
git bisect slow # equivalent to: git bisect bad
git bisect fast # equivalent to: git bisect good
git bisect terms # show active term names
```
### Advanced Start Flags
| Flag | Effect |
|---|---|
| `--no-checkout` | Updates `BISECT_HEAD` ref instead of checking out; useful for tests that don't need a working tree; automatic in bare repos |
| `--first-parent` | Follow only first parents at merges; finds the integration commit that introduced a regression; ignores broken side branches |
| `-- <path>...` | Limit bisection to specific paths; reduces number of trials |
---
## git log — Format and Filtering
### Named Format Presets (`--format` / `--pretty`)
| Name | Output |
|---|---|
| `oneline` | `<hash> <title>` |
| `short` | hash, author, title |
| `medium` | hash, author, date, full message (default) |
| `full` | adds committer |
| `fuller` | separate author/committer dates |
| `reference` | `<abbrev> (<title>, <date>)` — for use in commit messages |
| `email` | RFC 2822 email format |
| `raw` | full object as stored in the object database |
| `format:<str>` | custom template with placeholders |
### Custom Format Placeholders
**Commit identity:**
| Placeholder | Meaning |
|---|---|
| `%H` | full commit hash |
| `%h` | abbreviated commit hash |
| `%T` | tree hash |
| `%t` | abbreviated tree hash |
| `%P` | full parent hashes |
| `%p` | abbreviated parent hashes |
**Author:**
| Placeholder | Meaning |
|---|---|
| `%an` | author name |
| `%aN` | author name (mailmap-resolved) |
| `%ae` | author email |
| `%aE` | author email (mailmap-resolved) |
| `%ad` | author date (respects `--date=`) |
| `%ar` | author date, relative |
| `%at` | author date, UNIX timestamp |
| `%ai` | author date, ISO 8601-like |
| `%aI` | author date, strict ISO 8601 |
| `%as` | author date, short (YYYY-MM-DD) |
**Committer:**
| Placeholder | Meaning |
|---|---|
| `%cn` | committer name |
| `%ce` | committer email |
| `%cd` | committer date (respects `--date=`) |
| `%cr` | committer date, relative |
| `%ct` | committer date, UNIX timestamp |
| `%ci` | committer date, ISO 8601-like |
| `%cs` | committer date, short |
**Message:**
| Placeholder | Meaning |
|---|---|
| `%s` | subject (first line) |
| `%f` | sanitized subject (filename-safe) |
| `%b` | body (everything after blank line following subject) |
| `%B` | raw body (subject + body) |
| `%N` | commit notes |
**Refs and decorations:**
| Placeholder | Meaning |
|---|---|
| `%d` | ref names (like `--decorate`) |
| `%D` | ref names without surrounding parentheses |
| `%S` | ref name by which commit was reached (requires `--source`) |
| `%(decorate[:opts])` | custom decorated refs; options: `prefix=`, `suffix=`, `separator=`, `pointer=`, `tag=` |
| `%(describe[:opts])` | like `git describe`; options: `tags=`, `abbrev=`, `match=`, `exclude=` |
**GPG signature:**
| Placeholder | Meaning |
|---|---|
| `%G?` | status: `G`=good, `B`=bad, `U`=unknown, `X`=expired, `R`=revoked, `N`=no signature |
| `%GS` | signer name |
| `%GK` | signing key ID |
**Trailers:**
```
%(trailers[:key=<k>][,only][,separator=<s>][,unfold][,keyonly][,valueonly])
```
**Formatting / color:**
| Placeholder | Meaning |
|---|---|
| `%n` | newline |
| `%%` | literal `%` |
| `%Cred` / `%Cgreen` / `%Cblue` / `%Creset` | terminal colors |
| `%C(<spec>)` | color per git-config spec |
| `%<(<n>[,trunc])` | right-pad field to width n |
| `%>(<n>)` | left-pad to width |
**Reflog** (requires `-g` / `--walk-reflogs`):
| Placeholder | Meaning |
|---|---|
| `%gD` | reflog selector (e.g. `refs/stash@{1}`) |
| `%gd` | shortened reflog selector |
| `%gs` | reflog subject |
### Pickaxe Search: -S and -G
**`-S<string>`** — finds commits where the **count** of `<string>` changed (i.e. the string was added or removed net). Does not match commits where the string merely appears in a diff hunk without a count change.
```bash
git log -S"my_function"
git log -S"my_function" --pickaxe-regex # treat as POSIX ERE
git log -S"my_function" --pickaxe-all # show all files in matching changesets
```
**`-G<regex>`** — finds commits where any added or removed **line** in the patch matches `<regex>`. Broader than `-S`: matches whenever the pattern appears in diff text regardless of count.
```bash
git log -G"frotz\(nitfol"
```
**Critical distinction:** given a diff that removes one occurrence of `foo` and adds one occurrence of `foo` (net change = 0):
- `-S"foo"` — does **not** match (count unchanged)
- `-G"foo"` — **matches** (pattern appears in patch text)
Binary files are searched by `-S`; ignored by `-G` unless `--text` is supplied.
**`--pickaxe-all`** — when a match is found, show all changed files in that changeset, not just the matching ones.
### --follow
```bash
git log --follow -- <file>
```
Continues file history across renames. Without `--follow`, log stops at the rename boundary. Only valid for a single file path.
### --diff-filter
Selects commits (in `git log`) or files (in `git diff`) by change type:
| Letter | Meaning |
|---|---|
| `A` | Added |
| `C` | Copied |
| `D` | Deleted |
| `M` | Modified |
| `R` | Renamed |
| `T` | Type changed (regular file ↔ symlink ↔ submodule) |
| `U` | Unmerged (conflict) |
| `X` | Unknown (indicates a git bug) |
| `B` | Pairing broken |
Lowercase letters **exclude** that type:
```bash
git log --diff-filter=ad # exclude added and deleted files
git log --diff-filter=M # only show commits with modified files
```
`C` and `R` only appear when copy/rename detection is enabled (`-C`, `-M` flags or `diff.renames` config).
### -L — Line Range History
Traces the evolution of a specific range of lines or a named function through commits. Implies `--patch`.
```bash
git log -L 10,20:file.txt
git log -L /start_pattern/,/end_pattern/:file.txt
git log -L :myfunction:src/app.c
git log -L /init/,+15:config.py # 15 lines after first match of /init/
```
Range formats:
| Format | Meaning |
|---|---|
| `<n>` | Absolute line number (1-based) |
| `/<regex>/` | First line matching regex from previous range end |
| `^/<regex>/` | First line matching regex from file start |
| `+<n>` / `-<n>` | Offset relative to `<start>` (end position only) |
Limitations: incompatible with `--raw`, `--numstat`, `--shortstat`, `--name-only`, `--name-status`, `--check`. Cannot use pathspec limiters alongside `-L`.
### Graph and Ancestry Filters
```bash
git log --first-parent # at merges, follow only first parent (mainline evolution)
git log --merges # only merge commits (≥2 parents); equivalent to --min-parents=2
git log --no-merges # only non-merge commits; equivalent to --max-parents=1
git log --ancestry-path D..M # only commits actually on the path from D to M
git log --min-parents=<n> # include only commits with ≥ n parents
git log --max-parents=<n> # include only commits with ≤ n parents
```
`--ancestry-path` is significant: without it, `D..M` includes all commits reachable from M but not D — including side branches that merged into the path. With it, only commits directly between D and M are shown.
---
## git diff — Output Control
### --stat
```bash
git diff --stat # diffstat: file names + ± bar
git diff --stat=<width>,<name-width>,<count>
git diff --compact-summary # alongside --stat: shows new/gone, +x/-x (executable), +l (symlink)
git diff --numstat # machine-readable: <added>\t<deleted>\t<path>; - for binary
```
### --name-only / --name-status
```bash
git diff --name-only # only filenames, one per line
git diff --name-status # status letter + filename per line
```
`--name-status` uses the same status letters as `--diff-filter`.
### --word-diff
```bash
git diff --word-diff # inline word-level diff with [-removed-] {+added+} markers
git diff --word-diff=color # color only, no markers
git diff --word-diff=porcelain # machine-readable: +/- prefixed lines, ~ for newlines
git diff --word-diff-regex=<re> # define what counts as a "word"
```
### Whitespace Flags
| Flag | Effect |
|---|---|
| `-b` / `--ignore-space-change` | Treat any run of whitespace as equivalent; ignore trailing whitespace |
| `-w` / `--ignore-all-space` | Ignore all whitespace completely |
| `--ignore-space-at-eol` | Ignore whitespace at end-of-line only |
| `--ignore-blank-lines` | Ignore changes consisting entirely of blank lines |
| `-I<regex>` / `--ignore-matching-lines=<re>` | Ignore changes where all changed lines match regex |
plugins/git/docs/research/docs/git/installation.md
+53
View File
@@ -0,0 +1,53 @@
---
topic: installation
source_keys:
- git-scm-docs
---
## Linux
Debian / Ubuntu:
```bash
sudo apt install git-all
```
Fedora / RHEL / CentOS:
```bash
sudo dnf install git-all
```
Other distributions use their native package manager. The `git-all` meta-package pulls in optional tools (GUI clients, credential helpers); install `git` alone for the minimal CLI.
## macOS
The fastest path — run any git command and macOS prompts you to install the Xcode Command Line Tools:
```bash
git --version
```
This installs Apple's bundled git. For a more recent version, use the binary installer from git-scm.com or install via Homebrew:
```bash
brew install git
```
## Windows
**Option 1 — Git for Windows** (recommended): download the installer from git-scm.com/download/win. It includes Git Bash (a POSIX shell), Git GUI, and optionally integrates with the Windows credential manager.
**Option 2 — Chocolatey**:
```bash
choco install git
```
**Option 3 — winget**:
```bash
winget install --id Git.Git
```
## Post-install Verification
```bash
git --version
```
Minimum recommended versions for modern features: 2.23+ (for `git switch` / `git restore`), 2.38+ (for `git worktree` improvements).
plugins/git/docs/research/docs/git/overview.md
+76
View File
@@ -0,0 +1,76 @@
---
topic: overview
source_keys:
- context7-git-htmldocs
---
## What Git Is
Git is a distributed version control system designed to track changes in source code across the full lifetime of a project. Unlike centralised VCS tools, every developer holds a complete copy of the repository — full history, all branches, all objects. This means most operations (log, diff, branch, commit) are local and fast, and the repository survives any single node failing.
## Core Mental Model
Git models a project's history as a directed acyclic graph (DAG) of commit objects. Each commit is identified by a SHA-1 hash derived from its content and parent references, making history immutable by design. You cannot change a past commit — you can only create new commits that supersede it.
Three areas govern where changes live at any moment:
- **Working tree** — the files on disk you edit directly.
- **Index (staging area)** — a snapshot assembled for the next commit. Changes must be explicitly staged with `git add` before they become part of a commit.
- **Repository (`.git/`)** — the permanent object store. Once committed, content is addressable by hash.
## Key Concepts
**Repository** — a `.git/` directory containing all objects (blobs, trees, commits, tags) and refs. Bare repositories (no working tree) are used as shared remotes.
**Commit** — a snapshot of the entire repository tree at a point in time, plus a pointer to its parent(s), author metadata, and a message. A merge commit has two parents.
**Branch** — a movable pointer to a commit. Creating a branch is cheap: it is just a 41-byte ref file. Switching branches (`git checkout` / `git switch`) updates HEAD and the working tree.
**HEAD** — a symbolic ref pointing to the currently checked-out branch (or directly to a commit in detached HEAD state). The next commit advances whatever HEAD points to.
**Remote** — a named reference to another repository. `origin` is the conventional name for the repository a local repo was cloned from. Remotes are fetched into remote-tracking branches (e.g. `origin/main`) which are local, read-only mirrors.
**Tag** — a permanent, human-readable name for a specific commit. Annotated tags carry a message and are signed; lightweight tags are just a ref alias.
**Ref** — any named pointer to a commit: branches live under `refs/heads/`, tags under `refs/tags/`, remotes under `refs/remotes/`.
## Repository Structure
```
.git/
├── HEAD # points to current branch or commit
├── config # local repo config
├── index # staging area (binary)
├── objects/ # content-addressable object store
│ ├── pack/ # packed objects for efficiency
│ └── info/
├── refs/
│ ├── heads/ # local branch tips
│ ├── remotes/ # remote-tracking branches
│ └── tags/ # tags
├── hooks/ # optional shell scripts on git events
├── modules/ # submodule git dirs (when present)
└── worktrees/ # linked worktree metadata (when present)
```
## Fundamental Workflow
```bash
git init # create a new repository
git add <file> # stage changes
git diff --cached # review what is staged
git commit -m "message" # snapshot staged changes
git log --oneline --graph # visualise history
git push origin main # send commits to remote
git pull # fetch + merge (or rebase) from remote
```
## Architecture Properties
**Distributed** — every clone is a full backup. There is no single point of failure at the protocol level.
**Content-addressed** — objects are stored by their SHA-1 hash. Identical content is stored once regardless of how many branches or commits reference it.
**Immutable history** — commit hashes change if content changes. Rewriting history (rebase, amend) creates new commits; old ones remain until garbage-collected.
**Porcelain vs plumbing** — Git exposes high-level commands for humans (porcelain: `commit`, `merge`, `log`) and low-level commands for scripting (plumbing: `cat-file`, `update-ref`, `rev-parse`). Scripts should prefer plumbing for stability.
plugins/git/docs/research/docs/git/remotes.md
+192
View File
@@ -0,0 +1,192 @@
---
topic: remotes
source_keys:
- git-scm-push-docs
- git-scm-fetch-docs
- git-scm-pull-docs
- git-scm-remote-docs
- context7-git-htmldocs
---
## Remote Management (`git remote`)
### Add
```bash
git remote add <name> <url>
git remote add -f <name> <url> # fetch immediately after adding
git remote add -t <branch> <name> <url> # track only one branch (repeatable)
git remote add --no-tags <name> <url> # suppress automatic tag import
git remote add --mirror=fetch <name> <url> # mirror all refs locally (bare repos only)
git remote add --mirror=push <name> <url> # every push behaves like --mirror
```
### Remove / Rename / URLs
```bash
git remote remove <name> # delete remote + all tracking refs + config
git remote rename <old> <new>
git remote set-url <name> <newurl> # replace first fetch URL
git remote set-url <name> <newurl> <oldurl-regex> # replace specific URL by regex
git remote set-url --push <name> <url> # change push URL only (must point same repo)
git remote set-url --add <name> <url> # add extra push URL (push to multiple remotes)
git remote set-url --delete <name> <regex> # remove matching URLs
git remote get-url <name> # show effective URL after insteadOf rewrites
git remote get-url --push --all <name> # show all push URLs
```
`--push` on `set-url` changes only where pushes go — fetch and push URLs must still reference the same repository. For genuine fetch-from-A push-to-B workflows, use two separate named remotes.
### Inspect and Housekeeping
```bash
git remote -v # list remotes with URLs
git remote show <name> # live query: tracked branches, ahead/behind status
git remote show -n <name> # same, using cached data (no network)
git remote prune <name> # delete stale tracking refs (no fetch)
git remote prune --dry-run <name> # preview what would be pruned
git remote set-head <name> -a # auto-detect remote's default branch (fetch first)
git remote set-head <name> <branch> # set remote HEAD explicitly
git remote set-head <name> -d # delete refs/remotes/<name>/HEAD
```
`git remote show` requires `-v` before `show`, not after. `set-head -a` silently does nothing if the tracking branch doesn't exist locally — always fetch first.
## Fetching (`git fetch`)
```bash
git fetch <remote> # fetch all branches from remote
git fetch <remote> <branch> # fetch one branch (stores in FETCH_HEAD)
git fetch --all # fetch from all configured remotes
git fetch --all --prune # fetch all + prune stale tracking refs
git fetch --prune # delete remote-tracking refs no longer on remote
git fetch --prune-tags # also prune local tags not on remote
git fetch --depth=<n> # deepen / create shallow clone
git fetch --unshallow # convert shallow clone to full history
git fetch --update-shallow # allow fetch to update shallow boundaries
git fetch --refmap='' <remote> <branch> # fetch without storing (FETCH_HEAD only)
```
**`--prune` does not prune tags by default.** Add `--prune-tags` explicitly, or configure permanently:
```bash
git config remote.origin.prune true # auto-prune on every fetch
git config fetch.pruneTags true # prune tags when --prune is active
```
**Remote-tracking branch mechanics.** The default fetch refspec is `+refs/heads/*:refs/remotes/origin/*`. The `+` forces updates — remote-tracking branches mirror the remote exactly and do not protect local history. Fetch never touches local branches.
## Pushing (`git push`)
```bash
git push <remote> <branch> # push branch
git push -u origin <branch> # push and set upstream (branch.<name>.remote/merge)
git push --all # push all local branches
git push --tags # push all tags
git push origin <tag> # push a specific tag
git push origin --delete <branch> # delete remote branch
git push origin :<branch> # delete remote branch (refspec form)
git push --prune origin 'refs/heads/*:refs/heads/*' # delete remote branches with no local counterpart
```
### Force Push Safety
**`--force` (`-f`)** — unconditionally overwrites the remote ref. Applies to all refs in the push. To force only one ref, use `+` in the refspec:
```bash
git push origin +main develop # forces main, safe-pushes develop
```
**`--force-with-lease`** — rejects the push if the remote ref has moved since your last fetch. Three forms:
| Form | What it protects |
|---|---|
| `--force-with-lease` (bare) | All refs being pushed, vs. remote-tracking branch |
| `--force-with-lease=<refname>` | Named ref only |
| `--force-with-lease=<refname>:<sha>` | Named ref must be at exact SHA — stable, not experimental |
**Critical caveat with the bare form:** any background process that runs `git fetch` (IDE plugin, cron, editor) updates your remote-tracking branch, making the lease check pass even if someone else has pushed. The protection is silently defeated.
Two mitigations:
```bash
# Option 1: dedicated push remote (background tools only fetch origin)
git remote add origin-push $(git config remote.origin.url)
git push --force-with-lease origin-push
# Option 2: explicit SHA via tag (unaffected by tracking branch state)
git fetch
git tag base master
git rebase -i master
git push --force-with-lease=master:base master:master
```
**`--force-if-includes`** — adds a second check on top of bare `--force-with-lease`: verifies the remote-tracking tip appears in your local branch's reflog, meaning you actually integrated it. No-op without `--force-with-lease`. Has no effect when `--force-with-lease=<ref>:<sha>` is used.
Safest force-push combination:
```bash
git push --force-with-lease --force-if-includes origin
```
### Refspec Syntax
```
[+]<src>[:<dst>]
```
| Pattern | Meaning |
|---|---|
| `<branch>` | Push to same-named remote branch |
| `<src>:<dst>` | Push `<src>` local ref to `<dst>` remote ref |
| `+<src>:<dst>` | Force this refspec (non-fast-forward allowed) |
| `:<branch>` | Delete remote `<branch>` |
| `refs/heads/*:refs/heads/*` | Glob: push all matching branches |
| `^refs/heads/dev-*` | Negative: exclude matching refs |
| `tag <name>` | Sugar for `refs/tags/<name>:refs/tags/<name>` |
Remote-side policies (`receive.denyDeletes`, `receive.denyDeleteCurrent`, `receive.denyNonFastForwards`) are enforced server-side regardless of local flags.
## Pulling (`git pull`)
`git pull` is `git fetch` followed by a merge or rebase. Always fetch first if you want control; `git pull` is convenient but less explicit.
### Diverged Branch Resolution Strategies
**`--ff-only`** (recommended default for disciplined teams)
- Succeeds only when local is a strict ancestor of remote — no divergence.
- Fails explicitly when diverged, forcing a conscious choice.
- Config: `git config pull.ff only`
**`--rebase`** / `--rebase=true`
- Replays local unpublished commits on top of fetched tip. Linear history.
- Rewrites SHAs — unsafe for commits already pushed to a shared branch.
- Config: `git config pull.rebase true`
**`--rebase=merges`**
- Preserves intentional local merge commits during replay.
- Config: `git config pull.rebase merges`
**`--no-rebase`** / merge (default when `pull.rebase=false`)
- Three-way merge commit. Non-linear history. Original commits unchanged.
- Config: `git config pull.rebase false`
**`--squash`**
- Collapses all incoming commits into staged changes. Does not commit. You write the commit message.
### Config Precedence for Pull Behaviour
Precedence (highest wins):
1. Command-line flag
2. `pull.rebase` global/local config
3. `branch.<name>.rebase` (branch-specific override)
4. `branch.autoSetupRebase` (set on tracking branch creation)
Per-branch override example:
```bash
git config --global pull.rebase true
git config branch.develop.rebase false # develop always merges
```
### Pull Gotchas
- Rebase rewrites SHAs. Only rebase unpublished local work — rebasing already-pushed commits causes conflicts for everyone downstream.
- `--recurse-submodules` only fetches already-checked-out submodules; newly added submodules are not initialized automatically.
- Default merge strategy changed to `ort` in Git 2.34. `recursive` is now an alias. Strategy options (`-X ours`, `-X theirs`, `-X ignore-space-change`) still pass through.
- `pull.rebase` default became `--ff-only` in recent Git versions. Teams migrating from older Git should set this explicitly to avoid surprises.
plugins/git/docs/research/docs/git/sources.md
+113
View File
@@ -0,0 +1,113 @@
# Sources
## context7-git-htmldocs
- **URL:** context7:/git/htmldocs
- **Description:** Official Git HTML documentation from the git/htmldocs repository — covers all commands, concepts, and internals (19,370 code snippets, High reputation).
- **Contributing files:** overview.md, cli-reference.md, branching-merging.md
- **Status:** `extracted`
## git-scm-docs
- **URL:** https://git-scm.com/docs/git-config
- **Description:** Official git-scm.com reference pages — git-config manual covering all config variables, scopes, and the installation guide.
- **Contributing files:** installation.md, configuration.md, cli-reference.md
- **Status:** `extracted`
## git-scm-submodule-docs
- **URL:** https://git-scm.com/docs/git-submodule
- **Description:** Official git-scm.com reference for git-submodule — all subcommands, flags, configuration keys, and behaviour details.
- **Contributing files:** submodules.md
- **Status:** `extracted`
## git-scm-worktree-docs
- **URL:** https://git-scm.com/docs/git-worktree
- **Description:** Official git-scm.com reference for git-worktree — all subcommands, flags, ref-sharing rules, and gotchas.
- **Contributing files:** worktrees.md
- **Status:** `extracted`
## nvie-gitflow-post
- **URL:** https://nvie.com/posts/a-successful-git-branching-model/
- **Description:** Original 2010 post by Vincent Driessen introducing the Gitflow branching model, including a 2020 reflection note recommending GitHub Flow for continuous delivery teams.
- **Contributing files:** gitflow.md
- **Status:** `extracted`
## atlassian-gitflow-tutorial
- **URL:** https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
- **Description:** Atlassian's comprehensive Gitflow tutorial covering all five branch types, lifecycle steps, and CLI usage.
- **Contributing files:** gitflow.md
- **Status:** `extracted`
## gitflow-cheatsheet
- **URL:** https://danielkummer.github.io/git-flow-cheatsheet/
- **Description:** Visual cheatsheet for the git-flow CLI commands (git-flow-avh fork), covering all subcommands for feature, release, and hotfix branches.
- **Contributing files:** gitflow.md
- **Status:** `extracted`
## conventional-commits-spec
- **URL:** https://www.conventionalcommits.org/en/v1.0.0/
- **Description:** The Conventional Commits v1.0.0 specification — full format rules, breaking change conventions, footer token format, examples, and SemVer mapping rationale.
- **Contributing files:** commits.md
- **Status:** `extracted`
## commitlint-config-conventional
- **URL:** https://github.com/conventional-changelog/commitlint
- **Description:** The commitlint `@commitlint/config-conventional` package — defines the 11 standard commit types, header length limits, and validation constraints.
- **Contributing files:** commits.md
- **Status:** `extracted`
## git-scm-push-docs
- **URL:** https://git-scm.com/docs/git-push
- **Description:** Official git-scm.com reference for git-push — refspec syntax, --force-with-lease semantics (including background-fetch caveat and mitigations), --force-if-includes, --delete, --prune, --set-upstream.
- **Contributing files:** remotes.md
- **Status:** `extracted`
## git-scm-fetch-docs
- **URL:** https://git-scm.com/docs/git-fetch
- **Description:** Official git-scm.com reference for git-fetch — --prune, --prune-tags, --all, --depth, --unshallow, --update-shallow, remote-tracking branch mechanics and refmap.
- **Contributing files:** remotes.md
- **Status:** `extracted`
## git-scm-pull-docs
- **URL:** https://git-scm.com/docs/git-pull
- **Description:** Official git-scm.com reference for git-pull — diverged branch resolution strategies (--ff-only, --rebase variants, merge), pull.rebase config precedence, and gotchas.
- **Contributing files:** remotes.md
- **Status:** `extracted`
## git-scm-remote-docs
- **URL:** https://git-scm.com/docs/git-remote
- **Description:** Official git-scm.com reference for git-remote — add, remove, rename, set-url (fetch/push split), prune, set-head, show, get-url with insteadOf resolution.
- **Contributing files:** remotes.md
- **Status:** `extracted`
## git-scm-bisect-docs
- **URL:** https://git-scm.com/docs/git-bisect
- **Description:** Official git-scm.com reference for git-bisect — full workflow, bisect run exit code semantics, bisect skip, log/replay, visualize, new/old/custom terms, --no-checkout, --first-parent.
- **Contributing files:** history-inspection.md
- **Status:** `extracted`
## git-scm-log-docs
- **URL:** https://git-scm.com/docs/git-log
- **Description:** Official git-scm.com reference for git-log — full --format placeholder table, -S/-G pickaxe search, --follow, --diff-filter, -L line range history, --ancestry-path, --first-parent, --merges.
- **Contributing files:** history-inspection.md
- **Status:** `extracted`
## git-scm-diff-docs
- **URL:** https://git-scm.com/docs/git-diff
- **Description:** Official git-scm.com reference for git-diff — --diff-filter letter table, --stat variants, --name-only/--name-status, --word-diff modes, whitespace flags.
- **Contributing files:** history-inspection.md
- **Status:** `extracted`
plugins/git/docs/research/docs/git/submodules.md
+203
View File
@@ -0,0 +1,203 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
## Concept Overview
A submodule is a full Git repository embedded as a subdirectory inside a parent repository (the superproject). The superproject does not store the submodule's files — it stores a pointer to a specific commit SHA in the submodule's history. Submodules maintain completely independent commit histories.
Two files govern submodules:
- `.gitmodules` — version-controlled; defines each submodule's name, path, and URL. Shared with collaborators.
- `.git/config` — local only; populated on `git submodule init`. Override URLs here before fetching.
The submodule's git directory lives at `.git/modules/<name>/`, linked to the working tree via a `.git` pointer file. The working directory normally ends up in **detached HEAD state** after `git submodule update`.
## Key Commands
### Add a submodule
```bash
git submodule add <url> <path>
git submodule add -b <branch> <url> <path> # track a specific branch
git submodule add --depth 1 <url> <path> # shallow clone
git submodule add -f <url> <path> # force-add (gitignored path or name conflict)
git submodule add --name <name> <url> <path> # logical name differs from path
```
After `add`, two items are staged: a new `.gitmodules` entry and a gitlink at the path. A `git commit` is still required.
### Initialize
```bash
git submodule init [<path>...]
```
Copies submodule URLs from `.gitmodules` to `.git/config`. This is where you can edit local URL overrides before fetching. Does not clone.
### Update (clone + checkout)
```bash
git submodule update --init --recursive # most common: init + update, all levels
git submodule update --remote --merge # update to remote branch tip
git submodule update --remote --rebase # same, via rebase
git submodule update --jobs <n> # parallel updates
git submodule update -f # force (discard local changes)
```
| Flag | Meaning |
|---|---|
| `--init` | Run init first (avoids a separate step) |
| `--remote` | Use the submodule's remote branch tip instead of the superproject's recorded commit |
| `--checkout` | Detached HEAD at recorded commit (default) |
| `--rebase` | Rebase current branch onto recorded commit |
| `--merge` | Merge recorded commit into current branch |
| `--recursive` | Operate on nested submodules |
| `--jobs <n>` | Parallel clone (defaults to `submodule.fetchJobs`) |
| `-N` / `--no-fetch` | Skip remote fetch |
| `--depth <n>` | Shallow clone |
| `--filter <spec>` | Partial clone filter |
### Status
```bash
git submodule status [--recursive] [<path>...]
git submodule status --cached # show SHA in superproject index
```
Prefix meanings:
- `-` — not initialized
- `+` — checked-out commit differs from superproject's recorded commit
- `U` — merge conflict inside the submodule
- (blank) — clean
### Deinit (unregister)
```bash
git submodule deinit <path>
git submodule deinit --all # all submodules
git submodule deinit -f <path> # force (local modifications present)
```
Removes the submodule section from `.git/config` and empties the working tree. Does **not** remove the entry from `.gitmodules` or the gitlink from the index — use `git rm` for that.
### Remove completely
```bash
git submodule deinit path/to/sub
git rm path/to/sub
rm -rf .git/modules/<name> # stale git dir not auto-cleaned
git commit -m "Remove submodule"
```
### Sync URLs
```bash
git submodule sync [--recursive]
```
Propagates URL changes from `.gitmodules` into `.git/config`. Use after a submodule's remote URL has been renamed upstream.
### Run a command in every submodule
```bash
git submodule foreach <command>
git submodule foreach --recursive <command>
git submodule foreach 'git pull origin main || :' # || : continues on failure
```
Available shell variables inside `<command>`: `$name`, `$sm_path`, `$displaypath`, `$sha1`, `$toplevel`.
### Other subcommands
```bash
git submodule summary [<path>...] # show commits between recorded and current
git submodule set-branch -b <branch> <path> # set tracking branch for --remote
git submodule set-url <path> <url> # update URL in .gitmodules + sync
git submodule absorbgitdirs [<path>...] # move embedded .git/ into .git/modules/
```
## Workflow Patterns
### Clone a repo with submodules
```bash
# One step (Git 2.13+)
git clone --recurse-submodules <url>
# Two steps
git clone <url>
git submodule update --init --recursive
```
### Add a dependency as a submodule
```bash
git submodule add https://github.com/org/lib.git libs/lib
git commit -m "chore: add lib as submodule"
```
### Keep submodules pinned to superproject's recorded commit
```bash
git submodule update --recursive # after every git pull
```
Configure Git to do this automatically on pull:
```bash
git config submodule.recurse true
```
### Update submodules to latest on their remote branch
```bash
git submodule update --remote --merge --recursive
git commit -am "chore: update submodules to latest"
```
### Override a submodule URL locally (private mirror)
```bash
git submodule init
# Edit .git/config to change the URL
git submodule update
```
## Common Gotchas
**Detached HEAD by default.** `git submodule update` checks out a specific commit, not a branch. Commits made inside the submodule are invisible to the superproject until you update the pointer. Always check your branch before committing inside a submodule.
**Two pushes required.** Commit and push inside the submodule first, then update the pointer in the superproject and push that. Forgetting to push the submodule leaves others unable to fetch the recorded commit.
**`--recursive` is not the default.** Most commands operate one level deep. Pass `--recursive` explicitly for nested submodules.
**Relative URLs are relative to the remote, not the filesystem.** `../foo.git` is relative to the superproject's default remote URL.
**Custom update commands are security-gated.** A `.gitmodules` entry of `update = !some-command` is not copied to `.git/config` by `git submodule init`, so cloning cannot execute arbitrary code automatically.
**`deinit` is not removal.** Use `git rm` after `deinit` to actually remove from the repo. Also delete `.git/modules/<name>/` manually.
**`.git/modules/` persists after `git rm`.** Re-adding the same path will fail until you delete it.
## Configuration
In `.gitmodules` (version-controlled):
| Key | Purpose |
|---|---|
| `submodule.<name>.path` | Working tree path |
| `submodule.<name>.url` | Remote URL |
| `submodule.<name>.branch` | Branch for `update --remote` |
| `submodule.<name>.update` | Default update procedure |
| `submodule.<name>.shallow` | Recommend shallow clone |
In `.git/config` (local, after `init`):
| Key | Purpose |
|---|---|
| `submodule.<name>.url` | Local URL override |
| `submodule.<name>.update` | Local procedure override |
| `submodule.fetchJobs` | Default parallelism for `update --jobs` |
| `submodule.recurse` | Auto-recurse on `pull`, `push`, etc. |
plugins/git/docs/research/docs/git/worktrees.md
+181
View File
@@ -0,0 +1,181 @@
---
topic: worktrees
source_keys:
- git-scm-worktree-docs
---
## Concept Overview
A worktree lets you check out multiple branches simultaneously from one repository, each in its own directory on disk. All worktrees share the same objects, configuration, and most refs — but each has its own `HEAD`, index, and per-worktree metadata.
**Main worktree** — the original working tree from `git init` or `git clone`. Exactly one per repo. Cannot be removed or moved via git commands (use `repair` if moved manually).
**Linked worktree** — any additional worktree created with `git worktree add`. Multiple can coexist. Each gets a private directory at `$GIT_DIR/worktrees/<name>/` holding its `HEAD`, `index`, `gitdir` pointer, and optionally a `locked` file.
**Shared across worktrees:** everything under `refs/` (branches, tags, remotes), objects, config.
**Per-worktree (not shared):** `HEAD`, `ORIG_HEAD`, `MERGE_HEAD`, refs under `refs/bisect/`, `refs/worktree/`, `refs/rewritten/`.
## Key Commands
### Add a worktree
```bash
git worktree add <path> # create worktree, derive branch from path basename
git worktree add <path> <branch> # check out existing branch
git worktree add -b <new-branch> <path> # create and check out new branch
git worktree add -B <branch> <path> # create or reset branch to HEAD
git worktree add -d <path> # detached HEAD
git worktree add --orphan -b <branch> <path> # new unborn branch
```
| Flag | Meaning |
|---|---|
| `-b <branch>` | Create and check out a new branch; fails if it exists |
| `-B <branch>` | Like `-b` but resets the branch if it already exists |
| `-d` / `--detach` | Detach HEAD; useful for throwaway experiments |
| `--orphan` | Create empty unborn branch |
| `--no-checkout` | Suppress initial checkout (for sparse-checkout setup) |
| `--guess-remote` | Look for a matching remote-tracking branch by path basename |
| `--lock [--reason <str>]` | Lock immediately on creation (atomic; avoids race vs. add-then-lock) |
| `-f` / `--force` | Allow when branch is already checked out elsewhere |
| `--relative-paths` | Link via relative paths (portable across moves) |
Using "`-`" as `<commit-ish>` is shorthand for `@{-1}` (previous branch).
### List worktrees
```bash
git worktree list # show all worktrees
git worktree list -v # show lock/prune reasons
git worktree list --porcelain # machine-readable output
git worktree list --porcelain -z # NUL-terminated (for paths with spaces)
```
Output shows path, HEAD commit, branch name, and `locked` or `prunable` status.
### Lock / Unlock
```bash
git worktree lock <worktree> --reason "on external SSD"
git worktree unlock <worktree>
```
Prevents the worktree from being pruned, moved, or deleted. Use for worktrees on removable drives or network mounts.
### Move a worktree
```bash
git worktree move <worktree> <new-path>
git worktree move -f <worktree> <new-path> # override standard safeguards
git worktree move -ff <worktree> <new-path> # override locked state too
```
Cannot move the main worktree. Cannot move a worktree that contains submodules.
### Remove a worktree
```bash
git worktree remove <worktree> # only clean worktrees (no untracked/modified files)
git worktree remove -f <worktree> # force-remove unclean
git worktree remove -ff <worktree> # force-remove even if locked
```
Deletes the worktree directory and its `$GIT_DIR/worktrees/<name>/` metadata. Main worktree cannot be removed.
### Prune stale metadata
```bash
git worktree prune # clean up orphaned metadata
git worktree prune --dry-run # preview what would be removed
git worktree prune --expire <time> # override expiry threshold
```
Cleans up `$GIT_DIR/worktrees/` entries for directories that no longer exist. Also triggered by `git gc`. Controlled by `gc.worktreePruneExpire` config.
### Repair broken connections
```bash
git worktree repair # fix all broken connections from main worktree
git worktree repair <path> # reconnect a specific linked worktree
```
Reestablishes bidirectional pointers after a manual move. Run from the main worktree after it was moved, or from a linked worktree after it was moved.
## Workflow Patterns
### Emergency fix without disrupting current work
```bash
git worktree add -b emergency-fix ../temp main
cd ../temp
# fix, commit
git commit -a -m "fix: critical production bug"
cd -
git worktree remove ../temp
```
No stashing required. Your ongoing work in the main worktree is untouched.
### Review a PR branch alongside your current work
```bash
git worktree add ../review-pr-123 origin/feature-xyz
# open ../review-pr-123 in a second editor window or terminal
```
### Throwaway experiment in detached HEAD
```bash
git worktree add -d ../experiment
# experiment freely
git worktree remove ../experiment
```
### Sparse-checkout worktree
```bash
git worktree add --no-checkout ../sparse main
cd ../sparse
git sparse-checkout init --cone
git sparse-checkout set src/
git checkout main
```
### Worktree on removable media
```bash
git worktree add /mnt/usb/project feature-branch
git worktree lock /mnt/usb/project --reason "external SSD"
# when device reconnected:
git worktree unlock /mnt/usb/project
```
## Common Gotchas
**A branch can only be checked out in one worktree at a time.** Attempting to add a worktree for an already-checked-out branch fails without `--force`.
**Submodules are unsupported.** The docs explicitly warn: "Multiple checkout in general is still experimental, and the support for submodules is incomplete. It is NOT recommended to make multiple checkouts of a superproject." Worktrees with submodules cannot be moved and require `--force` to remove.
**Never `rm -rf` a worktree directory manually.** It leaves stale metadata in `$GIT_DIR/worktrees/`. Use `git worktree remove` instead. If you already deleted manually, run `git worktree prune` or wait for `git gc`.
**Moving worktrees manually breaks bidirectional pointers.** Fix with `git worktree repair`.
**`--lock` on `add` is not the same as create-then-lock.** There is a race window between two separate calls. Use `--lock` directly on `add` when the guarantee matters.
**`extensions.worktreeConfig = true` is a one-way door for older Git.** It enables per-worktree config (`git config --worktree ...`) but makes the repo refuse to open in older Git versions. Also: `core.bare` and `core.worktree` must then live in `config.worktree`, not `config`.
**Force-flag escalation.** Some operations require `-f` twice (`-ff`) — specifically, removing or moving a locked worktree.
**Worktree identification.** Worktrees can be referenced by full path, unique basename, or unique partial path. Ambiguous partial paths error.
**`checkout.defaultRemote`** — if a branch name matches multiple remotes during `worktree add`, Git refuses unless this is configured to disambiguate.
## Configuration
| Key | Effect |
|---|---|
| `worktree.guessRemote` | Default for `--guess-remote` flag on `worktree add` |
| `worktree.useRelativePaths` | Default for `--relative-paths` on `worktree add` |
| `gc.worktreePruneExpire` | How long before stale worktree metadata is pruned by `git gc` |
| `extensions.worktreeConfig` | Enable per-worktree config scope (`config.worktree` file) |
plugins/kyberforge/docs/research/docs/pre-commit/cli-reference.md → plugins/git/docs/research/docs/pre-commit/cli-reference.md
View File
File renamed without changes.
plugins/kyberforge/docs/research/docs/pre-commit/configuration.md → plugins/git/docs/research/docs/pre-commit/configuration.md
View File
File renamed without changes.
plugins/kyberforge/docs/research/docs/pre-commit/examples.md → plugins/git/docs/research/docs/pre-commit/examples.md
View File
File renamed without changes.
plugins/kyberforge/docs/research/docs/pre-commit/hook-authoring.md → plugins/git/docs/research/docs/pre-commit/hook-authoring.md
View File
File renamed without changes.
Loaded 100 of 289 files, more files were not shown because too many files have changed in this diff. Show more