Three rounds of review on the Vale prefilter surfaced patterns worth
keeping rather than just fixing.
The first has now recurred three times in a single PR — a check reporting
success because it had silently not run — so it is flagged as a
graduation candidate per LESSONS.md's own three-instance rule.
- A clean linter result can mean "nothing was checked": the frontmatter
scope silently not matching, warning-level rules never affecting an
exit code, and globs matching zero files all produced green results
that were then cited as evidence of cleanliness.
- One signal, two consumers, no named distinction: Vale severities were
tuned for the audit report while the commit gate silently inherited the
resulting exit code, because CONTEXT.md described both as one mechanism.
- Measure a rule's false-positive rate at the severity you will ship it
at: VagueQualifier was trialled at warning, where a false positive is
free, and shipped at error, where it costs a blocked commit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
The round-3 fixes changed shipped skill content in three plugins without
touching their manifests, so installed copies would keep serving the old
content from cache. plugin-author requires a patch bump for exactly this
reason: consumers use the version to detect changes.
It matters most for lint — anyone installed at 1.1.2 has a cached
vale-run/SKILL.md stating that Vale exits non-zero on warnings, which is
backwards and would lead them to build a gate that passes everything.
- bin 1.1.0 -> 1.1.1 (caveman: suppression comments removed)
- kyberforge 1.2.3 -> 1.2.4 (skill-audit/agent-audit: Vale step reworked)
- lint 1.1.2 -> 1.1.3 (vale-run: exit-code and suppression-syntax fixes)
Marketplace entries carry no per-plugin version, so both marketplace.json
files are unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Round-3 review of PR #85 found the "enforcing" pre-commit hook enforced
nothing. Vale's exit code keys on error-level alerts alone: five of the
six rules were level: warning, so they exited 0, and pre-commit hides
output from a passing hook — the alerts were invisible and blocked
nothing. ADR-0013 rejected a report-only trial tier and then shipped one
by accident.
Flatten every rule to level: error. Vale's own exit code is then correct,
so the hook entry drops to a bare vale-wrap.sh call and the graded
error->FAIL / warning->SUGGESTION mapping disappears from both audit
skills: every alert is a FAIL, in the gate and the audit alike. No
ignorable tier, matching shellcheck, the test suite and
conventional-pre-commit.
Delete Kyberforge.VagueQualifier. Measured against the 41 skill/agent
files as they stood before the rule ever ran: 2 hits. One marginal
("very different" -> "fundamentally different"), one an unfixable false
positive — caveman/SKILL.md quotes "of course" as an example of filler,
a mention not a use — which forced the only Vale suppression comments in
the repo. Those four lines go with it; two of them were dead anyway,
suppressing a frontmatter-scoped rule on a body line. Held-out prose (273
files) fired 15 times, 9 inside out-of-scope research examples and the
rest one word in two idioms in a single doc. SentenceOpenerThereIs
survives: 22 held-out hits, both in-corpus hits clean rewrites, zero
suppressions.
Widen .vale.ini's globs to [**/SKILL.md], [**/agents/*.md] and
[**/*.agent.md]. The plugins/*/-prefixed globs scoped nothing — Vale's *
crosses /, so they already matched docs/research/examples/**/agents/*.md
and assets/templates/SKILL.md, the two paths CONTEXT.md claimed they
excluded. Scoping is and was the hook's files: regex. The old globs also
hid a silent false negative: a skill outside plugins/ matched no section,
so Vale reported 0 files and exited 0, which both audits read as clean.
They now treat a 0-file run as NOT RUN and fall back to full judgment.
Also:
- vale-wrap.sh resolves relative --config values and file arguments
against the caller's cwd, as vale does, instead of the repo root, which
hard-errored from a subdirectory and silently skipped flattening for
file args that did not resolve from the root. Absolute paths inside the
cwd are relativized so reports cite resolvable paths, not scratch ones.
- vale-run's exit-code model was documented backwards ("exits non-zero
whenever it finds an alert at or above MinAlertLevel") and would have
led anyone following it to build a gate that passes everything. Its
Markdown suppression syntax was MDX-only and does not suppress in .md;
corrected in the skill and its troubleshooting reference, with
backtick/fence exemption documented as the first resort.
- skill-size-check.sh fails only above 500 lines, agreeing with
skill-audit's validate.sh <= 500 pass.
- ADR-0013 and CONTEXT.md amended to match, recording why graded
severities cannot gate.
Verified: 9 test scripts / 15 vale-wrap cases pass; vale-audit-prefilter,
skill-size-check and shellcheck pass --all-files; check-manifests and
claude plugin validate --strict clean. New tests fail against the old
script (3 of them) and pass against the new one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
plugins/lint/docs/research/docs/vale/ had no top-level index pointing
into it, unlike plugins/kyberforge/docs/README.md which indexes its
own research directories. Add plugins/lint/docs/README.md mirroring
that convention: one line per file describing what it covers, plus a
provenance note tying the directory back to plugins/lint/sources.md
and the vale-config/vale-run skills that consume it.
Closes out a follow-up item from PR #85's review.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Addresses PR #85's outstanding review items after grilling the open
questions against ADR-0013/CONTEXT.md/ADR-0010:
Blocking fixes:
- vale-wrap.sh: replace json.dumps() escaping (which silently defeated
Vale's frontmatter scope on any description containing a quote,
backslash, or non-ASCII char — ~58% of the corpus) with a single-quoted
YAML scalar, substituting a Unicode right single quote for embedded
apostrophes rather than '' doubling (Vale's frontmatter scanner isn't a
full YAML parser and silently truncates on '' too).
- vale-wrap.sh: fix a blank-line-inside-a-folded-description truncation
bug via indentation-based, blank-line-tolerant body capture; narrow
flattening to `>`-style scalars only (`|` already works unflattened).
- skill-audit/agent-audit Step 1: make the vale-wrap.sh invocation
cwd-independent via git rev-parse --show-toplevel, fixing a bug where
no single cwd satisfied all three Step 1 commands.
- styles/Kyberforge/VagueQualifier.yml: prune 17 tokens verified
false-positive-dominated on this repo's own voice via a real corpus
sweep (obvious, clearly, usually, several, simple, easy, completely,
simply, tiny, etc.), keep 13 with real or unattested noise. Revert the
28 prose "fixes" those tokens drove across 14 skill files back to their
original, correct wording, including a functional regression to
caveman/SKILL.md's own filler-word list (a mention, not a use) — now
guarded with vale-off comments against recurrence.
Gaps:
- --minAlertLevel=warning on the pre-commit hook and Step 1 invocation
so warning-level rules actually surface, without collapsing the
FAIL/SUGGESTION severity mapping skill-audit/agent-audit rely on.
- vale-wrap.sh: fix --config=<path> equals-form, absolute-path silent
no-op, and a zero-file-argument stdin hang.
- Route vale-run and lint-runner through a documented wrapper script
when a target repo has one, instead of unconditionally recommending
bare `vale`.
- Wire Kyberforge.VagueQualifier/SentenceOpenerThereIs into skill-audit/
agent-audit's dimension-mapping prose (Body discipline).
- Add plugins/lint/sources.md provenance for lint-runner (ADR-0010).
- Sync both marketplace.json lint-entry descriptions with plugin.json.
- Retune skill-size-check.sh's MAX_WORDS 5000->2900 (measured ~1.6-1.7
tokens/word on this repo's corpus, the old value gated at ~8,500
tokens against a stated 5,000 ceiling); fix the >/>= line-count
boundary and wc -l undercount on files with no trailing newline.
- Document the vale binary as a Setup prerequisite in AGENTS.md.
- Fix SentenceOpenerThereIs's dead regex alternative and add a real
sentence-start anchor/scope.
- Fix a stale docs/research/docs/vale/ index pointer in kyberforge's
docs README (moved to plugins/lint/ in e1a5403).
- Rewrite ADR-0013's Consequences section past-tense to describe what
actually landed, and record the styles-portability limitation
(repo-root placement stays intentional; deferred to a separate
session per this PR's review).
Test coverage: 9 new vale-wrap.sh fixtures (quotes, backslash/unicode,
blank-line paragraphs, --config= form, zero-arg/absolute-path handling,
literal-block no-regression) and boundary-pair tests for
skill-size-check.sh's line/word ceilings.
bash tests/run-tests.sh: 9 scripts + 125 bats assertions, all passing.
scripts/check-manifests.sh and claude plugin validate --strict: clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Deferred item from PR #85 review. Per ADR-0013: cherry-picks two low-noise
rules from trialing write-good/alex against the real corpus (VagueQualifier,
SentenceOpenerThereIs) into styles/Kyberforge rather than adopting either
package wholesale (both are tuned for blog prose and were noisy on this
repo's terse, imperative instruction files - see the ADR's rejected-rule
list). Adds a new skill-size-check pre-commit hook enforcing agentskills.io's
500-line/5,000-token SKILL.md ceiling, currently unenforced. Fixes the 28
resulting violations across 20 existing SKILL.md/agent files so the
enforcing pre-commit hook lands clean.
governance.md/CONTROLS.md were evaluated and excluded as rule sources -
they're org/CI-infrastructure controls, not prose patterns Vale can express.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QUDczvw1H3eEeMD29Q9Lbi
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.
Vale's text.frontmatter.description scope silently stops matching once
the description is a YAML block scalar spanning 2+ physical lines —
the style used by most skills/agents in this repo. scripts/vale-wrap.sh
flattens the description to one line in a scratch copy (preserving the
repo-relative path and total line count) before invoking real vale, and
both audit skills plus the pre-commit hook now call it instead of vale
directly. Also tightens the pre-commit hook's file glob to single path
segments so it can't cross into docs/research examples or asset
templates the way the audit skills' scoped invocations already avoid.
Addresses PR #85 review feedback.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
Adds vale-audit-prefilter as a local pre-commit hook scoped to skill/agent
markdown files, matching the invocation pattern skill-audit/agent-audit
already use. Runs at commit-stage only since it's a fast deterministic
prefilter; push-stage already covers the full test suite and manifest checks.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
Adds repo-root .vale.ini plus a custom Kyberforge style (description-opener,
vague-wording, and generic reference-pointer padding rules) and a
KyberforgeCopilot style scoped to .agent.md files (Use proactively check).
skill-audit and agent-audit Step 1 now run vale against the specific file(s)
being audited and defer the corresponding Description/Patterns/Body checks
to its output instead of re-deriving them by LLM judgment, per the split
proposed in issue #84.
Closes#84
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
Adds the lint plugin entry to both marketplace manifests and records
the resolved scope/structure decisions from grilling in CONTEXT.md:
standalone repo-agnostic plugin, split vale-config/vale-run skills,
report-only lint-runner agent, audit-pipeline wiring deferred.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
Merge duplicate gotcha in vale-config (Packages vs BasedOnStyles was
stated twice) and align vale-run's category field with vale-config's
(lint, not linting) so sibling skills in the plugin agree.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
Report-only agent that composes vale-config/vale-run to run a lint
sweep over a scope and return normalized findings — no Edit tool, it
flags issues rather than fixing them. Also lands the plugin manifest
scaffold (plugin.json, .claude-plugin/plugin.json) that the earlier
vale-config/vale-run skill commits assumed but didn't carry, bumped
to 1.1.0 for the new agent.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
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.
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
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.
plugins/bin loses a whole skill (gitea removed) — minor bump (1.0.5 ->
1.1.0) to reflect the capability-surface change. plugins/gitea gains a
reference file and a README fix, no new capability — patch bump
(1.3.1 -> 1.3.2).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The deep-module split in plugins/gitea/ (ADR 0011) already covers every
domain the old plugins/bin/skills/gitea/ flat skill handled. Move its
token-access.md into plugins/gitea/references/ first, since it held
empirical scope-test results (Actions/CI, Wiki, Notifications, Packages,
User/Org) not reproduced anywhere in the new plugin, then drop the old
skill and fix a stale cross-reference pointing at it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.
PR review feedback: Step 3 gave no concrete guidance on what good
AGENTS.md content looks like, and the skill had no substantive
references file (only provenance bookkeeping in sources.md), unlike
sibling kyberforge skills. Adds section-by-section content guidance,
the worked example, and monorepo precedence rules synthesized from
the agentsmd research corpus.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
core gained three skills for the first time (agentsmd-author,
agentsmd-audit, provider-adapter-author). Minor bump reflects new
capability rather than a fix. Also declares the missing `skills`
path in the Copilot manifest so Copilot CLI discovers them
(CC auto-discovers from the plugin root; Copilot requires explicit
declaration per ADR-0016 convention).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.
Converts a target repo's provider-specific instruction file (CLAUDE.md,
.cursor/rules, copilot-instructions.md, etc.) into a thin adapter over
AGENTS.md, mirroring this repo's own two-tier CLAUDE.md pattern
(ADR-0002/0003). Self-validates via a bundled deterministic script
(scripts/validate-adapter.sh) rather than a separate paired audit skill.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.
The previous commit only landed the research-folder rename — a multi-path
git add silently failed and left CONTEXT.md, ADR-0012, and the actual skill
files unstaged. This lands them: the agentsmd-audit skill itself (three
deterministic validators for secrets, structure, and drift against a target
repo's AGENTS.md), its bats test suite, provenance record, and the
CONTEXT.md/ADR entries documenting why this lives in core rather than
kyberforge.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Audits a target repo's AGENTS.md file(s) for embedded secrets, structural
completeness against the agents.md common-sections checklist, and drift
(referenced commands/paths that no longer resolve). First active skill in
the core plugin — kyberforge is scoped to marketplace-factory meta-tooling,
not generic target-repo documentation (see ADR-0012). Moves the agentsmd
research corpus from plugins/kyberforge to plugins/core to match.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Adds a bullet to the Subagent orchestration section in AGENTS.md so
coordinators treat merged-PR cleanup as one atomic step: verify the
merge, force-remove the worktree (double -f, since this repo's test
runs initialize submodules), and delete both the feature branch and
any Agent-tool-generated worktree-agent-<id> isolation branch.
Fixes#75
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
skill-author and agent-author SKILL.md files received bug fixes (git-log
commit-hash verification before reporting completion, skill-author now
forbids self-spawning audit/recheck subagents during its authoring pass,
and agent-author closed checklist/coverage gaps). Patch bump to reflect
fixed behavior, not new capability.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
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
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.
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
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
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
Adds a Subagent orchestration section to AGENTS.md so orchestrating
agents know upfront: forks must stop once their assigned task is done
rather than autonomously draining a shared TaskList, governance-gated
actions must not be exposed to forks without a fresh confirmation
round, and TaskGet/TaskUpdate/TaskList are fork-only so the coordinator
must own task-list bookkeeping for fresh subagents itself.
Refs #68, #70
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
