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). A consuming repo installs them the same way — apm is the only supported install path.

~/.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 and in any consuming repo (ADR-0018). Each unit 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 per-plugin plugin.json at all — apm reads apm.yml, and the repo's one generated manifest, .claude-plugin/marketplace.json, is compiled from that source.

Self-contained is a hard constraint, not a description: a file reference inside .apm/skills/<name>/ may not reach outside that skill's own directory, and there is no cross-skill sharing mechanism to reach for instead. That is why the Vale styles ship inside the one skill that uses them, factory-audit/assets/vale/ (ADR-0014, ADR-0025), and why ADR-0020's constants are copied into two validators — the plugin's validate.sh and the repo's scripts/skill-size-check.sh — rather than sourced from one. The constraint used to be explained by Claude Code's plugin cache-install copying a plugin to a cache; that is no longer the reason and never was the only one. It is stated independently for APM package mode by the agentskills.io spec (plugins/kyberforge/.apm/skills/skill-author/references/deployment-modes.md), which is why ADR-0024 consequence 6 pins it as a negative result: ending native install did not relax it, and it is not to be re-litigated on the assumption that it did.

Which apm package 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

One compiler produces the generated content in the tree:

• apm pack compiles the marketplace manifest (ADR-0015). Repo-wide, from the root apm.yml's marketplace: block: .claude-plugin/marketplace.json (apm's claude output profile) — the only manifest this repo generates or ships. Copilot CLI checks for a marketplace manifest at several conventional paths, falling back through .github/plugin/marketplace.json to .claude-plugin/marketplace.json — since this repo already generates the latter, no dedicated Copilot-path mirror is maintained.

apm is the only supported install path. A flat skills/, agents/, hooks/ mirror used to be compiled to each plugin root so Claude Code's installer could convention-scan it, alongside a per-plugin .claude-plugin/plugin.json and .github/plugin/plugin.json; both are gone, together with native claude plugin install support. apm reads plugins/<name>/apm.yml and deploys from .apm/ directly, and never probed those manifests.

.apm/ is the sole hand-edited authoring source for plugin content. Hand-authored material that is not an .apm/ primitive — README.md, docs/, bin/, sources.md, and per-plugin extras such as plugins/gitea/references/ and plugins/bin/evals/ — lives at the plugin root. A hand-edit to the generated .claude-plugin/marketplace.json is reported as drift by the apm-pack-check-clean pre-push hook.

Plugin-root documentation belongs in docs/. That convention is older than the mirror's removal: a hand-written README.md placed inside a mirrored directory used to be destroyed by the next sync with no drift report, which cost the repo one document — plugins/kyberforge/hooks/README.md, since restored to plugins/kyberforge/docs/hooks.md.

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; core/ai-constitution.md and docs/wiki/HUMANS.md as human-facing reference; CONTEXT.md glossing the one governance term used unglossed elsewhere (HITL); the rest of the governance vocabulary is defined in core/ai-constitution.md.
• 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 38 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).