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

providers/claude-code/CLAUDE.md (source) is deployed to ~/.claude/CLAUDE.md via install.sh. It has two tiers: (1) a short always-loaded section for universal rules that must apply every session — including communication style; (2) a content index of pointers to on-demand files in ~/.claude/core/ that the agent reads when needed. Context size is kept minimal.

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

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.

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.

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.

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.

Fleet

The set of machines and projects under management in Phase 2 of the Management Application. A fleet member is any machine that has the config deployed and can be reached by the runtime orchestration layer.

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.

Content types

• Instructions — stateless rules defining AI behavior. Split into two tiers: (1) universal rules (communication, behavior) live in the always-on section of providers/claude-code/CLAUDE.md; (2) topic-specific rules (coding, git, testing) live in core/instructions/<topic>.md and are read on-demand.
• 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 → to-prd → to-issues as a product design workflow.
• Prompts — shared fragments (system prompt sections, output formats) embedded into multiple skills or workflows.

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.