Susan

Tools

All commands are written in Go and live in cmd/ of the repository. make install at the root builds, tests and installs nexusctl, nexusadm, nexushelm and harnessctl, with their Claude Code hooks; proxyctl installs on its own with make -C cmd/proxyctl install.

Commands for people

CommandSetupPurpose
flowctlAllClient of the operator: submit a run (one execution of a workflow; see the glossary), list, get, watch until it ends, cancel, and usage to total tokens per model. --output json prints machine-readable output; exit codes are stable.
proxyctlWorkstationLocal Traefik reverse proxy in HTTPS on *.localhost for every project of the computer, with mkcert certificates: up, routes add, domains add, domains check.
nexusadmHomelabCluster administration: node add and node remove, grant for time-limited accesses, secret for the keyring, audit of the API server, doctor to check the nodes, log of the actions taken.
nexusctlHomelabkubectl with a chosen access, every call logged.
nexushelmHomelabhelm with a chosen access, every call logged, Helm releases stored in Secrets.
harnessctlAllGuard for Claude Code on your workstation: edits to agent rules after confirmation, and folders outside the project opened to an agent for 30 days at most.

Actions that need cluster administration rights open a confirmation window on your desktop session.

Components of the suite

ComponentRuns inPurpose
nexus-dashboardOne serviceFollows the items (units of work, such as a request), shows the questions that runs ask in the view “Waiting for you”, resumes a run when you answer, reads pull requests on Forgejo and drives the operator over its HTTP API.
nexus-operatorOne serviceTurns WorkflowRun resources into Kubernetes Jobs, or into Docker containers with its docker engine, and follows each run until it ends. nexus-operator provision <project> prepares the namespaces of a project.
nexus-agentThe pod of each runMain container: runs AWF and forwards what it produces to the collector, or straight to the operator on a workstation. Its exit code is AWF’s.
nexus-collectorThe pod of each run (cluster)Sidecar: receives the messages of the agent and of the plugin on a Unix socket, writes them to its on-disk journal and relays them to the operator over gRPC with mutual TLS. It is the only way out of the pod to the control plane.
nexus-pluginInside AWFAWF plugin that pushes the events of a run and carries the ask and report operations.
nexus-execThe pod of a run with a stackRuns a program in another container of the pod, with its input, output and exit code.

Workflows

PackContent
openspec-tddPack gplanchat/awf-workflow-openspec-tdd, version pinned in deploy/runner/Dockerfile and installed in the run image: OpenSpec changes with an Elephant Goldfish Model (EGM) review in the design phases and a test written before the code.
packs/factoryask, apply-change, apply-many, apply-task, tdd-slice and free-task: apply OpenSpec changes in parallel, one worktree per change, a test-first cycle per task, merges one at a time and a JSON report. Install with bash packs/factory/install.sh.

Infrastructure

FolderContent
compose.yamlThe workstation setup.
infra/Ansible playbook and roles of the homelab setup: base system, MicroK8s, Kueue, firewall, DNS, certificate authority, WireGuard, backup target.
deploy/helm/nexus-factoryHelm chart of the cluster setups.
api/OpenAPI contract of the dashboard.