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

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, and docs/VISION.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-0003.

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; forge calls grill-with-docs to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching *-author skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (skill-author runs /skill-audit, agent-author runs kyberforge:agent-audit, both in the same context as the authoring work). forge additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, forge loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. plugin-author and marketplace-author have no audit counterpart and get no recheck; their terminal check is claude plugin validate.

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.

agentsmd-author / agentsmd-audit

A skill pair in the core plugin for writing, updating, and reviewing a target repo's AGENTS.md file(s) (the generic open-standard file — see the AGENTS.md entry above — not this repo's own). agentsmd-author creates/updates AGENTS.md content, supports nested monorepo placement (per the standard's nearest-file-wins precedence), and closes out by invoking agentsmd-audit inline. agentsmd-audit runs a single combined pass checking three mandatory baselines: secrets/credentials (governance.md hard prohibition — AGENTS.md is committed content), structural completeness (common-sections checklist from the agents.md spec), and accuracy/drift (do referenced commands and paths actually resolve against the repo). agentsmd-audit never inspects provider adapter files (see provider-adapter-author) — its scope is AGENTS.md content only. Chosen over folding this into kyberforge because kyberforge's scope is meta-tooling for the holocron marketplace itself, not generic target-repo documentation; core is the intended home for cross-cutting, repo-agnostic utility skills.

provider-adapter-author

A companion skill (core plugin) that detects a target repo's provider-specific instruction file (CLAUDE.md, .cursor/rules/*.mdc, copilot-instructions.md, etc.) and, where it duplicates content AGENTS.md should own, converts it into a thin adapter that imports AGENTS.md — mirroring this repo's own ADR-0002/ADR-0003 two-tier adapter pattern. Self-validates via its own bundled deterministic script (scripts/validate-adapter.sh: checks for an import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — the check is mechanical, so a script suffices per governance.md's "prefer deterministic code for repeatable tasks." agentsmd-author calls this skill via skill composition when it detects an existing provider file with overlapping content.

lint plugin

A standalone, repo-agnostic plugin (plugins/lint/) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: vale-config (setup — .vale.ini, StylesPath, styles) and vale-run (invoke Vale, interpret/report findings). A lint-runner agent composes these for isolated-context lint sweeps; it is report-only (no Edit tool) — it flags findings, it does not rewrite prose. Vale's research docs (docs/research/docs/vale/) moved from plugins/kyberforge/ to plugins/lint/ to keep the provenance chain same-plugin.

Vale audit prefilter (skill-audit / agent-audit)

Wiring Vale as a deterministic prefilter for skill-audit/agent-audit's Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic lint plugin, so its config lives at the repo root rather than inside plugins/lint/: .vale.ini plus a custom Kyberforge style (styles/Kyberforge/) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a KyberforgeCopilot style (styles/KyberforgeCopilot/) scoped only to .agent.md files for the Copilot-only "Use proactively has no effect" check. error alerts map to FAIL, warning/suggestion map to SUGGESTION. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, Use proactively, generic reference-pointer padding) plus, per ADR-0013, two body-wide prose-pattern checks (vague-qualifier filler, "There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.

Both skills' Step 1, and the vale-audit-prefilter pre-commit hook, call scripts/vale-wrap.sh rather than vale directly — a workaround for a confirmed Vale 3.15.2 limitation (see vale-config's Gotchas): text.frontmatter.description silently stops matching once the description is a YAML block scalar (>/|) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real vale; single-line descriptions pass through untouched. tests/test-vale-wrap.sh regression-tests this. Both call sites still scope every invocation to the specific file(s) being audited, never a repo-wide sweep — Vale's glob matching crosses directory boundaries (plugins/*/agents/*.md matches nested docs/research/examples/**/agents/*.md too), so scoping is what keeps research-example files out of the audit's lint pass. The pre-commit hook's own glob is tightened to ^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$ (single-segment, not .*) for the same reason, since pre-commit invokes it automatically against whatever staged files match rather than a manually-scoped target.

This scope expands per ADR-0013: cherry-picked low-noise write-good/alex rules landed in styles/Kyberforge as two new rule files, Kyberforge.VagueQualifier and Kyberforge.SentenceOpenerThereIs, plus a new sibling pre-commit hook, skill-size-check (scripts/skill-size-check.sh), enforcing agentskills.io's 500-line/5,000-token SKILL.md ceiling — scoped to ^plugins/[^/]+/skills/[^/]+/SKILL\.md$ only, same as vale-audit-prefilter, so it never lints docs/research/examples/ reference skills. File scope (SKILL.md + agent files) and enforcement model (rules land directly in styles/Kyberforge, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine).

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.