+babysitter
This commit is contained in:
@@ -0,0 +1,238 @@
|
||||
# Project Profile: nixos-config
|
||||
|
||||
A reliable, elegant, multi-system NixOS flake configuration for personal desktop, server, cloud, Home Manager, package, overlay, and secret management.
|
||||
|
||||
> Last updated: 2026-05-29T16:02:11.092188Z | Version: 1
|
||||
|
||||
## Goals
|
||||
|
||||
- **reliability** [high]: Keep all managed NixOS systems reproducible, reliable, and easy to validate before deployment. (active)
|
||||
- **architecture** [high]: Maintain an elegant multi-system architecture with clear host boundaries and reusable common modules. (active)
|
||||
- **modularization** [high]: Continue breaking up the former monorepo by keeping Home Manager profiles in m3ta-home and custom packages/modules in m3ta-nixpkgs where appropriate. (active)
|
||||
- **automation** [medium]: CI/CD is not currently configured; add useful Gitea Actions validation later for formatting, linting, flake evaluation, and safe host checks. (deferred)
|
||||
|
||||
## Tech Stack
|
||||
|
||||
### Languages
|
||||
|
||||
- Nix (primary system, module, overlay, and package configuration language)
|
||||
- Markdown (project, agent, and workflow documentation)
|
||||
- JSON/YAML (tool configuration and metadata)
|
||||
|
||||
### Frameworks
|
||||
|
||||
- Nix flakes [reproducible dependency and output model]
|
||||
- NixOS modules [host and service configuration]
|
||||
- Home Manager [user environment management]
|
||||
- Agenix [encrypted secret management]
|
||||
- Disko [server disk provisioning]
|
||||
- NUR [community package access]
|
||||
- llm-agents.nix [LLM agent packages overlay]
|
||||
- m3ta-home [external reusable Home Manager profiles]
|
||||
- m3ta-nixpkgs [external custom packages/modules/overlays]
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- m3-ares [desktop NixOS host]
|
||||
- m3-kratos [desktop NixOS host]
|
||||
- m3-daedalus [portable laptop/Home Manager configuration]
|
||||
- m3-atlas [primary server NixOS host]
|
||||
- m3-helios [minimal server/AdGuard host]
|
||||
- m3-hermes [secondary server/Hermes host]
|
||||
- m3-aether [cloud VM/minimal server host]
|
||||
|
||||
**Build tools:** nix, nixos-rebuild, nix build, nix flake show, alejandra, statix, deadnix
|
||||
|
||||
**Package managers:** nix flakes
|
||||
|
||||
## Architecture
|
||||
|
||||
**Pattern:** Pure Nix flake-based NixOS configuration repository with host-specific modules, common shared modules, overlays, custom packages, agenix secrets, and externalized Home Manager/package inputs.
|
||||
**Data flow:** flake.nix wires inputs, overlays, packages, NixOS modules, and Home Manager. Host modules import common configuration and host-specific hardware/programs/services/secrets. Host profile flags in hosts/common/users/m3tam3re.nix feed the external m3ta-home mkHome integration. Secrets flow through agenix registry and host secret modules.
|
||||
|
||||
### Modules
|
||||
|
||||
| Module | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| flake.nix | `flake.nix` | Top-level entry point defining inputs, packages, overlays, Home Manager modules, NixOS configurations, and dev shells. |
|
||||
| hosts/common | `hosts/common` | Shared NixOS configuration, nix settings, overlays, Home Manager setup, ports, extra services, and users. |
|
||||
| hosts | `hosts` | Per-host NixOS/Home Manager configurations for desktops, servers, and cloud VM. |
|
||||
| modules/nixos | `modules/nixos` | Reusable NixOS modules. |
|
||||
| modules/home-manager | `modules/home-manager` | Reusable Home Manager module exports. |
|
||||
| overlays | `overlays` | Nixpkgs overlays for stable, locked, pinned, master, temporary, and agent packages. |
|
||||
| pkgs | `pkgs` | Custom package export set. |
|
||||
| secrets | `secrets` | Encrypted agenix secret files and registry. |
|
||||
|
||||
**Entry points:** `flake.nix`, `hosts/<host>/default.nix`, `hosts/<host>/configuration.nix`, `hosts/common/default.nix`, `hosts/common/users/m3tam3re.nix`, `overlays/default.nix`, `pkgs/default.nix`, `secrets.nix`
|
||||
|
||||
## Team
|
||||
|
||||
- **m3tam3re** (solo developer and operator): architecture, implementation, host maintenance, deployments, review
|
||||
- **m3ta-chiron** (agent contributor): semi-autonomous implementation, validation, documentation updates, conventional commits
|
||||
|
||||
## Workflows
|
||||
|
||||
### development
|
||||
|
||||
Default feature-branch workflow for solo development with conventional commits and validation before push.
|
||||
**Triggers:** new feature, bug fix, refactor, agent task
|
||||
|
||||
1. review Beads issues with bd ready --json
|
||||
2. claim work with bd update <id> --claim when applicable
|
||||
3. edit Nix modules or project files
|
||||
4. run alejandra .
|
||||
5. run statix check .
|
||||
6. run targeted nix flake or host dry-run checks
|
||||
7. commit with conventional commit format
|
||||
8. pull --rebase and push
|
||||
|
||||
### nix validation
|
||||
|
||||
Quality gate for Nix configuration changes.
|
||||
**Triggers:** Nix code changes, before deployment, before commit
|
||||
|
||||
1. alejandra .
|
||||
2. statix check .
|
||||
3. deadnix check or deadnix -w when appropriate
|
||||
4. nix flake show
|
||||
5. sudo nixos-rebuild dry-run --flake .#<host> for affected hosts
|
||||
|
||||
### host deployment
|
||||
|
||||
Manual deployment after successful dry-run validation.
|
||||
**Triggers:** manual host update
|
||||
|
||||
1. sudo nixos-rebuild dry-run --flake .#<host>
|
||||
2. sudo nixos-rebuild switch --flake .#<host>
|
||||
|
||||
### dependency/input update
|
||||
|
||||
Controlled flake input updates without manually editing flake.lock.
|
||||
**Triggers:** planned dependency update, security update
|
||||
|
||||
1. use nix flake update or nixos-rebuild --update-input <input>
|
||||
2. validate affected outputs
|
||||
3. commit flake.nix/flake.lock changes
|
||||
|
||||
### beads issue tracking
|
||||
|
||||
Persistent issue tracking and session handoff workflow.
|
||||
**Triggers:** start of tracked work, completion of tracked work
|
||||
|
||||
1. bd ready --json
|
||||
2. bd show <id>
|
||||
3. bd update <id> --claim
|
||||
4. bd close <id> --reason <summary>
|
||||
5. bd dolt push
|
||||
|
||||
## Processes
|
||||
|
||||
- **Babysitter project install** (`cradle/project-install`, undefined)
|
||||
|
||||
## Tools
|
||||
|
||||
### Linting
|
||||
|
||||
- statix
|
||||
- deadnix
|
||||
|
||||
### Testing
|
||||
|
||||
- nix flake show
|
||||
- nixos-rebuild dry-run
|
||||
- nix build
|
||||
|
||||
### Formatting
|
||||
|
||||
- alejandra
|
||||
|
||||
## Services
|
||||
|
||||
- **code.m3ta.dev** (git hosting) - git+ssh://gitea@code.m3ta.dev
|
||||
- **GitHub** (flake input hosting) - github:* flake inputs
|
||||
- **Agenix** (secret encryption) - github:ryantm/agenix
|
||||
- **Hermes Agent** (NixOS module/agent service) - github:NousResearch/hermes-agent
|
||||
- **RustFS** (NixOS server service flake) - github:rustfs/rustfs-flake
|
||||
|
||||
## CI/CD
|
||||
|
||||
**Status:** Not configured/enabled for now.
|
||||
|
||||
No Babysitter CI/CD workflow is currently installed. If CI/CD is added later, prefer Gitea Actions because this repository is hosted on code.m3ta.dev.
|
||||
|
||||
## Pain Points
|
||||
|
||||
- **high** [architecture]: The repository is transitioning away from a monorepo; boundaries with m3ta-home and m3ta-nixpkgs must remain clear.
|
||||
- Remediation: Keep host-specific decisions local while moving reusable Home Manager profiles and package/module abstractions to their dedicated inputs.
|
||||
- **medium** [validation]: A single shared Nix change can require validating several hosts to be confident.
|
||||
- Remediation: Use targeted affected-host validation locally for now; add a Gitea Actions validation matrix later if CI/CD is re-enabled.
|
||||
- **medium** [dependency management]: Multiple pinned, locked, stable, master, and external SSH flake inputs increase update complexity.
|
||||
- Remediation: Update inputs intentionally, group related updates, and validate affected host outputs.
|
||||
- **medium** [operations]: Service additions often need synchronized module, secret, and network/TLS changes.
|
||||
- Remediation: Use checklist-style issue templates or Babysitter processes for service changes.
|
||||
|
||||
## Bottlenecks
|
||||
|
||||
- flake.nix and flake.lock are high-churn files whose changes can affect many hosts at once. at flake.nix, flake.lock (very frequent)
|
||||
Impact: High; evaluation failures can block all hosts.
|
||||
- Secret registry and host secret modules must stay aligned with encrypted .age files. at secrets.nix, hosts/*/secrets.nix, secrets/*.age (recurring)
|
||||
Impact: Medium to high; missing or mismatched secrets break host deployment.
|
||||
- Server service changes can span service modules, secrets, Traefik/networking, and flake inputs. at hosts/m3-atlas/services, hosts/m3-hermes/services, hosts/common (frequent)
|
||||
Impact: High for m3-atlas and m3-hermes changes; requires host-specific dry-runs.
|
||||
- Home Manager behavior depends on both the external m3ta-home input and local host flags. at flake.nix, hosts/common/users/m3tam3re.nix, m3ta-home input (frequent after migration)
|
||||
Impact: Medium; may require coordinated updates across repositories.
|
||||
|
||||
## Conventions
|
||||
|
||||
### Naming
|
||||
|
||||
- **files:** hyphen-case for Nix/docs where practical; host directories use m3-* names
|
||||
- **hosts:** m3-<greek-name>
|
||||
- **modules:** one module per file/directory where possible
|
||||
- **nixVariables:** camelCase
|
||||
|
||||
### Git
|
||||
|
||||
- **branchStrategy:** default feature branches for non-trivial work; master as integration branch
|
||||
- **commits:** conventional commits for agent work
|
||||
- **reviews:** optional for solo development
|
||||
- **releaseCadence:** continuous/manual as needed
|
||||
- **remote:** code.m3ta.dev over SSH for private inputs and repo access
|
||||
|
||||
**Import order:** module function arguments > imports > let bindings > options/config
|
||||
|
||||
**Error handling:** Nix configuration should fail explicitly during evaluation/build; avoid hiding errors or impure paths.
|
||||
|
||||
**Testing:** Run alejandra, statix, deadnix as appropriate, nix flake show, and host-specific nixos-rebuild dry-run before switching.
|
||||
|
||||
### Additional Rules
|
||||
|
||||
- Use Beads for persistent task tracking.
|
||||
- Use non-interactive flags for shell file operations.
|
||||
- Do not modify flake.lock directly; use nix flake update.
|
||||
- Do not commit plaintext secrets.
|
||||
- Use SSH URLs for code.m3ta.dev flake inputs.
|
||||
- Operate Babysitter semi-autonomously with breakpoints for destructive, deployment, or architecture-changing decisions.
|
||||
|
||||
## Repositories
|
||||
|
||||
- **nixos-config** [`/home/m3tam3re/p/NIX/nixos-config`]
|
||||
- **m3ta-home** - git+ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-home
|
||||
- **m3ta-nixpkgs** - git+ssh://gitea@code.m3ta.dev/m3tam3re/nixpkgs
|
||||
|
||||
## CLAUDE.md Instructions
|
||||
|
||||
- Respect AGENTS.md as the source of project workflow rules.
|
||||
- Resolve the active Babysitter process library before using library processes.
|
||||
- Use cradle/project-install for project setup or profile refresh.
|
||||
- Use evolutionary GSD: map affected Nix modules/hosts, make focused changes, verify, and iterate.
|
||||
- Prefer alejandra, statix, deadnix, nix flake show, and targeted host dry-runs for Nix changes.
|
||||
- Preserve boundaries between nixos-config, m3ta-home, and m3ta-nixpkgs.
|
||||
- Use breakpoints for destructive operations, deployments, architecture changes, and secret-handling decisions.
|
||||
- Babysitter CI/CD is not currently enabled; if re-added later, use Gitea Actions rather than GitHub Actions.
|
||||
|
||||
## Installed Extensions
|
||||
|
||||
- Skills: project-install, babysit, specializations/devops-sre-platform/skills/cicd-pipelines/SKILL.md, specializations/devops-sre-platform/skills/gitops/SKILL.md, specializations/devops-sre-platform/skills/secrets-management/SKILL.md
|
||||
- Agents: general-purpose, specializations/devops-sre-platform/agents/platform-engineer/AGENT.md, specializations/devops-sre-platform/agents/cicd-specialist/AGENT.md
|
||||
- Processes: cradle/project-install, methodologies/gsd/quick.js, methodologies/gsd/verify-work.js, methodologies/gsd/iterative-convergence.js, methodologies/evolutionary.js, specializations/devops-sre-platform/iac-testing.js
|
||||
Reference in New Issue
Block a user