From 97a9d26161b76771fe29aaedb06bfd15e33da01d Mon Sep 17 00:00:00 2001 From: Lauri Gates Date: Tue, 7 Apr 2026 20:23:11 +0300 Subject: [PATCH 1/5] docs: initialize blueprint and migrate ADRs to docs/adrs/ - Initialize Blueprint Development structure (v3.2.0) - Create docs/blueprint/ with manifest.json and README - Migrate 13 ADRs + README from docs/adr/ to docs/adrs/ - Fix internal cross-reference in ADR-0011 - Add initial rules: development.md, testing.md, document-management.md - Enable decision detection (document-management rule) - Add docs/blueprint/work-orders/ to .gitignore Co-Authored-By: Claude Opus 4.6 (1M context) --- .gitignore | 3 + .../0001-chezmoi-exact-directory-strategy.md | 159 +++++++++++ ...02-unified-tool-version-management-mise.md | 236 ++++++++++++++++ .../0003-skill-activation-trigger-keywords.md | 187 +++++++++++++ ...0004-subagent-first-delegation-strategy.md | 203 ++++++++++++++ ...05-namespace-based-command-organization.md | 229 +++++++++++++++ .../0006-documentation-first-development.md | 218 +++++++++++++++ .../0007-layered-knowledge-distribution.md | 213 ++++++++++++++ docs/adrs/0008-project-scoped-mcp-servers.md | 231 +++++++++++++++ ...009-conventional-commits-release-please.md | 251 +++++++++++++++++ docs/adrs/0010-tiered-test-execution.md | 262 ++++++++++++++++++ docs/adrs/0011-claude-rules-migration.md | 151 ++++++++++ docs/adrs/0012-justfile-command-runner.md | 252 +++++++++++++++++ ...-nixos-declarative-system-configuration.md | 240 ++++++++++++++++ docs/adrs/README.md | 56 ++++ docs/blueprint/README.md | 29 ++ docs/blueprint/manifest.json | 114 ++++++++ exact_dot_claude/rules/development.md | 23 ++ exact_dot_claude/rules/document-management.md | 31 +++ exact_dot_claude/rules/testing.md | 25 ++ 20 files changed, 3113 insertions(+) create mode 100644 docs/adrs/0001-chezmoi-exact-directory-strategy.md create mode 100644 docs/adrs/0002-unified-tool-version-management-mise.md create mode 100644 docs/adrs/0003-skill-activation-trigger-keywords.md create mode 100644 docs/adrs/0004-subagent-first-delegation-strategy.md create mode 100644 docs/adrs/0005-namespace-based-command-organization.md create mode 100644 docs/adrs/0006-documentation-first-development.md create mode 100644 docs/adrs/0007-layered-knowledge-distribution.md create mode 100644 docs/adrs/0008-project-scoped-mcp-servers.md create mode 100644 docs/adrs/0009-conventional-commits-release-please.md create mode 100644 docs/adrs/0010-tiered-test-execution.md create mode 100644 docs/adrs/0011-claude-rules-migration.md create mode 100644 docs/adrs/0012-justfile-command-runner.md create mode 100644 docs/adrs/0013-nixos-declarative-system-configuration.md create mode 100644 docs/adrs/README.md create mode 100644 docs/blueprint/README.md create mode 100644 docs/blueprint/manifest.json create mode 100644 exact_dot_claude/rules/development.md create mode 100644 exact_dot_claude/rules/document-management.md create mode 100644 exact_dot_claude/rules/testing.md diff --git a/.gitignore b/.gitignore index 8b1105a..3862570 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,9 @@ settings.local.json tmp/ +# Blueprint work orders (task-specific, may contain sensitive details) +docs/blueprint/work-orders/ + # Security: prevent accidental commit of secrets/credentials .env .env.* diff --git a/docs/adrs/0001-chezmoi-exact-directory-strategy.md b/docs/adrs/0001-chezmoi-exact-directory-strategy.md new file mode 100644 index 0000000..53490a0 --- /dev/null +++ b/docs/adrs/0001-chezmoi-exact-directory-strategy.md @@ -0,0 +1,159 @@ +# ADR-0001: Chezmoi exact_ Directory Strategy for Claude Code Configuration + +## Status + +Accepted + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +The `.claude` directory contains Claude Code's configuration including: +- **103+ skills** - Auto-discovered capabilities with YAML frontmatter +- **76 slash commands** - Organized across 14 namespaces +- **22 specialized agents** - Domain-specific task handlers +- **Settings and scripts** - Runtime configuration + +This directory is managed by chezmoi (dotfiles manager) but also actively used by Claude Code processes during runtime. Two competing approaches existed: + +### Option A: Symlink Strategy +Use chezmoi's `symlink_` prefix to create symbolic links from `~/.claude` to the source directory. + +**Pros:** +- Changes immediately visible without `chezmoi apply` +- Single source of truth (source directory) +- Simpler mental model + +**Cons:** +- **Race conditions**: Claude Code processes accessing files during modifications/renames caused corruption +- **Partial states**: Mid-edit files visible to running processes +- **No atomic updates**: Changes applied incrementally, not atomically + +### Option B: exact_ Directory Strategy +Use chezmoi's `exact_` prefix (`exact_dot_claude/`) to copy files with automatic cleanup of orphaned entries. + +**Pros:** +- **Atomic updates**: `chezmoi apply` provides explicit checkpoints +- **Process stability**: Running Claude processes unaffected until apply +- **Auto-cleanup**: Deleted/renamed skills automatically removed (like Neovim plugins with lazy.nvim) +- **Predictable state**: Target always matches source exactly after apply + +**Cons:** +- Requires explicit `chezmoi apply` after changes +- Two locations (source vs target) can cause confusion + +### The Race Condition Problem + +With symlinks, we observed: +1. User edits skill file in source directory +2. Claude Code process reads partially-written file mid-save +3. YAML frontmatter parsing fails or returns incomplete data +4. Skill activation becomes unpredictable + +This was particularly problematic because: +- Skills activate based on description matching user queries +- Corrupted descriptions = missed activations +- Multiple Claude sessions could run simultaneously + +### Runtime Directory Challenge + +Claude Code creates runtime directories that should NOT be managed: +- `projects/` - Project-specific state +- `session-env/` - Session environment data +- `shell-snapshots/` - Shell state snapshots +- `plans/` - Plan mode state + +These must persist across `chezmoi apply` operations. + +## Decision + +**Use the `exact_` prefix strategy** with runtime directory preservation via `.chezmoiignore`. + +### Implementation + +1. **Source directory**: `~/.local/share/chezmoi/exact_dot_claude/` +2. **Target directory**: `~/.claude` (managed atomically) +3. **Runtime preservation**: `exact_dot_claude/.chezmoiignore` excludes runtime directories + +``` +# exact_dot_claude/.chezmoiignore +plans/ +projects/ +session-env/ +shell-snapshots/ +settings.local.json +``` + +### Workflow + +```bash +# Edit skills/commands in source directory +vim ~/.local/share/chezmoi/exact_dot_claude/skills/my-skill/SKILL.md + +# Apply atomically when ready +chezmoi apply -v ~/.claude + +# Or use convenience alias +alias ca-claude='chezmoi apply -v ~/.claude' +``` + +### Why exact_ Instead of Regular Copy + +The `exact_` prefix tells chezmoi to: +1. Remove files in target that don't exist in source +2. Ensure target matches source exactly +3. Delete orphaned skills/commands automatically + +Without `exact_`, renamed or deleted skills would persist as orphans. + +## Consequences + +### Positive + +1. **Eliminated race conditions** - Running Claude processes see consistent state +2. **Explicit checkpoints** - Changes only visible after deliberate `chezmoi apply` +3. **Automatic cleanup** - No manual removal of old skills needed +4. **Predictable behavior** - Skills either fully present or absent, never partial +5. **Safe experimentation** - Edit source without affecting running sessions + +### Negative + +1. **Two-step workflow** - Must remember to run `chezmoi apply` +2. **Potential for drift** - Source and target can diverge until apply +3. **Learning curve** - New contributors must understand the pattern + +### Mitigations + +- **Alias convenience**: `ca-claude` for quick application +- **Documentation**: Clear CLAUDE.md instructions at repository root +- **Git hooks**: Could add pre-commit hook to warn of unapplied changes (not implemented) + +## Alternatives Considered + +### Git Worktree +Use git worktree to have source directory be the actual `.claude` directory. + +**Rejected because**: Still doesn't solve atomicity; introduces git complexity. + +### inotify/fswatch Auto-Apply +Watch source directory and auto-apply on changes. + +**Rejected because**: Defeats the purpose of explicit checkpoints; could apply mid-edit. + +### Containerized Claude Code +Run Claude Code in container with mounted config. + +**Rejected because**: Overkill for this problem; introduces deployment complexity. + +## Related Decisions + +- ADR-0002: Unified Tool Version Management with Mise (shared philosophy of explicit state management) +- Skills activation via trigger keywords (depends on reliable skill file integrity) + +## References + +- chezmoi documentation: https://www.chezmoi.io/reference/source-state-attributes/ +- `exact_dot_claude/CLAUDE.md` - Directory management documentation +- `exact_dot_claude/.chezmoiignore` - Runtime directory exclusions diff --git a/docs/adrs/0002-unified-tool-version-management-mise.md b/docs/adrs/0002-unified-tool-version-management-mise.md new file mode 100644 index 0000000..c19cac0 --- /dev/null +++ b/docs/adrs/0002-unified-tool-version-management-mise.md @@ -0,0 +1,236 @@ +# ADR-0002: Unified Tool Version Management with Mise + +## Status + +Accepted (Migration In Progress) + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +The dotfiles repository manages a complex development environment spanning multiple languages and tool ecosystems: + +### The Tool Sprawl Problem + +**Before mise**, tools were managed by multiple package managers: + +| Tool Type | Package Manager | Config Location | +|-----------|-----------------|-----------------| +| System utilities | Homebrew | `Brewfile` | +| Python runtimes | Homebrew | `Brewfile` | +| Python CLI tools | uv (pipx-style) | `.chezmoidata.toml` | +| Node.js runtime | nvm/Homebrew | Various | +| Rust tools | cargo | `dot_default-cargo-packages` | +| Go tools | go install | Manual | +| Kubernetes tools | Homebrew | `Brewfile` | + +**Problems with multi-manager approach:** + +1. **Version inconsistency**: `brew install kubectl` on different days = different versions +2. **No lockfile**: No way to pin exact tool versions across machines +3. **Slow installations**: `cargo install bat` compiles from source (5+ minutes) +4. **Context switching**: Different commands for different tool types +5. **CI/local drift**: CI might use different tool versions than local +6. **Security gaps**: Homebrew only provides SHA256 checksums + +### Tool Categories Analysis + +We identified distinct tool categories with different requirements: + +**Bootstrap Tools** (must exist before anything else): +- chezmoi, git, fish, mise itself + +**Language Runtimes** (need version switching per-project): +- Python 3.11/3.13, Node.js, Go, Rust, Bun + +**Python CLI Tools** (Python-based utilities): +- ruff, ansible, pre-commit, glances, etc. + +**System CLI Tools** (standalone binaries): +- kubectl, helm, terraform, ripgrep, fd, bat, jq, etc. + +**GUI Applications** (macOS/Linux desktop apps): +- Ghostty, Obsidian, VS Code (Homebrew casks) + +**Services/Daemons** (background processes): +- PostgreSQL, Mosquitto, Ollama + +### Mise Capabilities + +[mise](https://mise.jdx.dev/) (formerly rtx) provides: + +1. **Unified interface**: Single command for all tool types +2. **Multiple backends**: + - Core: Language runtimes (python, node, go, rust) + - `pipx:`: Python tools via uvx (fast!) + - `aqua:`: CLI tools with security attestations + - `npm:`, `cargo:`: Ecosystem-specific tools +3. **Lockfile**: `mise.lock` for reproducible builds +4. **Per-directory versions**: Auto-switch based on `.mise.toml` +5. **Task runner**: Replace Makefile with cross-platform tasks +6. **Security**: aqua backend provides checksums + SLSA provenance + Cosign signatures + +## Decision + +**Adopt mise as the primary tool version manager** while keeping Homebrew for bootstrap tools, GUI apps, and services. + +### Tool Distribution Strategy + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Tool Management Strategy │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ Homebrew (Brewfile) mise (config.toml.tmpl) │ +│ ───────────────────── ──────────────────────── │ +│ • Bootstrap: chezmoi, • Runtimes: python, node, │ +│ git, fish, uv, mise go, rust, bun │ +│ • GUI Apps: casks • Python tools: pipx:ruff, │ +│ • Services: postgresql, pipx:ansible, etc. │ +│ mosquitto • CLI tools: aqua:kubectl, │ +│ • Platform-specific: aqua:helm, aqua:terraform │ +│ lldpd, mas • Search: aqua:ripgrep, │ +│ • Build tools: cmake, aqua:fd, aqua:bat │ +│ ninja, autoconf • Git tools: aqua:lazygit, │ +│ aqua:gh, aqua:delta │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Configuration Structure + +**Primary config**: `private_dot_config/mise/config.toml.tmpl` + +```toml +# Runtimes +[tools] +python = ["3.11", "3.13"] +node = "latest" +go = "1.23" +rust = "stable" +bun = "latest" + +# Python tools (uses uvx automatically when uv installed) +"pipx:ruff" = "latest" +"pipx:ansible" = "latest" +"pipx:pre-commit" = "latest" + +# CLI tools with security verification +"aqua:kubernetes/kubectl" = "latest" +"aqua:helm/helm" = "latest" +"aqua:hashicorp/terraform" = "latest" +"aqua:BurntSushi/ripgrep" = "latest" +``` + +### Backend Selection Criteria + +| Backend | Use When | Security | +|---------|----------|----------| +| Core | Language runtimes | Standard | +| `pipx:` | Python CLI tools | Via uv | +| `aqua:` | Standalone binaries | Checksums + SLSA + Cosign | +| `npm:` | Node.js tools | Via npm | +| `cargo:` | Must compile from source | Standard | + +### Task Runner Migration + +Replace Makefile with mise tasks: + +```toml +[tasks.lint] +description = "Run all linters" +run = "shellcheck **/*.sh && luacheck nvim/lua && actionlint" + +[tasks.update] +description = "Update all tools" +depends = ["update:brew", "update:mise", "update:nvim"] +``` + +**Command mapping**: +- `make lint` → `mise run lint` +- `make update` → `mise run update` +- `make setup` → `mise run setup` + +## Consequences + +### Positive + +1. **Reproducible environments**: `mise.lock` ensures identical versions +2. **Faster installations**: aqua uses pre-built binaries (seconds vs minutes) +3. **Enhanced security**: aqua provides SLSA provenance and attestations +4. **Automatic version switching**: Per-project `.mise.toml` files +5. **Unified interface**: Single tool for runtimes + CLI tools + tasks +6. **Cross-platform tasks**: TOML-based tasks work on macOS/Linux/Windows + +### Negative + +1. **Migration complexity**: Gradual transition from existing tools +2. **Learning curve**: Team must learn mise commands +3. **Dual management**: Homebrew still needed for some categories +4. **Trust requirement**: Must trust `.mise.toml` files in new directories + +### Migration Path + +**Phase 1** (Complete): Create mise config alongside existing tools +**Phase 2** (In Progress): Install tools via mise, verify functionality +**Phase 3** (Planned): Remove duplicates from Homebrew +**Phase 4** (Future): Deprecate legacy tool configs + +### Packages Migrated to mise + +| Category | Count | Examples | +|----------|-------|----------| +| Python tools | 18 | ruff, ansible, pre-commit | +| Kubernetes | 6 | kubectl, helm, argocd, k9s | +| Search tools | 5 | ripgrep, fd, bat, lsd, delta | +| Infrastructure | 2 | terraform, skaffold | +| Data processing | 2 | jq, yq | +| Other CLI | 4 | gh, lazygit, zoxide, atuin | + +**Total**: ~37 tools migrated from Homebrew/cargo/manual + +### Packages Remaining in Homebrew + +- **Bootstrap**: chezmoi, git, fish, uv, mise +- **Build tools**: cmake, ninja, autoconf +- **GUI apps**: All casks +- **Services**: postgresql, mosquitto, ollama +- **Platform-specific**: lldpd (macOS), mas (macOS) +- **Specialized**: arduino-cli, platformio, wireshark + +## Alternatives Considered + +### asdf +The original polyglot version manager. + +**Rejected because**: Slower than mise, less active development, no built-in task runner. + +### nix/home-manager +Declarative system configuration. + +**Rejected because**: Steeper learning curve, overkill for tool versions, less portable. + +### Keep Multi-Manager Approach +Continue with Homebrew + uv + cargo + manual. + +**Rejected because**: No reproducibility, version drift, slow installations. + +### devbox +Nix-based development environments. + +**Rejected because**: Requires Nix understanding, less flexible backends. + +## Related Decisions + +- ADR-0001: Chezmoi exact_ Directory Strategy (shared philosophy of explicit state) +- Homebrew for bootstrap tools (mise depends on Homebrew-installed mise) + +## References + +- mise documentation: https://mise.jdx.dev/ +- aqua registry: https://github.com/aquaproj/aqua-registry +- Migration guide: `docs/mise-migration-guide.md` +- Analysis: `docs/homebrew-mise-migration-analysis.md` +- Configuration: `private_dot_config/mise/config.toml.tmpl` diff --git a/docs/adrs/0003-skill-activation-trigger-keywords.md b/docs/adrs/0003-skill-activation-trigger-keywords.md new file mode 100644 index 0000000..843e425 --- /dev/null +++ b/docs/adrs/0003-skill-activation-trigger-keywords.md @@ -0,0 +1,187 @@ +# ADR-0003: Skill Activation via Trigger Keywords + +## Status + +Accepted + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +The dotfiles repository contains **103+ skills** - modular capabilities that extend Claude's functionality through specialized knowledge domains. Skills activate automatically when Claude determines they're relevant to the user's request. + +### The Discovery Problem + +Skills are discovered from the `~/.claude/skills/` directory, but **only metadata is pre-loaded** at startup: + +```yaml +--- +name: skill-identifier +description: What this does and when to use it +--- +``` + +Claude sees only the `name` and `description` fields (~100 tokens) when deciding whether to load a skill. The full `SKILL.md` content (often 200-500 lines) is only loaded if the skill is activated. + +This creates a **discovery bottleneck**: If the description doesn't match user language, the skill never activates. + +### Measured Activation Rates + +Through experimentation, we measured activation rates across different description approaches: + +| Approach | Activation Rate | Example | +|----------|-----------------|---------| +| Basic description | ~20% | "Helps with documents" | +| Specific capabilities | ~35% | "Extract text from PDFs and process documents" | +| Trigger keywords | ~50% | Includes tool names like "PyPDF2", "pdfplumber" | +| Explicit "Use when..." | ~70% | "Use when user mentions PDFs, forms, extraction" | +| Forced evaluation hooks | ~84% | System-level skill evaluation triggers | + +### The Vocabulary Mismatch + +Users don't speak in technical abstractions. They say: +- "Help me with my dotfiles" (not "configuration file management") +- "Search for TODOs in the code" (not "perform regex pattern matching") +- "Fix my pytest tests" (not "resolve Python testing framework issues") + +Skills with generic descriptions like "helps with configuration" fail to match user vocabulary. + +### Scale Challenge + +With 100+ skills, disambiguation becomes critical: +- Multiple skills could reasonably match a query +- Generic descriptions cause activation conflicts +- Users can't discover skills they don't know exist + +## Decision + +**Adopt explicit trigger keyword patterns** with "Use when..." clauses in all skill descriptions. + +### Description Formula + +``` +[What it does in 1-2 sentences] + [Specific domain terms] + "Use when [explicit triggers]." +``` + +### Implementation Pattern + +**Before (20% activation):** +```yaml +description: Helps with Python testing +``` + +**After (70% activation):** +```yaml +description: | + Core Python development concepts, idioms, best practices, and language features. + Covers Python 3.10+ features, type hints, async/await, and Pythonic patterns. + For running scripts, see uv-run. For project setup, see uv-project-management. + Use when user mentions Python, type hints, async Python, decorators, context managers, + or writing Pythonic code. +``` + +### Trigger Keyword Categories + +1. **Tool names**: `pytest`, `uv`, `ripgrep`, `chezmoi` +2. **File extensions**: `.py`, `.toml`, `.yml` +3. **Config files**: `pyproject.toml`, `.chezmoiignore` +4. **Action verbs**: "search", "find", "deploy", "test" +5. **Domain terms**: "dotfiles", "cross-platform", "container" + +### Real Examples from Repository + +**chezmoi-expert skill:** +```yaml +description: | + Comprehensive chezmoi dotfiles management expertise including templates, cross-platform + configuration, file naming conventions, and troubleshooting. Covers source directory + management, reproducible environment setup, and chezmoi templating with Go templates. + Use when user mentions chezmoi, dotfiles, cross-platform config, chezmoi apply, + chezmoi diff, .chezmoidata, or managing configuration files across machines. +``` + +**rg-code-search skill:** +```yaml +description: Fast code search using ripgrep (rg) with smart defaults, regex patterns, + and file filtering. Use when searching for text patterns, code snippets, or performing + multi-file code analysis. +``` + +### Documentation Requirements + +All skills must include: +1. **YAML frontmatter** with `name` and `description` fields +2. **Description under 1024 characters** but specific enough to disambiguate +3. **"Use when..." clause** with concrete trigger scenarios +4. **Third person perspective** ("Extracts..." not "I extract...") + +## Consequences + +### Positive + +1. **3.5x activation improvement** - From ~20% to ~70% with proper descriptions +2. **Predictable behavior** - Clear mapping between user language and skill activation +3. **Self-documenting** - "Use when" clauses serve as usage documentation +4. **Conflict reduction** - Specific triggers reduce multi-skill ambiguity +5. **Discoverability** - Users can infer skill existence from natural language + +### Negative + +1. **Maintenance burden** - Must update triggers as user vocabulary evolves +2. **Description bloat** - Comprehensive descriptions approach 1024 char limit +3. **False positives** - Overly broad triggers may activate inappropriate skills +4. **Manual process** - No automated validation of activation patterns + +### Skill Writing Checklist + +For each new skill: +- [ ] YAML frontmatter present with `name` and `description` +- [ ] Description answers: What does it do? When should Claude use it? +- [ ] Trigger keywords match user language (not technical jargon) +- [ ] "Use when..." clause explicitly states activation scenarios +- [ ] Third person perspective throughout +- [ ] Under 1024 characters but specific enough + +### Metrics Tracking + +Skills documentation tracks: +- Total skills: 100+ +- YAML frontmatter compliance: 100% +- "Use when" clause adoption: Target 100% + +## Alternatives Considered + +### Semantic Matching +Use embedding-based similarity between user query and skill descriptions. + +**Rejected because**: Would require infrastructure changes to Claude Code; current keyword approach achieves acceptable activation rates. + +### Skill Categories/Tags +Organize skills into categories that users explicitly select. + +**Rejected because**: Adds friction; users shouldn't need to know skill taxonomy. + +### System Hooks for Forced Evaluation +Use Claude Code hooks to force skill evaluation on every request. + +**Partially adopted**: Hooks achieve 84% activation but add latency; reserved for critical skills. + +### Skill Aliases +Multiple names/descriptions pointing to same skill. + +**Not implemented**: Would increase maintenance burden; single well-written description preferred. + +## Related Decisions + +- ADR-0001: Chezmoi exact_ Directory Strategy (skills depend on file integrity) +- ADR-0004: Subagent-First Delegation Strategy (skills inform agent selection) +- ADR-0005: Namespace-Based Command Organization (commands vs skills distinction) + +## References + +- Skills directory: `exact_dot_claude/skills/` +- Skills documentation: `exact_dot_claude/skills/CLAUDE.md` +- External analysis: [Making Skills Activate Reliably](https://scottspence.com/posts/how-to-make-claude-code-skills-activate-reliably) +- Anthropic skills guide: https://code.claude.com/docs/en/skills diff --git a/docs/adrs/0004-subagent-first-delegation-strategy.md b/docs/adrs/0004-subagent-first-delegation-strategy.md new file mode 100644 index 0000000..1814885 --- /dev/null +++ b/docs/adrs/0004-subagent-first-delegation-strategy.md @@ -0,0 +1,203 @@ +# ADR-0004: Subagent-First Delegation Strategy + +## Status + +Accepted + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +Claude Code supports **subagents** - specialized agents that can be spawned to handle specific tasks. The dotfiles repository defines 22+ specialized agents for different domains: + +- `Explore` - Code exploration and research +- `code-review` - Quality, security, performance analysis +- `test-runner` - Test execution and failure analysis +- `security-audit` - OWASP analysis and vulnerability assessment +- `system-debugging` - Root cause analysis +- `documentation` - Generate docs from code +- `cicd-pipelines` - GitHub Actions and deployment +- `code-refactoring` - Quality improvements, SOLID principles +- And 14+ more specialized agents + +### The Quality Problem + +When Claude handles complex tasks directly (without delegation), several issues emerge: + +1. **Context overload** - Long conversations accumulate context, reducing response quality +2. **Inconsistent methodology** - Ad-hoc approaches to systematic tasks +3. **Missed edge cases** - Without specialized expertise, subtle issues escape notice +4. **No validation** - Single-pass execution without expert review + +### Subagent Advantages + +Subagents provide: + +1. **Specialized expertise** - Each agent has domain-specific knowledge +2. **Systematic investigation** - Agents follow consistent methodologies +3. **Fresh context** - New agents start with clean context +4. **Parallel execution** - Independent tasks run simultaneously +5. **Expert validation** - Specialized review catches domain-specific issues + +### The Over-Engineering Risk + +However, delegation has costs: +- **Latency** - Spawning agents takes time +- **Coordination overhead** - Managing multiple agents adds complexity +- **Simple task bloat** - Trivial edits don't need specialized agents + +The challenge: **When should Claude delegate vs. handle directly?** + +## Decision + +**Default to subagent delegation** for any task matching specialized domains, with explicit exceptions for trivial operations. + +### Decision Framework + +``` +Task received +├─ Can it be split into independent subtasks? +│ └─ YES → Identify subtasks, launch multiple agents in parallel +├─ Is it code exploration/research? +│ └─ YES → Use Explore agent +├─ Does it match a specialized domain? +│ └─ YES → Use domain-specific agent +├─ Is it multi-step or complex? +│ └─ YES → Use general-purpose agent or appropriate specialist +├─ Is it a trivial single-file edit? +│ └─ YES → Use direct tools (state reasoning) +└─ When in doubt → Delegate to agent +``` + +### When to Delegate (Default) + +| Task Type | Agent | Why Delegate | +|-----------|-------|--------------| +| Code exploration | `Explore` | Systematic codebase navigation | +| Security review | `security-audit` | OWASP expertise, vulnerability patterns | +| Code review | `code-review` | Quality, security, performance analysis | +| Complex debugging | `system-debugging` | Root cause analysis methodology | +| Documentation | `documentation` | Comprehensive doc generation | +| Test execution | `test-runner` | Failure analysis, concise reporting | +| Test strategy | `test-architecture` | Coverage analysis, framework selection | +| CI/CD work | `cicd-pipelines` | GitHub Actions expertise | +| Refactoring | `code-refactoring` | SOLID principles, quality patterns | + +### When to Handle Directly (Exceptions) + +Only handle directly when ALL conditions are met: + +1. **Single file** - Edit confined to one file +2. **Crystal clear** - Requirements unambiguous +3. **Trivial scope** - Would take longer to explain than execute +4. **No domain expertise needed** - Generic text/code changes + +**Examples of direct handling:** +- "Change variable name X to Y in this file" +- "Fix typo in README line 42" +- "Add this import statement" + +**Counter-examples (should delegate):** +- "Find where error handling is implemented" → `Explore` agent +- "Review this code for security issues" → `security-audit` agent +- "This code is broken, help me fix it" → `system-debugging` agent + +### Parallel Execution + +When tasks are independent, launch multiple agents simultaneously: + +``` +"Review code and run tests" + → Launch code-review + test-runner simultaneously + +"Check security and update docs" + → Launch security-audit + documentation simultaneously + +"Explore auth flow and find API usages" + → Launch multiple Explore agents with different queries +``` + +### Reasoning Transparency + +When handling directly (exception case), explicitly state reasoning: + +> "I'll handle this directly because it's a single-line typo fix in a known file. Delegating would add unnecessary overhead for this trivial change." + +## Consequences + +### Positive + +1. **Consistent quality** - Specialized agents apply domain best practices +2. **Reduced errors** - Expert validation catches domain-specific issues +3. **Parallel throughput** - Independent tasks complete simultaneously +4. **Fresh context** - Agents avoid context pollution from long conversations +5. **Systematic approach** - Agents follow established methodologies +6. **Traceable decisions** - Explicit reasoning when not delegating + +### Negative + +1. **Latency overhead** - Agent spawning takes 1-3 seconds +2. **Coordination complexity** - Must track multiple agent results +3. **Potential over-delegation** - Trivial tasks routed to agents +4. **Learning curve** - Users may not understand agent selection + +### Agent Selection Quick Reference + +| User Says | Agent to Use | +|-----------|--------------| +| "Find...", "Where is...", "How does X work?" | `Explore` | +| "Review this code", "Check quality" | `code-review` | +| "Is this secure?", "Check for vulnerabilities" | `security-audit` | +| "Run the tests", "Why are tests failing?" | `test-runner` | +| "Help me debug", "This is broken" | `system-debugging` | +| "Generate docs", "Document this" | `documentation` | +| "Refactor this", "Improve code quality" | `code-refactoring` | +| "Set up CI", "Fix the workflow" | `cicd-pipelines` | + +### Tiered Test Execution Integration + +Testing follows a tiered model with agent mapping: + +| Tier | Duration | Agent | When | +|------|----------|-------|------| +| Unit | < 30s | `test-runner` | After every change | +| Integration | < 5min | `test-runner` | After feature completion | +| E2E | < 30min | `test-runner` | Before commit/PR | + +Complex test failures escalate to `system-debugging` agent. + +## Alternatives Considered + +### No Delegation (Direct Handling) +Handle all tasks directly without subagents. + +**Rejected because**: Quality degrades with context accumulation; no specialized validation. + +### User-Selected Delegation +Let users explicitly choose when to delegate. + +**Rejected because**: Users shouldn't need to understand agent taxonomy; adds friction. + +### Automatic Complexity Detection +Use heuristics to detect when tasks need delegation. + +**Partially adopted**: Decision framework encodes complexity heuristics, but defaults to delegation. + +### Agent Composition +Create meta-agents that coordinate multiple specialized agents. + +**Future consideration**: Current manual orchestration works; may adopt as patterns stabilize. + +## Related Decisions + +- ADR-0003: Skill Activation via Trigger Keywords (skills inform agent behavior) +- ADR-0005: Namespace-Based Command Organization (commands invoke agents) +- ADR-0001: Chezmoi exact_ Directory Strategy (agent configs managed atomically) + +## References + +- Delegation strategy: `exact_dot_claude/CLAUDE.md` +- Agent definitions: `exact_dot_claude/agents/` +- Test tiers: `exact_dot_claude/CLAUDE.md` (Tiered Test Execution section) diff --git a/docs/adrs/0005-namespace-based-command-organization.md b/docs/adrs/0005-namespace-based-command-organization.md new file mode 100644 index 0000000..74cb0a5 --- /dev/null +++ b/docs/adrs/0005-namespace-based-command-organization.md @@ -0,0 +1,229 @@ +# ADR-0005: Namespace-Based Command Organization + +## Status + +Accepted + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +The dotfiles repository contains **76 slash commands** - markdown files that expand into prompts when invoked with the `/` prefix. As the command collection grew, several problems emerged: + +### The Flat Namespace Problem + +Initially, all commands lived in a flat directory: + +``` +.claude/commands/ +├── commit.md +├── review.md +├── test.md +├── deploy.md +├── lint.md +├── fix-pr.md +├── new-project.md +├── ... +└── (76 files) +``` + +**Problems:** + +1. **Name collisions** - Multiple domains want "test", "review", "deploy" +2. **Discoverability** - Users can't find commands they don't know exist +3. **Cognitive load** - 76 flat commands overwhelm mental models +4. **Ambiguous scope** - `review.md` could be code review, PR review, or doc review + +### Command Growth Trajectory + +| Milestone | Commands | Organization | +|-----------|----------|--------------| +| Initial | ~10 | Flat directory | +| 6 months | ~30 | Flat, naming conflicts | +| 12 months | ~50 | Informal prefixes (git-*, test-*) | +| Current | 76+ | Namespace directories | + +### User Discovery Challenge + +Users invoke commands by memory or tab completion. Without organization: +- Can't remember exact command names +- Tab completion shows 76 options +- No logical grouping aids recall +- Related commands not co-located + +### Comparison: Skills vs Commands + +| Aspect | Skills | Commands | +|--------|--------|----------| +| Invocation | Automatic (Claude decides) | Explicit (user types `/`) | +| Discovery | Via description matching | Via `/` prefix + completion | +| Organization | Flat (100+ skills) | Namespaced (14 categories) | +| Naming | Must be globally unique | Scoped to namespace | + +Skills work flat because Claude handles discovery. Commands need namespaces because humans handle discovery. + +## Decision + +**Organize commands into namespace directories** with colon-separated invocation syntax. + +### Namespace Structure + +``` +.claude/commands/ +├── blueprint-*.md # Root-level: Blueprint methodology +├── project-*.md # Root-level: Project operations +├── code/ # Code quality and review +│ ├── antipatterns.md # /code:antipatterns +│ ├── review.md # /code:review +│ └── refactor.md # /code:refactor +├── configure/ # Infrastructure standards +│ ├── all.md # /configure:all +│ ├── linting.md # /configure:linting +│ └── ... # 20+ configuration commands +├── deploy/ # Deployment operations +├── deps/ # Dependency management +├── docs/ # Documentation generation +├── git/ # Git and GitHub operations +├── lint/ # Linting and quality checks +├── meta/ # Claude Code introspection +├── project/ # Project setup/maintenance +├── sync/ # Synchronization tasks +├── test/ # Testing infrastructure +├── tools/ # Tool initialization +└── workflow/ # Development workflows +``` + +### Invocation Syntax + +```bash +# Namespaced command +/namespace:command + +# Root-level command (backward compatibility) +/command + +# With parameters +/namespace:command arg1 --flag arg2 +``` + +### 14 Namespaces Defined + +| Namespace | Purpose | Example Commands | +|-----------|---------|------------------| +| `code` | Code quality, review | `antipatterns`, `review`, `refactor` | +| `configure` | Infrastructure standards | `all`, `linting`, `tests`, `mcp` | +| `deploy` | Deployment operations | `release`, `handoff` | +| `deps` | Dependency management | `install` | +| `docs` | Documentation | `generate`, `sync`, `decommission` | +| `git` | Git/GitHub operations | `commit`, `maintain`, `issues`, `fix-pr` | +| `lint` | Linting checks | `check` | +| `meta` | Claude introspection | `assimilate`, `audit` | +| `project` | Project setup | `new`, `init`, `modernize` | +| `sync` | Synchronization | `github-podio`, `daily` | +| `test` | Testing infrastructure | `quick`, `full`, `consult`, `setup` | +| `tools` | Tool initialization | `vectorcode` | +| `workflow` | Development automation | `dev`, `dev-zen` | +| (root) | Cross-cutting concerns | `delegate`, `blueprint-*`, `project-*` | + +### Naming Conventions + +1. **Use kebab-case**: `fix-pr.md` not `FixPR.md` +2. **Be descriptive**: `fix-pr.md` better than `fix.md` +3. **Avoid redundant namespace**: `git/commit.md` not `git/git-commit.md` +4. **Use verbs**: `review.md`, `deploy.md`, `generate.md` + +### Migration Path + +Legacy commands remain at root level for backward compatibility: +- `/blueprint-*` - Blueprint Development methodology +- `/project-continue` - Project state analysis +- `/project-test-loop` - TDD loop +- `/refactor` - Legacy (prefer `/code:refactor`) + +## Consequences + +### Positive + +1. **Scoped naming** - `test/run.md` and `lint/check.md` don't conflict +2. **Logical grouping** - Related commands co-located +3. **Improved discovery** - Tab complete within namespace +4. **Scalable** - Can grow to 200+ commands without chaos +5. **Self-documenting** - Namespace reveals command purpose +6. **Reduced cognitive load** - 14 namespaces vs 76 flat commands + +### Negative + +1. **Longer invocation** - `/git:commit` vs `/commit` +2. **Learning curve** - Users must learn namespace structure +3. **Migration overhead** - Existing references need updating +4. **Potential namespace sprawl** - Could create too many namespaces + +### Tab Completion Improvement + +**Before (flat):** +``` +/c +→ commit, code-review, configure-all, configure-linting, ... +``` + +**After (namespaced):** +``` +/c +→ code:, configure: + +/configure: +→ all, linting, tests, mcp, ... +``` + +### Command Counts by Namespace + +| Namespace | Commands | Notes | +|-----------|----------|-------| +| `configure` | 22 | Infrastructure standards | +| `test` | 6 | Testing workflows | +| `git` | 5 | Git operations | +| `docs` | 4 | Documentation | +| `project` | 4 | Project setup | +| `code` | 3 | Code quality | +| `deploy` | 2 | Deployment | +| `sync` | 2 | Synchronization | +| `workflow` | 2 | Automation | +| `meta` | 2 | Introspection | +| Others | 1 each | Specialized | +| (root) | ~10 | Legacy/cross-cutting | + +## Alternatives Considered + +### Flat with Prefixes +Keep flat directory but use filename prefixes: `git-commit.md`, `test-run.md`. + +**Rejected because**: Still clutters tab completion; doesn't provide directory grouping. + +### Deep Nesting +Allow nested namespaces: `/configure:tests:coverage`. + +**Rejected because**: Over-complicates invocation; two levels sufficient for 76 commands. + +### Tag-Based Organization +Flat directory with YAML tags for categorization. + +**Rejected because**: Doesn't improve tab completion; tags require tooling support. + +### Automatic Namespace Inference +Infer namespace from command content. + +**Rejected because**: Explicit directories are clearer; no magic behavior. + +## Related Decisions + +- ADR-0003: Skill Activation via Trigger Keywords (commands invoke skills) +- ADR-0004: Subagent-First Delegation Strategy (commands delegate to agents) +- ADR-0001: Chezmoi exact_ Directory Strategy (commands managed atomically) + +## References + +- Commands directory: `exact_dot_claude/commands/` +- Commands documentation: `exact_dot_claude/commands/CLAUDE.md` +- Migration script: `scripts/migrate-command-namespaces.sh` diff --git a/docs/adrs/0006-documentation-first-development.md b/docs/adrs/0006-documentation-first-development.md new file mode 100644 index 0000000..22adfec --- /dev/null +++ b/docs/adrs/0006-documentation-first-development.md @@ -0,0 +1,218 @@ +# ADR-0006: Documentation-First Development + +## Status + +Accepted + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +The dotfiles repository evolved from a simple configuration collection to a complex system with: +- 103+ skills with intricate activation patterns +- 76 slash commands across 14 namespaces +- 22 specialized agents with delegation rules +- Cross-platform templates and tool configurations +- CI/CD pipelines with automated workflows + +### The Implementation-First Problem + +Early development followed an implementation-first pattern: +1. Write code +2. Test manually +3. Document after (or never) + +**Consequences:** + +- **Undocumented features**: Skills and commands existed without clear usage guidance +- **Inconsistent patterns**: Each feature invented its own conventions +- **Knowledge silos**: Only the creator understood how features worked +- **Regression risk**: No clear specification to test against +- **Discovery failures**: Users couldn't find capabilities they didn't know existed + +### The Context7 Revelation + +Using the `context7` MCP server for documentation research revealed: +- Official documentation often contradicted assumptions +- Tool behaviors had changed between versions +- "Best practices" evolved faster than implementation +- Configuration options had undocumented interactions + +Implementing features without checking current documentation led to: +- Using deprecated APIs +- Missing new capabilities +- Incompatible configurations +- Wasted rework cycles + +### PRD-First Mandate + +For significant features, the lack of upfront requirements caused: +- Scope creep during implementation +- Unclear success criteria +- Misaligned expectations +- Difficult code review (what was the goal?) + +## Decision + +**Adopt documentation-first development** with three pillars: + +### 1. Research Before Implementation + +Before writing any code: + +``` +1. Research relevant documentation using context7 and web search +2. Verify implementation approaches against official docs +3. Check for breaking changes and version compatibility +4. Validate configuration options against current documentation +``` + +**Tools:** +- `context7` MCP server for documentation lookup +- Web search for current best practices +- Official tool documentation + +### 2. PRD-First for Significant Features + +Every new feature or significant change MUST have a Product Requirements Document: + +```markdown +# Feature Name PRD + +## Problem Statement +What problem are we solving? + +## Proposed Solution +How will we solve it? + +## Success Criteria +How do we know it works? + +## Non-Goals +What are we NOT doing? + +## Technical Approach +Implementation strategy + +## Testing Plan +How will we verify? +``` + +**Enforcement:** +- Use `requirements-documentation` agent for PRD generation +- PRD templates in `docs/` directory +- PRD review before implementation begins + +### 3. Test-Driven Development (TDD) + +Follow strict RED → GREEN → REFACTOR workflow: + +``` +1. RED: Write a failing test that defines desired behavior +2. GREEN: Implement minimal code to make the test pass +3. REFACTOR: Improve code quality while keeping tests green +4. Run full test suite to verify no regressions +``` + +**Tiered Test Execution:** + +| Tier | When to Run | Duration | +|------|-------------|----------| +| Unit | After every change | < 30s | +| Integration | After feature completion | < 5min | +| E2E | Before commit/PR | < 30min | + +### Implementation Checklist + +Before implementing any change: + +- [ ] Read relevant documentation sections thoroughly +- [ ] Verify syntax and parameters in official documentation +- [ ] Check for breaking changes and version compatibility +- [ ] Review best practices and recommended patterns +- [ ] Validate configuration options against current docs +- [ ] Check for deprecated features to avoid +- [ ] Confirm implementation matches current best practices + +## Consequences + +### Positive + +1. **Reduced rework** - Documentation research catches issues early +2. **Consistent patterns** - PRDs establish conventions before code +3. **Clear success criteria** - Tests define expected behavior +4. **Knowledge preservation** - Documentation captures rationale +5. **Easier onboarding** - New contributors understand the "why" +6. **Better code review** - PRD provides review context + +### Negative + +1. **Initial slowdown** - Documentation takes time upfront +2. **Overhead for small changes** - PRD may be overkill for trivial fixes +3. **Documentation drift** - Must maintain docs alongside code +4. **Tool dependency** - Relies on context7 MCP availability + +### Scope Guidelines + +| Change Type | PRD Required? | Documentation Required? | +|-------------|---------------|------------------------| +| New feature | Yes | Yes | +| Significant refactor | Yes | Yes | +| Bug fix | No | Update if behavior changes | +| Typo fix | No | No | +| Dependency update | No | If breaking changes | +| New skill/command | Yes (brief) | Yes | + +### Agent Integration + +Testing agents consult based on scenario: + +| Scenario | Agent | +|----------|-------| +| Run tests, analyze failures | `test-runner` | +| New feature test strategy | `test-architecture` | +| Complex test failures | `system-debugging` | +| Test code quality review | `code-review` | + +Consult `test-architecture` agent when: +- Creating tests for new features +- Coverage drops or gaps identified +- Flaky tests detected +- Test framework decisions needed + +## Alternatives Considered + +### Pure TDD Without Documentation Research +Write tests first without researching current documentation. + +**Rejected because**: Tests may encode incorrect assumptions about tool behavior. + +### Documentation After Implementation +Write docs after code is complete (traditional approach). + +**Rejected because**: Knowledge loss, inconsistent patterns, undocumented features. + +### Wiki-Based Documentation +Maintain documentation in external wiki instead of repo. + +**Rejected because**: Documentation drifts from code; not versioned together. + +### Minimal Documentation +Only document public APIs and user-facing features. + +**Rejected because**: Internal patterns need documentation for maintainability. + +## Related Decisions + +- ADR-0003: Skill Activation via Trigger Keywords (documentation enables discovery) +- ADR-0004: Subagent-First Delegation Strategy (agents enforce TDD) +- ADR-0007: Layered Knowledge Distribution (where documentation lives) + +## References + +- Core principles: `exact_dot_claude/CLAUDE.md` (Development Process section) +- PRD templates: `docs/` directory +- Test commands: `exact_dot_claude/commands/test/` +- requirements-documentation agent: `exact_dot_claude/agents/requirements-documentation/` diff --git a/docs/adrs/0007-layered-knowledge-distribution.md b/docs/adrs/0007-layered-knowledge-distribution.md new file mode 100644 index 0000000..0c34579 --- /dev/null +++ b/docs/adrs/0007-layered-knowledge-distribution.md @@ -0,0 +1,213 @@ +# ADR-0007: Layered Knowledge Distribution (CLAUDE.md Architecture) + +## Status + +Accepted + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +The dotfiles repository contains extensive configuration and automation across multiple domains: +- Chezmoi dotfiles management +- Neovim editor configuration +- Shell and terminal setup +- Claude Code skills, commands, and agents +- CI/CD workflows +- Maintenance scripts + +### The Monolithic Documentation Problem + +Initially, all guidance lived in a single root `CLAUDE.md` file. As the repository grew: + +**Problems with single-file documentation:** +1. **Information overload** - 1000+ lines in one file +2. **Irrelevant context** - Neovim details shown when working on shell configs +3. **Maintenance burden** - All changes to one file cause merge conflicts +4. **Discovery failure** - Hard to find domain-specific guidance +5. **Stale information** - Distant sections not updated with related code + +### Claude Code's Context Loading + +Claude Code automatically loads `CLAUDE.md` files from: +1. Repository root +2. Current working directory +3. Parent directories up to root + +This means **multiple CLAUDE.md files are loaded simultaneously**, enabling layered documentation that's context-aware. + +### Domain Expert Principle + +Different repository areas have different experts: +- Neovim config → Neovim expertise +- Fish shell → Shell scripting expertise +- Skills system → Claude Code agent expertise +- CI/CD → GitHub Actions expertise + +Centralizing all documentation forces one person/context to maintain all domains. + +## Decision + +**Distribute documentation across domain-specific CLAUDE.md files** following the principle: "Domain experts write domain documentation at the point of source code." + +### Documentation Hierarchy + +``` +dotfiles/ +├── CLAUDE.md # Root: Repository overview, tools, security +├── exact_dot_claude/ +│ ├── CLAUDE.md # Claude Code: Design principles, delegation +│ ├── commands/ +│ │ └── CLAUDE.md # Commands: 14 namespaces, 76 commands +│ ├── skills/ +│ │ └── CLAUDE.md # Skills: 103+ skills, activation patterns +│ └── agents/ +│ └── CLAUDE.md # Agents: 22 agents, delegation flows +├── private_dot_config/ +│ ├── CLAUDE.md # Config: Chezmoi naming, templates +│ └── nvim/ +│ └── CLAUDE.md # Neovim: Lua config, LSP, plugins +└── scripts/ + └── CLAUDE.md # Scripts: Maintenance automation +``` + +### 8 CLAUDE.md Files by Domain + +| File | Domain | Key Content | +|------|--------|-------------| +| **Root** | Repository | Overview, MCP servers, linting, security, release-please | +| **exact_dot_claude/** | Claude Code design | Delegation strategy, core principles, TDD workflow | +| **commands/** | Slash commands | 14 namespaces, command anatomy, creation guide | +| **skills/** | Agent skills | 103+ skills, activation patterns, YAML format | +| **agents/** | Specialized agents | 22 agents, analysis vs implementation, delegation flows | +| **private_dot_config/** | Configuration | Chezmoi naming, templates, cross-platform | +| **nvim/** | Neovim | Lua architecture, LSP, plugins, lazy.nvim | +| **scripts/** | Maintenance | Completion generation, namespace migration | + +### Content Distribution Rules + +| Content Type | Location | Rationale | +|--------------|----------|-----------| +| Repository overview | Root | First thing anyone sees | +| Tool versions, linting | Root | Applies everywhere | +| Security, secrets | Root | Critical, universal | +| Claude Code philosophy | exact_dot_claude/ | Design decisions | +| Command reference | commands/ | Co-located with commands | +| Skill activation guide | skills/ | Near skill definitions | +| Agent architecture | agents/ | With agent configs | +| Chezmoi patterns | private_dot_config/ | Config-specific | +| Neovim details | nvim/ | Editor-specific | +| Script usage | scripts/ | Near scripts | + +### Cross-Reference Pattern + +Each domain CLAUDE.md includes a "See Also" section: + +```markdown +## See Also + +- **Root CLAUDE.md** - Overall repository guidance +- **`.claude/CLAUDE.md`** - High-level design and delegation strategy +- **Chezmoi Expert Skill** - Automatic guidance for chezmoi operations +``` + +### Root CLAUDE.md Quick Reference + +The root file includes a navigation table: + +```markdown +| Topic | Documentation | Key Information | +|-------|---------------|-----------------| +| **Overall guidance** | `CLAUDE.md` (this file) | Repository overview | +| **Claude Code design** | `.claude/CLAUDE.md` | Delegation strategy | +| **Slash commands** | `.claude/commands/CLAUDE.md` | 14 namespaces | +| **Skills catalog** | `.claude/skills/CLAUDE.md` | 103+ skills | +| **Configuration** | `private_dot_config/CLAUDE.md` | Chezmoi patterns | +| **Maintenance** | `scripts/CLAUDE.md` | CLI completions | +``` + +## Consequences + +### Positive + +1. **Context-aware loading** - Only relevant docs loaded per directory +2. **Reduced cognitive load** - Focused information per domain +3. **Parallel maintenance** - Different areas updated independently +4. **Domain expertise** - Specialists maintain their sections +5. **Discoverable** - Documentation lives near related code +6. **Merge-friendly** - Changes isolated to domain files + +### Negative + +1. **Navigation complexity** - Must know where to look +2. **Potential duplication** - Some info may appear in multiple places +3. **Consistency challenge** - Different writing styles per domain +4. **Discovery for newcomers** - Must learn the hierarchy + +### File Size Guidelines + +| File | Target Lines | Rationale | +|------|--------------|-----------| +| Root CLAUDE.md | 300-500 | Overview, not exhaustive | +| Domain CLAUDE.md | 200-400 | Focused reference | +| Subdomain CLAUDE.md | 100-200 | Specific details | + +If a CLAUDE.md exceeds 500 lines, consider: +1. Moving detailed content to separate docs +2. Creating subdomain CLAUDE.md files +3. Using progressive disclosure (summary → details) + +### Update Protocol + +When making changes: + +1. **Identify affected domain** - Which CLAUDE.md owns this content? +2. **Update domain file** - Make changes in the appropriate file +3. **Check cross-references** - Update "See Also" if needed +4. **Verify navigation** - Ensure root quick reference is current + +## Alternatives Considered + +### Single Monolithic CLAUDE.md +Keep all documentation in one file. + +**Rejected because**: Information overload, maintenance burden, irrelevant context loading. + +### External Documentation System +Use dedicated docs site (GitBook, Docusaurus, etc.). + +**Rejected because**: Not loaded by Claude Code; documentation drifts from code. + +### README.md Files Instead +Use README.md in each directory. + +**Rejected because**: Claude Code specifically loads CLAUDE.md; README is for humans browsing GitHub. + +### Wiki-Based Documentation +Maintain docs in GitHub wiki. + +**Rejected because**: Not versioned with code; not loaded by Claude Code. + +### Flat Documentation Directory +All docs in `docs/` without hierarchy. + +**Rejected because**: Loses co-location benefit; all docs loaded regardless of context. + +## Related Decisions + +- ADR-0006: Documentation-First Development (what to document) +- ADR-0003: Skill Activation via Trigger Keywords (skills docs) +- ADR-0005: Namespace-Based Command Organization (commands docs) + +## References + +- Root: `CLAUDE.md` +- Claude Code design: `exact_dot_claude/CLAUDE.md` +- Commands: `exact_dot_claude/commands/CLAUDE.md` +- Skills: `exact_dot_claude/skills/CLAUDE.md` +- Agents: `exact_dot_claude/agents/CLAUDE.md` +- Configuration: `private_dot_config/CLAUDE.md` +- Neovim: `private_dot_config/nvim/CLAUDE.md` +- Scripts: `scripts/CLAUDE.md` diff --git a/docs/adrs/0008-project-scoped-mcp-servers.md b/docs/adrs/0008-project-scoped-mcp-servers.md new file mode 100644 index 0000000..22886ac --- /dev/null +++ b/docs/adrs/0008-project-scoped-mcp-servers.md @@ -0,0 +1,231 @@ +# ADR-0008: Project-Scoped MCP Servers + +## Status + +Accepted + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +MCP (Model Context Protocol) servers extend Claude Code with specialized capabilities: +- `github` - GitHub API integration for issues, PRs, repos +- `context7` - Documentation lookup and context management +- `playwright` - Browser automation and testing +- `vectorcode` - Semantic code search using embeddings +- `sequential-thinking` - Enhanced reasoning for complex tasks + +### The User-Scoped Problem + +Initially, MCP servers were configured in the user-scoped settings file: + +``` +~/.claude/settings.json + └── mcpServers: { github, playwright, vectorcode, ... } +``` + +**Problems with user-scoped configuration:** + +1. **Context bloat** - All MCP tools loaded in every repository + - Working on a simple script? Still loading Kubernetes, Playwright, Sentry tools + - Token usage increases with unnecessary tool descriptions + +2. **Hidden dependencies** - Team can't see what MCP servers a project needs + - "Why doesn't this work?" → Missing MCP server not in user settings + - Onboarding requires manual MCP configuration + +3. **Environment pollution** - Irrelevant tools appear in suggestions + - "Add a test" → Playwright suggestions in a CLI tool project + - Cognitive load from filtering irrelevant options + +4. **No reproducibility** - Each developer configures differently + - Different MCP servers = different Claude behavior + - Hard to debug team-wide issues + +### MCP Server Categories + +Analysis revealed distinct server categories: + +| Category | Examples | Scope | +|----------|----------|-------| +| **Version Control** | github | Most projects | +| **Documentation** | context7 | Research-heavy projects | +| **Testing** | playwright | Web projects | +| **Search** | vectorcode | Large codebases | +| **Infrastructure** | argocd-mcp, sentry | DevOps projects | +| **Productivity** | podio-mcp | Specific workflows | +| **AI** | sequential-thinking, pal | Complex reasoning | + +Not every project needs every server. + +## Decision + +**Manage MCP servers per-project** via `.mcp.json` in project root, with a favorites registry in `.chezmoidata.toml` for easy installation. + +### Project-Scoped Configuration + +Each project declares its MCP dependencies: + +```json +// .mcp.json (in project root, committed to git) +{ + "mcpServers": { + "github": { + "command": "go", + "args": ["run", "github.com/github/github-mcp-server/cmd/github-mcp-server@latest", "stdio"] + }, + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +**Benefits:** +- Team shares the same MCP configuration via git +- Only relevant servers loaded per project +- Clear project dependencies +- Reproducible across developers + +### Favorites Registry + +Maintain curated MCP server configurations in `.chezmoidata.toml`: + +```toml +[mcp_servers.github] + enabled = false # Disabled by default + scope = "project" + command = "go" + args = ["run", "github.com/github/github-mcp-server/cmd/github-mcp-server@latest", "stdio"] + description = "GitHub API integration" + category = "vcs" + env_vars = ["GITHUB_TOKEN"] + +[mcp_servers.playwright] + enabled = false + scope = "project" + command = "bunx" + args = ["-y", "@playwright/mcp@latest"] + description = "Browser automation and testing" + category = "testing" +``` + +**Why disabled by default?** +- Avoids bloating every project's context +- Forces explicit decision about which servers to enable +- Registry serves as documentation, not auto-installation + +### Installation Workflow + +**Interactive (recommended):** +```bash +/configure:mcp # Claude command for guided installation +``` + +**Manual:** +1. Check available servers in `.chezmoidata.toml` +2. Copy configuration to project's `.mcp.json` +3. Set required environment variables + +### Intelligent Suggestions + +The **mcp-management skill** suggests servers based on project structure: + +| Project Signal | Suggested Server | +|----------------|------------------| +| `.github/` directory | github | +| `playwright.config.*` | playwright | +| Large codebase (>1000 files) | vectorcode | +| `.argocd/` or ArgoCD refs | argocd-mcp | +| `sentry.client.config.*` | sentry | + +### Environment Variables + +Servers requiring API tokens reference environment variables: + +```json +{ + "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } +} +``` + +**Token storage:** +- `~/.api_tokens` - Sourced by shell (gitignored) +- Project `.env` - Local overrides (gitignored) + +**Never hardcode tokens in `.mcp.json`** + +## Consequences + +### Positive + +1. **Clean context** - Only relevant MCP tools per project +2. **Team alignment** - Shared configuration via git +3. **Explicit dependencies** - Clear what a project needs +4. **Reduced confusion** - No irrelevant tool suggestions +5. **Faster startup** - Fewer servers to initialize + +### Negative + +1. **Initial setup** - Must configure `.mcp.json` per project +2. **Duplication** - Similar configs across related projects +3. **Discovery** - New developers must know about registry +4. **Maintenance** - Update configs when servers change + +### Migration Path + +**From user-scoped to project-scoped:** + +1. Identify which MCP servers current project actually uses +2. Create `.mcp.json` with only needed servers +3. Remove servers from `~/.claude/settings.json` (optional) +4. Commit `.mcp.json` to git + +### Server Selection Guide + +| Project Type | Recommended Servers | +|--------------|---------------------| +| **CLI Tool** | github | +| **Web App** | github, playwright | +| **Large Monorepo** | github, vectorcode | +| **DevOps/Infrastructure** | github, argocd-mcp, context7 | +| **Research/Documentation** | github, context7 | +| **Complex Reasoning** | sequential-thinking | + +## Alternatives Considered + +### Keep User-Scoped Only +Continue with all servers in `~/.claude/settings.json`. + +**Rejected because**: Context bloat, no team sharing, hidden dependencies. + +### Workspace-Level Configuration +Configure at IDE/editor workspace level. + +**Rejected because**: Not portable across editors; Claude Code uses `.mcp.json`. + +### Auto-Detection Only +Automatically enable servers based on project structure. + +**Rejected because**: May enable unwanted servers; explicit configuration preferred. + +### Monorepo-Wide Configuration +Single config for entire monorepo. + +**Rejected because**: Different packages may need different servers; too coarse-grained. + +## Related Decisions + +- ADR-0002: Unified Tool Version Management (similar project-scoped philosophy) +- ADR-0006: Documentation-First Development (context7 for research) +- ADR-0004: Subagent-First Delegation (agents may use MCP servers) + +## References + +- Project MCP config: `.mcp.json` +- Favorites registry: `.chezmoidata.toml` (`[mcp_servers]` section) +- MCP management skill: `exact_dot_claude/skills/mcp-management/` +- Installation command: `/configure:mcp` diff --git a/docs/adrs/0009-conventional-commits-release-please.md b/docs/adrs/0009-conventional-commits-release-please.md new file mode 100644 index 0000000..59ca95e --- /dev/null +++ b/docs/adrs/0009-conventional-commits-release-please.md @@ -0,0 +1,251 @@ +# ADR-0009: Conventional Commits and Release-Please Automation + +## Status + +Accepted + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +The dotfiles repository and its plugins require versioning and changelog management. Traditional approaches involve: +- Manual version bumps in package manifests +- Hand-written CHANGELOG.md entries +- Remembering to tag releases +- Coordinating version numbers across multiple files + +### The Manual Versioning Problem + +Manual version management caused: + +1. **Inconsistent versions** - Different files showing different versions +2. **Forgotten changelogs** - Features shipped without documentation +3. **Merge conflicts** - Multiple PRs editing CHANGELOG.md simultaneously +4. **Human error** - Wrong version numbers, duplicate entries +5. **Release friction** - Tedious manual steps delayed releases + +### Conventional Commits Standard + +The [Conventional Commits](https://www.conventionalcommits.org/) specification provides: +- Structured commit messages with semantic meaning +- Machine-readable format for automation +- Human-readable history for understanding changes + +**Format:** +``` +(): + +[optional body] + +[optional footer(s)] +``` + +**Types:** +| Type | Purpose | Version Bump | +|------|---------|--------------| +| `feat` | New feature | Minor (0.x.0) | +| `fix` | Bug fix | Patch (0.0.x) | +| `feat!` | Breaking feature | Major (x.0.0) | +| `BREAKING CHANGE:` | Breaking change footer | Major (x.0.0) | +| `chore` | Maintenance | None | +| `docs` | Documentation | None | +| `refactor` | Code improvement | None | + +### Release-Please Tool + +Google's [release-please](https://github.com/googleapis/release-please) automates: +1. Analyzing conventional commits since last release +2. Determining semantic version bump +3. Generating CHANGELOG.md entries +4. Updating version fields in manifests +5. Creating release PRs +6. Tagging releases when merged + +## Decision + +**Adopt conventional commits with release-please automation**, enforced by skill-based protection and permission system. + +### Commit Message Convention + +All commits must follow conventional commit format: + +**Feature (minor bump):** +``` +feat(auth): add OAuth2 support + +Implements OAuth2 authentication with PKCE. +Includes refresh token rotation. + +Refs: #42 +``` + +**Bug fix (patch bump):** +``` +fix(api): handle timeout edge case + +Fixes race condition in token refresh. + +Fixes: #123 +``` + +**Breaking change (major bump):** +``` +feat(api)!: redesign authentication + +BREAKING CHANGE: Auth endpoint now requires OAuth2. +Migration guide: docs/migration/v2.md +``` + +### Protected Files + +**Hard protection (permission system blocks edits):** +- `**/CHANGELOG.md` - All changelog files + +**Soft protection (skill warns before edits):** +- `package.json` - version field +- `pyproject.toml` - version field +- `Cargo.toml` - version field +- `.claude-plugin/plugin.json` - version field + +### Permission System Configuration + +In `~/.claude/settings.json`: +```json +{ + "permissions": { + "deny": [ + "Edit(**/CHANGELOG.md)", + "Write(**/CHANGELOG.md)", + "MultiEdit(**/CHANGELOG.md)" + ] + } +} +``` + +### Skill-Based Detection + +The `release-please-protection` skill: +1. Detects edit attempts to protected files +2. Explains why manual edits cause problems +3. Provides conventional commit templates +4. Suggests proper workflow + +**Example response when CHANGELOG.md edit attempted:** +``` +⚠️ CHANGELOG.md Protection Active + +I cannot edit CHANGELOG.md - it's managed by release-please automation. + +**Proper workflow:** +1. Make changes with conventional commit messages +2. Release-please automatically generates changelog entries +3. Review and merge the release PR + +**For your change, use:** +feat(scope): your feature description +``` + +### Automated Workflow + +``` +Developer commits → Conventional commit format + ↓ +Release-please → Analyzes commits since last release + ↓ +Creates Release PR → Updates CHANGELOG.md + version fields + ↓ +PR merged → Tags release, publishes +``` + +### Emergency Override + +For exceptional cases requiring manual edits: + +```bash +# 1. Temporarily disable protection +vim ~/.claude/settings.json +# Comment out CHANGELOG.md deny rules + +# 2. Make edits + +# 3. Re-enable protection +# Uncomment the deny rules + +# 4. Sync with chezmoi +chezmoi apply +``` + +## Consequences + +### Positive + +1. **Automated changelogs** - No manual CHANGELOG maintenance +2. **Consistent versioning** - Semantic versions derived from commits +3. **No merge conflicts** - Automated PRs don't conflict +4. **Clear history** - Commit messages explain "why" +5. **Reduced friction** - Releases happen automatically +6. **Team alignment** - Everyone follows same convention + +### Negative + +1. **Learning curve** - Team must learn conventional commit format +2. **Commit discipline** - Requires consistent message formatting +3. **Automation dependency** - Release process depends on tooling +4. **Override complexity** - Emergency manual edits are awkward + +### Enforcement Layers + +| Layer | Mechanism | Scope | +|-------|-----------|-------| +| Permission system | `deny` rules in settings.json | CHANGELOG.md blocked | +| Skill detection | release-please-protection | Version fields warned | +| Pre-commit hooks | commitlint | Commit format validated | +| CI/CD | GitHub Actions | PR validation | + +### Commit Message Checklist + +- [ ] Starts with valid type (`feat`, `fix`, `chore`, etc.) +- [ ] Scope in parentheses if applicable +- [ ] Colon and space after type/scope +- [ ] Description in imperative mood +- [ ] Body explains "why" not "what" +- [ ] Footer references issues if applicable +- [ ] Breaking changes marked with `!` or `BREAKING CHANGE:` + +## Alternatives Considered + +### Manual Versioning +Continue with manual version bumps and changelogs. + +**Rejected because**: Error-prone, inconsistent, creates merge conflicts. + +### Semantic-Release +Use semantic-release instead of release-please. + +**Not rejected**: Both are viable; release-please chosen for its PR-based workflow and multi-language support. + +### Git Tags Only +Use git tags for versioning without changelog automation. + +**Rejected because**: Loses changelog documentation; doesn't update manifest files. + +### Changelog Generator Scripts +Custom scripts to generate changelogs. + +**Rejected because**: Reinventing release-please; maintenance burden. + +## Related Decisions + +- ADR-0006: Documentation-First Development (commits document changes) +- ADR-0004: Subagent-First Delegation (git-commit-workflow skill) +- ADR-0005: Namespace-Based Command Organization (/git:commit command) + +## References + +- Conventional Commits: https://www.conventionalcommits.org/ +- Release-Please: https://github.com/googleapis/release-please +- Protection skill: `exact_dot_claude/skills/release-please-protection/` +- Git commit skill: `exact_dot_claude/skills/git-commit-workflow/` +- Root CLAUDE.md: Release-Please Automation section diff --git a/docs/adrs/0010-tiered-test-execution.md b/docs/adrs/0010-tiered-test-execution.md new file mode 100644 index 0000000..613b314 --- /dev/null +++ b/docs/adrs/0010-tiered-test-execution.md @@ -0,0 +1,262 @@ +# ADR-0010: Tiered Test Execution with Specialized Agents + +## Status + +Accepted + +## Date + +2024-12 (retroactively documented 2025-12) + +## Context + +The dotfiles repository and projects it manages require testing across multiple dimensions: +- Unit tests for individual functions +- Integration tests for component interactions +- End-to-end tests for full workflows +- Configuration validation tests +- Cross-platform compatibility tests + +### The Flat Testing Problem + +Early testing followed a "run all tests" approach: + +```bash +make test # Runs everything, every time +``` + +**Problems:** + +1. **Slow feedback** - 10+ minute test suites for small changes +2. **Wasted resources** - E2E tests run for typo fixes +3. **Developer friction** - Long waits discourage frequent testing +4. **CI bottlenecks** - All PRs wait for full suite + +### Test Duration Analysis + +| Test Type | Typical Duration | When Needed | +|-----------|------------------|-------------| +| Unit | < 30 seconds | Every change | +| Integration | 1-5 minutes | Feature completion | +| E2E | 5-30 minutes | Before commit/PR | +| Performance | 10-60 minutes | Release candidates | + +Running all tests for every change wastes 95%+ of test execution time. + +### Agent Expertise Gap + +Different test scenarios require different expertise: +- **Test failures**: Need failure analysis, not test design +- **New features**: Need test strategy, not just execution +- **Flaky tests**: Need debugging, not more test runs +- **Coverage gaps**: Need architectural guidance + +A single "test" command couldn't provide specialized responses. + +## Decision + +**Implement tiered test execution** with specialized testing agents, exposed via namespace-organized commands. + +### Test Tiers + +| Tier | Duration | Trigger | Command | +|------|----------|---------|---------| +| **Unit** | < 30s | Every change | `/test:quick` | +| **Integration** | < 5min | Feature completion | `/test:full` | +| **E2E** | < 30min | Before commit/PR | `/test:full` | + +### Tier Selection Criteria + +The `test-tier-selection` skill automatically determines appropriate tier: + +``` +Change scope analysis: +├─ Single file, isolated function → Unit tier +├─ Multiple files, same module → Integration tier +├─ Cross-module changes → E2E tier +├─ Configuration changes → Full validation +└─ Documentation only → Skip tests +``` + +### Specialized Testing Agents + +| Agent | Role | Capabilities | +|-------|------|--------------| +| `test-runner` | **Execution** | Run tests, analyze failures, report results | +| `test-architecture` | **Strategy** | Coverage analysis, framework selection, test design | +| `system-debugging` | **Investigation** | Root cause analysis, flaky test diagnosis | +| `code-review` | **Quality** | Test code review, assertion quality | + +### Agent Selection Guide + +| Scenario | Agent | Command | +|----------|-------|---------| +| Run tests, see results | `test-runner` | `/test:quick` or `/test:full` | +| New feature needs tests | `test-architecture` | `/test:consult new-feature` | +| Tests failing mysteriously | `system-debugging` | Direct delegation | +| Coverage dropped | `test-architecture` | `/test:consult coverage` | +| Flaky test detected | `system-debugging` | Direct delegation | +| Test code quality check | `code-review` | `/code:review` on test files | + +### Command Structure + +``` +/test:quick → Unit tests only (< 30s feedback) +/test:full → All tiers (comprehensive) +/test:consult → Consult test-architecture agent +/test:report → Show last test results +/test:run → Auto-detect and run appropriate tests +/test:setup → Configure testing infrastructure +``` + +### Workflow Integration + +**Development Cycle:** +``` +1. Make change +2. /test:quick → Immediate feedback (unit tests) +3. Continue development +4. /test:quick → Verify each change +5. Feature complete +6. /test:full → Comprehensive validation +7. /git:commit → Commit with confidence +``` + +**TDD Loop (via /project-test-loop):** +``` +1. RED: Write failing test +2. /test:quick → Confirm failure +3. GREEN: Implement minimal code +4. /test:quick → Confirm pass +5. REFACTOR: Improve code +6. /test:quick → Verify no regression +``` + +### Agent Delegation Flow + +``` +User: "Run the tests" + │ + ├─ /test:quick or /test:full + │ └─ Delegates to test-runner agent + │ └─ Executes tests + │ └─ Analyzes failures + │ └─ Reports concise summary + │ + └─ If complex failures detected: + └─ test-runner suggests: system-debugging agent + └─ Orchestrator delegates for root cause analysis +``` + +### Failure Reporting Format + +`test-runner` agent provides structured failure reports: + +``` +❌ 3 tests failed + +1. test_auth_flow (tests/test_auth.py:42) + Expected: 200 + Actual: 401 + Likely cause: Token expiration not handled + +2. test_api_timeout (tests/test_api.py:87) + TimeoutError after 30s + Likely cause: Mock server not responding + +3. test_config_load (tests/test_config.py:15) + FileNotFoundError: config.yaml + Likely cause: Missing test fixture + +Suggested actions: +- Fix auth token refresh logic (test 1) +- Check mock server setup in conftest.py (test 2) +- Add config.yaml to test fixtures (test 3) +``` + +## Consequences + +### Positive + +1. **Fast feedback** - Unit tests in <30 seconds +2. **Appropriate testing** - Right tests for right changes +3. **Specialized expertise** - Agents match test scenarios +4. **Resource efficiency** - No unnecessary E2E for small changes +5. **Clear commands** - `/test:quick` vs `/test:full` intent is obvious +6. **Actionable reports** - Failure analysis, not just stack traces + +### Negative + +1. **Tier judgment** - Must decide which tier to run +2. **Agent selection** - Learning which agent for which scenario +3. **Configuration** - Initial setup of test tiers +4. **Potential gaps** - Wrong tier might miss issues + +### Test Infrastructure Requirements + +For full tier support, projects should have: + +``` +tests/ +├── unit/ → Fast, isolated tests +├── integration/ → Component interaction tests +└── e2e/ → Full workflow tests + +pytest.ini or pyproject.toml: + markers: + - unit: Fast unit tests + - integration: Integration tests + - e2e: End-to-end tests +``` + +### Framework Support + +| Framework | Unit Command | Full Command | +|-----------|--------------|--------------| +| pytest | `pytest -m unit` | `pytest` | +| jest | `jest --testPathPattern=unit` | `jest` | +| cargo | `cargo test --lib` | `cargo test` | +| go | `go test -short` | `go test` | + +### Metrics to Track + +- **Time to feedback**: Unit test duration +- **Test reliability**: Flaky test rate +- **Coverage**: Per-tier coverage percentages +- **Agent accuracy**: Correct agent selection rate + +## Alternatives Considered + +### Single Test Command +One command runs all tests always. + +**Rejected because**: Slow feedback, wasted resources, developer friction. + +### Manual Tier Selection +Developer manually specifies which tests to run. + +**Rejected because**: Cognitive load, inconsistent selection, easy to forget tiers. + +### Parallel All Tests +Run all tiers in parallel for speed. + +**Rejected because**: Resource intensive, still slow for E2E, overkill for small changes. + +### Test on Commit Only +Only run tests on git commit. + +**Rejected because**: Feedback too late, larger fix batches, more debugging. + +## Related Decisions + +- ADR-0004: Subagent-First Delegation Strategy (test agents are subagents) +- ADR-0005: Namespace-Based Command Organization (/test: namespace) +- ADR-0006: Documentation-First Development (TDD workflow) + +## References + +- Test commands: `exact_dot_claude/commands/test/` +- Test tier selection skill: `exact_dot_claude/skills/test-tier-selection/` +- test-runner agent: `exact_dot_claude/agents/test-runner/` +- test-architecture agent: `exact_dot_claude/agents/test-architecture/` +- TDD workflow: `exact_dot_claude/CLAUDE.md` (Tiered Test Execution section) diff --git a/docs/adrs/0011-claude-rules-migration.md b/docs/adrs/0011-claude-rules-migration.md new file mode 100644 index 0000000..d8e93da --- /dev/null +++ b/docs/adrs/0011-claude-rules-migration.md @@ -0,0 +1,151 @@ +# ADR 0011: Migration to Claude Code Rules System + +## Status + +Accepted + +## Date + +2025-12-13 + +## Context + +Claude Code introduced the `.claude/rules/` directory feature in v2.0.64 (December 2025) as a modular approach for organizing project-specific instructions. Prior to this, all Claude Code instructions were maintained in: + +1. **CLAUDE.md files** - Monolithic files containing project context, conventions, and operational rules +2. **Skills** - Context-dependent expertise that activates based on task relevance + +The existing setup had several issues: + +- `exact_dot_claude/CLAUDE.md` had grown to 300+ lines mixing high-level design with detailed operational rules +- Universal constraints (delegation, code quality, security) were mixed with project-specific context +- It was unclear which instructions applied universally vs. conditionally +- Maintenance required editing a single large file + +## Decision + +Migrate universal operational rules from CLAUDE.md files to the new `.claude/rules/` directory while: + +1. **Keeping CLAUDE.md files** for high-level project context and navigation +2. **Keeping Skills** for domain-specific expertise that activates conditionally +3. **Creating focused rule files** for universal constraints that apply regardless of task type + +### Rules Created + +| Rule File | Content Migrated From | Purpose | +|-----------|----------------------|---------| +| `rules/delegation.md` | `exact_dot_claude/CLAUDE.md` | When to use subagents vs direct tools | +| `rules/communication.md` | `exact_dot_claude/CLAUDE.md` | Tone, style, response formatting | +| `rules/development-process.md` | `exact_dot_claude/CLAUDE.md` + Root `CLAUDE.md` | TDD, documentation-first, git workflow | +| `rules/code-quality.md` | `exact_dot_claude/CLAUDE.md` | SOLID, functional principles, fail-fast | +| `rules/tool-selection.md` | `exact_dot_claude/CLAUDE.md` | Decision framework for tools | +| `rules/security.md` | Root `CLAUDE.md` | API tokens, secrets, scanning | +| `rules/release-please.md` | Root `CLAUDE.md` | Protected files, conventional commits | + +### Content Kept in CLAUDE.md + +- **Root `CLAUDE.md`**: Repository overview, chezmoi configuration, key files, tools, MCP servers +- **`exact_dot_claude/CLAUDE.md`**: High-level design philosophy, directory structure, chezmoi management + +### Content Kept as Skills + +All 102 skills remain as skills because they: +- Activate conditionally based on task relevance +- Provide specialized domain expertise +- Have YAML frontmatter for activation triggers +- Follow progressive disclosure with REFERENCE.md files + +## Consequences + +### Positive + +- **Improved organization**: Single-concern rule files are easier to maintain +- **Clearer semantics**: Rules = universal, Skills = conditional, CLAUDE.md = context +- **Better discoverability**: Rule files have descriptive names indicating their purpose +- **Reduced file size**: CLAUDE.md files are now focused and concise +- **Future-proof**: Aligned with Claude Code's official feature for project instructions + +### Negative + +- **More files to manage**: 7 rule files instead of 2 large CLAUDE.md sections +- **Learning curve**: Team members need to understand rules vs skills vs CLAUDE.md +- **Chezmoi complexity**: Additional directory (`rules/`) under `exact_dot_claude/` + +### Neutral + +- **Same priority level**: Rules load with the same priority as `.claude/CLAUDE.md` +- **No behavior change**: The same instructions apply, just organized differently +- **Backward compatible**: Existing skills and commands work unchanged + +## Alternatives Considered + +### 1. Keep Everything in CLAUDE.md + +**Rejected because:** +- Files were becoming unwieldy (300+ lines) +- Mixed concerns (context vs rules) +- Claude Code now has a dedicated feature for this + +### 2. Convert All Rules to Skills + +**Rejected because:** +- Skills activate conditionally based on description matching +- Universal constraints should apply unconditionally +- Would require convoluted "Use when..." clauses to always activate + +### 3. Use Path-Scoped Rules Only + +**Rejected because:** +- Most rules apply project-wide, not to specific paths +- Path scoping is better suited for subdirectory-specific conventions +- Would add unnecessary complexity via YAML frontmatter + +## Implementation Notes + +### Directory Structure After Migration + +``` +exact_dot_claude/ +├── CLAUDE.md # Slimmed: ~70 lines (was ~300) +├── rules/ # NEW +│ ├── delegation.md +│ ├── communication.md +│ ├── development-process.md +│ ├── code-quality.md +│ ├── tool-selection.md +│ ├── security.md +│ └── release-please.md +├── skills/ # Unchanged: 102 skills +├── commands/ # Unchanged +└── ... +``` + +### Applying Changes + +After pulling this change: +```bash +chezmoi apply -v ~/.claude +``` + +### Memory Hierarchy + +Rules load in this order (lower number = loaded first, higher takes precedence): + +1. `~/.claude/CLAUDE.md` - User preferences +2. `./CLAUDE.md` - Project root +3. `./.claude/CLAUDE.md` + `./.claude/rules/**/*.md` - **Same level** +4. `./.claude/CLAUDE.local.md` - Personal overrides +5. `./src/CLAUDE.md` - Subdirectory context + +## Related Files + +- `.claude/rules/` - The rules directory this ADR introduces +- `.claude/CLAUDE.md` - High-level design documentation updated to reference rules +- `CLAUDE.md` (root) - Project overview updated with rules references +- `docs/adrs/0001-chezmoi-exact-directory-strategy.md` - Related decision on `exact_` prefix for `.claude/` management + +## References + +- [Claude Code Rules Documentation](https://code.claude.com/docs/en/memory) +- [Claude Code v2.0.64 Changelog](https://claudelog.com/claude-code-changelog/) +- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) diff --git a/docs/adrs/0012-justfile-command-runner.md b/docs/adrs/0012-justfile-command-runner.md new file mode 100644 index 0000000..13d690e --- /dev/null +++ b/docs/adrs/0012-justfile-command-runner.md @@ -0,0 +1,252 @@ +# ADR-0012: Justfile Command Runner + +## Status + +Accepted + +## Date + +2025-12 + +## Context + +The dotfiles repository used a Makefile for common development tasks like applying configurations, running linters, and managing the development environment. + +### Problems with Make + +While Make is ubiquitous, it has several issues for this use case: + +1. **`.PHONY` boilerplate**: Every non-file target requires explicit `.PHONY` declaration +2. **Tab sensitivity**: Recipes must use tabs, not spaces (common source of errors) +3. **GNU vs BSD Make**: Syntax differences between platforms cause portability issues +4. **Variable syntax**: `$(VAR)` vs `${VAR}` vs `$$VAR` confusion +5. **Color output**: Requires manual ANSI escape code definitions +6. **Poor error messages**: Cryptic errors without source context +7. **Build-system baggage**: Make is designed for builds, not command running + +### Recipe Complexity Analysis + +The existing Makefile had 30+ recipes across categories: + +| Category | Recipes | Complexity | +|----------|---------|------------| +| Build & Development | apply, check, diff, status, verify | Simple | +| Testing | test, lint, smoke-* | Medium | +| Environment Setup | setup, setup-brew, setup-mise, setup-nvim | Medium | +| Utilities | update, bump, clean, security-audit | Complex | +| Development | dev, edit, ci | Simple | +| Information | info, help | Simple | + +**Pain points observed**: +- The `lint` recipe had complex shell conditionals for tool detection +- Help generation required awk parsing of `##` comments +- Color definitions duplicated at top of file +- Recursive `$(MAKE)` calls for dependencies + +### Justfile Capabilities + +[just](https://github.com/casey/just) is a modern command runner that addresses these issues: + +1. **No `.PHONY`**: All recipes are commands by default +2. **Indentation agnostic**: Spaces or tabs work fine +3. **Cross-platform**: Consistent behavior on Linux, macOS, Windows +4. **Built-in colors**: `{{BLUE}}`, `{{GREEN}}`, `{{YELLOW}}`, `{{RED}}`, `{{NORMAL}}` +5. **Clear errors**: Shows source context in error messages +6. **Native help**: `just --list` with automatic doc comment extraction +7. **Recipe attributes**: `[private]`, `[confirm]`, `[linux]`, `[macos]`, etc. +8. **Parameters**: Recipes can accept command-line arguments +9. **Conditionals**: `if`/`else` expressions in recipe bodies + +## Decision + +**Replace the Makefile with a justfile** as the project's command runner. + +### Recipe Organization + +``` +justfile +├── Default (help) +├── Build & Development +│ ├── apply # Apply dotfiles +│ ├── check # Alias for status +│ ├── diff # Show differences +│ ├── status # Show status +│ └── verify # Verify integrity +├── Testing +│ ├── test # Run all tests +│ ├── lint # Run all linters +│ ├── lint-shell # Shell scripts only +│ ├── lint-lua # Neovim config only +│ ├── lint-actions # GitHub Actions only +│ ├── pre-commit # Pre-commit hooks +│ ├── smoke # Docker smoke test +│ └── smoke-* # Docker variants +├── Environment Setup +│ ├── setup # Full setup +│ ├── setup-brew # Homebrew packages +│ ├── setup-mise # mise tools +│ └── setup-nvim # Neovim plugins +├── Utilities +│ ├── update # Update all tools +│ ├── bump # Bump versions +│ ├── clean # Clean caches +│ └── secrets # Scan for secrets +├── Development +│ ├── dev # Start dev environment +│ └── edit # Open in editor +└── Information + ├── info # System information + └── doctor # Diagnose issues +``` + +### Key Improvements + +**1. Built-in colored output**: +```just +# Before (Makefile) +BLUE := \033[34m +RESET := \033[0m +apply: + @echo "$(BLUE)Applying...$(RESET)" + +# After (justfile) +apply: + @echo "{{BLUE}}Applying...{{NORMAL}}" +``` + +**2. No `.PHONY` declarations**: +```just +# Before (Makefile) +.PHONY: apply status check diff verify + +# After (justfile) +# Nothing needed - all recipes are commands +``` + +**3. Private recipes for internal use**: +```just +[private] +_check-tool tool: + @command -v {{tool}} >/dev/null 2>&1 +``` + +**4. Platform-specific recipes**: +```just +[macos] +setup-macos: + brew install coreutils + +[linux] +setup-linux: + sudo apt install build-essential +``` + +**5. Recipe parameters**: +```just +# Apply specific target +apply target="": + chezmoi apply {{target}} -v +``` + +### Recipes Removed + +| Recipe | Reason | +|--------|--------| +| `docker` | Deprecated alias for `smoke` | +| `docs-serve` | Not implemented | +| `qa` | Redundant (same as `lint check`) | + +### Recipes Added + +| Recipe | Purpose | +|--------|---------| +| `lint-shell` | Run shellcheck only | +| `lint-lua` | Run luacheck only | +| `lint-actions` | Run actionlint only | +| `pre-commit` | Run pre-commit hooks | +| `secrets` | Scan for secrets with detect-secrets | +| `doctor` | Diagnose common issues | + +### Recipes Modified + +| Recipe | Change | +|--------|--------| +| `lint` | Now depends on individual lint-* recipes | +| `security-audit` | Renamed to `secrets`, uses detect-secrets | +| `colors` | Made private (demo/debug tool) | + +## Consequences + +### Positive + +1. **Simpler syntax**: No Make quirks or POSIX shell restrictions +2. **Better DX**: Built-in colors, `--list` for discovery +3. **Cross-platform**: Consistent behavior everywhere +4. **Maintainable**: Easier to read and modify +5. **Extensible**: Recipe attributes enable advanced patterns +6. **Modern tooling**: Active development, good documentation + +### Negative + +1. **New dependency**: Requires `just` to be installed +2. **Team learning**: Contributors must learn `just` syntax +3. **Ecosystem**: Less ubiquitous than Make +4. **IDE support**: Fewer plugins than Makefile support + +### Migration Path + +1. **Install just**: Added to mise config (`aqua:casey/just`) +2. **Create justfile**: Converted all Makefile recipes +3. **Update docs**: CLAUDE.md references `just` commands +4. **Remove Makefile**: Deleted after verification + +### Command Mapping + +| Old Command | New Command | +|-------------|-------------| +| `make` | `just` | +| `make apply` | `just apply` | +| `make lint` | `just lint` | +| `make test` | `just test` | +| `make setup` | `just setup` | +| `make update` | `just update` | +| `make info` | `just info` | + +## Alternatives Considered + +### Keep Makefile +Continue using Make with workarounds for its limitations. + +**Rejected because**: Accumulated complexity, poor error messages, cross-platform issues. + +### mise Tasks +Use mise's built-in task runner (`mise run`). + +**Rejected because**: Less mature than just, TOML syntax less readable for complex recipes, mise already serves tool version management role. + +### Task (go-task) +Use Taskfile.yml with go-task. + +**Rejected because**: YAML syntax less readable than just, less active community. + +### npm scripts / package.json +Use Node.js scripts pattern. + +**Rejected because**: Requires Node.js, not appropriate for non-JS projects. + +### Shell Scripts +Replace with individual shell scripts. + +**Rejected because**: No unified interface, harder to discover available commands. + +## Related Decisions + +- [ADR-0002](0002-unified-tool-version-management-mise.md): mise for tool management (just installed via mise) +- [ADR-0010](0010-tiered-test-execution.md): Test execution strategy (smoke tests in justfile) + +## References + +- just documentation: https://just.systems/man/en/ +- just GitHub: https://github.com/casey/just +- just vs Make: https://just.systems/man/en/what-are-the-idiosyncrasies-of-make-that-just-avoids.html +- Configuration: `justfile` in repository root diff --git a/docs/adrs/0013-nixos-declarative-system-configuration.md b/docs/adrs/0013-nixos-declarative-system-configuration.md new file mode 100644 index 0000000..72e2234 --- /dev/null +++ b/docs/adrs/0013-nixos-declarative-system-configuration.md @@ -0,0 +1,240 @@ +# ADR-0013: NixOS Configuration for Declarative System Management + +## Status + +Accepted + +## Date + +2025-12 + +## Context + +The dotfiles repository has evolved into a sophisticated cross-platform configuration system using chezmoi and mise. However, for NixOS users, there's an opportunity to achieve even greater reproducibility through fully declarative system configuration. + +### Current State + +The repository already manages: +- **Dotfiles**: Via chezmoi with templates and cross-platform support +- **Tool versions**: Via mise with lockfile for reproducibility +- **Shell configuration**: Zsh/Fish with comprehensive aliases +- **Editor setup**: Neovim with lazy.nvim and 75+ plugins +- **Development tools**: Language runtimes, formatters, linters + +### The Gap + +While chezmoi + mise provides excellent user-level configuration, it doesn't address: + +1. **System-level packages**: Kernel, drivers, system services +2. **Declarative services**: Docker, Tailscale, SSH daemon configuration +3. **Atomic upgrades**: Rollback to previous system state +4. **Full reproducibility**: Same system on any machine from single config + +### Why NixOS Now? + +Several factors motivated adding NixOS support: + +1. **Complementary approach**: NixOS doesn't replace chezmoi—they work together +2. **User preference extrapolation**: Existing configs reveal clear tool preferences +3. **Home Manager integration**: Bridges NixOS and traditional dotfiles +4. **CI/Server use case**: Declarative server configurations for homelab + +### Relationship to ADR-0002 (mise) + +ADR-0002 rejected Nix/home-manager as "overkill for tool versions." This ADR takes a different view: + +| ADR-0002 Position | ADR-0013 Position | +|-------------------|-------------------| +| Nix for tool versions = overkill | NixOS for full system = appropriate | +| mise provides reproducibility | NixOS provides atomic rollbacks | +| Cross-platform (macOS + Linux) | Linux-only (NixOS + home-manager) | + +**Key insight**: mise handles tools on macOS + traditional Linux. NixOS handles full system declarativity when that's desired. They're not competing—they serve different use cases. + +## Decision + +**Add NixOS configuration to the dotfiles repository** as an optional, complementary configuration method for NixOS users. + +### Architecture + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Configuration Approaches │ +├────────────────────────────────────────────────────────────────┤ +│ │ +│ Traditional (macOS/Linux) NixOS │ +│ ───────────────────────── ────── │ +│ • chezmoi for dotfiles • flake.nix for system │ +│ • mise for tool versions • home.nix for user config │ +│ • Homebrew for bootstrap • Declarative packages │ +│ │ +│ ┌──────────────┐ │ +│ │ Shared │ │ +│ │ Principles │ │ +│ ├──────────────┤ │ +│ │ • TokyoNight │ │ +│ │ • Zsh + Fish │ │ +│ │ • Neovim │ │ +│ │ • Git config │ │ +│ │ • Aliases │ │ +│ └──────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────┘ +``` + +### Directory Structure + +``` +nixos/ +├── flake.nix # Flake with inputs and system definitions +├── configuration.nix # NixOS system configuration +├── home.nix # Home Manager entry point +├── README.md # Usage documentation +├── hardware/ +│ ├── generic.nix # Desktop workstation template +│ ├── laptop.nix # Laptop with power management +│ └── arm64.nix # Raspberry Pi / ARM boards +├── modules/ +│ ├── networking.nix # NetworkManager, firewall +│ ├── security.nix # Hardening, PAM, sudo +│ └── virtualization.nix # Docker, Podman, QEMU/KVM +└── home/ + ├── shell.nix # Zsh, Fish, Starship, FZF + ├── neovim.nix # Editor with lazy.nvim + ├── git.nix # Git, GitHub CLI, Lazygit + ├── development.nix # Language configs, linters + └── terminal.nix # Kitty, Tmux, Zellij +``` + +### Preference Extrapolation + +Configurations were derived by analyzing existing dotfiles: + +| Source | Derived NixOS Config | +|--------|---------------------| +| `Brewfile` | System packages, services | +| `mise/config.toml.tmpl` | Language runtimes | +| `dot_zshrc.tmpl`, `aliases.zsh` | Shell configuration, 60+ aliases | +| `nvim/init.lua`, `nvim/lua/` | Neovim plugins and LSP | +| `dot_tmux.conf` | Tmux configuration | +| `starship.toml` | Starship prompt theme | +| `.chezmoidata.toml` | Python tools, MCP servers | + +### Configuration Options + +Three NixOS configurations for different hardware: + +1. **workstation**: Generic desktop with full development setup +2. **laptop**: TLP power management, battery thresholds, touchpad +3. **arm64**: Raspberry Pi and ARM server support + +Plus standalone home-manager for non-NixOS Linux: + +```bash +# NixOS full system +sudo nixos-rebuild switch --flake .#workstation + +# Home Manager only (Ubuntu, Fedora, etc.) +home-manager switch --flake .#lgates@linux +``` + +### Integration Strategies + +Users can choose their integration level: + +**Option A: NixOS-only** (full declarative) +- All configs in Nix +- No chezmoi needed +- Maximum reproducibility + +**Option B: NixOS + Chezmoi hybrid** (recommended) +- NixOS for system + packages +- Chezmoi for dotfiles (symlinked) +- Familiar editing workflow + +**Option C: Home Manager standalone** +- Keep existing distro (Ubuntu, Fedora) +- Use home-manager for user config +- Gradual adoption path + +## Consequences + +### Positive + +1. **Full system reproducibility**: Rebuild identical system from flake +2. **Atomic rollbacks**: `nixos-rebuild switch --rollback` for instant recovery +3. **Unified packages**: All tools declared in one place +4. **Multi-machine**: Same config across desktop, laptop, servers +5. **Preference preservation**: Existing tool choices honored +6. **Modular design**: Pick modules you need + +### Negative + +1. **Learning curve**: Nix language syntax is unique +2. **Linux-only**: NixOS doesn't run on macOS (Darwin support is separate) +3. **Maintenance burden**: Two config systems to maintain +4. **Build times**: Initial system builds can be slow +5. **Disk usage**: Nix store accumulates generations + +### Trade-offs + +| Aspect | chezmoi + mise | NixOS | +|--------|----------------|-------| +| Learning curve | Lower | Higher | +| Cross-platform | macOS + Linux | Linux only | +| Rollback | Manual | Atomic, instant | +| Disk usage | Minimal | ~10-30GB for store | +| Package availability | Homebrew ecosystem | Nixpkgs (80,000+) | +| Configuration style | File templates | Functional (Nix lang) | + +### Migration Path + +1. **Test in VM**: Try NixOS config in QEMU/VirtualBox first +2. **Home Manager first**: Use standalone home-manager on existing distro +3. **Dual boot**: Install NixOS alongside current distro +4. **Full migration**: Replace primary system when comfortable + +## Alternatives Considered + +### Ansible for System Configuration + +**Rejected because**: +- Imperative rather than declarative +- No atomic rollbacks +- Drift between runs possible +- Overkill for personal workstation + +### Ignoring NixOS Users + +**Rejected because**: +- Growing NixOS user base +- Natural fit for declarative dotfiles philosophy +- Requested by users of the dotfiles repo + +### Full Nix Darwin (macOS) + +**Deferred because**: +- Additional complexity +- Homebrew works well on macOS +- Can add later as separate configuration + +### Replace chezmoi with Nix + +**Rejected because**: +- chezmoi works cross-platform +- Familiar to existing users +- Hybrid approach is more flexible + +## Related Decisions + +- **ADR-0001**: Chezmoi exact_ Directory Strategy (atomic updates philosophy shared) +- **ADR-0002**: Unified Tool Version Management with Mise (complementary on traditional Linux) +- **ADR-0007**: Layered Knowledge Distribution (modular config approach) + +## References + +- NixOS Manual: https://nixos.org/manual/nixos/stable/ +- Home Manager: https://nix-community.github.io/home-manager/ +- Nix Flakes: https://nixos.wiki/wiki/Flakes +- Configuration: `nixos/` directory +- Usage guide: `nixos/README.md` diff --git a/docs/adrs/README.md b/docs/adrs/README.md new file mode 100644 index 0000000..7b583f9 --- /dev/null +++ b/docs/adrs/README.md @@ -0,0 +1,56 @@ +# Architecture Decision Records + +This directory contains Architecture Decision Records (ADRs) documenting significant technical decisions made in this dotfiles repository. + +## What is an ADR? + +An ADR is a document that captures an important architectural decision made along with its context and consequences. ADRs help future maintainers understand why certain decisions were made. + +## ADR Index + +| ID | Title | Status | Date | +|----|-------|--------|------| +| [0001](0001-chezmoi-exact-directory-strategy.md) | Chezmoi exact_ Directory Strategy | Accepted | 2024-12 | +| [0002](0002-unified-tool-version-management-mise.md) | Unified Tool Version Management with Mise | Accepted | 2024-12 | +| [0003](0003-skill-activation-trigger-keywords.md) | Skill Activation via Trigger Keywords | Accepted | 2024-12 | +| [0004](0004-subagent-first-delegation-strategy.md) | Subagent-First Delegation Strategy | Accepted | 2024-12 | +| [0005](0005-namespace-based-command-organization.md) | Namespace-Based Command Organization | Accepted | 2024-12 | +| [0006](0006-documentation-first-development.md) | Documentation-First Development | Accepted | 2024-12 | +| [0007](0007-layered-knowledge-distribution.md) | Layered Knowledge Distribution | Accepted | 2024-12 | +| [0008](0008-project-scoped-mcp-servers.md) | Project-Scoped MCP Servers | Accepted | 2024-12 | +| [0009](0009-conventional-commits-release-please.md) | Conventional Commits + Release-Please | Accepted | 2024-12 | +| [0010](0010-tiered-test-execution.md) | Tiered Test Execution | Accepted | 2024-12 | +| [0011](0011-claude-rules-migration.md) | Claude Rules Migration | Accepted | 2025-12 | +| [0012](0012-justfile-command-runner.md) | Justfile Command Runner | Accepted | 2025-12 | +| [0013](0013-nixos-declarative-system-configuration.md) | NixOS Declarative System Configuration | Accepted | 2025-12 | + +## ADR Format + +Each ADR follows the [Michael Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions): + +```markdown +# ADR-NNNN: Title + +## Status +[Proposed | Accepted | Deprecated | Superseded] + +## Date +YYYY-MM + +## Context +What is the issue motivating this decision? + +## Decision +What is the change being proposed/made? + +## Consequences +What are the positive and negative results? +``` + +## Creating a New ADR + +1. Copy the template from an existing ADR +2. Number sequentially (0003, 0004, etc.) +3. Use lowercase-kebab-case for filenames +4. Update this README's index table +5. Link related ADRs in the "Related Decisions" section diff --git a/docs/blueprint/README.md b/docs/blueprint/README.md new file mode 100644 index 0000000..5eb5075 --- /dev/null +++ b/docs/blueprint/README.md @@ -0,0 +1,29 @@ +# Blueprint Documentation + +Blueprint development structure for this project. + +## Contents + +- `manifest.json` — Blueprint configuration and task registry (v3.2.0) +- `work-orders/` — Detailed work order documents +- `ai_docs/` — AI-curated documentation + +## Related Directories + +- `docs/prds/` — Product Requirements Documents +- `docs/adrs/` — Architecture Decision Records +- `docs/prps/` — Product Requirement Prompts +- `.claude/rules/` — Generated and custom rules + +## Commands + +```bash +/blueprint:status # Check configuration and task health +/blueprint:derive-prd # Generate PRD from existing docs/codebase +/blueprint:derive-plans # Derive docs from git history +/blueprint:derive-rules # Generate rules from git patterns +/blueprint:generate-rules # Generate rules from PRDs +/blueprint:adr-validate # Validate ADR relationships +/blueprint:sync-ids # Assign IDs to documents +/blueprint:execute # Run next logical action +``` diff --git a/docs/blueprint/manifest.json b/docs/blueprint/manifest.json new file mode 100644 index 0000000..5b295ab --- /dev/null +++ b/docs/blueprint/manifest.json @@ -0,0 +1,114 @@ +{ + "format_version": "3.2.0", + "created_at": "2026-04-07T00:00:00Z", + "updated_at": "2026-04-07T00:00:00Z", + "created_by": { + "blueprint_plugin": "3.2.0" + }, + "project": { + "name": "chezmoi", + "detected_stack": ["zsh", "lua", "shell", "mise", "chezmoi", "neovim"] + }, + "structure": { + "has_prds": true, + "has_adrs": true, + "has_prps": true, + "has_work_orders": true, + "has_ai_docs": false, + "has_modular_rules": true, + "has_feature_tracker": false, + "has_document_detection": true, + "claude_md_mode": "both" + }, + "generated": { + "rules": {}, + "commands": {} + }, + "custom_overrides": { + "skills": [], + "commands": [] + }, + "task_registry": { + "derive-prd": { + "enabled": true, + "auto_run": false, + "last_completed_at": null, + "last_result": null, + "schedule": "on-demand", + "stats": {}, + "context": {} + }, + "derive-plans": { + "enabled": true, + "auto_run": false, + "last_completed_at": null, + "last_result": null, + "schedule": "weekly", + "stats": {}, + "context": {} + }, + "derive-rules": { + "enabled": true, + "auto_run": false, + "last_completed_at": null, + "last_result": null, + "schedule": "weekly", + "stats": {}, + "context": {} + }, + "generate-rules": { + "enabled": true, + "auto_run": false, + "last_completed_at": null, + "last_result": null, + "schedule": "on-change", + "stats": {}, + "context": {} + }, + "adr-validate": { + "enabled": true, + "auto_run": false, + "last_completed_at": null, + "last_result": null, + "schedule": "weekly", + "stats": {}, + "context": {} + }, + "feature-tracker-sync": { + "enabled": false, + "auto_run": false, + "last_completed_at": null, + "last_result": null, + "schedule": "daily", + "stats": {}, + "context": {} + }, + "sync-ids": { + "enabled": true, + "auto_run": false, + "last_completed_at": null, + "last_result": null, + "schedule": "on-change", + "stats": {}, + "context": {} + }, + "claude-md": { + "enabled": true, + "auto_run": false, + "last_completed_at": null, + "last_result": null, + "schedule": "on-change", + "stats": {}, + "context": {} + }, + "curate-docs": { + "enabled": false, + "auto_run": false, + "last_completed_at": null, + "last_result": null, + "schedule": "on-demand", + "stats": {}, + "context": {} + } + } +} diff --git a/exact_dot_claude/rules/development.md b/exact_dot_claude/rules/development.md new file mode 100644 index 0000000..5d71d82 --- /dev/null +++ b/exact_dot_claude/rules/development.md @@ -0,0 +1,23 @@ +# Development Workflow + +## TDD Workflow + +Follow RED → GREEN → REFACTOR: +1. Write a failing test +2. Implement minimal code to pass +3. Refactor while keeping tests green + +## Commit Conventions + +Use conventional commits: `type(scope): description` + +Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `style` + +Common scopes: `zsh`, `nvim`, `mise`, `chezmoi`, `claude`, `brew`, `scripts` + +## Chezmoi Workflow + +- Always edit source files in `~/.local/share/chezmoi/`, never target files directly +- Run `chezmoi diff` before `chezmoi apply` to review changes +- Use `chezmoi apply --dry-run` to preview without applying +- After modifying `exact_dot_claude/rules/`, run `chezmoi apply -v ~/.claude` to sync diff --git a/exact_dot_claude/rules/document-management.md b/exact_dot_claude/rules/document-management.md new file mode 100644 index 0000000..456eda5 --- /dev/null +++ b/exact_dot_claude/rules/document-management.md @@ -0,0 +1,31 @@ +# Document Management + +## Decision Detection + +Watch for these patterns during conversations and prompt to create formal documents: + +**Architecture decisions** (→ create ADR in `docs/adrs/`): +- Choosing between tools, approaches, or patterns +- Deciding on configuration strategies +- Selecting package managers or version managers +- Making cross-platform compatibility choices + +**Feature requirements** (→ create/update PRD in `docs/prds/`): +- Discussing new dotfiles features or capabilities +- Defining desired shell behaviors or integrations +- Planning new tool configurations + +**Implementation plans** (→ create PRP in `docs/prps/`): +- Detailed plans for implementing a new tool setup +- Migration strategies between tools +- Complex configuration refactoring + +## Document Locations + +- PRDs: `docs/prds/` — what and why +- ADRs: `docs/adrs/` — architecture decisions with context and trade-offs +- PRPs: `docs/prps/` — how to implement + +## ADR Naming + +`docs/adrs/NNNN-kebab-case-title.md` — use next sequential number. diff --git a/exact_dot_claude/rules/testing.md b/exact_dot_claude/rules/testing.md new file mode 100644 index 0000000..8b646e9 --- /dev/null +++ b/exact_dot_claude/rules/testing.md @@ -0,0 +1,25 @@ +# Testing Requirements + +## Test Tiers + +| Tier | Command | When | +|------|---------|------| +| Lint | `mise run lint` or `just lint` | After every change | +| Shell | `mise run lint:shell` | After modifying shell scripts | +| Lua | `mise run lint:lua` | After modifying Neovim config | +| Actions | `mise run lint:actions` | After modifying workflows | +| Full | `mise run test` | Before committing | +| Docker | `mise run test:docker` | For environment changes | + +## Linting Standards + +- Shell scripts: shellcheck with `.shellcheckrc` config +- Lua (Neovim): luacheck with `.luacheckrc` config +- GitHub Actions: actionlint +- Lua formatting: stylua with `.stylua.toml` +- Secrets: gitleaks with `.gitleaks.toml` +- Pre-commit: `pre-commit run --all-files` + +## Coverage Expectations + +Shell scripts and config files — focus on linting compliance and smoke test passing rather than unit coverage. From afaec005957568bd34ddb0ffd2daa7b4a98a70c8 Mon Sep 17 00:00:00 2001 From: Lauri Gates Date: Wed, 8 Apr 2026 09:04:49 +0300 Subject: [PATCH 2/5] docs: derive PRD-001 and complete ADR migration - Generate project-overview PRD from README, CLAUDE.md, and components docs - Remove old docs/adr/ directory (files already in docs/adrs/ from previous commit) - Update manifest with PRD-001 entry and ID registry Co-Authored-By: Claude Opus 4.6 (1M context) --- .../0001-chezmoi-exact-directory-strategy.md | 159 ----------- ...02-unified-tool-version-management-mise.md | 236 ---------------- .../0003-skill-activation-trigger-keywords.md | 187 ------------- ...0004-subagent-first-delegation-strategy.md | 203 -------------- ...05-namespace-based-command-organization.md | 229 --------------- .../0006-documentation-first-development.md | 218 --------------- .../0007-layered-knowledge-distribution.md | 213 -------------- docs/adr/0008-project-scoped-mcp-servers.md | 231 --------------- ...009-conventional-commits-release-please.md | 251 ----------------- docs/adr/0010-tiered-test-execution.md | 262 ------------------ docs/adr/0011-claude-rules-migration.md | 151 ---------- docs/adr/0012-justfile-command-runner.md | 252 ----------------- ...-nixos-declarative-system-configuration.md | 240 ---------------- docs/adr/README.md | 56 ---- docs/blueprint/manifest.json | 30 +- docs/prds/project-overview.md | 166 +++++++++++ 16 files changed, 192 insertions(+), 2892 deletions(-) delete mode 100644 docs/adr/0001-chezmoi-exact-directory-strategy.md delete mode 100644 docs/adr/0002-unified-tool-version-management-mise.md delete mode 100644 docs/adr/0003-skill-activation-trigger-keywords.md delete mode 100644 docs/adr/0004-subagent-first-delegation-strategy.md delete mode 100644 docs/adr/0005-namespace-based-command-organization.md delete mode 100644 docs/adr/0006-documentation-first-development.md delete mode 100644 docs/adr/0007-layered-knowledge-distribution.md delete mode 100644 docs/adr/0008-project-scoped-mcp-servers.md delete mode 100644 docs/adr/0009-conventional-commits-release-please.md delete mode 100644 docs/adr/0010-tiered-test-execution.md delete mode 100644 docs/adr/0011-claude-rules-migration.md delete mode 100644 docs/adr/0012-justfile-command-runner.md delete mode 100644 docs/adr/0013-nixos-declarative-system-configuration.md delete mode 100644 docs/adr/README.md create mode 100644 docs/prds/project-overview.md diff --git a/docs/adr/0001-chezmoi-exact-directory-strategy.md b/docs/adr/0001-chezmoi-exact-directory-strategy.md deleted file mode 100644 index 53490a0..0000000 --- a/docs/adr/0001-chezmoi-exact-directory-strategy.md +++ /dev/null @@ -1,159 +0,0 @@ -# ADR-0001: Chezmoi exact_ Directory Strategy for Claude Code Configuration - -## Status - -Accepted - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -The `.claude` directory contains Claude Code's configuration including: -- **103+ skills** - Auto-discovered capabilities with YAML frontmatter -- **76 slash commands** - Organized across 14 namespaces -- **22 specialized agents** - Domain-specific task handlers -- **Settings and scripts** - Runtime configuration - -This directory is managed by chezmoi (dotfiles manager) but also actively used by Claude Code processes during runtime. Two competing approaches existed: - -### Option A: Symlink Strategy -Use chezmoi's `symlink_` prefix to create symbolic links from `~/.claude` to the source directory. - -**Pros:** -- Changes immediately visible without `chezmoi apply` -- Single source of truth (source directory) -- Simpler mental model - -**Cons:** -- **Race conditions**: Claude Code processes accessing files during modifications/renames caused corruption -- **Partial states**: Mid-edit files visible to running processes -- **No atomic updates**: Changes applied incrementally, not atomically - -### Option B: exact_ Directory Strategy -Use chezmoi's `exact_` prefix (`exact_dot_claude/`) to copy files with automatic cleanup of orphaned entries. - -**Pros:** -- **Atomic updates**: `chezmoi apply` provides explicit checkpoints -- **Process stability**: Running Claude processes unaffected until apply -- **Auto-cleanup**: Deleted/renamed skills automatically removed (like Neovim plugins with lazy.nvim) -- **Predictable state**: Target always matches source exactly after apply - -**Cons:** -- Requires explicit `chezmoi apply` after changes -- Two locations (source vs target) can cause confusion - -### The Race Condition Problem - -With symlinks, we observed: -1. User edits skill file in source directory -2. Claude Code process reads partially-written file mid-save -3. YAML frontmatter parsing fails or returns incomplete data -4. Skill activation becomes unpredictable - -This was particularly problematic because: -- Skills activate based on description matching user queries -- Corrupted descriptions = missed activations -- Multiple Claude sessions could run simultaneously - -### Runtime Directory Challenge - -Claude Code creates runtime directories that should NOT be managed: -- `projects/` - Project-specific state -- `session-env/` - Session environment data -- `shell-snapshots/` - Shell state snapshots -- `plans/` - Plan mode state - -These must persist across `chezmoi apply` operations. - -## Decision - -**Use the `exact_` prefix strategy** with runtime directory preservation via `.chezmoiignore`. - -### Implementation - -1. **Source directory**: `~/.local/share/chezmoi/exact_dot_claude/` -2. **Target directory**: `~/.claude` (managed atomically) -3. **Runtime preservation**: `exact_dot_claude/.chezmoiignore` excludes runtime directories - -``` -# exact_dot_claude/.chezmoiignore -plans/ -projects/ -session-env/ -shell-snapshots/ -settings.local.json -``` - -### Workflow - -```bash -# Edit skills/commands in source directory -vim ~/.local/share/chezmoi/exact_dot_claude/skills/my-skill/SKILL.md - -# Apply atomically when ready -chezmoi apply -v ~/.claude - -# Or use convenience alias -alias ca-claude='chezmoi apply -v ~/.claude' -``` - -### Why exact_ Instead of Regular Copy - -The `exact_` prefix tells chezmoi to: -1. Remove files in target that don't exist in source -2. Ensure target matches source exactly -3. Delete orphaned skills/commands automatically - -Without `exact_`, renamed or deleted skills would persist as orphans. - -## Consequences - -### Positive - -1. **Eliminated race conditions** - Running Claude processes see consistent state -2. **Explicit checkpoints** - Changes only visible after deliberate `chezmoi apply` -3. **Automatic cleanup** - No manual removal of old skills needed -4. **Predictable behavior** - Skills either fully present or absent, never partial -5. **Safe experimentation** - Edit source without affecting running sessions - -### Negative - -1. **Two-step workflow** - Must remember to run `chezmoi apply` -2. **Potential for drift** - Source and target can diverge until apply -3. **Learning curve** - New contributors must understand the pattern - -### Mitigations - -- **Alias convenience**: `ca-claude` for quick application -- **Documentation**: Clear CLAUDE.md instructions at repository root -- **Git hooks**: Could add pre-commit hook to warn of unapplied changes (not implemented) - -## Alternatives Considered - -### Git Worktree -Use git worktree to have source directory be the actual `.claude` directory. - -**Rejected because**: Still doesn't solve atomicity; introduces git complexity. - -### inotify/fswatch Auto-Apply -Watch source directory and auto-apply on changes. - -**Rejected because**: Defeats the purpose of explicit checkpoints; could apply mid-edit. - -### Containerized Claude Code -Run Claude Code in container with mounted config. - -**Rejected because**: Overkill for this problem; introduces deployment complexity. - -## Related Decisions - -- ADR-0002: Unified Tool Version Management with Mise (shared philosophy of explicit state management) -- Skills activation via trigger keywords (depends on reliable skill file integrity) - -## References - -- chezmoi documentation: https://www.chezmoi.io/reference/source-state-attributes/ -- `exact_dot_claude/CLAUDE.md` - Directory management documentation -- `exact_dot_claude/.chezmoiignore` - Runtime directory exclusions diff --git a/docs/adr/0002-unified-tool-version-management-mise.md b/docs/adr/0002-unified-tool-version-management-mise.md deleted file mode 100644 index c19cac0..0000000 --- a/docs/adr/0002-unified-tool-version-management-mise.md +++ /dev/null @@ -1,236 +0,0 @@ -# ADR-0002: Unified Tool Version Management with Mise - -## Status - -Accepted (Migration In Progress) - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -The dotfiles repository manages a complex development environment spanning multiple languages and tool ecosystems: - -### The Tool Sprawl Problem - -**Before mise**, tools were managed by multiple package managers: - -| Tool Type | Package Manager | Config Location | -|-----------|-----------------|-----------------| -| System utilities | Homebrew | `Brewfile` | -| Python runtimes | Homebrew | `Brewfile` | -| Python CLI tools | uv (pipx-style) | `.chezmoidata.toml` | -| Node.js runtime | nvm/Homebrew | Various | -| Rust tools | cargo | `dot_default-cargo-packages` | -| Go tools | go install | Manual | -| Kubernetes tools | Homebrew | `Brewfile` | - -**Problems with multi-manager approach:** - -1. **Version inconsistency**: `brew install kubectl` on different days = different versions -2. **No lockfile**: No way to pin exact tool versions across machines -3. **Slow installations**: `cargo install bat` compiles from source (5+ minutes) -4. **Context switching**: Different commands for different tool types -5. **CI/local drift**: CI might use different tool versions than local -6. **Security gaps**: Homebrew only provides SHA256 checksums - -### Tool Categories Analysis - -We identified distinct tool categories with different requirements: - -**Bootstrap Tools** (must exist before anything else): -- chezmoi, git, fish, mise itself - -**Language Runtimes** (need version switching per-project): -- Python 3.11/3.13, Node.js, Go, Rust, Bun - -**Python CLI Tools** (Python-based utilities): -- ruff, ansible, pre-commit, glances, etc. - -**System CLI Tools** (standalone binaries): -- kubectl, helm, terraform, ripgrep, fd, bat, jq, etc. - -**GUI Applications** (macOS/Linux desktop apps): -- Ghostty, Obsidian, VS Code (Homebrew casks) - -**Services/Daemons** (background processes): -- PostgreSQL, Mosquitto, Ollama - -### Mise Capabilities - -[mise](https://mise.jdx.dev/) (formerly rtx) provides: - -1. **Unified interface**: Single command for all tool types -2. **Multiple backends**: - - Core: Language runtimes (python, node, go, rust) - - `pipx:`: Python tools via uvx (fast!) - - `aqua:`: CLI tools with security attestations - - `npm:`, `cargo:`: Ecosystem-specific tools -3. **Lockfile**: `mise.lock` for reproducible builds -4. **Per-directory versions**: Auto-switch based on `.mise.toml` -5. **Task runner**: Replace Makefile with cross-platform tasks -6. **Security**: aqua backend provides checksums + SLSA provenance + Cosign signatures - -## Decision - -**Adopt mise as the primary tool version manager** while keeping Homebrew for bootstrap tools, GUI apps, and services. - -### Tool Distribution Strategy - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Tool Management Strategy │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ Homebrew (Brewfile) mise (config.toml.tmpl) │ -│ ───────────────────── ──────────────────────── │ -│ • Bootstrap: chezmoi, • Runtimes: python, node, │ -│ git, fish, uv, mise go, rust, bun │ -│ • GUI Apps: casks • Python tools: pipx:ruff, │ -│ • Services: postgresql, pipx:ansible, etc. │ -│ mosquitto • CLI tools: aqua:kubectl, │ -│ • Platform-specific: aqua:helm, aqua:terraform │ -│ lldpd, mas • Search: aqua:ripgrep, │ -│ • Build tools: cmake, aqua:fd, aqua:bat │ -│ ninja, autoconf • Git tools: aqua:lazygit, │ -│ aqua:gh, aqua:delta │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` - -### Configuration Structure - -**Primary config**: `private_dot_config/mise/config.toml.tmpl` - -```toml -# Runtimes -[tools] -python = ["3.11", "3.13"] -node = "latest" -go = "1.23" -rust = "stable" -bun = "latest" - -# Python tools (uses uvx automatically when uv installed) -"pipx:ruff" = "latest" -"pipx:ansible" = "latest" -"pipx:pre-commit" = "latest" - -# CLI tools with security verification -"aqua:kubernetes/kubectl" = "latest" -"aqua:helm/helm" = "latest" -"aqua:hashicorp/terraform" = "latest" -"aqua:BurntSushi/ripgrep" = "latest" -``` - -### Backend Selection Criteria - -| Backend | Use When | Security | -|---------|----------|----------| -| Core | Language runtimes | Standard | -| `pipx:` | Python CLI tools | Via uv | -| `aqua:` | Standalone binaries | Checksums + SLSA + Cosign | -| `npm:` | Node.js tools | Via npm | -| `cargo:` | Must compile from source | Standard | - -### Task Runner Migration - -Replace Makefile with mise tasks: - -```toml -[tasks.lint] -description = "Run all linters" -run = "shellcheck **/*.sh && luacheck nvim/lua && actionlint" - -[tasks.update] -description = "Update all tools" -depends = ["update:brew", "update:mise", "update:nvim"] -``` - -**Command mapping**: -- `make lint` → `mise run lint` -- `make update` → `mise run update` -- `make setup` → `mise run setup` - -## Consequences - -### Positive - -1. **Reproducible environments**: `mise.lock` ensures identical versions -2. **Faster installations**: aqua uses pre-built binaries (seconds vs minutes) -3. **Enhanced security**: aqua provides SLSA provenance and attestations -4. **Automatic version switching**: Per-project `.mise.toml` files -5. **Unified interface**: Single tool for runtimes + CLI tools + tasks -6. **Cross-platform tasks**: TOML-based tasks work on macOS/Linux/Windows - -### Negative - -1. **Migration complexity**: Gradual transition from existing tools -2. **Learning curve**: Team must learn mise commands -3. **Dual management**: Homebrew still needed for some categories -4. **Trust requirement**: Must trust `.mise.toml` files in new directories - -### Migration Path - -**Phase 1** (Complete): Create mise config alongside existing tools -**Phase 2** (In Progress): Install tools via mise, verify functionality -**Phase 3** (Planned): Remove duplicates from Homebrew -**Phase 4** (Future): Deprecate legacy tool configs - -### Packages Migrated to mise - -| Category | Count | Examples | -|----------|-------|----------| -| Python tools | 18 | ruff, ansible, pre-commit | -| Kubernetes | 6 | kubectl, helm, argocd, k9s | -| Search tools | 5 | ripgrep, fd, bat, lsd, delta | -| Infrastructure | 2 | terraform, skaffold | -| Data processing | 2 | jq, yq | -| Other CLI | 4 | gh, lazygit, zoxide, atuin | - -**Total**: ~37 tools migrated from Homebrew/cargo/manual - -### Packages Remaining in Homebrew - -- **Bootstrap**: chezmoi, git, fish, uv, mise -- **Build tools**: cmake, ninja, autoconf -- **GUI apps**: All casks -- **Services**: postgresql, mosquitto, ollama -- **Platform-specific**: lldpd (macOS), mas (macOS) -- **Specialized**: arduino-cli, platformio, wireshark - -## Alternatives Considered - -### asdf -The original polyglot version manager. - -**Rejected because**: Slower than mise, less active development, no built-in task runner. - -### nix/home-manager -Declarative system configuration. - -**Rejected because**: Steeper learning curve, overkill for tool versions, less portable. - -### Keep Multi-Manager Approach -Continue with Homebrew + uv + cargo + manual. - -**Rejected because**: No reproducibility, version drift, slow installations. - -### devbox -Nix-based development environments. - -**Rejected because**: Requires Nix understanding, less flexible backends. - -## Related Decisions - -- ADR-0001: Chezmoi exact_ Directory Strategy (shared philosophy of explicit state) -- Homebrew for bootstrap tools (mise depends on Homebrew-installed mise) - -## References - -- mise documentation: https://mise.jdx.dev/ -- aqua registry: https://github.com/aquaproj/aqua-registry -- Migration guide: `docs/mise-migration-guide.md` -- Analysis: `docs/homebrew-mise-migration-analysis.md` -- Configuration: `private_dot_config/mise/config.toml.tmpl` diff --git a/docs/adr/0003-skill-activation-trigger-keywords.md b/docs/adr/0003-skill-activation-trigger-keywords.md deleted file mode 100644 index 843e425..0000000 --- a/docs/adr/0003-skill-activation-trigger-keywords.md +++ /dev/null @@ -1,187 +0,0 @@ -# ADR-0003: Skill Activation via Trigger Keywords - -## Status - -Accepted - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -The dotfiles repository contains **103+ skills** - modular capabilities that extend Claude's functionality through specialized knowledge domains. Skills activate automatically when Claude determines they're relevant to the user's request. - -### The Discovery Problem - -Skills are discovered from the `~/.claude/skills/` directory, but **only metadata is pre-loaded** at startup: - -```yaml ---- -name: skill-identifier -description: What this does and when to use it ---- -``` - -Claude sees only the `name` and `description` fields (~100 tokens) when deciding whether to load a skill. The full `SKILL.md` content (often 200-500 lines) is only loaded if the skill is activated. - -This creates a **discovery bottleneck**: If the description doesn't match user language, the skill never activates. - -### Measured Activation Rates - -Through experimentation, we measured activation rates across different description approaches: - -| Approach | Activation Rate | Example | -|----------|-----------------|---------| -| Basic description | ~20% | "Helps with documents" | -| Specific capabilities | ~35% | "Extract text from PDFs and process documents" | -| Trigger keywords | ~50% | Includes tool names like "PyPDF2", "pdfplumber" | -| Explicit "Use when..." | ~70% | "Use when user mentions PDFs, forms, extraction" | -| Forced evaluation hooks | ~84% | System-level skill evaluation triggers | - -### The Vocabulary Mismatch - -Users don't speak in technical abstractions. They say: -- "Help me with my dotfiles" (not "configuration file management") -- "Search for TODOs in the code" (not "perform regex pattern matching") -- "Fix my pytest tests" (not "resolve Python testing framework issues") - -Skills with generic descriptions like "helps with configuration" fail to match user vocabulary. - -### Scale Challenge - -With 100+ skills, disambiguation becomes critical: -- Multiple skills could reasonably match a query -- Generic descriptions cause activation conflicts -- Users can't discover skills they don't know exist - -## Decision - -**Adopt explicit trigger keyword patterns** with "Use when..." clauses in all skill descriptions. - -### Description Formula - -``` -[What it does in 1-2 sentences] + [Specific domain terms] + "Use when [explicit triggers]." -``` - -### Implementation Pattern - -**Before (20% activation):** -```yaml -description: Helps with Python testing -``` - -**After (70% activation):** -```yaml -description: | - Core Python development concepts, idioms, best practices, and language features. - Covers Python 3.10+ features, type hints, async/await, and Pythonic patterns. - For running scripts, see uv-run. For project setup, see uv-project-management. - Use when user mentions Python, type hints, async Python, decorators, context managers, - or writing Pythonic code. -``` - -### Trigger Keyword Categories - -1. **Tool names**: `pytest`, `uv`, `ripgrep`, `chezmoi` -2. **File extensions**: `.py`, `.toml`, `.yml` -3. **Config files**: `pyproject.toml`, `.chezmoiignore` -4. **Action verbs**: "search", "find", "deploy", "test" -5. **Domain terms**: "dotfiles", "cross-platform", "container" - -### Real Examples from Repository - -**chezmoi-expert skill:** -```yaml -description: | - Comprehensive chezmoi dotfiles management expertise including templates, cross-platform - configuration, file naming conventions, and troubleshooting. Covers source directory - management, reproducible environment setup, and chezmoi templating with Go templates. - Use when user mentions chezmoi, dotfiles, cross-platform config, chezmoi apply, - chezmoi diff, .chezmoidata, or managing configuration files across machines. -``` - -**rg-code-search skill:** -```yaml -description: Fast code search using ripgrep (rg) with smart defaults, regex patterns, - and file filtering. Use when searching for text patterns, code snippets, or performing - multi-file code analysis. -``` - -### Documentation Requirements - -All skills must include: -1. **YAML frontmatter** with `name` and `description` fields -2. **Description under 1024 characters** but specific enough to disambiguate -3. **"Use when..." clause** with concrete trigger scenarios -4. **Third person perspective** ("Extracts..." not "I extract...") - -## Consequences - -### Positive - -1. **3.5x activation improvement** - From ~20% to ~70% with proper descriptions -2. **Predictable behavior** - Clear mapping between user language and skill activation -3. **Self-documenting** - "Use when" clauses serve as usage documentation -4. **Conflict reduction** - Specific triggers reduce multi-skill ambiguity -5. **Discoverability** - Users can infer skill existence from natural language - -### Negative - -1. **Maintenance burden** - Must update triggers as user vocabulary evolves -2. **Description bloat** - Comprehensive descriptions approach 1024 char limit -3. **False positives** - Overly broad triggers may activate inappropriate skills -4. **Manual process** - No automated validation of activation patterns - -### Skill Writing Checklist - -For each new skill: -- [ ] YAML frontmatter present with `name` and `description` -- [ ] Description answers: What does it do? When should Claude use it? -- [ ] Trigger keywords match user language (not technical jargon) -- [ ] "Use when..." clause explicitly states activation scenarios -- [ ] Third person perspective throughout -- [ ] Under 1024 characters but specific enough - -### Metrics Tracking - -Skills documentation tracks: -- Total skills: 100+ -- YAML frontmatter compliance: 100% -- "Use when" clause adoption: Target 100% - -## Alternatives Considered - -### Semantic Matching -Use embedding-based similarity between user query and skill descriptions. - -**Rejected because**: Would require infrastructure changes to Claude Code; current keyword approach achieves acceptable activation rates. - -### Skill Categories/Tags -Organize skills into categories that users explicitly select. - -**Rejected because**: Adds friction; users shouldn't need to know skill taxonomy. - -### System Hooks for Forced Evaluation -Use Claude Code hooks to force skill evaluation on every request. - -**Partially adopted**: Hooks achieve 84% activation but add latency; reserved for critical skills. - -### Skill Aliases -Multiple names/descriptions pointing to same skill. - -**Not implemented**: Would increase maintenance burden; single well-written description preferred. - -## Related Decisions - -- ADR-0001: Chezmoi exact_ Directory Strategy (skills depend on file integrity) -- ADR-0004: Subagent-First Delegation Strategy (skills inform agent selection) -- ADR-0005: Namespace-Based Command Organization (commands vs skills distinction) - -## References - -- Skills directory: `exact_dot_claude/skills/` -- Skills documentation: `exact_dot_claude/skills/CLAUDE.md` -- External analysis: [Making Skills Activate Reliably](https://scottspence.com/posts/how-to-make-claude-code-skills-activate-reliably) -- Anthropic skills guide: https://code.claude.com/docs/en/skills diff --git a/docs/adr/0004-subagent-first-delegation-strategy.md b/docs/adr/0004-subagent-first-delegation-strategy.md deleted file mode 100644 index 1814885..0000000 --- a/docs/adr/0004-subagent-first-delegation-strategy.md +++ /dev/null @@ -1,203 +0,0 @@ -# ADR-0004: Subagent-First Delegation Strategy - -## Status - -Accepted - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -Claude Code supports **subagents** - specialized agents that can be spawned to handle specific tasks. The dotfiles repository defines 22+ specialized agents for different domains: - -- `Explore` - Code exploration and research -- `code-review` - Quality, security, performance analysis -- `test-runner` - Test execution and failure analysis -- `security-audit` - OWASP analysis and vulnerability assessment -- `system-debugging` - Root cause analysis -- `documentation` - Generate docs from code -- `cicd-pipelines` - GitHub Actions and deployment -- `code-refactoring` - Quality improvements, SOLID principles -- And 14+ more specialized agents - -### The Quality Problem - -When Claude handles complex tasks directly (without delegation), several issues emerge: - -1. **Context overload** - Long conversations accumulate context, reducing response quality -2. **Inconsistent methodology** - Ad-hoc approaches to systematic tasks -3. **Missed edge cases** - Without specialized expertise, subtle issues escape notice -4. **No validation** - Single-pass execution without expert review - -### Subagent Advantages - -Subagents provide: - -1. **Specialized expertise** - Each agent has domain-specific knowledge -2. **Systematic investigation** - Agents follow consistent methodologies -3. **Fresh context** - New agents start with clean context -4. **Parallel execution** - Independent tasks run simultaneously -5. **Expert validation** - Specialized review catches domain-specific issues - -### The Over-Engineering Risk - -However, delegation has costs: -- **Latency** - Spawning agents takes time -- **Coordination overhead** - Managing multiple agents adds complexity -- **Simple task bloat** - Trivial edits don't need specialized agents - -The challenge: **When should Claude delegate vs. handle directly?** - -## Decision - -**Default to subagent delegation** for any task matching specialized domains, with explicit exceptions for trivial operations. - -### Decision Framework - -``` -Task received -├─ Can it be split into independent subtasks? -│ └─ YES → Identify subtasks, launch multiple agents in parallel -├─ Is it code exploration/research? -│ └─ YES → Use Explore agent -├─ Does it match a specialized domain? -│ └─ YES → Use domain-specific agent -├─ Is it multi-step or complex? -│ └─ YES → Use general-purpose agent or appropriate specialist -├─ Is it a trivial single-file edit? -│ └─ YES → Use direct tools (state reasoning) -└─ When in doubt → Delegate to agent -``` - -### When to Delegate (Default) - -| Task Type | Agent | Why Delegate | -|-----------|-------|--------------| -| Code exploration | `Explore` | Systematic codebase navigation | -| Security review | `security-audit` | OWASP expertise, vulnerability patterns | -| Code review | `code-review` | Quality, security, performance analysis | -| Complex debugging | `system-debugging` | Root cause analysis methodology | -| Documentation | `documentation` | Comprehensive doc generation | -| Test execution | `test-runner` | Failure analysis, concise reporting | -| Test strategy | `test-architecture` | Coverage analysis, framework selection | -| CI/CD work | `cicd-pipelines` | GitHub Actions expertise | -| Refactoring | `code-refactoring` | SOLID principles, quality patterns | - -### When to Handle Directly (Exceptions) - -Only handle directly when ALL conditions are met: - -1. **Single file** - Edit confined to one file -2. **Crystal clear** - Requirements unambiguous -3. **Trivial scope** - Would take longer to explain than execute -4. **No domain expertise needed** - Generic text/code changes - -**Examples of direct handling:** -- "Change variable name X to Y in this file" -- "Fix typo in README line 42" -- "Add this import statement" - -**Counter-examples (should delegate):** -- "Find where error handling is implemented" → `Explore` agent -- "Review this code for security issues" → `security-audit` agent -- "This code is broken, help me fix it" → `system-debugging` agent - -### Parallel Execution - -When tasks are independent, launch multiple agents simultaneously: - -``` -"Review code and run tests" - → Launch code-review + test-runner simultaneously - -"Check security and update docs" - → Launch security-audit + documentation simultaneously - -"Explore auth flow and find API usages" - → Launch multiple Explore agents with different queries -``` - -### Reasoning Transparency - -When handling directly (exception case), explicitly state reasoning: - -> "I'll handle this directly because it's a single-line typo fix in a known file. Delegating would add unnecessary overhead for this trivial change." - -## Consequences - -### Positive - -1. **Consistent quality** - Specialized agents apply domain best practices -2. **Reduced errors** - Expert validation catches domain-specific issues -3. **Parallel throughput** - Independent tasks complete simultaneously -4. **Fresh context** - Agents avoid context pollution from long conversations -5. **Systematic approach** - Agents follow established methodologies -6. **Traceable decisions** - Explicit reasoning when not delegating - -### Negative - -1. **Latency overhead** - Agent spawning takes 1-3 seconds -2. **Coordination complexity** - Must track multiple agent results -3. **Potential over-delegation** - Trivial tasks routed to agents -4. **Learning curve** - Users may not understand agent selection - -### Agent Selection Quick Reference - -| User Says | Agent to Use | -|-----------|--------------| -| "Find...", "Where is...", "How does X work?" | `Explore` | -| "Review this code", "Check quality" | `code-review` | -| "Is this secure?", "Check for vulnerabilities" | `security-audit` | -| "Run the tests", "Why are tests failing?" | `test-runner` | -| "Help me debug", "This is broken" | `system-debugging` | -| "Generate docs", "Document this" | `documentation` | -| "Refactor this", "Improve code quality" | `code-refactoring` | -| "Set up CI", "Fix the workflow" | `cicd-pipelines` | - -### Tiered Test Execution Integration - -Testing follows a tiered model with agent mapping: - -| Tier | Duration | Agent | When | -|------|----------|-------|------| -| Unit | < 30s | `test-runner` | After every change | -| Integration | < 5min | `test-runner` | After feature completion | -| E2E | < 30min | `test-runner` | Before commit/PR | - -Complex test failures escalate to `system-debugging` agent. - -## Alternatives Considered - -### No Delegation (Direct Handling) -Handle all tasks directly without subagents. - -**Rejected because**: Quality degrades with context accumulation; no specialized validation. - -### User-Selected Delegation -Let users explicitly choose when to delegate. - -**Rejected because**: Users shouldn't need to understand agent taxonomy; adds friction. - -### Automatic Complexity Detection -Use heuristics to detect when tasks need delegation. - -**Partially adopted**: Decision framework encodes complexity heuristics, but defaults to delegation. - -### Agent Composition -Create meta-agents that coordinate multiple specialized agents. - -**Future consideration**: Current manual orchestration works; may adopt as patterns stabilize. - -## Related Decisions - -- ADR-0003: Skill Activation via Trigger Keywords (skills inform agent behavior) -- ADR-0005: Namespace-Based Command Organization (commands invoke agents) -- ADR-0001: Chezmoi exact_ Directory Strategy (agent configs managed atomically) - -## References - -- Delegation strategy: `exact_dot_claude/CLAUDE.md` -- Agent definitions: `exact_dot_claude/agents/` -- Test tiers: `exact_dot_claude/CLAUDE.md` (Tiered Test Execution section) diff --git a/docs/adr/0005-namespace-based-command-organization.md b/docs/adr/0005-namespace-based-command-organization.md deleted file mode 100644 index 74cb0a5..0000000 --- a/docs/adr/0005-namespace-based-command-organization.md +++ /dev/null @@ -1,229 +0,0 @@ -# ADR-0005: Namespace-Based Command Organization - -## Status - -Accepted - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -The dotfiles repository contains **76 slash commands** - markdown files that expand into prompts when invoked with the `/` prefix. As the command collection grew, several problems emerged: - -### The Flat Namespace Problem - -Initially, all commands lived in a flat directory: - -``` -.claude/commands/ -├── commit.md -├── review.md -├── test.md -├── deploy.md -├── lint.md -├── fix-pr.md -├── new-project.md -├── ... -└── (76 files) -``` - -**Problems:** - -1. **Name collisions** - Multiple domains want "test", "review", "deploy" -2. **Discoverability** - Users can't find commands they don't know exist -3. **Cognitive load** - 76 flat commands overwhelm mental models -4. **Ambiguous scope** - `review.md` could be code review, PR review, or doc review - -### Command Growth Trajectory - -| Milestone | Commands | Organization | -|-----------|----------|--------------| -| Initial | ~10 | Flat directory | -| 6 months | ~30 | Flat, naming conflicts | -| 12 months | ~50 | Informal prefixes (git-*, test-*) | -| Current | 76+ | Namespace directories | - -### User Discovery Challenge - -Users invoke commands by memory or tab completion. Without organization: -- Can't remember exact command names -- Tab completion shows 76 options -- No logical grouping aids recall -- Related commands not co-located - -### Comparison: Skills vs Commands - -| Aspect | Skills | Commands | -|--------|--------|----------| -| Invocation | Automatic (Claude decides) | Explicit (user types `/`) | -| Discovery | Via description matching | Via `/` prefix + completion | -| Organization | Flat (100+ skills) | Namespaced (14 categories) | -| Naming | Must be globally unique | Scoped to namespace | - -Skills work flat because Claude handles discovery. Commands need namespaces because humans handle discovery. - -## Decision - -**Organize commands into namespace directories** with colon-separated invocation syntax. - -### Namespace Structure - -``` -.claude/commands/ -├── blueprint-*.md # Root-level: Blueprint methodology -├── project-*.md # Root-level: Project operations -├── code/ # Code quality and review -│ ├── antipatterns.md # /code:antipatterns -│ ├── review.md # /code:review -│ └── refactor.md # /code:refactor -├── configure/ # Infrastructure standards -│ ├── all.md # /configure:all -│ ├── linting.md # /configure:linting -│ └── ... # 20+ configuration commands -├── deploy/ # Deployment operations -├── deps/ # Dependency management -├── docs/ # Documentation generation -├── git/ # Git and GitHub operations -├── lint/ # Linting and quality checks -├── meta/ # Claude Code introspection -├── project/ # Project setup/maintenance -├── sync/ # Synchronization tasks -├── test/ # Testing infrastructure -├── tools/ # Tool initialization -└── workflow/ # Development workflows -``` - -### Invocation Syntax - -```bash -# Namespaced command -/namespace:command - -# Root-level command (backward compatibility) -/command - -# With parameters -/namespace:command arg1 --flag arg2 -``` - -### 14 Namespaces Defined - -| Namespace | Purpose | Example Commands | -|-----------|---------|------------------| -| `code` | Code quality, review | `antipatterns`, `review`, `refactor` | -| `configure` | Infrastructure standards | `all`, `linting`, `tests`, `mcp` | -| `deploy` | Deployment operations | `release`, `handoff` | -| `deps` | Dependency management | `install` | -| `docs` | Documentation | `generate`, `sync`, `decommission` | -| `git` | Git/GitHub operations | `commit`, `maintain`, `issues`, `fix-pr` | -| `lint` | Linting checks | `check` | -| `meta` | Claude introspection | `assimilate`, `audit` | -| `project` | Project setup | `new`, `init`, `modernize` | -| `sync` | Synchronization | `github-podio`, `daily` | -| `test` | Testing infrastructure | `quick`, `full`, `consult`, `setup` | -| `tools` | Tool initialization | `vectorcode` | -| `workflow` | Development automation | `dev`, `dev-zen` | -| (root) | Cross-cutting concerns | `delegate`, `blueprint-*`, `project-*` | - -### Naming Conventions - -1. **Use kebab-case**: `fix-pr.md` not `FixPR.md` -2. **Be descriptive**: `fix-pr.md` better than `fix.md` -3. **Avoid redundant namespace**: `git/commit.md` not `git/git-commit.md` -4. **Use verbs**: `review.md`, `deploy.md`, `generate.md` - -### Migration Path - -Legacy commands remain at root level for backward compatibility: -- `/blueprint-*` - Blueprint Development methodology -- `/project-continue` - Project state analysis -- `/project-test-loop` - TDD loop -- `/refactor` - Legacy (prefer `/code:refactor`) - -## Consequences - -### Positive - -1. **Scoped naming** - `test/run.md` and `lint/check.md` don't conflict -2. **Logical grouping** - Related commands co-located -3. **Improved discovery** - Tab complete within namespace -4. **Scalable** - Can grow to 200+ commands without chaos -5. **Self-documenting** - Namespace reveals command purpose -6. **Reduced cognitive load** - 14 namespaces vs 76 flat commands - -### Negative - -1. **Longer invocation** - `/git:commit` vs `/commit` -2. **Learning curve** - Users must learn namespace structure -3. **Migration overhead** - Existing references need updating -4. **Potential namespace sprawl** - Could create too many namespaces - -### Tab Completion Improvement - -**Before (flat):** -``` -/c -→ commit, code-review, configure-all, configure-linting, ... -``` - -**After (namespaced):** -``` -/c -→ code:, configure: - -/configure: -→ all, linting, tests, mcp, ... -``` - -### Command Counts by Namespace - -| Namespace | Commands | Notes | -|-----------|----------|-------| -| `configure` | 22 | Infrastructure standards | -| `test` | 6 | Testing workflows | -| `git` | 5 | Git operations | -| `docs` | 4 | Documentation | -| `project` | 4 | Project setup | -| `code` | 3 | Code quality | -| `deploy` | 2 | Deployment | -| `sync` | 2 | Synchronization | -| `workflow` | 2 | Automation | -| `meta` | 2 | Introspection | -| Others | 1 each | Specialized | -| (root) | ~10 | Legacy/cross-cutting | - -## Alternatives Considered - -### Flat with Prefixes -Keep flat directory but use filename prefixes: `git-commit.md`, `test-run.md`. - -**Rejected because**: Still clutters tab completion; doesn't provide directory grouping. - -### Deep Nesting -Allow nested namespaces: `/configure:tests:coverage`. - -**Rejected because**: Over-complicates invocation; two levels sufficient for 76 commands. - -### Tag-Based Organization -Flat directory with YAML tags for categorization. - -**Rejected because**: Doesn't improve tab completion; tags require tooling support. - -### Automatic Namespace Inference -Infer namespace from command content. - -**Rejected because**: Explicit directories are clearer; no magic behavior. - -## Related Decisions - -- ADR-0003: Skill Activation via Trigger Keywords (commands invoke skills) -- ADR-0004: Subagent-First Delegation Strategy (commands delegate to agents) -- ADR-0001: Chezmoi exact_ Directory Strategy (commands managed atomically) - -## References - -- Commands directory: `exact_dot_claude/commands/` -- Commands documentation: `exact_dot_claude/commands/CLAUDE.md` -- Migration script: `scripts/migrate-command-namespaces.sh` diff --git a/docs/adr/0006-documentation-first-development.md b/docs/adr/0006-documentation-first-development.md deleted file mode 100644 index 22adfec..0000000 --- a/docs/adr/0006-documentation-first-development.md +++ /dev/null @@ -1,218 +0,0 @@ -# ADR-0006: Documentation-First Development - -## Status - -Accepted - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -The dotfiles repository evolved from a simple configuration collection to a complex system with: -- 103+ skills with intricate activation patterns -- 76 slash commands across 14 namespaces -- 22 specialized agents with delegation rules -- Cross-platform templates and tool configurations -- CI/CD pipelines with automated workflows - -### The Implementation-First Problem - -Early development followed an implementation-first pattern: -1. Write code -2. Test manually -3. Document after (or never) - -**Consequences:** - -- **Undocumented features**: Skills and commands existed without clear usage guidance -- **Inconsistent patterns**: Each feature invented its own conventions -- **Knowledge silos**: Only the creator understood how features worked -- **Regression risk**: No clear specification to test against -- **Discovery failures**: Users couldn't find capabilities they didn't know existed - -### The Context7 Revelation - -Using the `context7` MCP server for documentation research revealed: -- Official documentation often contradicted assumptions -- Tool behaviors had changed between versions -- "Best practices" evolved faster than implementation -- Configuration options had undocumented interactions - -Implementing features without checking current documentation led to: -- Using deprecated APIs -- Missing new capabilities -- Incompatible configurations -- Wasted rework cycles - -### PRD-First Mandate - -For significant features, the lack of upfront requirements caused: -- Scope creep during implementation -- Unclear success criteria -- Misaligned expectations -- Difficult code review (what was the goal?) - -## Decision - -**Adopt documentation-first development** with three pillars: - -### 1. Research Before Implementation - -Before writing any code: - -``` -1. Research relevant documentation using context7 and web search -2. Verify implementation approaches against official docs -3. Check for breaking changes and version compatibility -4. Validate configuration options against current documentation -``` - -**Tools:** -- `context7` MCP server for documentation lookup -- Web search for current best practices -- Official tool documentation - -### 2. PRD-First for Significant Features - -Every new feature or significant change MUST have a Product Requirements Document: - -```markdown -# Feature Name PRD - -## Problem Statement -What problem are we solving? - -## Proposed Solution -How will we solve it? - -## Success Criteria -How do we know it works? - -## Non-Goals -What are we NOT doing? - -## Technical Approach -Implementation strategy - -## Testing Plan -How will we verify? -``` - -**Enforcement:** -- Use `requirements-documentation` agent for PRD generation -- PRD templates in `docs/` directory -- PRD review before implementation begins - -### 3. Test-Driven Development (TDD) - -Follow strict RED → GREEN → REFACTOR workflow: - -``` -1. RED: Write a failing test that defines desired behavior -2. GREEN: Implement minimal code to make the test pass -3. REFACTOR: Improve code quality while keeping tests green -4. Run full test suite to verify no regressions -``` - -**Tiered Test Execution:** - -| Tier | When to Run | Duration | -|------|-------------|----------| -| Unit | After every change | < 30s | -| Integration | After feature completion | < 5min | -| E2E | Before commit/PR | < 30min | - -### Implementation Checklist - -Before implementing any change: - -- [ ] Read relevant documentation sections thoroughly -- [ ] Verify syntax and parameters in official documentation -- [ ] Check for breaking changes and version compatibility -- [ ] Review best practices and recommended patterns -- [ ] Validate configuration options against current docs -- [ ] Check for deprecated features to avoid -- [ ] Confirm implementation matches current best practices - -## Consequences - -### Positive - -1. **Reduced rework** - Documentation research catches issues early -2. **Consistent patterns** - PRDs establish conventions before code -3. **Clear success criteria** - Tests define expected behavior -4. **Knowledge preservation** - Documentation captures rationale -5. **Easier onboarding** - New contributors understand the "why" -6. **Better code review** - PRD provides review context - -### Negative - -1. **Initial slowdown** - Documentation takes time upfront -2. **Overhead for small changes** - PRD may be overkill for trivial fixes -3. **Documentation drift** - Must maintain docs alongside code -4. **Tool dependency** - Relies on context7 MCP availability - -### Scope Guidelines - -| Change Type | PRD Required? | Documentation Required? | -|-------------|---------------|------------------------| -| New feature | Yes | Yes | -| Significant refactor | Yes | Yes | -| Bug fix | No | Update if behavior changes | -| Typo fix | No | No | -| Dependency update | No | If breaking changes | -| New skill/command | Yes (brief) | Yes | - -### Agent Integration - -Testing agents consult based on scenario: - -| Scenario | Agent | -|----------|-------| -| Run tests, analyze failures | `test-runner` | -| New feature test strategy | `test-architecture` | -| Complex test failures | `system-debugging` | -| Test code quality review | `code-review` | - -Consult `test-architecture` agent when: -- Creating tests for new features -- Coverage drops or gaps identified -- Flaky tests detected -- Test framework decisions needed - -## Alternatives Considered - -### Pure TDD Without Documentation Research -Write tests first without researching current documentation. - -**Rejected because**: Tests may encode incorrect assumptions about tool behavior. - -### Documentation After Implementation -Write docs after code is complete (traditional approach). - -**Rejected because**: Knowledge loss, inconsistent patterns, undocumented features. - -### Wiki-Based Documentation -Maintain documentation in external wiki instead of repo. - -**Rejected because**: Documentation drifts from code; not versioned together. - -### Minimal Documentation -Only document public APIs and user-facing features. - -**Rejected because**: Internal patterns need documentation for maintainability. - -## Related Decisions - -- ADR-0003: Skill Activation via Trigger Keywords (documentation enables discovery) -- ADR-0004: Subagent-First Delegation Strategy (agents enforce TDD) -- ADR-0007: Layered Knowledge Distribution (where documentation lives) - -## References - -- Core principles: `exact_dot_claude/CLAUDE.md` (Development Process section) -- PRD templates: `docs/` directory -- Test commands: `exact_dot_claude/commands/test/` -- requirements-documentation agent: `exact_dot_claude/agents/requirements-documentation/` diff --git a/docs/adr/0007-layered-knowledge-distribution.md b/docs/adr/0007-layered-knowledge-distribution.md deleted file mode 100644 index 0c34579..0000000 --- a/docs/adr/0007-layered-knowledge-distribution.md +++ /dev/null @@ -1,213 +0,0 @@ -# ADR-0007: Layered Knowledge Distribution (CLAUDE.md Architecture) - -## Status - -Accepted - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -The dotfiles repository contains extensive configuration and automation across multiple domains: -- Chezmoi dotfiles management -- Neovim editor configuration -- Shell and terminal setup -- Claude Code skills, commands, and agents -- CI/CD workflows -- Maintenance scripts - -### The Monolithic Documentation Problem - -Initially, all guidance lived in a single root `CLAUDE.md` file. As the repository grew: - -**Problems with single-file documentation:** -1. **Information overload** - 1000+ lines in one file -2. **Irrelevant context** - Neovim details shown when working on shell configs -3. **Maintenance burden** - All changes to one file cause merge conflicts -4. **Discovery failure** - Hard to find domain-specific guidance -5. **Stale information** - Distant sections not updated with related code - -### Claude Code's Context Loading - -Claude Code automatically loads `CLAUDE.md` files from: -1. Repository root -2. Current working directory -3. Parent directories up to root - -This means **multiple CLAUDE.md files are loaded simultaneously**, enabling layered documentation that's context-aware. - -### Domain Expert Principle - -Different repository areas have different experts: -- Neovim config → Neovim expertise -- Fish shell → Shell scripting expertise -- Skills system → Claude Code agent expertise -- CI/CD → GitHub Actions expertise - -Centralizing all documentation forces one person/context to maintain all domains. - -## Decision - -**Distribute documentation across domain-specific CLAUDE.md files** following the principle: "Domain experts write domain documentation at the point of source code." - -### Documentation Hierarchy - -``` -dotfiles/ -├── CLAUDE.md # Root: Repository overview, tools, security -├── exact_dot_claude/ -│ ├── CLAUDE.md # Claude Code: Design principles, delegation -│ ├── commands/ -│ │ └── CLAUDE.md # Commands: 14 namespaces, 76 commands -│ ├── skills/ -│ │ └── CLAUDE.md # Skills: 103+ skills, activation patterns -│ └── agents/ -│ └── CLAUDE.md # Agents: 22 agents, delegation flows -├── private_dot_config/ -│ ├── CLAUDE.md # Config: Chezmoi naming, templates -│ └── nvim/ -│ └── CLAUDE.md # Neovim: Lua config, LSP, plugins -└── scripts/ - └── CLAUDE.md # Scripts: Maintenance automation -``` - -### 8 CLAUDE.md Files by Domain - -| File | Domain | Key Content | -|------|--------|-------------| -| **Root** | Repository | Overview, MCP servers, linting, security, release-please | -| **exact_dot_claude/** | Claude Code design | Delegation strategy, core principles, TDD workflow | -| **commands/** | Slash commands | 14 namespaces, command anatomy, creation guide | -| **skills/** | Agent skills | 103+ skills, activation patterns, YAML format | -| **agents/** | Specialized agents | 22 agents, analysis vs implementation, delegation flows | -| **private_dot_config/** | Configuration | Chezmoi naming, templates, cross-platform | -| **nvim/** | Neovim | Lua architecture, LSP, plugins, lazy.nvim | -| **scripts/** | Maintenance | Completion generation, namespace migration | - -### Content Distribution Rules - -| Content Type | Location | Rationale | -|--------------|----------|-----------| -| Repository overview | Root | First thing anyone sees | -| Tool versions, linting | Root | Applies everywhere | -| Security, secrets | Root | Critical, universal | -| Claude Code philosophy | exact_dot_claude/ | Design decisions | -| Command reference | commands/ | Co-located with commands | -| Skill activation guide | skills/ | Near skill definitions | -| Agent architecture | agents/ | With agent configs | -| Chezmoi patterns | private_dot_config/ | Config-specific | -| Neovim details | nvim/ | Editor-specific | -| Script usage | scripts/ | Near scripts | - -### Cross-Reference Pattern - -Each domain CLAUDE.md includes a "See Also" section: - -```markdown -## See Also - -- **Root CLAUDE.md** - Overall repository guidance -- **`.claude/CLAUDE.md`** - High-level design and delegation strategy -- **Chezmoi Expert Skill** - Automatic guidance for chezmoi operations -``` - -### Root CLAUDE.md Quick Reference - -The root file includes a navigation table: - -```markdown -| Topic | Documentation | Key Information | -|-------|---------------|-----------------| -| **Overall guidance** | `CLAUDE.md` (this file) | Repository overview | -| **Claude Code design** | `.claude/CLAUDE.md` | Delegation strategy | -| **Slash commands** | `.claude/commands/CLAUDE.md` | 14 namespaces | -| **Skills catalog** | `.claude/skills/CLAUDE.md` | 103+ skills | -| **Configuration** | `private_dot_config/CLAUDE.md` | Chezmoi patterns | -| **Maintenance** | `scripts/CLAUDE.md` | CLI completions | -``` - -## Consequences - -### Positive - -1. **Context-aware loading** - Only relevant docs loaded per directory -2. **Reduced cognitive load** - Focused information per domain -3. **Parallel maintenance** - Different areas updated independently -4. **Domain expertise** - Specialists maintain their sections -5. **Discoverable** - Documentation lives near related code -6. **Merge-friendly** - Changes isolated to domain files - -### Negative - -1. **Navigation complexity** - Must know where to look -2. **Potential duplication** - Some info may appear in multiple places -3. **Consistency challenge** - Different writing styles per domain -4. **Discovery for newcomers** - Must learn the hierarchy - -### File Size Guidelines - -| File | Target Lines | Rationale | -|------|--------------|-----------| -| Root CLAUDE.md | 300-500 | Overview, not exhaustive | -| Domain CLAUDE.md | 200-400 | Focused reference | -| Subdomain CLAUDE.md | 100-200 | Specific details | - -If a CLAUDE.md exceeds 500 lines, consider: -1. Moving detailed content to separate docs -2. Creating subdomain CLAUDE.md files -3. Using progressive disclosure (summary → details) - -### Update Protocol - -When making changes: - -1. **Identify affected domain** - Which CLAUDE.md owns this content? -2. **Update domain file** - Make changes in the appropriate file -3. **Check cross-references** - Update "See Also" if needed -4. **Verify navigation** - Ensure root quick reference is current - -## Alternatives Considered - -### Single Monolithic CLAUDE.md -Keep all documentation in one file. - -**Rejected because**: Information overload, maintenance burden, irrelevant context loading. - -### External Documentation System -Use dedicated docs site (GitBook, Docusaurus, etc.). - -**Rejected because**: Not loaded by Claude Code; documentation drifts from code. - -### README.md Files Instead -Use README.md in each directory. - -**Rejected because**: Claude Code specifically loads CLAUDE.md; README is for humans browsing GitHub. - -### Wiki-Based Documentation -Maintain docs in GitHub wiki. - -**Rejected because**: Not versioned with code; not loaded by Claude Code. - -### Flat Documentation Directory -All docs in `docs/` without hierarchy. - -**Rejected because**: Loses co-location benefit; all docs loaded regardless of context. - -## Related Decisions - -- ADR-0006: Documentation-First Development (what to document) -- ADR-0003: Skill Activation via Trigger Keywords (skills docs) -- ADR-0005: Namespace-Based Command Organization (commands docs) - -## References - -- Root: `CLAUDE.md` -- Claude Code design: `exact_dot_claude/CLAUDE.md` -- Commands: `exact_dot_claude/commands/CLAUDE.md` -- Skills: `exact_dot_claude/skills/CLAUDE.md` -- Agents: `exact_dot_claude/agents/CLAUDE.md` -- Configuration: `private_dot_config/CLAUDE.md` -- Neovim: `private_dot_config/nvim/CLAUDE.md` -- Scripts: `scripts/CLAUDE.md` diff --git a/docs/adr/0008-project-scoped-mcp-servers.md b/docs/adr/0008-project-scoped-mcp-servers.md deleted file mode 100644 index 22886ac..0000000 --- a/docs/adr/0008-project-scoped-mcp-servers.md +++ /dev/null @@ -1,231 +0,0 @@ -# ADR-0008: Project-Scoped MCP Servers - -## Status - -Accepted - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -MCP (Model Context Protocol) servers extend Claude Code with specialized capabilities: -- `github` - GitHub API integration for issues, PRs, repos -- `context7` - Documentation lookup and context management -- `playwright` - Browser automation and testing -- `vectorcode` - Semantic code search using embeddings -- `sequential-thinking` - Enhanced reasoning for complex tasks - -### The User-Scoped Problem - -Initially, MCP servers were configured in the user-scoped settings file: - -``` -~/.claude/settings.json - └── mcpServers: { github, playwright, vectorcode, ... } -``` - -**Problems with user-scoped configuration:** - -1. **Context bloat** - All MCP tools loaded in every repository - - Working on a simple script? Still loading Kubernetes, Playwright, Sentry tools - - Token usage increases with unnecessary tool descriptions - -2. **Hidden dependencies** - Team can't see what MCP servers a project needs - - "Why doesn't this work?" → Missing MCP server not in user settings - - Onboarding requires manual MCP configuration - -3. **Environment pollution** - Irrelevant tools appear in suggestions - - "Add a test" → Playwright suggestions in a CLI tool project - - Cognitive load from filtering irrelevant options - -4. **No reproducibility** - Each developer configures differently - - Different MCP servers = different Claude behavior - - Hard to debug team-wide issues - -### MCP Server Categories - -Analysis revealed distinct server categories: - -| Category | Examples | Scope | -|----------|----------|-------| -| **Version Control** | github | Most projects | -| **Documentation** | context7 | Research-heavy projects | -| **Testing** | playwright | Web projects | -| **Search** | vectorcode | Large codebases | -| **Infrastructure** | argocd-mcp, sentry | DevOps projects | -| **Productivity** | podio-mcp | Specific workflows | -| **AI** | sequential-thinking, pal | Complex reasoning | - -Not every project needs every server. - -## Decision - -**Manage MCP servers per-project** via `.mcp.json` in project root, with a favorites registry in `.chezmoidata.toml` for easy installation. - -### Project-Scoped Configuration - -Each project declares its MCP dependencies: - -```json -// .mcp.json (in project root, committed to git) -{ - "mcpServers": { - "github": { - "command": "go", - "args": ["run", "github.com/github/github-mcp-server/cmd/github-mcp-server@latest", "stdio"] - }, - "context7": { - "command": "bunx", - "args": ["-y", "@upstash/context7-mcp"] - } - } -} -``` - -**Benefits:** -- Team shares the same MCP configuration via git -- Only relevant servers loaded per project -- Clear project dependencies -- Reproducible across developers - -### Favorites Registry - -Maintain curated MCP server configurations in `.chezmoidata.toml`: - -```toml -[mcp_servers.github] - enabled = false # Disabled by default - scope = "project" - command = "go" - args = ["run", "github.com/github/github-mcp-server/cmd/github-mcp-server@latest", "stdio"] - description = "GitHub API integration" - category = "vcs" - env_vars = ["GITHUB_TOKEN"] - -[mcp_servers.playwright] - enabled = false - scope = "project" - command = "bunx" - args = ["-y", "@playwright/mcp@latest"] - description = "Browser automation and testing" - category = "testing" -``` - -**Why disabled by default?** -- Avoids bloating every project's context -- Forces explicit decision about which servers to enable -- Registry serves as documentation, not auto-installation - -### Installation Workflow - -**Interactive (recommended):** -```bash -/configure:mcp # Claude command for guided installation -``` - -**Manual:** -1. Check available servers in `.chezmoidata.toml` -2. Copy configuration to project's `.mcp.json` -3. Set required environment variables - -### Intelligent Suggestions - -The **mcp-management skill** suggests servers based on project structure: - -| Project Signal | Suggested Server | -|----------------|------------------| -| `.github/` directory | github | -| `playwright.config.*` | playwright | -| Large codebase (>1000 files) | vectorcode | -| `.argocd/` or ArgoCD refs | argocd-mcp | -| `sentry.client.config.*` | sentry | - -### Environment Variables - -Servers requiring API tokens reference environment variables: - -```json -{ - "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } -} -``` - -**Token storage:** -- `~/.api_tokens` - Sourced by shell (gitignored) -- Project `.env` - Local overrides (gitignored) - -**Never hardcode tokens in `.mcp.json`** - -## Consequences - -### Positive - -1. **Clean context** - Only relevant MCP tools per project -2. **Team alignment** - Shared configuration via git -3. **Explicit dependencies** - Clear what a project needs -4. **Reduced confusion** - No irrelevant tool suggestions -5. **Faster startup** - Fewer servers to initialize - -### Negative - -1. **Initial setup** - Must configure `.mcp.json` per project -2. **Duplication** - Similar configs across related projects -3. **Discovery** - New developers must know about registry -4. **Maintenance** - Update configs when servers change - -### Migration Path - -**From user-scoped to project-scoped:** - -1. Identify which MCP servers current project actually uses -2. Create `.mcp.json` with only needed servers -3. Remove servers from `~/.claude/settings.json` (optional) -4. Commit `.mcp.json` to git - -### Server Selection Guide - -| Project Type | Recommended Servers | -|--------------|---------------------| -| **CLI Tool** | github | -| **Web App** | github, playwright | -| **Large Monorepo** | github, vectorcode | -| **DevOps/Infrastructure** | github, argocd-mcp, context7 | -| **Research/Documentation** | github, context7 | -| **Complex Reasoning** | sequential-thinking | - -## Alternatives Considered - -### Keep User-Scoped Only -Continue with all servers in `~/.claude/settings.json`. - -**Rejected because**: Context bloat, no team sharing, hidden dependencies. - -### Workspace-Level Configuration -Configure at IDE/editor workspace level. - -**Rejected because**: Not portable across editors; Claude Code uses `.mcp.json`. - -### Auto-Detection Only -Automatically enable servers based on project structure. - -**Rejected because**: May enable unwanted servers; explicit configuration preferred. - -### Monorepo-Wide Configuration -Single config for entire monorepo. - -**Rejected because**: Different packages may need different servers; too coarse-grained. - -## Related Decisions - -- ADR-0002: Unified Tool Version Management (similar project-scoped philosophy) -- ADR-0006: Documentation-First Development (context7 for research) -- ADR-0004: Subagent-First Delegation (agents may use MCP servers) - -## References - -- Project MCP config: `.mcp.json` -- Favorites registry: `.chezmoidata.toml` (`[mcp_servers]` section) -- MCP management skill: `exact_dot_claude/skills/mcp-management/` -- Installation command: `/configure:mcp` diff --git a/docs/adr/0009-conventional-commits-release-please.md b/docs/adr/0009-conventional-commits-release-please.md deleted file mode 100644 index 59ca95e..0000000 --- a/docs/adr/0009-conventional-commits-release-please.md +++ /dev/null @@ -1,251 +0,0 @@ -# ADR-0009: Conventional Commits and Release-Please Automation - -## Status - -Accepted - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -The dotfiles repository and its plugins require versioning and changelog management. Traditional approaches involve: -- Manual version bumps in package manifests -- Hand-written CHANGELOG.md entries -- Remembering to tag releases -- Coordinating version numbers across multiple files - -### The Manual Versioning Problem - -Manual version management caused: - -1. **Inconsistent versions** - Different files showing different versions -2. **Forgotten changelogs** - Features shipped without documentation -3. **Merge conflicts** - Multiple PRs editing CHANGELOG.md simultaneously -4. **Human error** - Wrong version numbers, duplicate entries -5. **Release friction** - Tedious manual steps delayed releases - -### Conventional Commits Standard - -The [Conventional Commits](https://www.conventionalcommits.org/) specification provides: -- Structured commit messages with semantic meaning -- Machine-readable format for automation -- Human-readable history for understanding changes - -**Format:** -``` -(): - -[optional body] - -[optional footer(s)] -``` - -**Types:** -| Type | Purpose | Version Bump | -|------|---------|--------------| -| `feat` | New feature | Minor (0.x.0) | -| `fix` | Bug fix | Patch (0.0.x) | -| `feat!` | Breaking feature | Major (x.0.0) | -| `BREAKING CHANGE:` | Breaking change footer | Major (x.0.0) | -| `chore` | Maintenance | None | -| `docs` | Documentation | None | -| `refactor` | Code improvement | None | - -### Release-Please Tool - -Google's [release-please](https://github.com/googleapis/release-please) automates: -1. Analyzing conventional commits since last release -2. Determining semantic version bump -3. Generating CHANGELOG.md entries -4. Updating version fields in manifests -5. Creating release PRs -6. Tagging releases when merged - -## Decision - -**Adopt conventional commits with release-please automation**, enforced by skill-based protection and permission system. - -### Commit Message Convention - -All commits must follow conventional commit format: - -**Feature (minor bump):** -``` -feat(auth): add OAuth2 support - -Implements OAuth2 authentication with PKCE. -Includes refresh token rotation. - -Refs: #42 -``` - -**Bug fix (patch bump):** -``` -fix(api): handle timeout edge case - -Fixes race condition in token refresh. - -Fixes: #123 -``` - -**Breaking change (major bump):** -``` -feat(api)!: redesign authentication - -BREAKING CHANGE: Auth endpoint now requires OAuth2. -Migration guide: docs/migration/v2.md -``` - -### Protected Files - -**Hard protection (permission system blocks edits):** -- `**/CHANGELOG.md` - All changelog files - -**Soft protection (skill warns before edits):** -- `package.json` - version field -- `pyproject.toml` - version field -- `Cargo.toml` - version field -- `.claude-plugin/plugin.json` - version field - -### Permission System Configuration - -In `~/.claude/settings.json`: -```json -{ - "permissions": { - "deny": [ - "Edit(**/CHANGELOG.md)", - "Write(**/CHANGELOG.md)", - "MultiEdit(**/CHANGELOG.md)" - ] - } -} -``` - -### Skill-Based Detection - -The `release-please-protection` skill: -1. Detects edit attempts to protected files -2. Explains why manual edits cause problems -3. Provides conventional commit templates -4. Suggests proper workflow - -**Example response when CHANGELOG.md edit attempted:** -``` -⚠️ CHANGELOG.md Protection Active - -I cannot edit CHANGELOG.md - it's managed by release-please automation. - -**Proper workflow:** -1. Make changes with conventional commit messages -2. Release-please automatically generates changelog entries -3. Review and merge the release PR - -**For your change, use:** -feat(scope): your feature description -``` - -### Automated Workflow - -``` -Developer commits → Conventional commit format - ↓ -Release-please → Analyzes commits since last release - ↓ -Creates Release PR → Updates CHANGELOG.md + version fields - ↓ -PR merged → Tags release, publishes -``` - -### Emergency Override - -For exceptional cases requiring manual edits: - -```bash -# 1. Temporarily disable protection -vim ~/.claude/settings.json -# Comment out CHANGELOG.md deny rules - -# 2. Make edits - -# 3. Re-enable protection -# Uncomment the deny rules - -# 4. Sync with chezmoi -chezmoi apply -``` - -## Consequences - -### Positive - -1. **Automated changelogs** - No manual CHANGELOG maintenance -2. **Consistent versioning** - Semantic versions derived from commits -3. **No merge conflicts** - Automated PRs don't conflict -4. **Clear history** - Commit messages explain "why" -5. **Reduced friction** - Releases happen automatically -6. **Team alignment** - Everyone follows same convention - -### Negative - -1. **Learning curve** - Team must learn conventional commit format -2. **Commit discipline** - Requires consistent message formatting -3. **Automation dependency** - Release process depends on tooling -4. **Override complexity** - Emergency manual edits are awkward - -### Enforcement Layers - -| Layer | Mechanism | Scope | -|-------|-----------|-------| -| Permission system | `deny` rules in settings.json | CHANGELOG.md blocked | -| Skill detection | release-please-protection | Version fields warned | -| Pre-commit hooks | commitlint | Commit format validated | -| CI/CD | GitHub Actions | PR validation | - -### Commit Message Checklist - -- [ ] Starts with valid type (`feat`, `fix`, `chore`, etc.) -- [ ] Scope in parentheses if applicable -- [ ] Colon and space after type/scope -- [ ] Description in imperative mood -- [ ] Body explains "why" not "what" -- [ ] Footer references issues if applicable -- [ ] Breaking changes marked with `!` or `BREAKING CHANGE:` - -## Alternatives Considered - -### Manual Versioning -Continue with manual version bumps and changelogs. - -**Rejected because**: Error-prone, inconsistent, creates merge conflicts. - -### Semantic-Release -Use semantic-release instead of release-please. - -**Not rejected**: Both are viable; release-please chosen for its PR-based workflow and multi-language support. - -### Git Tags Only -Use git tags for versioning without changelog automation. - -**Rejected because**: Loses changelog documentation; doesn't update manifest files. - -### Changelog Generator Scripts -Custom scripts to generate changelogs. - -**Rejected because**: Reinventing release-please; maintenance burden. - -## Related Decisions - -- ADR-0006: Documentation-First Development (commits document changes) -- ADR-0004: Subagent-First Delegation (git-commit-workflow skill) -- ADR-0005: Namespace-Based Command Organization (/git:commit command) - -## References - -- Conventional Commits: https://www.conventionalcommits.org/ -- Release-Please: https://github.com/googleapis/release-please -- Protection skill: `exact_dot_claude/skills/release-please-protection/` -- Git commit skill: `exact_dot_claude/skills/git-commit-workflow/` -- Root CLAUDE.md: Release-Please Automation section diff --git a/docs/adr/0010-tiered-test-execution.md b/docs/adr/0010-tiered-test-execution.md deleted file mode 100644 index 613b314..0000000 --- a/docs/adr/0010-tiered-test-execution.md +++ /dev/null @@ -1,262 +0,0 @@ -# ADR-0010: Tiered Test Execution with Specialized Agents - -## Status - -Accepted - -## Date - -2024-12 (retroactively documented 2025-12) - -## Context - -The dotfiles repository and projects it manages require testing across multiple dimensions: -- Unit tests for individual functions -- Integration tests for component interactions -- End-to-end tests for full workflows -- Configuration validation tests -- Cross-platform compatibility tests - -### The Flat Testing Problem - -Early testing followed a "run all tests" approach: - -```bash -make test # Runs everything, every time -``` - -**Problems:** - -1. **Slow feedback** - 10+ minute test suites for small changes -2. **Wasted resources** - E2E tests run for typo fixes -3. **Developer friction** - Long waits discourage frequent testing -4. **CI bottlenecks** - All PRs wait for full suite - -### Test Duration Analysis - -| Test Type | Typical Duration | When Needed | -|-----------|------------------|-------------| -| Unit | < 30 seconds | Every change | -| Integration | 1-5 minutes | Feature completion | -| E2E | 5-30 minutes | Before commit/PR | -| Performance | 10-60 minutes | Release candidates | - -Running all tests for every change wastes 95%+ of test execution time. - -### Agent Expertise Gap - -Different test scenarios require different expertise: -- **Test failures**: Need failure analysis, not test design -- **New features**: Need test strategy, not just execution -- **Flaky tests**: Need debugging, not more test runs -- **Coverage gaps**: Need architectural guidance - -A single "test" command couldn't provide specialized responses. - -## Decision - -**Implement tiered test execution** with specialized testing agents, exposed via namespace-organized commands. - -### Test Tiers - -| Tier | Duration | Trigger | Command | -|------|----------|---------|---------| -| **Unit** | < 30s | Every change | `/test:quick` | -| **Integration** | < 5min | Feature completion | `/test:full` | -| **E2E** | < 30min | Before commit/PR | `/test:full` | - -### Tier Selection Criteria - -The `test-tier-selection` skill automatically determines appropriate tier: - -``` -Change scope analysis: -├─ Single file, isolated function → Unit tier -├─ Multiple files, same module → Integration tier -├─ Cross-module changes → E2E tier -├─ Configuration changes → Full validation -└─ Documentation only → Skip tests -``` - -### Specialized Testing Agents - -| Agent | Role | Capabilities | -|-------|------|--------------| -| `test-runner` | **Execution** | Run tests, analyze failures, report results | -| `test-architecture` | **Strategy** | Coverage analysis, framework selection, test design | -| `system-debugging` | **Investigation** | Root cause analysis, flaky test diagnosis | -| `code-review` | **Quality** | Test code review, assertion quality | - -### Agent Selection Guide - -| Scenario | Agent | Command | -|----------|-------|---------| -| Run tests, see results | `test-runner` | `/test:quick` or `/test:full` | -| New feature needs tests | `test-architecture` | `/test:consult new-feature` | -| Tests failing mysteriously | `system-debugging` | Direct delegation | -| Coverage dropped | `test-architecture` | `/test:consult coverage` | -| Flaky test detected | `system-debugging` | Direct delegation | -| Test code quality check | `code-review` | `/code:review` on test files | - -### Command Structure - -``` -/test:quick → Unit tests only (< 30s feedback) -/test:full → All tiers (comprehensive) -/test:consult → Consult test-architecture agent -/test:report → Show last test results -/test:run → Auto-detect and run appropriate tests -/test:setup → Configure testing infrastructure -``` - -### Workflow Integration - -**Development Cycle:** -``` -1. Make change -2. /test:quick → Immediate feedback (unit tests) -3. Continue development -4. /test:quick → Verify each change -5. Feature complete -6. /test:full → Comprehensive validation -7. /git:commit → Commit with confidence -``` - -**TDD Loop (via /project-test-loop):** -``` -1. RED: Write failing test -2. /test:quick → Confirm failure -3. GREEN: Implement minimal code -4. /test:quick → Confirm pass -5. REFACTOR: Improve code -6. /test:quick → Verify no regression -``` - -### Agent Delegation Flow - -``` -User: "Run the tests" - │ - ├─ /test:quick or /test:full - │ └─ Delegates to test-runner agent - │ └─ Executes tests - │ └─ Analyzes failures - │ └─ Reports concise summary - │ - └─ If complex failures detected: - └─ test-runner suggests: system-debugging agent - └─ Orchestrator delegates for root cause analysis -``` - -### Failure Reporting Format - -`test-runner` agent provides structured failure reports: - -``` -❌ 3 tests failed - -1. test_auth_flow (tests/test_auth.py:42) - Expected: 200 - Actual: 401 - Likely cause: Token expiration not handled - -2. test_api_timeout (tests/test_api.py:87) - TimeoutError after 30s - Likely cause: Mock server not responding - -3. test_config_load (tests/test_config.py:15) - FileNotFoundError: config.yaml - Likely cause: Missing test fixture - -Suggested actions: -- Fix auth token refresh logic (test 1) -- Check mock server setup in conftest.py (test 2) -- Add config.yaml to test fixtures (test 3) -``` - -## Consequences - -### Positive - -1. **Fast feedback** - Unit tests in <30 seconds -2. **Appropriate testing** - Right tests for right changes -3. **Specialized expertise** - Agents match test scenarios -4. **Resource efficiency** - No unnecessary E2E for small changes -5. **Clear commands** - `/test:quick` vs `/test:full` intent is obvious -6. **Actionable reports** - Failure analysis, not just stack traces - -### Negative - -1. **Tier judgment** - Must decide which tier to run -2. **Agent selection** - Learning which agent for which scenario -3. **Configuration** - Initial setup of test tiers -4. **Potential gaps** - Wrong tier might miss issues - -### Test Infrastructure Requirements - -For full tier support, projects should have: - -``` -tests/ -├── unit/ → Fast, isolated tests -├── integration/ → Component interaction tests -└── e2e/ → Full workflow tests - -pytest.ini or pyproject.toml: - markers: - - unit: Fast unit tests - - integration: Integration tests - - e2e: End-to-end tests -``` - -### Framework Support - -| Framework | Unit Command | Full Command | -|-----------|--------------|--------------| -| pytest | `pytest -m unit` | `pytest` | -| jest | `jest --testPathPattern=unit` | `jest` | -| cargo | `cargo test --lib` | `cargo test` | -| go | `go test -short` | `go test` | - -### Metrics to Track - -- **Time to feedback**: Unit test duration -- **Test reliability**: Flaky test rate -- **Coverage**: Per-tier coverage percentages -- **Agent accuracy**: Correct agent selection rate - -## Alternatives Considered - -### Single Test Command -One command runs all tests always. - -**Rejected because**: Slow feedback, wasted resources, developer friction. - -### Manual Tier Selection -Developer manually specifies which tests to run. - -**Rejected because**: Cognitive load, inconsistent selection, easy to forget tiers. - -### Parallel All Tests -Run all tiers in parallel for speed. - -**Rejected because**: Resource intensive, still slow for E2E, overkill for small changes. - -### Test on Commit Only -Only run tests on git commit. - -**Rejected because**: Feedback too late, larger fix batches, more debugging. - -## Related Decisions - -- ADR-0004: Subagent-First Delegation Strategy (test agents are subagents) -- ADR-0005: Namespace-Based Command Organization (/test: namespace) -- ADR-0006: Documentation-First Development (TDD workflow) - -## References - -- Test commands: `exact_dot_claude/commands/test/` -- Test tier selection skill: `exact_dot_claude/skills/test-tier-selection/` -- test-runner agent: `exact_dot_claude/agents/test-runner/` -- test-architecture agent: `exact_dot_claude/agents/test-architecture/` -- TDD workflow: `exact_dot_claude/CLAUDE.md` (Tiered Test Execution section) diff --git a/docs/adr/0011-claude-rules-migration.md b/docs/adr/0011-claude-rules-migration.md deleted file mode 100644 index d9ec03d..0000000 --- a/docs/adr/0011-claude-rules-migration.md +++ /dev/null @@ -1,151 +0,0 @@ -# ADR 0011: Migration to Claude Code Rules System - -## Status - -Accepted - -## Date - -2025-12-13 - -## Context - -Claude Code introduced the `.claude/rules/` directory feature in v2.0.64 (December 2025) as a modular approach for organizing project-specific instructions. Prior to this, all Claude Code instructions were maintained in: - -1. **CLAUDE.md files** - Monolithic files containing project context, conventions, and operational rules -2. **Skills** - Context-dependent expertise that activates based on task relevance - -The existing setup had several issues: - -- `exact_dot_claude/CLAUDE.md` had grown to 300+ lines mixing high-level design with detailed operational rules -- Universal constraints (delegation, code quality, security) were mixed with project-specific context -- It was unclear which instructions applied universally vs. conditionally -- Maintenance required editing a single large file - -## Decision - -Migrate universal operational rules from CLAUDE.md files to the new `.claude/rules/` directory while: - -1. **Keeping CLAUDE.md files** for high-level project context and navigation -2. **Keeping Skills** for domain-specific expertise that activates conditionally -3. **Creating focused rule files** for universal constraints that apply regardless of task type - -### Rules Created - -| Rule File | Content Migrated From | Purpose | -|-----------|----------------------|---------| -| `rules/delegation.md` | `exact_dot_claude/CLAUDE.md` | When to use subagents vs direct tools | -| `rules/communication.md` | `exact_dot_claude/CLAUDE.md` | Tone, style, response formatting | -| `rules/development-process.md` | `exact_dot_claude/CLAUDE.md` + Root `CLAUDE.md` | TDD, documentation-first, git workflow | -| `rules/code-quality.md` | `exact_dot_claude/CLAUDE.md` | SOLID, functional principles, fail-fast | -| `rules/tool-selection.md` | `exact_dot_claude/CLAUDE.md` | Decision framework for tools | -| `rules/security.md` | Root `CLAUDE.md` | API tokens, secrets, scanning | -| `rules/release-please.md` | Root `CLAUDE.md` | Protected files, conventional commits | - -### Content Kept in CLAUDE.md - -- **Root `CLAUDE.md`**: Repository overview, chezmoi configuration, key files, tools, MCP servers -- **`exact_dot_claude/CLAUDE.md`**: High-level design philosophy, directory structure, chezmoi management - -### Content Kept as Skills - -All 102 skills remain as skills because they: -- Activate conditionally based on task relevance -- Provide specialized domain expertise -- Have YAML frontmatter for activation triggers -- Follow progressive disclosure with REFERENCE.md files - -## Consequences - -### Positive - -- **Improved organization**: Single-concern rule files are easier to maintain -- **Clearer semantics**: Rules = universal, Skills = conditional, CLAUDE.md = context -- **Better discoverability**: Rule files have descriptive names indicating their purpose -- **Reduced file size**: CLAUDE.md files are now focused and concise -- **Future-proof**: Aligned with Claude Code's official feature for project instructions - -### Negative - -- **More files to manage**: 7 rule files instead of 2 large CLAUDE.md sections -- **Learning curve**: Team members need to understand rules vs skills vs CLAUDE.md -- **Chezmoi complexity**: Additional directory (`rules/`) under `exact_dot_claude/` - -### Neutral - -- **Same priority level**: Rules load with the same priority as `.claude/CLAUDE.md` -- **No behavior change**: The same instructions apply, just organized differently -- **Backward compatible**: Existing skills and commands work unchanged - -## Alternatives Considered - -### 1. Keep Everything in CLAUDE.md - -**Rejected because:** -- Files were becoming unwieldy (300+ lines) -- Mixed concerns (context vs rules) -- Claude Code now has a dedicated feature for this - -### 2. Convert All Rules to Skills - -**Rejected because:** -- Skills activate conditionally based on description matching -- Universal constraints should apply unconditionally -- Would require convoluted "Use when..." clauses to always activate - -### 3. Use Path-Scoped Rules Only - -**Rejected because:** -- Most rules apply project-wide, not to specific paths -- Path scoping is better suited for subdirectory-specific conventions -- Would add unnecessary complexity via YAML frontmatter - -## Implementation Notes - -### Directory Structure After Migration - -``` -exact_dot_claude/ -├── CLAUDE.md # Slimmed: ~70 lines (was ~300) -├── rules/ # NEW -│ ├── delegation.md -│ ├── communication.md -│ ├── development-process.md -│ ├── code-quality.md -│ ├── tool-selection.md -│ ├── security.md -│ └── release-please.md -├── skills/ # Unchanged: 102 skills -├── commands/ # Unchanged -└── ... -``` - -### Applying Changes - -After pulling this change: -```bash -chezmoi apply -v ~/.claude -``` - -### Memory Hierarchy - -Rules load in this order (lower number = loaded first, higher takes precedence): - -1. `~/.claude/CLAUDE.md` - User preferences -2. `./CLAUDE.md` - Project root -3. `./.claude/CLAUDE.md` + `./.claude/rules/**/*.md` - **Same level** -4. `./.claude/CLAUDE.local.md` - Personal overrides -5. `./src/CLAUDE.md` - Subdirectory context - -## Related Files - -- `.claude/rules/` - The rules directory this ADR introduces -- `.claude/CLAUDE.md` - High-level design documentation updated to reference rules -- `CLAUDE.md` (root) - Project overview updated with rules references -- `docs/adr/0001-chezmoi-exact-directory-strategy.md` - Related decision on `exact_` prefix for `.claude/` management - -## References - -- [Claude Code Rules Documentation](https://code.claude.com/docs/en/memory) -- [Claude Code v2.0.64 Changelog](https://claudelog.com/claude-code-changelog/) -- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) diff --git a/docs/adr/0012-justfile-command-runner.md b/docs/adr/0012-justfile-command-runner.md deleted file mode 100644 index 13d690e..0000000 --- a/docs/adr/0012-justfile-command-runner.md +++ /dev/null @@ -1,252 +0,0 @@ -# ADR-0012: Justfile Command Runner - -## Status - -Accepted - -## Date - -2025-12 - -## Context - -The dotfiles repository used a Makefile for common development tasks like applying configurations, running linters, and managing the development environment. - -### Problems with Make - -While Make is ubiquitous, it has several issues for this use case: - -1. **`.PHONY` boilerplate**: Every non-file target requires explicit `.PHONY` declaration -2. **Tab sensitivity**: Recipes must use tabs, not spaces (common source of errors) -3. **GNU vs BSD Make**: Syntax differences between platforms cause portability issues -4. **Variable syntax**: `$(VAR)` vs `${VAR}` vs `$$VAR` confusion -5. **Color output**: Requires manual ANSI escape code definitions -6. **Poor error messages**: Cryptic errors without source context -7. **Build-system baggage**: Make is designed for builds, not command running - -### Recipe Complexity Analysis - -The existing Makefile had 30+ recipes across categories: - -| Category | Recipes | Complexity | -|----------|---------|------------| -| Build & Development | apply, check, diff, status, verify | Simple | -| Testing | test, lint, smoke-* | Medium | -| Environment Setup | setup, setup-brew, setup-mise, setup-nvim | Medium | -| Utilities | update, bump, clean, security-audit | Complex | -| Development | dev, edit, ci | Simple | -| Information | info, help | Simple | - -**Pain points observed**: -- The `lint` recipe had complex shell conditionals for tool detection -- Help generation required awk parsing of `##` comments -- Color definitions duplicated at top of file -- Recursive `$(MAKE)` calls for dependencies - -### Justfile Capabilities - -[just](https://github.com/casey/just) is a modern command runner that addresses these issues: - -1. **No `.PHONY`**: All recipes are commands by default -2. **Indentation agnostic**: Spaces or tabs work fine -3. **Cross-platform**: Consistent behavior on Linux, macOS, Windows -4. **Built-in colors**: `{{BLUE}}`, `{{GREEN}}`, `{{YELLOW}}`, `{{RED}}`, `{{NORMAL}}` -5. **Clear errors**: Shows source context in error messages -6. **Native help**: `just --list` with automatic doc comment extraction -7. **Recipe attributes**: `[private]`, `[confirm]`, `[linux]`, `[macos]`, etc. -8. **Parameters**: Recipes can accept command-line arguments -9. **Conditionals**: `if`/`else` expressions in recipe bodies - -## Decision - -**Replace the Makefile with a justfile** as the project's command runner. - -### Recipe Organization - -``` -justfile -├── Default (help) -├── Build & Development -│ ├── apply # Apply dotfiles -│ ├── check # Alias for status -│ ├── diff # Show differences -│ ├── status # Show status -│ └── verify # Verify integrity -├── Testing -│ ├── test # Run all tests -│ ├── lint # Run all linters -│ ├── lint-shell # Shell scripts only -│ ├── lint-lua # Neovim config only -│ ├── lint-actions # GitHub Actions only -│ ├── pre-commit # Pre-commit hooks -│ ├── smoke # Docker smoke test -│ └── smoke-* # Docker variants -├── Environment Setup -│ ├── setup # Full setup -│ ├── setup-brew # Homebrew packages -│ ├── setup-mise # mise tools -│ └── setup-nvim # Neovim plugins -├── Utilities -│ ├── update # Update all tools -│ ├── bump # Bump versions -│ ├── clean # Clean caches -│ └── secrets # Scan for secrets -├── Development -│ ├── dev # Start dev environment -│ └── edit # Open in editor -└── Information - ├── info # System information - └── doctor # Diagnose issues -``` - -### Key Improvements - -**1. Built-in colored output**: -```just -# Before (Makefile) -BLUE := \033[34m -RESET := \033[0m -apply: - @echo "$(BLUE)Applying...$(RESET)" - -# After (justfile) -apply: - @echo "{{BLUE}}Applying...{{NORMAL}}" -``` - -**2. No `.PHONY` declarations**: -```just -# Before (Makefile) -.PHONY: apply status check diff verify - -# After (justfile) -# Nothing needed - all recipes are commands -``` - -**3. Private recipes for internal use**: -```just -[private] -_check-tool tool: - @command -v {{tool}} >/dev/null 2>&1 -``` - -**4. Platform-specific recipes**: -```just -[macos] -setup-macos: - brew install coreutils - -[linux] -setup-linux: - sudo apt install build-essential -``` - -**5. Recipe parameters**: -```just -# Apply specific target -apply target="": - chezmoi apply {{target}} -v -``` - -### Recipes Removed - -| Recipe | Reason | -|--------|--------| -| `docker` | Deprecated alias for `smoke` | -| `docs-serve` | Not implemented | -| `qa` | Redundant (same as `lint check`) | - -### Recipes Added - -| Recipe | Purpose | -|--------|---------| -| `lint-shell` | Run shellcheck only | -| `lint-lua` | Run luacheck only | -| `lint-actions` | Run actionlint only | -| `pre-commit` | Run pre-commit hooks | -| `secrets` | Scan for secrets with detect-secrets | -| `doctor` | Diagnose common issues | - -### Recipes Modified - -| Recipe | Change | -|--------|--------| -| `lint` | Now depends on individual lint-* recipes | -| `security-audit` | Renamed to `secrets`, uses detect-secrets | -| `colors` | Made private (demo/debug tool) | - -## Consequences - -### Positive - -1. **Simpler syntax**: No Make quirks or POSIX shell restrictions -2. **Better DX**: Built-in colors, `--list` for discovery -3. **Cross-platform**: Consistent behavior everywhere -4. **Maintainable**: Easier to read and modify -5. **Extensible**: Recipe attributes enable advanced patterns -6. **Modern tooling**: Active development, good documentation - -### Negative - -1. **New dependency**: Requires `just` to be installed -2. **Team learning**: Contributors must learn `just` syntax -3. **Ecosystem**: Less ubiquitous than Make -4. **IDE support**: Fewer plugins than Makefile support - -### Migration Path - -1. **Install just**: Added to mise config (`aqua:casey/just`) -2. **Create justfile**: Converted all Makefile recipes -3. **Update docs**: CLAUDE.md references `just` commands -4. **Remove Makefile**: Deleted after verification - -### Command Mapping - -| Old Command | New Command | -|-------------|-------------| -| `make` | `just` | -| `make apply` | `just apply` | -| `make lint` | `just lint` | -| `make test` | `just test` | -| `make setup` | `just setup` | -| `make update` | `just update` | -| `make info` | `just info` | - -## Alternatives Considered - -### Keep Makefile -Continue using Make with workarounds for its limitations. - -**Rejected because**: Accumulated complexity, poor error messages, cross-platform issues. - -### mise Tasks -Use mise's built-in task runner (`mise run`). - -**Rejected because**: Less mature than just, TOML syntax less readable for complex recipes, mise already serves tool version management role. - -### Task (go-task) -Use Taskfile.yml with go-task. - -**Rejected because**: YAML syntax less readable than just, less active community. - -### npm scripts / package.json -Use Node.js scripts pattern. - -**Rejected because**: Requires Node.js, not appropriate for non-JS projects. - -### Shell Scripts -Replace with individual shell scripts. - -**Rejected because**: No unified interface, harder to discover available commands. - -## Related Decisions - -- [ADR-0002](0002-unified-tool-version-management-mise.md): mise for tool management (just installed via mise) -- [ADR-0010](0010-tiered-test-execution.md): Test execution strategy (smoke tests in justfile) - -## References - -- just documentation: https://just.systems/man/en/ -- just GitHub: https://github.com/casey/just -- just vs Make: https://just.systems/man/en/what-are-the-idiosyncrasies-of-make-that-just-avoids.html -- Configuration: `justfile` in repository root diff --git a/docs/adr/0013-nixos-declarative-system-configuration.md b/docs/adr/0013-nixos-declarative-system-configuration.md deleted file mode 100644 index 72e2234..0000000 --- a/docs/adr/0013-nixos-declarative-system-configuration.md +++ /dev/null @@ -1,240 +0,0 @@ -# ADR-0013: NixOS Configuration for Declarative System Management - -## Status - -Accepted - -## Date - -2025-12 - -## Context - -The dotfiles repository has evolved into a sophisticated cross-platform configuration system using chezmoi and mise. However, for NixOS users, there's an opportunity to achieve even greater reproducibility through fully declarative system configuration. - -### Current State - -The repository already manages: -- **Dotfiles**: Via chezmoi with templates and cross-platform support -- **Tool versions**: Via mise with lockfile for reproducibility -- **Shell configuration**: Zsh/Fish with comprehensive aliases -- **Editor setup**: Neovim with lazy.nvim and 75+ plugins -- **Development tools**: Language runtimes, formatters, linters - -### The Gap - -While chezmoi + mise provides excellent user-level configuration, it doesn't address: - -1. **System-level packages**: Kernel, drivers, system services -2. **Declarative services**: Docker, Tailscale, SSH daemon configuration -3. **Atomic upgrades**: Rollback to previous system state -4. **Full reproducibility**: Same system on any machine from single config - -### Why NixOS Now? - -Several factors motivated adding NixOS support: - -1. **Complementary approach**: NixOS doesn't replace chezmoi—they work together -2. **User preference extrapolation**: Existing configs reveal clear tool preferences -3. **Home Manager integration**: Bridges NixOS and traditional dotfiles -4. **CI/Server use case**: Declarative server configurations for homelab - -### Relationship to ADR-0002 (mise) - -ADR-0002 rejected Nix/home-manager as "overkill for tool versions." This ADR takes a different view: - -| ADR-0002 Position | ADR-0013 Position | -|-------------------|-------------------| -| Nix for tool versions = overkill | NixOS for full system = appropriate | -| mise provides reproducibility | NixOS provides atomic rollbacks | -| Cross-platform (macOS + Linux) | Linux-only (NixOS + home-manager) | - -**Key insight**: mise handles tools on macOS + traditional Linux. NixOS handles full system declarativity when that's desired. They're not competing—they serve different use cases. - -## Decision - -**Add NixOS configuration to the dotfiles repository** as an optional, complementary configuration method for NixOS users. - -### Architecture - -``` -┌────────────────────────────────────────────────────────────────┐ -│ Configuration Approaches │ -├────────────────────────────────────────────────────────────────┤ -│ │ -│ Traditional (macOS/Linux) NixOS │ -│ ───────────────────────── ────── │ -│ • chezmoi for dotfiles • flake.nix for system │ -│ • mise for tool versions • home.nix for user config │ -│ • Homebrew for bootstrap • Declarative packages │ -│ │ -│ ┌──────────────┐ │ -│ │ Shared │ │ -│ │ Principles │ │ -│ ├──────────────┤ │ -│ │ • TokyoNight │ │ -│ │ • Zsh + Fish │ │ -│ │ • Neovim │ │ -│ │ • Git config │ │ -│ │ • Aliases │ │ -│ └──────────────┘ │ -│ │ -└────────────────────────────────────────────────────────────────┘ -``` - -### Directory Structure - -``` -nixos/ -├── flake.nix # Flake with inputs and system definitions -├── configuration.nix # NixOS system configuration -├── home.nix # Home Manager entry point -├── README.md # Usage documentation -├── hardware/ -│ ├── generic.nix # Desktop workstation template -│ ├── laptop.nix # Laptop with power management -│ └── arm64.nix # Raspberry Pi / ARM boards -├── modules/ -│ ├── networking.nix # NetworkManager, firewall -│ ├── security.nix # Hardening, PAM, sudo -│ └── virtualization.nix # Docker, Podman, QEMU/KVM -└── home/ - ├── shell.nix # Zsh, Fish, Starship, FZF - ├── neovim.nix # Editor with lazy.nvim - ├── git.nix # Git, GitHub CLI, Lazygit - ├── development.nix # Language configs, linters - └── terminal.nix # Kitty, Tmux, Zellij -``` - -### Preference Extrapolation - -Configurations were derived by analyzing existing dotfiles: - -| Source | Derived NixOS Config | -|--------|---------------------| -| `Brewfile` | System packages, services | -| `mise/config.toml.tmpl` | Language runtimes | -| `dot_zshrc.tmpl`, `aliases.zsh` | Shell configuration, 60+ aliases | -| `nvim/init.lua`, `nvim/lua/` | Neovim plugins and LSP | -| `dot_tmux.conf` | Tmux configuration | -| `starship.toml` | Starship prompt theme | -| `.chezmoidata.toml` | Python tools, MCP servers | - -### Configuration Options - -Three NixOS configurations for different hardware: - -1. **workstation**: Generic desktop with full development setup -2. **laptop**: TLP power management, battery thresholds, touchpad -3. **arm64**: Raspberry Pi and ARM server support - -Plus standalone home-manager for non-NixOS Linux: - -```bash -# NixOS full system -sudo nixos-rebuild switch --flake .#workstation - -# Home Manager only (Ubuntu, Fedora, etc.) -home-manager switch --flake .#lgates@linux -``` - -### Integration Strategies - -Users can choose their integration level: - -**Option A: NixOS-only** (full declarative) -- All configs in Nix -- No chezmoi needed -- Maximum reproducibility - -**Option B: NixOS + Chezmoi hybrid** (recommended) -- NixOS for system + packages -- Chezmoi for dotfiles (symlinked) -- Familiar editing workflow - -**Option C: Home Manager standalone** -- Keep existing distro (Ubuntu, Fedora) -- Use home-manager for user config -- Gradual adoption path - -## Consequences - -### Positive - -1. **Full system reproducibility**: Rebuild identical system from flake -2. **Atomic rollbacks**: `nixos-rebuild switch --rollback` for instant recovery -3. **Unified packages**: All tools declared in one place -4. **Multi-machine**: Same config across desktop, laptop, servers -5. **Preference preservation**: Existing tool choices honored -6. **Modular design**: Pick modules you need - -### Negative - -1. **Learning curve**: Nix language syntax is unique -2. **Linux-only**: NixOS doesn't run on macOS (Darwin support is separate) -3. **Maintenance burden**: Two config systems to maintain -4. **Build times**: Initial system builds can be slow -5. **Disk usage**: Nix store accumulates generations - -### Trade-offs - -| Aspect | chezmoi + mise | NixOS | -|--------|----------------|-------| -| Learning curve | Lower | Higher | -| Cross-platform | macOS + Linux | Linux only | -| Rollback | Manual | Atomic, instant | -| Disk usage | Minimal | ~10-30GB for store | -| Package availability | Homebrew ecosystem | Nixpkgs (80,000+) | -| Configuration style | File templates | Functional (Nix lang) | - -### Migration Path - -1. **Test in VM**: Try NixOS config in QEMU/VirtualBox first -2. **Home Manager first**: Use standalone home-manager on existing distro -3. **Dual boot**: Install NixOS alongside current distro -4. **Full migration**: Replace primary system when comfortable - -## Alternatives Considered - -### Ansible for System Configuration - -**Rejected because**: -- Imperative rather than declarative -- No atomic rollbacks -- Drift between runs possible -- Overkill for personal workstation - -### Ignoring NixOS Users - -**Rejected because**: -- Growing NixOS user base -- Natural fit for declarative dotfiles philosophy -- Requested by users of the dotfiles repo - -### Full Nix Darwin (macOS) - -**Deferred because**: -- Additional complexity -- Homebrew works well on macOS -- Can add later as separate configuration - -### Replace chezmoi with Nix - -**Rejected because**: -- chezmoi works cross-platform -- Familiar to existing users -- Hybrid approach is more flexible - -## Related Decisions - -- **ADR-0001**: Chezmoi exact_ Directory Strategy (atomic updates philosophy shared) -- **ADR-0002**: Unified Tool Version Management with Mise (complementary on traditional Linux) -- **ADR-0007**: Layered Knowledge Distribution (modular config approach) - -## References - -- NixOS Manual: https://nixos.org/manual/nixos/stable/ -- Home Manager: https://nix-community.github.io/home-manager/ -- Nix Flakes: https://nixos.wiki/wiki/Flakes -- Configuration: `nixos/` directory -- Usage guide: `nixos/README.md` diff --git a/docs/adr/README.md b/docs/adr/README.md deleted file mode 100644 index 7b583f9..0000000 --- a/docs/adr/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Architecture Decision Records - -This directory contains Architecture Decision Records (ADRs) documenting significant technical decisions made in this dotfiles repository. - -## What is an ADR? - -An ADR is a document that captures an important architectural decision made along with its context and consequences. ADRs help future maintainers understand why certain decisions were made. - -## ADR Index - -| ID | Title | Status | Date | -|----|-------|--------|------| -| [0001](0001-chezmoi-exact-directory-strategy.md) | Chezmoi exact_ Directory Strategy | Accepted | 2024-12 | -| [0002](0002-unified-tool-version-management-mise.md) | Unified Tool Version Management with Mise | Accepted | 2024-12 | -| [0003](0003-skill-activation-trigger-keywords.md) | Skill Activation via Trigger Keywords | Accepted | 2024-12 | -| [0004](0004-subagent-first-delegation-strategy.md) | Subagent-First Delegation Strategy | Accepted | 2024-12 | -| [0005](0005-namespace-based-command-organization.md) | Namespace-Based Command Organization | Accepted | 2024-12 | -| [0006](0006-documentation-first-development.md) | Documentation-First Development | Accepted | 2024-12 | -| [0007](0007-layered-knowledge-distribution.md) | Layered Knowledge Distribution | Accepted | 2024-12 | -| [0008](0008-project-scoped-mcp-servers.md) | Project-Scoped MCP Servers | Accepted | 2024-12 | -| [0009](0009-conventional-commits-release-please.md) | Conventional Commits + Release-Please | Accepted | 2024-12 | -| [0010](0010-tiered-test-execution.md) | Tiered Test Execution | Accepted | 2024-12 | -| [0011](0011-claude-rules-migration.md) | Claude Rules Migration | Accepted | 2025-12 | -| [0012](0012-justfile-command-runner.md) | Justfile Command Runner | Accepted | 2025-12 | -| [0013](0013-nixos-declarative-system-configuration.md) | NixOS Declarative System Configuration | Accepted | 2025-12 | - -## ADR Format - -Each ADR follows the [Michael Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions): - -```markdown -# ADR-NNNN: Title - -## Status -[Proposed | Accepted | Deprecated | Superseded] - -## Date -YYYY-MM - -## Context -What is the issue motivating this decision? - -## Decision -What is the change being proposed/made? - -## Consequences -What are the positive and negative results? -``` - -## Creating a New ADR - -1. Copy the template from an existing ADR -2. Number sequentially (0003, 0004, etc.) -3. Use lowercase-kebab-case for filenames -4. Update this README's index table -5. Link related ADRs in the "Related Decisions" section diff --git a/docs/blueprint/manifest.json b/docs/blueprint/manifest.json index 5b295ab..d5704fd 100644 --- a/docs/blueprint/manifest.json +++ b/docs/blueprint/manifest.json @@ -7,7 +7,14 @@ }, "project": { "name": "chezmoi", - "detected_stack": ["zsh", "lua", "shell", "mise", "chezmoi", "neovim"] + "detected_stack": [ + "zsh", + "lua", + "shell", + "mise", + "chezmoi", + "neovim" + ] }, "structure": { "has_prds": true, @@ -32,10 +39,13 @@ "derive-prd": { "enabled": true, "auto_run": false, - "last_completed_at": null, - "last_result": null, + "last_completed_at": "2026-04-07T00:00:00Z", + "last_result": "success", "schedule": "on-demand", - "stats": {}, + "stats": { + "runs_total": 1, + "items_created": 1 + }, "context": {} }, "derive-plans": { @@ -110,5 +120,17 @@ "stats": {}, "context": {} } + }, + "id_registry": { + "last_prd": 1, + "documents": { + "PRD-001": { + "path": "docs/prds/project-overview.md", + "title": "Dotfiles", + "github_issues": [], + "created": "2026-04-07" + } + }, + "github_issues": {} } } diff --git a/docs/prds/project-overview.md b/docs/prds/project-overview.md new file mode 100644 index 0000000..ce6ed74 --- /dev/null +++ b/docs/prds/project-overview.md @@ -0,0 +1,166 @@ +--- +id: PRD-001 +created: 2026-04-07 +modified: 2026-04-07 +status: Draft +version: "1.0" +relates-to: [] +github-issues: [] +name: blueprint-derive-prd +--- + +# Dotfiles — Product Requirements Document + +## Executive Summary + +### Problem Statement +Setting up a consistent, reproducible development environment across multiple machines (macOS, Linux) is time-consuming and error-prone without a managed dotfiles system. Manual configuration drifts over time, tool versions diverge, and context-specific settings (secrets, platform differences) are difficult to maintain securely. + +### Proposed Solution +A chezmoi-managed dotfiles repository that declaratively configures the full development environment: shell (Zsh), editor (Neovim), CLI tools, package management (Homebrew + mise), and AI tooling (Claude Code + MCP servers). Templates handle cross-platform differences; secret files use the `private_` prefix; exact-match directories ensure no orphaned config files. + +### Business Impact +- **Faster machine setup**: New machines fully configured via `chezmoi init && chezmoi apply` in minutes +- **Consistency**: Identical tool versions, key bindings, editor settings, and shell behavior across all machines +- **AI-augmented workflow**: Claude Code with plugins and MCP servers available consistently everywhere +- **Security**: Secrets managed via `~/.api_tokens` (never committed); gitleaks scanning on every commit + +## Stakeholders & Personas + +### Stakeholder Matrix +| Role | Name | Responsibility | +|------|------|----------------| +| Owner / Developer | Lauri Gates | All decisions, implementation, maintenance | + +### User Personas + +#### Primary: Developer (Lauri Gates) +- **Description**: Software developer working across multiple macOS machines, occasionally Linux +- **Needs**: Consistent Zsh environment, fast Neovim with LSP, reproducible tool versions, Claude Code with full plugin ecosystem +- **Pain Points**: Re-configuring tools on new machines; config drift; manual MCP server setup; forgetting which Neovim plugins are in use +- **Goals**: `chezmoi apply` fully restores the expected environment; AI tooling works out of the box on any machine + +## Functional Requirements + +### Core Features + +| ID | Feature | Description | Priority | +|----|---------|-------------|----------| +| FR-001 | Chezmoi dotfile management | Source-controlled dotfiles applied via `chezmoi apply`; templates for cross-platform differences | P0 | +| FR-002 | Zsh shell configuration | Starship prompt, FZF integration, syntax highlighting, autosuggestions, vi-mode, completions | P0 | +| FR-003 | Neovim configuration | Lua-based config with lazy.nvim, Treesitter, LSP, completion (blink.cmp), formatters, linters | P0 | +| FR-004 | Tool version management | mise manages Node, Python, Go, Rust, Bun and CLI tools via pipx/aqua backends | P0 | +| FR-005 | Package management | Homebrew Brewfile with profile-based package selection (core, dev, infra, gui) | P0 | +| FR-006 | Claude Code integration | Plugins from laurigates/claude-plugins; MCP server registry in `.chezmoidata.toml`; per-project `.mcp.json` | P1 | +| FR-007 | Secret management | API tokens in `~/.api_tokens` (sourced by mise); private files use `private_` prefix; gitleaks scanning | P0 | +| FR-008 | Cross-platform templates | Chezmoi templates handle macOS/Linux differences for shell config, tool paths, platform-specific packages | P1 | +| FR-009 | CI/CD pipeline | Smoke tests (Ubuntu/macOS), linting (shellcheck, luacheck, actionlint, stylua), secret scanning | P1 | +| FR-010 | AI-assisted development | Claude Code claude.yml workflow for AI-assisted PRs/issues; auto plugin install in CI | P2 | +| FR-011 | MCP server management | Dynamic MCP config from `.chezmoidata.toml`; enable/disable servers; per-project overrides | P1 | +| FR-012 | Task runner | justfile with standard recipes: apply, diff, lint, test, plugin management, tool updates | P1 | + +### User Stories + +- As a developer, I want `chezmoi apply` to fully configure a new machine so I can start working in under 10 minutes +- As a developer, I want Neovim LSP to work for my primary languages (Lua, Python, Shell, Go) without manual setup +- As a developer, I want Claude Code with all my plugins available on every machine without re-installing +- As a developer, I want to enable/disable MCP servers in one config file that propagates everywhere +- As a developer, I want my shell to have consistent key bindings, aliases, and completions across machines +- As a developer, I want secrets kept out of git while still being accessible to tools that need them + +## Non-Functional Requirements + +### Performance +- Shell startup time: < 500ms (measured by `time zsh -i -c exit`) +- `chezmoi apply` idempotent: no changes on second run when environment is current +- Neovim startup: < 200ms for daily use + +### Security +- No secrets in git — API tokens, credentials via `~/.api_tokens` +- Private files use `private_` chezmoi prefix (mode 600) +- gitleaks on every commit via pre-commit hook +- detect-secrets baseline maintained in `.secrets.baseline` + +### Reliability +- Smoke test CI validates setup on Ubuntu and macOS +- Docker-based smoke test for isolated environment testing +- Pre-commit hooks prevent broken commits (shellcheck, luacheck, actionlint) + +### Compatibility +- **Primary**: macOS (darwin/arm64) — Apple Silicon +- **Secondary**: Ubuntu/Debian Linux (CI, VMs) +- **Future**: NixOS (ADR-0013 documents intent) + +## Technical Considerations + +### Architecture +- **Chezmoi** as the single source of truth for all dotfiles +- **Templates** (`.tmpl` suffix) for platform/arch-specific config +- **exact_** prefix for directories where orphaned files should be removed (e.g., `exact_dot_claude/`) +- **private_** prefix for secret/sensitive config files (chmod 600) +- **mise** for all runtime tool versions; backends: `pipx:` for Python CLIs, `aqua:` for binaries +- **Brewfile** with profile-based package selection via `.chezmoidata/profiles.toml` + +### Key Configuration Files +- `.chezmoidata.toml` — MCP servers, uv_tools, platform data +- `.chezmoidata/packages.toml` — Profile-based Homebrew package registry +- `.chezmoidata/profiles.toml` — Profile activation flags +- `dot_zshrc.tmpl` — Zsh config (template) +- `private_dot_config/mise/config.toml.tmpl` — mise tools and tasks +- `private_dot_config/nvim/` — Neovim Lua configuration +- `exact_dot_claude/` — Claude Code config (exact-match semantics) + +### Dependencies +- chezmoi, mise, Homebrew (macOS), git +- Neovim 0.9+, Lua 5.1+ +- Claude Code CLI (for AI-assisted development features) + +### Integration Points +- GitHub (CI/CD, Claude Code workflows, issue/PR automation) +- Claude Code plugin marketplace (laurigates/claude-plugins) +- MCP servers: context7, sequential-thinking, pal, playwright, github + +## Success Metrics + +| Metric | Target | Measurement | +|--------|--------|-------------| +| New machine setup time | < 10 min | Manual timing | +| Shell startup time | < 500ms | `time zsh -i -c exit` | +| CI smoke test pass rate | 100% | GitHub Actions | +| Pre-commit hook pass rate | 100% on main | Git log | + +## Scope + +### In Scope +- Zsh shell configuration (prompts, plugins, completions, key bindings) +- Neovim editor configuration (Lua, plugins, LSP, formatters) +- Tool version management via mise +- Package management via Homebrew +- Claude Code configuration (plugins, skills, rules, MCP servers) +- Git configuration (delta, conventional commits, pre-commit hooks) +- CI/CD pipeline (smoke tests, linting, security scanning) +- Cross-platform templates (macOS primary, Linux secondary) +- Secret management patterns + +### Out of Scope +- GUI application configuration (beyond Brewfile cask installs) +- Windows/WSL support +- NixOS full support (intent documented in ADR-0013, not yet implemented) +- Team/organization rollout (solo project) + +## Timeline & Phases + +### Current Phase: Active Development +Ongoing improvements across all areas: AI tooling expansion, new tool integrations, Claude Code plugin development, performance optimizations. + +### Roadmap +| Phase | Focus | Status | +|-------|-------|--------| +| Foundation | Chezmoi, Zsh, Neovim, mise, Homebrew | Complete | +| AI Integration | Claude Code, plugins, MCP servers, claude.yml | Active | +| Blueprint | Blueprint development structure, PRDs, ADRs | Active | +| NixOS | Declarative system configuration (ADR-0013) | Planned | + +--- +*Generated from existing documentation via /blueprint:derive-prd* +*Review and update as project evolves* From e21bb5bf0c437caddf81f22d293533d4a585bfd3 Mon Sep 17 00:00:00 2001 From: Lauri Gates Date: Wed, 8 Apr 2026 09:10:39 +0300 Subject: [PATCH 3/5] docs: derive ADRs and PRPs from git history analysis MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ADR-0014: Profile-based package registry (packages.toml + profiles.toml) - ADR-0015: Gitleaks replacing detect-secrets for secret scanning - ADR-0016: Shell completion auto-generation pattern - PRP-001: Fish shell migration (experimental → primary) - PRP-002: NixOS implementation plan - PRP-003: Sketchybar macOS integration - Update ADR README index with new entries - Update manifest with derive-plans task completion and ID registry Co-Authored-By: Claude Opus 4.6 (1M context) --- .../0014-profile-based-package-registry.md | 47 +++++++++++++++++++ docs/adrs/0015-gitleaks-secret-detection.md | 42 +++++++++++++++++ .../0016-shell-completion-auto-generation.md | 43 +++++++++++++++++ docs/adrs/README.md | 3 ++ docs/blueprint/manifest.json | 38 ++++++++++++--- docs/prps/fish-shell-migration.md | 46 ++++++++++++++++++ docs/prps/nixos-implementation.md | 47 +++++++++++++++++++ docs/prps/sketchybar-integration.md | 44 +++++++++++++++++ 8 files changed, 304 insertions(+), 6 deletions(-) create mode 100644 docs/adrs/0014-profile-based-package-registry.md create mode 100644 docs/adrs/0015-gitleaks-secret-detection.md create mode 100644 docs/adrs/0016-shell-completion-auto-generation.md create mode 100644 docs/prps/fish-shell-migration.md create mode 100644 docs/prps/nixos-implementation.md create mode 100644 docs/prps/sketchybar-integration.md diff --git a/docs/adrs/0014-profile-based-package-registry.md b/docs/adrs/0014-profile-based-package-registry.md new file mode 100644 index 0000000..528a0dc --- /dev/null +++ b/docs/adrs/0014-profile-based-package-registry.md @@ -0,0 +1,47 @@ +# ADR-0014: Profile-Based Package Registry + +**Date**: 2026-04-08 +**Status**: Accepted +**Confidence**: High (direct evidence from codebase) + +## Context + +The Brewfile was growing large and monolithic, containing packages needed for different use cases (core tools, development, infrastructure, GUI applications) without differentiation. On a minimal machine or a CI runner, there was no easy way to install only the relevant subset. + +Commit evidence: `feat(packages): restructure into profile-based package registry` + +## Decision + +Restructure Homebrew package management into a profile-based registry: + +- `.chezmoidata/packages.toml` — Registry of all available packages grouped by profile +- `.chezmoidata/profiles.toml` — Activation flags per profile (`dev`, `infra`, `gui`, etc.) +- Chezmoi templates render only packages for active profiles into the final `Brewfile` + +Profiles: +- `core` — Always installed (chezmoi, mise, git, shell tools) +- `dev` — Development tools (neovim, ripgrep, fd, etc.) +- `dev_build` — Build dependencies +- `infra` — Infrastructure tools (terraform, kubectl, helm) +- `security` — Security scanning tools +- `embedded` — Arduino, serial tools +- `services` — Local service dependencies +- `media` — Media processing tools +- `gui` — GUI applications (cask installs) + +## Consequences + +**Positive:** +- Brewfile is now generated from a single source of truth +- Easy to enable/disable feature sets by toggling profile flags +- CI can install only `core` profile for faster smoke tests +- New machine setup can be tailored to the machine's role + +**Negative:** +- Adds complexity: changes now require editing `packages.toml` instead of `Brewfile` directly +- Template rendering adds a step between editing and seeing the final Brewfile + +## Related + +- ADR-0002: Unified Tool Version Management with Mise (complementary system for runtime tools) +- `docs/prds/project-overview.md` FR-005: Package management diff --git a/docs/adrs/0015-gitleaks-secret-detection.md b/docs/adrs/0015-gitleaks-secret-detection.md new file mode 100644 index 0000000..473b733 --- /dev/null +++ b/docs/adrs/0015-gitleaks-secret-detection.md @@ -0,0 +1,42 @@ +# ADR-0015: Gitleaks for Secret Detection + +**Date**: 2026-04-08 +**Status**: Accepted +**Confidence**: High (direct evidence from commit history) + +## Context + +Secret detection was previously handled by `detect-secrets`, which maintains a `.secrets.baseline` file of known false positives. While effective, `detect-secrets` has significant drawbacks in this repository: + +- Slow on large repos — scans all content on each run +- The baseline file requires ongoing maintenance as new "secrets" (false positives) are introduced +- Poor integration with chezmoi template syntax (`.tmpl` files contain template variables that trigger false positives constantly) +- Python dependency that adds complexity to the pre-commit setup + +Commit evidence: `chore: replace detect-secrets with gitleaks (#169)` + +## Decision + +Replace `detect-secrets` with `gitleaks` for secret detection: + +- `gitleaks` configured via `.gitleaks.toml` with custom rules and allowlists +- Runs as a pre-commit hook via `gitleaks protect --staged` +- Handles chezmoi template variables and known false positives via allowlist in `.gitleaks.toml` +- Removes `.secrets.baseline` maintenance burden + +## Consequences + +**Positive:** +- Faster scanning (Rust-based, designed for git repos) +- Configuration via `.gitleaks.toml` is more readable than JSON baseline +- Better support for chezmoi template allowlisting +- No Python runtime dependency for secret scanning + +**Negative:** +- Migration required allowlisting historical false positives in `.gitleaks.toml` +- Team members must have gitleaks installed (managed via mise/Brewfile) + +## Related + +- ADR-0010: Tiered Test Execution (pre-commit is the first tier) +- `docs/prds/project-overview.md` FR-007: Secret management diff --git a/docs/adrs/0016-shell-completion-auto-generation.md b/docs/adrs/0016-shell-completion-auto-generation.md new file mode 100644 index 0000000..629f2e1 --- /dev/null +++ b/docs/adrs/0016-shell-completion-auto-generation.md @@ -0,0 +1,43 @@ +# ADR-0016: Shell Completion Auto-Generation Pattern + +**Date**: 2026-04-08 +**Status**: Accepted +**Confidence**: Medium (inferred from scripts and commit patterns) + +## Context + +Shell completions for CLI tools (Claude Code, uv, pip, docker, kubectl, etc.) need to stay in sync with the installed tool versions. Manually maintaining completion scripts is error-prone — completions become stale after tool upgrades, leading to missing or broken tab completion. + +The completion list is large (36+ tools in `.chezmoidata/completions.toml`) and grows with each new tool added to the environment. + +Commit evidence: `fix(completions): auto-regenerate claude completions on CLI update`, `feat(completions): update Claude CLI completions for v4.6` + +## Decision + +Auto-generate shell completions rather than version-controlling static completion files: + +- `.chezmoidata/completions.toml` — Registry of all tools with their completion commands (e.g., `uv generate-shell-completion zsh`) +- Chezmoi template (`dot_zshrc.tmpl`) iterates the registry and sources completions dynamically +- For tools without built-in completion commands (e.g., Claude Code), `scripts/generate-claude-completion.sh` generates from `--help` output and the result is committed as a managed chezmoi file +- mise hook triggers Claude completion regeneration on Claude CLI version changes + +**Trade-offs considered:** +- Fully dynamic (generate at shell startup): Too slow — 36 completions would noticeably delay shell start +- Fully static (commit all completion files): Becomes stale; large diffs on tool updates +- Chosen hybrid: Dynamic for tools with fast `generate-shell-completion` support; committed files for tools that lack it + +## Consequences + +**Positive:** +- Completions stay current with tool versions automatically +- Single registry to add new tools +- Shell startup stays fast (completions are pre-generated, not runtime-computed) + +**Negative:** +- Claude CLI completions require manual regeneration when Claude Code adds new subcommands +- `generate-claude-completion.sh` is fragile (parses `--help` output) + +## Related + +- ADR-0002: Unified Tool Version Management with Mise +- `docs/prds/project-overview.md` FR-002: Zsh shell configuration diff --git a/docs/adrs/README.md b/docs/adrs/README.md index 7b583f9..92ee698 100644 --- a/docs/adrs/README.md +++ b/docs/adrs/README.md @@ -23,6 +23,9 @@ An ADR is a document that captures an important architectural decision made alon | [0011](0011-claude-rules-migration.md) | Claude Rules Migration | Accepted | 2025-12 | | [0012](0012-justfile-command-runner.md) | Justfile Command Runner | Accepted | 2025-12 | | [0013](0013-nixos-declarative-system-configuration.md) | NixOS Declarative System Configuration | Accepted | 2025-12 | +| [0014](0014-profile-based-package-registry.md) | Profile-Based Package Registry | Accepted | 2026-04 | +| [0015](0015-gitleaks-secret-detection.md) | Gitleaks for Secret Detection | Accepted | 2026-04 | +| [0016](0016-shell-completion-auto-generation.md) | Shell Completion Auto-Generation Pattern | Accepted | 2026-04 | ## ADR Format diff --git a/docs/blueprint/manifest.json b/docs/blueprint/manifest.json index d5704fd..dfba330 100644 --- a/docs/blueprint/manifest.json +++ b/docs/blueprint/manifest.json @@ -1,7 +1,7 @@ { "format_version": "3.2.0", "created_at": "2026-04-07T00:00:00Z", - "updated_at": "2026-04-07T00:00:00Z", + "updated_at": "2026-04-08T00:00:00Z", "created_by": { "blueprint_plugin": "3.2.0" }, @@ -51,11 +51,18 @@ "derive-plans": { "enabled": true, "auto_run": false, - "last_completed_at": null, - "last_result": null, + "last_completed_at": "2026-04-08T00:00:00Z", + "last_result": "success", "schedule": "weekly", - "stats": {}, - "context": {} + "stats": { + "runs_total": 1, + "items_processed": 200, + "items_created": 6 + }, + "context": { + "commits_analyzed_up_to": "afaec005957568bd34ddb0ffd2daa7b4a98a70c8", + "commits_analyzed_count": 200 + } }, "derive-rules": { "enabled": true, @@ -123,12 +130,31 @@ }, "id_registry": { "last_prd": 1, + "last_prp": 3, "documents": { "PRD-001": { "path": "docs/prds/project-overview.md", - "title": "Dotfiles", + "title": "Dotfiles — Product Requirements Document", "github_issues": [], "created": "2026-04-07" + }, + "PRP-001": { + "path": "docs/prps/fish-shell-migration.md", + "title": "Fish Shell Migration", + "github_issues": [], + "created": "2026-04-08" + }, + "PRP-002": { + "path": "docs/prps/nixos-implementation.md", + "title": "NixOS Implementation", + "github_issues": [], + "created": "2026-04-08" + }, + "PRP-003": { + "path": "docs/prps/sketchybar-integration.md", + "title": "Sketchybar macOS Integration", + "github_issues": [], + "created": "2026-04-08" } }, "github_issues": {} diff --git a/docs/prps/fish-shell-migration.md b/docs/prps/fish-shell-migration.md new file mode 100644 index 0000000..df06b45 --- /dev/null +++ b/docs/prps/fish-shell-migration.md @@ -0,0 +1,46 @@ +--- +id: PRP-001 +created: 2026-04-08 +modified: 2026-04-08 +status: Draft +confidence: 6 +source: git history (private_dot_config/private_fish/ directory existence) +relates-to: [PRD-001] +--- + +# Fish Shell Migration + +## Context + +An experimental Fish shell configuration exists in `private_dot_config/private_fish/` but Zsh remains the primary shell. Fish offers a better interactive experience out-of-the-box (better completions, syntax highlighting, autosuggestions without plugins), but migration requires porting Zsh-specific configuration. + +## Problem + +Zsh requires numerous plugins (syntax-highlighting, autosuggestions, vi-mode, fzf-tab) to match Fish's default interactive experience. Each plugin is an external dependency managed via `.chezmoiexternal.toml`. Fish provides these capabilities natively. + +## Proposed Approach + +1. **Audit Zsh → Fish feature parity**: Map all current Zsh functions, aliases, completions, and integrations to Fish equivalents +2. **Port key functions**: `ghpc`, `serial-devices`, `serial-monitor`, FZF integration, mise activation, Starship integration +3. **Handle compatibility**: Some tools (mise, Homebrew) have Fish-specific activation — verify all work +4. **Dual-shell period**: Run Fish as interactive shell while keeping Zsh for scripting compatibility +5. **Remove Zsh plugins**: Once feature-parity confirmed, remove external Zsh plugin dependencies from `.chezmoiexternal.toml` + +## Success Criteria + +- All current Zsh aliases and functions available in Fish +- Shell startup time ≤ current Zsh baseline (< 500ms) +- All tool completions (36+ from completions.toml) working +- mise, Homebrew, FZF, Starship all integrated +- CI smoke test validates Fish shell setup + +## Considerations + +- Fish is not POSIX-compatible — scripts must remain Zsh/bash +- Some tools may have weaker Fish support than Zsh +- Neovim terminal integration should be tested with Fish + +## Related + +- `docs/prds/project-overview.md` FR-002: Zsh shell configuration +- `private_dot_config/private_fish/` — existing experimental config diff --git a/docs/prps/nixos-implementation.md b/docs/prps/nixos-implementation.md new file mode 100644 index 0000000..d5397de --- /dev/null +++ b/docs/prps/nixos-implementation.md @@ -0,0 +1,47 @@ +--- +id: PRP-002 +created: 2026-04-08 +modified: 2026-04-08 +status: Draft +confidence: 5 +source: ADR-0013 (NixOS Declarative System Configuration) +relates-to: [PRD-001, ADR-0013] +--- + +# NixOS Implementation + +## Context + +ADR-0013 documents the intent to support NixOS as a secondary platform. NixOS offers declarative system configuration that complements chezmoi's dotfile management. The `nixos/` directory exists in the repository but implementation is incomplete. + +## Problem + +On NixOS, Homebrew is not available and mise has limitations (no system package management). Package installation requires Nix expressions. The current chezmoi templates don't handle NixOS-specific paths or package availability. + +## Proposed Approach + +1. **Audit NixOS compatibility**: Run chezmoi templates in NixOS environment and identify failures +2. **Add NixOS detection**: Add `{{ if eq .chezmoi.os "linux" }}` guards for Homebrew-specific sections +3. **Create home-manager config**: Use home-manager for user-level package management equivalent to Brewfile +4. **Port Brewfile to home.packages**: Map Homebrew formulas to Nix package names for active profiles +5. **Handle mise on NixOS**: Configure mise to work with Nix-managed system tools +6. **CI validation**: Add NixOS container-based smoke test + +## Success Criteria + +- `chezmoi apply` runs without errors on NixOS +- All core development tools available via Nix packages +- Neovim, Zsh, and mise working correctly +- CI smoke test on NixOS passes + +## Considerations + +- Nix package names differ from Homebrew formula names — mapping required +- home-manager is a separate dependency to bootstrap +- NixOS system-level config (`/etc/nixos/`) is outside chezmoi scope for now + +## Related + +- `docs/adrs/0013-nixos-declarative-system-configuration.md` +- `docs/prds/project-overview.md` FR-008: Cross-platform templates +- `nixos/` directory in repository root diff --git a/docs/prps/sketchybar-integration.md b/docs/prps/sketchybar-integration.md new file mode 100644 index 0000000..1405933 --- /dev/null +++ b/docs/prps/sketchybar-integration.md @@ -0,0 +1,44 @@ +--- +id: PRP-003 +created: 2026-04-08 +modified: 2026-04-08 +status: Draft +confidence: 6 +source: git history (sketchybar scope: 5 commits in last 200) +relates-to: [PRD-001] +--- + +# Sketchybar macOS Integration + +## Context + +Sketchybar is a highly customizable macOS menu bar replacement. The dotfiles include Sketchybar configuration (committed changes in `sketchybar` scope), including a GitHub repos plugin showing PR/issue counts. However, the integration is not fully documented and some components have been removed (k8s plugin, yabai click handler). + +## Problem + +Sketchybar configuration is present but: +- Not documented in README or docs/ +- Depends on yabai (tiling WM) for some features that were removed +- GitHub plugin requires a token — integration with `~/.api_tokens` not verified +- No smoke test validates Sketchybar config + +## Proposed Approach + +1. **Document current state**: Audit what plugins/widgets are active and their dependencies +2. **Verify GitHub token integration**: Ensure the GitHub repos plugin reads from `~/.api_tokens` (never hardcoded) +3. **Create Sketchybar ADR**: Document the decision to use Sketchybar vs. alternatives (Raycast bar, default menu bar) +4. **Add to README**: Document Sketchybar as optional macOS-only component +5. **Consider yabai reintegration**: Decide whether to add yabai back or keep Sketchybar standalone +6. **Brewfile integration**: Ensure Sketchybar is in the `gui` profile with correct dependencies + +## Success Criteria + +- Sketchybar config applies cleanly via `chezmoi apply` +- GitHub plugin displays PR/issue counts using `~/.api_tokens` token +- Configuration documented in README as macOS-only optional component +- Separate ADR for Sketchybar architectural decision + +## Related + +- `docs/prds/project-overview.md` FR-005: Package management (gui profile) +- `docs/adrs/0013-nixos-declarative-system-configuration.md` (macOS vs. Linux scope) From 98b6fe6e658cfbbd31c611a46e6fa93989ef7897 Mon Sep 17 00:00:00 2001 From: Lauri Gates Date: Wed, 8 Apr 2026 09:35:48 +0300 Subject: [PATCH 4/5] docs: derive Claude rules from git history patterns - chezmoi-conventions.md: template patterns, exact_/private_ prefixes, deprecation handling, source-vs-target workflow - dependency-management.md: mise backend selection, Homebrew profiles, MCP server management, upgrade patterns - Update manifest with derive-rules task completion Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/blueprint/manifest.json | 14 ++++-- exact_dot_claude/rules/chezmoi-conventions.md | 46 +++++++++++++++++++ .../rules/dependency-management.md | 38 +++++++++++++++ 3 files changed, 94 insertions(+), 4 deletions(-) create mode 100644 exact_dot_claude/rules/chezmoi-conventions.md create mode 100644 exact_dot_claude/rules/dependency-management.md diff --git a/docs/blueprint/manifest.json b/docs/blueprint/manifest.json index dfba330..4e2659c 100644 --- a/docs/blueprint/manifest.json +++ b/docs/blueprint/manifest.json @@ -67,11 +67,17 @@ "derive-rules": { "enabled": true, "auto_run": false, - "last_completed_at": null, - "last_result": null, + "last_completed_at": "2026-04-08T00:00:00Z", + "last_result": "success", "schedule": "weekly", - "stats": {}, - "context": {} + "stats": { + "runs_total": 1, + "items_processed": 200, + "items_created": 2 + }, + "context": { + "commits_analyzed_up_to": "e21bb5b" + } }, "generate-rules": { "enabled": true, diff --git a/exact_dot_claude/rules/chezmoi-conventions.md b/exact_dot_claude/rules/chezmoi-conventions.md new file mode 100644 index 0000000..5c46fa7 --- /dev/null +++ b/exact_dot_claude/rules/chezmoi-conventions.md @@ -0,0 +1,46 @@ +# Chezmoi Conventions + +Derived from git history patterns (1404 commits, 2018–2026). + +## File Naming Prefixes + +| Prefix | Meaning | Example | +|--------|---------|---------| +| `dot_` | Creates `.filename` target | `dot_zshrc.tmpl` → `~/.zshrc` | +| `private_` | Mode 0600 (owner-only) | `private_dot_config/` | +| `exact_` | Remove orphaned files in directory | `exact_dot_claude/` | +| `.tmpl` suffix | Chezmoi template with Go text/template syntax | `dot_zshrc.tmpl` | + +## Template Conventions + +- Use `{{ .chezmoi.os }}` for platform branching, not runtime detection +- Use `.chezmoidata.toml` and `.chezmoidata/` for structured template data +- Keep templates readable: extract complex logic to helper templates or scripts +- Template variables for lists (packages, completions, MCP servers) go in `.chezmoidata/` + +## Directory Semantics + +- `exact_dot_claude/` — Orphaned files auto-removed on `chezmoi apply`; critical for keeping `.claude/` clean +- `private_dot_config/` — Secret-adjacent configs; mode 0600 +- Never create a `.claude/` directory in the chezmoi source — it's gitignored and used as a runtime directory + +## Source vs Target + +- **Always edit** source files at `~/.local/share/chezmoi/` +- **Never edit** target files directly (e.g., `~/.zshrc`) +- After modifying `exact_dot_claude/rules/`, run `chezmoi apply --force ~/.claude` +- Use `chezmoi diff` to preview changes before applying + +## Script Conventions + +- `run_onchange_*` scripts execute when their template hash changes +- `run_once_*` scripts execute only on first apply +- Scripts should be idempotent — safe to re-run + +## Deprecation Patterns + +From commit history: promptly replace deprecated tools and APIs: +- `docker-compose` → `docker compose` (CLI v2) +- `vim.loop` → `vim.uv` (Neovim API) +- `detect-secrets` → `gitleaks` (secret scanning) +- `curl|sh` → setup actions (CI security) diff --git a/exact_dot_claude/rules/dependency-management.md b/exact_dot_claude/rules/dependency-management.md new file mode 100644 index 0000000..13b3d76 --- /dev/null +++ b/exact_dot_claude/rules/dependency-management.md @@ -0,0 +1,38 @@ +# Dependency Management + +Derived from git history patterns (tooling decisions across 1404 commits). + +## Tool Installation Priority + +1. **mise** with appropriate backend: + - Core runtimes: `python`, `node`, `go`, `rust`, `bun` + - Python CLIs: `pipx:` backend (runs via uvx) + - Standalone binaries: `aqua:` backend (checksum verification) +2. **uv tool install** — Python tools as isolated packages +3. **bun install -g** — JavaScript/TypeScript global packages +4. **cargo install** / **go install** — When not available via aqua +5. **brew install** — Last resort for CLI tools; primary for system packages and GUI apps + +## Homebrew Package Profiles + +Packages are managed through `.chezmoidata/packages.toml` with profile activation in `.chezmoidata/profiles.toml`: + +- `core` — Always installed +- `dev` — Development tools (default: enabled) +- `infra` — Infrastructure tools (terraform, kubectl, helm) +- `gui` — GUI applications (cask installs) +- Enable/disable profiles by toggling flags in `profiles.toml` + +## Upgrade Patterns + +- Replace deprecated tools promptly — don't maintain compatibility shims +- When upgrading, remove the old tool entirely (no dual-install period) +- Update CI workflows alongside local tooling +- Prefer tools with native completion support over manual completion scripts + +## MCP Server Management + +- Registry of available servers in `.chezmoidata.toml` under `[mcp_servers]` +- Enable/disable per server — `enabled = true/false` +- Project-specific overrides in per-project `.mcp.json` +- Use `update-ai-tools.sh` for safe updates during active sessions From c80496a54b8e890a03e7378e5a15c536877c9067 Mon Sep 17 00:00:00 2001 From: Lauri Gates Date: Wed, 8 Apr 2026 09:37:06 +0300 Subject: [PATCH 5/5] docs: update CLAUDE.md with blueprint integration - Add Blueprint Documentation section with PRD, ADRs, PRPs, and manifest references - Add docs/blueprint/README.md to sub-documentation list - Update manifest claude-md task registry Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 11 +++++++++++ docs/blueprint/manifest.json | 8 +++++--- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4a23ede..c8a2a02 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,6 +72,16 @@ pre-commit run detect-secrets --all-files - **smoke.yml** — Multi-platform (Ubuntu/macOS) linting and build - **claude.yml** — AI-assisted dev with auto plugin install from [laurigates/claude-plugins](https://github.com/laurigates/claude-plugins) +## Blueprint Documentation + +Blueprint v3.2.0 manages project documentation and rules. + +- **PRD**: `docs/prds/project-overview.md` — Feature requirements and scope +- **ADRs**: `docs/adrs/` — 16 Architecture Decision Records ([index](docs/adrs/README.md)) +- **PRPs**: `docs/prps/` — Implementation plans (fish, NixOS, sketchybar) +- **Manifest**: `docs/blueprint/manifest.json` — Configuration and task registry +- **Commands**: `/blueprint:status`, `/blueprint:execute`, `/blueprint:derive-plans` + ## Sub-documentation - `exact_dot_claude/CLAUDE.md` — Claude Code design and directory structure @@ -80,6 +90,7 @@ pre-commit run detect-secrets --all-files - `private_dot_config/CLAUDE.md` — Application configuration - `private_dot_config/nvim/CLAUDE.md` — Neovim configuration - `scripts/CLAUDE.md` — Maintenance scripts +- `docs/blueprint/README.md` — Blueprint structure overview ## Security & Release diff --git a/docs/blueprint/manifest.json b/docs/blueprint/manifest.json index 4e2659c..f747fe9 100644 --- a/docs/blueprint/manifest.json +++ b/docs/blueprint/manifest.json @@ -118,10 +118,12 @@ "claude-md": { "enabled": true, "auto_run": false, - "last_completed_at": null, - "last_result": null, + "last_completed_at": "2026-04-08T00:00:00Z", + "last_result": "success", "schedule": "on-change", - "stats": {}, + "stats": { + "runs_total": 1 + }, "context": {} }, "curate-docs": {