aRustyDev
diff --git a/‎components/rules/ai-context-files.md‎
Lines changed: 41 additions & 0 deletions b/‎components/rules/ai-context-files.md‎
Lines changed: 41 additions & 0 deletions
diff --git a/‎components/rules/architecture-decision-records.md‎
Lines changed: 45 additions & 0 deletions b/‎components/rules/architecture-decision-records.md‎
Lines changed: 45 additions & 0 deletions
diff --git a/‎components/rules/claude.md‎
Lines changed: 41 additions & 0 deletions b/‎components/rules/claude.md‎
Lines changed: 41 additions & 0 deletions
diff --git a/‎components/rules/documentation.md‎
Lines changed: 55 additions & 0 deletions b/‎components/rules/documentation.md‎
Lines changed: 55 additions & 0 deletions
diff --git a/‎components/rules/frontmatter.md‎
Lines changed: 72 additions & 0 deletions b/‎components/rules/frontmatter.md‎
Lines changed: 72 additions & 0 deletions
diff --git a/‎components/rules/justfile.md‎
Lines changed: 74 additions & 0 deletions b/‎components/rules/justfile.md‎
Lines changed: 74 additions & 0 deletions
@@ -0,0 +1,41 @@
+---
+paths:
+  - .claude/**
+  - CLAUDE.md
+  - CLAUDE.local.md
+  - AGENT.md
+  - AGENTS.md
+---
+
+# AI Context Files
+
+## Source of Truth
+
+`aRustyDev/ai` is the central repository for all AI context files.
+
+Structure: `components/<type>/<name>/` where type is one of:
+- `skills/` - Domain expertise and methodology
+- `rules/` - Behavioral constraints and patterns
+- `commands/` - Slash command definitions
+- `agents/` - Agent configurations
+- `hooks/` - Event-driven automations
+
+## Local → Central Flow
+
+1. **Develop locally** in `.claude/` during project work
+2. **Stabilize** through use across sessions
+3. **Generalize** by removing project-specific details
+4. **PR to `aRustyDev/ai`** targeting `components/<type>/<name>/`
+5. **Reference centrally** once merged
+
+## When to Upstream
+
+- Rule/skill is useful beyond this single project
+- Content has been validated across multiple sessions
+- No project-specific secrets or paths remain
+
+## When to Keep Local
+
+- Project-specific configuration
+- Experimental rules still being refined
+- Overrides of central content for this repo only
@@ -0,0 +1,45 @@
+---
+paths:
+  - "docs/src/adr/*.md"
+  - "adr-*.md"
+---
+
+# Architecture Decision Records
+
+> **Skill**: Load `architecture-decision-records-dev` for authoring, reviewing, planning, updating, or backfilling ADRs.
+
+## Directory & Naming
+
+- Store ADRs in `docs/src/adr/`
+- Name: `adr-NNN-title-in-kebab-case.md` (3-digit, sequential)
+- Find next number: `ls docs/src/adr/ | grep -oP '\d+' | sort -n | tail -1`
+
+## Required Sections
+
+| Section | Purpose |
+|---------|---------|
+| Frontmatter | Per `frontmatter.md` rule — must include `status` field |
+| Status | Proposed, Accepted, Deprecated, Superseded |
+| Context | Problem statement and constraints |
+| Decision | Specific, actionable choice |
+| Alternatives | 2+ options with trade-offs |
+| Consequences | Positive, negative, neutral |
+| Diagram | At least one Mermaid diagram |
+
+## Rules
+
+1. **One decision per ADR** — keep scope focused
+2. **Document the "why"** — rationale matters more than the "what"
+3. **Never edit accepted ADRs** — write a new ADR that supersedes
+4. **Be specific** — no placeholders, no hand-waving
+5. **Include honest trade-offs** — every choice has downsides
+6. **Title in imperative mood** — "Use X for Y", not "X was chosen"
+
+## Status Lifecycle
+
+```
+Proposed → Accepted → [Deprecated | Superseded by ADR-NNN]
+         → Withdrawn
+```
+
+When superseding: update old ADR status to `Superseded by ADR-NNN` and reference the old ADR in the new one.
@@ -0,0 +1,41 @@
+---
+paths:
+  - "**/CLAUDE.md"
+  - "**/.claude/CLAUDE.md"
+  - "**/CLAUDE.local.md"
+---
+
+# CLAUDE.md Context Layering
+
+## Problem
+
+Multiple CLAUDE.md files exist at different levels. Duplicating content wastes context tokens and creates drift.
+
+## Priority Order (highest to lowest)
+
+| Priority | Location | Purpose |
+|----------|----------|---------|
+| 1 | `/Library/Application Support/ClaudeCode/CLAUDE.md` | Enterprise policy (immutable) |
+| 2 | `./.claude/CLAUDE.md` or `./CLAUDE.md` | Project conventions |
+| 3 | `./.claude/rules/*.md` | Domain-specific rules |
+| 4 | `~/.claude/CLAUDE.md` | User preferences |
+| 5 | `./CLAUDE.local.md` | Local overrides (gitignored) |
+
+Files layer additively. Lower priority files extend, not replace, higher ones.
+
+## What Goes Where
+
+| Content | File |
+|---------|------|
+| Cross-project preferences (editor style, commit style) | `~/.claude/CLAUDE.md` |
+| Project structure, conventions, workflows | `.claude/CLAUDE.md` |
+| Domain rules (how to write justfiles, handle docs) | `.claude/rules/*.md` |
+| Personal API keys, local paths, experiments | `CLAUDE.local.md` |
+
+## Rules
+
+- **Never duplicate** content that exists at a higher layer
+- **Always extend** rather than repeat
+- Use `@import` in project CLAUDE.md to reference shared content
+- If content applies to ALL projects, it belongs in `~/.claude/CLAUDE.md`
+- If content applies to matching files only, it belongs in `.claude/rules/` with `globs:` frontmatter
@@ -0,0 +1,55 @@
+---
+paths:
+  - docs/**
+  - "*.md"
+---
+
+# Documentation Types
+
+## Where Things Go
+
+| Type | Location | Format | When |
+|------|----------|--------|------|
+| **User docs** | `docs/src/` | mdBook chapters | Features, guides, reference |
+| **ADRs** | `docs/src/adr/` | ADR template | Architecture decisions |
+| **Blog/Lessons** | `docs/blog/` | Blog post template | Problems solved, insights |
+| **Notes** | `docs/notes/` | Free-form | Scratchpad, research, spikes |
+
+## Output Style by Type
+
+### User Docs (`docs/src/`)
+- Written for **end users**
+- Task-oriented: "How to X"
+- Include code examples with expected output
+- Update `SUMMARY.md` when adding pages
+
+### ADRs (`docs/src/adr/`)
+- Written for **future maintainers**
+- Follow template: Status → Context → Decision → Consequences
+- Numbered sequentially: `001-decision-name.md`
+- Never delete, only supersede
+
+### Blog/Lessons (`docs/blog/`)
+- Written for **future agents and developers**
+- Must include: Problem context, Investigation, Solution, Reproduction steps
+- Goal: enough context to recreate the problem and understand the fix
+- Use `docs/blog/_template.md` as starting point
+
+### Notes (`docs/notes/`)
+- Written for **yourself**
+- No format requirements
+- Ephemeral - can be deleted freely
+- Good for research dumps before formalizing
+
+## Brand Assets
+
+- **Source**: `aRustyDev/brand` (serves `brand.arusty.dev`)
+- **In production**: Use CDN URLs (`brand.arusty.dev/logos/...`)
+- **In development**: Direct file references are fine
+- **Assets**: Logos, colors, typography, guidelines
+- Use `design-brand-applying-dev` skill when styling artifacts
+
+## Central Documentation
+
+- `aRustyDev/docs` aggregates docs from all repos → `docs.arusty.dev`
+- `aRustyDev/blog` serves blog content → `blog.arusty.dev`
@@ -0,0 +1,72 @@
+---
+paths:
+  - "*.md"
+---
+
+# Frontmatter Pattern
+
+## When to Use
+
+Apply frontmatter to markdown files in repos under `aRustyDev/*`, `libsdk/*`, or `civicbyte/*`.
+
+## Schema
+
+Reference: `https://schemas.arusty.dev/markdown/frontmatter/latest.schema.json`
+
+## Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUIDv4 | Document-specific identifier |
+| `project.id` | UUIDv4 | Project this document belongs to |
+| `status` | enum | Document lifecycle state |
+
+### Project ID
+
+The `project.id` value must be consistent across the repo. It exists in two places:
+1. Git note on the root commit
+2. Git config as `project.id`
+
+### Status Enum
+
+Use consistent status values: `draft`, `active`, `deprecated`, `superseded`, `archived`
+
+## Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | Human-readable title |
+| `description` | string | Brief summary |
+| `version` | semver | Document version |
+| `tags` | string[] | Categorization tags |
+| `authors` | string[] | Author list |
+| `related` | map | Related document references |
+
+## Related Field
+
+Maps relation types to lists of UUIDs:
+
+```yaml
+related:
+  extends: [<uuid>]
+  supersedes: [<uuid>]
+  depends-on: [<uuid>]
+  references: [<uuid>]
+```
+
+Reference documents by `id` (UUIDv4), not by file path. This allows documents to move without breaking references.
+
+## Example
+
+```yaml
+---
+id: 550e8400-e29b-41d4-a716-446655440000
+project:
+  id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
+title: Feature Design
+status: active
+tags: [design, core]
+related:
+  depends-on: [7c9e6679-7425-40de-944b-e07fc1f90ae7]
+---
+```
@@ -0,0 +1,74 @@
+---
+paths:
+  - justfile
+  - "*.just"
+---
+
+# Justfile Conventions
+
+> **Skill**: Load `justfile-dev` for authoring, reviewing, planning, converting, or upgrading justfiles.
+
+## Structure
+
+```just
+set shell := ["bash", "-cu"]
+
+# Variables and configuration at top
+
+# =============================================================================
+# Section Name
+# =============================================================================
+
+# Recipe description (this becomes the doc comment)
+[group('section')]
+recipe-name *args:
+    command {{args}}
+```
+
+## Rules
+
+1. **Group all recipes** using `[group('name')]` - no ungrouped recipes except `default`
+2. **Document every recipe** with a comment above it
+3. **Use `set shell := ["bash", "-cu"]`** for safety (`-c` = command string, `-u` = error on undefined vars)
+4. **Prefer parameters over env vars** for recipe inputs
+5. **Keep recipes focused** - single responsibility, compose with dependencies
+6. **Private helpers** start with `_` (e.g., `_ensure-tool`)
+7. **Use `[confirm]`** for destructive operations
+
+## Standard Groups
+
+| Group | Purpose |
+|-------|---------|
+| `dev` | Development workflows (setup, build, fmt, check) |
+| `test` | Testing commands |
+| `lint` | Linting and formatting checks |
+| `docs` | Documentation generation and serving |
+| `docker` | Container operations |
+| `release` | Release and CI workflows |
+| `util` | Maintenance utilities (clean, update) |
+
+## Modules and Imports
+
+- Use `import? "just/<module>.just"` for optional local modules
+- CDN modules: `mod name "https://just.arusty.dev/modules/<name>.just"`
+- Module library lives at `aRustyDev/just` → `just.arusty.dev`
+
+## Key Features Reference
+
+| Feature | Syntax | Use When |
+|---------|--------|----------|
+| Parameters | `recipe name:` | Recipe needs input |
+| Variadic | `recipe *args:` | Pass-through arguments |
+| Default values | `recipe name='default':` | Optional parameters |
+| Dependencies | `recipe: dep1 dep2` | Recipe requires others first |
+| Conditional | `if os() == "macos" { ... }` | Platform-specific logic |
+| Shebang | `#!/usr/bin/env python3` | Multi-line scripts in other languages |
+| `[script]` | `[script('python3')]` | Cleaner alternative to shebang |
+| `[confirm]` | `[confirm('Delete all?')]` | Destructive operations |
+
+## Anti-Patterns
+
+- Don't chain commands with `&&` in recipes (use separate lines or dependencies)
+- Don't use `cd` (use `[working-directory]` attribute instead)
+- Don't put secrets in justfiles (use env vars or `op://` URLs)
+- Don't create monolithic recipes (compose from focused ones)