--- 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/.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/.md` — Product Requirements Documents - `docs/ard/.md` — Architecture Requirements Documents - `docs/bug/.md` — Bug Briefs - `docs/notes/.md` — Exploration Notes - `docs/adr/NNNN-.md` — Architecture Decision Records - `docs/issues/NNNN-.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.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/.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.