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
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.
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.
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
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
## 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
## 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 <noreply@anthropic.com>
## Why
The WARNING admonition blocks in CLAUDE.md and providers/claude-code/CLAUDE.md
added noise without adding clarity — the file paths already communicate which
config is which. The "Key rules" block in AGENTS.md duplicated guidance already
present in the content index above it.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
Structure section listed .claude-plugin/, docs/, scripts/, tests/ —
all either obvious or carrying stale annotations (Chunk 6, sync.sh).
HUMANS.md path updated to docs/wiki/ after the wiki move. sync.sh
key rule removed since the script doesn't exist yet.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Skills and evals migrated from .agents/ to plugins/bin/ plugin directory.
Remove .mcp.json, provider-manifest.sh, and skills-lock.json legacy artifacts.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds plugins/, .agents/evals/, and .claude-plugin/ to the structure
section. Clarifies that .agents/skills/ contains directly-deployed skills
only; marketplace and factory skills now live in plugins/kyberforge/.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- AGENTS.md: add factory principles and factory-integration-decisions to
on-demand content index so they are discoverable for skill design work
- write-skill: insert conflict-check step (step 3) — sub-agent reads
constitution and factory principles after grill, before any writing;
hard gate with explicit self-check item; renumber steps 3–8 → 4–9
- META.md: bump to v1.4
Closes the gap identified in PRD chunk-3-skills-library §sub-agent-usage:
conflict checking against constitution and factory principles was specified
but never wired into the write-skill process.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Create AGENTS.md at repo root and core/AGENTS.md as provider-agnostic
sources of always-on rules. Slim both CLAUDE.md files to thin adapters.
Deploy core/AGENTS.md → ~/.agents/AGENTS.md via deploy-manifest.sh.
Update three test suites to check correct locations post-refactor.
All automated tests pass (57 instructions, 106 install, 25 governance).
HITL behavioral test plan in test-instructions-and-docs.sh scenarios 9–12.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
