System Agent Family Guide

crefft > AI > System Agents

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Quick Reference

Commands are listed under the family’s own name. Claude Code 2.1.263 already claims /system, so the installed entrypoint is /crefft-system: see Installation for the copy steps, the name probe, and the discovery check. Nothing works until the definitions are copied into a discovery path.

Overview

The crefft System Agent Family is a coordinated set of specialized AI agents for comprehensive infrastructure and system analysis. Unlike ad-hoc reviews, this family provides:

1. Specialized Expertise - Each agent is an expert in its domain
2. Cost Optimization - Right model for each task (Sonnet for specialists, Opus for coordination)
3. Cross-System Analysis - Identifies systemic issues across stack layers
4. Security Focus - Defense in depth, secrets management, least privilege
5. Auto-Fix Oriented - Every issue includes remediation steps

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                       CREFFT  SYSTEM AGENT FAMILY                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│                      ┌────────────────────────────┐                         │
│                      │    SYSTEM ARCHITECT        │                         │
│                      │   (Opus - Coordinator)     │                         │
│                      └─────────────┬──────────────┘                         │
│                                    │                                         │
│  ┌────────────────────────────────────────────────────────────────────┐     │
│  │                     CORE INFRASTRUCTURE                             │     │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐                       │     │
│  │  │ DOCKER │ │ANSIBLE │ │ LINUX  │ │ VERIFY │                       │     │
│  │  │(Sonnet)│ │(Sonnet)│ │(Sonnet)│ │(Sonnet)│                       │     │
│  │  └────────┘ └────────┘ └────────┘ └────────┘                       │     │
│  └────────────────────────────────────────────────────────────────────┘     │
│                                                                              │
│  ┌────────────────────────────────────────────────────────────────────┐     │
│  │                   SECURITY & RESILIENCE                             │     │
│  │  ┌────────┐ ┌────────┐ ┌────────┐                                  │     │
│  │  │SECRETS │ │ BACKUP │ │NETWORK │                                  │     │
│  │  │(Sonnet)│ │(Sonnet)│ │(Sonnet)│                                  │     │
│  │  └────────┘ └────────┘ └────────┘                                  │     │
│  └────────────────────────────────────────────────────────────────────┘     │
│                                                                              │
│  ┌────────────────────────────────────────────────────────────────────┐     │
│  │                   INGRESS & IDENTITY                                │     │
│  │  ┌────────┐ ┌────────┐                                             │     │
│  │  │TRAEFIK │ │IDENTITY│                                             │     │
│  │  │(Sonnet)│ │(Sonnet)│                                             │     │
│  │  └────────┘ └────────┘                                             │     │
│  └────────────────────────────────────────────────────────────────────┘     │
│                                                                              │
│  ┌────────────────────────────────────────────────────────────────────┐     │
│  │                   DATA & OBSERVABILITY                              │     │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐                       │     │
│  │  │MONITOR │ │DATABASE│ │STORAGE │ │MESSAGE │                       │     │
│  │  │(Sonnet)│ │(Sonnet)│ │(Sonnet)│ │(Sonnet)│                       │     │
│  │  └────────┘ └────────┘ └────────┘ └────────┘                       │     │
│  └────────────────────────────────────────────────────────────────────┘     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Agent Specifications

Tier 1: Strategic Coordinator

System Architect

The System Architect is the strategic coordinator for all infrastructure assessments.

Responsibilities:

• Assess overall infrastructure security and configuration
• Route to appropriate specialist agents
• Synthesize findings across systems
• Identify cross-system concerns (secrets, networking, permissions)
• Provide prioritized remediation roadmap

When to Use:

• Comprehensive infrastructure review
• Production deployment readiness
• Security audit preparation
• Cross-system configuration validation

Tier 2: Core Infrastructure Specialists

Docker Reviewer

Container and Docker Compose security specialist.

Coverage:

• Dockerfile best practices and security
• Image pinning (digests vs tags)
• Container security (non-root, capabilities, read-only)
• Health checks and graceful shutdown
• Docker Compose organization
• Networking and secrets management
• Logging configuration

Reference: crefft Docker Guide

Ansible Reviewer

Ansible playbook and role review specialist.

Coverage:

• FQCN (Fully Qualified Collection Names)
• Idempotency verification
• Secrets management (vault, no hardcoded secrets)
• Role structure and organization
• Task naming and documentation
• Handler usage
• Molecule testing setup
• Inventory best practices

Reference: crefft Ansible Guide

Linux Reviewer

Linux system configuration and hardening specialist.

Coverage:

• systemd unit security hardening
• SSH configuration (sshd_config)
• sysctl security settings
• Firewall rules (nftables)
• User and permission management
• AppArmor profiles
• Automatic updates (unattended-upgrades)
• Logging and auditing (journald)

Reference: crefft Linux Guide, SSH Guide

Verify Build

CI/CD and build validation specialist.

Coverage:

• Build process validation
• Test execution and coverage
• Linting and formatting checks
• Type checking
• Dependency auditing
• CI/CD pipeline configuration
• Artifact generation

Tier 3: Security & Resilience Specialists

Secrets Reviewer

Secrets management and encryption specialist.

Coverage:

• SOPS/age encryption configuration
• Plaintext secret detection
• Docker secrets usage
• CI/CD secret injection
• Ansible vault usage
• Key rotation and lifecycle
• Secret access control

Backup Reviewer

Backup strategy and disaster recovery specialist.

Coverage:

• 3-2-1 backup rule compliance
• RTO/RPO documentation
• Database backup (pgBackRest)
• Filesystem backup (restic, borg, ZFS)
• Backup automation and scheduling
• Recovery testing verification
• Retention policies
• Backup encryption

Networking Reviewer

Network security and configuration specialist.

Coverage:

• Firewall configuration (nftables)
• DNS configuration (DoT, DNSSEC)
• Reverse proxy setup (Traefik)
• VPN configuration (Tailscale, WireGuard)
• TLS/SSL configuration
• Network segmentation
• Port exposure analysis
• IPv6 configuration

Tier 4: Data & Observability Specialists

Monitoring Reviewer

Observability and alerting specialist.

Coverage:

• Prometheus scrape configuration
• Metrics cardinality management
• Alert rules design
• Recording rules optimization
• Grafana dashboard design
• Log aggregation (Loki)
• SLO/SLI definitions
• Retention and storage policies

Database Reviewer

PostgreSQL configuration and operations specialist.

Coverage:

• PostgreSQL configuration tuning
• Connection pooling (PgBouncer, PgCat)
• Replication configuration
• Backup configuration (pgBackRest)
• Security hardening
• Performance monitoring
• Maintenance (autovacuum)
• High availability setup

Storage Reviewer

Storage infrastructure specialist (S3-compatible and ZFS).

Coverage:

• Garage (S3-compatible) configuration
• Bucket policies and access control
• Object lifecycle policies
• ZFS pool configuration
• ZFS dataset properties
• Snapshot and replication
• Scrub and maintenance
• Storage encryption

Messaging Reviewer

Messaging infrastructure specialist (MQTT and Kafka).

Coverage:

• EMQX broker configuration
• MQTT ACL and authentication
• EMQX clustering
• Kafka broker configuration
• Kafka topic design
• Consumer configuration
• Schema management
• Message retention policies

Tier 5: Ingress & Identity Specialists

Traefik Reviewer

Reverse proxy and ingress specialist.

Coverage:

• TLS configuration
• Let’s Encrypt / ACME
• Security headers middleware
• Rate limiting
• Entry points configuration
• Docker provider labels
• Access logging
• Service health checks

Identity Reviewer

Identity and access management specialist (Authentik).

Coverage:

• OIDC/OAuth2 provider configuration
• SAML service provider configuration
• LDAP provider configuration
• MFA/authentication policies
• Flow design
• Outpost configuration
• Session and token management
• Group and permission management

## System Review: [Brief Title]

| Metric | Value |
|--------|-------|
| **Review Effort** | [1-5] |
| **Risk Level** | Low / Medium / High / Critical |
| **Environment** | Development / Staging / Production |

### 🔴 Critical (must fix before deployment)

- [ ] **[Category]**: [description] (`file:line`)

  **Current**:
  ```[lang]
  [problematic config]
  ```

  **Recommended**:

  ```[lang]
  [fixed config]
  ```

  **Why**: [explanation with crefft reference]

### 🟡 Warning (should fix)

### 🔵 Suggestion (consider)

### ✅ Positive Observations

### Summary

[1-2 sentence overall assessment]

Cross-System Analysis

The System Architect identifies issues that span multiple systems:

Secrets Management

Network Security

User/Permission Model

Cost Optimization

Cost by Mode:

Workflow Examples

Example 1: Production Deployment Review

sequenceDiagram
    participant Ops as Operator
    participant SA as System Architect
    participant DR as Docker Reviewer
    participant AR as Ansible Reviewer
    participant LR as Linux Reviewer

    Ops->>SA: /system (production stack)
    SA->>SA: Analyze infrastructure scope
    SA->>DR: Docker stacks detected
    SA->>AR: Ansible roles detected
    SA->>LR: Linux configs detected
    DR-->>SA: 1 Critical, 2 High
    AR-->>SA: 0 Critical, 3 High
    LR-->>SA: 1 Critical, 1 High
    SA->>SA: Synthesize + cross-system analysis
    SA->>Ops: Consolidated Report + Roadmap

Example 2: Docker Stack Review

sequenceDiagram
    participant Dev as Developer
    participant SA as System Architect
    participant DR as Docker Reviewer

    Dev->>SA: /system docker stacks/platform/
    SA->>DR: Review Docker stack
    DR-->>SA: Security findings
    SA->>Dev: Docker-focused report
    Dev->>Dev: Fix issues
    Dev->>SA: Re-review
    SA-->>Dev: ✅ Approved

$ claude --settings '{"agents":{"system":{"enabled":true}}}' \
    --agent system-architect -p 'Return OK.'
--agent 'system-architect' not found. Available agents: claude, Explore,
general-purpose, Plan, statusline-setup

mkdir -p .claude/agents/system
cp configs/claude/agents/system/*.md .claude/agents/system/

mkdir -p .claude/skills/crefft-system
cp configs/claude/commands/system.md .claude/skills/crefft-system/SKILL.md

---
description: Route an infrastructure review to the crefft system agent family.
---

$ HOME="$(mktemp -d)" claude --safe-mode -p '/crefft-system probe'
Unknown command: /crefft-system

$ HOME="$(mktemp -d)" claude --safe-mode -p '/system probe'
Not logged in · Please run /login

claude --agent crefft-discovery-probe -p 'noop' 2>&1 |
  grep -q system-architect && echo 'system agents discovered'

Pin the session agent (optional)

To run a whole session as one reviewer rather than delegating to it, set the documented agent key in .claude/settings.json:

{
  "agent": "system-architect"
}

--agent overrides this key for a single session.

Best Practices

Future Agents

Planned additions to the System Agent Family:

See Also

• Code Agent Family — Code quality review agents
• Security Agent Family — Security-focused agents
• Claude Code CLI — CLI configuration

Last Updated: 2026-01-02 Version: 3.0.0