Files

Defame1297 013b913bd4 docs: correct claims the apm conversion left false

Documentation asserted things the code no longer did, which is how several of this
round's defects survived three review passes.

- `docs/spec/architecture.md` still described the pre-APM model — "each plugin has a
  `plugin.json` manifest" — when no such file exists. AGENTS.md routes agents here
  for the current structure, so it was live drift, not archive. Also cited ADR-0012
  where ADR-0003 is meant.
- AGENTS.md never said `.apm/` is the sole hand-edited source, while the generated
  mirror is byte-identical with no marker — an agent reading only AGENTS.md would
  edit the mirror and find out at pre-push. It also omitted that `apm` and `jq` are
  now required to push, unlike the `vale` bullet that exists for exactly that reason,
  and understated the pre-push gate. `apm marketplace check` hard-fails offline and
  `--offline` does not help, so the `SKIP=` escape hatch is documented rather than
  new machinery built.
- ADR-0017 carried hardcoded line numbers that drifted twice within one PR, and said
  `mcpServers` reinjection was real-syncs-only where the script's own header says
  both modes. Line numbers dropped rather than corrected.
- ADR-0015 asserted issue #90 was closed. It is open. Reworded to defer to the
  issue's own state rather than depend on someone remembering to close it.
- ADR-0014 said both audit skills pass `--config`; both SKILL.md files say pass none,
  and passing one fails with E100. The ADR was wrong.
- ADR-0007 cross-referenced an archived ADR-0011 whose number was later reused.
  Disambiguated with a note — renumbering a published ADR rewrites an immutable
  record and breaks every existing citation.
- CONTEXT.md claimed `lint-runner` is report-only via a missing `Edit` tool.
  Plugin-scope APM agents cannot express `tools:` (ADR-0016), so it is report-only by
  instruction now; ADR-0016 accepted that regression but CONTEXT.md was not updated.
- Recorded two undocumented consequences of the conversion: `displayName` dropped
  from all six compiled manifests and `owner.email` from the marketplace, and
  `mattpocock-skills` silently version-pinned and manually maintained.
- Wrote the version-bump policy issue #90 specified but never delivered. Its previous
  carrier, `marketplace-author`, was deleted in this PR, leaving the per-package rule
  documented nowhere.
- README fixes: kyberforge listed skills belonging to the `git` plugin and a deleted
  hooks path, `bin` advertised an agents directory it never had, and the docs index
  listed files that do not exist.

Refs: #90

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT

2026-08-14 01:53:26 +00:00

7.2 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 an apm package (apm.yml + .apm/) carrying skills, agents, hooks, MCP servers, and bundled assets; install separately via claude plugin install <name>@holocron
providers/claude-code/ — Claude Code adapter (deployed to ~/.claude/ via install.sh)

Edit `.apm/`, never the flat mirror

Inside a plugin, plugins/<name>/.apm/ is the only hand-edited content source. Everything else in a plugin root is generated:

scripts/sync-plugin-content.sh generates the flat plugins/<name>/{skills,agents,commands,instructions,extensions}/ directories and the merged plugins/<name>/hooks/hooks.json (ADR-0017)
apm pack generates both per-plugin manifests — plugins/<name>/.claude-plugin/plugin.json and plugins/<name>/.github/plugin/plugin.json — and two of the three root marketplace manifests: .claude-plugin/marketplace.json (apm's claude output profile) and .agents/plugins/marketplace.json (its codex profile, a differently-shaped file) (ADR-0015)
scripts/sync-marketplace-mirror.sh generates the third, .github/plugin/marketplace.json — Copilot CLI's legacy manifest path. No apm output profile targets it: apm ships exactly two marketplace output profiles, claude and codex (documented in plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md). The mirror is a byte-identical copy of .claude-plugin/marketplace.json, gated by the check-marketplace-mirror-sync pre-push hook. Do not expect apm pack to refresh it — that assumption is exactly the drift this pair exists to prevent

Nothing labels a generated file as generated — plugins/kyberforge/skills/forge/SKILL.md is byte-identical to its .apm/ original, with no marker in either. Check the path before you edit. An edit to the mirror is discarded by the next sync and is reported as drift by the check-plugin-content-sync pre-push hook, which is the earliest anyone finds out. Details in docs/spec/architecture.md.

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 (the 12-hook gate described below).
Install the apm CLI — four pre-push hooks shell out to it: apm-marketplace-check, apm-audit-ci, apm-pack-check-clean, and check-plugin-content-sync (via scripts/sync-plugin-content.sh, which wraps apm pack). The first three are bare apm … hook entries, so without it the push dies with an unhelpful "command not found". Use kyberforge:apm-install, or curl -sSL https://aka.ms/apm-unix | sh; verify with apm --version.
Install jq — required by scripts/check-manifests.sh and scripts/sync-plugin-content.sh, both pre-push. These at least fail loudly (Error: jq is required but not installed).
Install the vale binary — required by the vale-audit-prefilter-skill/-agent pre-commit hooks. Their files: patterns are .apm/-scoped: ^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$ and ^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$. Only the authoring source triggers them — a SKILL.md in the generated mirror matches neither pattern, so prose findings surface only when you edit the file you are supposed to be editing. Without the binary 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/.apm/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 runs 12 pre-push hooks, not just the test suite — run-tests and check-manifests, plus generated-content drift gates (check-plugin-content-sync, check-marketplace-mirror-sync, check-vale-style-sync, check-scope-walkup-sync), apm's own gates (apm-marketplace-check, apm-audit-ci, apm-pack-check-clean), host validators (validate-plugins, validate-marketplace, both needing the claude CLI), and check-release-needed. Run pre-commit run --hook-stage pre-push --all-files locally — one command, the whole gate.
apm-marketplace-check needs the network. It resolves every marketplace.packages[] entry including the remote mattpocock-skills ref, and it is always_run, so an unreachable network hard-fails the push. --offline is not an escape hatch — it still exits 1 on that entry (No cached refs (offline)). To push without a network, skip that one hook using pre-commit's own mechanism: SKIP=apm-marketplace-check git push. Skip that hook alone — it is the only one whose failure mode is "no network". Every other pre-push hook is a real local check, and adding it to SKIP disarms it silently.
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

7.2 KiB Raw Blame History