Skip to content

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.

  • 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
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

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/.

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.

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
Terminal window
kubectl --context fzymgc-house get nodes # the Kubernetes MCP server reads the same context

In a Claude Code session, ask for the last ten log rows from default.otel_logs. The ClickStack MCP server answers from the cluster.