Files

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

3.6 KiB

Raw Blame History

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. 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/spec/architecture.md — current directory structure, install pipeline, provider model
docs/adr/ — architectural decisions; read before answering design questions or proposing structural changes
docs/ai-constitution.md — full governance evidence base; read when a governance decision needs justification
docs/research/ai-coding-factory/ai-coding-factory-principles.md — factory design rationale; read when implementing, auditing, or reviewing skills or factory structure
docs/notes/factory-integration-decisions.md — decisions from the factory integration grill; read when making skill authoring or factory design decisions
Governance rules are always in effect — core/instructions/governance.md (agent rules); docs/research/governance_principles/CONTROLS.md