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.

Docs convention

Workflow artifacts are committed to docs/ in subdirectories by type. All are tracked as issues.

Naming:

• docs/prd/<slug>.md — Product Requirements Documents
• docs/notes/<slug>.md — Exploration Notes
• docs/adr/NNNN-<slug>.md — Architecture Decision Records
• docs/issues/NNNN-<slug>.md — Issues
• docs/spec/<slug>.md — Living spec files (current deployed state); updated in the same PR as any behavior change

NNNN — zero-padded 4-digit sequential number (e.g. 0001, 0042). Used only for artifact types referenced by number (issues, ADRs). PRDs, ARDs, Bug Briefs, and Notes are referenced by topic and use a descriptive slug only.

Other repo-level artifacts:

• LESSONS.md — long-loop feedback log; patterns observed during development. Three or more entries on the same pattern graduate to the relevant standing file. Updated by the session-handoff skill or by the human directly.

Slug — kebab-case, lowercase, max 4–5 words, derived from the document title. No dates (git history carries dates). Examples: chunk-2-instructions, user-auth-flow, database-migration.

When each is written: PRDs, ARDs — produced by a grill session before issues are created. ADRs are post-decision — written during or after implementation of an ARD when a hard-to-reverse choice is made. An improvement kick-off produces either a PRD (user-facing scope) or ARD (architectural scope).

Content chunk QA

Instruction files and other content chunks cannot be unit tested. Verification is human-executed after implementation: open a new Claude session, exercise the relevant behaviour, and confirm the rules take effect. Each issue includes a short acceptance criteria checklist for the human to run post-commit. Automated QA applies to tooling (scripts, hooks); manual QA applies to agent behaviour and content correctness.

Instruction quality matters more than instruction presence. In-context rules (including always-on CLAUDE.md rules) compete with the model's RLHF-trained defaults and can lose — even in a fresh session with the files correctly deployed. Flat one-liner imperatives are the weakest form. Rules that are specific, include a counter-example ("do X, not Y"), or show the boundary condition are significantly more reliable. When a behavioral test fails, the first question is whether the rule is underspecified, not whether in-context instruction-following is inherently unreliable. Do not accept rule violations as an expected baseline — treat them as a signal to strengthen the instruction.

Conventional commits

All commits in this repo follow the Conventional Commits specification (feat:, fix:, docs:, chore:, refactor:, test:). Convention is defined in core/instructions/git.md. Changelog tooling is a follow-on issue — convention is established first.

Repo/gitea as source of truth

All project state, decisions, context, and working conventions live in this repo ro 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) and the resolved rows (marked ✅) in the docs/ROADMAP.md open questions table. Never propose an approach without verifying no decision already covers it.

Before answering any orientation question ("what's next?", "where were we?", "what are we working on?", "what's the status?"), read docs/ROADMAP.md and check the handoff section of any open issue files in docs/issues/ that are relevant to the current chunk. Do not answer from memory or git log alone — the roadmap and open issues are the authoritative source of current status.

Working context

This repo is built by a junior developer as a homelab tool intended to scale to professional environments. The agent should challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them.

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. Two deployment paths: (1) direct — .agents/skills/<skill-name>/SKILL.md in this repo, deployed to ~/.agents/skills/ on install, available immediately as slash commands; (2) via plugin — plugins/<plugin-name>/skills/<skill-name>/SKILL.md, available only after the plugin is installed (claude plugin install <name>@<marketplace>). Providers that don't read ~/.agents/skills/ natively get a symlink adapter declared in providers/<name>/provider-manifest.sh (e.g. Claude Code: ~/.claude/skills/ → ~/.agents/skills/). Skills inside plugins 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 scaffold

The non-content structural parts of a plugin: both manifests (plugin.json and .claude-plugin/plugin.json), directory skeleton (skills/, agents/, hooks/, bin/), and version. Distinct from plugin content (the skills, agents, hooks, and MCP servers inside those directories). Managed by /plugin-author; content is managed by content-specific skills (/skill-author, /agent-author, etc.).

Version parity

The convention that the version field is always present and identical in both the Copilot CLI manifest (plugin.json) and the Claude Code manifest (.claude-plugin/plugin.json). Enforced by /plugin-author on every create and update. Existing plugins in the repo did not follow this convention before ADR-0016.

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. Register the marketplace with claude plugin marketplace add <owner>/<repo>. Plugin names must be kebab-case and not reserved (anthropic-*, claude-*, agent-skills, official-claude-plugins). Cross-tool compatibility reference: plugins/kyberforge/docs/plugin-marketplace-architecture.md.

Content types

• Instructions — stateless rules defining AI behavior. Split into two tiers: (1) universal rules (communication, behavior) live in AGENTS.md (provider-agnostic), loaded into every session via the provider adapter (CLAUDE.md imports AGENTS.md); (2) topic-specific rules (coding, git, testing) live in core/instructions/<topic>.md and are read on-demand via @import in the Claude Code adapter.
• Agents — role definitions activated on-demand for a specific task.
• Workflows — compositions of skills chained into a larger task. Invokable by agents or humans. Example: grill-me → write-prd → break-into-issues as the canonical design workflow.
• Prompts — shared fragments (system prompt sections, output formats) embedded into multiple skills or workflows.

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

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. Composition chains are formalised as workflows in Chunk 4.

INFO (finding level)

A third finding level in skill-audit reports, below SUGGESTION. Observational — flags something worth noting that is not actionable and does not imply a defect. A skill with only INFO findings is a clean PASS. Counted separately in the result block as · P info and never mixed into the FAIL or SUGGESTION counts. Current use: a references/*.md file with no source_keys when sources.md is present; a skill-level source slug not found in the upstream research sources. See ADR-0014.

Provider-agnostic issue tracker

Skills and workflows reference "linked issue" generically rather than a specific provider. In the file-based phase, an issue is a docs/issues/NNNN-<slug>.md file. When Gitea MCP is configured, the same skills use it instead. The active backend is determined at runtime by MCP availability. "Issue" is the canonical 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.

PRD scope

A PRD contains: problem statement, goals, explicit non-goals, functional requirements at feature level, success criteria. Never contains: technical approach, implementation steps, or EARS-level detail. HOW is handled downstream: workstream-level technical approach belongs in architecture-review (≥2 options, tradeoffs, optional step after write-prd); issue-level HOW belongs in issue design notes. Prerequisite: a completed grill session. Validated by inline self-checks in the write-prd skill.

Issue scope

An issue contains: link to parent PRD (inherited why) + one-line context for this slice, EARS-format acceptance criteria, brownfield delta markers (ADDED/MODIFIED/REMOVED), design notes for non-trivial issues (the issue-level HOW — implementation specifics scoped to this slice only), independently completable task checklist. Prerequisite: parent PRD linked, or explicit standalone justification. No issue may block another open issue. Validated by inline self-checks in write-issue-spec and break-into-issues.

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 (Chunk 6 tooling), not maintained manually. This principle applies to instruction files, skills, and workflow documents.

Workstream

A focused work session oriented around a single goal — a feature, bug, improvement, or exploration. Starts with a grill to produce an artifact (PRD, Bug Brief, ADR, etc.), runs through issue implementation, and closes with docs + commit. Ongoing skills (/diagnose, /prototype, /zoom-out) are invoked ad hoc within a workstream as needed.

Workflow artifacts

Output documents produced by a grill session that scope the work before implementation. All are committed to the repo under docs/ following the docs convention. Each artifact generates one or more issues but is not itself an issue.

Pre-work (grill output):

• PRD (Product Requirements Document) — for features and improvements with user-facing scope

Post-decision:

• ADR (Architecture Decision Record) — records the decision made, alternatives considered, and rationale. Written during or after implementation of an ARD, not before. Hard-to-reverse decisions only.