Claude Code

Project-Level Agents

Infrastructure-specific specialists loaded from ~/projects/.claude/agents/

ai-servicers.com

What Are Project-Level Agents?

Project-level agents are infrastructure-specific specialists scoped to the linuxserver.lan workspace. They handle the actual implementation work — architecture design, code deployment, and security configuration — and are typically coordinated by the PM agent for multi-phase projects.

Where They Live

  • Location: ~/projects/.claude/agents/
  • Scoped to this infrastructure workspace
  • 4 agents: Architect, Developer, Security, QA
  • Each has its own role, tools, and expertise

vs User-Level Agents

  • User-level (PM) — orchestrates, coordinates, reports
  • Project-level — executes specialized tasks
  • Project agents are invoked by PM or directly
  • Each agent escalates gaps to the appropriate peer
Project Agent

Architect

System design and architecture specialist — designs robust, scalable systems with expertise in Docker, databases, networking, and microservices.

Core Expertise

  • System architecture design and patterns
  • Technology stack evaluation and selection
  • Service integration and API design
  • Performance and scalability analysis
  • Database architecture and data modeling
  • Container orchestration patterns
  • Security architecture considerations

Technical Profile

  • Model: Claude Sonnet
  • Tools: Read, Write, Grep, Glob, Bash
  • File: ~/projects/.claude/agents/architect.md

Escalates To

  • Developer — implementation feasibility feedback
  • Security — network feasibility, security review
  • PM — trade-off decisions, requirements clarification
Project Agent

Developer

Implementation and deployment specialist — writes code, deploys containers, debugs services, and manages databases hands-on.

Core Expertise

  • Python development (FastAPI, Flask, Django)
  • Docker and docker-compose deployment
  • Database operations (PostgreSQL, MongoDB, Redis)
  • Container debugging and log analysis
  • CI/CD and deployment automation
  • API development and integration
  • Performance optimization and monitoring

Technical Profile

  • Model: Claude Sonnet
  • Tools: Read, Write, Edit, Grep, Glob, Bash
  • File: ~/projects/.claude/agents/developer.md

Escalates To

  • Architect — design gaps, architecture flaws
  • Security — routing, auth, network changes needed
  • PM — blockers, scope changes
Project Agent

Security

Security and network infrastructure specialist — configures Traefik routing, Keycloak OAuth2, SSL/TLS certificates, and Docker networking.

Core Expertise

  • Network topology and Docker networking
  • Traefik reverse proxy configuration
  • SSL/TLS certificate management (Let's Encrypt)
  • Keycloak SSO and OAuth2/OIDC authentication
  • Firewall rules and network security
  • Security hardening and vulnerability assessment
  • Authentication and authorization patterns

Technical Profile

  • Model: Claude Sonnet
  • Tools: Read, Write, Grep, Glob, Bash
  • File: ~/projects/.claude/agents/security.md

Escalates To

  • Architect — architecture context, dependencies
  • Developer — implementation, testing validation
  • PM — security trade-offs, compliance decisions
Project Agent

QA

Quality assurance specialist — creates tests from developer specifications, runs them via GitLab CI pipelines, validates deployments, and enforces quality gates.

Core Expertise

  • Test creation from developer specifications
  • GitLab CI pipeline integration and monitoring
  • Quality gate enforcement
  • Deployment validation and health checks
  • Service health verification
  • Specification compliance testing
  • Regression and integration testing

Technical Profile

  • Model: Claude Sonnet
  • Tools: Read, Write, Edit, Grep, Glob, Bash
  • File: ~/projects/.claude/agents/qa.md

Escalates To

  • Developer — failing tests, implementation bugs
  • Architect — design-level quality concerns
  • PM — quality trade-offs, release readiness

How Agents Coordinate

PM
Orchestrates
User-level
→
Arch
Designs
Project-level
→
Sec
Configures
Project-level
→
Dev
Implements
Project-level
→
QA
Validates
Project-level

File-Based Communication

  • Agents write decisions to ~/projects/data/claudeagents/{agent}/
  • Downstream agents read upstream agent output
  • Developer reads both Architect and Security decisions before building
  • Escalations filed as structured markdown files

Escalation Protocol

  • Any agent can escalate a blocker to another
  • Escalations go to escalations/{target}/{project}/
  • PM monitors and re-routes as needed
  • "1 hop" rule — escalated tasks are not re-delegated

Project-Level Agents — Summary

4 Project Agents
Architect Designs Systems
Security Configures Network
Developer Implements & Deploys
QA Validates & Tests

Project-level agents execute specialized tasks within this infrastructure. They are coordinated by the PM agent but can also be invoked directly for focused work. Each agent escalates gaps to the right peer — no agent works around design or security issues.

Location: ~/projects/.claude/agents/ — scoped to the linuxserver.lan workspace, loaded alongside the project-level skills and CLAUDE.md context.

ai-servicers.com