Agent Architecture — Archon Platform¶
Overview¶
The CanEast platform uses 21 custom Claude Code sub-agents (prefix: ccagnt-) to enforce platform-specific rules, accelerate consistent reviews, and maintain a CIO-defensible portfolio posture across all 6 repos.
Canonical source: archon-docs/docs/internal/agents/ — private, excluded from public docs pipeline.
Deployed to: ~/.claude/agents/ on the CanEast AI Node workstation (WSL), making them available across all Claude Code sessions and all repo directories.
To deploy after pulling changes:
ADO Work Item: WI #101
Invocation¶
Agents are invoked via Claude Code's --agent flag or inline during sessions:
# Explicit invocation from CLI
claude --agent ccagnt-session "end of session"
claude --agent ccagnt-architect "review this ADR draft"
claude --agent ccagnt-ansible "review my playbook"
During interactive sessions, Claude Code selects agents automatically based on task context, or you can direct it:
"use ccagnt-reviewer to check this PR"
"run ccagnt-session to close out"
"ask ccagnt-ciso about the MFA gap"
Agent Registry¶
Core (5 agents)¶
These agents are the foundation of the platform's governance. They are invoked proactively by Claude Code on most tasks.
| Agent | File | Role | When to Invoke |
|---|---|---|---|
| ccagnt-architect | ccagnt-architect.md | Platform architecture reviewer | Any new feature, ADR, or infrastructure decision |
| ccagnt-reviewer | ccagnt-reviewer.md | Code and IaC reviewer | After any code, Ansible, Terraform, or pipeline change |
| ccagnt-security | ccagnt-security.md | DevSecOps security reviewer | After writing code handling secrets, network configs, containers, or external inputs |
| ccagnt-ciso | ccagnt-ciso.md | Strategic security program owner | Executive security posture review, CISSP alignment, threat model currency |
| ccagnt-planner | ccagnt-planner.md | Sprint and backlog planner | Triaging backlog, planning sprint work, mapping tasks to roadmap phases |
IaC / Automation (4 agents)¶
Focused on specific IaC domains — invoked when working in that technology area.
| Agent | File | Role | When to Invoke |
|---|---|---|---|
| ccagnt-ansible | ccagnt-ansible.md | Ansible and AWX reviewer | Writing or reviewing playbooks, roles, inventory, AWX job templates |
| ccagnt-terraform | ccagnt-terraform.md | Terraform reviewer | Writing or reviewing Terraform in archon-cloud (Azure, GCP, Cloudflare) |
| ccagnt-pipeline | ccagnt-pipeline.md | CI/CD pipeline reviewer | Writing or reviewing ADO pipeline YAML, service connections, scan stages |
| ccagnt-ot | ccagnt-ot.md | OT/embedded reviewer | ESP32 firmware, PlatformIO, MQTT, OT GitFlow in archon-apps |
Data / Compliance (4 agents)¶
Invoked when decisions affect data, security posture, or compliance obligations.
| Agent | File | Role | When to Invoke |
|---|---|---|---|
| ccagnt-db | ccagnt-db.md | Data and database advisor | Introducing any data storage, Phase 6 PII planning |
| ccagnt-audit | ccagnt-audit.md | Compliance and audit evidence | Security review prep, evidence packages, CISSP domain coverage |
| ccagnt-vulnmgmt | ccagnt-vulnmgmt.md | Vulnerability management | Triaging CVEs from Grype scans, managing vulnerability backlog |
| ccagnt-purpleteam | ccagnt-purpleteam.md | Purple team advisor | Threat simulation planning (BLOCKED until WI #116 ADR accepted) |
Ops (4 agents)¶
Operational agents for day-to-day platform management.
| Agent | File | Role | When to Invoke |
|---|---|---|---|
| ccagnt-docsync | ccagnt-docsync.md | Documentation sync | archon-docs out of date, context regeneration, ADR hygiene |
| ccagnt-network | ccagnt-network.md | Network architecture reviewer | Firewall rules, VPN, DNS, VLAN, DMZ, OPNsense changes |
| ccagnt-cost | ccagnt-cost.md | Cloud cost advisor | Azure/Cloudflare spend review, rightsizing, Phase 4-6 expansion planning |
| ccagnt-incident | ccagnt-incident.md | Incident response advisor | Alert triage, node anomaly, security event investigation |
Meta (4 agents)¶
Session management and agent governance agents.
| Agent | File | Role | When to Invoke |
|---|---|---|---|
| ccagnt-harness | ccagnt-harness.md | Agent test harness | After creating or modifying any ccagnt agent — validate hard rules still enforced |
| ccagnt-context | ccagnt-context.md | Context manager | Start of any session — loads current platform state from archon-docs |
| ccagnt-session-light | ccagnt-session-light.md | Daily session close (fast, ~5 min) | End of most work sessions |
| ccagnt-session-full | ccagnt-session-full.md | End-of-sprint session close (full audit, ~15-20 min) | Sprint boundaries, major phase completions |
Platform Hard Rules (enforced by all relevant agents)¶
The following rules are non-negotiable and enforced regardless of what the user requests:
| Rule | Agents Enforcing |
|---|---|
| Grype + Syft only — Trivy avoided (ADR-0003, TeamPCP compromise March 2026) | ccagnt-security, ccagnt-pipeline, ccagnt-architect, ccagnt-vulnmgmt |
| ansible-svc-account only — never personal accounts for Ansible automation | ccagnt-ansible, ccagnt-reviewer, ccagnt-security |
| SSH port REDACTED on caneast-site1-node2, caneast-site1-node3 (port 22 on caneast-site1-node1 RPi4 only) | ccagnt-ansible, ccagnt-reviewer, ccagnt-network |
| OPNsense as KVM VM only — never Docker (ADR-0004) | ccagnt-network, ccagnt-architect |
| NTP via NRC Canada only (time.nrc.ca, time.chu.nrc.ca) | ccagnt-network, ccagnt-architect |
| ESP32 rain sensor: 3V3 pin only — VIN/5V burns the module | ccagnt-ot, ccagnt-architect |
| All secrets via Infisical self-hosted (REDACTED:[REDACTED]) | ccagnt-security, ccagnt-reviewer, ccagnt-ansible |
| Purple team simulations require accepted ADR — ADR-0027 accepted (WI #116) | ccagnt-purpleteam, ccagnt-ciso |
| Squash merge only, PR required for all changes to main | ccagnt-reviewer |
| FQCN for all Ansible modules (ADR-0013) | ccagnt-ansible, ccagnt-reviewer |
| Public docs use CanEast sanitized naming — no real IPs/hostnames | ccagnt-reviewer, ccagnt-docsync |
Design Notes¶
Naming Convention¶
All agents use the ccagnt- prefix (CanEast Claude Agent). This:
- Prevents naming collision with other projects
- Makes agents easy to list and find (ls ~/.claude/agents/ccagnt-*)
- Signals they are platform-specific, not general-purpose
Scope¶
Agent source files are committed to archon-docs/docs/internal/agents/ (private, not published) and deployed to ~/.claude/agents/ on the CanEast AI Node workstation. User scope makes them available:
- Across all 6 Archon repos
- In the parent ~/homelab/repos/ workspace
- In any other directory when Claude Code is invoked
Model¶
All ccagnt agents use model: sonnet for cost-efficiency. If a specific agent requires deeper reasoning (e.g., ccagnt-ciso for a complex posture review), this can be overridden at invocation.
Tool Access¶
- Read-only agents (ccagnt-architect, ccagnt-ciso, ccagnt-planner, ccagnt-network, ccagnt-purpleteam, ccagnt-harness):
Read, Grep, Glob— cannot modify files - Review agents with write access (ccagnt-ansible, ccagnt-terraform, ccagnt-pipeline, ccagnt-security, ccagnt-reviewer, ccagnt-ot, ccagnt-vulnmgmt, ccagnt-docsync, ccagnt-incident):
Read, Write, Edit, Bash, Grep, Glob - Ops/meta agents (ccagnt-context, ccagnt-session-light, ccagnt-session-full):
Read, Bash, Grep, Glob
References¶
- ADO WI #101: Agent architecture implementation
- ECC (everything-claude-code) repository: reference agent templates
- ADR-0003: Trivy risk assessment and Grype adoption
- ADR-0004: OPNsense KVM deployment
- ADR-0013: Ansible FQCN requirement
- WI #116: Purple team ADR (blocks ccagnt-purpleteam simulations)