README
¶
neckbeard
A plugin for your coding agent that turns an app into reviewable cloud infrastructure and a cost estimate. Plans and scaffolds for AWS, GCP, or Azure, with GitHub Actions or GitLab CI, from a bundled catalog of maintained OpenTofu modules. Pre-alpha: deployment coverage and delivery automation are incomplete.
Inspired by ponytail. The neckbeard handles your infra so you don't have to.
you: /neckbeard:analyze
agent: reads your repo → evidence-backed profile → asks what code can't tell it
you: resolve the draft's questions, pick a cloud and a tier
agent: plan → estimate ($83/mo, here's the table) → scaffold → validate
you: review the files and follow docs/bootstrap.md per environment
next: configure cloud access and verify deployment (coverage varies by lane)
Why this exists
Coding agents are good at app code and bad at freehanding infrastructure. The failure mode is always the same: plausible-looking HCL that is subtly broken, insecure by default, and unestimable. neckbeard inverts the roles:
- Humans maintain the golden path — versioned OpenTofu modules, pipeline templates, GitOps layouts, per cloud.
- The agent analyzes, parameterizes, and explains. It reads your app, figures out what it needs, and maps that onto catalog inputs — with file:line evidence for every claim it makes.
- Everything in between is deterministic code. Same inputs, same bytes:
the planner emits a hash-verified
blueprint.yamllockfile, the renderer is a pure function of it, and regeneration never silently overwrites your edits.
The agent never invents infrastructure. Needs the catalog can't express become named findings ("redis is outside the workload contract"), not force-fits onto the nearest module.
The part nobody else tells you: what it costs
The same reference app (HTTP service + worker + cron + Postgres), smallest tier, all three environments, live prices via Infracost:
| Cloud Run | Container Apps | ECS Fargate | EKS | GKE (regional) | AKS | |
|---|---|---|---|---|---|---|
| monthly | $77 | ~$98* | $250 | $396 | $754 | ~$801* |
* Infracost can't price Container Apps compute yet — and instead of letting a
low number lie, the report names every unpriced resource. That's the house
style: neckbeard estimate gives you baseline-while-idle costs, explicit usage
assumptions (a tier name is not a usage estimate — the numbers are, and you can
edit them), low/expected/high scenario ranges, and a provenance footer. Cloud budget alerts are planned; the current CLI does
not configure them. When implemented, alerts will notify, not cap spending.
It also prices your decisions: the table above is why neckbeard tells solo developers "you don't need Kubernetes yet" — with receipts.
Honesty as architecture
Infrastructure tools love implying more than they've proven. neckbeard reports in three verdicts, and the third one is the point:
V0 PASSED tofu validate [prd]
V0 PASSED checkov policy [prd] ← every skip carries a written reason
V0 PASSED kubeconform (clusters/)
V1 NOT EXERCISED authenticated plan requires cloud credentials
V2 NOT EXERCISED deployment verification release-harness only for now
- Static validation never claims deployability — V0/V1/V2 are distinct levels, each reported as exercised or not.
- Every checkov skip in the generated
.checkov.yamlstates its reason. A skip without a reason is a lie about your security posture. - When live runs break, the failures become public findings and then harness requirements. Our first real deployment produced ten of them; five became catalog fixes the same day.
- Placeholder pins say "placeholder". Degraded paths print why (Azure + GitLab merge-request plans can't federate — the pipeline says so instead of failing mysteriously).
What you get
- Three isolated environments (dev/stg/prd) with independent state, sized by tier presets over explicit dimensions: traffic, availability, RPO/RTO, operating capacity. Every preset value is visible and overridable within the catalog's tested envelope — and values outside it are marked, not blessed.
- Two runtimes per cloud: serverless containers (Cloud Run / ECS Fargate / Container Apps) or Kubernetes (EKS / GKE / AKS) with Flux manifests for dev image automation. Complete promotion, rollback, and serverless release automation remain subsequent work; initial image references are placeholders.
- CI/CD for GitHub Actions or GitLab CI from one internal model: test →
build → scan (trivy blocks HIGH/CRITICAL) → push; infra plans on PRs with a
read-only role, applies on main with a write role, prd gated by environment
protection. Zero static cloud keys — OIDC federation everywhere,
enforced by a test that fails if a rendered pipeline ever mentions
AWS_SECRET_ACCESS_KEY. - Security posture as explicit controls: private-by-default networks, secrets managers holding names the operator fills (values never touch neckbeard, its state, or your git history), scoped CI identities, managed WAF rules where the tier enables them.
- A bootstrap runbook (
docs/bootstrap.md) that takes a human with elevated credentials through federated CI setup per environment — state backend first, then OIDC trust, then CI roles.
Quick start
As a Claude Code plugin:
/plugin marketplace add bealesh/neckbeard
/plugin install neckbeard@neckbeard
then, in your app's repo: /neckbeard:analyze.
Codex CLI, Cursor, or any SKILL.md-speaking agent:
go install github.com/bealesh/neckbeard/cmd/neckbeard@latest
neckbeard skill install # .agents/skills/ — the open standard
neckbeard skill install -target cursor # + repo slash commands for Cursor
neckbeard skill install -scope user # once, for every repo on this machine
The skill is the same operating manual everywhere; only the discovery path
differs. Codex invokes it via /skills or $neckbeard; Cursor loads it on
demand and gets /neckbeard-analyze and /neckbeard-sync as commands.
Or drive the CLI directly:
go install github.com/bealesh/neckbeard/cmd/neckbeard@latest
neckbeard doctor -for plan # checks the bundled catalog; no cloud access
neckbeard analyze # draft profile + the questions code can't answer
$EDITOR app-profile.yaml # resolve each assumption with a same-id confirmed answer
$EDITOR neckbeard.yaml # cloud, region, tier, runtime, repo
neckbeard plan # deterministic blueprint + topology summary
neckbeard doctor -for estimate
neckbeard estimate # the money table, before anything exists
neckbeard scaffold # infra/, pipelines, clusters/ — yours to review
neckbeard validate # V0: fmt, validate, checkov, kubeconform
The binary bundles the catalog, schemas, presets, and installed skill references:
no neckbeard source checkout is needed. Use neckbeard schema neckbeard,
neckbeard schema app-profile, and neckbeard presets for exact inputs. See the
onboarding guide for a complete
config and examples for existing databases and unsupported dependencies.
The supported workload is one image, up to 10 HTTP/worker/cron processes, with
repository-root build context. Omitted or empty command preserves image defaults.
plan refuses unresolved assumptions, undecided datastore provisioning, and
unsupported findings without an explicit disposition. Existing services use
mode: reference and a connection secret_name; their lifecycle remains external.
Scaffold includes pinned module contents under .neckbeard/catalog/. Commit that
directory with the generated infrastructure and ownership manifest. Upgrading to
a different bundled catalog requires a new plan and review of the diff. Explicit
-catalog and -catalog-source remain available for catalog development.
Planning and scaffolding need no external tools or cloud credentials. Estimates
need Infracost 0.10.x and its pricing login. Validation needs the pinned
OpenTofu version, with Checkov, kubeconform (Kubernetes), and actionlint (GitHub)
for their respective gates. neckbeard doctor -for estimate|validate|all reports
missing or incompatible tools; validate reports unavailable checks as
NOT EXERCISED. Doctor checks tool availability, not cloud permissions or quotas.
Status: pre-alpha, and precise about it
The current development checkpoint and remaining acceptance gates are tracked in the launch plan, with detailed live deployment evidence. The live coverage below describes the development checkpoint, not completed launch acceptance.
| cloud / VCS | serverless live evidence | Kubernetes live lifecycle |
|---|---|---|
| AWS / GitHub | Deploy, update, rollback and failed-release recovery passed | Not yet |
| GCP / GitHub | Bootstrap/database prepared; app deployment partially applied | Not yet |
| Azure / GitHub | Deploy, update, rollback and environment recreation passed | Not yet |
| AWS / GitLab | App deployment not yet exercised | Not yet |
| GCP / GitLab | App deployment not yet exercised | Not yet |
| Azure / GitLab | App deployment not yet exercised | Not yet |
The six-lane static matrix runs on every PR using the bundled catalog. Tests also run a built binary from three unrelated fixture apps across all 12 cloud/VCS/runtime combinations, including an existing database and external Redis. These tests cover onboarding and rendering; pricing is stubbed in the automated fixture test. GitLab's separate-account approval preflight passed, but that does not prove a cloud deployment. Full lifecycle acceptance remains 0/12: promotion, clean automated setup/teardown, Kubernetes and the remaining deployment paths are unfinished. The live evidence notes also document the current workflow-linter compatibility gap. Do not treat static validation as deployment proof.
Also honest: landing zones (org structure, central audit, guardrails — the Path F story in DESIGN.md) are designed but not yet built; the adopt path (existing accounts/projects/subscriptions) is what ships today.
How it hangs together
you / your agent deterministic core
┌──────────────────────┐ ┌───────────────────────────┐
repo ──▶│ analyze: facts w/ │ profile │ plan: catalog @ pinned │
│ evidence, questions, ├───────────▶│ versions → blueprint.yaml │
│ judgment, answers │ config │ (hash-verified lockfile) │
└──────────────────────┘ └─────────┬─────────────────┘
┌──────────────┼──────────────┐
▼ ▼ ▼
estimate scaffold validate
Infracost, ownership V0 static,
scenarios, contract: V1 plan,
unpriced never silently V2 deploy —
named overwrite each reported
Deep dives: DESIGN.md (the full design, kept honest since day one) · docs/findings/ (what reality taught us) · CONTRIBUTING.md.
License
Apache-2.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
bellwether is the representative reference application for neckbeard's release matrix (DESIGN §12.3): one binary, three modes matching the workload contract — an HTTP service, a background worker, and a scheduled job — using PostgreSQL when configured and degrading honestly when not.
|
bellwether is the representative reference application for neckbeard's release matrix (DESIGN §12.3): one binary, three modes matching the workload contract — an HTTP service, a background worker, and a scheduled job — using PostgreSQL when configured and degrading honestly when not. |
|
Package catalogassets distributes the tested catalog with the CLI binary.
|
Package catalogassets distributes the tested catalog with the CLI binary. |
|
cmd
|
|
|
neckbeard
command
neckbeard core CLI.
|
neckbeard core CLI. |
|
core
|
|
|
analyze
Package analyze is the deterministic detection layer under the analyzer (DESIGN §7, §8): it walks a repository and reports what is mechanically observable — Dockerfiles, exposed ports, environment-variable reads, language markers — as FACTS with file:line evidence, plus the inferences and assumptions those facts support.
|
Package analyze is the deterministic detection layer under the analyzer (DESIGN §7, §8): it walks a repository and reports what is mechanically observable — Dockerfiles, exposed ports, environment-variable reads, language markers — as FACTS with file:line evidence, plus the inferences and assumptions those facts support. |
|
blueprint
Package blueprint defines the generated lockfile: a pure, deterministic function of profile + config + manifest + catalog (DESIGN §9).
|
Package blueprint defines the generated lockfile: a pure, deterministic function of profile + config + manifest + catalog (DESIGN §9). |
|
catalog
Package catalog loads the module catalog index: the golden path, pinned.
|
Package catalog loads the module catalog index: the golden path, pinned. |
|
config
Package config loads and validates neckbeard.yaml, the user-owned configuration.
|
Package config loads and validates neckbeard.yaml, the user-owned configuration. |
|
doctor
Package doctor checks local prerequisites without contacting cloud accounts.
|
Package doctor checks local prerequisites without contacting cloud accounts. |
|
estimate
Package estimate implements the FinOps pipeline (DESIGN §13): the blueprint is rendered to a scratch directory (never the user's repo) and priced with Infracost's HCL parsing — no cloud credentials involved.
|
Package estimate implements the FinOps pipeline (DESIGN §13): the blueprint is rendered to a scratch directory (never the user's repo) and priced with Infracost's HCL parsing — no cloud credentials involved. |
|
ownership
Package ownership implements the file-ownership zones and regeneration contract (DESIGN §6.1–6.2): every generated file is tracked in .neckbeard/manifest.json with its content hash; regeneration replaces a file only when it is unmodified.
|
Package ownership implements the file-ownership zones and regeneration contract (DESIGN §6.1–6.2): every generated file is tracked in .neckbeard/manifest.json with its content hash; regeneration replaces a file only when it is unmodified. |
|
pipeline
Package pipeline holds the shared delivery model (DESIGN §11.1): one small internal description of the behaviors we generate — test, build/scan/push, per-env infra plan/apply with OIDC and environment binding — rendered to GitHub Actions and GitLab CI by deterministic renderers so the two can never drift.
|
Package pipeline holds the shared delivery model (DESIGN §11.1): one small internal description of the behaviors we generate — test, build/scan/push, per-env infra plan/apply with OIDC and environment binding — rendered to GitHub Actions and GitLab CI by deterministic renderers so the two can never drift. |
|
planner
Package planner resolves app profile + configuration + tier presets against the pinned catalog into a deterministic blueprint.
|
Package planner resolves app profile + configuration + tier presets against the pinned catalog into a deterministic blueprint. |
|
presets
Package presets embeds the tier presets: explicit dimensions and the module inputs / usage numbers each tier expands to (DESIGN §4.2).
|
Package presets embeds the tier presets: explicit dimensions and the module inputs / usage numbers each tier expands to (DESIGN §4.2). |
|
profile
Package profile loads app-profile.yaml — the agent-written, user-reviewed application profile.
|
Package profile loads app-profile.yaml — the agent-written, user-reviewed application profile. |
|
release
Package release prepares deployment foundations and deploys immutable images using native cloud CLIs.
|
Package release prepares deployment foundations and deploys immutable images using native cloud CLIs. |
|
render
Package render turns a blueprint into a write-set: a pure function of the blueprint, byte-identical on every call (DESIGN §9).
|
Package render turns a blueprint into a write-set: a pure function of the blueprint, byte-identical on every call (DESIGN §9). |
|
skillinstall
Package skillinstall places the neckbeard skill where coding agents discover it.
|
Package skillinstall places the neckbeard skill where coding agents discover it. |
|
validate
Package validate implements the V0 static level of the validation ladder (DESIGN §12.1).
|
Package validate implements the V0 static level of the validation ladder (DESIGN §12.1). |
|
version
Package version pins the planner/CLI version recorded in every blueprint.
|
Package version pins the planner/CLI version recorded in every blueprint. |
|
Package pluginassets embeds the agent-facing assets so the CLI binary is the single distribution channel: `neckbeard skill install` places the SKILL.md — the cross-agent open standard adopted by Codex CLI, Cursor, Gemini CLI, and others — where the user's tool discovers it.
|
Package pluginassets embeds the agent-facing assets so the CLI binary is the single distribution channel: `neckbeard skill install` places the SKILL.md — the cross-agent open standard adopted by Codex CLI, Cursor, Gemini CLI, and others — where the user's tool discovers it. |
|
Package schemas embeds the language-neutral JSON Schema contracts and validates YAML documents against them.
|
Package schemas embeds the language-neutral JSON Schema contracts and validates YAML documents against them. |