docs: initialize blueprint development structure

.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.*

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
 

docs/adr/0011-claude-rules-migration.md → docs/adrs/0011-claude-rules-migration.md

@@ -142,7 +142,7 @@ Rules load in this order (lower number = loaded first, higher takes precedence):
 - `.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
+- `docs/adrs/0001-chezmoi-exact-directory-strategy.md` - Related decision on `exact_` prefix for `.claude/` management
 
 ## References
 

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

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

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

docs/adr/README.md → 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
 

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
+```

docs/blueprint/manifest.json

@@ -0,0 +1,170 @@
+{
+  "format_version": "3.2.0",
+  "created_at": "2026-04-07T00:00:00Z",
+  "updated_at": "2026-04-08T00: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": "2026-04-07T00:00:00Z",
+      "last_result": "success",
+      "schedule": "on-demand",
+      "stats": {
+        "runs_total": 1,
+        "items_created": 1
+      },
+      "context": {}
+    },
+    "derive-plans": {
+      "enabled": true,
+      "auto_run": false,
+      "last_completed_at": "2026-04-08T00:00:00Z",
+      "last_result": "success",
+      "schedule": "weekly",
+      "stats": {
+        "runs_total": 1,
+        "items_processed": 200,
+        "items_created": 6
+      },
+      "context": {
+        "commits_analyzed_up_to": "afaec005957568bd34ddb0ffd2daa7b4a98a70c8",
+        "commits_analyzed_count": 200
+      }
+    },
+    "derive-rules": {
+      "enabled": true,
+      "auto_run": false,
+      "last_completed_at": "2026-04-08T00:00:00Z",
+      "last_result": "success",
+      "schedule": "weekly",
+      "stats": {
+        "runs_total": 1,
+        "items_processed": 200,
+        "items_created": 2
+      },
+      "context": {
+        "commits_analyzed_up_to": "e21bb5b"
+      }
+    },
+    "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": "2026-04-08T00:00:00Z",
+      "last_result": "success",
+      "schedule": "on-change",
+      "stats": {
+        "runs_total": 1
+      },
+      "context": {}
+    },
+    "curate-docs": {
+      "enabled": false,
+      "auto_run": false,
+      "last_completed_at": null,
+      "last_result": null,
+      "schedule": "on-demand",
+      "stats": {},
+      "context": {}
+    }
+  },
+  "id_registry": {
+    "last_prd": 1,
+    "last_prp": 3,
+    "documents": {
+      "PRD-001": {
+        "path": "docs/prds/project-overview.md",
+        "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": {}
+  }
+}