holocron/CONTEXT.md

name, description

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

Context

Principles

Provider-agnostic core

core/ content uses plain imperative language — no tool names, provider APIs, or format assumptions. Anything referencing a specific tool belongs in providers/, not core/. Providers translate core content into the tool's expected format and language.

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/ard/<slug>.md — Architecture Requirements Documents
• docs/bug/<slug>.md — Bug Briefs
• 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, Bug Briefs, and Notes are pre-work — 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.

Project override model

Projects override on-demand content (workflows, agent roles, prompts) by placing their own versions in .claude/. Universal rules are additive — projects extend them, not replace them. A rule that needs per-project suppression is not truly universal.

Sync model

Projects must never edit synced files directly — customizations live in separate override files. A sync conflict is a signal that a synced file was edited directly.

Repo as source of truth

All project state, decisions, context, and working conventions live in this repo. 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. Canonical location: .agents/skills/<skill-name>/SKILL.md in this repo; deployed to ~/.agents/skills/ on install. 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/).

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.

Source field

Field (source:) in a skill's META.md tracking upstream provenance. An array — supports multiple upstream sources per skill. Each entry: repo (GitHub slug, e.g. mattpocock/skills — no URL, slug is stable and searchable), commit (exact SHA reviewed at adoption), files (list of files adopted with inline comments on what was taken), updated (date of last upstream review for this entry). Absence of source: means self-authored original. Upstream review cadence: per-skill during Chunk 3 (run during source review step); quarterly after roadmap completion (post Chunk 7). Companion field: references: (array of URLs or citations) for general external citations — distinct from source: which tracks adoptions with commit-level traceability. Both fields live in META.md, not in SKILL.md frontmatter.

META.md

A per-skill markdown file containing a single YAML code block with provenance and audit fields: version, updated, when, source, and references. Lives alongside the SKILL.md in the skill directory (.agents/skills/<name>/META.md). Not loaded at agent startup — progressive disclosure principle: name and description route the skill; provenance is only needed for upgrade reviews and audits. Prevents these fields from being scanned on every session start alongside every skill's name and description. The authoritative schema is META-TEMPLATE.md in .agents/skills/write-skill/. See also: Source field.

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). Gitea-specific skills are a provider adapter (providers/gitea/), not part of the core library. See ADR-0011.

Design phase sequence

The canonical pre-implementation sequence within any workstream: grill-lean (optional lightweight interrogation, no docs) → grill-me (primary: deep interrogation + domain alignment + ADR writing) → write-prd (why + what only, never how) → architecture-review (optional: technical approach evaluation, ≥2 options) → break-into-issues (independently shippable slices; proposes Gitea milestone groupings for PRDs producing >5 issues).

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 in docs/issues/ but is not itself an issue.

Pre-work (grill output):

• PRD (Product Requirements Document) — for features and improvements with user-facing scope
• ARD (Architecture Requirements Document) — for architectural changes; defines what needs to change and why, analogous to a PRD but for architecture. Produced before implementation; not the same as an ADR.
• Bug Brief — for bugs; feeds into /diagnose
• Exploration Note — for ideation; may or may not produce issues

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.