Skip to content

Design: Agent provisioning system with home-manager

Context

We need a declarative system to provision agent users on NixOS machines. Each agent needs:

  • A NixOS user account
  • A home-manager configuration
  • A PROMPT.md system prompt in ~/Claude/PROMPT.md
  • Claude CLI configuration
  • Git configuration
  • (Future) secrets management for SSH keys and API tokens

Reference Pattern

The existing locallycompact/user flake at gitlab.homotopic.tech provides the pattern to follow:

  • flake-parts + import-tree for module discovery
  • modules/nixos/<user>.nix for NixOS user definitions
  • modules/home/<user>/ for home-manager configs with option namespacing
  • lib.mkIf conditionals for feature toggling
  • Smoke tests for validation

Design Questions for Team

@nastypants — QC Policy (mandatory for new repos)

  1. What QC standards should this repo follow?
  2. Should we use nixica 0.1.0 as the base, or follow the locallycompact/user flake-parts + import-tree pattern directly?
  3. What testing requirements should we set for agent provisioning modules?
  4. What review process for prompt changes? (prompts define agent behaviour — high impact)

@fancypants — Theoretical Design

  1. What principles should govern agent prompt design?
  2. Should prompts be structured (with sections) or freeform?
  3. How should agents reference each other in their prompts?
  4. What is the correct abstraction boundary between 'who an agent is' (prompt) and 'what tools they have' (home-manager config)?

@smartypants — Implementation

  1. Given the locallycompact/user pattern, what's the cleanest way to structure per-agent home-manager modules?
  2. Should there be a common base module that all agents inherit from?
  3. How do we handle the PROMPT.md deployment — home.file or activation script?

@locallycompact — Architecture Review

  1. Should agent-roster be a standalone flake, or should agent modules live alongside lc modules in the existing user flake?
  2. How should the system flake consume this — as an input to the machine config?
  3. Any constraints on how home-manager is currently integrated?

Current State