111 lines
10 KiB
Markdown
111 lines
10 KiB
Markdown
---
|
||
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.
|
||
|
||
**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`, and `docs/VISION.md`. Everything needed to orient is here.
|
||
|
||
### 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.
|
||
|
||
### 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. 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 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.
|
||
|
||
### 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.
|
||
|
||
### Symbolic oversight
|
||
Oversight implemented as a gesture (assigning a reviewer) rather than a functional safeguard. A reviewer without the information, time, agency, or intent to evaluate is not oversight — it is the appearance of oversight. The documented failure mode: symbolic oversight passes audits but does not catch errors. Genuine oversight requires: the reviewer has access to what was produced, time to evaluate it meaningfully, authority to reject it, and the intent to do so.
|
||
|
||
### Data classification tiers
|
||
The four-tier framework governing what data may enter AI context. Apply the tier of the most sensitive element in any dataset or prompt.
|
||
|
||
| Tier | Examples | AI Rule |
|
||
|---|---|---|
|
||
| **Public** | Publicly available info | No restrictions |
|
||
| **Internal** | Operational data, anonymised logs | Enterprise AI tools only; not consumer/free-tier |
|
||
| **Confidential** | Source code, architecture, personal data, IP | Enterprise AI + contractual data-not-trained guarantee |
|
||
| **Restricted** | GDPR Article 9 health/biometrics, credentials, regulated financial data | Never enters AI context — hard architectural prohibition |
|
||
|
||
Defined in full in `docs/ai-constitution.md` Section 3. Agent-actionable rules in `core/instructions/governance.md`.
|
||
|
||
### 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.
|
||
|
||
### 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.
|