holocron/CONTEXT.md

name, description

name	description
AI Development Repo	Domain language and decisions for the global AI development config repository

Context

Principles

CLAUDE.md index model

AGENTS.md is the source of always-on universal rules (provider-agnostic). providers/claude-code/CLAUDE.md is a thin adapter: it imports ~/.agents/AGENTS.md via @~/.agents/AGENTS.md and appends Claude Code-specific additions (@import for governance.md, content index). Deployed to ~/.claude/CLAUDE.md via install.sh. Context size is kept minimal — only what is needed every session is loaded upfront; detailed content is pulled on demand. See ADR-0012.

Instruction file format

core/instructions/<topic>.md files are plain markdown — no frontmatter, no schema. The agent decides when to read each file based on task context and the content index label in providers/claude-code/CLAUDE.md. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice.

Repo/gitea as source of truth

All project state, decisions, context, and working conventions live in this repo or Gitea. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read CLAUDE.md, CONTEXT.md, docs/VISION.md, and docs/spec/overview.md. Everything needed to orient is here.

Before answering any design or architecture question, check for existing decisions: docs/adr/ (hard architectural decisions).

Glossary

Management Application

A separate product (separate repo) for browsing, editing, and configuring AI development configs through a proper product UI. Git is the persistence layer, invisible to the user. The app is repo-agnostic — it works with any git repo that follows these conventions. This repo is the canonical default content (the official starter). See docs/VISION.md for the phased roadmap.

Skills

Reusable slash commands for AI coding tools, defined as SKILL.md files following the Agent Skills open standard. Deployed via plugin — plugins/<plugin-name>/skills/<skill-name>/SKILL.md, available after the plugin is installed (claude plugin install <name>@<marketplace>). Skills are self-contained — they cannot reference files outside the plugin directory after install-time caching.

Plugin

The deployable unit in the plugin marketplace. A plugin bundles one or more skills, agents, hooks, prompts, MCP servers, and optionally a bin/ directory into a single installable directory. Each plugin has two manifests: .claude-plugin/plugin.json (Claude Code) and plugin.json at the plugin root (Copilot CLI). Plugins are copied to a cache on install — they cannot reference files outside their own directory. In this repo, plugins live under plugins/<name>/. Install a plugin with claude plugin install <name>@<marketplace>.

Plugin marketplace

A Git repository with a marketplace.json manifest listing installable plugins. No backend, registry, or SaaS required — the Git repo is the marketplace. This repo is the holocron marketplace. The manifest lives at .claude-plugin/marketplace.json (read by both Claude Code and Copilot CLI) and is mirrored to .github/plugin/marketplace.json.

HITL (human-in-the-loop)

Agent pauses before a consequential action; human approves before execution. Required for irreversible or high-stakes actions (architecture changes, production deployments, security configuration). The agent drafts the change plan and waits — it does not proceed autonomously. Contrast with HOTL.

HOTL (human-on-the-loop)

Agent acts; human monitors and can intervene after the fact. Acceptable for low-stakes, bounded, reversible actions where the cost of pausing for approval exceeds the blast radius of an error. The distinction between HITL and HOTL must be explicit and documented — defaulting to HOTL for convenience is not acceptable.

Sycophancy

The failure mode where RLHF-trained models prioritise approval over accuracy. Treated as a first-class reliability risk: models change correct answers to wrong ones under user pressure in a majority of observed cases, then persist in the wrong answer. Designing against sycophancy is an explicit obligation, not a quality-of-life concern. Countermeasures: explicit pushback resistance instructions, prompting for dissent, cross-validating against independent sources. Never interpret AI agreement as AI accuracy.

AGENTS.md

The provider-agnostic always-on instruction entry point. Two files:

• 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.

Contains always-on rules in plain markdown with no provider-specific syntax (no @import). Provider-specific files (CLAUDE.md) are thin adapters that import the relevant AGENTS.md and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0012.

Skill composition

A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: grill-me calls write-adr when a decision crystallises; implement-feature calls tdd as its implementation methodology.

Provider-agnostic issue tracker

Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0017). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it).

Provenance chain

The three-stage traceability record linking a skill back to its research inputs: (1) /research produces topic docs and a sources.md in plugins/<plugin>/docs/research/docs/<topic>/; (2) /skill-author reads those docs and records which sources informed which skill files in references/sources.md (including a Research doc: back-pointer to the upstream research file) and source_keys frontmatter on SKILL.md and references/*.md; (3) skill-audit validates the chain is complete and internally consistent via validate-provenance.sh. A skill with research input but no references/sources.md, or with source_keys that don't match references/sources.md slugs, has a broken provenance chain.

Bidirectional reference principle

Files that reference other files should declare those references explicitly. The referencing file carries the forward reference (e.g. content index in CLAUDE.md, references: in frontmatter). The referenced file carries a when: field describing when it is loaded. Both sides should agree — divergence signals staleness. The reverse map ("what files reference this file?") is derived by a reference scanner script, not maintained manually. This principle applies to instruction files, skills, and workflow documents.

LESSONS.md

Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.