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). Reserve forge for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (skill-author, plugin-author, agentsmd-author, etc.); routing a known fix through forge's grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. 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 repo's AGENTS.md file(s) — the generic open-standard file (see the AGENTS.md entry above), including 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 only replaces the specific pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, Use proactively, generic reference-pointer padding) — body discipline, near-miss exclusion strength, and control calibration stay LLM judgment per the issue's explicit non-goals.

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 into styles/Kyberforge (still pending implementation) plus a new sibling pre-commit hook, skill-size-check (scripts/skill-size-check.sh), enforcing skill-authoring.md'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.