Setting up agent development

Create two new top-level files: AGENTS.md (repo guide for AI agents per the agents.md spec) and PLAN.md (long-term architecture and roadmap). Both are greenfield — the repo currently has only a minimal README.md with setup steps. Content must be grounded in the existing codebase: Talos Linux on libvirt/QEMU, HashiCorp Vault, Tailscale networking, dual-stack IPv4/IPv6.

Technical Approach

Create AGENTS.md at repo root

# Evolved NPCs Infrastructure

## Project Overview
Infrastructure-as-code for a Talos Linux Kubernetes cluster on local
libvirt/QEMU (macOS arm64). 4-phase setup: control-plane → Vault → CI → workers.

## Hard Rules
- Never run `terraform apply` or `talosctl` without explicit user confirmation
- Never commit secrets, TLS certs, or private keys
- All infra changes via Terraform plan/apply — no manual `virsh`/`qemu-img`

## Repo Map
| Directory           | Purpose                                               |
|---------------------|-------------------------------------------------------|
| `control-plane/`    | Terraform: Talos control-plane VM on libvirt          |
| `hc-vault/`         | Vault via podman-compose + nginx TLS proxy            |
| `worker/`           | Shell scripts + patches for Talos worker VMs          |
| `teamcity-agent/`   | CI/CD agent (planned, not yet implemented)            |

## Tech Stack
- **OS:** Talos Linux v1.11.1 (immutable, no SSH)
- **IaC:** Terraform (`siderolabs/talos` ~0.9 + `dmacvicar/libvirt` ~0.7)
- **Networking:** Dual-stack libvirt NAT bridge + Tailscale TLS
- **Secrets:** HashiCorp Vault (standalone podman-compose)
- **VMs:** QEMU arm64, managed by Terraform + shell helpers

## Code Conventions
- Shell: `set -e`, `log_info`/`log_warn`/`log_error` helpers, Homebrew deps
- Terraform: variables inline in `main.tf` with defaults
- Patches: JSON-patch (`op`/`path`/`value`) with `<>` placeholders
- Images: `tepichord/` namespace

## How Changes Ship
- `terraform plan` → review → `terraform apply`
- `control-plane/cleanup.sh` tears down the cluster
- `worker/vm-setup/manage-vms.sh` for start/stop/status

Create PLAN.md at repo root

# Evolved NPCs Infrastructure — Plan

## Vision
Local-first Kubernetes infra for evolved NPC workloads.
Stack: Talos Linux, HashiCorp Vault, TeamCity CI/CD, QEMU/libvirt on macOS arm64.

## Current State
- Single control-plane node (2 GB RAM, 2 vCPUs) on local libvirt
- Vault standalone via podman-compose with Tailscale TLS
- Worker VMs via shell scripts
- Dual-stack: IPv4 `10.5.0.0/24` + IPv6 `2001:db8:b84b:5::/64`

## Phased Roadmap

### Phase 1: Control Plane ✅
Terraform-provisioned Talos VM + dual-stack NAT bridge (XSLT).

### Phase 2: HashiCorp Vault ✅
Standalone Vault (podman-compose) + nginx TLS termination.

### Phase 3: TeamCity Agent 🚧
Directory not yet created. Options: JetBrains Terraform provider or Kotlin DSL.

### Phase 4: Worker Nodes 🚧
Shell provisioning exists. Target: Terraform-managed 3+ worker nodes.

## Target Architecture
- **HA control plane:** 3 nodes (etcd quorum)
- **API load balancer:** DNS round-robin or L4 LB on port 6443
- **Secrets:** Vault Secrets Operator (VSO) for in-cluster sync
- **CI/CD:** TeamCity builds + deploys infra and application workloads

## Security Model
- Talos: immutable, API-only, no SSH
- Vault: TLS, file storage, 96-day lease TTL
- `.gitignore` enforces no secrets in repo

## Open Questions
- Cloud migration path (current code is libvirt-specific)
- Vault placement: external (current) vs. in-cluster
- Multi-arch: currently arm64-only

Implementation Details

Files to create:

/AGENTS.md — new file, ~50 lines
/PLAN.md — new file, ~60 lines

Dependencies: None — both are standalone Markdown files.

Constraints:

AGENTS.md must follow the agents.md spec conventions (human-readable, no YAML frontmatter required)
PLAN.md phases must align with the existing README's 4-phase sequence
Content grounded in actual repo files: control-plane/main.tf, hc-vault/docker-compose.yml, worker/vm-setup/create-worker-vm.sh

Out-of-scope notes:

No changes to existing Terraform, shell scripts, or compose files
The teamcity-agent/ directory is NOT created in this issue — only documented as planned
Cloud deployment is mentioned as an open question, not a planned feature
Worker script uses Talos v1.11.0 (behind control-plane's v1.11.1) — documented as-is; upgrade is a separate concern

Acceptance Criteria

AGENTS.md exists at repo root with: Project Overview, Hard Rules, Repo Map, Tech Stack, Code Conventions, How Changes Ship
PLAN.md exists at repo root with: Vision, Current State, Phased Roadmap (4 phases), Target Architecture, Security Model, Open Questions
Repo Map table accurately reflects the 3 existing directories (control-plane/, hc-vault/, worker/) plus planned teamcity-agent/
PLAN.md phases match the README's setup sequence: control-plane → hc-vault → teamcity-agent → worker
No secrets, IPs, or hostnames hardcoded that should be in variables

Testing Plan

Visual review: Confirm both files render correctly as Markdown (headings, tables, code blocks)
Accuracy check: Verify Repo Map directories and Tech Stack entries match actual repo contents
Link check: Confirm the agents.md spec link resolves (https://agents.md/)

None — this is a standalone documentation issue.

Naina: *Updated on 2026-08-14 based on codebase verification.* #### Overview Create two new top-level files: `AGENTS.md` (repo guide for AI agents per the [agents.md spec](https://agents.md/)) and `PLAN.md` (long-term architecture and roadmap). Both are greenfield — the repo currently has only a minimal `README.md` with setup steps. Content must be grounded in the existing codebase: Talos Linux on libvirt/QEMU, HashiCorp Vault, Tailscale networking, dual-stack IPv4/IPv6. #### Technical Approach 1. **Create `AGENTS.md`** at repo root ```markdown # Evolved NPCs Infrastructure ## Project Overview Infrastructure-as-code for a Talos Linux Kubernetes cluster on local libvirt/QEMU (macOS arm64). 4-phase setup: control-plane → Vault → CI → workers. ## Hard Rules - Never run `terraform apply` or `talosctl` without explicit user confirmation - Never commit secrets, TLS certs, or private keys - All infra changes via Terraform plan/apply — no manual `virsh`/`qemu-img` ## Repo Map | Directory | Purpose | |---------------------|-------------------------------------------------------| | `control-plane/` | Terraform: Talos control-plane VM on libvirt | | `hc-vault/` | Vault via podman-compose + nginx TLS proxy | | `worker/` | Shell scripts + patches for Talos worker VMs | | `teamcity-agent/` | CI/CD agent (planned, not yet implemented) | ## Tech Stack - **OS:** Talos Linux v1.11.1 (immutable, no SSH) - **IaC:** Terraform (`siderolabs/talos` ~0.9 + `dmacvicar/libvirt` ~0.7) - **Networking:** Dual-stack libvirt NAT bridge + Tailscale TLS - **Secrets:** HashiCorp Vault (standalone podman-compose) - **VMs:** QEMU arm64, managed by Terraform + shell helpers ## Code Conventions - Shell: `set -e`, `log_info`/`log_warn`/`log_error` helpers, Homebrew deps - Terraform: variables inline in `main.tf` with defaults - Patches: JSON-patch (`op`/`path`/`value`) with `<>` placeholders - Images: `tepichord/` namespace ## How Changes Ship - `terraform plan` → review → `terraform apply` - `control-plane/cleanup.sh` tears down the cluster - `worker/vm-setup/manage-vms.sh` for start/stop/status ``` 2. **Create `PLAN.md`** at repo root ```markdown # Evolved NPCs Infrastructure — Plan ## Vision Local-first Kubernetes infra for evolved NPC workloads. Stack: Talos Linux, HashiCorp Vault, TeamCity CI/CD, QEMU/libvirt on macOS arm64. ## Current State - Single control-plane node (2 GB RAM, 2 vCPUs) on local libvirt - Vault standalone via podman-compose with Tailscale TLS - Worker VMs via shell scripts - Dual-stack: IPv4 `10.5.0.0/24` + IPv6 `2001:db8:b84b:5::/64` ## Phased Roadmap ### Phase 1: Control Plane ✅ Terraform-provisioned Talos VM + dual-stack NAT bridge (XSLT). ### Phase 2: HashiCorp Vault ✅ Standalone Vault (podman-compose) + nginx TLS termination. ### Phase 3: TeamCity Agent 🚧 Directory not yet created. Options: JetBrains Terraform provider or Kotlin DSL. ### Phase 4: Worker Nodes 🚧 Shell provisioning exists. Target: Terraform-managed 3+ worker nodes. ## Target Architecture - **HA control plane:** 3 nodes (etcd quorum) - **API load balancer:** DNS round-robin or L4 LB on port 6443 - **Secrets:** Vault Secrets Operator (VSO) for in-cluster sync - **CI/CD:** TeamCity builds + deploys infra and application workloads ## Security Model - Talos: immutable, API-only, no SSH - Vault: TLS, file storage, 96-day lease TTL - `.gitignore` enforces no secrets in repo ## Open Questions - Cloud migration path (current code is libvirt-specific) - Vault placement: external (current) vs. in-cluster - Multi-arch: currently arm64-only ``` #### Implementation Details **Files to create:** - `/AGENTS.md` — new file, ~50 lines - `/PLAN.md` — new file, ~60 lines **Dependencies:** None — both are standalone Markdown files. **Constraints:** - `AGENTS.md` must follow the [agents.md spec](https://agents.md/) conventions (human-readable, no YAML frontmatter required) - `PLAN.md` phases must align with the existing README's 4-phase sequence - Content grounded in actual repo files: `control-plane/main.tf`, `hc-vault/docker-compose.yml`, `worker/vm-setup/create-worker-vm.sh` **Out-of-scope notes:** - No changes to existing Terraform, shell scripts, or compose files - The `teamcity-agent/` directory is NOT created in this issue — only documented as planned - Cloud deployment is mentioned as an open question, not a planned feature - Worker script uses Talos v1.11.0 (behind control-plane's v1.11.1) — documented as-is; upgrade is a separate concern #### Acceptance Criteria - [ ] `AGENTS.md` exists at repo root with: Project Overview, Hard Rules, Repo Map, Tech Stack, Code Conventions, How Changes Ship - [ ] `PLAN.md` exists at repo root with: Vision, Current State, Phased Roadmap (4 phases), Target Architecture, Security Model, Open Questions - [ ] Repo Map table accurately reflects the 3 existing directories (`control-plane/`, `hc-vault/`, `worker/`) plus planned `teamcity-agent/` - [ ] PLAN.md phases match the README's setup sequence: control-plane → hc-vault → teamcity-agent → worker - [ ] No secrets, IPs, or hostnames hardcoded that should be in variables #### Testing Plan - **Visual review:** Confirm both files render correctly as Markdown (headings, tables, code blocks) - **Accuracy check:** Verify Repo Map directories and Tech Stack entries match actual repo contents - **Link check:** Confirm the agents.md spec link resolves (https://agents.md/) #### Related Issues/PRs - None — this is a standalone documentation issue.

tepichord added

and removed

labels

2026-08-14 11:51:36 -07:00

tepichord added

status

implement

and removed