Skip to content

Module specification: agent option types and PROMPT.md generation

Overview

Define the Nix module types for the agent-roster flake, based on the design agreed in #1.

Module Specification

Agent Option Type

options.agents = lib.mkOption {
  type = lib.types.attrsOf (lib.types.submodule {
    options = {
      role = lib.mkOption { type = lib.types.str; };
      principles = lib.mkOption { type = lib.types.listOf lib.types.str; };
      delegation = lib.mkOption {
        type = lib.types.attrsOf lib.types.str;
        description = "Role-based delegation map. Must include 'escalation' key.";
      };
      context = lib.mkOption {
        type = lib.types.submodule {
          options.workingDirectory = lib.mkOption { type = lib.types.str; };
        };
      };
      constraints = lib.mkOption { type = lib.types.listOf lib.types.str; };
    };
  });
};

PROMPT.md Generation

Each agent's PROMPT.md is generated from the structured options at activation time:

# Role
${agent.role}

# Principles
${lib.concatMapStringsSep "\n" (p: "- ${p}") agent.principles}

# Delegation
${lib.concatMapStringsSep "\n" (name: "- ${name}: @${agent.delegation.${name}}") (builtins.attrNames agent.delegation)}

# Context
- Working directory: ${agent.context.workingDirectory}

# Constraints
${lib.concatMapStringsSep "\n" (c: "- ${c}") agent.constraints}

Structural Validation Assertions (7 rules from @nastypants)

  1. All five sections present (enforced by option types — non-optional)
  2. Role is non-empty
  3. Principles is non-empty (at least one)
  4. Delegation references valid agents (builtins.hasAttr check)
  5. Delegation includes escalation key pointing to valid agent
  6. Context includes workingDirectory (enforced by option type)
  7. Constraints is non-empty (at least one)

Authority Model

  • Mediation Law: every agent has escalation pointing to a universal mediator
  • Task delegation cycles are allowed (collaborative back-and-forth)
  • Authority escalation must terminate at universal mediator (@locallycompact)

Home-Manager Integration

Each agent gets:

  • NixOS user account
  • home-manager config with PROMPT.md deployed to ~/Claude/PROMPT.md
  • SSH public key (if provided)
  • Shell configuration

Acceptance Criteria

  • nix flake check passes with all 7 structural assertions
  • PROMPT.md generated correctly for each defined agent
  • At least one agent (bossypants) defined as proof of concept
  • @nastypants QC review passed
  • @fancypants theoretical review passed

References

/cc @smartypants @nastypants @fancypants @locallycompact