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

5.6 KiB

Raw Blame History

Architecture

Layered model

this repo (global defaults)
    └── scripts/install.sh → ~/.claude/         (Claude Code config + content)

project repo (local overrides)
    └── .claude/settings.json, CLAUDE.md (overrides global)

Content deployment model

scripts/install.sh is a deployer, not a composer. It sources scripts/deploy-manifest.sh and deploys three categories:

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/, installed independently via claude plugin install <name>@holocron. Each plugin is an apm package: plugins/<name>/apm.yml plus a hand-authored plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/ tree (ADR-0015). There is no hand-maintained plugin.json — every manifest and every host-visible content directory is compiled from that source.

Two compilers produce the plugin roots you see in the tree:

apm pack compiles the manifests (ADR-0015). Per plugin: .claude-plugin/plugin.json and .github/plugin/plugin.json, both generated from plugins/<name>/apm.yml. Repo-wide, from the root apm.yml's marketplace: block: .claude-plugin/marketplace.json (apm's claude output profile) and .agents/plugins/marketplace.json (its codex profile, a differently-shaped file). Those two are the only marketplace outputs apm has profiles for — the third root manifest, .github/plugin/marketplace.json (Copilot CLI's legacy path), is a byte-identical mirror of the Claude one maintained by scripts/sync-marketplace-mirror.sh and gated by the check-marketplace-mirror-sync pre-push hook.
scripts/sync-plugin-content.sh compiles the content mirror (ADR-0017). It wraps apm pack --format plugin and copies the resulting bundle's flat agents/, skills/, commands/, instructions/, extensions/, and merged hooks/hooks.json back to the plugin root. Claude Code's installer convention-scans those flat paths and has no .apm/ awareness whatsoever, so the mirror exists solely to satisfy the host's discovery contract.

.apm/ is the sole hand-edited authoring source for plugin content. An edit made in the flat mirror is discarded by the next sync and is reported as drift by the check-plugin-content-sync pre-push hook. Hand-authored material that is not an .apm/ primitive — README.md, docs/, bin/, sources.md, and .mcp.json — lives at the plugin root and is untouched by either compiler.

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/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-0003):

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.

This repo also has a CLAUDE.md at its root — the Claude Code entry point for working in this repo. It imports AGENTS.md and CONTEXT.md, nothing more. This is distinct from providers/claude-code/CLAUDE.md, which is the global config deployed to ~/.claude/.

Provider model

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.

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.

5.6 KiB Raw Blame History