AI Portability¶

The Archon platform is designed so that AI context travels with the code, not with the AI session.

Philosophy¶

AI sessions are ephemeral. Each new Claude Code session starts cold with no memory of prior work. The platform solves this not by relying on AI memory features, but by treating context as infrastructure: version-controlled, pipeline-generated, and always current.

The core principle: context lives in the repo, not in the tool.

How it works¶

CLAUDE.md files¶

Every Archon repo has a CLAUDE.md at its root. These files:

Point to archon-docs/docs/_context.md as the authoritative platform context source
Declare repo-specific scope and constraints (e.g., IaC tooling boundaries, secret hygiene rules)
Are the first file Claude Code reads at session start

This means any capable AI assistant with access to the repo can load full platform context in one read.

_context.md (generated)¶

docs/_context.md is not hand-maintained. It is generated by generate-context.py on every push to archon-docs main, aggregating:

Platform inventory and node status
ADR index and decision summary
Phase roadmap state
Active constraints (Grype-only scanning, IT/OT separation, branch policy)

The pipeline ensures _context.md is never stale. No manual sync required.

ADRs as reasoning layer¶

Architecture Decision Records are the platform's reasoning layer. Each ADR captures:

The decision made
Alternatives considered and why they were rejected
Consequences and constraints that follow

An AI assistant reading the ADR index can reconstruct why the platform is built the way it is, not just what it is. This is the difference between a tool that can answer "what port does AdGuard use?" and one that can answer "should we move AdGuard to a container?".

MCP servers¶

MCP servers provide structured, authenticated access to external systems:

Server	Purpose
Azure Infrastructure	Azure resource queries
Kubernetes	k3s cluster operations
Infisical	Secrets retrieval
Cloudflare	DNS and Pages operations

MCP replaces ad-hoc curl one-liners and reduces the surface area of credential handling in prompts.

Portability guarantees¶

Guarantee	How enforced
Context survives session restart	_context.md regenerated on every main push
Context is model-agnostic	Plain Markdown, no tool-specific formatting
Secrets stay out of context	Infisical MCP, never hardcoded in CLAUDE.md
ADR decisions are machine-readable	Structured Markdown with consistent headers

Limitations¶

_context.md reflects the state of archon-docs at last push, not real-time cluster state
MCP server availability depends on local network access (k3s, Infisical) or API credentials (Azure, Cloudflare)
Claude Code session memory (.claude/ directory) is machine-local and does not replicate

ADR-0011: Claude Code as primary IaC authoring tool
ADR-0021: Claude Code as platform developer AI tooling
ADR-0026: Claude Code optimization and MCP strategy
ADR-0023: Multi-repo docs aggregation