Declarative system configuration for macOS via Nix Flakes.
# One command to rule them all
darwin-rebuild switch --flake ~/dotfilesThis single command:
- Rebuilds nix-darwin system configuration
- Applies Home Manager user configuration
- Generates Quality System artifacts (skills, personas, memories)
- Symlinks Claude Code/Desktop config
- Validates all checks pass
┌─────────────────────────────────────────────────────────────────────────┐
│ Nix Flakes │
│ flake.nix → flake/ │
│ ├── darwin.nix (macOS system config) │
│ ├── home.nix (user environment) │
│ └── checks.nix (CI validation) │
└─────────────────────────────────────────────────────────────────────────┘
│
darwin-rebuild switch
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Quality System │
│ config/quality/src/ │
│ ├── memories/ (17 engineering patterns) │
│ ├── critic-mode/ (5 metacognitive behaviors) │
│ ├── skills/ (9 domain skills) │
│ ├── personas/ (6 AI personas) │
│ ├── rules/ (12 AST-based rules) │
│ ├── stack/ (frozen versions SSOT) │
│ └── hooks/ (PARAGON enforcement) │
└─────────────────────────────────────────────────────────────────────────┘
│
bun run generate
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Generated Output │
│ config/quality/generated/ │
│ ├── memories.md (canonical engineering knowledge) │
│ ├── critic-mode.md (self-review protocol) │
│ ├── settings.json (Claude Code settings) │
│ ├── skills/ (SKILL.md files) │
│ └── personas/ (persona.md files) │
└─────────────────────────────────────────────────────────────────────────┘
│
Home Manager symlinks
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Runtime Config │
│ ~/.claude/ │
│ ├── settings.json → generated/settings.json │
│ ├── skills/ → generated/skills/ │
│ └── agents/ → generated/personas/ │
│ │
│ ~/.config/claude/mcp-servers.json (12 MCP servers) │
└─────────────────────────────────────────────────────────────────────────┘
The Quality System is a TypeScript-based code quality framework that generates Claude Code configuration from a single source of truth.
| Component | Count | Description |
|---|---|---|
| Memories | 17 | Engineering patterns (principles, constraints, patterns, gotchas) |
| Critic Behaviors | 5 | Metacognitive protocols (3 planning, 2 execution) |
| Skills | 9 | Domain expertise (Effect-TS, testing, observability, etc.) |
| Personas | 6 | AI agent configurations (effect-architect, debugger, etc.) |
| Rules | 12 | AST-based code validation (no-any, no-try-catch, etc.) |
49 quality guards enforced at multiple layers:
| Layer | Mechanism |
|---|---|
| Claude | PreToolUse hooks (paragon-guard.ts) |
| Git | pre-commit hooks (git-hooks.nix) |
| CI | GitHub Actions (paragon-check.yml) |
Blocking guards: bash safety, conventional commits, forbidden files/imports, any type, z.infer, no-mock, TDD, DevOps files/commands, assumption language
6 Model Context Protocol servers configured (optimized Jan 2026):
| Server | Purpose |
|---|---|
| ref | SOTA documentation search (60-95% fewer tokens) |
| exa | Code context search across repos |
| github | GitHub API integration |
| playwright | Browser automation |
| ast-grep | AST-based code search |
| repomix | Codebase packaging for AI |
# Run Quality System tests
cd config/quality && bun test
# Regenerate artifacts
cd config/quality && bun run generate
# Full validation
cd config/quality && bun run validate
# Check Nix flake
nix flake check
# Rebuild system
darwin-rebuild switch --flake ~/dotfiles~/dotfiles/
├── flake.nix # Nix flake entry point
├── flake/ # Flake modules
│ ├── darwin.nix # macOS system config
│ ├── home.nix # User environment
│ └── checks.nix # CI validation
├── modules/ # Nix modules
│ ├── darwin/ # nix-darwin modules
│ └── home/ # Home Manager modules
├── config/ # Configuration sources
│ ├── quality/ # Quality System (TypeScript)
│ └── agents/ # Claude Code agent configs
└── .github/workflows/ # CI workflows
- TypeScript types are SSOT: Define Effect Schema first, derive types via
Schema.Type - Result types for errors: Never throw, use
Effect<A, E, R>orEither<A, E> - Parse at boundaries:
Schema.decodeUnknownat entry points, trust types internally - Single source of truth: versions.ts for deps, ports.nix for ports
- Conventional commits:
type(scope): description