Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

chore: bootstrap repo with chunks 1 and 2

Browse Source 
Establishes the global AI development config repo from scratch:

- Chunk 1: repo skeleton, install.sh, statusline, deploy manifest
- Chunk 2: core instructions (coding/git/testing), CLAUDE.md rewrite
  (always-on + content index two-tier model), docs restructure,
  6 ADRs, ROADMAP.md, .gitkeep placeholders
- Bootstrap skills in .claude/skills/ (to be catalogued and migrated
  to .agents/skills/ in Chunk 3)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Defame1297
2026-05-10 19:29:58 +00:00
commit a3bb708bff
66 changed files with 3283 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
CONTEXT.md Normal file
View File

@@ -0,0 +1,78 @@
---
name: AI Development Repo
description: 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](https://agentskills.io). 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.