holocron/docs/spec/architecture.md

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 — in this repo by apm install against the dependencies.apm entries in the root apm.yml, which lands them in .claude/skills/ and .claude/agents/ (ADR-0018); elsewhere by 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) and carries nothing else — the content index of on-demand instruction files sits in core/AGENTS.md, deployed to ~/.agents/AGENTS.md and imported by it. 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 apm install here, or claude plugin install <name>@holocron for a host consuming the marketplace natively (ADR-0018). Self-contained is a hard constraint, not a description: a plugin is copied to a cache on install, so nothing inside it may reference a file outside its own directory. That is why the Vale styles are duplicated across two skills rather than shared (ADR-0014), and why ADR-0020's constants are copied into three validators rather than sourced from one. 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.

Which plugin a new skill belongs in follows from what each one is scoped to. The boundary that matters most in practice is core vs kyberforge: core is the home for cross-cutting, repo-agnostic utility skills that a consumer would want against their repo, while kyberforge is meta-tooling for the holocron marketplace itself. A skill that authors a target repo's AGENTS.md is core; a skill that audits a SKILL.md against this marketplace's contract is kyberforge.

The second boundary worth stating is git vs gitea, because both own things called branches and both touch pull requests: git is whatever works over the git wire protocol against a local clone, gitea is whatever goes through the forge's HTTP API. That is why git-branches and gitea-branches both exist and are not duplicates.

These are routing boundaries, not inventories — they answer "where does a new skill go", so they deliberately do not enumerate what each plugin ships today. The plugin's published description in its apm.yml states the same boundary for a consumer deciding whether to install (ADR-0021); neither carries an inventory. For what a plugin ships today, read plugins/<name>/.apm/skills/ or the plugin list in README.md.

Plugin	Scope
core	Authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it
git	Git operations and git hook tooling — anything driven over the git wire protocol against a local clone, plus the pre-commit hooks that guard it
gitea	Anything reached through the Gitea HTTP API rather than the git wire protocol — the forge's own objects
kyberforge	Creating and maintaining a Claude Code / Copilot CLI plugin marketplace — this repo's own meta-tooling
lint	Configuring and running linters against a target repo; repo-agnostic, first linter is Vale
bin	Unsorted skills that have not earned a home yet

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, .mcp.json, and per-plugin extras such as plugins/git/config.example.json, plugins/gitea/references/ and plugins/bin/evals/ — lives at the plugin root and is untouched by either compiler.

.mcp.json is the one entry in that list that is still load-bearing for apm rather than merely ignored by it. MCP is a first-class apm primitive — dependencies.mcp sits beside dependencies.apm in the manifest schema, and apm tracks deployed servers in apm.lock.yaml under mcp_servers, mcp_configs and mcp_config_provenance. A plugin reaches that primitive indirectly. apm pack writes the string ".mcp.json" into the generated .github/plugin/plugin.json as its mcpServers value, and on install apm resolves the plugin manifest in the order plugin.json, .github/plugin/plugin.json, .claude-plugin/plugin.json — so the Copilot manifest wins, the pointer is followed, and .mcp.json is injected into the package's dependencies.mcp with any ${VAR} env references intact. Verified against the real remote: a git-sourced install of plugins/gitea deploys the gitea server with both env references unexpanded.

Two consequences follow, and both have bitten already:

• Do not declare dependencies.mcp in a plugin's own apm.yml. It is the schema-correct place and it breaks the build. The apm-audit-ci pre-push hook runs apm audit --ci inside every plugins/*/, so a declared dependency arms lockfile-exists there, which then demands an apm.lock.yaml in the package plus every file of that package's own deployed tree present inside the package directory. Measured on plugins/gitea: 93 missing deployed files and 79 drifted paths.
• .claude-plugin/plugin.json carries an env-stripped copy. apm pack inlines .mcp.json there, and its sanitiser drops env and headers blocks unconditionally at any depth, ${VAR} indirection included. That copy is inert under apm, which never reaches it, but a native Claude Code plugin install reads exactly that file and would launch the server with no credentials. Anything installed natively rather than through apm needs its MCP env supplied by the host.

That immunity is positional, not by filename. Anything placed inside a mirrored directory is destroyed regardless of what it is: sync_dir runs rm -rf "$dst" before every copy, and sync_hooks_json does the same to hooks/. A hand-written README.md under plugins/<name>/hooks/ or plugins/<name>/skills/ is deleted by the next sync with no drift report, because a file with no .apm/ counterpart is simply absent from the regenerated tree. This has already cost the repo one document — plugins/kyberforge/hooks/README.md, since restored to plugins/kyberforge/docs/hooks.md. Plugin-root documentation belongs in docs/.

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.

Those on-demand files are plain markdown — no frontmatter, no schema. The agent decides when to read each one from task context and the content index label alone. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice; it is a deliberate deferral, not an oversight to close.

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 nothing else; there is no @CONTEXT.md import. It is not import-only either: below the import sits a fenced <!-- rtk-instructions v2 --> … <!-- /rtk-instructions --> block carrying the RTK command-prefix convention, which is tool-specific content with no AGENTS.md source. This is distinct from providers/claude-code/CLAUDE.md, which is the global config deployed to ~/.claude/.

CONTEXT.md is therefore not always-loaded. AGENTS.md instructs agents to read it at session start, which is a behavioural instruction, not an @import guarantee — LESSONS.md's 2026-05-17 entry proposed adding the import and it was never applied. Treat that entry as open work rather than a record of a landed change.

Reference conventions

The stated convention is that files referencing other files declare those references explicitly: the referencing file carries the forward reference (the content index in core/AGENTS.md, references: in frontmatter), the referenced file carries a when: field describing when it is loaded, and divergence between the two signals staleness. It is aspirational, not a description of the repo today — no file under core/instructions/ carries frontmatter at all, when: appears in exactly one of the 39 SKILL.md sources under plugins/*/.apm/skills/, and the reference scanner script meant to derive the reverse map ("what files reference this file?") does not exist; docs/notes/skill-implementation-workflow.md still lists it as unbuilt work. Treat it as intent for instruction files, skills, and workflow documents, not as a rule the repo enforces.

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/. There is no index file — the directory holds numbered ADRs whose filenames state their decision, so ls docs/adr/ is the index. Read a superseding ADR before the one it supersedes: ADR-0015 (apm as the authoring source of truth) supersedes ADR-0001 and moots ADR-0006, ADR-0017 corrects ADR-0015's host-discovery gap, and ADR-0019 supersedes one claim in ADR-0018 (that .claude/settings.json's committed content is exactly {"hooks": {}}) while keeping the rule behind it. Entry points for the structure described on this page: ADR-0002 (two-tier CLAUDE.md), ADR-0003 (AGENTS.md as the provider-agnostic entry point), ADR-0015 and ADR-0017 (the two compilers behind the plugin roots).