AI Tooling
Claude Code is the AI assistant this repository is built around. The repository tells it how to
work through CLAUDE.md files, repository skills and MCP servers.
Prerequisites
Section titled “Prerequisites”- Claude Code installed on the workstation
- A Vault login and cluster access (Environment Setup, Cluster Access)
- A path to the cluster network, for the MCP servers that read live state
Configuration files
Section titled “Configuration files”| File | Purpose |
|---|---|
CLAUDE.md |
The routing layer: which MCP server and which skill to use for each task, the prose rules, the branch and workflow constraints |
ansible/CLAUDE.md, tf/CLAUDE.md, argocd/CLAUDE.md, tf/cloudflare/CLAUDE.md |
Constraints for work under each directory. Read the one for the directory before editing there |
.claude/settings.json |
Project settings: the sandbox, the allowed commands, the output style. It enables every MCP server the user has configured |
.claude/skills/ |
Repository skills: nas-throwaway-lxc, untrusted-leg-dns-check, spike-findings-selfhosted-cluster and the openspec-* skills |
~/.claude/CLAUDE.md |
Personal preferences, outside the repository |
~/.claude.json |
The user’s MCP server configuration. The repository ships no .mcp.json |
Skills
Section titled “Skills”CLAUDE.md routes tasks to skills. The skills that every session uses:
| Task | Skill |
|---|---|
| Creative work and design | superpowers:brainstorming |
| Bug investigation | superpowers:systematic-debugging |
| Multi-step implementation | superpowers:writing-plans |
| Feature isolation | superpowers:using-git-worktrees |
| Pull request review | pr-review-toolkit:review-pr |
| Terraform | fzymgc-house:terraform |
| Prose of any kind | simple-english |
| A client vantage point on a VLAN that no workstation is on | nas-throwaway-lxc |
| What DNS a Guest or Telework client gets | untrusted-leg-dns-check |
Design specs go under docs/engineering/specs/ and implementation plans under
docs/engineering/plans/.
MCP servers
Section titled “MCP servers”| Task | Server |
|---|---|
| File read and write | Filesystem |
| Logs, metrics and traces | ClickStack and ClickHouse, first for any triage. The tables are default.otel_logs, otel_metrics_* and otel_traces |
| Live Kubernetes object state | Kubernetes, read only |
| Live UniFi controller state: devices, clients, firewall policies and events | UniFi Network (unifi_ro), read only |
| Library documentation | Context7 |
| Web search | Exa |
| Web scraping | Firecrawl |
The cluster also serves MCP servers behind LiteLLM at llm.fzymgc.house/<server>/mcp, for any
client that speaks MCP over HTTP. MCP Gateway Clients
describes each server, its authentication and the client configuration.
Constraints that every session follows
Section titled “Constraints that every session follows”| Rule | Reason |
|---|---|
| Work on a feature branch and open a pull request | main is protected |
Never apply kubectl changes |
ArgoCD owns deployments |
Use uv for Python, never pip |
The pinned environment is the only one that is tested |
Use rg, not grep, in this checkout |
Commands for the resolver pair keep grep, because the pair has no rg |
| Check for an applicable skill before answering | The routing table is the contract |
Make sure that the tooling works
Section titled “Make sure that the tooling works”kubectl --context fzymgc-house get nodes # the Kubernetes MCP server reads the same contextIn a Claude Code session, ask for the last ten log rows from default.otel_logs. The ClickStack
MCP server answers from the cluster.