holocron/docs/spec/architecture.md

Architecture

Current deployed architecture. Updated in the same PR as any structural change.

Layered model

this repo (global defaults)
    ├── install.sh → ~/.agents/skills/  (canonical skills location)
    ├── install.sh → ~/.claude/skills/  (symlink → ~/.agents/skills/, Claude Code adapter)
    └── install.sh → ~/.claude/         (Claude Code config + content)

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

Projects consume from this repo by pulling updates via sync.sh (Chunk 6). Until then, install is a one-time manual step.

Directory structure

ai-development/
├── AGENTS.md                    # Provider-agnostic always-on rules for this repo; imported by repo CLAUDE.md
├── CONTEXT.md                   # Domain language, principles, glossary; auto-loaded at session start
├── docs/                        # Workflow artifacts and issues (prd/, ard/, bug/, notes/, adr/, issues/, spec/) + research/ (raw research audit trail)
├── .agents/                     # Agent Skills standard location (provider-agnostic)
│   └── skills/                  # SKILL.md files — canonical source, deployed to ~/.agents/skills/
├── core/                        # Provider-agnostic source of truth
│   ├── AGENTS.md                # Global always-on rules (Communication + Behavior); deployed to ~/.agents/AGENTS.md
│   ├── instructions/            # AI behavior definitions (plain markdown)
│   ├── agents/                  # Agent role definitions
│   ├── workflows/               # Workflow definitions
│   └── prompts/                 # Reusable prompt templates
├── providers/                   # Provider-specific adapters
│   ├── claude-code/             # CLAUDE.md (thin adapter), settings.json, provider-manifest.sh
│   └── copilot/                 # copilot-instructions.md, hooks, agents adapter
├── templates/                   # Project scaffolding templates
└── scripts/
    ├── deploy-manifest.sh       # Source→target mappings; sourced by install.sh and sync.sh
    ├── install.sh               # Deploys to ~/.agents/skills/, ~/.claude/, etc.
    ├── sync.sh                  # Pulls updates into an existing project
    └── init-project.sh          # Bootstraps a new or existing project

Content deployment model

install.sh is a deployer, not a composer. It does not concatenate content into a single file. Instead:

• .agents/skills/ → ~/.agents/skills/ — canonical skills location; each skill dir is replaced individually (parent not wiped, user-added skills preserved)
• core/AGENTS.md → ~/.agents/AGENTS.md — global always-on rules (Communication + Behavior); imported by ~/.claude/CLAUDE.md via @~/.agents/AGENTS.md
• Provider adapters declared in providers/*/provider-manifest.sh — symlinks from the provider's skill path to ~/.agents/skills/; e.g. Claude Code gets ~/.claude/skills/ → ~/.agents/skills/ because it reads ~/.claude/skills/ natively. Providers that read ~/.agents/skills/ directly need no adapter.
• core/ → ~/.claude/core/ — workflows, prompts, agent definitions; agent reads on demand
• providers/claude-code/settings.json → ~/.claude/settings.json
• providers/claude-code/CLAUDE.md → ~/.claude/CLAUDE.md — thin adapter: imports ~/.agents/AGENTS.md and governance.md; no original content

~/.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.

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/HUMANS.md as human-facing reference; CONTEXT.md extended with governance domain language.
• Phase 2 (Chunk 6): 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-0012):

• Repo-level AGENTS.md — instructions for agents working inside this repo (structure, key rules, chunk workflow). 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.

Skills are the strongest shared primitive — the SKILL.md format and Agent Skills open standard are cross-provider. Providers that don't read ~/.agents/skills/ natively declare a symlink adapter in providers/<name>/provider-manifest.sh; install.sh discovers and wires these up automatically.

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.